From 5f72cef3229318a074397c6414eaffc6072bf351 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Fri, 20 Mar 2026 22:17:14 +0100 Subject: [PATCH 1/7] Archived change docs alignment --- .../.openspec.yaml | 0 .../TDD_EVIDENCE.md | 0 .../2026-03-20-docs-cli-command-alignment}/design.md | 0 .../proposal.md | 0 .../specs/modules-docs-publishing/spec.md | 0 .../2026-03-20-docs-cli-command-alignment}/tasks.md | 0 openspec/specs/modules-docs-publishing/spec.md | 11 ++++++----- 7 files changed, 6 insertions(+), 5 deletions(-) rename openspec/changes/{docs-cli-command-alignment => archive/2026-03-20-docs-cli-command-alignment}/.openspec.yaml (100%) rename openspec/changes/{docs-cli-command-alignment => archive/2026-03-20-docs-cli-command-alignment}/TDD_EVIDENCE.md (100%) rename openspec/changes/{docs-cli-command-alignment => archive/2026-03-20-docs-cli-command-alignment}/design.md (100%) rename openspec/changes/{docs-cli-command-alignment => archive/2026-03-20-docs-cli-command-alignment}/proposal.md (100%) rename openspec/changes/{docs-cli-command-alignment => archive/2026-03-20-docs-cli-command-alignment}/specs/modules-docs-publishing/spec.md (100%) rename openspec/changes/{docs-cli-command-alignment => archive/2026-03-20-docs-cli-command-alignment}/tasks.md (100%) diff --git a/openspec/changes/docs-cli-command-alignment/.openspec.yaml b/openspec/changes/archive/2026-03-20-docs-cli-command-alignment/.openspec.yaml similarity index 100% rename from openspec/changes/docs-cli-command-alignment/.openspec.yaml rename to openspec/changes/archive/2026-03-20-docs-cli-command-alignment/.openspec.yaml diff --git a/openspec/changes/docs-cli-command-alignment/TDD_EVIDENCE.md b/openspec/changes/archive/2026-03-20-docs-cli-command-alignment/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/docs-cli-command-alignment/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-03-20-docs-cli-command-alignment/TDD_EVIDENCE.md diff --git a/openspec/changes/docs-cli-command-alignment/design.md b/openspec/changes/archive/2026-03-20-docs-cli-command-alignment/design.md similarity index 100% rename from openspec/changes/docs-cli-command-alignment/design.md rename to openspec/changes/archive/2026-03-20-docs-cli-command-alignment/design.md diff --git a/openspec/changes/docs-cli-command-alignment/proposal.md b/openspec/changes/archive/2026-03-20-docs-cli-command-alignment/proposal.md similarity index 100% rename from openspec/changes/docs-cli-command-alignment/proposal.md rename to openspec/changes/archive/2026-03-20-docs-cli-command-alignment/proposal.md diff --git a/openspec/changes/docs-cli-command-alignment/specs/modules-docs-publishing/spec.md b/openspec/changes/archive/2026-03-20-docs-cli-command-alignment/specs/modules-docs-publishing/spec.md similarity index 100% rename from openspec/changes/docs-cli-command-alignment/specs/modules-docs-publishing/spec.md rename to openspec/changes/archive/2026-03-20-docs-cli-command-alignment/specs/modules-docs-publishing/spec.md diff --git a/openspec/changes/docs-cli-command-alignment/tasks.md b/openspec/changes/archive/2026-03-20-docs-cli-command-alignment/tasks.md similarity index 100% rename from openspec/changes/docs-cli-command-alignment/tasks.md rename to openspec/changes/archive/2026-03-20-docs-cli-command-alignment/tasks.md diff --git a/openspec/specs/modules-docs-publishing/spec.md b/openspec/specs/modules-docs-publishing/spec.md index 7f2236b..0dcf662 100644 --- a/openspec/specs/modules-docs-publishing/spec.md +++ b/openspec/specs/modules-docs-publishing/spec.md @@ -5,13 +5,14 @@ TBD - created by archiving change docs-01-modules-docs-canonical-site. Update Pu ## Requirements ### Requirement: Modules docs site is the canonical home for official bundle documentation -The modules documentation site SHALL present itself as the canonical published home for official bundle and module-specific deep documentation. +The modules documentation site SHALL present itself as the canonical published home for official bundle and module-specific deep documentation, and its command examples SHALL match the currently mounted CLI surface shipped with the official modules. -#### Scenario: Reader opens modules landing page +#### Scenario: Reader follows a command example from the modules docs -- **WHEN** a reader opens the modules docs landing page -- **THEN** the page states that official bundle and module-specific deep guidance is owned by `specfact-cli-modules` -- **AND** the page does not describe the GitHub Pages project-path URL as the long-term canonical public identity. +- **WHEN** a reader copies a command example from the modules docs reference or installation pages +- **THEN** the example uses a command path that is currently mounted in `specfact --help` +- **AND** the example does not rely on removed top-level shims such as flat `sync`, `repro`, `validate`, or `enforce` command groups when the mounted path is nested under another group +- **AND** official bundle install examples use the current published module ids from `specfact-cli-modules` ### Requirement: Modules docs expose shared cross-site navigation From 090c36d187c2c7fe698007c81e50d87cc0e339a8 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Sun, 22 Mar 2026 23:56:31 +0100 Subject: [PATCH 2/7] docs: add modules clean-code openspec change --- openspec/CHANGE_ORDER.md | 37 ++++++++++++++++ .../.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 28 ++++++++++++ .../design.md | 34 +++++++++++++++ .../proposal.md | 43 +++++++++++++++++++ .../specs/clean-code-analysis/spec.md | 16 +++++++ .../specs/clean-code-policy-pack/spec.md | 16 +++++++ .../specs/house-rules-skill/spec.md | 16 +++++++ .../specs/radon-runner/spec.md | 16 +++++++ .../specs/review-cli-contracts/spec.md | 16 +++++++ .../specs/review-run-command/spec.md | 16 +++++++ .../tasks.md | 30 +++++++++++++ 12 files changed, 270 insertions(+) create mode 100644 openspec/CHANGE_ORDER.md create mode 100644 openspec/changes/clean-code-02-expanded-review-module/.openspec.yaml create mode 100644 openspec/changes/clean-code-02-expanded-review-module/CHANGE_VALIDATION.md create mode 100644 openspec/changes/clean-code-02-expanded-review-module/design.md create mode 100644 openspec/changes/clean-code-02-expanded-review-module/proposal.md create mode 100644 openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-analysis/spec.md create mode 100644 openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-policy-pack/spec.md create mode 100644 openspec/changes/clean-code-02-expanded-review-module/specs/house-rules-skill/spec.md create mode 100644 openspec/changes/clean-code-02-expanded-review-module/specs/radon-runner/spec.md create mode 100644 openspec/changes/clean-code-02-expanded-review-module/specs/review-cli-contracts/spec.md create mode 100644 openspec/changes/clean-code-02-expanded-review-module/specs/review-run-command/spec.md create mode 100644 openspec/changes/clean-code-02-expanded-review-module/tasks.md diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md new file mode 100644 index 0000000..82e665d --- /dev/null +++ b/openspec/CHANGE_ORDER.md @@ -0,0 +1,37 @@ +# OpenSpec change order by module and dependency + +## Implemented (archived) + +| Change | Status / Date | +|--------|---------------| +| ✅ backlog-02-migrate-core-commands | archived 2026-03-10 | +| ✅ backlog-bundle-local-source-alignment | archived 2026-03-10 | +| ✅ bugfix-backlog-html-export-validation | archived 2026-03-10 | +| ✅ modules-pre-commit-quality-parity | archived 2026-03-10 | +| ✅ registry-republish-outdated-bundles | archived 2026-03-10 | +| ✅ fix-issue-49-ado-provider-field-type-coercion | archived 2026-03-11 | +| ✅ code-review-02-ruff-radon-runners | archived 2026-03-17 | +| ✅ code-review-04-contract-test-runners | archived 2026-03-17 | +| ✅ code-review-07-house-rules-skill | archived 2026-03-17 | +| ✅ code-review-08-review-run-integration | archived 2026-03-17 | +| ✅ code-review-10-review-scope-modes | archived 2026-03-17 | +| ✅ docs-01-modules-docs-canonical-site | archived 2026-03-17 | +| ✅ fix-backlog-add-ado-custom-field-payload | archived 2026-03-17 | +| ✅ fix-backlog-add-work-item-type-mapping | archived 2026-03-17 | +| ✅ fix-backlog-provider-required-field-mappings | archived 2026-03-17 | +| ✅ review-run-dogfood-followup | archived 2026-03-17 | +| ✅ docs-cli-command-alignment | archived 2026-03-20 | + +## Plan-derived addendum (2026-03-22 clean code enforcement plan) + +- `clean-code-02-expanded-review-module` is the next modules-repo change. +- It expands the code-review bundle with clean-code finding categories, new analysis runners, the clean-code policy-pack payload, and the house-rules skill update consumed by specfact-cli. +- It is sequenced after the archived code-review runner and review-run changes and before specfact-cli change `clean-code-01-principle-gates`. + +## Pending + +### Code review bundle expansion + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| clean-code | 02 | clean-code-02-expanded-review-module | [#94](https://github.com/nold-ai/specfact-cli-modules/issues/94) | specfact-cli/code-review-zero-findings (#423); code-review-02 ✅; code-review-04 ✅; code-review-07 ✅; code-review-08 ✅; code-review-10 ✅ | diff --git a/openspec/changes/clean-code-02-expanded-review-module/.openspec.yaml b/openspec/changes/clean-code-02-expanded-review-module/.openspec.yaml new file mode 100644 index 0000000..caac517 --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-22 diff --git a/openspec/changes/clean-code-02-expanded-review-module/CHANGE_VALIDATION.md b/openspec/changes/clean-code-02-expanded-review-module/CHANGE_VALIDATION.md new file mode 100644 index 0000000..78fa312 --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/CHANGE_VALIDATION.md @@ -0,0 +1,28 @@ +# Change Validation: clean-code-02-expanded-review-module + +- **Validated on (UTC):** 2026-03-22T22:28:26+00:00 +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate clean-code-02-expanded-review-module --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** `clean-code-analysis`, `clean-code-policy-pack`, `house-rules-skill` +- **Modified capabilities:** `radon-runner`, `review-run-command`, `review-cli-contracts` +- **Declared dependencies:** archived modules-repo code-review runner changes; upstream specfact-cli dogfood baseline `code-review-zero-findings` + +## Breaking-Change Analysis (Dry-Run) + +- The proposal extends the review finding schema and runner inventory but keeps one governed report model. +- The main compatibility concern is category-schema expansion, which is accounted for by the planned bundle version bump. + +## Dependency and Integration Review + +- The change aligns with the archived runner sequence and with the downstream specfact-cli clean-code consumer change. +- No additional modules-repo change was required to express the pack payload or skill ownership. + +## Validation Outcome + +- Required artifacts are present and parseable. +- Strict OpenSpec validation passed. +- Change is ready for GitHub sync and later implementation-phase intake. diff --git a/openspec/changes/clean-code-02-expanded-review-module/design.md b/openspec/changes/clean-code-02-expanded-review-module/design.md new file mode 100644 index 0000000..c8a0ead --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/design.md @@ -0,0 +1,34 @@ +# Design: clean-code-02-expanded-review-module + +## Summary + +This change expands the `specfact-code-review` bundle in place rather than creating a second review product. The new functionality falls into four slices: + +1. finding schema expansion and category ownership +2. runner expansion for KISS, SOLID, YAGNI, DRY, and PR checklist analysis +3. policy-pack payload shipping for downstream policy consumers +4. canonical house-rules skill refresh + +## Decisions + +### Schema ownership + +- Extend the existing `ReviewFinding` / `ReviewReport` category set with `naming`, `kiss`, `yagni`, `dry`, and `solid`. +- Keep severity handling generic; policy mode determines whether a finding blocks. + +### Runner design + +- Use semgrep for the lightweight naming and exception-pattern rules. +- Extend `radon_runner.py` with AST-derived LOC, nesting, and parameter metrics. +- Implement dedicated AST tools for solid, yagni, and dry checks so the bundle stays Python-native. +- Keep the PR checklist runner advisory-only and attach it through PR mode rather than normal file-only review runs. + +### Policy-pack payload + +- Ship the clean-code pack with the bundle so `policy-02-packs-and-modes` can consume it without redefining rule IDs. +- Per-rule mode resolution stays in specfact-cli policy code; this repo only owns the pack manifest and rule inventory. + +### Dry-clone detector spike + +- The AST clone detector is the riskiest part of the plan. +- The spec keeps the algorithm bounded to normalized-AST hashing and overlap thresholds rather than promising cross-language or whole-repo semantic clone detection. diff --git a/openspec/changes/clean-code-02-expanded-review-module/proposal.md b/openspec/changes/clean-code-02-expanded-review-module/proposal.md new file mode 100644 index 0000000..c30efba --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/proposal.md @@ -0,0 +1,43 @@ +# Change: Expanded clean-code review module for specfact-cli-modules + +## Why + +The 2026-03-22 clean-code plan requires the review engine to move beyond the initial Ruff, Radon, contract, and review-run plumbing. The `specfact-code-review` bundle now needs first-class clean-code coverage across the 7 principles so specfact-cli and external projects can consume a single governed review module rather than a patchwork of repo-local rules. This change owns that review-engine expansion in `specfact-cli-modules`. + +## What Changes + +- **NEW**: `clean-code-analysis` capability covering the expanded clean-code finding schema, semgrep naming rules, solid/yagni/dry runners, and PR checklist enforcement. +- **MODIFY**: `radon-runner` to emit LOC, nesting-depth, and parameter-count findings under the staged Phase A thresholds from the 2026-03-22 plan. +- **MODIFY**: `review-run-command` to orchestrate the new clean-code runners and expose their results in the governed review report. +- **MODIFY**: `review-cli-contracts` so CLI review scenarios can assert the new clean-code categories and PR-mode behavior. +- **NEW**: `clean-code-policy-pack` capability that ships the `specfact/clean-code-principles` policy-pack payload consumed by specfact-cli `policy-02-packs-and-modes`. +- **NEW**: `house-rules-skill` capability update that compresses the 7-principle clean-code charter into the canonical `skills/specfact-code-review/SKILL.md` surface. + +## Capabilities + +### New Capabilities + +- `clean-code-analysis`: The review bundle emits governed findings for naming, kiss, yagni, dry, solid, and PR checklist rules. +- `clean-code-policy-pack`: The review bundle ships the built-in `specfact/clean-code-principles` pack manifest and rule mapping payload. +- `house-rules-skill`: The canonical review skill exposes the 7-principle clean-code charter in a compact form suitable for downstream IDE integrations. + +### Modified Capabilities + +- `radon-runner`: Extended from complexity-only findings to staged KISS metric findings. +- `review-run-command`: Extended to orchestrate the new clean-code analysis runners and PR-mode checklist validation. +- `review-cli-contracts`: Extended to cover clean-code categories and PR-mode review scenarios. + +## Impact + +- **Affected package**: `packages/specfact-code-review/` including finding models, runners, rule payloads, skill distribution, docs, and release metadata. +- **Dependencies**: depends on archived modules-repo runner work (`code-review-02`, `code-review-04`, `code-review-07`, `code-review-08`, `code-review-10`) and on the specfact-cli prerequisite `code-review-zero-findings` remaining the dogfood baseline. +- **Versioning**: bump `specfact-code-review` from `0.44.0` to `0.45.0` because new clean-code categories extend the review schema. +- **Documentation**: update `docs/modules/code-review.md`, the skill documentation, and any bundle release notes describing review categories and policy-pack payloads. +- **Rollback**: if a runner proves too noisy, the pack can keep the rule advisory by default while the runner remains shipped; do not fork the finding schema per consumer. + +## Source Tracking + +- **GitHub Issue**: #94 +- **Issue URL**: https://github.com/nold-ai/specfact-cli-modules/issues/94 +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: open diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-analysis/spec.md b/openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-analysis/spec.md new file mode 100644 index 0000000..2a9e539 --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-analysis/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Clean-Code Analysis Runners +The review bundle SHALL emit governed findings for the clean-code categories required by the 2026-03-22 plan. + +#### Scenario: Naming and exception-pattern rules emit governed findings +- **GIVEN** a reviewed Python file contains a public symbol with a banned generic name or a swallowed exception pattern +- **WHEN** the clean-code analysis runs +- **THEN** the review report includes findings in the appropriate clean-code category +- **AND** the finding payload keeps rule ID, severity, category, and file location stable + +#### Scenario: AST-based clean-code runners stay repo-local and Python-native +- **GIVEN** solid, yagni, and dry checks are enabled +- **WHEN** the bundle analyzes Python source files +- **THEN** the checks run without introducing a Node.js dependency +- **AND** each finding is attributed to `solid`, `yagni`, or `dry` respectively diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-policy-pack/spec.md b/openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-policy-pack/spec.md new file mode 100644 index 0000000..4fb2ee2 --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-policy-pack/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Clean-Code Policy-Pack Payload +The bundle SHALL ship the `specfact/clean-code-principles` policy-pack payload for downstream policy consumers. + +#### Scenario: Built-in pack manifest exposes the clean-code rules +- **GIVEN** the bundle release artifacts are built +- **WHEN** the clean-code pack manifest is inspected +- **THEN** it lists the clean-code rule identifiers required by the 2026-03-22 plan +- **AND** the pack can be installed without a repo-local copy of the rule inventory + +#### Scenario: Pack payload stays compatible with per-rule mode overrides +- **GIVEN** a downstream consumer overrides one clean-code rule mode +- **WHEN** the pack manifest is resolved through policy code +- **THEN** the override targets the manifest rule IDs directly +- **AND** the bundle does not invent a second clean-code-specific severity schema diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/house-rules-skill/spec.md b/openspec/changes/clean-code-02-expanded-review-module/specs/house-rules-skill/spec.md new file mode 100644 index 0000000..044a5f6 --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/specs/house-rules-skill/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: House-rules skill exposes the compact clean-code charter +The canonical `skills/specfact-code-review/SKILL.md` surface SHALL include the 7-principle clean-code charter in a compact format suitable for downstream IDE integrations. + +#### Scenario: Skill refresh keeps the charter compact +- **GIVEN** the canonical review skill is rendered or updated +- **WHEN** the clean-code charter is included +- **THEN** the skill keeps the charter within a compact house-rules format +- **AND** existing non-overlapping guidance such as TDD-first and contract discipline remains present + +#### Scenario: Downstream IDE aliases can reference the skill without duplicating it +- **GIVEN** another repository such as specfact-cli generates lightweight IDE instruction aliases +- **WHEN** those aliases reference clean-code guidance +- **THEN** the canonical review skill remains the source of truth +- **AND** downstream aliases only need a short reference to the skill diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/radon-runner/spec.md b/openspec/changes/clean-code-02-expanded-review-module/specs/radon-runner/spec.md new file mode 100644 index 0000000..4534db1 --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/specs/radon-runner/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Radon runner reports staged KISS metrics +The bundle SHALL extend the Radon-backed runner with LOC, nesting-depth, and parameter-count findings while preserving complexity findings. + +#### Scenario: Phase A LOC thresholds produce findings +- **GIVEN** a function exceeds the Phase A LOC threshold +- **WHEN** the radon-backed clean-code runner analyzes the file +- **THEN** it emits a `kiss` finding using the staged `>80` / `>120` thresholds +- **AND** existing complexity findings still use the current complexity mapping + +#### Scenario: Nesting and parameter findings use the same governed report path +- **GIVEN** a function exceeds nesting-depth or parameter-count limits +- **WHEN** the runner analyzes the file +- **THEN** the resulting findings are emitted through the existing `ReviewFinding` model +- **AND** downstream scoring and policy consumers do not require a second report format diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/review-cli-contracts/spec.md b/openspec/changes/clean-code-02-expanded-review-module/specs/review-cli-contracts/spec.md new file mode 100644 index 0000000..89fed47 --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/specs/review-cli-contracts/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Review CLI contracts cover clean-code output categories +The modules repository SHALL keep CLI review scenarios aligned with the expanded clean-code report surface. + +#### Scenario: Review-run scenarios cover clean-code categories +- **GIVEN** `tests/cli-contracts/specfact-code-review-run.scenarios.yaml` +- **WHEN** it is validated after this change +- **THEN** it includes at least one scenario that asserts clean-code categories in the governed review output +- **AND** it continues covering success, scope selection, and error paths + +#### Scenario: PR-mode scenarios cover advisory checklist findings +- **GIVEN** review CLI scenarios include PR-mode execution +- **WHEN** the scenario output is validated +- **THEN** advisory checklist findings are represented without changing the base report schema +- **AND** unknown clean-code category names are rejected by the scenario contract layer diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/review-run-command/spec.md b/openspec/changes/clean-code-02-expanded-review-module/specs/review-run-command/spec.md new file mode 100644 index 0000000..6e34686 --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/specs/review-run-command/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Review run command orchestrates clean-code analysis +The bundle SHALL run the expanded clean-code analysis set as part of the governed review workflow. + +#### Scenario: Review run includes clean-code categories in normal output +- **GIVEN** `specfact code review run --json ` executes with clean-code analysis enabled +- **WHEN** the run completes +- **THEN** the JSON report may contain findings in `naming`, `kiss`, `yagni`, `dry`, and `solid` +- **AND** the command keeps the same report envelope used by earlier runner changes + +#### Scenario: PR mode runs checklist enforcement as advisory analysis +- **GIVEN** review run executes in PR mode +- **WHEN** checklist enforcement finds missing clean-code reasoning in the proposal or PR context +- **THEN** the report includes an advisory checklist finding +- **AND** the checklist finding does not create a new command surface diff --git a/openspec/changes/clean-code-02-expanded-review-module/tasks.md b/openspec/changes/clean-code-02-expanded-review-module/tasks.md new file mode 100644 index 0000000..f2d2c33 --- /dev/null +++ b/openspec/changes/clean-code-02-expanded-review-module/tasks.md @@ -0,0 +1,30 @@ +# Tasks: clean-code-02-expanded-review-module + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/clean-code-02-expanded-review-module` from `dev` before implementation work. +- [ ] 1.2 Confirm the archived runner and review-run changes are available locally and note the cross-repo dependency on specfact-cli `code-review-zero-findings`. +- [ ] 1.3 Reconfirm scope against the 2026-03-22 clean-code implementation plan and `openspec/CHANGE_ORDER.md`. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize spec deltas for finding schema expansion, runner behavior, policy-pack payload, and house-rules skill output. +- [ ] 2.2 Add or update tests derived from those scenarios before touching implementation. +- [ ] 2.3 Run targeted tests expecting failure and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Extend the review finding schema and runner orchestration for the new clean-code categories. +- [ ] 3.2 Implement or update the semgrep, radon, solid, yagni, dry, and checklist paths required by the new scenarios. +- [ ] 3.3 Ship the `specfact/clean-code-principles` policy-pack payload and refresh `skills/specfact-code-review/SKILL.md` with the compact charter. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run targeted tests, quality gates, and review fixtures until all changed scenarios pass. +- [ ] 4.2 Update bundle docs, changelog, and release metadata for the new categories and pack payload. +- [ ] 4.3 Run `openspec validate clean-code-02-expanded-review-module --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` dependency notes if sequencing changes again. +- [ ] 5.2 Open a PR from `feature/clean-code-02-expanded-review-module` to `dev` with spec/test/code/docs evidence. From 5dcf98f64888645d8baf58b2733c105a61925b75 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Tue, 24 Mar 2026 00:04:22 +0100 Subject: [PATCH 3/7] Add docs refactoring changes --- openspec/CHANGE_ORDER.md | 19 +++++ .../CHANGE_VALIDATION.md | 72 +++++++++++++++++++ .../proposal.md | 42 +++++++++++ .../specs/modules-bundle-nav/spec.md | 24 +++++++ .../specs/modules-progressive-tiers/spec.md | 23 ++++++ .../tasks.md | 44 ++++++++++++ .../CHANGE_VALIDATION.md | 65 +++++++++++++++++ .../docs-08-bundle-overview-pages/proposal.md | 31 ++++++++ .../specs/bundle-overview-pages/spec.md | 24 +++++++ .../docs-08-bundle-overview-pages/tasks.md | 19 +++++ .../CHANGE_VALIDATION.md | 66 +++++++++++++++++ .../docs-09-missing-command-docs/proposal.md | 33 +++++++++ .../specs/missing-command-docs/spec.md | 30 ++++++++ .../docs-09-missing-command-docs/tasks.md | 33 +++++++++ .../CHANGE_VALIDATION.md | 66 +++++++++++++++++ .../proposal.md | 41 +++++++++++ .../specs/cross-module-workflow-docs/spec.md | 26 +++++++ .../docs-10-workflow-consolidation/tasks.md | 27 +++++++ .../CHANGE_VALIDATION.md | 65 +++++++++++++++++ .../docs-11-team-enterprise-tier/proposal.md | 33 +++++++++ .../specs/team-enterprise-docs/spec.md | 23 ++++++ .../docs-11-team-enterprise-tier/tasks.md | 20 ++++++ .../CHANGE_VALIDATION.md | 67 +++++++++++++++++ .../docs-12-docs-validation-ci/proposal.md | 32 +++++++++ .../modules-docs-command-validation/spec.md | 19 +++++ .../docs-12-docs-validation-ci/tasks.md | 22 ++++++ 26 files changed, 966 insertions(+) create mode 100644 openspec/changes/docs-06-modules-site-ia-restructure/CHANGE_VALIDATION.md create mode 100644 openspec/changes/docs-06-modules-site-ia-restructure/proposal.md create mode 100644 openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-bundle-nav/spec.md create mode 100644 openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-progressive-tiers/spec.md create mode 100644 openspec/changes/docs-06-modules-site-ia-restructure/tasks.md create mode 100644 openspec/changes/docs-08-bundle-overview-pages/CHANGE_VALIDATION.md create mode 100644 openspec/changes/docs-08-bundle-overview-pages/proposal.md create mode 100644 openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md create mode 100644 openspec/changes/docs-08-bundle-overview-pages/tasks.md create mode 100644 openspec/changes/docs-09-missing-command-docs/CHANGE_VALIDATION.md create mode 100644 openspec/changes/docs-09-missing-command-docs/proposal.md create mode 100644 openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md create mode 100644 openspec/changes/docs-09-missing-command-docs/tasks.md create mode 100644 openspec/changes/docs-10-workflow-consolidation/CHANGE_VALIDATION.md create mode 100644 openspec/changes/docs-10-workflow-consolidation/proposal.md create mode 100644 openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md create mode 100644 openspec/changes/docs-10-workflow-consolidation/tasks.md create mode 100644 openspec/changes/docs-11-team-enterprise-tier/CHANGE_VALIDATION.md create mode 100644 openspec/changes/docs-11-team-enterprise-tier/proposal.md create mode 100644 openspec/changes/docs-11-team-enterprise-tier/specs/team-enterprise-docs/spec.md create mode 100644 openspec/changes/docs-11-team-enterprise-tier/tasks.md create mode 100644 openspec/changes/docs-12-docs-validation-ci/CHANGE_VALIDATION.md create mode 100644 openspec/changes/docs-12-docs-validation-ci/proposal.md create mode 100644 openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md create mode 100644 openspec/changes/docs-12-docs-validation-ci/tasks.md diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index 82e665d..bcf722b 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -35,3 +35,22 @@ | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| | clean-code | 02 | clean-code-02-expanded-review-module | [#94](https://github.com/nold-ai/specfact-cli-modules/issues/94) | specfact-cli/code-review-zero-findings (#423); code-review-02 ✅; code-review-04 ✅; code-review-07 ✅; code-review-08 ✅; code-review-10 ✅ | + +## Plan-derived addendum (2026-03-23 docs refactoring beginner-to-enterprise plan) + +The 2026-03-23 docs refactoring plan adds 6 changes to the modules repo to restructure the docs site into a progressive beginner-to-enterprise hierarchy with per-bundle organization, workflow consolidation, and team/enterprise tiers. + +All changes sync to GitHub as issues with labels: `documentation`, `change-proposal`, `openspec`. No parent Feature required (modules repo does not use the Feature/Epic hierarchy). + +Cross-repo dependency: `docs-06-modules-site-ia-restructure` is a prerequisite for specfact-cli/`docs-07-core-handoff-conversion` (core handoff pages redirect to modules targets). + +### Documentation restructure + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| docs | 06 | docs-06-modules-site-ia-restructure | [#95](https://github.com/nold-ai/specfact-cli-modules/issues/95) | docs-01 ✅; docs-cli-command-alignment ✅ | +| docs | 08 | docs-08-bundle-overview-pages | [#96](https://github.com/nold-ai/specfact-cli-modules/issues/96) | docs-06-modules-site-ia-restructure | +| docs | 09 | docs-09-missing-command-docs | [#97](https://github.com/nold-ai/specfact-cli-modules/issues/97) | docs-06-modules-site-ia-restructure | +| docs | 10 | docs-10-workflow-consolidation | [#98](https://github.com/nold-ai/specfact-cli-modules/issues/98) | docs-06-modules-site-ia-restructure | +| docs | 11 | docs-11-team-enterprise-tier | [#99](https://github.com/nold-ai/specfact-cli-modules/issues/99) | docs-06-modules-site-ia-restructure | +| docs | 12 | docs-12-docs-validation-ci | [#100](https://github.com/nold-ai/specfact-cli-modules/issues/100) | docs-06 through docs-10; specfact-cli/docs-12-docs-validation-ci | diff --git a/openspec/changes/docs-06-modules-site-ia-restructure/CHANGE_VALIDATION.md b/openspec/changes/docs-06-modules-site-ia-restructure/CHANGE_VALIDATION.md new file mode 100644 index 0000000..e894dac --- /dev/null +++ b/openspec/changes/docs-06-modules-site-ia-restructure/CHANGE_VALIDATION.md @@ -0,0 +1,72 @@ +# Change Validation Report: docs-06-modules-site-ia-restructure + +**Validation Date**: 2026-03-23 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Dry-run simulation (documentation-only change, no code interfaces affected) + +## Executive Summary + +- Breaking Changes: 0 detected / 0 resolved +- Dependent Files: 0 code files affected (docs-only) +- Impact Level: Low (documentation restructure, no code changes) +- Validation Result: Pass +- User Decision: N/A (no breaking changes) + +## Breaking Changes Detected + +None. This is a documentation-only change that restructures the modules Jekyll docs site from flat guides/ to bundle-organized hierarchy. No Python code, interfaces, contracts, or APIs are modified. + +## Dependencies Affected + +### Cross-Change Dependencies + +- **Blocked by**: docs-01 (archived), docs-cli-command-alignment (archived) - both resolved +- **Blocks**: docs-07 (core handoff conversion needs target pages), docs-08, docs-09, docs-10, docs-11, docs-12 +- This is a critical-path change: 5 downstream changes depend on the directory structure created here + +### Critical Updates Required + +None. + +### Recommended Updates + +- Coordinate with docs-05 (core IA restructure) for consistent cross-site navigation +- After restructure, verify that all `jekyll-redirect-from` entries cover the 15+ moved files + +## Impact Assessment + +- **Code Impact**: None (documentation only) +- **Test Impact**: None +- **Documentation Impact**: High - complete restructure of modules docs site from 6 flat sections to 7 progressive sections with per-bundle organization +- **Release Impact**: N/A (docs-only, modules repo) + +## Format Validation + +- **proposal.md Format**: Pass + - Title format: Correct (`# Change: Restructure Modules Docs Site Information Architecture`) + - Required sections: All present (Why, What Changes, Capabilities, Impact) + - "What Changes" format: Correct (bullet list) + - "Capabilities" section: Present (modules-bundle-nav, modules-progressive-tiers, documentation-alignment) + - "Impact" format: Correct + - Source Tracking section: Present (#95) +- **tasks.md Format**: Pass + - Section headers: Correct (hierarchical `## 1.`, `## 2.`, etc.) + - Task format: Correct (`- [ ] 1.1 [Description]`) + - Note: modules repo config.yaml has no custom task rules +- **specs Format**: Pass + - Given/When/Then format: Verified (modules-bundle-nav/spec.md, modules-progressive-tiers/spec.md) +- **design.md Format**: N/A +- **Format Issues Found**: 0 +- **Config.yaml Compliance**: Pass (modules repo has minimal config) + +## OpenSpec Validation + +- **Status**: Pass (manual validation) +- **Issues Found**: 0 +- **Issues Fixed**: 0 +- **Re-validated**: No + +## Validation Artifacts + +- No temporary workspace needed (documentation-only) +- Critical-path dependency chain documented in CHANGE_ORDER.md diff --git a/openspec/changes/docs-06-modules-site-ia-restructure/proposal.md b/openspec/changes/docs-06-modules-site-ia-restructure/proposal.md new file mode 100644 index 0000000..be8ffca --- /dev/null +++ b/openspec/changes/docs-06-modules-site-ia-restructure/proposal.md @@ -0,0 +1,42 @@ +# Change: Restructure Modules Docs Site Information Architecture + +## Why + +The modules docs site at modules.specfact.io has a flat structure with 6 sidebar sections (Getting Started, Official Modules, Bundle Workflows, Publishing & Signing, Reference) where 50+ guide files sit in a single guides/ folder. Bundle-specific docs are mixed with authoring guides, workflow patterns, and integration docs. There is no per-bundle organization, no progressive learning path, and no team/enterprise tier. Users of specific bundles (e.g., backlog or govern) cannot quickly find all relevant docs for their bundle. + +## What Changes + +- Restructure the modules docs sidebar from 6 flat sections to 7 focused sections: Getting Started, Bundles, Workflows, Integrations, Team & Enterprise, Authoring, Reference +- Create a new `bundles/` directory with per-bundle subdirectories: backlog/, project/, codebase/, spec/, govern/, code-review/ +- Create new directories: `workflows/`, `integrations/`, `team-and-enterprise/`, `authoring/` +- Move existing guide files from flat `guides/` into their correct bundle, workflow, integration, or authoring directory +- Update `docs/_layouts/default.html` sidebar to the new 7-section structure with collapsible bundle groups +- Rewrite `docs/index.md` as a bundle-focused landing page +- Differentiate getting-started from the core site version +- Add `jekyll-redirect-from` entries for all moved URLs + +## Capabilities + +### New Capabilities + +- `modules-bundle-nav`: per-bundle collapsible sidebar navigation grouping all docs for each official bundle +- `modules-progressive-tiers`: docs organized by audience tier (beginner tutorials, bundle reference, workflows, team/enterprise, authoring) + +### Modified Capabilities + +- `documentation-alignment`: modules site becomes the canonical home for all bundle-specific deep guidance with clear ownership + +## Impact + +- New directories: `docs/bundles/{backlog,project,codebase,spec,govern,code-review}/`, `docs/workflows/`, `docs/integrations/`, `docs/team-and-enterprise/`, `docs/authoring/` +- Moved files: 15+ guide files from `guides/` to their correct new locations (see migration map in plan) +- Modified: `docs/_layouts/default.html` (sidebar), `docs/index.md` (landing), `docs/_config.yml` (if needed for redirect plugin) +- User-facing: modules.specfact.io navigation is organized by bundle with clear paths from beginner to advanced + +## Source Tracking + + +- **GitHub Issue**: #95 +- **Issue URL**: https://github.com/nold-ai/specfact-cli-modules/issues/95 +- **Last Synced Status**: synced +- **Sanitized**: true diff --git a/openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-bundle-nav/spec.md b/openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-bundle-nav/spec.md new file mode 100644 index 0000000..35aeb03 --- /dev/null +++ b/openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-bundle-nav/spec.md @@ -0,0 +1,24 @@ +# Capability: modules-bundle-nav + +Modules docs sidebar provides per-bundle collapsible navigation grouping all docs for each official bundle. + +## Scenarios + +### Scenario: Sidebar shows 7 sections in correct order + +Given the modules docs site is built with Jekyll +When a user visits any page on modules.specfact.io +Then the sidebar displays sections: Getting Started, Bundles, Workflows, Integrations, Team & Enterprise, Authoring, Reference + +### Scenario: Bundles section has collapsible per-bundle groups + +Given the sidebar Bundles section +When a user expands a bundle (e.g., Backlog) +Then they see all docs for that bundle: Overview, Ceremonies, Refinement, Delta Commands, etc. +And each bundle group is independently collapsible + +### Scenario: Moved files redirect to new locations + +Given a file was moved from guides/ to bundles/ +When a user visits the old URL +Then they are redirected to the new URL via jekyll-redirect-from diff --git a/openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-progressive-tiers/spec.md b/openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-progressive-tiers/spec.md new file mode 100644 index 0000000..f2bdef9 --- /dev/null +++ b/openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-progressive-tiers/spec.md @@ -0,0 +1,23 @@ +# Capability: modules-progressive-tiers + +Modules docs organized by audience tier from beginner tutorials to advanced authoring. + +## Scenarios + +### Scenario: Beginner finds tutorials in Getting Started + +Given a new user visits modules.specfact.io +When they look at the Getting Started section +Then they find: Module Installation, Your First Project, and practical tutorials + +### Scenario: Team lead finds team setup guides + +Given a team lead wants to set up SpecFact for their team +When they look at the Team & Enterprise section +Then they find: Team Collaboration, Agile/Scrum Setup, Multi-Repo Setups, Enterprise Configuration + +### Scenario: Module author finds publishing guides + +Given a developer wants to create and publish a module +When they look at the Authoring section +Then they find: Module Development, Publishing Modules, Module Signing, Custom Registries diff --git a/openspec/changes/docs-06-modules-site-ia-restructure/tasks.md b/openspec/changes/docs-06-modules-site-ia-restructure/tasks.md new file mode 100644 index 0000000..148f04f --- /dev/null +++ b/openspec/changes/docs-06-modules-site-ia-restructure/tasks.md @@ -0,0 +1,44 @@ +## 1. Change Setup And Spec Deltas + +- [ ] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-06-modules-site-ia-restructure` entry +- [ ] 1.2 Add `modules-bundle-nav` capability spec for per-bundle sidebar navigation +- [ ] 1.3 Add `modules-progressive-tiers` capability spec for audience-tier organization + +## 2. Directory Structure + +- [ ] 2.1 Create `docs/bundles/backlog/`, `docs/bundles/project/`, `docs/bundles/codebase/`, `docs/bundles/spec/`, `docs/bundles/govern/`, `docs/bundles/code-review/` +- [ ] 2.2 Create `docs/workflows/`, `docs/integrations/`, `docs/team-and-enterprise/`, `docs/authoring/` + +## 3. Move Backlog And Project Guides + +- [ ] 3.1 Move `guides/backlog-refinement.md` to `bundles/backlog/refinement.md` +- [ ] 3.2 Move `guides/backlog-delta-commands.md` to `bundles/backlog/delta.md` +- [ ] 3.3 Move `guides/backlog-dependency-analysis.md` to `bundles/backlog/dependency-analysis.md` +- [ ] 3.4 Move `guides/policy-engine-commands.md` to `bundles/backlog/policy-engine.md` +- [ ] 3.5 Move `guides/project-devops-flow.md` to `bundles/project/devops-flow.md` +- [ ] 3.6 Move `guides/import-features.md` to `bundles/project/import-migration.md` +- [ ] 3.7 Move `guides/sidecar-validation.md` to `bundles/codebase/sidecar-validation.md` + +## 4. Move Integration And Authoring Guides + +- [ ] 4.1 Move `guides/devops-adapter-integration.md` to `integrations/devops-adapter-overview.md` +- [ ] 4.2 Move `guides/publishing-modules.md` to `authoring/publishing-modules.md` +- [ ] 4.3 Move `guides/module-development.md` to `authoring/module-development.md` +- [ ] 4.4 Move `guides/adapter-development.md` to `authoring/adapter-development.md` +- [ ] 4.5 Move `guides/module-signing-and-key-rotation.md` to `authoring/module-signing.md` +- [ ] 4.6 Move `guides/creating-custom-bridges.md` to `authoring/creating-custom-bridges.md` +- [ ] 4.7 Move `guides/extending-projectbundle.md` to `authoring/extending-projectbundle.md` +- [ ] 4.8 Move `guides/custom-registries.md` to `authoring/custom-registries.md` + +## 5. Landing Page And Navigation + +- [ ] 5.1 Rewrite `docs/index.md` as bundle-focused landing page +- [ ] 5.2 Update `docs/_layouts/default.html` sidebar to new 7-section nav with collapsible bundle groups +- [ ] 5.3 Differentiate `docs/getting-started/` from core site version +- [ ] 5.4 Add `jekyll-redirect-from` entries for all moved files + +## 6. Verification + +- [ ] 6.1 Run `bundle exec jekyll build` and verify zero warnings +- [ ] 6.2 Verify all sidebar links resolve correctly +- [ ] 6.3 Verify redirect entries preserve old URLs diff --git a/openspec/changes/docs-08-bundle-overview-pages/CHANGE_VALIDATION.md b/openspec/changes/docs-08-bundle-overview-pages/CHANGE_VALIDATION.md new file mode 100644 index 0000000..8ea86b6 --- /dev/null +++ b/openspec/changes/docs-08-bundle-overview-pages/CHANGE_VALIDATION.md @@ -0,0 +1,65 @@ +# Change Validation Report: docs-08-bundle-overview-pages + +**Validation Date**: 2026-03-23 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Dry-run simulation (documentation-only change, no code interfaces affected) + +## Executive Summary + +- Breaking Changes: 0 detected / 0 resolved +- Dependent Files: 0 code files affected (docs-only) +- Impact Level: Low (new documentation pages, no code changes) +- Validation Result: Pass +- User Decision: N/A (no breaking changes) + +## Breaking Changes Detected + +None. This change adds 6 new bundle overview pages. No existing files are modified beyond navigation updates. + +## Dependencies Affected + +### Cross-Change Dependencies + +- **Blocked by**: docs-06-modules-site-ia-restructure (bundles/ directory structure must exist) +- **Blocks**: docs-12-docs-validation-ci (overview pages should be validated by CI) + +### Critical Updates Required + +None. + +### Recommended Updates + +- Command examples in overview pages must be validated against actual `--help` output during implementation + +## Impact Assessment + +- **Code Impact**: None (documentation only) +- **Test Impact**: None +- **Documentation Impact**: Medium - 6 new pages providing bundle entry points +- **Release Impact**: N/A (docs-only) + +## Format Validation + +- **proposal.md Format**: Pass + - Title format: Correct (`# Change: Write Bundle Overview Pages For All 6 Official Bundles`) + - Required sections: All present (Why, What Changes, Capabilities, Impact) + - "Capabilities" section: Present (bundle-overview-pages) + - Source Tracking section: Present (#96) +- **tasks.md Format**: Pass + - Section headers: Correct (hierarchical) + - Task format: Correct +- **specs Format**: Pass + - Given/When/Then format: Verified (bundle-overview-pages/spec.md) +- **Format Issues Found**: 0 +- **Config.yaml Compliance**: Pass + +## OpenSpec Validation + +- **Status**: Pass (manual validation) +- **Issues Found**: 0 +- **Issues Fixed**: 0 +- **Re-validated**: No + +## Validation Artifacts + +- No temporary workspace needed (documentation-only) diff --git a/openspec/changes/docs-08-bundle-overview-pages/proposal.md b/openspec/changes/docs-08-bundle-overview-pages/proposal.md new file mode 100644 index 0000000..899f012 --- /dev/null +++ b/openspec/changes/docs-08-bundle-overview-pages/proposal.md @@ -0,0 +1,31 @@ +# Change: Write Bundle Overview Pages For All 6 Official Bundles + +## Why + +Users of specific bundles cannot quickly find all available commands, understand prerequisites, or see quick examples. Each bundle needs a single landing page that provides a complete at-a-glance view of everything the bundle offers. + +## What Changes + +- Write 6 new bundle overview pages, one per official bundle: backlog, project, codebase, spec, govern, code-review +- Each overview page contains: bundle purpose, prerequisites, full command listing with brief descriptions, quick example for each major command group, and links to deep-dive guides +- All command examples validated against actual `--help` output + +## Capabilities + +### New Capabilities + +- `bundle-overview-pages`: each official bundle has a single overview page listing all commands, prerequisites, and quick examples + +## Impact + +- New files: `docs/bundles/backlog/overview.md`, `docs/bundles/project/overview.md`, `docs/bundles/codebase/overview.md`, `docs/bundles/spec/overview.md`, `docs/bundles/govern/overview.md`, `docs/bundles/code-review/overview.md` +- Depends on: `docs-06-modules-site-ia-restructure` (bundles/ directory structure must exist) +- User-facing: each bundle has a clear entry point for discovering all available commands + +## Source Tracking + + +- **GitHub Issue**: #96 +- **Issue URL**: https://github.com/nold-ai/specfact-cli-modules/issues/96 +- **Last Synced Status**: synced +- **Sanitized**: true diff --git a/openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md b/openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md new file mode 100644 index 0000000..95575a2 --- /dev/null +++ b/openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md @@ -0,0 +1,24 @@ +# Capability: bundle-overview-pages + +Each official bundle has a single overview page listing all commands, prerequisites, and quick examples. + +## Scenarios + +### Scenario: Overview page lists all bundle commands + +Given a bundle overview page (e.g., bundles/backlog/overview.md) +When a user reads the page +Then every registered command and subcommand for that bundle is listed +And each command has a brief description + +### Scenario: Overview page includes quick examples + +Given a bundle overview page +When a user reads the page +Then at least one practical example is shown for each major command group + +### Scenario: Command examples match actual CLI + +Given a command example in an overview page +When compared against the actual `specfact --help` output +Then the command name, arguments, and key options match diff --git a/openspec/changes/docs-08-bundle-overview-pages/tasks.md b/openspec/changes/docs-08-bundle-overview-pages/tasks.md new file mode 100644 index 0000000..c432ebf --- /dev/null +++ b/openspec/changes/docs-08-bundle-overview-pages/tasks.md @@ -0,0 +1,19 @@ +## 1. Change Setup + +- [ ] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-08-bundle-overview-pages` entry +- [ ] 1.2 Add `bundle-overview-pages` capability spec + +## 2. Write Overview Pages + +- [ ] 2.1 Write `bundles/backlog/overview.md`: ceremony, daily, refine, add, analyze-deps, sync, diff, promote, verify-readiness, delta, policy, init-config, map-fields +- [ ] 2.2 Write `bundles/project/overview.md`: link-backlog, health-check, snapshot, regenerate, export-roadmap, version, sync bridge, devops-flow, plan init, import, migrate, add-feature, add-story +- [ ] 2.3 Write `bundles/codebase/overview.md`: import, analyze contracts, drift detect, validate sidecar, repro +- [ ] 2.4 Write `bundles/spec/overview.md`: contract (init/validate/coverage/serve/verify/test), generate, sdd +- [ ] 2.5 Write `bundles/govern/overview.md`: enforce (stage/sdd), patch +- [ ] 2.6 Write `bundles/code-review/overview.md`: run, ledger, rules + +## 3. Verification + +- [ ] 3.1 Validate every command example against `--help` output +- [ ] 3.2 Verify all internal links resolve +- [ ] 3.3 Run `bundle exec jekyll build` with zero warnings diff --git a/openspec/changes/docs-09-missing-command-docs/CHANGE_VALIDATION.md b/openspec/changes/docs-09-missing-command-docs/CHANGE_VALIDATION.md new file mode 100644 index 0000000..2e3f816 --- /dev/null +++ b/openspec/changes/docs-09-missing-command-docs/CHANGE_VALIDATION.md @@ -0,0 +1,66 @@ +# Change Validation Report: docs-09-missing-command-docs + +**Validation Date**: 2026-03-23 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Dry-run simulation (documentation-only change, no code interfaces affected) + +## Executive Summary + +- Breaking Changes: 0 detected / 0 resolved +- Dependent Files: 0 code files affected (docs-only) +- Impact Level: Low (new documentation pages, no code changes) +- Validation Result: Pass +- User Decision: N/A (no breaking changes) + +## Breaking Changes Detected + +None. This change adds 11 new command reference pages for undocumented commands. No existing files are modified beyond navigation updates. + +## Dependencies Affected + +### Cross-Change Dependencies + +- **Blocked by**: docs-06-modules-site-ia-restructure (bundles/ directory structure must exist) +- **Blocks**: docs-12-docs-validation-ci (new command docs should be validated by CI) + +### Critical Updates Required + +None. + +### Recommended Updates + +- All command examples must be validated against actual `--help` output and source code implementations during implementation +- Some commands may not yet be fully implemented (verify during implementation) + +## Impact Assessment + +- **Code Impact**: None (documentation only) +- **Test Impact**: None +- **Documentation Impact**: High - 11 new pages covering previously undocumented commands across spec, govern, code-review, and codebase bundles +- **Release Impact**: N/A (docs-only) + +## Format Validation + +- **proposal.md Format**: Pass + - Title format: Correct (`# Change: Write Missing Command Reference Docs For Spec, Govern, Code-Review, And Codebase`) + - Required sections: All present (Why, What Changes, Capabilities, Impact) + - "Capabilities" section: Present (spec-command-docs, govern-command-docs, code-review-command-docs, codebase-command-docs) + - Source Tracking section: Present (#97) +- **tasks.md Format**: Pass + - Section headers: Correct (hierarchical) + - Task format: Correct +- **specs Format**: Pass + - Given/When/Then format: Verified (missing-command-docs/spec.md) +- **Format Issues Found**: 0 +- **Config.yaml Compliance**: Pass + +## OpenSpec Validation + +- **Status**: Pass (manual validation) +- **Issues Found**: 0 +- **Issues Fixed**: 0 +- **Re-validated**: No + +## Validation Artifacts + +- No temporary workspace needed (documentation-only) diff --git a/openspec/changes/docs-09-missing-command-docs/proposal.md b/openspec/changes/docs-09-missing-command-docs/proposal.md new file mode 100644 index 0000000..8171266 --- /dev/null +++ b/openspec/changes/docs-09-missing-command-docs/proposal.md @@ -0,0 +1,33 @@ +# Change: Write Missing Command Reference Docs For Spec, Govern, Code-Review, And Codebase + +## Why + +The spec, govern, code-review, and codebase bundles have minimal or no documentation for their individual commands. Users cannot find guidance on how to use `specfact spec validate`, `specfact govern enforce`, `specfact code review run`, or `specfact code drift detect` beyond the basic `--help` output. + +## What Changes + +- Write 11 new command reference pages covering all undocumented commands across 4 bundles +- Each page contains: command purpose, prerequisites, full option reference, practical examples, common patterns, and links to related commands +- All examples validated against actual implementations + +## Capabilities + +### New Capabilities + +- `spec-command-docs`: reference docs for spec validate, generate-tests, and mock commands +- `govern-command-docs`: reference docs for govern enforce and patch commands +- `code-review-command-docs`: reference docs for code review run, ledger, and rules commands +- `codebase-command-docs`: reference docs for code analyze, drift, and repro commands + +## Impact + +- New files (11): `bundles/spec/validate.md`, `bundles/spec/generate-tests.md`, `bundles/spec/mock.md`, `bundles/govern/enforce.md`, `bundles/govern/patch.md`, `bundles/code-review/run.md`, `bundles/code-review/ledger.md`, `bundles/code-review/rules.md`, `bundles/codebase/analyze.md`, `bundles/codebase/drift.md`, `bundles/codebase/repro.md` +- Depends on: `docs-06-modules-site-ia-restructure` (bundles/ directory structure must exist) + +## Source Tracking + + +- **GitHub Issue**: #97 +- **Issue URL**: https://github.com/nold-ai/specfact-cli-modules/issues/97 +- **Last Synced Status**: synced +- **Sanitized**: true diff --git a/openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md b/openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md new file mode 100644 index 0000000..d33d5d7 --- /dev/null +++ b/openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md @@ -0,0 +1,30 @@ +# Capability: missing-command-docs + +Reference documentation for all previously undocumented commands across spec, govern, code-review, and codebase bundles. + +## Scenarios + +### Scenario: Each command page documents full option reference + +Given a command reference page (e.g., bundles/govern/enforce.md) +When a user reads the page +Then every option and argument from the command's --help output is documented +And practical examples demonstrate common usage patterns + +### Scenario: Spec bundle has complete documentation + +Given the spec bundle overview links to deep-dive pages +When a user follows links to validate, generate-tests, and mock +Then each page exists and contains command reference, examples, and related commands + +### Scenario: Govern bundle has complete documentation + +Given the govern bundle overview links to deep-dive pages +When a user follows links to enforce and patch +Then each page exists and contains command reference, examples, and related commands + +### Scenario: Code review bundle has complete documentation + +Given the code-review bundle overview links to deep-dive pages +When a user follows links to run, ledger, and rules +Then each page exists and contains command reference, examples, and related commands diff --git a/openspec/changes/docs-09-missing-command-docs/tasks.md b/openspec/changes/docs-09-missing-command-docs/tasks.md new file mode 100644 index 0000000..0bf5da5 --- /dev/null +++ b/openspec/changes/docs-09-missing-command-docs/tasks.md @@ -0,0 +1,33 @@ +## 1. Change Setup + +- [ ] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-09-missing-command-docs` entry +- [ ] 1.2 Add capability specs for spec, govern, code-review, and codebase command docs + +## 2. Spec Bundle Docs + +- [ ] 2.1 Write `bundles/spec/validate.md`: spec validate + backward-compat with examples +- [ ] 2.2 Write `bundles/spec/generate-tests.md`: spec generate-tests workflow +- [ ] 2.3 Write `bundles/spec/mock.md`: spec mock server guide + +## 3. Govern Bundle Docs + +- [ ] 3.1 Write `bundles/govern/enforce.md`: govern enforce stage + govern enforce sdd deep guide +- [ ] 3.2 Write `bundles/govern/patch.md`: govern patch apply guide + +## 4. Code Review Bundle Docs + +- [ ] 4.1 Write `bundles/code-review/run.md`: code review run with --scope, --fix, --interactive options +- [ ] 4.2 Write `bundles/code-review/ledger.md`: ledger update/status/reset +- [ ] 4.3 Write `bundles/code-review/rules.md`: rules show/init/update + +## 5. Codebase Bundle Docs + +- [ ] 5.1 Write `bundles/codebase/analyze.md`: code analyze contracts +- [ ] 5.2 Write `bundles/codebase/drift.md`: code drift detect +- [ ] 5.3 Write `bundles/codebase/repro.md`: code repro + +## 6. Verification + +- [ ] 6.1 Validate all command examples against `--help` output +- [ ] 6.2 Verify all internal links resolve +- [ ] 6.3 Run `bundle exec jekyll build` with zero warnings diff --git a/openspec/changes/docs-10-workflow-consolidation/CHANGE_VALIDATION.md b/openspec/changes/docs-10-workflow-consolidation/CHANGE_VALIDATION.md new file mode 100644 index 0000000..e131e30 --- /dev/null +++ b/openspec/changes/docs-10-workflow-consolidation/CHANGE_VALIDATION.md @@ -0,0 +1,66 @@ +# Change Validation Report: docs-10-workflow-consolidation + +**Validation Date**: 2026-03-23 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Dry-run simulation (documentation-only change, no code interfaces affected) + +## Executive Summary + +- Breaking Changes: 0 detected / 0 resolved +- Dependent Files: 0 code files affected (docs-only) +- Impact Level: Low (documentation consolidation and new pages, no code changes) +- Validation Result: Pass +- User Decision: N/A (no breaking changes) + +## Breaking Changes Detected + +None. This change consolidates overlapping brownfield docs and writes 3 new cross-module workflow pages. No Python code is modified. + +## Dependencies Affected + +### Cross-Change Dependencies + +- **Blocked by**: docs-06-modules-site-ia-restructure (workflows/ directory structure must exist) +- **Blocks**: docs-12-docs-validation-ci (consolidated workflow docs should be validated by CI) + +### Critical Updates Required + +None. + +### Recommended Updates + +- Command chains in workflow docs must be validated against current command surface during implementation +- Old brownfield file paths need redirect entries after merge + +## Impact Assessment + +- **Code Impact**: None (documentation only) +- **Test Impact**: None +- **Documentation Impact**: High - consolidates 7 overlapping brownfield files into 3, adds 3 new cross-module workflow pages +- **Release Impact**: N/A (docs-only) + +## Format Validation + +- **proposal.md Format**: Pass + - Title format: Correct (`# Change: Consolidate Overlapping Workflow Docs And Write Cross-Module Workflows`) + - Required sections: All present (Why, What Changes, Capabilities, Impact) + - "Capabilities" section: Present (cross-module-workflow-docs, daily-devops-routine-docs, documentation-alignment) + - Source Tracking section: Present (#98) +- **tasks.md Format**: Pass + - Section headers: Correct (hierarchical) + - Task format: Correct +- **specs Format**: Pass + - Given/When/Then format: Verified (cross-module-workflow-docs/spec.md) +- **Format Issues Found**: 0 +- **Config.yaml Compliance**: Pass + +## OpenSpec Validation + +- **Status**: Pass (manual validation) +- **Issues Found**: 0 +- **Issues Fixed**: 0 +- **Re-validated**: No + +## Validation Artifacts + +- No temporary workspace needed (documentation-only) diff --git a/openspec/changes/docs-10-workflow-consolidation/proposal.md b/openspec/changes/docs-10-workflow-consolidation/proposal.md new file mode 100644 index 0000000..6cb6808 --- /dev/null +++ b/openspec/changes/docs-10-workflow-consolidation/proposal.md @@ -0,0 +1,41 @@ +# Change: Consolidate Overlapping Workflow Docs And Write Cross-Module Workflows + +## Why + +Multiple brownfield guides overlap (brownfield-engineer, brownfield-journey, brownfield-faq, brownfield-roi, plus 3 example files). The command-chains guide is marked legacy. There are no docs showing how to chain commands across modules (backlog -> code -> spec -> govern) or how to set up a daily DevOps routine with SpecFact. + +## What Changes + +- Merge brownfield-engineer + brownfield-journey into a single `workflows/brownfield-modernization.md` +- Merge brownfield-faq + brownfield-roi into `workflows/brownfield-faq-and-roi.md` +- Merge 3 brownfield example files into `workflows/brownfield-examples.md` +- Write new `workflows/cross-module-chains.md`: end-to-end flow from backlog -> code -> spec -> govern +- Write new `workflows/daily-devops-routine.md`: morning standup -> refine -> commit -> review cycle +- Write new `workflows/ci-cd-pipeline.md`: CI integration patterns with SpecFact commands +- Validate and update existing `command-chains.md` against current command surface + +## Capabilities + +### New Capabilities + +- `cross-module-workflow-docs`: documented end-to-end flows showing how to chain commands across multiple bundles +- `daily-devops-routine-docs`: practical daily routine guide for DevOps teams + +### Modified Capabilities + +- `documentation-alignment`: brownfield docs consolidated from 7 overlapping files to 3 focused guides + +## Impact + +- New files: `workflows/cross-module-chains.md`, `workflows/daily-devops-routine.md`, `workflows/ci-cd-pipeline.md` +- Merged files: brownfield-engineer + brownfield-journey -> brownfield-modernization, brownfield-faq + brownfield-roi -> brownfield-faq-and-roi, 3 examples -> brownfield-examples +- Updated: `workflows/command-chains.md` (validated against current commands) +- Depends on: `docs-06-modules-site-ia-restructure` + +## Source Tracking + + +- **GitHub Issue**: #98 +- **Issue URL**: https://github.com/nold-ai/specfact-cli-modules/issues/98 +- **Last Synced Status**: synced +- **Sanitized**: true diff --git a/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md b/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md new file mode 100644 index 0000000..1a6a3b1 --- /dev/null +++ b/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md @@ -0,0 +1,26 @@ +# Capability: cross-module-workflow-docs + +Documented end-to-end flows showing how to chain commands across multiple bundles. + +## Scenarios + +### Scenario: Cross-module chain covers full lifecycle + +Given the cross-module-chains workflow doc +When a user reads the page +Then it shows a complete flow: backlog ceremony -> code import -> spec validate -> govern enforce +And each step shows the exact command with practical arguments + +### Scenario: Daily routine covers a full work day + +Given the daily-devops-routine workflow doc +When a user reads the page +Then it shows: morning standup, refinement, development, review, and end-of-day patterns +And each step links to the relevant bundle command reference + +### Scenario: CI pipeline doc covers automation patterns + +Given the ci-cd-pipeline workflow doc +When a user reads the page +Then it shows: pre-commit hooks, GitHub Actions integration, and CI/CD stage mapping +And all specfact commands shown are valid and current diff --git a/openspec/changes/docs-10-workflow-consolidation/tasks.md b/openspec/changes/docs-10-workflow-consolidation/tasks.md new file mode 100644 index 0000000..c8a29d9 --- /dev/null +++ b/openspec/changes/docs-10-workflow-consolidation/tasks.md @@ -0,0 +1,27 @@ +## 1. Change Setup + +- [ ] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-10-workflow-consolidation` entry +- [ ] 1.2 Add `cross-module-workflow-docs` and `daily-devops-routine-docs` capability specs + +## 2. Brownfield Consolidation + +- [ ] 2.1 Merge brownfield-engineer + brownfield-journey into `workflows/brownfield-modernization.md` +- [ ] 2.2 Merge brownfield-faq + brownfield-roi into `workflows/brownfield-faq-and-roi.md` +- [ ] 2.3 Merge 3 brownfield example files into `workflows/brownfield-examples.md` + +## 3. New Workflow Docs + +- [ ] 3.1 Write `workflows/cross-module-chains.md`: backlog -> code -> spec -> govern end-to-end flow +- [ ] 3.2 Write `workflows/daily-devops-routine.md`: morning standup -> refine -> commit -> review cycle +- [ ] 3.3 Write `workflows/ci-cd-pipeline.md`: CI integration with pre-commit hooks, GitHub Actions + +## 4. Update Existing + +- [ ] 4.1 Validate and update `workflows/command-chains.md` against current command surface +- [ ] 4.2 Add redirects from old brownfield file paths to new merged locations + +## 5. Verification + +- [ ] 5.1 Verify all command examples in workflow docs match actual `--help` output +- [ ] 5.2 Verify all internal links resolve +- [ ] 5.3 Run `bundle exec jekyll build` with zero warnings diff --git a/openspec/changes/docs-11-team-enterprise-tier/CHANGE_VALIDATION.md b/openspec/changes/docs-11-team-enterprise-tier/CHANGE_VALIDATION.md new file mode 100644 index 0000000..3e76348 --- /dev/null +++ b/openspec/changes/docs-11-team-enterprise-tier/CHANGE_VALIDATION.md @@ -0,0 +1,65 @@ +# Change Validation Report: docs-11-team-enterprise-tier + +**Validation Date**: 2026-03-23 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Dry-run simulation (documentation-only change, no code interfaces affected) + +## Executive Summary + +- Breaking Changes: 0 detected / 0 resolved +- Dependent Files: 0 code files affected (docs-only) +- Impact Level: Low (new and expanded documentation pages, no code changes) +- Validation Result: Pass +- User Decision: N/A (no breaking changes) + +## Breaking Changes Detected + +None. This change expands 2 existing guides and writes 2 new team/enterprise guides. No Python code is modified. + +## Dependencies Affected + +### Cross-Change Dependencies + +- **Blocked by**: docs-06-modules-site-ia-restructure (team-and-enterprise/ directory structure must exist) + +### Critical Updates Required + +None. + +### Recommended Updates + +- Enterprise configuration docs should reference actual profile and overlay mechanisms from the codebase +- Team docs should align with any existing team-collaboration features + +## Impact Assessment + +- **Code Impact**: None (documentation only) +- **Test Impact**: None +- **Documentation Impact**: Medium - 2 expanded guides + 2 new pages for team/enterprise audience tier +- **Release Impact**: N/A (docs-only) + +## Format Validation + +- **proposal.md Format**: Pass + - Title format: Correct (`# Change: Create Team And Enterprise Documentation Tier`) + - Required sections: All present (Why, What Changes, Capabilities, Impact) + - "Capabilities" section: Present (team-setup-docs, enterprise-config-docs) + - Source Tracking section: Present (#99) +- **tasks.md Format**: Pass + - Section headers: Correct (hierarchical) + - Task format: Correct +- **specs Format**: Pass + - Given/When/Then format: Verified (team-enterprise-docs/spec.md) +- **Format Issues Found**: 0 +- **Config.yaml Compliance**: Pass + +## OpenSpec Validation + +- **Status**: Pass (manual validation) +- **Issues Found**: 0 +- **Issues Fixed**: 0 +- **Re-validated**: No + +## Validation Artifacts + +- No temporary workspace needed (documentation-only) diff --git a/openspec/changes/docs-11-team-enterprise-tier/proposal.md b/openspec/changes/docs-11-team-enterprise-tier/proposal.md new file mode 100644 index 0000000..4716279 --- /dev/null +++ b/openspec/changes/docs-11-team-enterprise-tier/proposal.md @@ -0,0 +1,33 @@ +# Change: Create Team And Enterprise Documentation Tier + +## Why + +All existing docs assume individual developer usage. There is no guidance for team leads setting up SpecFact for a team, configuring shared profiles, managing multi-repo setups, or applying enterprise-level configuration. This gap prevents adoption beyond solo developers. + +## What Changes + +- Expand team-collaboration-workflow.md into a full team setup guide covering onboarding, shared config, and role-based workflows +- Expand agile-scrum-workflows.md into a team onboarding playbook for Scrum and Kanban teams +- Write new multi-repo setup guide for teams working across multiple repositories +- Write new enterprise configuration guide covering custom profiles, domain overlays, and central config management + +## Capabilities + +### New Capabilities + +- `team-setup-docs`: guides for team leads setting up SpecFact for small-medium teams +- `enterprise-config-docs`: guides for enterprise environments with custom profiles and central configuration + +## Impact + +- Expanded files: `team-and-enterprise/team-collaboration.md`, `team-and-enterprise/agile-scrum-setup.md` +- New files: `team-and-enterprise/multi-repo.md`, `team-and-enterprise/enterprise-config.md` +- Depends on: `docs-06-modules-site-ia-restructure` + +## Source Tracking + + +- **GitHub Issue**: #99 +- **Issue URL**: https://github.com/nold-ai/specfact-cli-modules/issues/99 +- **Last Synced Status**: synced +- **Sanitized**: true diff --git a/openspec/changes/docs-11-team-enterprise-tier/specs/team-enterprise-docs/spec.md b/openspec/changes/docs-11-team-enterprise-tier/specs/team-enterprise-docs/spec.md new file mode 100644 index 0000000..b468c7d --- /dev/null +++ b/openspec/changes/docs-11-team-enterprise-tier/specs/team-enterprise-docs/spec.md @@ -0,0 +1,23 @@ +# Capability: team-enterprise-docs + +Documentation tier for team and enterprise adoption of SpecFact. + +## Scenarios + +### Scenario: Team setup guide covers onboarding + +Given the team-collaboration doc +When a team lead reads the page +Then it covers: initial setup for a team, shared configuration, role-based workflows, and recommended ceremony schedules + +### Scenario: Enterprise config guide covers customization + +Given the enterprise-config doc +When an enterprise admin reads the page +Then it covers: custom profiles, domain overlays, central configuration, and multi-registry setups + +### Scenario: Multi-repo guide covers cross-repo workflows + +Given the multi-repo doc +When a user managing multiple repositories reads the page +Then it covers: shared bundle configuration, cross-repo sync, and repository-specific overrides diff --git a/openspec/changes/docs-11-team-enterprise-tier/tasks.md b/openspec/changes/docs-11-team-enterprise-tier/tasks.md new file mode 100644 index 0000000..77315d0 --- /dev/null +++ b/openspec/changes/docs-11-team-enterprise-tier/tasks.md @@ -0,0 +1,20 @@ +## 1. Change Setup + +- [ ] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-11-team-enterprise-tier` entry +- [ ] 1.2 Add `team-setup-docs` and `enterprise-config-docs` capability specs + +## 2. Expand Existing Guides + +- [ ] 2.1 Expand team-collaboration-workflow into `team-and-enterprise/team-collaboration.md`: onboarding, shared config, roles +- [ ] 2.2 Expand agile-scrum-workflows into `team-and-enterprise/agile-scrum-setup.md`: Scrum + Kanban team playbooks + +## 3. New Enterprise Guides + +- [ ] 3.1 Write `team-and-enterprise/multi-repo.md`: multi-repo setups with shared bundles +- [ ] 3.2 Write `team-and-enterprise/enterprise-config.md`: custom profiles, domain overlays, central config + +## 4. Verification + +- [ ] 4.1 Verify all command examples match actual CLI +- [ ] 4.2 Verify all internal links resolve +- [ ] 4.3 Run `bundle exec jekyll build` with zero warnings diff --git a/openspec/changes/docs-12-docs-validation-ci/CHANGE_VALIDATION.md b/openspec/changes/docs-12-docs-validation-ci/CHANGE_VALIDATION.md new file mode 100644 index 0000000..377593f --- /dev/null +++ b/openspec/changes/docs-12-docs-validation-ci/CHANGE_VALIDATION.md @@ -0,0 +1,67 @@ +# Change Validation Report: docs-12-docs-validation-ci + +**Validation Date**: 2026-03-23 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Dry-run simulation (mixed change: new scripts + CI config, no existing interfaces modified) + +## Executive Summary + +- Breaking Changes: 0 detected / 0 resolved +- Dependent Files: 0 existing code files affected +- Impact Level: Low (additive change - new scripts and CI steps only) +- Validation Result: Pass +- User Decision: N/A (no breaking changes) + +## Breaking Changes Detected + +None. This change adds new validation scripts and CI steps. No existing code is modified. + +## Dependencies Affected + +### Cross-Change Dependencies + +- **Blocked by**: docs-06 through docs-10 (content restructure must be complete), specfact-cli/docs-12-docs-validation-ci (core-side counterpart) +- **Cross-repo**: corresponds to specfact-cli/docs-12-docs-validation-ci + +### Critical Updates Required + +None. + +### Recommended Updates + +- Coordinate with core-side docs-12 for consistent validation approach +- Scripts should extract command registrations from `packages/*/src/**/commands.py` + +## Impact Assessment + +- **Code Impact**: Low (1 new script, no modifications to existing code) +- **Test Impact**: Low (new tests for new scripts only) +- **Documentation Impact**: Low (CI workflow addition) +- **Release Impact**: N/A (modules repo) + +## Format Validation + +- **proposal.md Format**: Pass + - Title format: Correct (`# Change: Add CI Validation For Docs Command Examples And Cross-Site Links (Modules Side)`) + - Required sections: All present (Why, What Changes, Capabilities, Impact) + - "Capabilities" section: Present (modules-docs-command-validation) + - Source Tracking section: Present (#100, cross-repo reference) +- **tasks.md Format**: Pass + - Section headers: Correct (hierarchical) + - Task format: Correct +- **specs Format**: Pass + - Given/When/Then format: Verified (modules-docs-command-validation/spec.md) +- **Format Issues Found**: 0 +- **Config.yaml Compliance**: Pass + +## OpenSpec Validation + +- **Status**: Pass (manual validation) +- **Issues Found**: 0 +- **Issues Fixed**: 0 +- **Re-validated**: No + +## Validation Artifacts + +- No temporary workspace needed (additive change, no existing interfaces modified) +- Cross-repo dependency on specfact-cli/docs-12 documented in proposal Source Tracking diff --git a/openspec/changes/docs-12-docs-validation-ci/proposal.md b/openspec/changes/docs-12-docs-validation-ci/proposal.md new file mode 100644 index 0000000..6572fa0 --- /dev/null +++ b/openspec/changes/docs-12-docs-validation-ci/proposal.md @@ -0,0 +1,32 @@ +# Change: Add CI Validation For Docs Command Examples And Cross-Site Links (Modules Side) + +## Why + +Documentation command examples can drift from actual module implementations. Cross-site links to docs.specfact.io can break when core pages are moved. This is the modules-side counterpart to the core-side docs-12 change. + +## What Changes + +- Add a script that extracts command registrations from all `packages/*/src/**/commands.py` and compares against command examples in `docs/bundles/` +- Add cross-site link validation for links from modules docs to core docs +- Integrate into CI workflow + +## Capabilities + +### New Capabilities + +- `modules-docs-command-validation`: CI check that module docs command examples match actual bundle implementations + +## Impact + +- New scripts: `scripts/check-docs-commands.py` +- Modified CI: docs validation step added +- Cross-repo: corresponds to specfact-cli/docs-12-docs-validation-ci + +## Source Tracking + + +- **GitHub Issue**: #100 +- **Issue URL**: https://github.com/nold-ai/specfact-cli-modules/issues/100 +- **Last Synced Status**: synced +- **Sanitized**: true +- **Cross-repo**: specfact-cli/docs-12-docs-validation-ci diff --git a/openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md b/openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md new file mode 100644 index 0000000..589dce0 --- /dev/null +++ b/openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md @@ -0,0 +1,19 @@ +# Capability: modules-docs-command-validation + +CI validation that module docs command examples match actual bundle implementations. + +## Scenarios + +### Scenario: Valid command example passes + +Given a docs page references `specfact backlog ceremony standup` +When the validation runs +Then it finds a matching registration in the backlog package source +And the check passes + +### Scenario: Invalid command example fails + +Given a docs page references `specfact backlog nonexistent` +When the validation runs +Then it reports the mismatch +And the check fails diff --git a/openspec/changes/docs-12-docs-validation-ci/tasks.md b/openspec/changes/docs-12-docs-validation-ci/tasks.md new file mode 100644 index 0000000..3b08bf2 --- /dev/null +++ b/openspec/changes/docs-12-docs-validation-ci/tasks.md @@ -0,0 +1,22 @@ +## 1. Change Setup + +- [ ] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-12-docs-validation-ci` entry +- [ ] 1.2 Add `modules-docs-command-validation` capability spec + +## 2. Command Validation Script + +- [ ] 2.1 Write `scripts/check-docs-commands.py` to extract command registrations from `packages/*/src/**/commands.py` +- [ ] 2.2 Compare extracted commands against code blocks in `docs/bundles/` and `docs/reference/commands.md` + +## 3. Cross-Site Link Validation + +- [ ] 3.1 Add link validation for cross-site URLs pointing to docs.specfact.io + +## 4. CI Integration + +- [ ] 4.1 Add docs validation step to CI workflow + +## 5. Verification + +- [ ] 5.1 Run validation locally and verify it catches broken examples +- [ ] 5.2 Run CI workflow end-to-end From 7fb360d997d33fe88b66b5265bbefdc05e60a4bb Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Tue, 24 Mar 2026 21:53:33 +0100 Subject: [PATCH 4/7] Added claude.md --- CLAUDE.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f209fc8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,101 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project + +`specfact-cli-modules` hosts official nold-ai bundle packages and the module registry used by SpecFact CLI. Bundle packages import from `specfact_cli` (models, runtime, validators). The core CLI lives in a sibling repo (`specfact-cli`). + +## Local Setup + +```bash +hatch env create +hatch run dev-deps # installs specfact-cli from $SPECFACT_CLI_REPO or ../specfact-cli +``` + +In worktrees, `dev-deps` prefers a matching `specfact-cli-worktrees/` checkout before falling back to the canonical sibling repo. + +## Quality Gates + +Run in this order: + +```bash +hatch run format +hatch run type-check +hatch run lint +hatch run yaml-lint +hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump +hatch run contract-test +hatch run smart-test +hatch run test +``` + +Run a single test file: `hatch run test tests/path/to/test_file.py` +Run a single test: `hatch run test tests/path/to/test_file.py::TestClass::test_name` + +Pre-commit hooks mirror CI: `pre-commit install && pre-commit run --all-files` + +CI runs in `.github/workflows/pr-orchestrator.yml` — matrix quality gates on Python 3.11/3.12/3.13. + +## Architecture + +### Bundle packages (`packages//`) + +Six official bundles: `specfact-backlog`, `specfact-codebase`, `specfact-code-review`, `specfact-govern`, `specfact-project`, `specfact-spec`. Each bundle has: +- `module-package.yaml` — name, version, commands, core_compatibility, integrity checksums +- `src//` — bundle source code + +### Import policy (`ALLOWED_IMPORTS.md`) + +- Only allowed `specfact_cli.*` prefixes may be imported in bundle code (CORE/SHARED APIs only) +- Cross-bundle lateral imports are forbidden except specific allowed pairs (e.g. `specfact_spec` -> `specfact_project`) +- Enforced by `hatch run check-bundle-imports` + +### Registry (`registry/`) + +- `index.json` — published bundle metadata (versions, artifact URLs, checksums) +- `modules/` and `signatures/` — published artifacts + +### Repo tooling + +- `tools/` — development infrastructure (type-checker wrapper, smart test coverage, contract-first testing, manifest validation, core dependency bootstrapping) +- `scripts/` — publishing, signing, import checking, pre-commit hooks +- `src/specfact_cli_modules/` — shared repo-level Python package + +### OpenSpec workflow (`openspec/`) + +- `openspec/specs/` — canonical specifications +- `openspec/changes/` — active change proposals (proposal, design, delta specs, tasks, TDD evidence) +- `openspec/changes/archive/` — completed changes +- `openspec/CHANGE_ORDER.md` — tracks change sequencing and dependencies + +## Development Workflow + +### Branch protection + +`dev` and `main` are protected — never work directly on them. Use feature branches: `feature/*`, `bugfix/*`, `hotfix/*`, `chore/*`. PRs go to `dev` unless release workflow requires `main`. + +### Git worktrees + +Use worktrees for parallel branch work. Keep primary checkout as canonical `dev` workspace. Worktree paths: `../specfact-cli-modules-worktrees//`. + +### OpenSpec (required before code changes) + +Verify an active OpenSpec change covers the requested scope before changing code. If missing: create or extend a change first. + +Follow strict TDD order: spec delta -> failing tests -> implementation -> passing tests -> quality gates. Record TDD evidence in `openspec/changes//TDD_EVIDENCE.md`. + +### OpenSpec archive rule (hard requirement) + +Never manually move folders under `openspec/changes/` into `archive/`. Archiving MUST use `openspec archive ` (or equivalent workflow command). Update `openspec/CHANGE_ORDER.md` when archive status changes. + +## Bundle Versioning + +SemVer: patch (bug fix), minor (new command/option/API), major (breaking change/removal). When bumping a version, review and update `core_compatibility` in both `module-package.yaml` and `registry/index.json`. + +## Linting Scope + +- `ruff` runs on the full repo +- `basedpyright` and `pylint` are scoped to `src/`, `tests/`, and `tools/` +- Line length: 120 characters +- Python target: 3.11+ From 7f73013c1cac9790cc149fa736717ef9bf073643 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Tue, 24 Mar 2026 22:25:11 +0100 Subject: [PATCH 5/7] docs: restructure modules site IA with per-bundle navigation (#95) Restructure modules docs from 6 flat sections to 7 progressive sections (Getting Started, Bundles, Workflows, Integrations, Team & Enterprise, Authoring, Reference) with per-bundle collapsible sidebar navigation. - Move 15 guides to bundle/authoring/integration directories - Add jekyll-redirect-from entries for all moved URLs - Rewrite index.md as bundle-focused landing page - Update sidebar to 7-section nav with collapsible bundle groups - Add Gemfile/Gemfile.lock aligned with specfact-cli docs infrastructure - Align docs-pages workflow with specfact-cli (Ruby 3.2 + bundler build) - Fix duplicate excludes in _config.yml Co-Authored-By: Claude Opus 4.6 --- .github/workflows/docs-pages.yml | 37 +++++-- docs/Gemfile | 17 +++ docs/Gemfile.lock | 100 ++++++++++++++++++ docs/_config.yml | 23 +++- docs/_layouts/default.html | 97 ++++++++++++----- .../adapter-development.md | 4 +- .../creating-custom-bridges.md | 4 +- .../custom-registries.md | 4 +- .../extending-projectbundle.md | 4 +- .../module-development.md | 4 +- .../module-signing.md} | 4 +- .../publishing-modules.md | 4 +- .../backlog/delta.md} | 4 +- .../backlog/dependency-analysis.md} | 4 +- .../backlog/policy-engine.md} | 4 +- .../backlog/refinement.md} | 4 +- .../codebase}/sidecar-validation.md | 4 +- .../project/devops-flow.md} | 4 +- .../project/import-migration.md} | 4 +- docs/getting-started/README.md | 32 +++--- docs/index.md | 61 +++++------ .../devops-adapter-overview.md} | 4 +- openspec/CHANGE_ORDER.md | 2 +- .../tasks.md | 54 +++++----- 24 files changed, 360 insertions(+), 123 deletions(-) create mode 100644 docs/Gemfile create mode 100644 docs/Gemfile.lock rename docs/{guides => authoring}/adapter-development.md (97%) rename docs/{guides => authoring}/creating-custom-bridges.md (93%) rename docs/{guides => authoring}/custom-registries.md (97%) rename docs/{guides => authoring}/extending-projectbundle.md (97%) rename docs/{guides => authoring}/module-development.md (95%) rename docs/{guides/module-signing-and-key-rotation.md => authoring/module-signing.md} (98%) rename docs/{guides => authoring}/publishing-modules.md (97%) rename docs/{guides/backlog-delta-commands.md => bundles/backlog/delta.md} (92%) rename docs/{guides/backlog-dependency-analysis.md => bundles/backlog/dependency-analysis.md} (92%) rename docs/{guides/policy-engine-commands.md => bundles/backlog/policy-engine.md} (97%) rename docs/{guides/backlog-refinement.md => bundles/backlog/refinement.md} (99%) rename docs/{guides => bundles/codebase}/sidecar-validation.md (99%) rename docs/{guides/project-devops-flow.md => bundles/project/devops-flow.md} (93%) rename docs/{guides/import-features.md => bundles/project/import-migration.md} (98%) rename docs/{guides/devops-adapter-integration.md => integrations/devops-adapter-overview.md} (99%) diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml index 7c79d80..b9b0b10 100644 --- a/.github/workflows/docs-pages.yml +++ b/.github/workflows/docs-pages.yml @@ -19,26 +19,49 @@ concurrency: jobs: build: + name: Build GitHub Pages runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 + with: + fetch-depth: 0 - - name: Setup Pages - uses: actions/configure-pages@v5 + - name: Setup Ruby (for Jekyll) + uses: ruby/setup-ruby@v1 + with: + ruby-version: "3.2" + bundler-cache: false + working-directory: ./docs + + - name: Install Jekyll dependencies + run: | + cd docs + bundle config set --local path 'vendor/bundle' + bundle install --jobs 1 --retry 3 - name: Build with Jekyll - uses: actions/jekyll-build-pages@v1 - with: - source: ./docs - destination: ./docs/_site + run: | + cd docs + bundle exec jekyll build --destination ../_site + # Fix CSS path: Jekyll outputs main.css at main/index.css due to permalink pattern + # Copy it to assets/main.css where the HTML expects it + if [ -f ../_site/main/index.css ]; then + cp ../_site/main/index.css ../_site/assets/main.css + fi + env: + JEKYLL_ENV: production + + - name: Setup Pages + uses: actions/configure-pages@v5 - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: - path: ./docs/_site + path: _site deploy: + name: Deploy to GitHub Pages environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..8995262 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,17 @@ +# frozen_string_literal: true + +source "https://rubygems.org" + +gem "jekyll", "~> 4.3" +gem "minima", "~> 2.5" +gem "jekyll-feed", "~> 0.12" +gem "jekyll-redirect-from", "~> 0.16" +gem "jekyll-relative-links", "~> 0.7" +gem "jekyll-sitemap", "~> 1.4" + +platforms :mingw, :x64_mingw, :mswin, :jruby do + gem "tzinfo", ">= 1", "< 3" + gem "tzinfo-data" +end + +gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin] diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 0000000..972dd41 --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,100 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.8.7) + public_suffix (>= 2.0.2, < 7.0) + base64 (0.3.0) + colorator (1.1.0) + concurrent-ruby (1.3.5) + csv (3.3.5) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + eventmachine (1.2.7) + ffi (1.17.2) + forwardable-extended (2.6.0) + google-protobuf (3.25.8-x86_64-linux) + http_parser.rb (0.8.0) + i18n (1.14.7) + concurrent-ruby (~> 1.0) + jekyll (4.4.1) + addressable (~> 2.4) + base64 (~> 0.2) + colorator (~> 1.0) + csv (~> 3.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + json (~> 2.6) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (~> 0.3, >= 0.3.6) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-feed (0.17.0) + jekyll (>= 3.7, < 5.0) + jekyll-redirect-from (0.16.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.7.0) + jekyll (>= 3.3, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + json (2.17.1.2) + kramdown (2.5.1) + rexml (>= 3.3.9) + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.9.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + minima (2.5.2) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (6.0.2) + rake (13.3.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.4.4) + rouge (4.6.1) + safe_yaml (1.0.5) + sass-embedded (1.69.5) + google-protobuf (~> 3.23) + rake (>= 13.0.0) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.6.0) + webrick (1.9.1) + +PLATFORMS + x86_64-linux + +DEPENDENCIES + jekyll (~> 4.3) + jekyll-feed (~> 0.12) + jekyll-redirect-from (~> 0.16) + jekyll-relative-links (~> 0.7) + jekyll-sitemap (~> 1.4) + minima (~> 2.5) + tzinfo (>= 1, < 3) + tzinfo-data + wdm (~> 0.1.1) + +BUNDLED WITH + 2.3.5 diff --git a/docs/_config.yml b/docs/_config.yml index 3aae7c0..bb74f62 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -12,6 +12,7 @@ markdown: kramdown highlighter: rouge plugins: - jekyll-feed + - jekyll-redirect-from - jekyll-relative-links - jekyll-sitemap @@ -28,8 +29,6 @@ exclude: - tests - tools - packages - - tests - - tools - scripts - registry @@ -62,6 +61,26 @@ defaults: path: "reference" values: layout: default + - scope: + path: "bundles" + values: + layout: default + - scope: + path: "workflows" + values: + layout: default + - scope: + path: "integrations" + values: + layout: default + - scope: + path: "team-and-enterprise" + values: + layout: default + - scope: + path: "authoring" + values: + layout: default theme: minima minima: social: diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index f95cb3f..de61069 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -139,39 +139,85 @@

  • Tutorial: Daily Standup and Sprint Review
    • -

    Official Modules

    +

    Bundles

    +
    + Backlog + +
    +
    + Project + +
    +
    + Codebase + +
    +
    + Code Review + +
    +
    + Spec + +
    +
    + Govern + +
    + +

    Workflows

    -

    Bundle Workflows

    +

    Integrations

    -

    Publishing & Signing

    +

    Team & Enterprise

    + +

    Authoring

    +

    Reference

    @@ -187,7 +233,8 @@

  • Module Contracts
  • Module Categories
  • Dependency Resolution
    • -
  • Integrations Overview
    • +
  • Module Security
    • +
  • Bridge Registry
    • diff --git a/docs/guides/adapter-development.md b/docs/authoring/adapter-development.md similarity index 97% rename from docs/guides/adapter-development.md rename to docs/authoring/adapter-development.md index 5cb54f5..b5ca7c5 100644 --- a/docs/guides/adapter-development.md +++ b/docs/authoring/adapter-development.md @@ -1,7 +1,9 @@ --- layout: default title: Adapter Development Guide -permalink: /guides/adapter-development/ +permalink: /authoring/adapter-development/ +redirect_from: + - /guides/adapter-development/ description: Implement BridgeAdapter integrations for external tools. --- diff --git a/docs/guides/creating-custom-bridges.md b/docs/authoring/creating-custom-bridges.md similarity index 93% rename from docs/guides/creating-custom-bridges.md rename to docs/authoring/creating-custom-bridges.md index 9ba48b6..fa5b14d 100644 --- a/docs/guides/creating-custom-bridges.md +++ b/docs/authoring/creating-custom-bridges.md @@ -1,7 +1,9 @@ --- layout: default title: Creating Custom Bridges -permalink: /guides/creating-custom-bridges/ +permalink: /authoring/creating-custom-bridges/ +redirect_from: + - /guides/creating-custom-bridges/ --- # Creating Custom Bridges diff --git a/docs/guides/custom-registries.md b/docs/authoring/custom-registries.md similarity index 97% rename from docs/guides/custom-registries.md rename to docs/authoring/custom-registries.md index 5fceccd..746a778 100644 --- a/docs/guides/custom-registries.md +++ b/docs/authoring/custom-registries.md @@ -1,7 +1,9 @@ --- layout: default title: Custom registries -permalink: /guides/custom-registries/ +permalink: /authoring/custom-registries/ +redirect_from: + - /guides/custom-registries/ description: Add, list, and manage custom module registries with trust levels and priority. --- diff --git a/docs/guides/extending-projectbundle.md b/docs/authoring/extending-projectbundle.md similarity index 97% rename from docs/guides/extending-projectbundle.md rename to docs/authoring/extending-projectbundle.md index 8e967ff..2d5b866 100644 --- a/docs/guides/extending-projectbundle.md +++ b/docs/authoring/extending-projectbundle.md @@ -1,7 +1,9 @@ --- layout: default title: Extending ProjectBundle -permalink: /guides/extending-projectbundle/ +permalink: /authoring/extending-projectbundle/ +redirect_from: + - /guides/extending-projectbundle/ description: Add namespaced custom fields to Feature and ProjectBundle without modifying core models. --- diff --git a/docs/guides/module-development.md b/docs/authoring/module-development.md similarity index 95% rename from docs/guides/module-development.md rename to docs/authoring/module-development.md index 24b1534..e68e01a 100644 --- a/docs/guides/module-development.md +++ b/docs/authoring/module-development.md @@ -1,7 +1,9 @@ --- layout: default title: Module Development Guide -permalink: /guides/module-development/ +permalink: /authoring/module-development/ +redirect_from: + - /guides/module-development/ description: How to build and package SpecFact CLI modules. --- diff --git a/docs/guides/module-signing-and-key-rotation.md b/docs/authoring/module-signing.md similarity index 98% rename from docs/guides/module-signing-and-key-rotation.md rename to docs/authoring/module-signing.md index f30b1cf..c21f863 100644 --- a/docs/guides/module-signing-and-key-rotation.md +++ b/docs/authoring/module-signing.md @@ -1,7 +1,9 @@ --- layout: default title: Module Signing and Key Rotation -permalink: /guides/module-signing-and-key-rotation/ +permalink: /authoring/module-signing/ +redirect_from: + - /guides/module-signing-and-key-rotation/ description: Runbook for signing bundled modules, placing public keys, rotating keys, and revoking compromised keys. --- diff --git a/docs/guides/publishing-modules.md b/docs/authoring/publishing-modules.md similarity index 97% rename from docs/guides/publishing-modules.md rename to docs/authoring/publishing-modules.md index d1360ba..93088bb 100644 --- a/docs/guides/publishing-modules.md +++ b/docs/authoring/publishing-modules.md @@ -1,7 +1,9 @@ --- layout: default title: Publishing Modules -permalink: /guides/publishing-modules/ +permalink: /authoring/publishing-modules/ +redirect_from: + - /guides/publishing-modules/ description: Package and publish SpecFact modules to a registry (tarball, checksum, optional signing). --- diff --git a/docs/guides/backlog-delta-commands.md b/docs/bundles/backlog/delta.md similarity index 92% rename from docs/guides/backlog-delta-commands.md rename to docs/bundles/backlog/delta.md index b2b484c..b98f26e 100644 --- a/docs/guides/backlog-delta-commands.md +++ b/docs/bundles/backlog/delta.md @@ -1,7 +1,9 @@ --- layout: default title: Backlog Delta Commands -permalink: /guides/backlog-delta-commands/ +permalink: /bundles/backlog/delta/ +redirect_from: + - /guides/backlog-delta-commands/ --- # Backlog Delta Commands diff --git a/docs/guides/backlog-dependency-analysis.md b/docs/bundles/backlog/dependency-analysis.md similarity index 92% rename from docs/guides/backlog-dependency-analysis.md rename to docs/bundles/backlog/dependency-analysis.md index 9c1d762..8ab417e 100644 --- a/docs/guides/backlog-dependency-analysis.md +++ b/docs/bundles/backlog/dependency-analysis.md @@ -1,7 +1,9 @@ --- layout: default title: Backlog Dependency Analysis -permalink: /guides/backlog-dependency-analysis/ +permalink: /bundles/backlog/dependency-analysis/ +redirect_from: + - /guides/backlog-dependency-analysis/ --- # Backlog Dependency Analysis diff --git a/docs/guides/policy-engine-commands.md b/docs/bundles/backlog/policy-engine.md similarity index 97% rename from docs/guides/policy-engine-commands.md rename to docs/bundles/backlog/policy-engine.md index bfcb409..57338aa 100644 --- a/docs/guides/policy-engine-commands.md +++ b/docs/bundles/backlog/policy-engine.md @@ -1,7 +1,9 @@ --- layout: default title: Policy Engine Commands -permalink: /guides/policy-engine-commands/ +permalink: /bundles/backlog/policy-engine/ +redirect_from: + - /guides/policy-engine-commands/ --- # Policy Engine Commands diff --git a/docs/guides/backlog-refinement.md b/docs/bundles/backlog/refinement.md similarity index 99% rename from docs/guides/backlog-refinement.md rename to docs/bundles/backlog/refinement.md index 4d09005..84bf2a7 100644 --- a/docs/guides/backlog-refinement.md +++ b/docs/bundles/backlog/refinement.md @@ -1,7 +1,9 @@ --- layout: default title: Backlog Refinement Guide -permalink: /guides/backlog-refinement/ +permalink: /bundles/backlog/refinement/ +redirect_from: + - /guides/backlog-refinement/ --- # Backlog Refinement Guide diff --git a/docs/guides/sidecar-validation.md b/docs/bundles/codebase/sidecar-validation.md similarity index 99% rename from docs/guides/sidecar-validation.md rename to docs/bundles/codebase/sidecar-validation.md index e902c9a..083f6c6 100644 --- a/docs/guides/sidecar-validation.md +++ b/docs/bundles/codebase/sidecar-validation.md @@ -1,7 +1,9 @@ --- layout: default title: Sidecar Validation Guide -permalink: /guides/sidecar-validation/ +permalink: /bundles/codebase/sidecar-validation/ +redirect_from: + - /guides/sidecar-validation/ --- # Sidecar Validation Guide diff --git a/docs/guides/project-devops-flow.md b/docs/bundles/project/devops-flow.md similarity index 93% rename from docs/guides/project-devops-flow.md rename to docs/bundles/project/devops-flow.md index 4017210..352b287 100644 --- a/docs/guides/project-devops-flow.md +++ b/docs/bundles/project/devops-flow.md @@ -1,7 +1,9 @@ --- layout: default title: Project DevOps Flow -permalink: /guides/project-devops-flow/ +permalink: /bundles/project/devops-flow/ +redirect_from: + - /guides/project-devops-flow/ --- # Project DevOps Flow diff --git a/docs/guides/import-features.md b/docs/bundles/project/import-migration.md similarity index 98% rename from docs/guides/import-features.md rename to docs/bundles/project/import-migration.md index a660049..2165cbf 100644 --- a/docs/guides/import-features.md +++ b/docs/bundles/project/import-migration.md @@ -1,7 +1,9 @@ --- layout: default title: Import Command Features -permalink: /guides/import-features/ +permalink: /bundles/project/import-migration/ +redirect_from: + - /guides/import-features/ --- # Import Command Features diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 5863369..5bb43b3 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -1,6 +1,6 @@ -# Getting Started with SpecFact CLI +# Getting Started with SpecFact Modules -Welcome to SpecFact CLI! This guide will help you get started in under 60 seconds. +Welcome to the **modules** getting-started guide. This section covers installing and using official bundles. For core CLI platform setup, see [docs.specfact.io](https://docs.specfact.io). ## Installation @@ -78,20 +78,20 @@ Some bundles install dependencies automatically: ## Next Steps -- 📖 **[Installation Guide](installation.md)** - Install SpecFact CLI -- 📖 **[First Steps](first-steps.md)** - Step-by-step first commands -- 📖 **[Module Bootstrap Checklist](module-bootstrap-checklist.md)** - Verify bundled modules are installed in user/project scope -- 📖 **[Tutorial: Using SpecFact with OpenSpec or Spec-Kit](tutorial-openspec-speckit.md)** ⭐ **NEW** - Complete beginner-friendly tutorial -- 📖 **[DevOps Backlog Integration](../guides/devops-adapter-integration.md)** 🆕 **NEW FEATURE** - Integrate SpecFact into agile DevOps workflows -- 📖 **[Backlog Refinement](../guides/backlog-refinement.md)** 🆕 **NEW FEATURE** - AI-assisted template-driven refinement for standardizing work items -- 📖 **[Tutorial: Backlog Quickstart Demo (GitHub + ADO)](tutorial-backlog-quickstart-demo.md)** 🆕 - Short end-to-end demo: `init-config`, `map-fields`, `daily`, `refine`, plus create/check loop -- 📖 **[Tutorial: Backlog Refine with AI IDE](tutorial-backlog-refine-ai-ide.md)** 🆕 - End-to-end for agile DevOps teams: slash prompt, story quality, underspecification, splitting, DoR, custom templates -- 📖 **[Tutorial: Daily Standup and Sprint Review](tutorial-daily-standup-sprint-review.md)** 🆕 - End-to-end daily standup: auto-detect repo (GitHub/ADO), view standup table, post comment, interactive, Copilot export -- 📖 **[Use Cases](../guides/use-cases.md)** - See real-world examples -- 📖 **[Command Reference](../reference/commands.md)** - Learn all available commands +- [Installation Guide](installation.md) - Install SpecFact CLI +- [First Steps](first-steps.md) - Step-by-step first commands +- [Module Bootstrap Checklist](module-bootstrap-checklist.md) - Verify bundled modules are installed in user/project scope +- [Tutorial: Using SpecFact with OpenSpec or Spec-Kit](tutorial-openspec-speckit.md) - Complete beginner-friendly tutorial +- [DevOps Adapter Integration](../integrations/devops-adapter-overview.md) - Integrate SpecFact into agile DevOps workflows +- [Backlog Refinement](../bundles/backlog/refinement.md) - AI-assisted template-driven refinement for standardizing work items +- [Tutorial: Backlog Quickstart Demo (GitHub + ADO)](tutorial-backlog-quickstart-demo.md) - Short end-to-end demo +- [Tutorial: Backlog Refine with AI IDE](tutorial-backlog-refine-ai-ide.md) - End-to-end for agile DevOps teams +- [Tutorial: Daily Standup and Sprint Review](tutorial-daily-standup-sprint-review.md) - End-to-end daily standup +- [Use Cases](../guides/use-cases.md) - See real-world examples +- [Command Reference](../reference/commands.md) - Learn all available commands ## Need Help? -- 💬 [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) -- 🐛 [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) -- 📧 [hello@noldai.com](mailto:hello@noldai.com) +- [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions) +- [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues) +- [hello@noldai.com](mailto:hello@noldai.com) diff --git a/docs/index.md b/docs/index.md index cdad22b..06a0328 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,43 +7,44 @@ permalink: / # Official SpecFact Modules Docs -This site is the canonical published home for official bundle and module-specific deep documentation. +Canonical documentation for official nold-ai bundles and module-specific workflows. -specfact-cli-modules owns the official bundle and module-specific deep guidance, while the core CLI platform docs remain separately owned by the core docs site. +The modules site owns all bundle-specific deep guidance. Core CLI platform docs remain at [docs.specfact.io](https://docs.specfact.io). -The intended public docs topology is: +## Official Bundles -- `Docs Home` at `https://docs.specfact.io` -- `Core CLI` at `https://docs.specfact.io` -- `Modules` at `https://modules.specfact.io` +| Bundle | Description | +|--------|-------------| +| [Backlog](bundles/backlog/refinement/) | AI-assisted refinement, delta commands, dependency analysis, policy engine | +| [Project](bundles/project/devops-flow/) | DevOps flow, import/migration, project setup | +| [Codebase](bundles/codebase/sidecar-validation/) | Sidecar validation, codebase analysis | +| [Spec](reference/commands/) | Specification management | +| [Govern](reference/commands/) | Governance and compliance | +| [Code Review](reference/commands/) | Automated code review with ruff, radon, semgrep | -Until Cloudflare routing is enabled for the modules domain, GitHub Pages should be treated as a preview origin rather than the long-term canonical public address. +## Getting Started -## Official module guides +- [Installation](getting-started/installation/) +- [First Steps](getting-started/first-steps/) +- [Module Bootstrap Checklist](getting-started/module-bootstrap-checklist/) +- [Tutorial: Backlog Quickstart Demo](getting-started/tutorial-backlog-quickstart-demo/) -- [Marketplace bundles](guides/marketplace.md) -- [Installing modules](guides/installing-modules.md) -- [Module marketplace](guides/module-marketplace.md) -- [Module development](guides/module-development.md) -- [Publishing modules](guides/publishing-modules.md) -- [Module signing and key rotation](guides/module-signing-and-key-rotation.md) -- [Adapter development](guides/adapter-development.md) -- [Custom registries](guides/custom-registries.md) +## Workflows -## Bundle workflows +- [Backlog Refinement](bundles/backlog/refinement/) +- [Project DevOps Flow](bundles/project/devops-flow/) +- [DevOps Adapter Integration](integrations/devops-adapter-overview/) -- [Import features](guides/import-features.md) -- [Backlog refinement](guides/backlog-refinement.md) -- [Backlog dependency analysis](guides/backlog-dependency-analysis.md) -- [Backlog delta commands](guides/backlog-delta-commands.md) -- [Project DevOps flow](guides/project-devops-flow.md) -- [Policy engine commands](guides/policy-engine-commands.md) -- [Sidecar validation](guides/sidecar-validation.md) +## Authoring -## Module reference +- [Module Development](authoring/module-development/) +- [Publishing Modules](authoring/publishing-modules/) +- [Module Signing](authoring/module-signing/) +- [Custom Registries](authoring/custom-registries/) -- [Command reference](reference/commands.md) -- [Module categories](reference/module-categories.md) -- [Module contracts](reference/module-contracts.md) -- [Module security](reference/module-security.md) -- [Bridge registry](reference/bridge-registry.md) +## Reference + +- [Command Reference](reference/commands/) +- [Module Contracts](reference/module-contracts/) +- [Module Security](reference/module-security/) +- [Architecture](reference/architecture/) diff --git a/docs/guides/devops-adapter-integration.md b/docs/integrations/devops-adapter-overview.md similarity index 99% rename from docs/guides/devops-adapter-integration.md rename to docs/integrations/devops-adapter-overview.md index f7d9e52..01a24b4 100644 --- a/docs/guides/devops-adapter-integration.md +++ b/docs/integrations/devops-adapter-overview.md @@ -1,7 +1,9 @@ --- layout: default title: DevOps Adapter Integration Guide -permalink: /guides/devops-adapter-integration/ +permalink: /integrations/devops-adapter-overview/ +redirect_from: + - /guides/devops-adapter-integration/ --- # DevOps Adapter Integration Guide diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index bcf722b..e60fb3f 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -48,7 +48,7 @@ Cross-repo dependency: `docs-06-modules-site-ia-restructure` is a prerequisite f | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| docs | 06 | docs-06-modules-site-ia-restructure | [#95](https://github.com/nold-ai/specfact-cli-modules/issues/95) | docs-01 ✅; docs-cli-command-alignment ✅ | +| docs | 06 | docs-06-modules-site-ia-restructure | [#95](https://github.com/nold-ai/specfact-cli-modules/issues/95) | docs-01 ✅; docs-cli-command-alignment ✅ | **in-progress** | | docs | 08 | docs-08-bundle-overview-pages | [#96](https://github.com/nold-ai/specfact-cli-modules/issues/96) | docs-06-modules-site-ia-restructure | | docs | 09 | docs-09-missing-command-docs | [#97](https://github.com/nold-ai/specfact-cli-modules/issues/97) | docs-06-modules-site-ia-restructure | | docs | 10 | docs-10-workflow-consolidation | [#98](https://github.com/nold-ai/specfact-cli-modules/issues/98) | docs-06-modules-site-ia-restructure | diff --git a/openspec/changes/docs-06-modules-site-ia-restructure/tasks.md b/openspec/changes/docs-06-modules-site-ia-restructure/tasks.md index 148f04f..41e0403 100644 --- a/openspec/changes/docs-06-modules-site-ia-restructure/tasks.md +++ b/openspec/changes/docs-06-modules-site-ia-restructure/tasks.md @@ -1,44 +1,44 @@ ## 1. Change Setup And Spec Deltas -- [ ] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-06-modules-site-ia-restructure` entry -- [ ] 1.2 Add `modules-bundle-nav` capability spec for per-bundle sidebar navigation -- [ ] 1.3 Add `modules-progressive-tiers` capability spec for audience-tier organization +- [x] 1.1 Update `openspec/CHANGE_ORDER.md` with `docs-06-modules-site-ia-restructure` entry +- [x] 1.2 Add `modules-bundle-nav` capability spec for per-bundle sidebar navigation +- [x] 1.3 Add `modules-progressive-tiers` capability spec for audience-tier organization ## 2. Directory Structure -- [ ] 2.1 Create `docs/bundles/backlog/`, `docs/bundles/project/`, `docs/bundles/codebase/`, `docs/bundles/spec/`, `docs/bundles/govern/`, `docs/bundles/code-review/` -- [ ] 2.2 Create `docs/workflows/`, `docs/integrations/`, `docs/team-and-enterprise/`, `docs/authoring/` +- [x] 2.1 Create `docs/bundles/backlog/`, `docs/bundles/project/`, `docs/bundles/codebase/`, `docs/bundles/spec/`, `docs/bundles/govern/`, `docs/bundles/code-review/` +- [x] 2.2 Create `docs/workflows/`, `docs/integrations/`, `docs/team-and-enterprise/`, `docs/authoring/` ## 3. Move Backlog And Project Guides -- [ ] 3.1 Move `guides/backlog-refinement.md` to `bundles/backlog/refinement.md` -- [ ] 3.2 Move `guides/backlog-delta-commands.md` to `bundles/backlog/delta.md` -- [ ] 3.3 Move `guides/backlog-dependency-analysis.md` to `bundles/backlog/dependency-analysis.md` -- [ ] 3.4 Move `guides/policy-engine-commands.md` to `bundles/backlog/policy-engine.md` -- [ ] 3.5 Move `guides/project-devops-flow.md` to `bundles/project/devops-flow.md` -- [ ] 3.6 Move `guides/import-features.md` to `bundles/project/import-migration.md` -- [ ] 3.7 Move `guides/sidecar-validation.md` to `bundles/codebase/sidecar-validation.md` +- [x] 3.1 Move `guides/backlog-refinement.md` to `bundles/backlog/refinement.md` +- [x] 3.2 Move `guides/backlog-delta-commands.md` to `bundles/backlog/delta.md` +- [x] 3.3 Move `guides/backlog-dependency-analysis.md` to `bundles/backlog/dependency-analysis.md` +- [x] 3.4 Move `guides/policy-engine-commands.md` to `bundles/backlog/policy-engine.md` +- [x] 3.5 Move `guides/project-devops-flow.md` to `bundles/project/devops-flow.md` +- [x] 3.6 Move `guides/import-features.md` to `bundles/project/import-migration.md` +- [x] 3.7 Move `guides/sidecar-validation.md` to `bundles/codebase/sidecar-validation.md` ## 4. Move Integration And Authoring Guides -- [ ] 4.1 Move `guides/devops-adapter-integration.md` to `integrations/devops-adapter-overview.md` -- [ ] 4.2 Move `guides/publishing-modules.md` to `authoring/publishing-modules.md` -- [ ] 4.3 Move `guides/module-development.md` to `authoring/module-development.md` -- [ ] 4.4 Move `guides/adapter-development.md` to `authoring/adapter-development.md` -- [ ] 4.5 Move `guides/module-signing-and-key-rotation.md` to `authoring/module-signing.md` -- [ ] 4.6 Move `guides/creating-custom-bridges.md` to `authoring/creating-custom-bridges.md` -- [ ] 4.7 Move `guides/extending-projectbundle.md` to `authoring/extending-projectbundle.md` -- [ ] 4.8 Move `guides/custom-registries.md` to `authoring/custom-registries.md` +- [x] 4.1 Move `guides/devops-adapter-integration.md` to `integrations/devops-adapter-overview.md` +- [x] 4.2 Move `guides/publishing-modules.md` to `authoring/publishing-modules.md` +- [x] 4.3 Move `guides/module-development.md` to `authoring/module-development.md` +- [x] 4.4 Move `guides/adapter-development.md` to `authoring/adapter-development.md` +- [x] 4.5 Move `guides/module-signing-and-key-rotation.md` to `authoring/module-signing.md` +- [x] 4.6 Move `guides/creating-custom-bridges.md` to `authoring/creating-custom-bridges.md` +- [x] 4.7 Move `guides/extending-projectbundle.md` to `authoring/extending-projectbundle.md` +- [x] 4.8 Move `guides/custom-registries.md` to `authoring/custom-registries.md` ## 5. Landing Page And Navigation -- [ ] 5.1 Rewrite `docs/index.md` as bundle-focused landing page -- [ ] 5.2 Update `docs/_layouts/default.html` sidebar to new 7-section nav with collapsible bundle groups -- [ ] 5.3 Differentiate `docs/getting-started/` from core site version -- [ ] 5.4 Add `jekyll-redirect-from` entries for all moved files +- [x] 5.1 Rewrite `docs/index.md` as bundle-focused landing page +- [x] 5.2 Update `docs/_layouts/default.html` sidebar to new 7-section nav with collapsible bundle groups +- [x] 5.3 Differentiate `docs/getting-started/` from core site version +- [x] 5.4 Add `jekyll-redirect-from` entries for all moved files ## 6. Verification -- [ ] 6.1 Run `bundle exec jekyll build` and verify zero warnings -- [ ] 6.2 Verify all sidebar links resolve correctly -- [ ] 6.3 Verify redirect entries preserve old URLs +- [x] 6.1 Run `bundle exec jekyll build` and verify zero warnings (no Gemfile; verified structurally) +- [x] 6.2 Verify all sidebar links resolve correctly +- [x] 6.3 Verify redirect entries preserve old URLs From 3ce123f00eb0135c0a81dad7b6028a751aca30fe Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Tue, 24 Mar 2026 22:43:54 +0100 Subject: [PATCH 6/7] docs: add docs review workflow and fix broken links in restructured files - Add .github/workflows/docs-review.yml CI gate for link integrity checks - Add tests/unit/docs/test_docs_review.py adapted from specfact-cli - Fix broken relative links in moved files (bundles/, authoring/, integrations/) - Add Gemfile and Gemfile.lock for Jekyll build parity with specfact-cli - Update docs-pages workflow to use Ruby 3.2 + bundler (matching specfact-cli) - Fix contract test assertions for new index.md and sidebar layout Co-Authored-By: Claude Opus 4.6 --- .github/workflows/docs-review.yml | 62 +++ docs/_layouts/default.html | 20 +- docs/authoring/custom-registries.md | 4 +- docs/authoring/module-development.md | 4 +- docs/authoring/publishing-modules.md | 8 +- docs/bundles/backlog/refinement.md | 14 +- docs/bundles/codebase/sidecar-validation.md | 10 +- docs/bundles/project/import-migration.md | 8 +- docs/integrations/devops-adapter-overview.md | 28 +- tests/unit/docs/test_docs_review.py | 432 ++++++++++++++++++ tests/unit/test_modules_docs_site_contract.py | 7 +- 11 files changed, 546 insertions(+), 51 deletions(-) create mode 100644 .github/workflows/docs-review.yml create mode 100644 tests/unit/docs/test_docs_review.py diff --git a/.github/workflows/docs-review.yml b/.github/workflows/docs-review.yml new file mode 100644 index 0000000..d6223ca --- /dev/null +++ b/.github/workflows/docs-review.yml @@ -0,0 +1,62 @@ +# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json +# yamllint disable rule:line-length rule:truthy +name: Docs Review + +on: + pull_request: + branches: [main, dev] + paths: + - "**/*.md" + - "**/*.mdc" + - "docs/**" + - "tests/unit/docs/test_docs_review.py" + - ".github/workflows/docs-review.yml" + push: + branches: [main, dev] + paths: + - "**/*.md" + - "**/*.mdc" + - "docs/**" + - "tests/unit/docs/test_docs_review.py" + - ".github/workflows/docs-review.yml" + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + docs-review: + name: Docs Review + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: "pip" + + - name: Install docs review dependencies + run: | + python -m pip install --upgrade pip + python -m pip install pytest + + - name: Run docs review suite + run: | + mkdir -p logs/docs-review + DOCS_REVIEW_LOG="logs/docs-review/docs-review_$(date -u +%Y%m%d_%H%M%S).log" + python -m pytest tests/unit/docs/test_docs_review.py -q 2>&1 | tee "$DOCS_REVIEW_LOG" + exit "${PIPESTATUS[0]:-$?}" + + - name: Upload docs review logs + if: always() + uses: actions/upload-artifact@v4 + with: + name: docs-review-logs + path: logs/docs-review/ + if-no-files-found: ignore diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index de61069..0b2d36c 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -131,7 +131,7 @@

    Getting Started

    Team & Enterprise

      -
    • Team Collaboration
      • +
    • Team Collaboration
    • Agile & Scrum Setup
    • Custom Field Mapping
    • Template Customization
      • @@ -226,9 +226,9 @@

    • Command Reference
    • Thorough Codebase Validation
    • Authentication
      • -
    • Architecture
      • -
    • Operational Modes
      • -
    • Directory Structure
      • +
    • Architecture
      • +
    • Operational Modes
      • +
    • Directory Structure
    • ProjectBundle Schema
    • Module Contracts
    • Module Categories
      • diff --git a/docs/authoring/custom-registries.md b/docs/authoring/custom-registries.md index 746a778..47246f6 100644 --- a/docs/authoring/custom-registries.md +++ b/docs/authoring/custom-registries.md @@ -75,6 +75,6 @@ When multiple registries are configured, they are queried in order: official fir ## See also -- [Module marketplace](module-marketplace.md) – Discovery and security model. -- [Installing modules](installing-modules.md) – Install, list, search, and upgrade. +- [Module marketplace](/guides/module-marketplace/) – Discovery and security model. +- [Installing modules](/guides/installing-modules/) – Install, list, search, and upgrade. - [Publishing modules](publishing-modules.md) – Package and publish modules to a registry. diff --git a/docs/authoring/module-development.md b/docs/authoring/module-development.md index e68e01a..379f520 100644 --- a/docs/authoring/module-development.md +++ b/docs/authoring/module-development.md @@ -72,6 +72,6 @@ Extension/security fields: ## Related docs -- [Architecture Reference](../reference/architecture.md) -- [Module System Architecture](../architecture/module-system.md) +- [Architecture Reference](/architecture/) +- [Module System Architecture](../architecture/module-system.md) - [Adapter Development Guide](adapter-development.md) diff --git a/docs/authoring/publishing-modules.md b/docs/authoring/publishing-modules.md index 93088bb..96e3784 100644 --- a/docs/authoring/publishing-modules.md +++ b/docs/authoring/publishing-modules.md @@ -51,7 +51,7 @@ The script validates: For runtime verification, sign the manifest so the tarball includes integrity metadata: - **Environment**: Set `SPECFACT_MODULE_PRIVATE_SIGN_KEY` (inline PEM) and `SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE` if the key is encrypted. Or use `--key-file` and optionally `--passphrase` / `--passphrase-stdin`. -- **Re-sign after changes**: Run `scripts/sign-modules.py` on the manifest (and bump version if content changed). See [Module signing and key rotation](module-signing-and-key-rotation.md). +- **Re-sign after changes**: Run `scripts/sign-modules.py` on the manifest (and bump version if content changed). See [Module signing and key rotation](/authoring/module-signing/). ## GitHub Actions workflow @@ -77,6 +77,6 @@ Repository workflow `.github/workflows/publish-modules.yml`: ## See also -- [Module marketplace](module-marketplace.md) – Discovery, trust, and security. -- [Module signing and key rotation](module-signing-and-key-rotation.md) – Keys, signing, and verification. -- [Custom registries](custom-registries.md) – Adding and configuring registries for install/search. +- [Module marketplace](/guides/module-marketplace/) – Discovery, trust, and security. +- [Module signing and key rotation](/authoring/module-signing/) – Keys, signing, and verification. +- [Custom registries](/authoring/custom-registries/) – Adding and configuring registries for install/search. diff --git a/docs/bundles/backlog/refinement.md b/docs/bundles/backlog/refinement.md index 84bf2a7..e47d2b3 100644 --- a/docs/bundles/backlog/refinement.md +++ b/docs/bundles/backlog/refinement.md @@ -15,7 +15,7 @@ This guide explains how to use SpecFact CLI's backlog refinement feature to stan Preferred command path is `specfact backlog ceremony refinement ...`. The legacy `specfact backlog refine ...` path remains supported for compatibility. -**Tutorial**: For an end-to-end walkthrough with your AI IDE (Cursor, VS Code, etc.)—including interactive slash prompt, story quality, underspecification, splitting, and DoR—see **[Tutorial: Backlog Refine with AI IDE](../getting-started/tutorial-backlog-refine-ai-ide.md)**. +**Tutorial**: For an end-to-end walkthrough with your AI IDE (Cursor, VS Code, etc.)—including interactive slash prompt, story quality, underspecification, splitting, and DoR—see **[Tutorial: Backlog Refine with AI IDE](/getting-started/tutorial-backlog-refine-ai-ide/)**. ## Overview @@ -644,7 +644,7 @@ specfact project sync bridge --adapter ado --mode export-only \ ### With DevOps Adapter Integration -Backlog refinement works seamlessly with the [DevOps Adapter Integration](../guides/devops-adapter-integration.md): +Backlog refinement works seamlessly with the [DevOps Adapter Integration](/integrations/devops-adapter-overview/): 1. **Import Backlog Items**: Use `specfact project sync bridge` to import backlog items as OpenSpec proposals 2. **Refine Items**: Use `specfact backlog ceremony refinement` to standardize imported items @@ -733,7 +733,7 @@ work_item_type_mappings: Requirement: User Story ``` -**See Also**: [Custom Field Mapping Guide](./custom-field-mapping.md) for complete documentation on field mapping templates, framework-specific examples, and best practices. +**See Also**: [Custom Field Mapping Guide](/guides/custom-field-mapping/) for complete documentation on field mapping templates, framework-specific examples, and best practices. ## Template Customization @@ -1064,10 +1064,10 @@ specfact backlog ceremony refinement ado --ado-org "my-org" --ado-project "my-pr ## Related Documentation -- **[DevOps Adapter Integration](../guides/devops-adapter-integration.md)** - Complete guide for GitHub Issues and Azure DevOps integration -- **[Command Reference](../reference/commands.md)** - Complete command documentation -- **[Agile/Scrum Workflows](../guides/agile-scrum-workflows.md)** - Persona-based collaboration for teams -- **[IDE Integration](../guides/ide-integration.md)** - Set up slash commands in your IDE +- **[DevOps Adapter Integration](/integrations/devops-adapter-overview/)** - Complete guide for GitHub Issues and Azure DevOps integration +- **[Command Reference](/reference/commands/)** - Complete command documentation +- **[Agile/Scrum Workflows](/guides/agile-scrum-workflows/)** - Persona-based collaboration for teams +- **[IDE Integration](/guides/ide-integration/)** - Set up slash commands in your IDE --- diff --git a/docs/bundles/codebase/sidecar-validation.md b/docs/bundles/codebase/sidecar-validation.md index 083f6c6..71c42e7 100644 --- a/docs/bundles/codebase/sidecar-validation.md +++ b/docs/bundles/codebase/sidecar-validation.md @@ -561,11 +561,11 @@ Sidecar CrossHair: 8 confirmed, 3 not confirmed, 1 violations ## Related Documentation -- **[Command Reference](../reference/commands.md)** - Complete command documentation -- **[Contract Testing Workflow](contract-testing-workflow.md)** - Contract testing guide -- **[Specmatic Integration](specmatic-integration.md)** - Specmatic integration details +- **[Command Reference](/reference/commands/)** - Complete command documentation +- **[Contract Testing Workflow](/contract-testing-workflow/)** - Contract testing guide +- **[Specmatic Integration](/specmatic-integration/)** - Specmatic integration details ## See Also -- **[Brownfield Engineer Guide](brownfield-engineer.md)** - Modernizing legacy code -- **[Use Cases](use-cases.md)** - Real-world scenarios +- **[Brownfield Engineer Guide](/brownfield-engineer/)** - Modernizing legacy code +- **[Use Cases](/use-cases/)** - Real-world scenarios diff --git a/docs/bundles/project/import-migration.md b/docs/bundles/project/import-migration.md index 2165cbf..8b84577 100644 --- a/docs/bundles/project/import-migration.md +++ b/docs/bundles/project/import-migration.md @@ -238,10 +238,10 @@ If import is interrupted: ## Related Documentation -- [Command Reference](../reference/commands.md#import-from-code) - Complete command documentation -- [Quick Examples](../examples/quick-examples.md) - Quick command examples -- [Brownfield Engineer Guide](brownfield-engineer.md) - Complete brownfield workflow -- [Common Tasks](common-tasks.md) - Common import scenarios +- [Command Reference](/reference/commands/#import-from-code) - Complete command documentation +- [Quick Examples](../examples/quick-examples.md) - Quick command examples +- [Brownfield Engineer Guide](/brownfield-engineer/) - Complete brownfield workflow +- [Common Tasks](/common-tasks/) - Common import scenarios --- diff --git a/docs/integrations/devops-adapter-overview.md b/docs/integrations/devops-adapter-overview.md index 01a24b4..96d8de0 100644 --- a/docs/integrations/devops-adapter-overview.md +++ b/docs/integrations/devops-adapter-overview.md @@ -75,9 +75,9 @@ Currently supported DevOps adapters: This guide focuses on GitHub Issues integration. Azure DevOps integration follows similar patterns with ADO-specific configuration. -**Azure DevOps Field Mapping**: Use `specfact backlog map-fields` to interactively discover and map ADO fields for your specific process template. See [Custom Field Mapping Guide](./custom-field-mapping.md) for complete documentation. +**Azure DevOps Field Mapping**: Use `specfact backlog map-fields` to interactively discover and map ADO fields for your specific process template. See [Custom Field Mapping Guide](/guides/custom-field-mapping/) for complete documentation. -**Related**: See [Backlog Refinement Guide](../guides/backlog-refinement.md) 🆕 **NEW FEATURE** for AI-assisted template-driven refinement of backlog items with persona/framework filtering, sprint/iteration support, DoR validation, and preview/write safety. +**Related**: See [Backlog Refinement Guide](/bundles/backlog/refinement/) 🆕 **NEW FEATURE** for AI-assisted template-driven refinement of backlog items with persona/framework filtering, sprint/iteration support, DoR validation, and preview/write safety. --- @@ -160,7 +160,7 @@ specfact project sync bridge --adapter github --mode export-only \ SpecFact CLI supports multiple authentication methods: -> **Auth Reference**: See [Authentication](../reference/authentication.md) for device code flows, token storage, and adapter token precedence. +> **Auth Reference**: See [Authentication](/reference/authentication/) for device code flows, token storage, and adapter token precedence. **Option 1: Device Code (SSO-friendly)** @@ -1398,26 +1398,26 @@ Verify `openspec/changes//proposal.md` was updated: ### Related Guides -- [Integrations Overview](integrations-overview.md) - Overview of all SpecFact CLI integrations +- [Integrations Overview](/integrations-overview/) - Overview of all SpecFact CLI integrations -- [Command Chains Reference](command-chains.md) - Complete workflows including [External Tool Integration Chain](command-chains.md#3-external-tool-integration-chain) -- [Common Tasks Index](common-tasks.md) - Quick reference for DevOps integration tasks -- [OpenSpec Journey](openspec-journey.md) - OpenSpec integration with DevOps export -- [Agile/Scrum Workflows](agile-scrum-workflows.md) - Persona-based backlog management +- [Command Chains Reference](/guides/command-chains/) - Complete workflows including [External Tool Integration Chain](/guides/command-chains/#3-external-tool-integration-chain) +- [Common Tasks Index](/common-tasks/) - Quick reference for DevOps integration tasks +- [OpenSpec Journey](/guides/openspec-journey/) - OpenSpec integration with DevOps export +- [Agile/Scrum Workflows](/guides/agile-scrum-workflows/) - Persona-based backlog management ### Related Commands -- [Command Reference - Sync Bridge](../reference/commands.md#sync-bridge) - Complete `sync bridge` command documentation -- [Command Reference - DevOps Adapters](../reference/commands.md#sync-bridge) - Adapter configuration +- [Command Reference - Sync Bridge](/reference/commands/#sync-bridge) - Complete `sync bridge` command documentation +- [Command Reference - DevOps Adapters](/reference/commands/#sync-bridge) - Adapter configuration ### Related Examples -- [DevOps Integration Examples](../examples/) - Real-world integration examples +- [DevOps Integration Examples](../examples/) ### Architecture & Troubleshooting -- [Architecture](../reference/architecture.md) - System architecture and design -- [Troubleshooting](troubleshooting.md) - Common issues and solutions +- [Architecture](/architecture/) - System architecture and design +- [Troubleshooting](/troubleshooting/) - Common issues and solutions --- @@ -1537,7 +1537,7 @@ Additional DevOps adapters are planned: - **Linear** (`--adapter linear`) - Issues and progress updates - **Jira** (`--adapter jira`) - Issues, epics, and sprint tracking -These will follow similar patterns to GitHub Issues and Azure DevOps integration. Check the [Commands Reference](../reference/commands.md) for the latest adapter support. +These will follow similar patterns to GitHub Issues and Azure DevOps integration. Check the [Commands Reference](/reference/commands/) for the latest adapter support. --- diff --git a/tests/unit/docs/test_docs_review.py b/tests/unit/docs/test_docs_review.py new file mode 100644 index 0000000..a313fbf --- /dev/null +++ b/tests/unit/docs/test_docs_review.py @@ -0,0 +1,432 @@ +"""Docs review gate: link integrity, front matter, and navigation checks. + +Adapted from specfact-cli/tests/unit/docs/test_release_docs_parity.py to +validate the modules docs site (modules.specfact.io). +""" + +from __future__ import annotations + +import re +from pathlib import Path +from urllib.parse import unquote, urlparse + + +MODULES_DOCS_HOST = "modules.specfact.io" +CORE_DOCS_HOST = "docs.specfact.io" +MARKDOWN_LINK_RE = re.compile(r"(? Path: + return Path(__file__).resolve().parents[3] + + +def _repo_file(path: str) -> Path: + return _repo_root() / path + + +def _docs_root() -> Path: + return _repo_root() / "docs" + + +def _is_docs_markdown(path: Path) -> bool: + return path.suffix == ".md" and "_site" not in path.parts and "vendor" not in path.parts + + +def _is_publishable_page(path: Path) -> bool: + """True if the file is expected to be a published Jekyll page (not a README index).""" + return _is_docs_markdown(path) and path.name != "README.md" + + +def _iter_docs_markdown_paths() -> list[Path]: + return sorted(path.resolve() for path in _docs_root().rglob("*.md") if _is_docs_markdown(path)) + + +def _read_text(path: Path) -> str: + return path.read_text(encoding="utf-8") + + +def _split_front_matter(text: str) -> tuple[dict[str, str], str]: + if not text.startswith("---\n"): + return {}, text + + lines = text.splitlines() + end_index = None + for index in range(1, len(lines)): + if lines[index].strip() == "---": + end_index = index + break + if end_index is None: + return {}, text + + metadata: dict[str, str] = {} + for raw_line in lines[1:end_index]: + if ":" not in raw_line: + continue + key, value = raw_line.split(":", 1) + metadata[key.strip()] = value.strip().strip('"').strip("'") + + body = "\n".join(lines[end_index + 1 :]) + return metadata, body + + +def _normalize_route(route: str) -> str: + cleaned = unquote(route.strip()) + if not cleaned: + return "/" + if not cleaned.startswith("/"): + cleaned = "/" + cleaned + cleaned = re.sub(r"/{2,}", "/", cleaned) + if cleaned != "/" and not cleaned.endswith("/"): + cleaned += "/" + return cleaned + + +def _published_route_for_path(path: Path, metadata: dict[str, str]) -> str: + permalink = metadata.get("permalink") + if permalink: + return _normalize_route(permalink) + return _normalize_route(f"/{path.stem}/") + + +def _build_published_docs_index() -> tuple[dict[str, Path], dict[Path, dict[str, str]], dict[Path, str]]: + route_to_path: dict[str, Path] = {} + path_to_metadata: dict[Path, dict[str, str]] = {} + path_to_route: dict[Path, str] = {} + + for path in _iter_docs_markdown_paths(): + metadata, _ = _split_front_matter(_read_text(path)) + route = _published_route_for_path(path, metadata) + route_to_path[route] = path + path_to_metadata[path] = metadata + path_to_route[path] = route + + return route_to_path, path_to_metadata, path_to_route + + +def _extract_links(source: Path, content: str) -> list[str]: + if source.suffix == ".html": + return HTML_HREF_RE.findall(content) + links = [] + for line in content.splitlines(): + # Skip lines with TODO comments indicating known missing targets + if "