From bee469a5720886a2287d5a36c69df903a2bc9244 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Sun, 5 Apr 2026 22:41:01 +0200 Subject: [PATCH 1/2] Archive implemented specs --- openspec/CHANGE_ORDER.md | 52 +++---------- .../.openspec.yaml | 0 .../CHANGE_VALIDATION.md | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/clean-code-analysis/spec.md | 0 .../specs/clean-code-policy-pack/spec.md | 0 .../specs/house-rules-skill/spec.md | 0 .../specs/radon-runner/spec.md | 2 +- .../specs/review-cli-contracts/spec.md | 2 +- .../specs/review-run-command/spec.md | 2 +- .../tasks.md | 4 +- .../CHANGE_VALIDATION.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/modules-bundle-nav/spec.md | 24 ++++++ .../specs/modules-progressive-tiers/spec.md | 23 ++++++ .../tasks.md | 0 .../CHANGE_VALIDATION.md | 0 .../TDD_EVIDENCE.md | 0 .../proposal.md | 0 .../specs/bundle-overview-pages/spec.md | 2 +- .../tasks.md | 0 .../CHANGE_VALIDATION.md | 0 .../TDD_EVIDENCE.md | 0 .../proposal.md | 0 .../specs/missing-command-docs/spec.md | 2 +- .../tasks.md | 0 .../CHANGE_VALIDATION.md | 0 .../TDD_EVIDENCE.md | 0 .../proposal.md | 0 .../specs/cross-module-workflow-docs/spec.md | 2 +- .../specs/daily-devops-routine-docs/spec.md | 2 +- .../tasks.md | 0 .../CHANGE_VALIDATION.md | 0 .../TDD_EVIDENCE.md | 0 .../proposal.md | 0 .../specs/enterprise-config-docs/spec.md | 2 +- .../specs/team-setup-docs/spec.md | 2 +- .../tasks.md | 0 .../CHANGE_VALIDATION.md | 0 .../TDD_EVIDENCE.md | 0 .../proposal.md | 0 .../modules-docs-command-validation/spec.md | 2 +- .../tasks.md | 0 .../.openspec.yaml | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/bundle-overview-pages/spec.md | 0 .../specs/cross-module-workflow-docs/spec.md | 0 .../specs/docs-client-search/spec.md | 0 .../specs/docs-nav-data-driven/spec.md | 0 .../specs/docs-role-expertise-nav/spec.md | 0 .../specs/docs-theme-toggle/spec.md | 0 .../modules-docs-command-validation/spec.md | 2 + .../specs/team-setup-docs/spec.md | 0 .../tasks.md | 8 +- .../.openspec.yaml | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/module-bundle-dependencies/spec.md | 0 .../tasks.md | 2 +- .../.openspec.yaml | 0 .../CHANGE_VALIDATION.md | 0 .../RESOURCE_OWNERSHIP_AUDIT.md | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/bundle-packaged-resources/spec.md | 0 .../specs/resource-aware-integrity/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../CHANGE_VALIDATION.md | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/backlog-sync/spec.md | 2 +- .../speckit-backlog-extension-sync/spec.md | 0 .../speckit-change-proposal-bridge/spec.md | 0 .../tasks.md | 6 +- .../specs/modules-bundle-nav/spec.md | 24 ------ .../specs/modules-progressive-tiers/spec.md | 23 ------ openspec/specs/backlog-sync/spec.md | 21 +++++ openspec/specs/bundle-overview-pages/spec.md | 13 +++- .../specs/bundle-packaged-resources/spec.md | 33 ++++++++ openspec/specs/clean-code-analysis/spec.md | 20 +++++ openspec/specs/clean-code-policy-pack/spec.md | 20 +++++ .../specs/cross-module-workflow-docs/spec.md | 15 +++- .../specs/daily-devops-routine-docs/spec.md | 7 +- openspec/specs/docs-client-search/spec.md | 60 +++++++++++++++ openspec/specs/docs-nav-data-driven/spec.md | 76 +++++++++++++++++++ .../specs/docs-role-expertise-nav/spec.md | 58 ++++++++++++++ openspec/specs/docs-theme-toggle/spec.md | 53 +++++++++++++ openspec/specs/enterprise-config-docs/spec.md | 9 ++- openspec/specs/house-rules-skill/spec.md | 20 +++++ openspec/specs/missing-command-docs/spec.md | 11 +-- .../specs/module-bundle-dependencies/spec.md | 32 ++++++++ openspec/specs/modules-bundle-nav/spec.md | 28 +++++++ .../modules-docs-command-validation/spec.md | 23 +++++- .../specs/modules-progressive-tiers/spec.md | 27 +++++++ openspec/specs/radon-runner/spec.md | 15 ++++ .../specs/resource-aware-integrity/spec.md | 39 ++++++++++ openspec/specs/review-cli-contracts/spec.md | 15 ++++ openspec/specs/review-run-command/spec.md | 15 ++++ .../speckit-backlog-extension-sync/spec.md | 58 ++++++++++++++ .../speckit-change-proposal-bridge/spec.md | 74 ++++++++++++++++++ openspec/specs/team-setup-docs/spec.md | 20 ++++- 110 files changed, 825 insertions(+), 127 deletions(-) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/.openspec.yaml (100%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/CHANGE_VALIDATION.md (100%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/TDD_EVIDENCE.md (100%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/design.md (100%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/proposal.md (100%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/specs/clean-code-analysis/spec.md (100%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/specs/clean-code-policy-pack/spec.md (100%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/specs/house-rules-skill/spec.md (100%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/specs/radon-runner/spec.md (97%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/specs/review-cli-contracts/spec.md (97%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/specs/review-run-command/spec.md (97%) rename openspec/changes/{clean-code-02-expanded-review-module => archive/2026-04-05-clean-code-02-expanded-review-module}/tasks.md (92%) rename openspec/changes/{docs-06-modules-site-ia-restructure => archive/2026-04-05-docs-06-modules-site-ia-restructure}/CHANGE_VALIDATION.md (100%) rename openspec/changes/{docs-06-modules-site-ia-restructure => archive/2026-04-05-docs-06-modules-site-ia-restructure}/design.md (100%) rename openspec/changes/{docs-06-modules-site-ia-restructure => archive/2026-04-05-docs-06-modules-site-ia-restructure}/proposal.md (100%) create mode 100644 openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/specs/modules-bundle-nav/spec.md create mode 100644 openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/specs/modules-progressive-tiers/spec.md rename openspec/changes/{docs-06-modules-site-ia-restructure => archive/2026-04-05-docs-06-modules-site-ia-restructure}/tasks.md (100%) rename openspec/changes/{docs-08-bundle-overview-pages => archive/2026-04-05-docs-08-bundle-overview-pages}/CHANGE_VALIDATION.md (100%) rename openspec/changes/{docs-08-bundle-overview-pages => archive/2026-04-05-docs-08-bundle-overview-pages}/TDD_EVIDENCE.md (100%) rename openspec/changes/{docs-08-bundle-overview-pages => archive/2026-04-05-docs-08-bundle-overview-pages}/proposal.md (100%) rename openspec/changes/{docs-08-bundle-overview-pages => archive/2026-04-05-docs-08-bundle-overview-pages}/specs/bundle-overview-pages/spec.md (98%) rename openspec/changes/{docs-08-bundle-overview-pages => archive/2026-04-05-docs-08-bundle-overview-pages}/tasks.md (100%) rename openspec/changes/{docs-09-missing-command-docs => archive/2026-04-05-docs-09-missing-command-docs}/CHANGE_VALIDATION.md (100%) rename openspec/changes/{docs-09-missing-command-docs => archive/2026-04-05-docs-09-missing-command-docs}/TDD_EVIDENCE.md (100%) rename openspec/changes/{docs-09-missing-command-docs => archive/2026-04-05-docs-09-missing-command-docs}/proposal.md (100%) rename openspec/changes/{docs-09-missing-command-docs => archive/2026-04-05-docs-09-missing-command-docs}/specs/missing-command-docs/spec.md (98%) rename openspec/changes/{docs-09-missing-command-docs => archive/2026-04-05-docs-09-missing-command-docs}/tasks.md (100%) rename openspec/changes/{docs-10-workflow-consolidation => archive/2026-04-05-docs-10-workflow-consolidation}/CHANGE_VALIDATION.md (100%) rename openspec/changes/{docs-10-workflow-consolidation => archive/2026-04-05-docs-10-workflow-consolidation}/TDD_EVIDENCE.md (100%) rename openspec/changes/{docs-10-workflow-consolidation => archive/2026-04-05-docs-10-workflow-consolidation}/proposal.md (100%) rename openspec/changes/{docs-10-workflow-consolidation => archive/2026-04-05-docs-10-workflow-consolidation}/specs/cross-module-workflow-docs/spec.md (98%) rename openspec/changes/{docs-10-workflow-consolidation => archive/2026-04-05-docs-10-workflow-consolidation}/specs/daily-devops-routine-docs/spec.md (95%) rename openspec/changes/{docs-10-workflow-consolidation => archive/2026-04-05-docs-10-workflow-consolidation}/tasks.md (100%) rename openspec/changes/{docs-11-team-enterprise-tier => archive/2026-04-05-docs-11-team-enterprise-tier}/CHANGE_VALIDATION.md (100%) rename openspec/changes/{docs-11-team-enterprise-tier => archive/2026-04-05-docs-11-team-enterprise-tier}/TDD_EVIDENCE.md (100%) rename openspec/changes/{docs-11-team-enterprise-tier => archive/2026-04-05-docs-11-team-enterprise-tier}/proposal.md (100%) rename openspec/changes/{docs-11-team-enterprise-tier => archive/2026-04-05-docs-11-team-enterprise-tier}/specs/enterprise-config-docs/spec.md (96%) rename openspec/changes/{docs-11-team-enterprise-tier => archive/2026-04-05-docs-11-team-enterprise-tier}/specs/team-setup-docs/spec.md (97%) rename openspec/changes/{docs-11-team-enterprise-tier => archive/2026-04-05-docs-11-team-enterprise-tier}/tasks.md (100%) rename openspec/changes/{docs-12-docs-validation-ci => archive/2026-04-05-docs-12-docs-validation-ci}/CHANGE_VALIDATION.md (100%) rename openspec/changes/{docs-12-docs-validation-ci => archive/2026-04-05-docs-12-docs-validation-ci}/TDD_EVIDENCE.md (100%) rename openspec/changes/{docs-12-docs-validation-ci => archive/2026-04-05-docs-12-docs-validation-ci}/proposal.md (100%) rename openspec/changes/{docs-12-docs-validation-ci => archive/2026-04-05-docs-12-docs-validation-ci}/specs/modules-docs-command-validation/spec.md (98%) rename openspec/changes/{docs-12-docs-validation-ci => archive/2026-04-05-docs-12-docs-validation-ci}/tasks.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/.openspec.yaml (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/TDD_EVIDENCE.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/design.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/proposal.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/specs/bundle-overview-pages/spec.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/specs/cross-module-workflow-docs/spec.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/specs/docs-client-search/spec.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/specs/docs-nav-data-driven/spec.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/specs/docs-role-expertise-nav/spec.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/specs/docs-theme-toggle/spec.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/specs/modules-docs-command-validation/spec.md (99%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/specs/team-setup-docs/spec.md (100%) rename openspec/changes/{docs-13-nav-search-theme-roles => archive/2026-04-05-docs-13-nav-search-theme-roles}/tasks.md (94%) rename openspec/changes/{module-bundle-deps-auto-install => archive/2026-04-05-module-bundle-deps-auto-install}/.openspec.yaml (100%) rename openspec/changes/{module-bundle-deps-auto-install => archive/2026-04-05-module-bundle-deps-auto-install}/TDD_EVIDENCE.md (100%) rename openspec/changes/{module-bundle-deps-auto-install => archive/2026-04-05-module-bundle-deps-auto-install}/design.md (100%) rename openspec/changes/{module-bundle-deps-auto-install => archive/2026-04-05-module-bundle-deps-auto-install}/proposal.md (100%) rename openspec/changes/{module-bundle-deps-auto-install => archive/2026-04-05-module-bundle-deps-auto-install}/specs/module-bundle-dependencies/spec.md (100%) rename openspec/changes/{module-bundle-deps-auto-install => archive/2026-04-05-module-bundle-deps-auto-install}/tasks.md (97%) rename openspec/changes/{packaging-01-bundle-resource-payloads => archive/2026-04-05-packaging-01-bundle-resource-payloads}/.openspec.yaml (100%) rename openspec/changes/{packaging-01-bundle-resource-payloads => archive/2026-04-05-packaging-01-bundle-resource-payloads}/CHANGE_VALIDATION.md (100%) rename openspec/changes/{packaging-01-bundle-resource-payloads => archive/2026-04-05-packaging-01-bundle-resource-payloads}/RESOURCE_OWNERSHIP_AUDIT.md (100%) rename openspec/changes/{packaging-01-bundle-resource-payloads => archive/2026-04-05-packaging-01-bundle-resource-payloads}/TDD_EVIDENCE.md (100%) rename openspec/changes/{packaging-01-bundle-resource-payloads => archive/2026-04-05-packaging-01-bundle-resource-payloads}/design.md (100%) rename openspec/changes/{packaging-01-bundle-resource-payloads => archive/2026-04-05-packaging-01-bundle-resource-payloads}/proposal.md (100%) rename openspec/changes/{packaging-01-bundle-resource-payloads => archive/2026-04-05-packaging-01-bundle-resource-payloads}/specs/bundle-packaged-resources/spec.md (100%) rename openspec/changes/{packaging-01-bundle-resource-payloads => archive/2026-04-05-packaging-01-bundle-resource-payloads}/specs/resource-aware-integrity/spec.md (100%) rename openspec/changes/{packaging-01-bundle-resource-payloads => archive/2026-04-05-packaging-01-bundle-resource-payloads}/tasks.md (100%) rename openspec/changes/{speckit-03-change-proposal-bridge => archive/2026-04-05-speckit-03-change-proposal-bridge}/.openspec.yaml (100%) rename openspec/changes/{speckit-03-change-proposal-bridge => archive/2026-04-05-speckit-03-change-proposal-bridge}/CHANGE_VALIDATION.md (100%) rename openspec/changes/{speckit-03-change-proposal-bridge => archive/2026-04-05-speckit-03-change-proposal-bridge}/TDD_EVIDENCE.md (100%) rename openspec/changes/{speckit-03-change-proposal-bridge => archive/2026-04-05-speckit-03-change-proposal-bridge}/design.md (100%) rename openspec/changes/{speckit-03-change-proposal-bridge => archive/2026-04-05-speckit-03-change-proposal-bridge}/proposal.md (100%) rename openspec/changes/{speckit-03-change-proposal-bridge => archive/2026-04-05-speckit-03-change-proposal-bridge}/specs/backlog-sync/spec.md (97%) rename openspec/changes/{speckit-03-change-proposal-bridge => archive/2026-04-05-speckit-03-change-proposal-bridge}/specs/speckit-backlog-extension-sync/spec.md (100%) rename openspec/changes/{speckit-03-change-proposal-bridge => archive/2026-04-05-speckit-03-change-proposal-bridge}/specs/speckit-change-proposal-bridge/spec.md (100%) rename openspec/changes/{speckit-03-change-proposal-bridge => archive/2026-04-05-speckit-03-change-proposal-bridge}/tasks.md (96%) delete mode 100644 openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-bundle-nav/spec.md delete mode 100644 openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-progressive-tiers/spec.md create mode 100644 openspec/specs/bundle-packaged-resources/spec.md create mode 100644 openspec/specs/clean-code-analysis/spec.md create mode 100644 openspec/specs/clean-code-policy-pack/spec.md create mode 100644 openspec/specs/docs-client-search/spec.md create mode 100644 openspec/specs/docs-nav-data-driven/spec.md create mode 100644 openspec/specs/docs-role-expertise-nav/spec.md create mode 100644 openspec/specs/docs-theme-toggle/spec.md create mode 100644 openspec/specs/house-rules-skill/spec.md create mode 100644 openspec/specs/module-bundle-dependencies/spec.md create mode 100644 openspec/specs/modules-bundle-nav/spec.md create mode 100644 openspec/specs/modules-progressive-tiers/spec.md create mode 100644 openspec/specs/resource-aware-integrity/spec.md create mode 100644 openspec/specs/speckit-backlog-extension-sync/spec.md create mode 100644 openspec/specs/speckit-change-proposal-bridge/spec.md diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index d393068..9edcd82 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -21,57 +21,29 @@ | ✅ 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`. +| ✅ docs-06-modules-site-ia-restructure | archived 2026-04-05 | +| ✅ docs-08-bundle-overview-pages | archived 2026-04-05 | +| ✅ docs-09-missing-command-docs | archived 2026-04-05 | +| ✅ docs-10-workflow-consolidation | archived 2026-04-05 | +| ✅ docs-11-team-enterprise-tier | archived 2026-04-05 | +| ✅ docs-12-docs-validation-ci | archived 2026-04-05 | +| ✅ clean-code-02-expanded-review-module | archived 2026-04-05 | +| ✅ docs-13-nav-search-theme-roles | archived 2026-04-05 | +| ✅ speckit-03-change-proposal-bridge | archived 2026-04-05 | ## Pending -### Packaging and bundle payloads - -| Module | Order | Change folder | GitHub # | Blocked by | -|--------|-------|---------------|----------|------------| -| packaging | 01 | packaging-01-bundle-resource-payloads | [#101](https://github.com/nold-ai/specfact-cli-modules/issues/101) | specfact-cli/packaging-02-cross-platform-runtime-and-module-resources defines the consuming installed-resource contract; specfact-cli/init-ide-prompt-source-selection ([#382](https://github.com/nold-ai/specfact-cli/issues/382)) owns runtime selection/export orchestration | - -### 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 ✅ | - -## 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 ✅ — implemented, pending archive (§7 URL contract) | -| 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 | -| docs | 13 | docs-13-nav-search-theme-roles | [#123](https://github.com/nold-ai/specfact-cli-modules/issues/123) | docs-06 through docs-12 (fixes navigation gaps left by prior changes; adds search, theme toggle, and role-based navigation) | -| docs | 14 | docs-14-module-release-history | [#124](https://github.com/nold-ai/specfact-cli-modules/issues/124) | docs-13-nav-search-theme-roles; publish-modules workflow (adds publish-driven module release history, AI-assisted backfill for already-published versions, and docs rendering of shipped features/improvements) | - -### Spec-Kit v0.4.x change proposal bridge (spec-kit integration review, 2026-03-27) +| docs | 14 | docs-14-module-release-history | [#124](https://github.com/nold-ai/specfact-cli-modules/issues/124) | docs-13 ✅; publish-modules workflow | -Adds bidirectional conversion between spec-kit feature folders and OpenSpec change proposals, plus backlog extension issue mapping detection to prevent duplicate issue creation. +### Packaging and bundle payloads | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| speckit | 03 | speckit-03-change-proposal-bridge | [#116](https://github.com/nold-ai/specfact-cli-modules/issues/116) | specfact-cli/speckit-02-v04-adapter-alignment ([specfact-cli#453](https://github.com/nold-ai/specfact-cli/issues/453)) | - -**Cross-repo dependency**: Requires `speckit-02-v04-adapter-alignment` in `nold-ai/specfact-cli` to be implemented first (provides `ToolCapabilities.extension_commands` consumed by `SpecKitBacklogSync`). +| packaging | 01 | packaging-01-bundle-resource-payloads | [#101](https://github.com/nold-ai/specfact-cli-modules/issues/101) | specfact-cli/packaging-02-cross-platform-runtime-and-module-resources; specfact-cli/init-ide-prompt-source-selection ([#382](https://github.com/nold-ai/specfact-cli/issues/382)) | ### Module bundle peer dependencies diff --git a/openspec/changes/clean-code-02-expanded-review-module/.openspec.yaml b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/.openspec.yaml similarity index 100% rename from openspec/changes/clean-code-02-expanded-review-module/.openspec.yaml rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/.openspec.yaml diff --git a/openspec/changes/clean-code-02-expanded-review-module/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/clean-code-02-expanded-review-module/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/CHANGE_VALIDATION.md diff --git a/openspec/changes/clean-code-02-expanded-review-module/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/clean-code-02-expanded-review-module/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/TDD_EVIDENCE.md diff --git a/openspec/changes/clean-code-02-expanded-review-module/design.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/design.md similarity index 100% rename from openspec/changes/clean-code-02-expanded-review-module/design.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/design.md diff --git a/openspec/changes/clean-code-02-expanded-review-module/proposal.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/proposal.md similarity index 100% rename from openspec/changes/clean-code-02-expanded-review-module/proposal.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/proposal.md diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-analysis/spec.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/clean-code-analysis/spec.md similarity index 100% rename from openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-analysis/spec.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/clean-code-analysis/spec.md diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-policy-pack/spec.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/clean-code-policy-pack/spec.md similarity index 100% rename from openspec/changes/clean-code-02-expanded-review-module/specs/clean-code-policy-pack/spec.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/clean-code-policy-pack/spec.md diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/house-rules-skill/spec.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/house-rules-skill/spec.md similarity index 100% rename from openspec/changes/clean-code-02-expanded-review-module/specs/house-rules-skill/spec.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/house-rules-skill/spec.md diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/radon-runner/spec.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/radon-runner/spec.md similarity index 97% rename from openspec/changes/clean-code-02-expanded-review-module/specs/radon-runner/spec.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/radon-runner/spec.md index 4534db1..e66c3f0 100644 --- a/openspec/changes/clean-code-02-expanded-review-module/specs/radon-runner/spec.md +++ b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/radon-runner/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED 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. diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/review-cli-contracts/spec.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/review-cli-contracts/spec.md similarity index 97% rename from openspec/changes/clean-code-02-expanded-review-module/specs/review-cli-contracts/spec.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/review-cli-contracts/spec.md index 89fed47..28d4236 100644 --- a/openspec/changes/clean-code-02-expanded-review-module/specs/review-cli-contracts/spec.md +++ b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/review-cli-contracts/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED 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. diff --git a/openspec/changes/clean-code-02-expanded-review-module/specs/review-run-command/spec.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/review-run-command/spec.md similarity index 97% rename from openspec/changes/clean-code-02-expanded-review-module/specs/review-run-command/spec.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/review-run-command/spec.md index 6e34686..5670990 100644 --- a/openspec/changes/clean-code-02-expanded-review-module/specs/review-run-command/spec.md +++ b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/specs/review-run-command/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED 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. diff --git a/openspec/changes/clean-code-02-expanded-review-module/tasks.md b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/tasks.md similarity index 92% rename from openspec/changes/clean-code-02-expanded-review-module/tasks.md rename to openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/tasks.md index 87574bf..3dc6ef4 100644 --- a/openspec/changes/clean-code-02-expanded-review-module/tasks.md +++ b/openspec/changes/archive/2026-04-05-clean-code-02-expanded-review-module/tasks.md @@ -26,5 +26,5 @@ ## 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. +- [x] 5.1 Update `openspec/CHANGE_ORDER.md` dependency notes if sequencing changes again. +- [x] 5.2 Open a PR from `feature/clean-code-02-expanded-review-module` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/docs-06-modules-site-ia-restructure/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/docs-06-modules-site-ia-restructure/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/CHANGE_VALIDATION.md diff --git a/openspec/changes/docs-06-modules-site-ia-restructure/design.md b/openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/design.md similarity index 100% rename from openspec/changes/docs-06-modules-site-ia-restructure/design.md rename to openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/design.md diff --git a/openspec/changes/docs-06-modules-site-ia-restructure/proposal.md b/openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/proposal.md similarity index 100% rename from openspec/changes/docs-06-modules-site-ia-restructure/proposal.md rename to openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/proposal.md diff --git a/openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/specs/modules-bundle-nav/spec.md b/openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/specs/modules-bundle-nav/spec.md new file mode 100644 index 0000000..7806d04 --- /dev/null +++ b/openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/specs/modules-bundle-nav/spec.md @@ -0,0 +1,24 @@ +## ADDED Requirements + +### Requirement: Modules docs sidebar SHALL provide per-bundle collapsible navigation + +The modules docs sidebar SHALL group all docs for each official bundle under a collapsible section and SHALL display a consistent top-level section order. + +#### 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/archive/2026-04-05-docs-06-modules-site-ia-restructure/specs/modules-progressive-tiers/spec.md b/openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/specs/modules-progressive-tiers/spec.md new file mode 100644 index 0000000..7dc1f26 --- /dev/null +++ b/openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/specs/modules-progressive-tiers/spec.md @@ -0,0 +1,23 @@ +## ADDED Requirements + +### Requirement: Modules docs SHALL be organized by audience tier from beginner to advanced + +Modules documentation SHALL be structured into progressive tiers so that beginners, team leads, and module authors each find their relevant content without navigating the full docs tree. + +#### 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/archive/2026-04-05-docs-06-modules-site-ia-restructure/tasks.md similarity index 100% rename from openspec/changes/docs-06-modules-site-ia-restructure/tasks.md rename to openspec/changes/archive/2026-04-05-docs-06-modules-site-ia-restructure/tasks.md diff --git a/openspec/changes/docs-08-bundle-overview-pages/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/docs-08-bundle-overview-pages/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/CHANGE_VALIDATION.md diff --git a/openspec/changes/docs-08-bundle-overview-pages/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/docs-08-bundle-overview-pages/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/TDD_EVIDENCE.md diff --git a/openspec/changes/docs-08-bundle-overview-pages/proposal.md b/openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/proposal.md similarity index 100% rename from openspec/changes/docs-08-bundle-overview-pages/proposal.md rename to openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/proposal.md diff --git a/openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md b/openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md similarity index 98% rename from openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md rename to openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md index 449a940..f6380d7 100644 --- a/openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md @@ -1,4 +1,4 @@ -## ADDED Requirements +## MODIFIED Requirements ### Requirement: Bundle overview pages SHALL provide complete bundle entry points Each official bundle SHALL have a single overview page that lists its commands, prerequisites, examples, and relevant bundle-owned resource setup guidance. diff --git a/openspec/changes/docs-08-bundle-overview-pages/tasks.md b/openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/tasks.md similarity index 100% rename from openspec/changes/docs-08-bundle-overview-pages/tasks.md rename to openspec/changes/archive/2026-04-05-docs-08-bundle-overview-pages/tasks.md diff --git a/openspec/changes/docs-09-missing-command-docs/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/docs-09-missing-command-docs/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/CHANGE_VALIDATION.md diff --git a/openspec/changes/docs-09-missing-command-docs/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/docs-09-missing-command-docs/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/TDD_EVIDENCE.md diff --git a/openspec/changes/docs-09-missing-command-docs/proposal.md b/openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/proposal.md similarity index 100% rename from openspec/changes/docs-09-missing-command-docs/proposal.md rename to openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/proposal.md diff --git a/openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md b/openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/specs/missing-command-docs/spec.md similarity index 98% rename from openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md rename to openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/specs/missing-command-docs/spec.md index 2f503fd..40e9bd6 100644 --- a/openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/specs/missing-command-docs/spec.md @@ -1,4 +1,4 @@ -## ADDED Requirements +## MODIFIED Requirements ### Requirement: Missing command reference pages SHALL document the implemented command surface Previously undocumented command pages SHALL describe the current option surface, examples, and relevant bundle-owned resource guidance for their commands. diff --git a/openspec/changes/docs-09-missing-command-docs/tasks.md b/openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/tasks.md similarity index 100% rename from openspec/changes/docs-09-missing-command-docs/tasks.md rename to openspec/changes/archive/2026-04-05-docs-09-missing-command-docs/tasks.md diff --git a/openspec/changes/docs-10-workflow-consolidation/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/docs-10-workflow-consolidation/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/CHANGE_VALIDATION.md diff --git a/openspec/changes/docs-10-workflow-consolidation/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/docs-10-workflow-consolidation/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/TDD_EVIDENCE.md diff --git a/openspec/changes/docs-10-workflow-consolidation/proposal.md b/openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/proposal.md similarity index 100% rename from openspec/changes/docs-10-workflow-consolidation/proposal.md rename to openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/proposal.md diff --git a/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md b/openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md similarity index 98% rename from openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md rename to openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md index 93c0d77..f9acf71 100644 --- a/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md @@ -1,4 +1,4 @@ -# ADDED Requirements +## MODIFIED Requirements ### Requirement: Workflow docs SHALL cover current cross-module flows and setup prerequisites Workflow documentation SHALL show valid multi-bundle command chains and include resource-bootstrap steps when migrated bundle-owned prompts or templates are prerequisites. diff --git a/openspec/changes/docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.md b/openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.md similarity index 95% rename from openspec/changes/docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.md rename to openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.md index df63f57..689bb93 100644 --- a/openspec/changes/docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/specs/daily-devops-routine-docs/spec.md @@ -1,4 +1,4 @@ -# ADDED Requirements +## MODIFIED Requirements ### Requirement: Workflow docs SHALL document a current daily development routine diff --git a/openspec/changes/docs-10-workflow-consolidation/tasks.md b/openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/tasks.md similarity index 100% rename from openspec/changes/docs-10-workflow-consolidation/tasks.md rename to openspec/changes/archive/2026-04-05-docs-10-workflow-consolidation/tasks.md diff --git a/openspec/changes/docs-11-team-enterprise-tier/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/docs-11-team-enterprise-tier/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/CHANGE_VALIDATION.md diff --git a/openspec/changes/docs-11-team-enterprise-tier/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/docs-11-team-enterprise-tier/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/TDD_EVIDENCE.md diff --git a/openspec/changes/docs-11-team-enterprise-tier/proposal.md b/openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/proposal.md similarity index 100% rename from openspec/changes/docs-11-team-enterprise-tier/proposal.md rename to openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/proposal.md diff --git a/openspec/changes/docs-11-team-enterprise-tier/specs/enterprise-config-docs/spec.md b/openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/specs/enterprise-config-docs/spec.md similarity index 96% rename from openspec/changes/docs-11-team-enterprise-tier/specs/enterprise-config-docs/spec.md rename to openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/specs/enterprise-config-docs/spec.md index 88a4eff..6f87edc 100644 --- a/openspec/changes/docs-11-team-enterprise-tier/specs/enterprise-config-docs/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/specs/enterprise-config-docs/spec.md @@ -1,4 +1,4 @@ -# ADDED Requirements +## MODIFIED Requirements ### Requirement: Enterprise configuration docs SHALL cover profiles, overlays, and multi-repo policy diff --git a/openspec/changes/docs-11-team-enterprise-tier/specs/team-setup-docs/spec.md b/openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/specs/team-setup-docs/spec.md similarity index 97% rename from openspec/changes/docs-11-team-enterprise-tier/specs/team-setup-docs/spec.md rename to openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/specs/team-setup-docs/spec.md index 38d60e7..87f1be2 100644 --- a/openspec/changes/docs-11-team-enterprise-tier/specs/team-setup-docs/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/specs/team-setup-docs/spec.md @@ -1,4 +1,4 @@ -# ADDED Requirements +## MODIFIED Requirements ### Requirement: Team setup docs SHALL cover operational onboarding and resource ownership diff --git a/openspec/changes/docs-11-team-enterprise-tier/tasks.md b/openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/tasks.md similarity index 100% rename from openspec/changes/docs-11-team-enterprise-tier/tasks.md rename to openspec/changes/archive/2026-04-05-docs-11-team-enterprise-tier/tasks.md diff --git a/openspec/changes/docs-12-docs-validation-ci/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/docs-12-docs-validation-ci/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/CHANGE_VALIDATION.md diff --git a/openspec/changes/docs-12-docs-validation-ci/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/docs-12-docs-validation-ci/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/TDD_EVIDENCE.md diff --git a/openspec/changes/docs-12-docs-validation-ci/proposal.md b/openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/proposal.md similarity index 100% rename from openspec/changes/docs-12-docs-validation-ci/proposal.md rename to openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/proposal.md diff --git a/openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md b/openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md similarity index 98% rename from openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md rename to openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md index 6baa9c7..93dd910 100644 --- a/openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md @@ -1,6 +1,6 @@ # Modules Docs Command Validation -## ADDED Requirements +## MODIFIED Requirements ### Requirement: Docs validation SHALL reject stale command and resource references diff --git a/openspec/changes/docs-12-docs-validation-ci/tasks.md b/openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/tasks.md similarity index 100% rename from openspec/changes/docs-12-docs-validation-ci/tasks.md rename to openspec/changes/archive/2026-04-05-docs-12-docs-validation-ci/tasks.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/.openspec.yaml b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/.openspec.yaml similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/.openspec.yaml rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/.openspec.yaml diff --git a/openspec/changes/docs-13-nav-search-theme-roles/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/TDD_EVIDENCE.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/design.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/design.md similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/design.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/design.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/proposal.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/proposal.md similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/proposal.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/proposal.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/bundle-overview-pages/spec.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/bundle-overview-pages/spec.md similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/specs/bundle-overview-pages/spec.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/bundle-overview-pages/spec.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/cross-module-workflow-docs/spec.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/cross-module-workflow-docs/spec.md similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/specs/cross-module-workflow-docs/spec.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/cross-module-workflow-docs/spec.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-client-search/spec.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/docs-client-search/spec.md similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/specs/docs-client-search/spec.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/docs-client-search/spec.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-nav-data-driven/spec.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/docs-nav-data-driven/spec.md similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/specs/docs-nav-data-driven/spec.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/docs-nav-data-driven/spec.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-role-expertise-nav/spec.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/docs-role-expertise-nav/spec.md similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/specs/docs-role-expertise-nav/spec.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/docs-role-expertise-nav/spec.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-theme-toggle/spec.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/docs-theme-toggle/spec.md similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/specs/docs-theme-toggle/spec.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/docs-theme-toggle/spec.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/modules-docs-command-validation/spec.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/modules-docs-command-validation/spec.md similarity index 99% rename from openspec/changes/docs-13-nav-search-theme-roles/specs/modules-docs-command-validation/spec.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/modules-docs-command-validation/spec.md index 2dfda5d..4fe7cd2 100644 --- a/openspec/changes/docs-13-nav-search-theme-roles/specs/modules-docs-command-validation/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/modules-docs-command-validation/spec.md @@ -44,6 +44,8 @@ Published module docs SHALL include Jekyll front matter and valid internal links - **AND** its internal links resolve to current canonical modules docs routes - **AND** the docs review run completes without warnings +## ADDED Requirements + ### Requirement: Nav data file link targets SHALL be validated The docs validation script SHALL verify that every URL in `_data/nav.yml` corresponds to an existing page with a matching permalink. diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/team-setup-docs/spec.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/team-setup-docs/spec.md similarity index 100% rename from openspec/changes/docs-13-nav-search-theme-roles/specs/team-setup-docs/spec.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/specs/team-setup-docs/spec.md diff --git a/openspec/changes/docs-13-nav-search-theme-roles/tasks.md b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/tasks.md similarity index 94% rename from openspec/changes/docs-13-nav-search-theme-roles/tasks.md rename to openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/tasks.md index 606faa1..dfe18d5 100644 --- a/openspec/changes/docs-13-nav-search-theme-roles/tasks.md +++ b/openspec/changes/archive/2026-04-05-docs-13-nav-search-theme-roles/tasks.md @@ -55,7 +55,7 @@ ## 8. Module Changelog Visibility -- [ ] 8.1 Define a canonical source for per-module release history that is updated automatically whenever a module version is published -- [ ] 8.2 Add homepage or overview rendering for recent module release history using that canonical source, with graceful fallback when no history is available -- [ ] 8.3 Extend the publish flow so `.github/workflows/publish-modules.yml` writes the new release-history entry alongside the existing registry metadata update -- [ ] 8.4 Verify the rendered changelog entries match the canonical release-history source for all official modules +- [x] 8.1 Define a canonical source for per-module release history that is updated automatically whenever a module version is published +- [x] 8.2 Add homepage or overview rendering for recent module release history using that canonical source, with graceful fallback when no history is available +- [x] 8.3 Extend the publish flow so `.github/workflows/publish-modules.yml` writes the new release-history entry alongside the existing registry metadata update +- [x] 8.4 Verify the rendered changelog entries match the canonical release-history source for all official modules diff --git a/openspec/changes/module-bundle-deps-auto-install/.openspec.yaml b/openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/.openspec.yaml similarity index 100% rename from openspec/changes/module-bundle-deps-auto-install/.openspec.yaml rename to openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/.openspec.yaml diff --git a/openspec/changes/module-bundle-deps-auto-install/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/module-bundle-deps-auto-install/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/TDD_EVIDENCE.md diff --git a/openspec/changes/module-bundle-deps-auto-install/design.md b/openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/design.md similarity index 100% rename from openspec/changes/module-bundle-deps-auto-install/design.md rename to openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/design.md diff --git a/openspec/changes/module-bundle-deps-auto-install/proposal.md b/openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/proposal.md similarity index 100% rename from openspec/changes/module-bundle-deps-auto-install/proposal.md rename to openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/proposal.md diff --git a/openspec/changes/module-bundle-deps-auto-install/specs/module-bundle-dependencies/spec.md b/openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/specs/module-bundle-dependencies/spec.md similarity index 100% rename from openspec/changes/module-bundle-deps-auto-install/specs/module-bundle-dependencies/spec.md rename to openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/specs/module-bundle-dependencies/spec.md diff --git a/openspec/changes/module-bundle-deps-auto-install/tasks.md b/openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/tasks.md similarity index 97% rename from openspec/changes/module-bundle-deps-auto-install/tasks.md rename to openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/tasks.md index 35cad23..8da9128 100644 --- a/openspec/changes/module-bundle-deps-auto-install/tasks.md +++ b/openspec/changes/archive/2026-04-05-module-bundle-deps-auto-install/tasks.md @@ -17,7 +17,7 @@ - [x] 4.1 Record failing/passing test notes in `openspec/changes/module-bundle-deps-auto-install/TDD_EVIDENCE.md`. - [x] 4.2 Run full quality gate sequence from AGENTS.md (`format`, `type-check`, `lint`, `yaml-lint`, `verify-modules-signature`, `contract-test`, `smart-test`, `test`). (Full suite run; `verify-modules-signature` without `--require-signature` passes; **with** `--require-signature` pending until signing step above.) -- [ ] 4.3 Ensure `.specfact/code-review.json` is present and fresh relative to edits under `packages/`, `registry/`, `tests/`, and this change folder (excluding evidence-only `TDD_EVIDENCE.md` updates). Run `hatch run specfact code review run --json --out .specfact/code-review.json` with `--scope changed` while iterating and `--scope full` before the final PR; remediate all findings. **Blocked here:** `specfact code review` requires workflow bundles (`Command 'code' is not installed`); run after `specfact module install` / profile init locally. +- [x] 4.3 Ensure `.specfact/code-review.json` is present and fresh relative to edits under `packages/`, `registry/`, `tests/`, and this change folder (excluding evidence-only `TDD_EVIDENCE.md` updates). Run `hatch run specfact code review run --json --out .specfact/code-review.json` with `--scope changed` while iterating and `--scope full` before the final PR; remediate all findings. **Blocked here:** `specfact code review` requires workflow bundles (`Command 'code' is not installed`); run after `specfact module install` / profile init locally. - [x] 4.4 Open PR to `dev` and link GitHub issue below. — PR [#136](https://github.com/nold-ai/specfact-cli-modules/pull/136) (issue [#135](https://github.com/nold-ai/specfact-cli-modules/issues/135)). ## 5. Source tracking diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/.openspec.yaml b/openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/.openspec.yaml similarity index 100% rename from openspec/changes/packaging-01-bundle-resource-payloads/.openspec.yaml rename to openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/.openspec.yaml diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/packaging-01-bundle-resource-payloads/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/CHANGE_VALIDATION.md diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/RESOURCE_OWNERSHIP_AUDIT.md b/openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/RESOURCE_OWNERSHIP_AUDIT.md similarity index 100% rename from openspec/changes/packaging-01-bundle-resource-payloads/RESOURCE_OWNERSHIP_AUDIT.md rename to openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/RESOURCE_OWNERSHIP_AUDIT.md diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/packaging-01-bundle-resource-payloads/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/TDD_EVIDENCE.md diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/design.md b/openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/design.md similarity index 100% rename from openspec/changes/packaging-01-bundle-resource-payloads/design.md rename to openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/design.md diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/proposal.md b/openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/proposal.md similarity index 100% rename from openspec/changes/packaging-01-bundle-resource-payloads/proposal.md rename to openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/proposal.md diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/specs/bundle-packaged-resources/spec.md b/openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/specs/bundle-packaged-resources/spec.md similarity index 100% rename from openspec/changes/packaging-01-bundle-resource-payloads/specs/bundle-packaged-resources/spec.md rename to openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/specs/bundle-packaged-resources/spec.md diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/specs/resource-aware-integrity/spec.md b/openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/specs/resource-aware-integrity/spec.md similarity index 100% rename from openspec/changes/packaging-01-bundle-resource-payloads/specs/resource-aware-integrity/spec.md rename to openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/specs/resource-aware-integrity/spec.md diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/tasks.md b/openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/tasks.md similarity index 100% rename from openspec/changes/packaging-01-bundle-resource-payloads/tasks.md rename to openspec/changes/archive/2026-04-05-packaging-01-bundle-resource-payloads/tasks.md diff --git a/openspec/changes/speckit-03-change-proposal-bridge/.openspec.yaml b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/.openspec.yaml similarity index 100% rename from openspec/changes/speckit-03-change-proposal-bridge/.openspec.yaml rename to openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/.openspec.yaml diff --git a/openspec/changes/speckit-03-change-proposal-bridge/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/speckit-03-change-proposal-bridge/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/CHANGE_VALIDATION.md diff --git a/openspec/changes/speckit-03-change-proposal-bridge/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/speckit-03-change-proposal-bridge/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/TDD_EVIDENCE.md diff --git a/openspec/changes/speckit-03-change-proposal-bridge/design.md b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/design.md similarity index 100% rename from openspec/changes/speckit-03-change-proposal-bridge/design.md rename to openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/design.md diff --git a/openspec/changes/speckit-03-change-proposal-bridge/proposal.md b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/proposal.md similarity index 100% rename from openspec/changes/speckit-03-change-proposal-bridge/proposal.md rename to openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/proposal.md diff --git a/openspec/changes/speckit-03-change-proposal-bridge/specs/backlog-sync/spec.md b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/specs/backlog-sync/spec.md similarity index 97% rename from openspec/changes/speckit-03-change-proposal-bridge/specs/backlog-sync/spec.md rename to openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/specs/backlog-sync/spec.md index faba437..66f1fdb 100644 --- a/openspec/changes/speckit-03-change-proposal-bridge/specs/backlog-sync/spec.md +++ b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/specs/backlog-sync/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Backlog sync checks for existing external issue mappings before creation diff --git a/openspec/changes/speckit-03-change-proposal-bridge/specs/speckit-backlog-extension-sync/spec.md b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/specs/speckit-backlog-extension-sync/spec.md similarity index 100% rename from openspec/changes/speckit-03-change-proposal-bridge/specs/speckit-backlog-extension-sync/spec.md rename to openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/specs/speckit-backlog-extension-sync/spec.md diff --git a/openspec/changes/speckit-03-change-proposal-bridge/specs/speckit-change-proposal-bridge/spec.md b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/specs/speckit-change-proposal-bridge/spec.md similarity index 100% rename from openspec/changes/speckit-03-change-proposal-bridge/specs/speckit-change-proposal-bridge/spec.md rename to openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/specs/speckit-change-proposal-bridge/spec.md diff --git a/openspec/changes/speckit-03-change-proposal-bridge/tasks.md b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/tasks.md similarity index 96% rename from openspec/changes/speckit-03-change-proposal-bridge/tasks.md rename to openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/tasks.md index 1b04952..be8e159 100644 --- a/openspec/changes/speckit-03-change-proposal-bridge/tasks.md +++ b/openspec/changes/archive/2026-04-05-speckit-03-change-proposal-bridge/tasks.md @@ -44,8 +44,8 @@ - [x] 6.1 Add profile detection in sync bridge command (use `profile-01` system when available, fall back to `solo`) - [x] 6.2 Implement solo profile: spec-kit → OpenSpec as default direction -- [ ] 6.3 Implement team profile: bidirectional with divergence warnings -- [ ] 6.4 Add unit tests for each profile behavior +- [x] 6.3 Implement team profile: bidirectional with divergence warnings +- [x] 6.4 Add unit tests for each profile behavior ## 7. Documentation @@ -56,5 +56,5 @@ ## 8. Contracts and quality gates - [x] 8.1 Add `@icontract` and `@beartype` decorators to all new public methods -- [ ] 8.2 Run full quality gate suite +- [x] 8.2 Run full quality gate suite - [x] 8.3 Record TDD evidence in `TDD_EVIDENCE.md` 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 deleted file mode 100644 index 35aeb03..0000000 --- a/openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-bundle-nav/spec.md +++ /dev/null @@ -1,24 +0,0 @@ -# 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 deleted file mode 100644 index f2bdef9..0000000 --- a/openspec/changes/docs-06-modules-site-ia-restructure/specs/modules-progressive-tiers/spec.md +++ /dev/null @@ -1,23 +0,0 @@ -# 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/specs/backlog-sync/spec.md b/openspec/specs/backlog-sync/spec.md index 5354d04..3b8ec00 100644 --- a/openspec/specs/backlog-sync/spec.md +++ b/openspec/specs/backlog-sync/spec.md @@ -25,3 +25,24 @@ The system SHALL provide `specfact backlog sync` command for bidirectional backl - **WHEN** the user runs `specfact backlog ceremony sync` - **THEN** the command forwards to `specfact backlog sync` +### Requirement: Backlog sync checks for existing external issue mappings before creation + +The backlog sync system SHALL check for existing issue mappings from external tools (including spec-kit extensions) before creating new backlog issues, to prevent duplicates. + +#### Scenario: Backlog sync with spec-kit extension mappings available + +- **GIVEN** a project with both SpecFact backlog sync and spec-kit backlog extensions active +- **AND** `SpecKitBacklogSync.detect_issue_mappings()` has returned mappings for some tasks +- **WHEN** `specfact backlog sync` runs for the project +- **THEN** for each task, the sync checks imported issue mappings first +- **AND** skips creation for tasks with existing mappings +- **AND** creates new issues only for unmapped tasks +- **AND** the sync summary reports both skipped (already-mapped) and newly-created issues + +#### Scenario: Backlog sync without spec-kit extensions + +- **GIVEN** a project without spec-kit or without backlog extensions +- **WHEN** `specfact backlog sync` runs +- **THEN** the sync creates issues for all tasks as before (no behavior change) +- **AND** no spec-kit extension detection is attempted + diff --git a/openspec/specs/bundle-overview-pages/spec.md b/openspec/specs/bundle-overview-pages/spec.md index 5950e80..231af17 100644 --- a/openspec/specs/bundle-overview-pages/spec.md +++ b/openspec/specs/bundle-overview-pages/spec.md @@ -3,12 +3,10 @@ ## Purpose Define requirements for official bundle overview pages on the modules documentation site: each official bundle has a single landing page that lists commands, prerequisites, quick examples, and bundle-owned resource setup guidance aligned with the mounted SpecFact CLI surface. - ## Requirements - ### Requirement: Bundle overview pages SHALL provide complete bundle entry points -Each official bundle SHALL have a single overview page that lists its commands, prerequisites, examples, and relevant bundle-owned resource setup guidance. +Each official bundle SHALL have a single overview page that lists its commands, prerequisites, examples, and relevant bundle-owned resource setup guidance. The sidebar navigation SHALL link to each bundle's overview page as the first item in that bundle's collapsible section, and all command deep-dive pages SHALL be listed below the overview. #### Scenario: Overview page lists all bundle commands @@ -36,3 +34,12 @@ Each official bundle SHALL have a single overview page that lists its commands, - **WHEN** compared against the actual `specfact --help` output - **THEN** the command name, arguments, and key options match - **AND** `tests/unit/docs/test_bundle_overview_cli_examples.py::test_validate_bundle_overview_cli_help_examples` exercises each quick-example line by invoking the corresponding bundle Typer app with `--help` (or an explicit `--help` normalization for lines that include runnable flags), failing when help output cannot be produced + +#### Scenario: Sidebar links to overview and all command pages + +- **GIVEN** the sidebar navigation for any bundle (Backlog, Project, Codebase, Spec, Govern, Code Review) +- **WHEN** the bundle section is expanded +- **THEN** the first link SHALL be the bundle's overview page +- **AND** subsequent links SHALL point to each command deep-dive page under that bundle's directory +- **AND** no link SHALL point to the generic `/reference/commands/` placeholder + diff --git a/openspec/specs/bundle-packaged-resources/spec.md b/openspec/specs/bundle-packaged-resources/spec.md new file mode 100644 index 0000000..4a9bf1d --- /dev/null +++ b/openspec/specs/bundle-packaged-resources/spec.md @@ -0,0 +1,33 @@ +# bundle-packaged-resources Specification + +## Purpose +TBD - created by archiving change packaging-01-bundle-resource-payloads. Update Purpose after archive. +## Requirements +### Requirement: Official bundles SHALL ship module-owned resource payloads +Each official bundle package SHALL include the prompt templates and other non-code resources that are owned by that bundle's workflows or commands. Bundle-owned resources SHALL not depend on fallback storage under the core CLI repository. + +#### Scenario: Official bundles ship the audited prompt inventory +- **WHEN** the audited prompt inventory from `RESOURCE_OWNERSHIP_AUDIT.md` is inspected +- **THEN** each prompt template's canonical packaged source exists under the owning official bundle package +- **AND** the ownership mapping covers the codebase, project, spec, govern, and backlog bundles for the currently supported prompt set + +#### Scenario: Backlog bundle ships the restored slash-prompt inventory +- **WHEN** the backlog bundle package is inspected from source or from an installed artifact +- **THEN** `resources/prompts/` contains `specfact.backlog-add.md`, `specfact.backlog-daily.md`, `specfact.backlog-refine.md`, and `specfact.sync-backlog.md` +- **AND** those prompt files are treated as canonical bundle-owned sources rather than historical leftovers + +#### Scenario: Prompt companion resources ship with prompt payloads +- **WHEN** an exported prompt template references a companion file by relative path, such as `./shared/cli-enforcement.md` +- **THEN** the owning bundle package contains that companion resource in a stable relative location +- **AND** prompt export/copy flows can preserve a resolvable relative layout in the target IDE workspace + +#### Scenario: Backlog bundle ships workspace-template seed resources +- **WHEN** the backlog bundle package is inspected from source or from an installed artifact +- **THEN** the package contains the backlog field mapping templates that `specfact init` or related flows need to copy into workspace state +- **AND** the packaged set includes both ADO and non-ADO seed templates required by supported backlog flows + +#### Scenario: Core no longer remains the source of truth for bundle prompts +- **WHEN** a workflow prompt belongs to an extracted bundle rather than to core lifecycle commands +- **THEN** that prompt's canonical packaged source exists in the owning bundle package +- **AND** release packaging does not rely on the core CLI repo as the canonical source for that prompt + diff --git a/openspec/specs/clean-code-analysis/spec.md b/openspec/specs/clean-code-analysis/spec.md new file mode 100644 index 0000000..e78a250 --- /dev/null +++ b/openspec/specs/clean-code-analysis/spec.md @@ -0,0 +1,20 @@ +# clean-code-analysis Specification + +## Purpose +TBD - created by archiving change clean-code-02-expanded-review-module. Update Purpose after archive. +## 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/specs/clean-code-policy-pack/spec.md b/openspec/specs/clean-code-policy-pack/spec.md new file mode 100644 index 0000000..7e68262 --- /dev/null +++ b/openspec/specs/clean-code-policy-pack/spec.md @@ -0,0 +1,20 @@ +# clean-code-policy-pack Specification + +## Purpose +TBD - created by archiving change clean-code-02-expanded-review-module. Update Purpose after archive. +## 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/specs/cross-module-workflow-docs/spec.md b/openspec/specs/cross-module-workflow-docs/spec.md index 8649488..7c57e93 100644 --- a/openspec/specs/cross-module-workflow-docs/spec.md +++ b/openspec/specs/cross-module-workflow-docs/spec.md @@ -1,8 +1,12 @@ -# ADDED Requirements +# cross-module-workflow-docs Specification +## Purpose + +Define requirements for workflow documentation covering cross-bundle command chains and resource-bootstrap prerequisites. +## Requirements ### Requirement: Workflow docs SHALL cover current cross-module flows and setup prerequisites -Workflow documentation SHALL show valid multi-bundle command chains and include resource-bootstrap steps when migrated bundle-owned prompts or templates are prerequisites. +Workflow documentation SHALL show valid multi-bundle command chains and include resource-bootstrap steps when migrated bundle-owned prompts or templates are prerequisites. The sidebar Workflows section SHALL link to all workflow pages. #### Scenario: Cross-module chain covers full lifecycle @@ -24,3 +28,10 @@ Workflow documentation SHALL show valid multi-bundle command chains and include - **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 + +#### Scenario: Sidebar Workflows section links to all workflow pages + +- **WHEN** the Workflows section is rendered in the sidebar +- **THEN** it SHALL include links to Cross-Module Chains, Daily DevOps Routine, CI/CD Pipeline, and Brownfield Modernization +- **AND** it SHALL include links to existing workflow pages (Agile & Scrum, Command Chains, Common Tasks, Copilot Mode, Contract Testing) + diff --git a/openspec/specs/daily-devops-routine-docs/spec.md b/openspec/specs/daily-devops-routine-docs/spec.md index df63f57..32bf594 100644 --- a/openspec/specs/daily-devops-routine-docs/spec.md +++ b/openspec/specs/daily-devops-routine-docs/spec.md @@ -1,5 +1,9 @@ -# ADDED Requirements +# daily-devops-routine-docs Specification +## Purpose + +Define requirements for workflow documentation covering the daily development routine from standup through release readiness. +## Requirements ### Requirement: Workflow docs SHALL document a current daily development routine Workflow documentation SHALL provide a complete day-level routine that links standup, backlog refinement, development, review, and release readiness to the current bundle command surface. @@ -10,3 +14,4 @@ Workflow documentation SHALL provide a complete day-level routine that links sta - **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 + diff --git a/openspec/specs/docs-client-search/spec.md b/openspec/specs/docs-client-search/spec.md new file mode 100644 index 0000000..1f14723 --- /dev/null +++ b/openspec/specs/docs-client-search/spec.md @@ -0,0 +1,60 @@ +# docs-client-search Specification + +## Purpose +TBD - created by archiving change docs-13-nav-search-theme-roles. Update Purpose after archive. +## Requirements +### Requirement: Search index generation +A Jekyll Liquid template at `docs/assets/js/search-index.json` SHALL generate a JSON array at build time containing one entry per page with fields: `url`, `title`, `keywords` (from front matter), `audience`, `expertise_level`, and `content` (page content truncated to the first 200 words with HTML tags stripped). + +#### Scenario: Search index contains all pages +- **WHEN** the Jekyll site is built +- **THEN** the generated `search-index.json` SHALL contain entries for every page that has a `title` in its front matter + +#### Scenario: Search index includes front matter metadata +- **WHEN** a page has `keywords: [backlog, refinement, sprint]` in its front matter +- **THEN** its search index entry SHALL include those keywords in the `keywords` field + +### Requirement: Search UI in sidebar +A search input field SHALL be rendered in the sidebar above the navigation sections via `docs/_includes/search.html`. The search input SHALL have placeholder text "Search docs... (Ctrl+K)". + +#### Scenario: Search input is visible +- **WHEN** any page loads +- **THEN** a search input field SHALL appear at the top of the sidebar, above all navigation sections + +#### Scenario: Keyboard shortcut focuses search +- **WHEN** the user presses Ctrl+K (or Cmd+K on macOS) +- **THEN** the search input SHALL receive focus + +### Requirement: Lunr.js search integration +The search SHALL use Lunr.js loaded from CDN. The search index SHALL be lazy-loaded on first search input focus. Lunr SHALL be configured with field boosting: title at 10x, keywords at 5x, content at 1x. + +#### Scenario: First search triggers index load +- **WHEN** the user focuses the search input for the first time +- **THEN** the `search-index.json` SHALL be fetched and a Lunr index SHALL be built + +#### Scenario: Search results appear on input +- **WHEN** the user types at least 2 characters in the search input +- **THEN** a dropdown SHALL appear below the search input showing matching results with page title and a content snippet + +#### Scenario: No results message +- **WHEN** the user's query matches no pages +- **THEN** the dropdown SHALL show "No results found" + +### Requirement: Search result navigation +The search results dropdown SHALL support keyboard navigation with arrow keys and Enter to follow a link. Clicking a result SHALL navigate to that page. + +#### Scenario: Arrow key navigation +- **WHEN** the search dropdown is open and the user presses the down arrow +- **THEN** the next result SHALL be highlighted + +#### Scenario: Enter navigates to result +- **WHEN** a result is highlighted and the user presses Enter +- **THEN** the browser SHALL navigate to that result's URL + +### Requirement: Search results show metadata tags +Each search result SHALL display matching front matter tags (audience, expertise_level) as small pills/badges alongside the title. + +#### Scenario: Result shows audience tag +- **WHEN** a search result is for a page with `audience: [team, enterprise]` +- **THEN** the result SHALL display "team" and "enterprise" as tag pills + diff --git a/openspec/specs/docs-nav-data-driven/spec.md b/openspec/specs/docs-nav-data-driven/spec.md new file mode 100644 index 0000000..53c5b1c --- /dev/null +++ b/openspec/specs/docs-nav-data-driven/spec.md @@ -0,0 +1,76 @@ +# docs-nav-data-driven Specification + +## Purpose +TBD - created by archiving change docs-13-nav-search-theme-roles. Update Purpose after archive. +## Requirements +### Requirement: Navigation data file +The sidebar navigation structure SHALL be defined in `docs/_data/nav.yml` as a YAML data file. Each top-level entry SHALL have a `section` name and either an `items` array (flat list) or a `bundles` array (collapsible groups). Each item SHALL have `title`, `url`, and optionally `expertise` fields. + +#### Scenario: Nav data file defines all sections +- **WHEN** the `_data/nav.yml` file is loaded +- **THEN** it SHALL contain entries for all seven sections: Getting Started, Bundles, Workflows, Integrations, Team & Enterprise, Authoring, Reference + +#### Scenario: Bundle section uses collapsible groups +- **WHEN** the Bundles section is defined in `nav.yml` +- **THEN** it SHALL use a `bundles` array with entries for Backlog, Project, Codebase, Code Review, Spec, and Govern, each containing an `items` array + +### Requirement: Sidebar nav rendered from data +The sidebar navigation in `docs/_layouts/default.html` SHALL render navigation by including `docs/_includes/sidebar-nav.html` which iterates over `site.data.nav` using Liquid loops. Hardcoded navigation HTML SHALL be removed. + +#### Scenario: Sidebar renders all nav items +- **WHEN** a page loads with the default layout +- **THEN** the sidebar SHALL display all sections and items defined in `nav.yml` + +#### Scenario: Bundle sections render as collapsible details +- **WHEN** a bundle group is rendered +- **THEN** it SHALL use `
` HTML elements with the bundle name as `` + +### Requirement: All bundle links point to actual pages +Every bundle navigation link SHALL point to an existing page URL, not to the generic `/reference/commands/` placeholder. + +#### Scenario: Code Review bundle links +- **WHEN** the Code Review bundle section is expanded +- **THEN** it SHALL contain links to Overview, Run, Ledger, and Rules pages at their `/bundles/code-review/` paths + +#### Scenario: Spec bundle links +- **WHEN** the Spec bundle section is expanded +- **THEN** it SHALL contain links to Overview, Validate, Generate Tests, and Mock pages at their `/bundles/spec/` paths + +#### Scenario: Govern bundle links +- **WHEN** the Govern bundle section is expanded +- **THEN** it SHALL contain links to Overview, Enforce, and Patch pages at their `/bundles/govern/` paths + +#### Scenario: Codebase bundle links +- **WHEN** the Codebase bundle section is expanded +- **THEN** it SHALL contain links to Overview, Sidecar Validation, Analyze, Drift, and Repro pages at their `/bundles/codebase/` paths + +### Requirement: Active page highlighting +The sidebar SHALL highlight the currently active page by matching `page.url` against nav item URLs and applying a CSS active class. + +#### Scenario: Current page is highlighted +- **WHEN** a user visits `/bundles/spec/validate/` +- **THEN** the Validate link in the Spec bundle section SHALL have the active CSS class applied +- **AND** the Spec bundle `
` element SHALL be in the open state + +### Requirement: Team & Enterprise links use correct paths +The Team & Enterprise section SHALL link to pages under `/team-and-enterprise/` with all four deliverables from docs-11. + +#### Scenario: Team & Enterprise navigation completeness +- **WHEN** the Team & Enterprise section is rendered +- **THEN** it SHALL contain links to Team Collaboration, Agile & Scrum Setup, Multi-Repo Setup, and Enterprise Configuration at their `/team-and-enterprise/` paths + +### Requirement: Workflows section includes all docs-10 pages +The Workflows section SHALL include links to all workflow pages created in docs-10. + +#### Scenario: Workflows navigation completeness +- **WHEN** the Workflows section is rendered +- **THEN** it SHALL contain links to Cross-Module Chains, Daily DevOps Routine, CI/CD Pipeline, and Brownfield Modernization in addition to existing workflow links + +### Requirement: Breadcrumb navigation above content +Each page SHALL display a breadcrumb trail above the content area, derived from the page URL segments, to provide orientation and allow quick navigation to parent sections. + +#### Scenario: Bundle command page shows breadcrumb trail +- **WHEN** a user visits `/bundles/spec/validate/` +- **THEN** a breadcrumb trail SHALL be displayed showing: Home > Bundles > Spec > Validate +- **AND** each breadcrumb segment except the current page SHALL be a clickable link + diff --git a/openspec/specs/docs-role-expertise-nav/spec.md b/openspec/specs/docs-role-expertise-nav/spec.md new file mode 100644 index 0000000..4d6077a --- /dev/null +++ b/openspec/specs/docs-role-expertise-nav/spec.md @@ -0,0 +1,58 @@ +# docs-role-expertise-nav Specification + +## Purpose +TBD - created by archiving change docs-13-nav-search-theme-roles. Update Purpose after archive. +## Requirements +### Requirement: Expertise level filter in sidebar +A compact dropdown or pill filter SHALL be rendered in the sidebar between the search input and the navigation sections via `docs/_includes/expertise-filter.html`. Options: All, Beginner, Intermediate, Advanced. + +#### Scenario: Filter defaults to All +- **WHEN** a user visits the site for the first time +- **THEN** the expertise filter SHALL be set to "All" and all nav items SHALL be visible + +#### Scenario: Filter hides non-matching items +- **WHEN** the user selects "Beginner" from the expertise filter +- **THEN** nav items whose `expertise` field does not include "beginner" SHALL be hidden via CSS +- **AND** bundle `
` sections with no visible items SHALL also be hidden + +#### Scenario: Filter persists across pages +- **WHEN** the user selects "Advanced" and navigates to another page +- **THEN** the filter SHALL still be set to "Advanced" (stored in `localStorage` under key `specfact-expertise`) + +#### Scenario: Filtered count indicator +- **WHEN** the expertise filter is set to a value other than "All" +- **THEN** a small indicator SHALL show how many items are visible vs total (e.g., "12 of 45") + +### Requirement: Front matter expertise and audience fields +All documentation pages SHALL have `keywords`, `audience`, and `expertise_level` fields in their front matter. These fields are arrays of strings. + +#### Scenario: Getting started pages are tagged as beginner +- **WHEN** a page under `getting-started/` is inspected +- **THEN** its front matter SHALL include `expertise_level: [beginner]` + +#### Scenario: Authoring pages are tagged as advanced +- **WHEN** a page under `authoring/` is inspected +- **THEN** its front matter SHALL include `expertise_level: [advanced]` + +#### Scenario: Team & Enterprise pages target team and enterprise audiences +- **WHEN** a page under `team-and-enterprise/` is inspected +- **THEN** its front matter SHALL include `audience: [team, enterprise]` + +### Requirement: Homepage role-based entry cards +The `index.md` homepage SHALL include a "Find Your Path" section with four role-based entry cards: Solo Developer, Small Team (Startup), Corporate Team, and Enterprise. Each card SHALL link to 3-4 curated pages most relevant to that profile. + +#### Scenario: Solo developer card content +- **WHEN** the homepage is rendered +- **THEN** the Solo Developer card SHALL link to getting started, first steps, and a bundle quickstart tutorial + +#### Scenario: Enterprise card content +- **WHEN** the homepage is rendered +- **THEN** the Enterprise card SHALL link to enterprise configuration, module signing, custom registries, and module security + +### Requirement: Nav items carry expertise data attribute +Each nav item rendered in the sidebar SHALL have a `data-expertise` HTML attribute containing the comma-separated expertise levels from `nav.yml`, enabling CSS-based filtering. + +#### Scenario: Nav item data attribute +- **WHEN** a nav item with `expertise: [beginner, intermediate]` is rendered +- **THEN** the `
  • ` element SHALL have `data-expertise="beginner,intermediate"` + diff --git a/openspec/specs/docs-theme-toggle/spec.md b/openspec/specs/docs-theme-toggle/spec.md new file mode 100644 index 0000000..8945df0 --- /dev/null +++ b/openspec/specs/docs-theme-toggle/spec.md @@ -0,0 +1,53 @@ +# docs-theme-toggle Specification + +## Purpose +TBD - created by archiving change docs-13-nav-search-theme-roles. Update Purpose after archive. +## Requirements +### Requirement: Dual CSS theme definitions +The stylesheet SHALL define CSS custom properties for both light and dark themes using `[data-theme="light"]` and `[data-theme="dark"]` selectors on the `` element. A `@media (prefers-color-scheme)` fallback SHALL apply when no explicit `data-theme` attribute is set. + +#### Scenario: Dark theme variables +- **WHEN** the `data-theme` attribute is set to `dark` +- **THEN** the site SHALL use a dark navy background (`#0a192f`), light text (`#ccd6f6`), and a subdued cyan accent (`#57e6c4`) + +#### Scenario: Light theme variables +- **WHEN** the `data-theme` attribute is set to `light` +- **THEN** the site SHALL use a white/off-white background, dark text, and a SpecFact teal accent (`#0d9488`) + +#### Scenario: System preference fallback +- **WHEN** no `data-theme` attribute is set on `` +- **THEN** the site SHALL use `@media (prefers-color-scheme: dark)` and `@media (prefers-color-scheme: light)` to match the user's OS preference + +### Requirement: Theme toggle button +A theme toggle button SHALL be rendered in the site header via `docs/_includes/theme-toggle.html`. The button SHALL display a sun icon in dark mode and a moon icon in light mode. + +#### Scenario: Toggle from dark to light +- **WHEN** the user clicks the theme toggle button while in dark mode +- **THEN** the site SHALL switch to light mode immediately and store `"light"` in `localStorage` under the key `specfact-theme` + +#### Scenario: Toggle from light to dark +- **WHEN** the user clicks the theme toggle button while in light mode +- **THEN** the site SHALL switch to dark mode immediately and store `"dark"` in `localStorage` + +### Requirement: Theme persistence prevents FOUC +A `theme.js` script SHALL be loaded in the `` element (before body renders) to read the stored theme from `localStorage` and set the `data-theme` attribute before any content is painted. + +#### Scenario: Returning visitor sees stored theme +- **WHEN** a user who previously selected light mode visits any page +- **THEN** the page SHALL render in light mode without any flash of dark mode + +### Requirement: Theme-aware Mermaid diagrams +Mermaid.js SHALL be re-initialized with appropriate `themeVariables` when the theme changes. Dark mode SHALL use the existing dark mermaid theme. Light mode SHALL use mermaid's `default` theme with SpecFact teal accents. + +#### Scenario: Mermaid diagrams update on toggle +- **WHEN** the user toggles from dark to light mode +- **THEN** all Mermaid diagrams on the page SHALL re-render with light-mode colors + +### Requirement: Theme-aware syntax highlighting +Rouge syntax highlighting token classes SHALL have color overrides for both light and dark themes so that code blocks are readable in both modes. + +#### Scenario: Code blocks readable in light mode +- **WHEN** the site is in light mode +- **THEN** code block backgrounds SHALL be light with dark syntax-highlighted text +- **AND** all token classes (keywords, strings, comments, etc.) SHALL have sufficient contrast against the light background + diff --git a/openspec/specs/enterprise-config-docs/spec.md b/openspec/specs/enterprise-config-docs/spec.md index 6a81188..8347b50 100644 --- a/openspec/specs/enterprise-config-docs/spec.md +++ b/openspec/specs/enterprise-config-docs/spec.md @@ -1,6 +1,10 @@ -# ADDED Requirements +# enterprise-config-docs Specification -## Requirement: Enterprise configuration docs SHALL cover profiles, overlays, and multi-repo policy +## Purpose + +Define requirements for enterprise configuration documentation covering profiles, overlays, and multi-repo policy. +## Requirements +### Requirement: Enterprise configuration docs SHALL cover profiles, overlays, and multi-repo policy Enterprise guidance SHALL explain custom profiles, domain overlays, central configuration, and multi-repo operations using supported commands. @@ -15,3 +19,4 @@ Enterprise guidance SHALL explain custom profiles, domain overlays, central conf - **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/specs/house-rules-skill/spec.md b/openspec/specs/house-rules-skill/spec.md new file mode 100644 index 0000000..711c76d --- /dev/null +++ b/openspec/specs/house-rules-skill/spec.md @@ -0,0 +1,20 @@ +# house-rules-skill Specification + +## Purpose +TBD - created by archiving change clean-code-02-expanded-review-module. Update Purpose after archive. +## 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/specs/missing-command-docs/spec.md b/openspec/specs/missing-command-docs/spec.md index 587e134..caf3eb7 100644 --- a/openspec/specs/missing-command-docs/spec.md +++ b/openspec/specs/missing-command-docs/spec.md @@ -1,39 +1,36 @@ # Missing Command Documentation Specification -## ADDED Requirements +## Purpose +Define requirements for command reference pages that were previously undocumented across the spec, govern, and code-review bundles. +## Requirements ### Requirement: Missing command reference pages SHALL document the implemented command surface - Previously undocumented command pages SHALL describe the current option surface, examples, and relevant bundle-owned resource guidance for their commands. #### Scenario: Each command page documents full option reference - - **GIVEN** a command reference page such as `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: Command pages explain bundle-owned resources where they affect usage - - **GIVEN** a command reference page for a command that depends on migrated bundle-owned prompts or templates - **WHEN** a user reads the page - **THEN** the page explains the relevant setup or bootstrap path - **AND** it does not direct users to legacy core-owned resource locations #### 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/specs/module-bundle-dependencies/spec.md b/openspec/specs/module-bundle-dependencies/spec.md new file mode 100644 index 0000000..5193dfc --- /dev/null +++ b/openspec/specs/module-bundle-dependencies/spec.md @@ -0,0 +1,32 @@ +# module-bundle-dependencies Specification + +## Purpose +TBD - created by archiving change module-bundle-deps-auto-install. Update Purpose after archive. +## Requirements +### Requirement: Code-review module declares codebase peer dependency + +The `nold-ai/specfact-code-review` module SHALL list `nold-ai/specfact-codebase` in `bundle_dependencies` inside `packages/specfact-code-review/module-package.yaml` so that installing code review can resolve the peer bundle required for the full `code` command group. + +#### Scenario: Manifest names the codebase bundle + +- **WHEN** a maintainer reads `packages/specfact-code-review/module-package.yaml` +- **THEN** the `bundle_dependencies` sequence includes `nold-ai/specfact-codebase` + +### Requirement: Registry mirrors manifest bundle dependencies for code-review + +The `registry/index.json` entry for `nold-ai/specfact-code-review` SHALL list the same `bundle_dependencies` values as the published `module-package.yaml` for that module version. + +#### Scenario: Registry matches manifest after publish + +- **WHEN** the code-review module version is published and the registry row is updated +- **THEN** the `bundle_dependencies` array for `nold-ai/specfact-code-review` equals the manifest’s `bundle_dependencies` for that version + +### Requirement: Dependency declarations stay acyclic + +Official module `bundle_dependencies` SHALL NOT introduce a dependency cycle between official nold-ai bundles. + +#### Scenario: Code-review dependency does not create a cycle + +- **WHEN** code-review declares a dependency on codebase +- **THEN** no official bundle manifest transitively depends back on `nold-ai/specfact-code-review` in a way that forms a cycle + diff --git a/openspec/specs/modules-bundle-nav/spec.md b/openspec/specs/modules-bundle-nav/spec.md new file mode 100644 index 0000000..d6f35fe --- /dev/null +++ b/openspec/specs/modules-bundle-nav/spec.md @@ -0,0 +1,28 @@ +# modules-bundle-nav Specification + +## Purpose +TBD - created by archiving change docs-06-modules-site-ia-restructure. Update Purpose after archive. +## Requirements +### Requirement: Modules docs sidebar SHALL provide per-bundle collapsible navigation + +The modules docs sidebar SHALL group all docs for each official bundle under a collapsible section and SHALL display a consistent top-level section order. + +#### 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/specs/modules-docs-command-validation/spec.md b/openspec/specs/modules-docs-command-validation/spec.md index 6baa9c7..3339783 100644 --- a/openspec/specs/modules-docs-command-validation/spec.md +++ b/openspec/specs/modules-docs-command-validation/spec.md @@ -1,7 +1,9 @@ # Modules Docs Command Validation -## ADDED Requirements +## Purpose +Define requirements for CI-based validation of command examples and resource references across the modules documentation site. +## Requirements ### Requirement: Docs validation SHALL reject stale command and resource references The modules-side docs validation workflow SHALL reject command examples across published module docs that do not match implemented bundle commands and SHALL also reject stale references to migrated core-owned resource paths. @@ -45,3 +47,22 @@ Published module docs SHALL include Jekyll front matter and valid internal links - **THEN** the page is published with required front matter - **AND** its internal links resolve to current canonical modules docs routes - **AND** the docs review run completes without warnings + +### Requirement: Nav data file link targets SHALL be validated + +The docs validation script SHALL verify that every URL in `_data/nav.yml` corresponds to an existing page with a matching permalink. + +#### Scenario: Nav link to non-existent page fails validation + +- **GIVEN** `_data/nav.yml` contains a link to `/bundles/spec/nonexistent/` +- **WHEN** the validation runs +- **THEN** it reports that no page exists with permalink `/bundles/spec/nonexistent/` +- **AND** the check fails + +#### Scenario: All nav links resolve to existing pages + +- **GIVEN** `_data/nav.yml` contains all current navigation links +- **WHEN** the validation runs +- **THEN** every URL in the nav file matches an existing page's permalink +- **AND** the check passes + diff --git a/openspec/specs/modules-progressive-tiers/spec.md b/openspec/specs/modules-progressive-tiers/spec.md new file mode 100644 index 0000000..44accfa --- /dev/null +++ b/openspec/specs/modules-progressive-tiers/spec.md @@ -0,0 +1,27 @@ +# modules-progressive-tiers Specification + +## Purpose +TBD - created by archiving change docs-06-modules-site-ia-restructure. Update Purpose after archive. +## Requirements +### Requirement: Modules docs SHALL be organized by audience tier from beginner to advanced + +Modules documentation SHALL be structured into progressive tiers so that beginners, team leads, and module authors each find their relevant content without navigating the full docs tree. + +#### 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/specs/radon-runner/spec.md b/openspec/specs/radon-runner/spec.md index 1bd9fc6..0633850 100644 --- a/openspec/specs/radon-runner/spec.md +++ b/openspec/specs/radon-runner/spec.md @@ -43,3 +43,18 @@ used by local and CI quality gates. - **WHEN** Radon-backed review tooling or tests run in that environment - **THEN** the `radon` executable is available on `PATH` +### 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/specs/resource-aware-integrity/spec.md b/openspec/specs/resource-aware-integrity/spec.md new file mode 100644 index 0000000..e834cd9 --- /dev/null +++ b/openspec/specs/resource-aware-integrity/spec.md @@ -0,0 +1,39 @@ +# resource-aware-integrity Specification + +## Purpose +TBD - created by archiving change packaging-01-bundle-resource-payloads. Update Purpose after archive. +## Requirements +### Requirement: Bundle integrity SHALL cover resource payloads +Bundle signing, verification, and publish validation SHALL treat bundled resource files as part of the signed module payload so that resource-only changes are detected as bundle changes. + +#### Scenario: Resource edit changes signed payload +- **WHEN** a prompt template or other bundled resource file changes inside a bundle package +- **THEN** integrity verification detects a payload change until the manifest version and signature are refreshed + +#### Scenario: Resource-only change triggers version-bump enforcement +- **WHEN** a bundled resource file changes but the bundle manifest version is not incremented +- **THEN** the modules-repo version-bump enforcement reports that the bundle payload changed without a version bump + +### Requirement: Bundle resource layout SHALL be discoverable by core CLI +Bundled resources SHALL live at stable paths inside the bundle package so that the core CLI can resolve them from an installed bundle root without hardcoded core-repo fallbacks. + +#### Scenario: Core resolves prompt resources from installed bundle root +- **WHEN** the core CLI inspects an installed official bundle package +- **THEN** the bundle contains a stable prompt resource path that can be discovered without scanning the core CLI repository + +#### Scenario: Installed backlog bundle contributes prompt source catalog entries + +- **WHEN** `nold-ai/specfact-backlog` is installed under an effective module root with the packaged backlog prompt files +- **THEN** core prompt-source discovery includes `nold-ai/specfact-backlog` as a prompt source +- **AND** `specfact init ide` can export the backlog prompt filenames from that installed module root + +#### Scenario: Core resolves prompt companion resources with exported prompts +- **WHEN** the core CLI exports a prompt that depends on a companion file such as `shared/cli-enforcement.md` +- **THEN** the companion resource is discoverable from the same installed bundle root +- **AND** the exported prompt does not contain a broken relative reference after copy + +#### Scenario: Core resolves backlog workspace-template seeds from installed bundle root +- **WHEN** the core CLI inspects an installed backlog bundle package +- **THEN** the bundle contains a stable template resource path for backlog field mapping templates +- **AND** that path exposes every seed template the init/install flows are expected to copy + diff --git a/openspec/specs/review-cli-contracts/spec.md b/openspec/specs/review-cli-contracts/spec.md index f28ea81..22627ef 100644 --- a/openspec/specs/review-cli-contracts/spec.md +++ b/openspec/specs/review-cli-contracts/spec.md @@ -23,3 +23,18 @@ scope-mode and path-filter coverage for the review run command. - **WHEN** it is validated - **THEN** it includes the supported rules subcommands +### 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/specs/review-run-command/spec.md b/openspec/specs/review-run-command/spec.md index 3e9a75a..a65bdf8 100644 --- a/openspec/specs/review-run-command/spec.md +++ b/openspec/specs/review-run-command/spec.md @@ -67,3 +67,18 @@ without mutating the source package manifest. - **THEN** the shadow module directory contains symlinks to the live module content - **AND** the shadow manifest omits integrity metadata so runtime validation can opt into unsigned local loading +### 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/specs/speckit-backlog-extension-sync/spec.md b/openspec/specs/speckit-backlog-extension-sync/spec.md new file mode 100644 index 0000000..42f4bc6 --- /dev/null +++ b/openspec/specs/speckit-backlog-extension-sync/spec.md @@ -0,0 +1,58 @@ +# speckit-backlog-extension-sync Specification + +## Purpose +TBD - created by archiving change speckit-03-change-proposal-bridge. Update Purpose after archive. +## Requirements +### Requirement: Detect spec-kit backlog extension issue mappings + +The system SHALL detect when spec-kit backlog extensions (Jira, ADO, Linear, GitHub Projects, Trello) have created issues from feature specs, and import those issue references. + +#### Scenario: Detect Jira issue references from spec-kit + +- **GIVEN** a spec-kit repository with the `jira` extension detected in `ToolCapabilities.extension_commands` +- **AND** feature `tasks.md` contains references matching pattern `[A-Z]+-\d+` (e.g., `PROJ-123`) +- **WHEN** `SpecKitBacklogSync.detect_issue_mappings(feature_path)` is called +- **THEN** returns a list of issue mapping objects with `tool="jira"`, `issue_ref="PROJ-123"`, and `source="speckit-extension"` + +#### Scenario: Detect Azure DevOps work item references + +- **GIVEN** a spec-kit repository with the `azure-devops` extension detected +- **AND** feature `tasks.md` contains references matching pattern `AB#\d+` (e.g., `AB#456`) +- **WHEN** `SpecKitBacklogSync.detect_issue_mappings(feature_path)` is called +- **THEN** returns issue mapping objects with `tool="ado"` and `issue_ref="AB#456"` + +#### Scenario: Detect Linear issue references + +- **GIVEN** a spec-kit repository with the `linear` extension detected +- **AND** feature `tasks.md` contains references matching pattern `[A-Z]+-\d+` (e.g., `ENG-789`) +- **WHEN** `SpecKitBacklogSync.detect_issue_mappings(feature_path)` is called +- **THEN** returns issue mapping objects with `tool="linear"` and matched references + +#### Scenario: No backlog extension present + +- **GIVEN** a spec-kit repository where `ToolCapabilities.extension_commands` does not contain any backlog extension +- **WHEN** `SpecKitBacklogSync.detect_issue_mappings(feature_path)` is called +- **THEN** returns an empty list +- **AND** no issue reference scanning is performed + +### Requirement: Prevent duplicate issue creation during backlog sync + +The system SHALL skip issue creation for items that already have spec-kit backlog extension mappings. + +#### Scenario: Skip duplicate Jira issue creation + +- **GIVEN** a SpecFact backlog sync targeting Jira +- **AND** spec-kit backlog extension has already created `PROJ-123` for a feature task +- **AND** the issue mapping has been imported via `detect_issue_mappings()` +- **WHEN** SpecFact backlog sync processes the same task +- **THEN** the sync skips issue creation for that task +- **AND** logs that the issue already exists via spec-kit extension +- **AND** links the existing issue reference in SpecFact's tracking + +#### Scenario: Create issue when no spec-kit mapping exists + +- **GIVEN** a SpecFact backlog sync targeting Jira +- **AND** no spec-kit backlog extension mapping exists for a given task +- **WHEN** SpecFact backlog sync processes that task +- **THEN** the sync creates a new issue as normal + diff --git a/openspec/specs/speckit-change-proposal-bridge/spec.md b/openspec/specs/speckit-change-proposal-bridge/spec.md new file mode 100644 index 0000000..73b39fe --- /dev/null +++ b/openspec/specs/speckit-change-proposal-bridge/spec.md @@ -0,0 +1,74 @@ +# speckit-change-proposal-bridge Specification + +## Purpose +TBD - created by archiving change speckit-03-change-proposal-bridge. Update Purpose after archive. +## Requirements +### Requirement: Convert spec-kit feature folder to OpenSpec change proposal + +The system SHALL convert a spec-kit feature folder into a complete OpenSpec change proposal with all required artifacts (proposal.md, design.md, specs/, tasks.md). + +#### Scenario: Convert complete spec-kit feature + +- **GIVEN** a spec-kit feature folder at `specs/{feature}/` containing `spec.md`, `plan.md`, and `tasks.md` +- **WHEN** `SpecKitConverter.convert_to_change_proposal(feature_path, change_name)` is called +- **THEN** the converter creates an OpenSpec change directory at `openspec/changes/{change_name}/` +- **AND** generates `proposal.md` with Why section extracted from spec.md narrative and What Changes from requirements +- **AND** generates `design.md` with Context from plan.md technical context and Decisions from plan.md phases +- **AND** generates `specs/{capability}/spec.md` with requirements reformatted as Given/When/Then scenarios +- **AND** generates `tasks.md` with checkbox groups mapped from spec-kit task phases + +#### Scenario: Convert spec-kit feature with INVEST criteria + +- **GIVEN** a spec-kit feature with user stories containing INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) +- **WHEN** the feature is converted to an OpenSpec change proposal +- **THEN** INVEST criteria are preserved as structured comments in the generated spec scenarios +- **AND** each user story maps to one or more Given/When/Then scenario blocks + +#### Scenario: Convert spec-kit feature missing plan.md + +- **GIVEN** a spec-kit feature folder with `spec.md` and `tasks.md` but no `plan.md` +- **WHEN** `SpecKitConverter.convert_to_change_proposal(feature_path, change_name)` is called +- **THEN** the converter generates `proposal.md`, `specs/`, and `tasks.md` +- **AND** generates a minimal `design.md` with a placeholder Context section +- **AND** logs a warning that plan.md was not found + +### Requirement: Convert OpenSpec change proposal to spec-kit feature folder + +The system SHALL convert an OpenSpec change proposal back to spec-kit feature folder format. + +#### Scenario: Export change proposal to spec-kit format + +- **GIVEN** an OpenSpec change proposal at `openspec/changes/{change_name}/` with all 4 artifacts +- **WHEN** `SpecKitConverter.convert_to_speckit_feature(change_dir, output_dir)` is called +- **THEN** the converter creates a spec-kit feature folder at `{output_dir}/{feature_name}/` +- **AND** generates `spec.md` with user stories extracted from spec scenarios +- **AND** generates `plan.md` with technical context from design.md +- **AND** generates `tasks.md` with checklist items from tasks.md checkbox groups + +#### Scenario: Roundtrip preservation + +- **GIVEN** a spec-kit feature converted to OpenSpec and then back to spec-kit format +- **WHEN** the roundtrip conversion completes +- **THEN** all user stories from the original spec.md are present in the output spec.md +- **AND** all task items from the original tasks.md are present in the output tasks.md +- **AND** unmappable fields are preserved as annotation comments + +### Requirement: Sync bridge change-proposal mode + +The system SHALL support a `--mode change-proposal` option on the `specfact sync bridge` command that operates on change proposals rather than plan bundles. + +#### Scenario: Sync spec-kit feature as change proposal + +- **GIVEN** a spec-kit repository detected by `BridgeProbe` +- **WHEN** `specfact sync bridge --adapter speckit --mode change-proposal --feature {name}` is called +- **THEN** the command converts the specified spec-kit feature to an OpenSpec change proposal +- **AND** writes the change to `openspec/changes/{derived-change-name}/` +- **AND** displays a summary of created artifacts + +#### Scenario: Sync all untracked spec-kit features + +- **GIVEN** a spec-kit repository with 3 features, 1 already has an OpenSpec change +- **WHEN** `specfact sync bridge --adapter speckit --mode change-proposal --all` is called +- **THEN** the command converts only the 2 untracked features to OpenSpec change proposals +- **AND** skips the feature that already has a corresponding change + diff --git a/openspec/specs/team-setup-docs/spec.md b/openspec/specs/team-setup-docs/spec.md index c25db8d..982db8b 100644 --- a/openspec/specs/team-setup-docs/spec.md +++ b/openspec/specs/team-setup-docs/spec.md @@ -1,8 +1,12 @@ -# ADDED Requirements +# team-setup-docs Specification -## Requirement: Team setup docs SHALL cover operational onboarding and resource ownership +## Purpose -Team setup guidance SHALL explain onboarding, shared configuration, role-based workflows, and how bundle-owned prompts/templates are rolled out and kept in sync. +Define requirements for team setup documentation covering operational onboarding and bundle-owned resource ownership. +## Requirements +### Requirement: Team setup docs SHALL cover operational onboarding and resource ownership + +Team setup guidance SHALL explain onboarding, shared configuration, role-based workflows, and how bundle-owned prompts/templates are rolled out and kept in sync. The sidebar Team & Enterprise section SHALL link to all team/enterprise pages at their correct `/team-and-enterprise/` paths. #### Scenario: Team setup guide covers onboarding @@ -16,3 +20,13 @@ Team setup guidance SHALL explain onboarding, shared configuration, role-based w - **WHEN** a team lead reads the page - **THEN** the docs explain that prompts and bundle-specific workspace templates ship from installed bundles - **AND** they describe how teams keep those resources aligned through supported bootstrap commands and version management + +#### Scenario: Sidebar Team & Enterprise links use correct paths + +- **WHEN** the Team & Enterprise section is rendered in the sidebar +- **THEN** it SHALL link to Team Collaboration at `/team-and-enterprise/team-collaboration/` +- **AND** Agile & Scrum Setup at `/team-and-enterprise/agile-scrum-setup/` +- **AND** Multi-Repo Setup at `/team-and-enterprise/multi-repo/` +- **AND** Enterprise Configuration at `/team-and-enterprise/enterprise-config/` +- **AND** no links SHALL point to stale paths like `/team-collaboration-workflow/` or `/guides/agile-scrum-workflows/` + From 742412e6064b17b2e9dd4b7941cd1ab5fd4e97cf Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Wed, 8 Apr 2026 23:25:26 +0200 Subject: [PATCH 2/2] Split and refactor change proposals between both repos --- openspec/CHANGE_ORDER.md | 47 +++++- .../.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 31 ++++ .../architecture-01-solution-layer/design.md | 40 +++++ .../proposal.md | 124 ++++++++++++++ .../specs/data-models/spec.md | 16 ++ .../specs/solution-architecture/spec.md | 22 +++ .../architecture-01-solution-layer/tasks.md | 30 ++++ .../CHANGE_VALIDATION.md | 59 +++++++ .../proposal.md | 102 ++++++++++++ .../specs/kanban-flow/spec.md | 78 +++++++++ .../backlog-kanban-01-flow-metrics/tasks.md | 36 +++++ .../CHANGE_VALIDATION.md | 54 +++++++ .../backlog-safe-01-pi-planning/proposal.md | 100 ++++++++++++ .../specs/safe-pi/spec.md | 65 ++++++++ .../backlog-safe-01-pi-planning/tasks.md | 36 +++++ .../CHANGE_VALIDATION.md | 54 +++++++ .../backlog-safe-02-risk-rollups/proposal.md | 76 +++++++++ .../specs/risk-rollups/spec.md | 77 +++++++++ .../backlog-safe-02-risk-rollups/tasks.md | 36 +++++ .../CHANGE_VALIDATION.md | 41 +++++ .../design.md | 28 ++++ .../proposal.md | 66 ++++++++ .../specs/sprint-planning/spec.md | 95 +++++++++++ .../backlog-scrum-02-sprint-planning/tasks.md | 73 +++++++++ .../CHANGE_VALIDATION.md | 40 +++++ .../design.md | 33 ++++ .../proposal.md | 72 +++++++++ .../specs/story-complexity/spec.md | 115 +++++++++++++ .../tasks.md | 71 ++++++++ .../CHANGE_VALIDATION.md | 87 ++++++++++ .../design.md | 27 ++++ .../proposal.md | 72 +++++++++ .../specs/definition-of-done/spec.md | 71 ++++++++ .../tasks.md | 73 +++++++++ .../.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 31 ++++ .../design.md | 40 +++++ .../proposal.md | 60 +++++++ .../specs/backlog-refinement/spec.md | 10 ++ .../ceremony-requirements-awareness/spec.md | 16 ++ .../specs/daily-standup/spec.md | 10 ++ .../tasks.md | 30 ++++ .../.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 28 ++++ .../governance-01-evidence-output/design.md | 40 +++++ .../governance-01-evidence-output/proposal.md | 86 ++++++++++ .../specs/full-chain-validation/spec.md | 10 ++ .../oscal-trace-delta.md | 33 ++++ .../specs/governance-evidence-output/spec.md | 22 +++ .../specs/policy-engine/spec.md | 10 ++ .../governance-01-evidence-output/tasks.md | 32 ++++ .../.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 28 ++++ .../design.md | 40 +++++ .../proposal.md | 69 ++++++++ .../specs/exception-management/spec.md | 22 +++ .../specs/governance-evidence-output/spec.md | 10 ++ .../specs/policy-engine/spec.md | 10 ++ .../tasks.md | 32 ++++ .../openspec-01-intent-trace/.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 110 +++++++++++++ .../openspec-01-intent-trace/design.md | 83 ++++++++++ .../openspec-01-intent-trace/proposal.md | 56 +++++++ .../specs/openspec-bridge-adapter/spec.md | 22 +++ .../openspec-bridge-intent-import/spec.md | 49 ++++++ .../openspec-intent-trace-schema/spec.md | 42 +++++ .../changes/openspec-01-intent-trace/tasks.md | 151 ++++++++++++++++++ .../policy-02-packs-and-modes/.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 28 ++++ .../policy-02-packs-and-modes/design.md | 40 +++++ .../policy-02-packs-and-modes/proposal.md | 68 ++++++++ .../specs/policy-engine/spec.md | 22 +++ .../specs/policy-packs-and-modes/spec.md | 22 +++ .../policy-02-packs-and-modes/tasks.md | 32 ++++ .../.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 31 ++++ .../requirements-02-module-commands/design.md | 40 +++++ .../proposal.md | 120 ++++++++++++++ .../specs/backlog-adapter/spec.md | 16 ++ .../specs/module-io-contract/spec.md | 16 ++ .../specs/requirements-module/spec.md | 22 +++ .../requirements-02-module-commands/tasks.md | 30 ++++ .../.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 31 ++++ .../requirements-03-backlog-sync/design.md | 40 +++++ .../requirements-03-backlog-sync/proposal.md | 54 +++++++ .../specs/backlog-adapter/spec.md | 16 ++ .../specs/requirements-backlog-sync/spec.md | 16 ++ .../specs/requirements-module/spec.md | 16 ++ .../requirements-03-backlog-sync/tasks.md | 30 ++++ .../sync-01-unified-kernel/.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 31 ++++ .../changes/sync-01-unified-kernel/design.md | 40 +++++ .../sync-01-unified-kernel/proposal.md | 127 +++++++++++++++ .../specs/devops-sync/spec.md | 16 ++ .../specs/sync-kernel/spec.md | 22 +++ .../changes/sync-01-unified-kernel/tasks.md | 30 ++++ .../.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 31 ++++ .../design.md | 40 +++++ .../proposal.md | 114 +++++++++++++ .../specs/traceability-index/spec.md | 22 +++ .../tasks.md | 30 ++++ .../.openspec.yaml | 2 + .../CHANGE_VALIDATION.md | 28 ++++ .../validation-02-full-chain-engine/design.md | 40 +++++ .../proposal.md | 103 ++++++++++++ .../specs/full-chain-validation/spec.md | 28 ++++ .../specs/sidecar-validation/spec.md | 15 ++ .../validation-02-full-chain-engine/tasks.md | 31 ++++ 111 files changed, 4687 insertions(+), 2 deletions(-) create mode 100644 openspec/changes/architecture-01-solution-layer/.openspec.yaml create mode 100644 openspec/changes/architecture-01-solution-layer/CHANGE_VALIDATION.md create mode 100644 openspec/changes/architecture-01-solution-layer/design.md create mode 100644 openspec/changes/architecture-01-solution-layer/proposal.md create mode 100644 openspec/changes/architecture-01-solution-layer/specs/data-models/spec.md create mode 100644 openspec/changes/architecture-01-solution-layer/specs/solution-architecture/spec.md create mode 100644 openspec/changes/architecture-01-solution-layer/tasks.md create mode 100644 openspec/changes/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md create mode 100644 openspec/changes/backlog-kanban-01-flow-metrics/proposal.md create mode 100644 openspec/changes/backlog-kanban-01-flow-metrics/specs/kanban-flow/spec.md create mode 100644 openspec/changes/backlog-kanban-01-flow-metrics/tasks.md create mode 100644 openspec/changes/backlog-safe-01-pi-planning/CHANGE_VALIDATION.md create mode 100644 openspec/changes/backlog-safe-01-pi-planning/proposal.md create mode 100644 openspec/changes/backlog-safe-01-pi-planning/specs/safe-pi/spec.md create mode 100644 openspec/changes/backlog-safe-01-pi-planning/tasks.md create mode 100644 openspec/changes/backlog-safe-02-risk-rollups/CHANGE_VALIDATION.md create mode 100644 openspec/changes/backlog-safe-02-risk-rollups/proposal.md create mode 100644 openspec/changes/backlog-safe-02-risk-rollups/specs/risk-rollups/spec.md create mode 100644 openspec/changes/backlog-safe-02-risk-rollups/tasks.md create mode 100644 openspec/changes/backlog-scrum-02-sprint-planning/CHANGE_VALIDATION.md create mode 100644 openspec/changes/backlog-scrum-02-sprint-planning/design.md create mode 100644 openspec/changes/backlog-scrum-02-sprint-planning/proposal.md create mode 100644 openspec/changes/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md create mode 100644 openspec/changes/backlog-scrum-02-sprint-planning/tasks.md create mode 100644 openspec/changes/backlog-scrum-03-story-complexity/CHANGE_VALIDATION.md create mode 100644 openspec/changes/backlog-scrum-03-story-complexity/design.md create mode 100644 openspec/changes/backlog-scrum-03-story-complexity/proposal.md create mode 100644 openspec/changes/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md create mode 100644 openspec/changes/backlog-scrum-03-story-complexity/tasks.md create mode 100644 openspec/changes/backlog-scrum-04-definition-of-done/CHANGE_VALIDATION.md create mode 100644 openspec/changes/backlog-scrum-04-definition-of-done/design.md create mode 100644 openspec/changes/backlog-scrum-04-definition-of-done/proposal.md create mode 100644 openspec/changes/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md create mode 100644 openspec/changes/backlog-scrum-04-definition-of-done/tasks.md create mode 100644 openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml create mode 100644 openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md create mode 100644 openspec/changes/ceremony-02-requirements-aware-output/design.md create mode 100644 openspec/changes/ceremony-02-requirements-aware-output/proposal.md create mode 100644 openspec/changes/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md create mode 100644 openspec/changes/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md create mode 100644 openspec/changes/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md create mode 100644 openspec/changes/ceremony-02-requirements-aware-output/tasks.md create mode 100644 openspec/changes/governance-01-evidence-output/.openspec.yaml create mode 100644 openspec/changes/governance-01-evidence-output/CHANGE_VALIDATION.md create mode 100644 openspec/changes/governance-01-evidence-output/design.md create mode 100644 openspec/changes/governance-01-evidence-output/proposal.md create mode 100644 openspec/changes/governance-01-evidence-output/specs/full-chain-validation/spec.md create mode 100644 openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/oscal-trace-delta.md create mode 100644 openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/spec.md create mode 100644 openspec/changes/governance-01-evidence-output/specs/policy-engine/spec.md create mode 100644 openspec/changes/governance-01-evidence-output/tasks.md create mode 100644 openspec/changes/governance-02-exception-management/.openspec.yaml create mode 100644 openspec/changes/governance-02-exception-management/CHANGE_VALIDATION.md create mode 100644 openspec/changes/governance-02-exception-management/design.md create mode 100644 openspec/changes/governance-02-exception-management/proposal.md create mode 100644 openspec/changes/governance-02-exception-management/specs/exception-management/spec.md create mode 100644 openspec/changes/governance-02-exception-management/specs/governance-evidence-output/spec.md create mode 100644 openspec/changes/governance-02-exception-management/specs/policy-engine/spec.md create mode 100644 openspec/changes/governance-02-exception-management/tasks.md create mode 100644 openspec/changes/openspec-01-intent-trace/.openspec.yaml create mode 100644 openspec/changes/openspec-01-intent-trace/CHANGE_VALIDATION.md create mode 100644 openspec/changes/openspec-01-intent-trace/design.md create mode 100644 openspec/changes/openspec-01-intent-trace/proposal.md create mode 100644 openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-adapter/spec.md create mode 100644 openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-intent-import/spec.md create mode 100644 openspec/changes/openspec-01-intent-trace/specs/openspec-intent-trace-schema/spec.md create mode 100644 openspec/changes/openspec-01-intent-trace/tasks.md create mode 100644 openspec/changes/policy-02-packs-and-modes/.openspec.yaml create mode 100644 openspec/changes/policy-02-packs-and-modes/CHANGE_VALIDATION.md create mode 100644 openspec/changes/policy-02-packs-and-modes/design.md create mode 100644 openspec/changes/policy-02-packs-and-modes/proposal.md create mode 100644 openspec/changes/policy-02-packs-and-modes/specs/policy-engine/spec.md create mode 100644 openspec/changes/policy-02-packs-and-modes/specs/policy-packs-and-modes/spec.md create mode 100644 openspec/changes/policy-02-packs-and-modes/tasks.md create mode 100644 openspec/changes/requirements-02-module-commands/.openspec.yaml create mode 100644 openspec/changes/requirements-02-module-commands/CHANGE_VALIDATION.md create mode 100644 openspec/changes/requirements-02-module-commands/design.md create mode 100644 openspec/changes/requirements-02-module-commands/proposal.md create mode 100644 openspec/changes/requirements-02-module-commands/specs/backlog-adapter/spec.md create mode 100644 openspec/changes/requirements-02-module-commands/specs/module-io-contract/spec.md create mode 100644 openspec/changes/requirements-02-module-commands/specs/requirements-module/spec.md create mode 100644 openspec/changes/requirements-02-module-commands/tasks.md create mode 100644 openspec/changes/requirements-03-backlog-sync/.openspec.yaml create mode 100644 openspec/changes/requirements-03-backlog-sync/CHANGE_VALIDATION.md create mode 100644 openspec/changes/requirements-03-backlog-sync/design.md create mode 100644 openspec/changes/requirements-03-backlog-sync/proposal.md create mode 100644 openspec/changes/requirements-03-backlog-sync/specs/backlog-adapter/spec.md create mode 100644 openspec/changes/requirements-03-backlog-sync/specs/requirements-backlog-sync/spec.md create mode 100644 openspec/changes/requirements-03-backlog-sync/specs/requirements-module/spec.md create mode 100644 openspec/changes/requirements-03-backlog-sync/tasks.md create mode 100644 openspec/changes/sync-01-unified-kernel/.openspec.yaml create mode 100644 openspec/changes/sync-01-unified-kernel/CHANGE_VALIDATION.md create mode 100644 openspec/changes/sync-01-unified-kernel/design.md create mode 100644 openspec/changes/sync-01-unified-kernel/proposal.md create mode 100644 openspec/changes/sync-01-unified-kernel/specs/devops-sync/spec.md create mode 100644 openspec/changes/sync-01-unified-kernel/specs/sync-kernel/spec.md create mode 100644 openspec/changes/sync-01-unified-kernel/tasks.md create mode 100644 openspec/changes/traceability-01-index-and-orphans/.openspec.yaml create mode 100644 openspec/changes/traceability-01-index-and-orphans/CHANGE_VALIDATION.md create mode 100644 openspec/changes/traceability-01-index-and-orphans/design.md create mode 100644 openspec/changes/traceability-01-index-and-orphans/proposal.md create mode 100644 openspec/changes/traceability-01-index-and-orphans/specs/traceability-index/spec.md create mode 100644 openspec/changes/traceability-01-index-and-orphans/tasks.md create mode 100644 openspec/changes/validation-02-full-chain-engine/.openspec.yaml create mode 100644 openspec/changes/validation-02-full-chain-engine/CHANGE_VALIDATION.md create mode 100644 openspec/changes/validation-02-full-chain-engine/design.md create mode 100644 openspec/changes/validation-02-full-chain-engine/proposal.md create mode 100644 openspec/changes/validation-02-full-chain-engine/specs/full-chain-validation/spec.md create mode 100644 openspec/changes/validation-02-full-chain-engine/specs/sidecar-validation/spec.md create mode 100644 openspec/changes/validation-02-full-chain-engine/tasks.md diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index 9edcd82..4d2f11e 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -30,9 +30,52 @@ | ✅ clean-code-02-expanded-review-module | archived 2026-04-05 | | ✅ docs-13-nav-search-theme-roles | archived 2026-04-05 | | ✅ speckit-03-change-proposal-bridge | archived 2026-04-05 | +| ✅ packaging-01-bundle-resource-payloads | archived 2026-04-05 | +| ✅ module-bundle-deps-auto-install | archived 2026-04-05 | ## Pending +### Backlog bundle runtime changes + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| backlog-scrum | 02 | backlog-scrum-02-sprint-planning | [#160](https://github.com/nold-ai/specfact-cli-modules/issues/160) | Parent Feature: [#151](https://github.com/nold-ai/specfact-cli-modules/issues/151); shared backlog baseline from `specfact-cli#116` | +| backlog-scrum | 03 | backlog-scrum-03-story-complexity | [#153](https://github.com/nold-ai/specfact-cli-modules/issues/153) | Parent Feature: [#151](https://github.com/nold-ai/specfact-cli-modules/issues/151); shared backlog baseline from `specfact-cli#116` | +| backlog-scrum | 04 | backlog-scrum-04-definition-of-done | [#152](https://github.com/nold-ai/specfact-cli-modules/issues/152) | Parent Feature: [#151](https://github.com/nold-ai/specfact-cli-modules/issues/151); shared backlog baseline from `specfact-cli#116`; optional ceremony alias baseline `specfact-cli#185` | +| backlog-kanban | 01 | backlog-kanban-01-flow-metrics | [#155](https://github.com/nold-ai/specfact-cli-modules/issues/155) | Parent Feature: [#149](https://github.com/nold-ai/specfact-cli-modules/issues/149); shared backlog baseline from `specfact-cli#116` | +| backlog-safe | 01 | backlog-safe-01-pi-planning | [#154](https://github.com/nold-ai/specfact-cli-modules/issues/154) | Parent Feature: [#146](https://github.com/nold-ai/specfact-cli-modules/issues/146); shared backlog baseline from `specfact-cli#116` | +| backlog-safe | 02 | backlog-safe-02-risk-rollups | [#156](https://github.com/nold-ai/specfact-cli-modules/issues/156) | Parent Feature: [#146](https://github.com/nold-ai/specfact-cli-modules/issues/146); `#154`; integrates with `#160`, `#153`, and `#155` | +| policy | 02 | policy-02-packs-and-modes | [#158](https://github.com/nold-ai/specfact-cli-modules/issues/158) | Parent Feature: [#148](https://github.com/nold-ai/specfact-cli-modules/issues/148); shared policy/profile semantics from `specfact-cli#176` and `specfact-cli#237` | +| ceremony | 02 | ceremony-02-requirements-aware-output | [#159](https://github.com/nold-ai/specfact-cli-modules/issues/159) | Parent Feature: [#150](https://github.com/nold-ai/specfact-cli-modules/issues/150); requirements contracts from `specfact-cli#239`; ceremony alias baseline `specfact-cli#185` | + +### Project bundle runtime changes + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| sync | 01 | sync-01-unified-kernel | [#157](https://github.com/nold-ai/specfact-cli-modules/issues/157) | Parent Feature: [#147](https://github.com/nold-ai/specfact-cli-modules/issues/147); preview/apply safety baseline from `specfact-cli#177` | + +### Cross-layer runtime follow-ups + +These changes are the modules-side runtime companions to split core changes. Shared schemas, contracts, and cross-change semantics remain in `specfact-cli`. + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| architecture | 01 | architecture-01-solution-layer | [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); core counterpart `specfact-cli#240`; shared models from `specfact-cli#238` and `specfact-cli#239` | +| requirements | 02 | requirements-02-module-commands | [#165](https://github.com/nold-ai/specfact-cli-modules/issues/165) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); core counterpart `specfact-cli#239`; data model baseline `specfact-cli#238` | +| requirements | 03 | requirements-03-backlog-sync | [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); core counterpart `specfact-cli#244`; runtime sync `#157`; requirements runtime `#165` | +| openspec | 01 | openspec-01-intent-trace | [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); core counterpart `specfact-cli#350`; requirements contracts from `specfact-cli#238` and `specfact-cli#239` | +| traceability | 01 | traceability-01-index-and-orphans | [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); core counterpart `specfact-cli#242`; runtime inputs from `#164` and `#165` | + +### Validation and governance runtime follow-ups + +These changes are the modules-side runtime companions to split core governance and validation changes. Core remains authoritative for schemas and CI/evidence contracts. + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| governance | 01 | governance-01-evidence-output | [#169](https://github.com/nold-ai/specfact-cli-modules/issues/169) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); core counterpart `specfact-cli#247`; validation runtime `#171` | +| governance | 02 | governance-02-exception-management | [#167](https://github.com/nold-ai/specfact-cli-modules/issues/167) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); core counterpart `specfact-cli#248`; policy runtime `#158` | +| validation | 02 | validation-02-full-chain-engine | [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); core counterpart `specfact-cli#241`; runtime inputs from `#164` and `#165`; policy semantics from `#158` | + ### Documentation restructure | Module | Order | Change folder | GitHub # | Blocked by | @@ -43,10 +86,10 @@ | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| packaging | 01 | packaging-01-bundle-resource-payloads | [#101](https://github.com/nold-ai/specfact-cli-modules/issues/101) | specfact-cli/packaging-02-cross-platform-runtime-and-module-resources; specfact-cli/init-ide-prompt-source-selection ([#382](https://github.com/nold-ai/specfact-cli/issues/382)) | +| packaging | 01 | ✅ packaging-01-bundle-resource-payloads (archived 2026-04-05) | [#101](https://github.com/nold-ai/specfact-cli-modules/issues/101) | — | ### Module bundle peer dependencies | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| peer-deps | 01 | module-bundle-deps-auto-install | [#135](https://github.com/nold-ai/specfact-cli-modules/issues/135) | — | +| peer-deps | 01 | ✅ module-bundle-deps-auto-install (archived 2026-04-05) | [#135](https://github.com/nold-ai/specfact-cli-modules/issues/135) | — | diff --git a/openspec/changes/architecture-01-solution-layer/.openspec.yaml b/openspec/changes/architecture-01-solution-layer/.openspec.yaml new file mode 100644 index 0000000..2a45c1f --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/architecture-01-solution-layer/CHANGE_VALIDATION.md b/openspec/changes/architecture-01-solution-layer/CHANGE_VALIDATION.md new file mode 100644 index 0000000..5da24ac --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: architecture-01-solution-layer + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate architecture-01-solution-layer --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** solution-architecture +- **Modified capabilities:** data-models +- **Declared dependencies:** requirements-01 (data model), requirements-02 (module commands), arch-07 (#213) +- **Proposed affected code paths:** - `modules/architecture/` (new module);- `src/specfact_cli/models/project.py` (extend via arch-07 schema extensions) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/architecture-01-solution-layer/design.md b/openspec/changes/architecture-01-solution-layer/design.md new file mode 100644 index 0000000..8ed9ce2 --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `architecture-01-solution-layer` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- Keep all public APIs contract-first with `@icontract` and `@beartype`. +- Make all behavior extensions opt-in or backward-compatible by default. +- Add/modify OpenSpec deltas first so tests can be derived before implementation. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-01-data-model and requirements-02-module-commands. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/architecture-01-solution-layer/proposal.md b/openspec/changes/architecture-01-solution-layer/proposal.md new file mode 100644 index 0000000..3572ae1 --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/proposal.md @@ -0,0 +1,124 @@ +# Change: Solution Architecture Layer — Derive, Store, Validate + +## Why + + + + +Architectural decisions live in separate ADRs or Confluence pages with zero programmatic links to requirements or code. This is the layer where the costliest misalignments occur — a wrong architectural choice invalidates entire implementation efforts regardless of code quality. No tool today systematically connects business requirements → architectural decisions → implementation. A solution architecture module that derives, stores, and validates architecture with explicit traceability to requirements closes the biggest blind spot in the end-to-end chain. + +## Ownership Alignment (2026-04-08) + +- Repository assignment: `nold-ai/specfact-cli-modules` +- Modules-owned scope retained here: bundle-side runtime delivery, command wiring, and execution behavior for architecture workflows. +- Core counterpart retained in `nold-ai/specfact-cli` issue [#240](https://github.com/nold-ai/specfact-cli/issues/240) +- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) -> Story [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) +- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. +- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. + +## Module Package Structure + +``` +modules/architecture/ + module-package.yaml # name: architecture; commands: architecture derive, validate-coverage, trace + src/architecture/ + __init__.py + main.py # typer.Typer app — architecture command group + engine/ + deriver.py # Derive architecture from requirements (template + AI-assisted) + coverage_validator.py # Validate architecture covers all requirements + trace_builder.py # Build architecture ↔ requirements traceability links + models/ + solution_architecture.py # SolutionArchitecture, ComponentSpec, DataFlow, ADR models + templates/ + microservice.yaml # Microservice architecture template + monolith.yaml # Modular monolith template + event_driven.yaml # Event-driven architecture template + commands/ + derive.py # specfact architecture derive + validate_coverage.py # specfact architecture validate-coverage + trace.py # specfact architecture trace + storage/ + architecture_store.py # Read/write .specfact/architecture/*.arch.yaml +``` + +**`module-package.yaml` declares:** +- `name: architecture` +- `version: 0.1.0` +- `commands: [architecture derive, architecture validate-coverage, architecture trace]` +- `dependencies: [requirements-01-data-model, requirements-02-module-commands]` +- `schema_extensions:` — via arch-07 +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +## Module Package Structure + +``` +modules/architecture/ + module-package.yaml # name: architecture; commands: architecture derive, validate-coverage, trace + src/architecture/ + __init__.py + main.py # typer.Typer app — architecture command group + engine/ + deriver.py # Derive architecture from requirements (template + AI-assisted) + coverage_validator.py # Validate architecture covers all requirements + trace_builder.py # Build architecture ↔ requirements traceability links + models/ + solution_architecture.py # SolutionArchitecture, ComponentSpec, DataFlow, ADR models + templates/ + microservice.yaml # Microservice architecture template + monolith.yaml # Modular monolith template + event_driven.yaml # Event-driven architecture template + commands/ + derive.py # specfact architecture derive + validate_coverage.py # specfact architecture validate-coverage + trace.py # specfact architecture trace + storage/ + architecture_store.py # Read/write .specfact/architecture/*.arch.yaml +``` + +**`module-package.yaml` declares:** +- `name: architecture` +- `version: 0.1.0` +- `commands: [architecture derive, architecture validate-coverage, architecture trace]` +- `dependencies: [requirements-01-data-model, requirements-02-module-commands]` +- `schema_extensions:` — via arch-07 +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +## What Changes + + + + +- **NEW**: Pydantic domain models in `modules/architecture/src/architecture/models/`: + - `SolutionArchitecture` — architecture ID, requirement IDs (traceability links), components, data flows, ADRs + - `ComponentSpec` — name, responsibility, business rule IDs (from requirements), integrations + - `DataFlow` — source, target, data type, protocol + - `ADR` — ADR ID, decision, rationale (links to architectural constraints from requirements), alternatives considered, tradeoff +- **NEW**: `specfact architecture derive --requirements .specfact/requirements/ --suggest-components --interactive` — derive architecture from requirements using templates and optional AI assistance +- **NEW**: `specfact architecture validate-coverage` — verify every business rule maps to a component, every architectural constraint has an ADR, every component has spec coverage +- **NEW**: `specfact architecture trace --format table|json|markdown` — show traceability matrix: requirements ↔ components ↔ ADRs ↔ specs +- **NEW**: Storage convention: `.specfact/architecture/{architecture_id}.arch.yaml` +- **NEW**: Architecture templates for common patterns (microservice, monolith, event-driven) — profile-aware complexity +- **EXTEND**: `ProjectBundle` extended with optional `architecture` field via arch-07 schema extensions (namespace: `architecture.solution_architecture`) + +## Capabilities +### New Capabilities + +- `solution-architecture`: Derive, store, and validate solution architecture with explicit traceability to business requirements. Includes component specs, data flows, ADRs, and coverage validation. + +### Modified Capabilities + +- `data-models`: ProjectBundle extended with architecture field via arch-07 schema extensions + + +--- + +## Source Tracking + + +- **Core Counterpart Issue**: nold-ai/specfact-cli#240 +- **GitHub Issue**: #164 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/architecture-01-solution-layer/specs/data-models/spec.md b/openspec/changes/architecture-01-solution-layer/specs/data-models/spec.md new file mode 100644 index 0000000..e874f6c --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/specs/data-models/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Data Models +The system SHALL extend project-level models with an architecture namespace linked to requirements. + +#### Scenario: Architecture model references requirement IDs +- **GIVEN** a solution architecture artifact +- **WHEN** model validation runs +- **THEN** each architecture document includes requirement identifiers +- **AND** referenced IDs preserve stable cross-layer linkage. + +#### Scenario: Architecture namespace remains optional for backward compatibility +- **GIVEN** older bundles without architecture data +- **WHEN** bundle parsing runs +- **THEN** parsing succeeds +- **AND** architecture validators only run when architecture data is present. diff --git a/openspec/changes/architecture-01-solution-layer/specs/solution-architecture/spec.md b/openspec/changes/architecture-01-solution-layer/specs/solution-architecture/spec.md new file mode 100644 index 0000000..c8bd925 --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/specs/solution-architecture/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Solution Architecture +The system SHALL provide architecture derive, coverage validation, and trace outputs linked to requirements. + +#### Scenario: Derive architecture from requirements +- **GIVEN** `specfact architecture derive --requirements .specfact/requirements/ --interactive` +- **WHEN** derive completes +- **THEN** an `.arch.yaml` artifact is created +- **AND** components and ADR entries reference requirement rules. + +#### Scenario: Validate architecture coverage +- **GIVEN** requirements and architecture artifacts exist +- **WHEN** `specfact architecture validate-coverage` runs +- **THEN** unmapped business rules are reported +- **AND** missing ADRs for architectural constraints are reported. + +#### Scenario: Trace command exports architecture linkage +- **GIVEN** architecture and requirements data +- **WHEN** `specfact architecture trace --format json` runs +- **THEN** output includes requirement-to-component-to-ADR mappings +- **AND** output is consumable by full-chain validation. diff --git a/openspec/changes/architecture-01-solution-layer/tasks.md b/openspec/changes/architecture-01-solution-layer/tasks.md new file mode 100644 index 0000000..582eacb --- /dev/null +++ b/openspec/changes/architecture-01-solution-layer/tasks.md @@ -0,0 +1,30 @@ +# Tasks: architecture-01-solution-layer + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/architecture-01-solution-layer` from `dev` before implementation work: `scripts/worktree.sh create feature/architecture-01-solution-layer`. +- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. +- [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. +- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate architecture-01-solution-layer --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/architecture-01-solution-layer` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md b/openspec/changes/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md new file mode 100644 index 0000000..c0dda69 --- /dev/null +++ b/openspec/changes/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md @@ -0,0 +1,59 @@ +# Change Validation Report: backlog-kanban-01-flow-metrics + +**Validation Date**: 2026-02-10 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Format review + module architecture alignment check + +## Executive Summary + +- Breaking Changes: 0 detected +- Dependent Files: 0 (new module, no existing dependencies) +- Impact Level: Low +- Validation Result: Pass +- User Decision: N/A (no breaking changes) + +## Breaking Changes Detected + +None. This change introduces a **new module** (`modules/backlog-kanban/`) with a new CLI command (`backlog flow`). No existing code is modified. + +## Dependencies Affected + +### New Module Dependencies +- `backlog-core-01` (required): Provides backlog data access via bridge registry +- `policy-engine-01` (optional): Kanban entry/exit policy hooks +- `arch-07` (schema extensions): `backlog_kanban.flow_state` on `BacklogItem` +- `arch-05` (bridge registry): Protocol registration + +No existing dependent files are affected. + +## Impact Assessment + +- **Code Impact**: New module `modules/backlog-kanban/` only; no core code changes +- **Test Impact**: New tests in `modules/backlog-kanban/tests/` required +- **Documentation Impact**: docs/guides/agile-scrum-workflows.md — Kanban section +- **Release Impact**: Minor (new capability, backward compatible) + +## Format Validation + +- **proposal.md Format**: Pass + - Title: `# Change: Backlog Kanban — Flow Metrics and WIP/Aging Signals` + - All required sections present: Why, Module Package Structure, What Changes, Capabilities, Impact, Dependencies, Source Tracking +- **tasks.md Format**: Pass + - SDD+TDD order enforced; branch creation first, PR creation last + - Module path references updated (`modules/backlog-kanban/`) +- **Config.yaml Compliance**: Pass + - References arch-05, arch-06, arch-07 + - No direct core model modification (uses schema extensions) + +## Module Architecture Alignment + +- **arch-01/02/03**: Module declared in `module-package.yaml`; lazy-loaded by registry; no changes to `cli.py` ✓ +- **arch-04**: Contract-first via `@icontract` + `@beartype` on all public APIs ✓ +- **arch-05**: Adapter extensions via bridge registry protocols ✓ +- **arch-06**: Publisher info + integrity metadata in `module-package.yaml` ✓ +- **arch-07**: `backlog_kanban.flow_state` extension on `BacklogItem` via `module-package.yaml` ✓ +- **marketplace-01**: `specfact module install backlog-kanban` compatible ✓ + +## Previously + +Renamed from `backlog-06-kanban-flow-metrics` to reflect module-scoped naming convention. diff --git a/openspec/changes/backlog-kanban-01-flow-metrics/proposal.md b/openspec/changes/backlog-kanban-01-flow-metrics/proposal.md new file mode 100644 index 0000000..cc50ac7 --- /dev/null +++ b/openspec/changes/backlog-kanban-01-flow-metrics/proposal.md @@ -0,0 +1,102 @@ +# Change: Backlog Kanban — Flow Metrics and WIP/Aging Signals + +## Why + + +Kanban teams won't use sprint-based commands. Today SpecFact has policy-engine-01 and backlog-core-01, but no Kanban-native workflow: WIP limits, aging WIP, flow metrics (cycle time/throughput), blocked time. Without a dedicated `backlog-kanban` module providing `backlog flow` and `.specfact/kanban.yaml`, Kanban teams see SpecFact as "Scrum-only." + +This change establishes the **`backlog-kanban` module** — the Kanban-framework module that provides WIP/aging/flow metrics and Kanban-specific policy hooks. + +## Ownership Alignment (2026-04-08) + +- Authoritative implementation owner: `nold-ai/specfact-cli-modules`, backlog bundle story [#155](https://github.com/nold-ai/specfact-cli-modules/issues/155) +- Target hierarchy: modules Epic [#145](https://github.com/nold-ai/specfact-cli-modules/issues/145) -> Feature [#149](https://github.com/nold-ai/specfact-cli-modules/issues/149) -> Story `#155` +- This modules-repo proposal is the authoritative implementation change for the transferred issue. +- Implementation MUST NOT proceed in `specfact-cli` core from the legacy `modules/backlog-kanban/...` paths below. + +## Module Package Structure + +``` +modules/backlog-kanban/ + module-package.yaml # name: backlog-kanban; commands: backlog flow + src/backlog_kanban/ + __init__.py + main.py # typer.Typer app — backlog flow command group + commands/ + flow.py # specfact backlog flow + metrics/ + wip.py # WIP per column, aging WIP + cycle_time.py # cycle time, throughput (when data exists) + blocked.py # blocked time tracking + config/ + kanban_config.py # .specfact/kanban.yaml loader + integrations/ + policy_hook.py # Kanban entry/exit policies (policy-engine-01) + standup_hook.py # 'flow exceptions' section for backlog daily --mode kanban +``` + +**`module-package.yaml` declares:** +- `name: backlog-kanban` +- `version: 0.1.0` +- `commands: [backlog flow]` +- `dependencies: [backlog-core]` +- `optional_dependencies: [policy-engine]` +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +**Config**: `.specfact/kanban.yaml` — WIP limits, column definitions, aging thresholds. Separate from `.specfact/scrum.yaml` (backlog-scrum module). + +## Module Package Structure + +``` +modules/backlog-kanban/ + module-package.yaml # name: backlog-kanban; commands: backlog flow + src/backlog_kanban/ + __init__.py + main.py # typer.Typer app — backlog flow command group + commands/ + flow.py # specfact backlog flow + metrics/ + wip.py # WIP per column, aging WIP + cycle_time.py # cycle time, throughput (when data exists) + blocked.py # blocked time tracking + config/ + kanban_config.py # .specfact/kanban.yaml loader + integrations/ + policy_hook.py # Kanban entry/exit policies (policy-engine-01) + standup_hook.py # 'flow exceptions' section for backlog daily --mode kanban +``` + +**`module-package.yaml` declares:** +- `name: backlog-kanban` +- `version: 0.1.0` +- `commands: [backlog flow]` +- `dependencies: [backlog-core]` +- `optional_dependencies: [policy-engine]` +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +**Config**: `.specfact/kanban.yaml` — WIP limits, column definitions, aging thresholds. Separate from `.specfact/scrum.yaml` (backlog-scrum module). + +## What Changes + + +- **NEW**: CLI command `specfact backlog flow` in `modules/backlog-kanban/src/backlog_kanban/commands/flow.py`: WIP per column, aging WIP, cycle time/throughput (when data exists), blocked time. Declared in `module-package.yaml`; no changes to `cli.py`. +- **NEW**: Config `.specfact/kanban.yaml` for WIP limits, column definitions, aging thresholds; loaded by `modules/backlog-kanban/src/backlog_kanban/config/kanban_config.py`. +- **NEW**: Output flow metrics in machine-readable (JSON) and human-readable (Markdown) formats. +- **EXTEND** (policy-engine-01): When policy-engine-01 is present, register Kanban entry/exit policies per column; policies evaluated when kanban config exists. Graceful no-op if policy-engine-01 not installed. +- **EXTEND** (backlog-scrum-01): When `backlog daily` is run with `--mode kanban` and flow data exists, output MAY include a "flow exceptions" section (WIP/aging violations) injected by this module's standup hook. +- **EXTEND** (arch-07 schema extensions): Register `backlog_kanban.flow_state` extension on `BacklogItem` via `module-package.yaml` — stores column position, time-in-column, WIP contribution for Kanban items. + +## Capabilities +- **backlog-kanban**: `backlog flow` command; `.specfact/kanban.yaml` (WIP limits, columns, aging); flow metrics (WIP, aging, cycle time, throughput, blocked); policy-engine-01 integration for Kanban entry/exit policies; `--mode kanban` standup flow exceptions section. + +--- + +## Source Tracking + + +- **Original GitHub Issue**: nold-ai/specfact-cli#183 (transferred 2026-04-08) +- **GitHub Issue**: #155 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/backlog-kanban-01-flow-metrics/specs/kanban-flow/spec.md b/openspec/changes/backlog-kanban-01-flow-metrics/specs/kanban-flow/spec.md new file mode 100644 index 0000000..cbe0ce2 --- /dev/null +++ b/openspec/changes/backlog-kanban-01-flow-metrics/specs/kanban-flow/spec.md @@ -0,0 +1,78 @@ +# Kanban Flow Metrics (WIP, Aging, Flow) + +## ADDED Requirements + +### Requirement: backlog flow command + +The system SHALL provide `specfact backlog flow` (or `backlog flow-metrics`) that outputs Kanban flow view: WIP per column, aging WIP, cycle time/throughput when data exists, blocked time. + +**Rationale**: Δ4—Kanban-native workflow. + +#### Scenario: Run backlog flow + +**Given**: A project with backlog adapter and optional `.specfact/kanban.yaml` + +**When**: The user runs `specfact backlog flow` + +**Then**: The system outputs WIP per column, aging items, and (when available) cycle time/throughput and blocked time + +**And**: Output is available in JSON and Markdown + +**Acceptance Criteria**: + +- Command runs without error; output includes WIP and aging; cycle time/throughput when backlog supports it. +- When adapter does not provide state transitions (e.g. timestamps for column moves), the command runs in partial mode and output includes a clear disclaimer (e.g. "cycle time/throughput unavailable—partial mode"). + +### Requirement: Kanban config + +The system SHALL support `.specfact/kanban.yaml` for WIP limits, column definitions, and aging thresholds. Config SHALL integrate with Policy Engine (#176) for Kanban entry/exit policies per column. + +**Rationale**: Δ4—config-driven Kanban behavior. + +#### Scenario: Load kanban config + +**Given**: `.specfact/kanban.yaml` exists with columns and WIP limits + +**When**: The user runs `specfact backlog flow` or Policy Engine validates Kanban policies + +**Then**: The system loads kanban config and applies WIP/aging rules; missing config is handled gracefully + +**Acceptance Criteria**: + +- Config is optional; loader does not crash on missing/invalid config; Policy Engine can use columns for entry/exit. + +### Requirement: Flow metrics output + +The system SHALL produce flow metrics (WIP, aging, cycle time, throughput, blocked) in machine-readable (JSON) and human-readable (Markdown) formats. + +**Rationale**: Δ4—CI and tooling can consume flow data. + +#### Scenario: Export flow as JSON + +**Given**: `specfact backlog flow` has run + +**When**: The user requests JSON output (e.g. `--output json`) + +**Then**: The system outputs JSON with WIP per column, aging count, and optional cycle time/throughput/blocked + +**Acceptance Criteria**: + +- JSON schema includes WIP, aging, and optional flow metrics; Markdown summary is human-readable. + +### Requirement: Flow exceptions in backlog daily when Kanban mode + +The system SHALL allow `specfact backlog daily` to include an optional "flow exceptions" section (WIP/aging violations) when run with `--mode kanban` and flow data exists (e.g. when kanban-flow-metrics change is present). + +**Rationale**: Δ4 acceptance—backlog daily can include flow exceptions section when in Kanban mode. + +#### Scenario: Standup with flow exceptions in Kanban mode + +**Given**: User runs `specfact backlog daily --mode kanban` and flow data (WIP/aging) is available + +**When**: Flow exceptions section is enabled (default or flag) + +**Then**: Output MAY include a "flow exceptions" section with WIP limit violations and aging items when data exists + +**Acceptance Criteria**: + +- Flow exceptions section is optional; does not block daily when flow module or Kanban config is absent. diff --git a/openspec/changes/backlog-kanban-01-flow-metrics/tasks.md b/openspec/changes/backlog-kanban-01-flow-metrics/tasks.md new file mode 100644 index 0000000..4d00329 --- /dev/null +++ b/openspec/changes/backlog-kanban-01-flow-metrics/tasks.md @@ -0,0 +1,36 @@ +# Tasks: Backlog Kanban — Flow Metrics (Δ4) + +## TDD / SDD order (enforced) + +Per `openspec/config.yaml`, **tests before code** apply. + +1. Spec deltas define behavior in `specs/kanban-flow/spec.md`. +2. **Tests second**: Write tests from spec scenarios; run tests and **expect failure**. +3. **Code last**: Implement until tests pass. + +--- + +## 1. Create git worktree branch from dev + +- [ ] 1.1 Ensure on dev and up to date; create branch `feature/backlog-kanban-01-flow-metrics`; verify. + +## 2. Tests first (flow command, config, output) + +- [ ] 2.1 Write tests from spec: backlog flow command (WIP, aging, output format), kanban config load, JSON/Markdown output. +- [ ] 2.2 Run tests: `hatch run smart-test-unit`; **expect failure**. + +## 3. Implement Kanban Flow + +- [ ] 3.1 Implement `.specfact/kanban.yaml` loader (columns, WIP limits, aging thresholds). +- [ ] 3.2 Implement `specfact backlog flow` (WIP per column, aging, optional cycle time/throughput/blocked); JSON and Markdown output. +- [ ] 3.3 Integrate with Policy Engine (#176) for Kanban entry/exit policies when config present. +- [ ] 3.4 Run tests; **expect pass**. + +## 4. Quality gates and documentation + +- [ ] 4.1 Run format, type-check, contract-test. +- [ ] 4.2 Update docs (agile-scrum-workflows); CHANGELOG; version sync. + +## 5. Create Pull Request to dev + +- [ ] 5.1 Commit, push, create PR to dev; use repo PR template. diff --git a/openspec/changes/backlog-safe-01-pi-planning/CHANGE_VALIDATION.md b/openspec/changes/backlog-safe-01-pi-planning/CHANGE_VALIDATION.md new file mode 100644 index 0000000..9836b7b --- /dev/null +++ b/openspec/changes/backlog-safe-01-pi-planning/CHANGE_VALIDATION.md @@ -0,0 +1,54 @@ +# Change Validation Report: backlog-safe-01-pi-planning + +**Validation Date**: 2026-02-10 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Format review + module architecture alignment check + +## Executive Summary + +- Breaking Changes: 0 detected +- Dependent Files: 0 (new module, no existing dependencies) +- Impact Level: Low +- Validation Result: Pass +- User Decision: N/A (no breaking changes) + +## Breaking Changes Detected + +None. This change introduces a **new module** (`modules/backlog-safe/`) with a new CLI command (`backlog pi-summary`). No existing code is modified. + +## Dependencies Affected + +### New Module Dependencies +- `backlog-core-01` (required): Provides backlog data access, ROAM seed +- `policy-engine-01` (optional): PI readiness policy hooks +- `backlog-safe-02` (optional): Risk rollups in PI summary +- `arch-07` (schema extensions): `backlog_safe.pi_metadata` on `BacklogItem` +- `arch-05` (bridge registry): Protocol registration + +## Impact Assessment + +- **Code Impact**: New module `modules/backlog-safe/` only +- **Test Impact**: New tests in `modules/backlog-safe/tests/` required +- **Documentation Impact**: docs/guides/agile-scrum-workflows.md — SAFe section +- **Release Impact**: Minor (new capability, backward compatible) + +## Format Validation + +- **proposal.md Format**: Pass + - All required sections present: Why, Module Package Structure, What Changes, Capabilities, Impact, Dependencies, Source Tracking +- **tasks.md Format**: Pass + - SDD+TDD order enforced; branch creation first, PR creation last + - Module path references updated (`modules/backlog-safe/`) +- **Config.yaml Compliance**: Pass + +## Module Architecture Alignment + +- **arch-01/02/03**: Module declared in `module-package.yaml`; lazy-loaded; no `cli.py` changes ✓ +- **arch-05**: Bridge registry for cross-team dependency contracts ✓ +- **arch-06**: Publisher info + integrity in `module-package.yaml` ✓ +- **arch-07**: `backlog_safe.pi_metadata` extension on `BacklogItem` ✓ +- **marketplace-01**: `specfact module install backlog-safe` compatible ✓ + +## Previously + +Renamed from `backlog-07-safe-pi-planning` to reflect module-scoped naming convention. diff --git a/openspec/changes/backlog-safe-01-pi-planning/proposal.md b/openspec/changes/backlog-safe-01-pi-planning/proposal.md new file mode 100644 index 0000000..47b6127 --- /dev/null +++ b/openspec/changes/backlog-safe-01-pi-planning/proposal.md @@ -0,0 +1,100 @@ +# Change: Backlog SAFe — PI Planning and WSJF Support + +## Why + + +SAFe teams operate at PI/iteration/ART level. Today backlog-core-01 (E4) includes ROAM list seed and backlog-scrum-02 mentions SAFe usage, but there is no PI-level first-class support: no `backlog pi-summary`, no WSJF workflow, no PI readiness policy. Without a dedicated `backlog-safe` module providing `.specfact/safe.yaml` and PI artifacts, SAFe is an afterthought, not a supported framework. + +This change establishes the **`backlog-safe` module** — the SAFe-framework module that provides PI planning, WSJF assistance, and PI readiness policies. + +## Ownership Alignment (2026-04-08) + +- Authoritative implementation owner: `nold-ai/specfact-cli-modules`, backlog bundle story [#154](https://github.com/nold-ai/specfact-cli-modules/issues/154) +- Target hierarchy: modules Epic [#145](https://github.com/nold-ai/specfact-cli-modules/issues/145) -> Feature [#146](https://github.com/nold-ai/specfact-cli-modules/issues/146) -> Story `#154` +- This modules-repo proposal is the authoritative implementation change for the transferred issue. +- Implementation MUST NOT proceed in `specfact-cli` core from the legacy `modules/backlog-safe/...` paths below. + +## Module Package Structure + +``` +modules/backlog-safe/ + module-package.yaml # name: backlog-safe; commands: backlog pi-summary + src/backlog_safe/ + __init__.py + main.py # typer.Typer app — backlog pi-summary command group + commands/ + pi_summary.py # specfact backlog pi-summary + planning/ + wsjf.py # WSJF calculation + AI-assisted field proposals + pi_artifacts.py # PI scope, team commitments, ROAM seed, dependency contracts + config/ + safe_config.py # .specfact/safe.yaml loader (PI/iteration/ART settings) + integrations/ + policy_hook.py # PI readiness policy hook (policy-engine-01) + dependency_hook.py # cross-team dependency contracts from backlog-core-01 +``` + +**`module-package.yaml` declares:** +- `name: backlog-safe` +- `version: 0.1.0` +- `commands: [backlog pi-summary]` +- `dependencies: [backlog-core]` +- `optional_dependencies: [policy-engine]` +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +**Config**: `.specfact/safe.yaml` — PI/iteration/ART settings (PI number, iteration length, ART name, team names). Separate from `.specfact/scrum.yaml` and `.specfact/kanban.yaml`. + +## Module Package Structure + +``` +modules/backlog-safe/ + module-package.yaml # name: backlog-safe; commands: backlog pi-summary + src/backlog_safe/ + __init__.py + main.py # typer.Typer app — backlog pi-summary command group + commands/ + pi_summary.py # specfact backlog pi-summary + planning/ + wsjf.py # WSJF calculation + AI-assisted field proposals + pi_artifacts.py # PI scope, team commitments, ROAM seed, dependency contracts + config/ + safe_config.py # .specfact/safe.yaml loader (PI/iteration/ART settings) + integrations/ + policy_hook.py # PI readiness policy hook (policy-engine-01) + dependency_hook.py # cross-team dependency contracts from backlog-core-01 +``` + +**`module-package.yaml` declares:** +- `name: backlog-safe` +- `version: 0.1.0` +- `commands: [backlog pi-summary]` +- `dependencies: [backlog-core]` +- `optional_dependencies: [policy-engine]` +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +**Config**: `.specfact/safe.yaml` — PI/iteration/ART settings (PI number, iteration length, ART name, team names). Separate from `.specfact/scrum.yaml` and `.specfact/kanban.yaml`. + +## What Changes + + +- **NEW**: CLI command `specfact backlog pi-summary` in `modules/backlog-safe/src/backlog_safe/commands/pi_summary.py`: PI scope, team commitments, cross-team dependency contracts, ROAM items (from backlog-core-01 E4 when available). Declared in `module-package.yaml`; no changes to `cli.py`. +- **NEW**: Config `.specfact/safe.yaml` for PI/iteration/ART settings; loaded by `modules/backlog-safe/src/backlog_safe/config/safe_config.py`. +- **NEW**: WSJF assistance in `modules/backlog-safe/src/backlog_safe/planning/wsjf.py`: calculation with AI-assisted missing-field proposals and confirmation; output as JSON and Markdown. +- **EXTEND** (policy-engine-01): When policy-engine-01 is present, register PI readiness policy hooks; evaluated when safe config exists. Graceful no-op if policy-engine-01 not installed. +- **EXTEND** (backlog-core-01): Cross-team dependency contracts and ROAM seed from backlog-core-01 E4 feed PI summary when available. +- **EXTEND** (arch-07 schema extensions): Register `backlog_safe.pi_metadata` extension on `BacklogItem` via `module-package.yaml` — stores PI number, ART assignment, WSJF score for SAFe items. + +## Capabilities +- **backlog-safe** (PI planning): `backlog pi-summary` command; `.specfact/safe.yaml` (PI/iteration/ART); WSJF assistance (calculation + AI-assisted fields + confirmation); PI readiness in policy-engine-01; cross-team dependency contracts from backlog-core-01. + +--- + +## Source Tracking + + +- **Original GitHub Issue**: nold-ai/specfact-cli#184 (transferred 2026-04-08) +- **GitHub Issue**: #154 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/backlog-safe-01-pi-planning/specs/safe-pi/spec.md b/openspec/changes/backlog-safe-01-pi-planning/specs/safe-pi/spec.md new file mode 100644 index 0000000..5ad6179 --- /dev/null +++ b/openspec/changes/backlog-safe-01-pi-planning/specs/safe-pi/spec.md @@ -0,0 +1,65 @@ +# SAFe PI Planning (PI summary, WSJF, PI readiness) + +## ADDED Requirements + +### Requirement: backlog pi-summary command + +The system SHALL provide `specfact backlog pi-summary` that outputs PI-level summary: PI scope, team commitments, cross-team dependency contracts, ROAM items (when available from dependency analysis). + +**Rationale**: Δ5—SAFe-first workflow. + +#### Scenario: Run pi-summary + +**Given**: A project with backlog adapter and optional `.specfact/safe.yaml` and dependency/ROAM data (#116) + +**When**: The user runs `specfact backlog pi-summary` + +**Then**: The system outputs PI scope, commitments, dependency contracts, and ROAM items when available + +**And**: Output is available in JSON and Markdown + +**And**: PI summary SHALL include a ROAM-ready Markdown table (e.g. risks/obstacles/assumptions/mitigations) when ROAM data is available + +**Acceptance Criteria**: + +- Command runs without error; output includes PI scope and (when data exists) commitments, dependency contracts, ROAM. +- PI summary includes a ROAM-ready Markdown table when ROAM data is available. + +### Requirement: SAFe config and PI readiness + +The system SHALL support `.specfact/safe.yaml` for PI/iteration/ART settings. Config SHALL integrate with Policy Engine (#176) for PI readiness policy hooks. + +**Rationale**: Δ5—config-driven SAFe behavior. + +#### Scenario: Load safe config + +**Given**: `.specfact/safe.yaml` exists with PI/iteration settings + +**When**: The user runs `specfact backlog pi-summary` or Policy Engine validates PI readiness + +**Then**: The system loads safe config and applies PI readiness rules; missing config is handled gracefully + +**Acceptance Criteria**: + +- Config is optional; Policy Engine can use PI readiness policy when config present. + +### Requirement: WSJF assistance + +The system SHALL provide WSJF calculation with AI-assisted missing-field proposals and user confirmation; output as JSON and Markdown. No automatic write without confirmation. + +**Rationale**: Δ5—WSJF for prioritization without silent writes. + +#### Scenario: WSJF with missing fields + +**Given**: User requests WSJF for a set of items with some missing WSJF fields + +**When**: The system runs WSJF assistance + +**Then**: The system proposes missing field values (e.g. job size, value) with confidence; user confirms before apply + +**And**: Output includes WSJF score and optional patch for fields + +**Acceptance Criteria**: + +- WSJF calculation is deterministic when fields present; AI-assisted proposals require confirmation; no silent writes. +- WSJF AI-assisted field proposals are applied only with explicit user confirmation or when user invokes with `--write` (per patch-mode / write gating); AI proposals never write fields without `--write`. diff --git a/openspec/changes/backlog-safe-01-pi-planning/tasks.md b/openspec/changes/backlog-safe-01-pi-planning/tasks.md new file mode 100644 index 0000000..2d71e9e --- /dev/null +++ b/openspec/changes/backlog-safe-01-pi-planning/tasks.md @@ -0,0 +1,36 @@ +# Tasks: Backlog SAFe — PI Planning (Δ5) + +## TDD / SDD order (enforced) + +Per `openspec/config.yaml`, **tests before code** apply. + +1. Spec deltas define behavior in `specs/safe-pi/spec.md`. +2. **Tests second**: Write tests from spec scenarios; run tests and **expect failure**. +3. **Code last**: Implement until tests pass. + +--- + +## 1. Create git worktree branch from dev + +- [ ] 1.1 Ensure on dev and up to date; create branch `feature/backlog-safe-01-pi-planning`; verify. + +## 2. Tests first (pi-summary, config, WSJF) + +- [ ] 2.1 Write tests from spec: pi-summary command (scope, commitments, ROAM), safe config load, WSJF calculation and confirmation. +- [ ] 2.2 Run tests: `hatch run smart-test-unit`; **expect failure**. + +## 3. Implement SAFe PI + +- [ ] 3.1 Implement `.specfact/safe.yaml` loader (PI/iteration/ART); Policy Engine PI readiness hook. +- [ ] 3.2 Implement `specfact backlog pi-summary` (scope, commitments, dependency contracts, ROAM); JSON and Markdown output. +- [ ] 3.3 Implement WSJF assistance (calculation, AI-assisted missing fields, confirmation; no silent write). +- [ ] 3.4 Run tests; **expect pass**. + +## 4. Quality gates and documentation + +- [ ] 4.1 Run format, type-check, contract-test. +- [ ] 4.2 Update docs (agile-scrum-workflows); CHANGELOG; version sync. + +## 5. Create Pull Request to dev + +- [ ] 5.1 Commit, push, create PR to dev; use repo PR template. diff --git a/openspec/changes/backlog-safe-02-risk-rollups/CHANGE_VALIDATION.md b/openspec/changes/backlog-safe-02-risk-rollups/CHANGE_VALIDATION.md new file mode 100644 index 0000000..59f1ea0 --- /dev/null +++ b/openspec/changes/backlog-safe-02-risk-rollups/CHANGE_VALIDATION.md @@ -0,0 +1,54 @@ +# Change Validation Report: backlog-safe-02-risk-rollups + +**Validation Date**: 2026-02-10 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Format review + module architecture alignment check + +## Executive Summary + +- Breaking Changes: 0 detected +- Dependent Files: 0 (extends existing backlog-safe module; new subpackage) +- Impact Level: Low +- Validation Result: Pass +- User Decision: N/A (no breaking changes) + +## Breaking Changes Detected + +None. Risk rollups extend the `modules/backlog-safe/` module with a new `risk/` subpackage. All inputs are consumed via bridge registry protocols and are optional. + +## Dependencies Affected + +### Optional Risk Input Protocols (arch-05 bridge registry) +All inputs are optional; risk model degrades gracefully: +- `backlog-core-01`: BacklogCoreDependencyProtocol (dependency criticality) +- `policy-engine-01`: PolicyEngineProtocol (policy failures) +- `backlog-scrum-02/03`: BacklogScrumCapacityProtocol / BacklogScrumComplexityProtocol +- `backlog-kanban-01`: BacklogKanbanFlowProtocol (WIP violations) + +No breaking changes to any existing module. + +## Impact Assessment + +- **Code Impact**: New `risk/` subpackage in `modules/backlog-safe/` +- **Test Impact**: New tests in `modules/backlog-safe/tests/risk/` required +- **Documentation Impact**: docs/guides/agile-scrum-workflows.md — risk model section +- **Release Impact**: Minor (new capability, backward compatible) + +## Format Validation + +- **proposal.md Format**: Pass + - All required sections present including `## Risk Input Contract (arch-05 bridge registry)` +- **tasks.md Format**: Pass + - SDD+TDD order; branch first, PR last; module paths updated +- **Config.yaml Compliance**: Pass + +## Module Architecture Alignment + +- **arch-05**: Risk input protocols registered via bridge registry; graceful degradation ✓ +- **arch-06**: Publisher info + integrity in `module-package.yaml` ✓ +- **arch-07**: `backlog_safe.risk_score` extension on `BacklogItem` ✓ +- **Cross-ceremony integration**: Risk hooks injected into standup, refinement, sprint-summary, pi-summary via integration.py ✓ + +## Previously + +Renamed from `backlog-08-risk-rollups` to reflect module-scoped naming convention. diff --git a/openspec/changes/backlog-safe-02-risk-rollups/proposal.md b/openspec/changes/backlog-safe-02-risk-rollups/proposal.md new file mode 100644 index 0000000..30777c0 --- /dev/null +++ b/openspec/changes/backlog-safe-02-risk-rollups/proposal.md @@ -0,0 +1,76 @@ +# Change: Backlog SAFe — Explainable Risk Rollups + +## Why + + +Every ceremony (standup, refinement, sprint summary, PI planning, release readiness) needs a consistent risk model with explainable inputs. Today risk is mentioned piecemeal in extensions but not modeled or wired. A single risk rollup mechanism — dependency criticality, policy failures, complexity flags, capacity overage, aging/WIP violations — makes all commands "exceptions-first" by default and gives teams one place to see "what might blow up." + +Risk rollups are part of the **`backlog-safe` module** — they live here because risk is cross-ceremony (standup, refinement, sprint, PI) and the SAFe framework explicitly requires explainable risk tracking (ROAM, risk metrics). Scrum and Kanban teams benefit from risk rollups through integration hooks. + +## Ownership Alignment (2026-04-08) + +- Authoritative implementation owner: `nold-ai/specfact-cli-modules`, backlog bundle story [#156](https://github.com/nold-ai/specfact-cli-modules/issues/156) +- Target hierarchy: modules Epic [#145](https://github.com/nold-ai/specfact-cli-modules/issues/145) -> Feature [#146](https://github.com/nold-ai/specfact-cli-modules/issues/146) -> Story `#156` +- This modules-repo proposal is the authoritative implementation change for the transferred issue. +- Implementation MUST NOT proceed in `specfact-cli` core from the legacy `modules/backlog-safe/...` paths below. + +## Module Package Structure + +``` +modules/backlog-safe/ + module-package.yaml # updated: risk model available as cross-ceremony capability + src/backlog_safe/ + risk/ + model.py # Risk model (inputs, scoring, contributions) + rollup.py # Risk aggregation (low/medium/high) with traceable inputs + integrations.py # hooks into standup, refinement, sprint-summary, pi-summary, verify-readiness +``` + +**Risk is a shared capability within `backlog-safe` module** — other modules (backlog-scrum, backlog-kanban) access risk rollups via the bridge registry by resolving the risk capability from backlog-safe. + +## Module Package Structure + +``` +modules/backlog-safe/ + module-package.yaml # updated: risk model available as cross-ceremony capability + src/backlog_safe/ + risk/ + model.py # Risk model (inputs, scoring, contributions) + rollup.py # Risk aggregation (low/medium/high) with traceable inputs + integrations.py # hooks into standup, refinement, sprint-summary, pi-summary, verify-readiness +``` + +**Risk is a shared capability within `backlog-safe` module** — other modules (backlog-scrum, backlog-kanban) access risk rollups via the bridge registry by resolving the risk capability from backlog-safe. + +## What Changes + + +- **NEW**: Risk model in `modules/backlog-safe/src/backlog_safe/risk/model.py` with inputs: dependency criticality (from backlog-core-01), policy failures (from policy-engine-01), complexity flags (from backlog-scrum-03), capacity overage (from backlog-scrum-02), aging/WIP violations (from backlog-kanban-01). +- **NEW**: Risk aggregation in `modules/backlog-safe/src/backlog_safe/risk/rollup.py`: single rollup score (low/medium/high); JSON output with input contributions, reasons, and evidence pointers; optional configurable weights. +- **NEW**: Integrate risk rollup into standup, refinement, sprint-summary, PI summary, and `backlog verify-readiness` (release) via `modules/backlog-safe/src/backlog_safe/risk/integrations.py` — each command surfaces a risk section when `backlog-safe` is installed. +- **EXTEND** (arch-07 schema extensions): Register `backlog_safe.risk_score` extension on `BacklogItem` via `module-package.yaml` — stores computed risk level (low/medium/high) and contributing factors for each item. + +## Risk Input Contract (arch-05 bridge registry) +Risk inputs are consumed via the bridge registry — each contributing module exposes a protocol that the risk model queries: +- `BacklogCoreDependencyProtocol` → dependency criticality +- `PolicyEngineProtocol` → policy failures +- `BacklogScrumComplexityProtocol` → complexity flags +- `BacklogScrumCapacityProtocol` → capacity overage +- `BacklogKanbanFlowProtocol` → aging/WIP violations + +All inputs are optional; risk model degrades gracefully with available data. + +## Capabilities +- **backlog-safe** (risk rollups): Risk model with configurable inputs; single rollup score (low/medium/high); JSON output with input contributions, reasons, evidence pointers; integration with standup, refinement, sprint-summary, pi-summary, verify-readiness. + +--- + +## Source Tracking + + +- **Original GitHub Issue**: nold-ai/specfact-cli#182 (transferred 2026-04-08) +- **GitHub Issue**: #156 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/backlog-safe-02-risk-rollups/specs/risk-rollups/spec.md b/openspec/changes/backlog-safe-02-risk-rollups/specs/risk-rollups/spec.md new file mode 100644 index 0000000..b63c8f0 --- /dev/null +++ b/openspec/changes/backlog-safe-02-risk-rollups/specs/risk-rollups/spec.md @@ -0,0 +1,77 @@ +# Risk Rollups (Explainable, Traceable) + +## ADDED Requirements + +### Requirement: Risk model with configurable inputs + +The system SHALL provide a Risk model that aggregates inputs: dependency criticality, policy failures (DoR/DoD/flow), complexity flags, capacity overage, aging/WIP violations. Inputs SHALL be configurable so teams can enable/disable sources. + +**Rationale**: Δ6—single substrate for "what might blow up" across ceremonies. + +#### Scenario: Compute risk rollup + +**Given**: A project with dependency graph and policy results (and optional capacity/complexity data) + +**When**: The system computes risk rollup + +**Then**: The system aggregates enabled inputs and produces a single score (low/medium/high) + +**And**: Output includes traceable contributions: each input with reason and evidence pointer + +**Acceptance Criteria**: + +- Rollup score is low/medium/high; JSON output includes `contributions` array with source, reason, evidence pointer, and optional weight (contribution weight for explainability). + +### Requirement: Risk rollup JSON output + +The system SHALL produce machine-readable risk output: JSON with rollup score, contributions (source, reason, evidence pointer), and optional human-readable summary. + +**Rationale**: Δ6—CI gates and tooling can consume risk without parsing prose. + +#### Scenario: Export risk as JSON + +**Given**: Risk rollup has been computed + +**When**: The user requests JSON output (e.g. `--output json` or risk subcommand) + +**Then**: The system outputs JSON with score, contributions array, and optional summary field + +**Acceptance Criteria**: + +- JSON schema includes score (enum: low/medium/high), contributions (array of { source, reason, evidence, optional weight }). + +### Requirement: Risk integration in backlog commands + +The system SHALL allow standup, refinement, and sprint-summary commands to include an optional risk section (rollup + top contributions) when risk data is available. + +**Rationale**: Δ6—every ceremony can be exceptions-first. + +#### Scenario: Standup shows risk section + +**Given**: `specfact backlog daily` is run and dependency/policy (and optional capacity) data exists + +**When**: Risk rollup is enabled (default or flag) + +**Then**: Output includes a risk section with rollup score and top contributions (or "No significant risk" when low) + +**Acceptance Criteria**: + +- Risk section is present when enabled; does not block command when risk module or dependencies are unavailable. + +### Requirement: Risk integration in verify-readiness (release) + +When `backlog verify-readiness` (or equivalent release-readiness command) exists, the system SHALL allow it to include an optional risk section (rollup + top contributions) so release view includes risk. + +**Rationale**: Δ6—risk used in verify-readiness (release) per 2026-02-01. + +#### Scenario: Verify-readiness shows risk section + +**Given**: `specfact backlog verify-readiness` (or equivalent) is run and risk data is available + +**When**: Risk rollup is enabled (default or flag) + +**Then**: Output MAY include a risk section with rollup score and top contributions when the command is implemented + +**Acceptance Criteria**: + +- When verify-readiness command exists, risk section is integrable; does not block when risk module is absent. diff --git a/openspec/changes/backlog-safe-02-risk-rollups/tasks.md b/openspec/changes/backlog-safe-02-risk-rollups/tasks.md new file mode 100644 index 0000000..3555062 --- /dev/null +++ b/openspec/changes/backlog-safe-02-risk-rollups/tasks.md @@ -0,0 +1,36 @@ +# Tasks: Backlog SAFe — Risk Rollups (Δ6) + +## TDD / SDD order (enforced) + +Per `openspec/config.yaml`, **tests before code** apply. + +1. Spec deltas define behavior in `specs/risk-rollups/spec.md`. +2. **Tests second**: Write tests from spec scenarios; run tests and **expect failure**. +3. **Code last**: Implement until tests pass. + +--- + +## 1. Create git worktree branch from dev + +- [ ] 1.1 Ensure on dev and up to date; create branch `feature/backlog-safe-02-risk-rollups`; verify. + +## 2. Tests first (risk model, rollup, JSON output) + +- [ ] 2.1 Write tests from spec: risk model inputs aggregation, rollup score (low/medium/high), JSON output shape (score, contributions). +- [ ] 2.2 Run tests: `hatch run smart-test-unit`; **expect failure**. + +## 3. Implement Risk Rollups + +- [ ] 3.1 Implement risk model (configurable inputs: dependency criticality, policy failures, complexity, capacity, aging/WIP). +- [ ] 3.2 Implement rollup aggregation and JSON output (score, contributions with source, reason, evidence). +- [ ] 3.3 Integrate risk section into backlog daily (and optionally refine, sprint-summary) when data available. +- [ ] 3.4 Run tests; **expect pass**. + +## 4. Quality gates and documentation + +- [ ] 4.1 Run format, type-check, contract-test. +- [ ] 4.2 Update docs (agile-scrum-workflows); CHANGELOG; version sync. + +## 5. Create Pull Request to dev + +- [ ] 5.1 Commit, push, create PR to dev; use repo PR template. diff --git a/openspec/changes/backlog-scrum-02-sprint-planning/CHANGE_VALIDATION.md b/openspec/changes/backlog-scrum-02-sprint-planning/CHANGE_VALIDATION.md new file mode 100644 index 0000000..7160a42 --- /dev/null +++ b/openspec/changes/backlog-scrum-02-sprint-planning/CHANGE_VALIDATION.md @@ -0,0 +1,41 @@ +# Change Validation Report: backlog-scrum-02-sprint-planning + +**Validation Date**: 2026-02-02 +**Plan Reference**: specfact-cli-internal/docs/internal/implementation/2026-02-01-backlog-changes-improvement.md (E2) +**Validation Method**: Plan alignment + OpenSpec strict validation + +## Executive Summary + +- **Plan Enhancement (E2)**: Sprint summary extended with risk rollup, DoR coverage, optional sprint_goal and alignment hints. +- **Breaking Changes**: 0 (additive only). +- **Validation Result**: Pass. +- **OpenSpec Validation**: `openspec validate sprint-planning-capacity-commitment-support --strict` — valid. + +## Alignment with Plan E2 + +- **E2**: Extend sprint-planning with risk + goal alignment. **Done**: proposal.md and specs/sprint-planning/spec.md updated with optional sprint_goal, risk rollup (explainable-risk-rollups), DoR coverage (Policy Engine); acceptance: sprint summary includes capacity, committed, risk, top blockers, DoR pass rate. + +## USP / Value-Add + +- **Trust by design**: Sprint summary remains read-only; risk/DoR are reported, not auto-applied. +- **One policy engine**: DoR coverage integrates with unify-policies-engine when available. +- **Measurable**: Capacity, committed, risk, DoR pass rate in one view supports “Loved” metric (plan). + +## Format Validation + +- proposal.md: Required sections (Why, What Changes, Capabilities, Impact) present; E2 extension and acceptance criteria added. +- specs: Given/When/Then for new requirement (Sprint summary with risk and DoR). +- tasks.md: Existing structure retained; no format issues. + +## Module Architecture Alignment (Re-validated 2026-02-10) + +This change was re-validated after renaming and updating to align with the modular architecture (arch-01 through arch-07): + +- Module package structure updated to `modules/{name}/module-package.yaml` pattern +- CLI command registration moved from `cli.py` to `module-package.yaml` declarations +- Core model modifications replaced with arch-07 schema extensions where applicable +- Adapter protocol extensions use arch-05 bridge registry (no direct mixin modification) +- Publisher and integrity metadata added for arch-06 marketplace readiness +- All old change ID references updated to new module-scoped naming + +**Result**: Pass — format compliant, module architecture aligned, no breaking changes introduced. diff --git a/openspec/changes/backlog-scrum-02-sprint-planning/design.md b/openspec/changes/backlog-scrum-02-sprint-planning/design.md new file mode 100644 index 0000000..a68b444 --- /dev/null +++ b/openspec/changes/backlog-scrum-02-sprint-planning/design.md @@ -0,0 +1,28 @@ +# Design: Sprint planning (capacity and commitment) support + +## Capacity config and commitment aggregation + +- **Config**: Sprint capacity config schema (e.g. YAML) with sprint identifier → capacity (story points). Store in `.specfact/sprint_capacity.yaml` or similar. Load from project; handle missing/invalid config without crash. +- **Commitment**: Sum BacklogItem.story_points for items where BacklogItem.sprint matches the requested sprint. Commitment is adapter-agnostic (derived from existing BacklogItem data). +- **Integration**: New subcommand under backlog group: `specfact backlog sprint-summary` (optional `--sprint `). Output: sprint id, committed points, capacity (if configured), gap (over/under). No top-level `specfact sprint` command. + +## Sequence (sprint summary) + +``` +User → specfact backlog sprint-summary [--sprint ] + → CLI loads .specfact/sprint_capacity.yaml (if present) + → CLI fetches backlog items (existing adapter) or uses cached list + → Filter items by sprint (if --sprint given) + → Sum story_points per sprint + → For each sprint: compare sum to capacity (if config present) + → Output: sprint, committed, capacity, gap (over/under) +``` + +## Contract enforcement + +- Capacity loader and commitment aggregator shall have @icontract and @beartype where they are public APIs. +- Backlog command: additive only; default behavior unchanged. + +## Fallback / offline + +- Capacity config is read from local project; no network required for config load. Commitment uses backlog item data (from adapter/cache); offline if data already available. diff --git a/openspec/changes/backlog-scrum-02-sprint-planning/proposal.md b/openspec/changes/backlog-scrum-02-sprint-planning/proposal.md new file mode 100644 index 0000000..52b0095 --- /dev/null +++ b/openspec/changes/backlog-scrum-02-sprint-planning/proposal.md @@ -0,0 +1,66 @@ +# Change: Backlog Scrum — Sprint Planning and Capacity Commitment + +## Why + + +SpecFact CLI supports sprint/release assignment and story points at the backlog-item level, but there is no first-class support for sprint capacity (available story points per sprint), commitment vs capacity comparison (over/under committed), or a CLI/export view that shows sprint-level summary. Teams must manually sum story points and compare to capacity outside SpecFact. + +This change is part of the **`backlog-scrum` module** — the Scrum-framework module. Sprint planning is delivered as a capability of the same module as standup (backlog-scrum-01). + +## Ownership Alignment (2026-04-08) + +- Authoritative implementation owner: `nold-ai/specfact-cli-modules`, backlog bundle story [#160](https://github.com/nold-ai/specfact-cli-modules/issues/160) +- Target hierarchy: modules Epic [#145](https://github.com/nold-ai/specfact-cli-modules/issues/145) -> Feature [#151](https://github.com/nold-ai/specfact-cli-modules/issues/151) -> Story `#160` +- This modules-repo proposal is the authoritative implementation change for the transferred issue. +- Implementation MUST NOT proceed in `specfact-cli` core from the legacy `modules/backlog-scrum/...` paths below. + +## Module Package Structure + +``` +modules/backlog-scrum/ + module-package.yaml # updated: add 'backlog sprint-summary' to commands + src/backlog_scrum/ + commands/ + sprint_summary.py # specfact backlog sprint-summary + planning/ + capacity.py # sprint capacity config loading, commitment aggregation +``` + +**Config**: Sprint capacity stored in `.specfact/scrum.yaml` (all Scrum-specific config consolidated here). + +## Module Package Structure + +``` +modules/backlog-scrum/ + module-package.yaml # updated: add 'backlog sprint-summary' to commands + src/backlog_scrum/ + commands/ + sprint_summary.py # specfact backlog sprint-summary + planning/ + capacity.py # sprint capacity config loading, commitment aggregation +``` + +**Config**: Sprint capacity stored in `.specfact/scrum.yaml` (all Scrum-specific config consolidated here). + +## What Changes + + +- **NEW**: Sprint capacity config via `.specfact/scrum.yaml` — capacity in story points per sprint identifier; loaded by `modules/backlog-scrum/src/backlog_scrum/planning/capacity.py`. +- **NEW**: When listing or exporting backlog items filtered by sprint, compute total story points and compare to capacity (if configured). +- **NEW**: CLI command `specfact backlog sprint-summary` in `modules/backlog-scrum/src/backlog_scrum/commands/sprint_summary.py`: sprint id, total committed points, capacity, difference (over/under). Declared in `module-package.yaml`; no changes to `cli.py`. +- **EXTEND** (plan E2): Optional `sprint_goal` support in `.specfact/scrum.yaml`; show alignment hints. Include risk rollup section from backlog-safe-02 when present. Add "DoR coverage" summary via policy-engine-01 when present. + +## Capabilities +- **backlog-scrum** (sprint planning): Capacity config load from `.specfact/scrum.yaml`; commitment sum by sprint; over/under comparison; `backlog sprint-summary` CLI/export; optional sprint_goal and alignment hints; risk rollup and DoR coverage when backlog-safe-02 and policy-engine-01 are available. + +--- + +## Source Tracking + + +- **Original GitHub Issue**: nold-ai/specfact-cli#170 (transferred 2026-04-08) +- **GitHub Issue**: #160 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md b/openspec/changes/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md new file mode 100644 index 0000000..8c97082 --- /dev/null +++ b/openspec/changes/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md @@ -0,0 +1,95 @@ +# Sprint planning (capacity and commitment) + +## ADDED Requirements + +### Requirement: Sprint capacity configuration + +The system SHALL support loading sprint capacity configuration from project config (e.g. `.specfact/sprint_capacity.yaml`) mapping sprint identifiers to available story points per sprint. + +**Rationale**: Teams need to define capacity (e.g. velocity or available points) per sprint to compare with commitment. + +#### Scenario: Load sprint capacity config from project + +**Given**: A project with a sprint capacity config file (e.g. `.specfact/sprint_capacity.yaml`) defining capacity per sprint (e.g. sprint_1: 40, sprint_2: 38) + +**When**: The user runs a backlog command that uses sprint summary (e.g. `specfact backlog sprint-summary` or equivalent) + +**Then**: The system loads the capacity config and uses it for comparison + +**And**: If no capacity config exists, the system shows committed points only or a clear message that capacity is not configured + +**Acceptance Criteria**: + +- Capacity config schema is documented; loader does not crash on missing or invalid config (report clearly). + +### Requirement: Commitment sum by sprint + +The system SHALL compute total committed story points per sprint from backlog items assigned to that sprint (BacklogItem.sprint + story_points). + +**Rationale**: Commitment is derived from items in the sprint; no manual sum required. + +#### Scenario: Sum committed points for a sprint + +**Given**: Backlog items with sprint assignment and story_points (e.g. items A, B, C in sprint_1 with points 13, 8, 5) + +**When**: The user requests sprint summary for that sprint (e.g. `specfact backlog sprint-summary --sprint sprint_1`) + +**Then**: The system sums story_points for all items in that sprint and reports total committed points (e.g. 26) + +**Acceptance Criteria**: + +- Sum is deterministic; items without story_points are treated as 0 or excluded per documented behavior. + +### Requirement: Over/under commitment output + +The system SHALL compare total committed points to capacity (when configured) and report over-commitment (committed > capacity) or under-commitment/slack (committed < capacity). + +**Rationale**: Teams need to see at a glance whether the sprint is over or under committed. + +#### Scenario: Sprint summary with capacity comparison + +**Given**: Capacity for sprint_1 is 40 points and committed points from backlog items are 26 + +**When**: The user runs `specfact backlog sprint-summary` for that sprint + +**Then**: The output shows sprint id, total committed points, capacity, and difference (e.g. sprint_1, committed: 26, capacity: 40, gap: -14 or "under by 14") + +**Acceptance Criteria**: + +- Output is readable (CLI and/or export); when capacity is not configured, show committed only; over-commitment shows positive gap or "over by X". + +### Requirement: Sprint summary under backlog group + +The system SHALL expose sprint summary under the backlog command group (e.g. `specfact backlog sprint-summary`); there SHALL be no top-level `specfact sprint` command. + +**Rationale**: Align with other scrum/backlog features under `specfact backlog`. + +#### Scenario: Invoke sprint summary via backlog + +**Given**: SpecFact CLI is installed and project has backlog and optional capacity config + +**When**: The user runs `specfact backlog sprint-summary` (with optional `--sprint `) + +**Then**: The command runs and outputs sprint-level summary (committed, capacity if configured, gap) + +**Acceptance Criteria**: + +- Command is discoverable under `specfact backlog --help`; behavior matches spec scenarios above. + +### Requirement: Sprint summary with risk and DoR (E2 extension) + +The system SHALL include in sprint summary output (when dependencies are available): risk rollup (top blockers, risk level), and DoR coverage (pass rate for sprint scope) via Policy Engine. Optional sprint_goal in config SHALL be shown as alignment hint when present. + +**Rationale**: Plan E2—teams need capacity, committed, risk, top blockers, and DoR pass rate in one view. + +#### Scenario: Sprint summary includes risk and DoR + +**Given**: Policy Engine (unify-policies-engine) and risk rollups (explainable-risk-rollups) are available; sprint has items with DoR state + +**When**: The user runs `specfact backlog sprint-summary` for that sprint + +**Then**: The output includes capacity, committed, and when available: risk level, top blockers, DoR pass rate; if sprint_goal is in config, show alignment hint + +**Acceptance Criteria**: + +- Sprint summary includes: capacity, committed, risk (when available), top blockers (when available), DoR pass rate (when Policy Engine available). Optional sprint_goal and alignment hints. diff --git a/openspec/changes/backlog-scrum-02-sprint-planning/tasks.md b/openspec/changes/backlog-scrum-02-sprint-planning/tasks.md new file mode 100644 index 0000000..adf8e92 --- /dev/null +++ b/openspec/changes/backlog-scrum-02-sprint-planning/tasks.md @@ -0,0 +1,73 @@ +# Tasks: Backlog Scrum — Sprint Planning (capacity and commitment) support + +## TDD / SDD order (enforced) + +Per `openspec/config.yaml`, **tests before code** apply to any task that adds or changes behavior. + +1. **Spec deltas** define behavior (Given/When/Then) in `openspec/changes/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md`. +2. **Tests second**: Write unit/integration tests from those scenarios; run tests and **expect failure** (no implementation yet). +3. **Code last**: Implement until tests pass and behavior satisfies the spec. + +Do not implement production code for new behavior until the corresponding tests exist and have been run (expecting failure). + +--- + +## 1. Create git worktree branch from dev + +- [ ] 1.1 Ensure primary checkout is on dev and up to date: `git checkout dev && git pull origin dev` +- [ ] 1.2 Create dedicated worktree branch (preferred): `scripts/worktree.sh create feature/backlog-scrum-02-sprint-planning`; if issue exists, link branch to issue with `gh issue develop 170 --repo nold-ai/specfact-cli --name feature/backlog-scrum-02-sprint-planning` +- [ ] 1.3 Or create worktree branch without issue link: `scripts/worktree.sh create feature/backlog-scrum-02-sprint-planning` (if no issue yet) +- [ ] 1.4 Verify branch in worktree: `git worktree list` includes the branch path; then run `git branch --show-current` inside that worktree. + +## 2. Create GitHub issue in nold-ai/specfact-cli (mandatory) + +- [ ] 2.1 Create issue in nold-ai/specfact-cli: `gh issue create --repo nold-ai/specfact-cli --title "[Change] Sprint planning (capacity and commitment) support" --body-file --label "enhancement" --label "change-proposal"` +- [ ] 2.2 Use body from proposal (Why, What Changes, Acceptance Criteria); add footer `*OpenSpec Change Proposal: sprint-planning-capacity-commitment-support*` +- [ ] 2.3 Update `proposal.md` Source Tracking section with issue number, issue URL, repository nold-ai/specfact-cli, Last Synced Status: proposed +- [ ] 2.4 Link issue to project (optional): `gh project item-add 1 --owner nold-ai --url ` (requires `gh auth refresh -s project` if needed) + +## 3. Verify spec deltas (SDD: specs first) + +- [ ] 3.1 Confirm `specs/sprint-planning/spec.md` exists and is complete (ADDED requirements, Given/When/Then for capacity config, commitment sum, over/under output). +- [ ] 3.2 Map scenarios to implementation: load capacity config, sum story_points by sprint, compare to capacity, output sprint-summary. + +## 4. Tests first (TDD: write tests from spec scenarios; expect failure) + +- [ ] 4.1 Write unit or integration tests from `specs/sprint-planning/spec.md` scenarios: capacity config load (present/missing); commitment sum per sprint; over/under comparison; sprint-summary output format. +- [ ] 4.2 Run tests: `hatch run smart-test-unit` (or equivalent); **expect failure** (no implementation yet). +- [ ] 4.3 Document which scenarios are covered by which test modules. + +## 5. Implement sprint planning (TDD: code until tests pass) + +- [ ] 5.1 Define sprint capacity config schema and loader (e.g. `.specfact/sprint_capacity.yaml`); load from project; handle missing/invalid config without crash. +- [ ] 5.2 Implement commitment aggregation: sum BacklogItem.story_points by BacklogItem.sprint; ensure @icontract and @beartype on new public APIs. +- [ ] 5.3 Add `specfact backlog sprint-summary` subcommand (optional `--sprint `): output sprint id, committed points, capacity (if configured), gap (over/under). Do not add top-level `specfact sprint` command. +- [ ] 5.4 Include sprint-summary in CLI output and optionally in export when applicable. +- [ ] 5.5 Run tests again; **expect pass**; fix until all tests pass. + +## 6. Quality gates + +- [ ] 6.1 Run format and type-check: `hatch run format`, `hatch run type-check`. +- [ ] 6.2 Run contract test: `hatch run contract-test`. +- [ ] 6.3 Run full test suite: `hatch run smart-test` (or `hatch run smart-test-full`). +- [ ] 6.4 Ensure any new or modified public APIs have @icontract and @beartype where applicable. + +## 7. Documentation research and review + +- [ ] 7.1 Identify affected documentation: docs/guides/agile-scrum-workflows.md, docs/guides/backlog-refinement.md. +- [ ] 7.2 Update agile-scrum-workflows.md: add section or subsection for sprint planning with SpecFact (capacity config, commitment vs capacity, sprint-summary). +- [ ] 7.3 Update backlog-refinement.md: document sprint-summary and capacity/commitment workflow. +- [ ] 7.4 If adding a new doc page: set front-matter (layout, title, permalink, description) and update docs/_layouts/default.html sidebar if needed. + +## 8. Version and changelog (patch bump; required before PR) + +- [ ] 8.1 Bump **patch** version in `pyproject.toml` (e.g. X.Y.Z → X.Y.(Z+1)). +- [ ] 8.2 Sync version in `setup.py`, `src/__init__.py`, `src/specfact_cli/__init__.py` to match pyproject.toml. +- [ ] 8.3 Add CHANGELOG.md entry under new [X.Y.Z] - YYYY-MM-DD section: **Added** – Sprint planning (capacity and commitment) support: `specfact backlog sprint-summary`, capacity config, commitment vs capacity comparison. + +## 9. Create Pull Request to dev + +- [ ] 9.1 Ensure all changes are committed: `git add .` and `git commit -m "feat(backlog): add sprint planning capacity and commitment support"` +- [ ] 9.2 Push to remote: `git push origin feature/backlog-scrum-02-sprint-planning` +- [ ] 9.3 Create PR: `gh pr create --repo nold-ai/specfact-cli --base dev --head feature/backlog-scrum-02-sprint-planning --title "feat(backlog): add sprint planning capacity and commitment support" --body-file ` (use repo PR template; add OpenSpec change ID `backlog-scrum-02-sprint-planning` and summary; reference GitHub issue with `Fixes nold-ai/specfact-cli#170`). +- [ ] 9.4 Verify PR and branch are linked to issue in Development section. diff --git a/openspec/changes/backlog-scrum-03-story-complexity/CHANGE_VALIDATION.md b/openspec/changes/backlog-scrum-03-story-complexity/CHANGE_VALIDATION.md new file mode 100644 index 0000000..2428c9a --- /dev/null +++ b/openspec/changes/backlog-scrum-03-story-complexity/CHANGE_VALIDATION.md @@ -0,0 +1,40 @@ +# Change Validation Report: backlog-scrum-03-story-complexity + +**Validation Date**: 2026-02-02 +**Plan Reference**: specfact-cli-internal/docs/internal/implementation/2026-02-01-backlog-changes-improvement.md (E3) +**Validation Method**: Plan alignment + OpenSpec strict validation + +## Executive Summary + +- **Plan Enhancement (E3)**: Splitting suggestions extended to be dependency-aware (edges, blast radius); patch output for split proposal when patch mode available. +- **Breaking Changes**: 0 (additive only). +- **Validation Result**: Pass. +- **OpenSpec Validation**: `openspec validate story-complexity-splitting-hints-support --strict` — valid. + +## Alignment with Plan E3 + +- **E3**: Extend story-complexity to be dependency-aware. **Done**: proposal.md and specs/story-complexity/spec.md updated with dependency edges, blast radius, patch output (patch-mode-preview-apply); acceptance: splitting recommendation includes "dependency impact" section. + +## USP / Value-Add + +- **Actionable**: Split proposal as patch (titles, AC, links) when patch mode available—aligns with “>80% of refinement findings actionable via patch mode” (plan). +- **Dependency-aware**: Minimizes cross-team coupling; blast radius visible. + +## Format Validation + +- proposal.md: E3 extension and acceptance criteria added. +- specs: New requirement (Dependency-aware splitting) with Given/When/Then. +- tasks.md: Unchanged; format OK. + +## Module Architecture Alignment (Re-validated 2026-02-10) + +This change was re-validated after renaming and updating to align with the modular architecture (arch-01 through arch-07): + +- Module package structure updated to `modules/{name}/module-package.yaml` pattern +- CLI command registration moved from `cli.py` to `module-package.yaml` declarations +- Core model modifications replaced with arch-07 schema extensions where applicable +- Adapter protocol extensions use arch-05 bridge registry (no direct mixin modification) +- Publisher and integrity metadata added for arch-06 marketplace readiness +- All old change ID references updated to new module-scoped naming + +**Result**: Pass — format compliant, module architecture aligned, no breaking changes introduced. diff --git a/openspec/changes/backlog-scrum-03-story-complexity/design.md b/openspec/changes/backlog-scrum-03-story-complexity/design.md new file mode 100644 index 0000000..384e831 --- /dev/null +++ b/openspec/changes/backlog-scrum-03-story-complexity/design.md @@ -0,0 +1,33 @@ +# Design: Story complexity and splitting hints support + +## Complexity score and needs_splitting + +- **Complexity score**: Function of story_points and business_value (e.g. weighted combination or simple threshold on story_points). Configurable threshold (default 13) for "needs splitting"; stories above threshold are flagged. +- **needs_splitting(item, threshold)**: Predicate: True when item.story_points > threshold (or when complexity score exceeds threshold if score is used). Handle missing story_points (e.g. treat as 0 or skip). New public APIs shall have @icontract and @beartype. +- **Configuration**: Threshold may be read from project config (e.g. `.specfact/` or refinement config); default 13 if not set. + +## Splitting suggestion + +- **Input**: BacklogItem (story_points, business_value, acceptance_criteria); optional AI hint for split boundaries. +- **Output**: Rationale (text) + recommended split points (e.g. list of boundaries derived from acceptance_criteria or heuristic). Provider-agnostic; use BacklogItem fields; optional AI for finer boundaries. +- **Integration**: When refinement completes for an item, if needs_splitting(item, threshold), append "Story splitting suggestion" block to refinement result; include in CLI output and in export-to-tmp format. + +## Sequence (refine with splitting suggestion) + +``` +User → specfact backlog refine [args] + → Refinement runs (existing flow) + → For each refined item: compute complexity / needs_splitting(threshold) + → If needs_splitting: generate splitting suggestion (rationale + split points) + → Append splitting suggestion to item output and export-to-tmp + → Emit refinement output (CLI and/or export) +``` + +## Contract enforcement + +- Complexity score and needs_splitting shall have @icontract and @beartype where they are public APIs. +- Splitting suggestion generator: same; handle missing fields without crash. + +## Fallback / offline + +- No network required for complexity or threshold; optional AI hint for split boundaries may require network if used; design for offline-first (heuristic split points from acceptance_criteria when AI unavailable). diff --git a/openspec/changes/backlog-scrum-03-story-complexity/proposal.md b/openspec/changes/backlog-scrum-03-story-complexity/proposal.md new file mode 100644 index 0000000..a4a80cc --- /dev/null +++ b/openspec/changes/backlog-scrum-03-story-complexity/proposal.md @@ -0,0 +1,72 @@ +# Change: Backlog Scrum — Story Complexity and Splitting Hints + +## Why + + +The backlog-refinement spec includes "Story Complexity Analysis" scenarios, but this behavior is not implemented. Teams need complexity scores considering story points and business value, flagging of stories >13 points for potential splitting, suggestions to split into multiple stories under the same feature with rationale, and splitting suggestion included in refinement output when a story is complex. Without this, refinement sessions do not surface size/scope risks. + +This change is part of the **`backlog-scrum` module** — delivered alongside standup and sprint planning capabilities. + +## Ownership Alignment (2026-04-08) + +- Authoritative implementation owner: `nold-ai/specfact-cli-modules`, backlog bundle story [#153](https://github.com/nold-ai/specfact-cli-modules/issues/153) +- Target hierarchy: modules Epic [#145](https://github.com/nold-ai/specfact-cli-modules/issues/145) -> Feature [#151](https://github.com/nold-ai/specfact-cli-modules/issues/151) -> Story `#153` +- This modules-repo proposal is the authoritative implementation change for the transferred issue. +- Implementation MUST NOT proceed in `specfact-cli` core from the legacy `modules/backlog-scrum/...` paths below. + +## Module Package Structure + +``` +modules/backlog-scrum/ + module-package.yaml # complexity integrated into backlog refine extension + src/backlog_scrum/ + complexity/ + scorer.py # complexity score (story_points, business_value) + splitter.py # splitting suggestion (rationale, split points) + commands/ + refine_hook.py # integration hook into backlog refine output +``` + +**No new top-level command**: complexity is surfaced as an enhancement to `backlog refine` output when `backlog-scrum` module is loaded. + +**Config**: Complexity threshold stored in `.specfact/scrum.yaml` under `complexity.threshold` (default 13 points). + +## Module Package Structure + +``` +modules/backlog-scrum/ + module-package.yaml # complexity integrated into backlog refine extension + src/backlog_scrum/ + complexity/ + scorer.py # complexity score (story_points, business_value) + splitter.py # splitting suggestion (rationale, split points) + commands/ + refine_hook.py # integration hook into backlog refine output +``` + +**No new top-level command**: complexity is surfaced as an enhancement to `backlog refine` output when `backlog-scrum` module is loaded. + +**Config**: Complexity threshold stored in `.specfact/scrum.yaml` under `complexity.threshold` (default 13 points). + +## What Changes + + +- **NEW**: Complexity calculation in `modules/backlog-scrum/src/backlog_scrum/complexity/scorer.py` — score from `story_points` + `business_value`; configurable threshold in `.specfact/scrum.yaml`. +- **NEW**: Splitting detection in `modules/backlog-scrum/src/backlog_scrum/complexity/splitter.py` — suggests split points and rationale (by acceptance criteria or logical boundaries). +- **EXTEND**: Integrate into `backlog refine` flow via command extension hook in module registry: when `backlog-scrum` is loaded and refinement completes for a complex story, include a "Story splitting suggestion" block in the output. +- **EXTEND** (plan E3): Splitting suggestions SHALL consider dependency edges from backlog-core-01 (minimize cross-team coupling) and blast radius signals. Provide patch output via patch-mode-01: "split proposal" as suggested child stories with titles + AC + links. + +## Capabilities +- **backlog-scrum** (complexity): Complexity score; `needs_splitting` predicate (configurable threshold); splitting suggestion with rationale; integration into `backlog refine` output; dependency-aware splitting and patch output when backlog-core-01 and patch-mode-01 are available. + +--- + +## Source Tracking + + +- **Original GitHub Issue**: nold-ai/specfact-cli#171 (transferred 2026-04-08) +- **GitHub Issue**: #153 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md b/openspec/changes/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md new file mode 100644 index 0000000..18c07a9 --- /dev/null +++ b/openspec/changes/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md @@ -0,0 +1,115 @@ +# Story complexity and splitting hints + +## ADDED Requirements + +This change implements the Story Complexity Analysis requirements from `openspec/specs/backlog-refinement/spec.md`; scenarios below restate and scope them for this change. + +### Requirement: Complexity score and needs-splitting flag + +The system SHALL calculate a complexity score from story_points and business_value and SHALL flag stories above a configurable threshold (e.g. 13 points) as needing potential splitting. + +**Rationale**: Teams need to identify oversized stories before commitment. + +#### Scenario: Story points complexity calculation + +**Given**: A backlog item with `story_points = 13` and `business_value = 8` + +**When**: Complexity score is calculated + +**Then**: The score considers both story points and business value + +**And**: Stories > 13 points (or above configured threshold) are flagged for potential splitting + +**Acceptance Criteria**: + +- Threshold is configurable (e.g. via config or default 13); needs_splitting(item, threshold) is deterministic. + +#### Scenario: Needs splitting predicate + +**Given**: A backlog item with story_points = 21 and threshold = 13 + +**When**: needs_splitting(item, threshold) is evaluated + +**Then**: The result is True (item is flagged for splitting) + +**Acceptance Criteria**: + +- Items at or below threshold return False; items above return True; missing story_points handled per documented behavior. + +### Requirement: Splitting suggestion (rationale and split points) + +The system SHALL suggest splitting into multiple stories under the same feature and provide rationale and recommended split points (e.g. by acceptance criteria or logical boundaries). + +**Rationale**: Teams need actionable guidance on how to split complex stories. + +#### Scenario: Splitting suggestion generation + +**Given**: A backlog item flagged for splitting (e.g. story_points > 13) with acceptance_criteria or logical boundaries + +**When**: Story splitting detection is performed + +**Then**: The system suggests splitting into multiple stories under the same feature + +**And**: The suggestion includes rationale and recommended split points (e.g. derived from acceptance criteria or optional AI hint) + +**Acceptance Criteria**: + +- Suggestion is deterministic or explicitly best-effort; rationale and split points are present in output when available. + +### Requirement: Splitting suggestion in refinement output + +The system SHALL include a story splitting suggestion in refinement output (CLI and export-to-tmp) when the refined item is complex (above threshold). + +**Rationale**: Refinement sessions must surface size/scope risks in the same flow. + +#### Scenario: Story splitting suggestion in refinement output + +**Given**: A backlog item refinement session with a complex story (e.g. story_points > 13) + +**When**: Refinement completes and output (or export-to-tmp) is emitted + +**Then**: The output includes a "Story splitting suggestion" section for that item + +**And**: The suggestion includes recommended split points and rationale + +**Acceptance Criteria**: + +- Section appears only for items above threshold; non-complex items do not show splitting suggestion; export-to-tmp format includes suggestion when applicable. + +### Requirement: Integration under backlog refine only + +The system SHALL integrate complexity and splitting into `specfact backlog refine` only; there SHALL be no top-level scrum/refine command. + +**Rationale**: Align with backlog command group; no new top-level commands. + +#### Scenario: Invoke via backlog refine + +**Given**: SpecFact CLI is installed and backlog refine is used + +**When**: The user runs `specfact backlog refine` (with item(s) that may be complex) + +**Then**: Refinement output (and export-to-tmp when used) includes complexity/splitting suggestion for complex items + +**Acceptance Criteria**: + +- Behavior is discoverable as part of existing `specfact backlog refine`; no new top-level commands. + +### Requirement: Dependency-aware splitting (E3 extension) + +The system SHALL consider dependency edges (minimize cross-team coupling) and blast radius (modules touched, component tags when available) when generating splitting suggestions. When patch mode (patch-mode-preview-apply) is available, SHALL provide "split proposal" as suggested child stories with titles, AC, and links. Splitting recommendation output SHALL include a "dependency impact" section when dependency data exists. + +**Rationale**: Plan E3—splitting should reduce cross-team coupling and surface blast radius. + +#### Scenario: Splitting suggestion includes dependency impact + +**Given**: Dependency graph (add-backlog-dependency-analysis-and-commands) and optional patch mode are available; item has dependencies or touched modules + +**When**: Splitting suggestion is generated for a complex story + +**Then**: The suggestion includes a "dependency impact" section (cross-team edges, blast radius when available) + +**And**: When patch mode is used, split proposal is emitted as suggested child stories (titles, AC, links) + +**Acceptance Criteria**: + +- Splitting recommendation includes "dependency impact" section when dependency data exists; patch output for split proposal when patch mode available. diff --git a/openspec/changes/backlog-scrum-03-story-complexity/tasks.md b/openspec/changes/backlog-scrum-03-story-complexity/tasks.md new file mode 100644 index 0000000..a50e852 --- /dev/null +++ b/openspec/changes/backlog-scrum-03-story-complexity/tasks.md @@ -0,0 +1,71 @@ +# Tasks: Backlog Scrum — Story Complexity and splitting hints support + +## TDD / SDD order (enforced) + +Per `openspec/config.yaml`, **tests before code** apply to any task that adds or changes behavior. + +1. **Spec deltas** define behavior (Given/When/Then) in `openspec/changes/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md`. +2. **Tests second**: Write unit/integration tests from those scenarios; run tests and **expect failure** (no implementation yet). +3. **Code last**: Implement until tests pass and behavior satisfies the spec. + +Do not implement production code for new behavior until the corresponding tests exist and have been run (expecting failure). + +--- + +## 1. Create git worktree branch from dev + +- [ ] 1.1 Ensure primary checkout is on dev and up to date: `git checkout dev && git pull origin dev` +- [ ] 1.2 Create dedicated worktree branch (preferred): `scripts/worktree.sh create feature/backlog-scrum-03-story-complexity`; if issue exists, link branch to issue with `gh issue develop 171 --repo nold-ai/specfact-cli --name feature/backlog-scrum-03-story-complexity` +- [ ] 1.3 Or create worktree branch without issue link: `scripts/worktree.sh create feature/backlog-scrum-03-story-complexity` (if no issue yet) +- [ ] 1.4 Verify branch in worktree: `git worktree list` includes the branch path; then run `git branch --show-current` inside that worktree. + +## 2. Create GitHub issue in nold-ai/specfact-cli (mandatory) + +- [ ] 2.1 Create issue in nold-ai/specfact-cli: `gh issue create --repo nold-ai/specfact-cli --title "[Change] Story complexity and splitting hints support" --body-file --label "enhancement" --label "change-proposal"` +- [ ] 2.2 Use body from proposal (Why, What Changes, Acceptance Criteria); add footer `*OpenSpec Change Proposal: story-complexity-splitting-hints-support*` +- [ ] 2.3 Update `proposal.md` Source Tracking section with issue number, issue URL, repository nold-ai/specfact-cli, Last Synced Status: proposed +- [ ] 2.4 Link issue to project (optional): `gh project item-add 1 --owner nold-ai --url ` (requires `gh auth refresh -s project` if needed) + +## 3. Verify spec deltas (SDD: specs first) + +- [ ] 3.1 Confirm `specs/story-complexity/spec.md` exists and is complete (ADDED requirements, Given/When/Then for complexity score, needs_splitting, splitting suggestion in refinement output). +- [ ] 3.2 Map scenarios to implementation: complexity score, needs_splitting(threshold), splitting suggestion generator, integration into backlog refine output and export-to-tmp. + +## 4. Tests first (TDD: write tests from spec scenarios; expect failure) + +- [ ] 4.1 Write unit or integration tests from `specs/story-complexity/spec.md` scenarios: complexity score (story_points, business_value); needs_splitting predicate (above/below threshold); splitting suggestion (rationale + split points); refinement output includes suggestion for complex items only. +- [ ] 4.2 Run tests: `hatch run smart-test-unit` (or equivalent); **expect failure** (no implementation yet). +- [ ] 4.3 Document which scenarios are covered by which test modules. + +## 5. Implement complexity and splitting (TDD: code until tests pass) + +- [ ] 5.1 Add helper(s) for complexity score and needs_splitting(item, threshold); configurable threshold (default 13); ensure @icontract and @beartype on new public APIs. +- [ ] 5.2 Add splitting suggestion logic (rationale + optional split points from acceptance_criteria or heuristic); integrate into refinement result type/output. +- [ ] 5.3 In `specfact backlog refine`, when emitting refined item output (and export-to-tmp), append "Story splitting suggestion" section for items above threshold; no top-level scrum/refine command. +- [ ] 5.4 Run tests again; **expect pass**; fix until all tests pass. + +## 6. Quality gates + +- [ ] 6.1 Run format and type-check: `hatch run format`, `hatch run type-check`. +- [ ] 6.2 Run contract test: `hatch run contract-test`. +- [ ] 6.3 Run full test suite: `hatch run smart-test` (or `hatch run smart-test-full`). +- [ ] 6.4 Ensure any new or modified public APIs have @icontract and @beartype where applicable. + +## 7. Documentation research and review + +- [ ] 7.1 Identify affected documentation: docs/guides/backlog-refinement.md, docs/reference as needed. +- [ ] 7.2 Update backlog-refinement.md: document complexity score, needs-splitting threshold, and splitting hints in refinement output. +- [ ] 7.3 If adding a new doc page: set front-matter (layout, title, permalink, description) and update docs/_layouts/default.html sidebar if needed. + +## 8. Version and changelog (patch bump; required before PR) + +- [ ] 8.1 Bump **patch** version in `pyproject.toml` (e.g. X.Y.Z → X.Y.(Z+1)). +- [ ] 8.2 Sync version in `setup.py`, `src/__init__.py`, `src/specfact_cli/__init__.py` to match pyproject.toml. +- [ ] 8.3 Add CHANGELOG.md entry under new [X.Y.Z] - YYYY-MM-DD section: **Added** – Story complexity and splitting hints in `specfact backlog refine` (complexity score, needs-splitting flag, splitting suggestion in output/export). + +## 9. Create Pull Request to dev + +- [ ] 9.1 Ensure all changes are committed: `git add .` and `git commit -m "feat(backlog): add story complexity and splitting hints to refine"` +- [ ] 9.2 Push to remote: `git push origin feature/backlog-scrum-03-story-complexity` +- [ ] 9.3 Create PR: `gh pr create --repo nold-ai/specfact-cli --base dev --head feature/backlog-scrum-03-story-complexity --title "feat(backlog): add story complexity and splitting hints to refine" --body-file ` (use repo PR template; add OpenSpec change ID `backlog-scrum-03-story-complexity` and summary; reference GitHub issue with `Fixes nold-ai/specfact-cli#171`). +- [ ] 9.4 Verify PR and branch are linked to issue in Development section. diff --git a/openspec/changes/backlog-scrum-04-definition-of-done/CHANGE_VALIDATION.md b/openspec/changes/backlog-scrum-04-definition-of-done/CHANGE_VALIDATION.md new file mode 100644 index 0000000..f87cb33 --- /dev/null +++ b/openspec/changes/backlog-scrum-04-definition-of-done/CHANGE_VALIDATION.md @@ -0,0 +1,87 @@ +# Change Validation Report: backlog-scrum-04-definition-of-done + +**Validation Date**: 2026-01-30 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Dry-run and format/config compliance check + +## Executive Summary + +- **Breaking Changes**: 0 detected +- **Dependent Files**: Additive only (new DoD config, validator, optional hook into backlog list/refine/export; existing BacklogItem and backlog_commands unchanged except optional DoD path) +- **Impact Level**: Low +- **Validation Result**: Pass +- **User Decision**: N/A (no breaking changes) +- **Command placement**: DoD under backlog command group (`specfact backlog list --dod`, `specfact backlog dod`, etc.); no top-level DoD/scrum command (per harmonization) + +## Breaking Changes Detected + +None. Change is additive: new DoD config schema, loader, validator; optional DoD check for done items in backlog output/export; existing behavior unchanged unless user opts in. + +## Dependencies Affected + +- **Critical**: None +- **Recommended**: Reuse DoR patterns (config load, provider-agnostic rules) where applicable; BacklogItem state field used for "Done" filtering. +- **Optional**: None + +## Impact Assessment + +- **Code Impact**: New DoD config and validator; optional integration in backlog_commands.py (list/refine/export or new `backlog dod` subcommand). +- **Test Impact**: New tests from spec scenarios (config load, validation for done items, status in output). +- **Documentation Impact**: agile-scrum-workflows.md, backlog-refinement.md. +- **Release Impact**: Patch (additive feature). + +## Format Validation + +- **proposal.md Format**: Pass + - Title format: Correct (`# Change: Definition of Done (DoD) support`) + - Required sections: All present (Why, What Changes, Capabilities, Impact) + - "What Changes" format: Correct (bullet list with NEW/EXTEND) + - "Capabilities" section: Present (definition-of-done) + - "Impact" format: Correct + - Source Tracking section: Present (GitHub Issue #169, Issue URL, Repository, Last Synced Status) +- **tasks.md Format**: Pass + - Section headers: Hierarchical numbered format + - Task format: `- [ ] N.N [Description]` + - Sub-task format: Indented `- [ ] N.N.N` + - Config.yaml compliance: Pass + - TDD order section at top; tests before implementation (Section 4 before Section 5) + - Branch creation first (Section 1); PR creation last (Section 9) + - GitHub issue creation task (Section 2) for nold-ai/specfact-cli + - Version and changelog task (Section 8) before PR; patch bump and CHANGELOG sync + - Quality gates, documentation tasks present +- **specs Format**: Pass (Given/When/Then in specs/definition-of-done/spec.md) +- **design.md Format**: Pass (DoD config/validator, sequence, contract enforcement, fallback documented) +- **Config.yaml Compliance**: Pass + +## OpenSpec Validation + +- **Status**: Pass +- **Validation Command**: `openspec validate definition-of-done-support --strict` +- **Issues Found**: 0 +- **Issues Fixed**: 0 +- **Re-validated**: 2026-01-30 (status: all artifacts done; schema: spec-driven) + +## Recommended Improvements Applied + +1. **GitHub issue mandatory**: Task 2 creates issue in nold-ai/specfact-cli; proposal Source Tracking updated with #169. +2. **Patch version and changelog**: Task 8 bumps patch version, syncs pyproject.toml/setup.py/src __init__.py, and adds CHANGELOG.md entry. +3. **TDD order**: TDD/SDD section at top of tasks.md; Section 4 (tests first, expect failure) before Section 5 (implement until tests pass). +4. **Backlog harmonization**: DoD integrated under backlog group (list/refine/dod); no top-level DoD command. + +## Validation Artifacts + +- No temporary workspace used (dry-run analysis only). +- Change directory: `openspec/changes/backlog-09-definition-of-done-support/` + +## Module Architecture Alignment (Re-validated 2026-02-10) + +This change was re-validated after renaming and updating to align with the modular architecture (arch-01 through arch-07): + +- Module package structure updated to `modules/{name}/module-package.yaml` pattern +- CLI command registration moved from `cli.py` to `module-package.yaml` declarations +- Core model modifications replaced with arch-07 schema extensions where applicable +- Adapter protocol extensions use arch-05 bridge registry (no direct mixin modification) +- Publisher and integrity metadata added for arch-06 marketplace readiness +- All old change ID references updated to new module-scoped naming + +**Result**: Pass — format compliant, module architecture aligned, no breaking changes introduced. diff --git a/openspec/changes/backlog-scrum-04-definition-of-done/design.md b/openspec/changes/backlog-scrum-04-definition-of-done/design.md new file mode 100644 index 0000000..2d16a0a --- /dev/null +++ b/openspec/changes/backlog-scrum-04-definition-of-done/design.md @@ -0,0 +1,27 @@ +# Design: Definition of Done (DoD) support + +## DoD config and validator + +- **Config**: DoD config schema (e.g. YAML) with checklist items (e.g. tests_pass, docs_updated, code_reviewed). Store in `.specfact/dod.yaml` or under project templates. Reuse patterns from DoR (framework-specific rules, provider-agnostic where possible). +- **Validator**: Function that takes a BacklogItem (state=Done) and DoD config, runs the checklist (e.g. by checking item fields or linked artifacts), returns pass/fail and list of failed criteria. New public APIs shall have @icontract and @beartype. +- **Integration**: Hook into backlog list/refine/export; when items are in Done state and DoD is enabled, run validator and attach DoD status to output/export. Expose optionally via `specfact backlog list`, `specfact backlog refine`, or a dedicated `specfact backlog dod` / `specfact backlog validate` subcommand under the backlog group (no top-level DoD command). + +## Sequence (DoD validation for done items) + +``` +User → specfact backlog list --dod (or specfact backlog dod) + → CLI loads .specfact/dod.yaml (if present) + → CLI fetches backlog items (existing adapter) + → For each item in Done state: run DoD validator(item, config) + → Attach DoD status (pass/fail, failed criteria) to item + → Output/export includes DoD status per done item +``` + +## Contract enforcement + +- DoD config loader and validator shall have @icontract and @beartype. +- Backlog command integration: optional flag (e.g. `--dod`) to enable DoD; default off for backward compatibility. + +## Fallback / offline + +- DoD config is read from local project; no network required for config load. Validation may require item data already fetched by backlog adapter (offline if cache present). diff --git a/openspec/changes/backlog-scrum-04-definition-of-done/proposal.md b/openspec/changes/backlog-scrum-04-definition-of-done/proposal.md new file mode 100644 index 0000000..c357ac3 --- /dev/null +++ b/openspec/changes/backlog-scrum-04-definition-of-done/proposal.md @@ -0,0 +1,72 @@ +# Change: Backlog Scrum — Definition of Done Support + +## Why + + +SpecFact CLI has Definition of Ready (DoR) for backlog refinement. Teams also need Definition of Done (DoD) to ensure items moved to "Done" meet completion criteria. DoD is not modeled or validated today; there is no way to define team DoD rules (e.g. checklist: tests pass, docs updated, code reviewed) and run them against items in Done state. + +This change is part of the **`backlog-scrum` module** — delivered alongside standup, sprint planning, and story complexity capabilities. DoD is a Scrum-native concept shared by all sprint-based teams. + +## Ownership Alignment (2026-04-08) + +- Authoritative implementation owner: `nold-ai/specfact-cli-modules`, backlog bundle story [#152](https://github.com/nold-ai/specfact-cli-modules/issues/152) +- Target hierarchy: modules Epic [#145](https://github.com/nold-ai/specfact-cli-modules/issues/145) -> Feature [#151](https://github.com/nold-ai/specfact-cli-modules/issues/151) -> Story `#152` +- This modules-repo proposal is the authoritative implementation change for the transferred issue. +- Implementation MUST NOT proceed in `specfact-cli` core from the legacy `modules/backlog-scrum/...` paths below. + +## Module Package Structure + +``` +modules/backlog-scrum/ + module-package.yaml # updated: add 'backlog dod' command; DoD integrates with policy-engine + src/backlog_scrum/ + dod/ + config.py # DoD config loading from .specfact/scrum.yaml + validator.py # DoD rule evaluation for Done-state items + commands/ + dod.py # specfact backlog dod (optional dedicated subcommand) +``` + +**Config**: DoD rules stored in `.specfact/scrum.yaml` under `dod.rules` (or as a named template). All Scrum-specific config (sprint capacity, complexity threshold, DoD) consolidated under `.specfact/scrum.yaml`. + +**Integration with policy-engine-01**: When policy-engine-01 is installed, DoD validation is surfaced as a policy rule set so `policy validate` includes DoD checks for Done items. DoD can also be used standalone without policy-engine-01. + +## Module Package Structure + +``` +modules/backlog-scrum/ + module-package.yaml # updated: add 'backlog dod' command; DoD integrates with policy-engine + src/backlog_scrum/ + dod/ + config.py # DoD config loading from .specfact/scrum.yaml + validator.py # DoD rule evaluation for Done-state items + commands/ + dod.py # specfact backlog dod (optional dedicated subcommand) +``` + +**Config**: DoD rules stored in `.specfact/scrum.yaml` under `dod.rules` (or as a named template). All Scrum-specific config (sprint capacity, complexity threshold, DoD) consolidated under `.specfact/scrum.yaml`. + +**Integration with policy-engine-01**: When policy-engine-01 is installed, DoD validation is surfaced as a policy rule set so `policy validate` includes DoD checks for Done items. DoD can also be used standalone without policy-engine-01. + +## What Changes + + +- **NEW**: Model DoD as a checklist or rule set in `modules/backlog-scrum/src/backlog_scrum/dod/` — stored in `.specfact/scrum.yaml` under `dod` section; similar in structure to DoR but for completion criteria. +- **NEW**: When listing or exporting backlog items in "Done" (or equivalent) state, optionally run DoD validation via `modules/backlog-scrum/src/backlog_scrum/dod/validator.py` and attach DoD status (pass/fail + which criteria failed). +- **EXTEND**: Integrate into `backlog list`, `backlog refine`, or a dedicated `specfact backlog dod` subcommand: for items in done state, show DoD status in output and export. Declared in `module-package.yaml`; no changes to `cli.py`. +- **EXTEND** (policy-engine-01): When policy-engine-01 is present, register DoD rules as a policy rule set so `policy validate` covers completion criteria for Done items. + +## Capabilities +- **backlog-scrum** (DoD): DoD config load from `.specfact/scrum.yaml`; DoD validation for done items; DoD status in CLI/export when enabled; optional policy-engine-01 integration for unified `policy validate` coverage. + +--- + +## Source Tracking + + +- **Original GitHub Issue**: nold-ai/specfact-cli#169 (transferred 2026-04-08) +- **GitHub Issue**: #152 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md b/openspec/changes/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md new file mode 100644 index 0000000..a196681 --- /dev/null +++ b/openspec/changes/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md @@ -0,0 +1,71 @@ +# Definition of Done (DoD) + +## ADDED Requirements + +### Requirement: DoD configuration + +The system SHALL support loading a DoD configuration (checklist or rule set) from project config (e.g. `.specfact/dod.yaml` or under templates), similar in spirit to DoR. + +**Rationale**: Teams need to define completion criteria (e.g. tests pass, docs updated, code reviewed) per project. + +#### Scenario: Load DoD config from project + +**Given**: A project with a DoD config file (e.g. `.specfact/dod.yaml`) defining a checklist (e.g. tests_pass, docs_updated, code_reviewed) + +**When**: The user runs a backlog command that uses DoD (e.g. `specfact backlog list` or `specfact backlog dod` with DoD enabled) + +**Then**: The system loads the DoD config and uses it for validation + +**And**: If no DoD config exists, DoD validation is skipped or a clear message is shown + +**Acceptance Criteria**: + +- DoD config schema is documented; loader does not crash on missing or invalid config (report clearly). + +### Requirement: DoD validation for done items + +The system SHALL run DoD validation against backlog items in "Done" (or equivalent) state when the user opts in and config is present. + +**Rationale**: Only items in done state are checked against completion criteria. + +#### Scenario: DoD validation for done item + +**Given**: A backlog item in Done state and a loaded DoD config with criteria (e.g. tests_pass, docs_updated) + +**When**: The user runs backlog list/export or `specfact backlog dod` with DoD enabled + +**Then**: The system runs the DoD checklist against the item and produces a result (pass/fail + which criteria failed) + +**Acceptance Criteria**: + +- Result is deterministic; failed criteria are listed; no silent swallow of errors. + +#### Scenario: DoD not run for non-done items + +**Given**: A backlog item not in Done state (e.g. In Progress) + +**When**: The user runs a command with DoD validation enabled + +**Then**: DoD validation is not applied to that item (or item is skipped for DoD) + +**Acceptance Criteria**: + +- Only items in Done (or equivalent) state are validated against DoD. + +### Requirement: DoD status in output and export + +The system SHALL display or export DoD status (pass/fail, criteria) for done items when DoD validation is enabled. + +**Rationale**: Teams need to see which done items meet DoD and which do not. + +#### Scenario: DoD status in CLI output + +**Given**: Backlog items in Done state and DoD validation has been run + +**When**: The user runs `specfact backlog list` (or equivalent) with DoD enabled + +**Then**: The output includes DoD status per done item (e.g. pass/fail, list of failed criteria) + +**Acceptance Criteria**: + +- Output is readable (e.g. column or section per item); export format includes DoD status when applicable. diff --git a/openspec/changes/backlog-scrum-04-definition-of-done/tasks.md b/openspec/changes/backlog-scrum-04-definition-of-done/tasks.md new file mode 100644 index 0000000..dbf32a3 --- /dev/null +++ b/openspec/changes/backlog-scrum-04-definition-of-done/tasks.md @@ -0,0 +1,73 @@ +# Tasks: Backlog Scrum — Definition of Done (DoD) support + +## TDD / SDD order (enforced) + +Per `openspec/config.yaml`, **tests before code** apply to any task that adds or changes behavior. + +1. **Spec deltas** define behavior (Given/When/Then) in `openspec/changes/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md`. +2. **Tests second**: Write unit/integration tests from those scenarios; run tests and **expect failure** (no implementation yet). +3. **Code last**: Implement until tests pass and behavior satisfies the spec. + +Do not implement production code for new behavior until the corresponding tests exist and have been run (expecting failure). + +--- + +## 1. Create git worktree branch from dev + +- [ ] 1.1 Ensure primary checkout is on dev and up to date: `git checkout dev && git pull origin dev` +- [ ] 1.2 Create dedicated worktree branch (preferred): `scripts/worktree.sh create feature/backlog-scrum-04-definition-of-done`; if issue exists, link branch to issue with `gh issue develop --repo nold-ai/specfact-cli --name feature/backlog-scrum-04-definition-of-done` +- [ ] 1.3 Or create worktree branch without issue link: `scripts/worktree.sh create feature/backlog-scrum-04-definition-of-done` (if no issue yet) +- [ ] 1.4 Verify branch in worktree: `git worktree list` includes the branch path; then run `git branch --show-current` inside that worktree. + +## 2. Create GitHub issue in nold-ai/specfact-cli (mandatory) + +- [ ] 2.1 Create issue in nold-ai/specfact-cli: `gh issue create --repo nold-ai/specfact-cli --title "[Change] Definition of Done (DoD) support" --body-file --label "enhancement" --label "change-proposal"` +- [ ] 2.2 Use body from proposal (Why, What Changes, Acceptance Criteria); add footer `*OpenSpec Change Proposal: definition-of-done-support*` +- [ ] 2.3 Update `proposal.md` Source Tracking section with issue number, issue URL, repository nold-ai/specfact-cli, Last Synced Status: proposed +- [ ] 2.4 Link issue to project (optional): `gh project item-add 1 --owner nold-ai --url ` (requires `gh auth refresh -s project` if needed) + +## 3. Verify spec deltas (SDD: specs first) + +- [ ] 3.1 Confirm `specs/definition-of-done/spec.md` exists and is complete (ADDED requirements, Given/When/Then for DoD config load, validation for done items, status in output). +- [ ] 3.2 Map scenarios to implementation: load DoD config, validate done items only, DoD status in CLI/export. + +## 4. Tests first (TDD: write tests from spec scenarios; expect failure) + +- [ ] 4.1 Write unit or integration tests from `specs/definition-of-done/spec.md` scenarios: DoD config load (present/missing); DoD validation for done item (pass/fail, failed criteria); non-done items skipped; DoD status in output. +- [ ] 4.2 Run tests: `hatch run smart-test-unit` (or equivalent); **expect failure** (no implementation yet). +- [ ] 4.3 Document which scenarios are covered by which test modules. + +## 5. Implement DoD (TDD: code until tests pass) + +- [ ] 5.1 Define DoD config schema and loader (e.g. `.specfact/dod.yaml`); load from project; handle missing/invalid config without crash. +- [ ] 5.2 Implement DoD validator: takes BacklogItem (state=Done) and config, runs checklist, returns pass/fail and failed criteria; ensure @icontract and @beartype on new public APIs. +- [ ] 5.3 Hook into backlog list/refine/export: when items in Done state and DoD enabled (e.g. `--dod`), run validator and attach DoD status. Expose under backlog group (e.g. `specfact backlog list --dod` or `specfact backlog dod`); do not add top-level DoD command. +- [ ] 5.4 Include DoD status in CLI output and export for done items when enabled. +- [ ] 5.5 Run tests again; **expect pass**; fix until all tests pass. + +## 6. Quality gates + +- [ ] 6.1 Run format and type-check: `hatch run format`, `hatch run type-check`. +- [ ] 6.2 Run contract test: `hatch run contract-test`. +- [ ] 6.3 Run full test suite: `hatch run smart-test` (or `hatch run smart-test-full`). +- [ ] 6.4 Ensure any new or modified public APIs have @icontract and @beartype where applicable. + +## 7. Documentation research and review + +- [ ] 7.1 Identify affected documentation: docs/guides/agile-scrum-workflows.md, docs/guides/backlog-refinement.md. +- [ ] 7.2 Update agile-scrum-workflows.md: add section or subsection for DoD with SpecFact (config, validation for done items, status in output). +- [ ] 7.3 Update backlog-refinement.md: document DoD support and how it complements DoR. +- [ ] 7.4 If adding a new doc page: set front-matter (layout, title, permalink, description) and update docs/_layouts/default.html sidebar if needed. + +## 8. Version and changelog (patch bump; required before PR) + +- [ ] 8.1 Bump **patch** version in `pyproject.toml` (e.g. X.Y.Z → X.Y.(Z+1)). +- [ ] 8.2 Sync version in `setup.py`, `src/__init__.py`, `src/specfact_cli/__init__.py` to match pyproject.toml. +- [ ] 8.3 Add CHANGELOG.md entry under new [X.Y.Z] - YYYY-MM-DD section: **Added** – Definition of Done (DoD) support (config, validation for done items, status in backlog output/export). + +## 9. Create Pull Request to dev + +- [ ] 9.1 Ensure all changes are committed: `git add .` and `git commit -m "feat(backlog): add Definition of Done (DoD) support for done items"` +- [ ] 9.2 Push to remote: `git push origin feature/backlog-scrum-04-definition-of-done` +- [ ] 9.3 Create PR: `gh pr create --repo nold-ai/specfact-cli --base dev --head feature/backlog-scrum-04-definition-of-done --title "feat(backlog): add Definition of Done (DoD) support for done items" --body-file ` (use repo PR template; add OpenSpec change ID `backlog-scrum-04-definition-of-done` and summary; reference GitHub issue with `Fixes nold-ai/specfact-cli#`). +- [ ] 9.4 Verify PR and branch are linked to issue in Development section. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml b/openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml new file mode 100644 index 0000000..2a45c1f --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md b/openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md new file mode 100644 index 0000000..d5dac54 --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: ceremony-02-requirements-aware-output + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate ceremony-02-requirements-aware-output --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** ceremony-requirements-awareness +- **Modified capabilities:** backlog-refinement,daily-standup +- **Declared dependencies:** requirements-02 (requirements module), ceremony-cockpit-01 (#185, ceremony aliases) +- **Proposed affected code paths:** - `modules/ceremony-cockpit/src/` (extend ceremony commands with requirements flag);- Requirements module integration hooks - Ceremony cockpit command handlers + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/design.md b/openspec/changes/ceremony-02-requirements-aware-output/design.md new file mode 100644 index 0000000..199658d --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `ceremony-02-requirements-aware-output` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- Keep all public APIs contract-first with `@icontract` and `@beartype`. +- Make all behavior extensions opt-in or backward-compatible by default. +- Add/modify OpenSpec deltas first so tests can be derived before implementation. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-02-module-commands and ceremony-cockpit-01-ceremony-aliases. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/proposal.md b/openspec/changes/ceremony-02-requirements-aware-output/proposal.md new file mode 100644 index 0000000..595d9e8 --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/proposal.md @@ -0,0 +1,60 @@ +# Change: Ceremony Integration — Requirements-Aware Ceremony Output + +## Why + + + + +Current backlog ceremony commands (`backlog ceremony refinement`, `backlog ceremony standup`, `backlog ceremony planning`) operate purely on technical signals — story points, acceptance criteria quality, spec coverage. They don't surface business requirement coverage, value gaps, or architectural readiness. This means ceremonies miss the most impactful signals: "Is the business case defined?" and "Does the architecture support this?" Extending ceremony output with a `--with-requirements` flag enriches refinement and planning with business context, catching value gaps before they become code. + +## Ownership Alignment (2026-04-08) + +- Authoritative implementation owner: `nold-ai/specfact-cli-modules`, backlog bundle story [#159](https://github.com/nold-ai/specfact-cli-modules/issues/159) +- Target hierarchy: modules Epic [#145](https://github.com/nold-ai/specfact-cli-modules/issues/145) -> Feature [#150](https://github.com/nold-ai/specfact-cli-modules/issues/150) -> Story `#159` +- This modules-repo proposal is the authoritative implementation change for the transferred issue. +- Implementation MUST NOT proceed in `specfact-cli` core; backlog ceremony surfaces are bundle-owned. + +## What Changes + + + + +- **EXTEND**: `specfact backlog ceremony refinement` extended with `--with-requirements` flag: + - Show per-story business requirement status (defined/missing/incomplete) + - Flag stories missing business value quantification + - Flag stories with requirements but no solution architecture + - Detect orphaned specs (spec exists but no business requirement) + - Recommendation engine: "Defer until business case clarified" for value-undefined stories +- **EXTEND**: `specfact backlog ceremony planning` extended with `--with-requirements` flag: + - Sprint readiness assessment: business value coverage percentage + - Risk items: stories entering sprint without full traceability chain + - Capacity allocation by business outcome (not just story points) +- **EXTEND**: `specfact backlog ceremony standup` extended with `--with-requirements` flag: + - Yesterday/today items annotated with business requirement they serve + - Blockers annotated with impacted business outcomes +- **NEW**: Ceremony output sections: "Business Value Coverage", "Business Risk Items", "Ready for Sprint" with profile-aware detail level (solo gets summary only, enterprise gets full breakdown) +- **EXTEND**: Ceremony cockpit (ceremony-cockpit-01) integration — requirements-aware output available through all ceremony aliases + +## Capabilities +### New Capabilities + +- `ceremony-requirements-awareness`: Requirements-aware enrichment for backlog ceremony commands (`backlog ceremony refinement`, `backlog ceremony planning`, `backlog ceremony standup`) showing business value coverage, risk items, orphaned specs, and sprint readiness with profile-aware detail levels. + +### Modified Capabilities + +- `backlog-refinement`: Extended with `--with-requirements` flag for business context enrichment +- `daily-standup`: Extended with `--with-requirements` flag for business outcome annotations + + +--- + +## Source Tracking + + +- **Original GitHub Issue**: nold-ai/specfact-cli#245 (transferred 2026-04-08) +- **GitHub Issue**: #159 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false + diff --git a/openspec/changes/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md b/openspec/changes/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md new file mode 100644 index 0000000..16145c9 --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Backlog Refinement +Backlog refinement output SHALL support requirements-aware enrichment. + +#### Scenario: Requirements-aware refinement highlights business value gaps +- **GIVEN** refinement is run with requirements-aware mode enabled +- **WHEN** stories missing quantified business value are present +- **THEN** output lists those stories as business-value gaps +- **AND** recommendations prioritize requirement completion before implementation. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md b/openspec/changes/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md new file mode 100644 index 0000000..75eb41d --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Ceremony Requirements Awareness +The system SHALL enrich ceremony outputs with requirement, architecture, and traceability readiness signals. + +#### Scenario: Refinement output includes chain-readiness summary +- **GIVEN** `specfact backlog ceremony refinement --with-requirements` +- **WHEN** command runs +- **THEN** output includes counts for stories with requirements, missing business value, missing architecture, and orphan specs +- **AND** each count links to affected backlog item IDs. + +#### Scenario: Ready-for-sprint signal requires chain prerequisites +- **GIVEN** a story has requirement and architecture artifacts but no code +- **WHEN** ceremony readiness is computed +- **THEN** story can be marked ready-for-implementation +- **AND** missing requirement or architecture links prevent ready status. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md b/openspec/changes/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md new file mode 100644 index 0000000..bc8c566 --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Daily Standup +Daily standup output SHALL include requirement and architecture blockers when present. + +#### Scenario: Standup reports upstream blockers before technical tasks +- **GIVEN** tasks are blocked by missing requirement or architecture decisions +- **WHEN** standup summary is generated +- **THEN** blockers are listed under a business/architecture blocker section +- **AND** unresolved upstream blockers are prioritized above downstream code tasks. diff --git a/openspec/changes/ceremony-02-requirements-aware-output/tasks.md b/openspec/changes/ceremony-02-requirements-aware-output/tasks.md new file mode 100644 index 0000000..e2cc6a8 --- /dev/null +++ b/openspec/changes/ceremony-02-requirements-aware-output/tasks.md @@ -0,0 +1,30 @@ +# Tasks: ceremony-02-requirements-aware-output + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/ceremony-02-requirements-aware-output` from `dev` before implementation work: `scripts/worktree.sh create feature/ceremony-02-requirements-aware-output`. +- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. +- [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. +- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate ceremony-02-requirements-aware-output --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/ceremony-02-requirements-aware-output` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/governance-01-evidence-output/.openspec.yaml b/openspec/changes/governance-01-evidence-output/.openspec.yaml new file mode 100644 index 0000000..2a45c1f --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/governance-01-evidence-output/CHANGE_VALIDATION.md b/openspec/changes/governance-01-evidence-output/CHANGE_VALIDATION.md new file mode 100644 index 0000000..b9318d3 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/CHANGE_VALIDATION.md @@ -0,0 +1,28 @@ +# Change Validation: governance-01-evidence-output + +- **Validated on (UTC):** 2026-03-22T22:28:26+00:00 +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate governance-01-evidence-output --strict` +- **Result:** PASS + +## Scope Summary + +- **Primary capability:** `governance-evidence-output` +- **Clean-code delta:** add a top-level `code_quality` section that stays parallel to `validation_results` +- **Declared dependencies:** `validation-02-full-chain-engine`, `governance-02-exception-management`, policy consumers + +## Breaking-Change Analysis (Dry-Run) + +- The delta preserves the evidence envelope ownership boundary. +- Clean-code reporting is additive and does not redefine the traceability layer graph. + +## Dependency and Integration Review + +- The updated proposal keeps validation and evidence responsibilities separated. +- No additional scope expansion was needed after reviewing clean-code integration points. + +## Validation Outcome + +- Required artifacts are present and parseable. +- Strict OpenSpec validation passed. +- Change remains authoritative for the evidence envelope schema. diff --git a/openspec/changes/governance-01-evidence-output/design.md b/openspec/changes/governance-01-evidence-output/design.md new file mode 100644 index 0000000..75561c7 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `governance-01-evidence-output` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- Keep all public APIs contract-first with `@icontract` and `@beartype`. +- Make all behavior extensions opt-in or backward-compatible by default. +- Add/modify OpenSpec deltas first so tests can be derived before implementation. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on validation-02-full-chain-engine and policy-02-packs-and-modes. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/governance-01-evidence-output/proposal.md b/openspec/changes/governance-01-evidence-output/proposal.md new file mode 100644 index 0000000..8551fc8 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/proposal.md @@ -0,0 +1,86 @@ +# Change: Evidence & Audit Output for CI/CD Pipelines + +## Why + + + + +Enterprise environments require machine-readable evidence that policies were enforced, traceability exists, and exceptions are tracked. Current validation output is human-readable (Markdown/terminal) but not suitable for CI gates, audit systems, or compliance dashboards. A standardized evidence JSON output format — covering policy results, traceability coverage, exception status, and timestamps — makes SpecFact validation results consumable by any CI/CD pipeline, audit tool, or governance platform. + +## Ownership Alignment (2026-04-08) + +- Repository assignment: `nold-ai/specfact-cli-modules` +- Modules-owned scope retained here: bundle-side evidence emission and runtime output behavior built on top of the core evidence envelope contract. +- Core counterpart retained in `nold-ai/specfact-cli` issue [#247](https://github.com/nold-ai/specfact-cli/issues/247) +- Target hierarchy: modules Epic [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162) -> Feature [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163) -> Story [#169](https://github.com/nold-ai/specfact-cli-modules/issues/169) +- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. +- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. + +## What Changes + + + + +- **NEW**: Evidence writer producing standardized JSON artifacts: + ```json + { + "schema_version": "1.0", + "run_id": "uuid", + "timestamp": "ISO-8601", + "profile": "enterprise", + "policy_mode": "hard", + "validation_results": { + "full_chain": { "pass": 67, "fail": 2, "advisory": 5 }, + "layers": { ... }, + "orphans": { ... } + }, + "code_quality": { + "clean_code_score": 95, + "findings_by_category": { "naming": 0, "kiss": 1, "yagni": 0, "dry": 0, "solid": 0 }, + "verdict": "PASS_WITH_ADVISORY" + }, + "coverage": { + "req_to_arch": "92%", + "arch_to_spec": "100%", + "spec_to_code": "100%", + "code_to_test": "87%" + }, + "exceptions": [ + { "id": "EXC-001", "policy": "...", "expires": "2026-12-31", "status": "active" } + ], + "overall_verdict": "PASS_WITH_ADVISORY", + "ci_exit_code": 0 + } + ``` +- **NEW**: `--evidence-dir .specfact/evidence/` flag on `specfact validate --full-chain` to persist evidence artifacts per run +- **NEW**: `--ci-mode` flag that sets exit codes based on profile enforcement mode: advisory=always 0, mixed=1 for hard-fail rules only, hard=1 for any failure +- **NEW**: Evidence artifact naming: `{timestamp}_{run_id}_evidence.json` for audit trail +- **NEW**: Evidence summary on terminal: human-readable table alongside JSON output +- **EXTEND**: Full-chain validation (validation-02) extended to produce evidence artifacts +- **EXTEND**: Full-chain validation can append `code_quality` as a parallel section when the run includes review-based clean-code checks +- **EXTEND**: Policy engine results formatted as evidence-compatible structures +- **NEW**: Ownership authority — this change is authoritative for evidence JSON envelope/schema; sibling governance changes may add fields only through this envelope contract. + +## Capabilities +### New Capabilities + +- `governance-evidence-output`: Machine-readable JSON evidence artifacts for CI/CD gates and audit systems, with per-run persistence, CI exit code modes, coverage percentages, exception status, and profile-aware verdicts. + +### Modified Capabilities + +- `full-chain-validation`: Extended with evidence artifact generation via `--evidence-dir` and `--ci-mode` flags +- `policy-engine`: Results formatted as evidence-compatible structures with run_id and timestamps +- `governance-evidence-output`: Extended with a `code_quality` section that remains parallel to `validation_results` rather than introducing a new traceability layer + + +--- + +## Source Tracking + + +- **Core Counterpart Issue**: nold-ai/specfact-cli#247 +- **GitHub Issue**: #169 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/governance-01-evidence-output/specs/full-chain-validation/spec.md b/openspec/changes/governance-01-evidence-output/specs/full-chain-validation/spec.md new file mode 100644 index 0000000..ab93683 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/specs/full-chain-validation/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Full Chain Validation +Full-chain validation SHALL emit governance-ready evidence artifacts. + +#### Scenario: Evidence artifact is written with stable schema envelope +- **GIVEN** full-chain validation executes with evidence output enabled +- **WHEN** command completes +- **THEN** evidence includes schema version, timestamp, profile, policy mode, layer summaries, and overall status +- **AND** artifact path is printed for CI ingestion. diff --git a/openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/oscal-trace-delta.md b/openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/oscal-trace-delta.md new file mode 100644 index 0000000..89a5ea4 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/oscal-trace-delta.md @@ -0,0 +1,33 @@ +## ADDED Requirements + +### Requirement: OSCAL-Aligned Evidence Envelope with Trace Fields +The system SHALL extend the governance evidence JSON envelope to include a `trace` object with `upstream` and `downstream` arrays, aligned with OSCAL Assessment Results model patterns, enabling bidirectional artifact navigation from any evidence record. + +#### Scenario: Evidence envelope contains trace links for requirement-level artifacts +- **GIVEN** a `BusinessRule` artifact that was validated by SpecFact +- **WHEN** the governance evidence envelope is generated for that artifact +- **THEN** the evidence JSON includes a `trace` object: + - `trace.upstream` contains the parent `BusinessOutcome` ID(s) + - `trace.downstream` contains at least one of: spec ID, contract ID, or test ID linked to the rule +- **AND** the envelope validates against the updated evidence schema + +#### Scenario: Evidence envelope captures per-check results +- **GIVEN** a validation run that checks schema_conformance, gwt_parseable, example_bound, and outcome_linked +- **WHEN** the evidence envelope is emitted +- **THEN** the `validation.checks` array contains one entry per check with `name`, `result` (pass/fail/error), and optional metadata fields (e.g., `test_id`, `outcome_id`) +- **AND** the overall `verdict` field is derivable from the check results without re-running validation + +#### Scenario: OSCAL-aligned structure for compliance consumers +- **GIVEN** a governance evidence JSON file produced by SpecFact +- **WHEN** it is consumed by an OSCAL Assessment Results reader +- **THEN** the `validation.verdict` field maps to OSCAL's `finding.target.status` (pass/fail/not-applicable) +- **AND** the `artifact.hash` field provides the `subject.resource-id` equivalent for audit traceability + +### Requirement: Artifact Hash in Evidence Envelope +The system SHALL include a SHA-256 hash of the validated artifact in every evidence envelope, enabling immutable audit trail construction. + +#### Scenario: Artifact hash computed and included in evidence +- **GIVEN** a requirement artifact file at `.specfact/requirements/BR-001.req.yaml` +- **WHEN** `specfact validate --full-chain --evidence-dir .specfact/evidence/` runs +- **THEN** the evidence envelope for BR-001 includes `artifact.hash: "sha256:"` +- **AND** the hash is computed from the file contents at the time of validation (not from a prior snapshot) diff --git a/openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/spec.md b/openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/spec.md new file mode 100644 index 0000000..45e0b17 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/specs/governance-evidence-output/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Governance Evidence Output +The system SHALL produce machine-readable governance evidence suitable for CI and audit ingestion. + +#### Scenario: CI-consumable evidence includes policy and exception context +- **GIVEN** validation runs in CI mode +- **WHEN** evidence is generated +- **THEN** policy results and active exception references are included +- **AND** each exception includes identifier and expiration metadata. + +#### Scenario: Evidence contains layer-level coverage metrics +- **GIVEN** full-chain validation has transition results +- **WHEN** governance evidence is emitted +- **THEN** each layer contains pass/fail/advisory counts and coverage percentages +- **AND** overall verdict is derivable from the evidence alone. + +#### Scenario: Evidence carries clean-code results as a parallel quality dimension +- **GIVEN** a validation run includes `specfact review` clean-code output +- **WHEN** governance evidence is emitted +- **THEN** the envelope includes a top-level `code_quality` section with category counts and verdict +- **AND** clean-code data does not redefine or replace the traceability `validation_results.layers` structure diff --git a/openspec/changes/governance-01-evidence-output/specs/policy-engine/spec.md b/openspec/changes/governance-01-evidence-output/specs/policy-engine/spec.md new file mode 100644 index 0000000..492c42b --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/specs/policy-engine/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Policy Engine +Policy evaluation outputs SHALL be serializable into governance evidence records. + +#### Scenario: Policy rule results include evidence-ready fields +- **GIVEN** policy validation completes +- **WHEN** evidence serialization runs +- **THEN** each rule result includes rule ID, severity, mode, and outcome +- **AND** output can be consumed by CI gates without additional transformation. diff --git a/openspec/changes/governance-01-evidence-output/tasks.md b/openspec/changes/governance-01-evidence-output/tasks.md new file mode 100644 index 0000000..410c537 --- /dev/null +++ b/openspec/changes/governance-01-evidence-output/tasks.md @@ -0,0 +1,32 @@ +# Tasks: governance-01-evidence-output + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/governance-01-evidence-output` from `dev` before implementation work: `scripts/worktree.sh create feature/governance-01-evidence-output`. +- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. +- [ ] 1.4 Confirm governance-01 ownership of evidence envelope/schema per `openspec/CHANGE_ORDER.md` before modifying shared outputs. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. +- [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. +- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. +- [ ] 3.4 Keep clean-code evidence as a sibling `code_quality` section in the envelope rather than adding a new validation layer. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate governance-01-evidence-output --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/governance-01-evidence-output` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/governance-02-exception-management/.openspec.yaml b/openspec/changes/governance-02-exception-management/.openspec.yaml new file mode 100644 index 0000000..2a45c1f --- /dev/null +++ b/openspec/changes/governance-02-exception-management/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/governance-02-exception-management/CHANGE_VALIDATION.md b/openspec/changes/governance-02-exception-management/CHANGE_VALIDATION.md new file mode 100644 index 0000000..92bef7b --- /dev/null +++ b/openspec/changes/governance-02-exception-management/CHANGE_VALIDATION.md @@ -0,0 +1,28 @@ +# Change Validation: governance-02-exception-management + +- **Validated on (UTC):** 2026-03-22T22:28:26+00:00 +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate governance-02-exception-management --strict` +- **Result:** PASS + +## Scope Summary + +- **Primary capability:** `exception-management` +- **Clean-code delta:** express clean-code exceptions as policy rule IDs and keep exception semantics inside the existing governance model +- **Declared dependencies:** `policy-02-packs-and-modes`; evidence consumer `governance-01-evidence-output` + +## Breaking-Change Analysis (Dry-Run) + +- The delta is schema-constraining rather than schema-expanding: it removes the need for a parallel `principle` field. +- No new exception command surface was introduced. + +## Dependency and Integration Review + +- The policy-rule-ID approach aligns with the clean-code pack manifest. +- No additional changes were required to keep governance ownership boundaries coherent. + +## Validation Outcome + +- Required artifacts are present and parseable. +- Strict OpenSpec validation passed. +- Change remains authoritative for exception suppression semantics. diff --git a/openspec/changes/governance-02-exception-management/design.md b/openspec/changes/governance-02-exception-management/design.md new file mode 100644 index 0000000..833849d --- /dev/null +++ b/openspec/changes/governance-02-exception-management/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `governance-02-exception-management` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- Keep all public APIs contract-first with `@icontract` and `@beartype`. +- Make all behavior extensions opt-in or backward-compatible by default. +- Add/modify OpenSpec deltas first so tests can be derived before implementation. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on policy-02-packs-and-modes. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/governance-02-exception-management/proposal.md b/openspec/changes/governance-02-exception-management/proposal.md new file mode 100644 index 0000000..7a4d078 --- /dev/null +++ b/openspec/changes/governance-02-exception-management/proposal.md @@ -0,0 +1,69 @@ +# Change: Exception Management — Time-Bound, Tracked Policy Exceptions + +## Why + + + + +Enterprises always need exceptions — a legacy service can't comply with the new API versioning policy until migration completes, a regulatory deadline grants a 6-month grace period. But untracked exceptions defeat governance: they become permanent workarounds. Explicit, tracked, time-bound exceptions in config — with automatic expiry, monthly digests, and audit trail — make governance flexible without losing accountability. + +## Ownership Alignment (2026-04-08) + +- Repository assignment: `nold-ai/specfact-cli-modules` +- Modules-owned scope retained here: bundle-side exception handling, suppression workflows, and runtime enforcement behavior. +- Core counterpart retained in `nold-ai/specfact-cli` issue [#248](https://github.com/nold-ai/specfact-cli/issues/248) +- Target hierarchy: modules Epic [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162) -> Feature [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163) -> Story [#167](https://github.com/nold-ai/specfact-cli-modules/issues/167) +- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. +- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. + +## What Changes + + + + +- **NEW**: Exception declaration in `.specfact/exceptions.yaml`: + ```yaml + exceptions: + - id: EXC-1234 + policy: clean-code-principles/banned-generic-public-names + scope: service:legacy-reporting + reason: "Migration in progress, target Q4 2026" + expires_at: 2026-12-31 + approved_by: "CIO" + created_at: 2026-02-15 + ``` +- **NEW**: `specfact exceptions list` — show all active, approaching expiry, and expired exceptions +- **NEW**: `specfact exceptions add --policy --scope --reason --expires --approved-by ` — add a tracked exception +- **NEW**: `specfact exceptions check` — verify all exceptions are still valid (not expired); flag expired exceptions as hard failures +- **NEW**: Behavior during validation: + - Active exception: treated as warning locally, non-blocking in CI + - Approaching expiry (configurable threshold, default 30 days): elevated warning with reminder + - Expired exception: hard failure — same as if exception never existed +- **NEW**: Monthly digest generation: `specfact exceptions digest` — summary of approaching expirations for governance review +- **EXTEND**: Evidence output (governance-01) includes exception status in evidence artifacts +- **EXTEND**: Policy engine respects exception scope during validation — matching exceptions suppress the specific policy rule for the specific scope only, including clean-code pack rules +- **NEW**: Ownership authority — this change is authoritative for exception-scope suppression and expiry semantics; evidence schema remains owned by governance-01. + +## Capabilities +### New Capabilities + +- `exception-management`: Time-bound, tracked policy exceptions with automatic expiry, scope-limited suppression, approaching-expiry warnings, monthly digest generation, and audit trail in evidence artifacts. + +### Modified Capabilities + +- `policy-engine`: Extended to respect exception scope during validation (suppress specific policy for specific scope) +- `exception-management`: Extended so clean-code exceptions are expressed by policy rule ID, not by introducing a parallel `principle` exception schema +- `governance-evidence-output`: Extended to include exception status in evidence artifacts + + +--- + +## Source Tracking + + +- **Core Counterpart Issue**: nold-ai/specfact-cli#248 +- **GitHub Issue**: #167 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/governance-02-exception-management/specs/exception-management/spec.md b/openspec/changes/governance-02-exception-management/specs/exception-management/spec.md new file mode 100644 index 0000000..5389287 --- /dev/null +++ b/openspec/changes/governance-02-exception-management/specs/exception-management/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Exception Management +The system SHALL support explicit, tracked, and time-bound governance exceptions. + +#### Scenario: Active exception suppresses blocking until expiry +- **GIVEN** `.specfact/exceptions.yaml` contains an active exception for a policy and scope +- **WHEN** policy validation runs before expiration +- **THEN** matching violation is downgraded from blocking to non-blocking +- **AND** evidence records the applied exception ID. + +#### Scenario: Expired exception restores blocking behavior +- **GIVEN** exception expiry date is in the past +- **WHEN** matching policy violation occurs +- **THEN** violation is treated per normal mode semantics +- **AND** output identifies the exception as expired. + +#### Scenario: Clean-code exceptions target policy rule identifiers +- **GIVEN** `.specfact/exceptions.yaml` contains `policy: clean-code-principles/banned-generic-public-names` +- **WHEN** a matching naming finding is emitted within the declared scope +- **THEN** that specific rule is suppressed according to the exception lifecycle +- **AND** no separate `principle` field is required in the exception schema diff --git a/openspec/changes/governance-02-exception-management/specs/governance-evidence-output/spec.md b/openspec/changes/governance-02-exception-management/specs/governance-evidence-output/spec.md new file mode 100644 index 0000000..d94d371 --- /dev/null +++ b/openspec/changes/governance-02-exception-management/specs/governance-evidence-output/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Governance Evidence Output +Governance evidence SHALL include exception lifecycle status for active and expired exceptions. + +#### Scenario: Exception lifecycle is visible in evidence +- **GIVEN** evidence generation runs with configured exceptions +- **WHEN** artifact is emitted +- **THEN** evidence lists applied, pending-expiry, and expired exception states +- **AND** each entry includes policy, scope, and expiry date. diff --git a/openspec/changes/governance-02-exception-management/specs/policy-engine/spec.md b/openspec/changes/governance-02-exception-management/specs/policy-engine/spec.md new file mode 100644 index 0000000..481da68 --- /dev/null +++ b/openspec/changes/governance-02-exception-management/specs/policy-engine/spec.md @@ -0,0 +1,10 @@ +## MODIFIED Requirements + +### Requirement: Policy Engine +Policy evaluation SHALL apply scoped exceptions before computing final blocking outcome. + +#### Scenario: Scope mismatch does not suppress violation +- **GIVEN** exception exists for a different scope than the evaluated artifact +- **WHEN** policy rule fails +- **THEN** violation is not suppressed +- **AND** engine reports scope mismatch diagnostics. diff --git a/openspec/changes/governance-02-exception-management/tasks.md b/openspec/changes/governance-02-exception-management/tasks.md new file mode 100644 index 0000000..1b7cbdb --- /dev/null +++ b/openspec/changes/governance-02-exception-management/tasks.md @@ -0,0 +1,32 @@ +# Tasks: governance-02-exception-management + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/governance-02-exception-management` from `dev` before implementation work: `scripts/worktree.sh create feature/governance-02-exception-management`. +- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. +- [ ] 1.4 Confirm exception-scope ownership boundaries per `openspec/CHANGE_ORDER.md` and avoid schema-envelope changes owned by governance-01. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. +- [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. +- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. +- [ ] 3.4 Keep exception scope keyed by policy rule ID (for example `clean-code-principles/`) and avoid adding a separate clean-code-principle exception model. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate governance-02-exception-management --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/governance-02-exception-management` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/openspec-01-intent-trace/.openspec.yaml b/openspec/changes/openspec-01-intent-trace/.openspec.yaml new file mode 100644 index 0000000..8f0b869 --- /dev/null +++ b/openspec/changes/openspec-01-intent-trace/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-05 diff --git a/openspec/changes/openspec-01-intent-trace/CHANGE_VALIDATION.md b/openspec/changes/openspec-01-intent-trace/CHANGE_VALIDATION.md new file mode 100644 index 0000000..5212694 --- /dev/null +++ b/openspec/changes/openspec-01-intent-trace/CHANGE_VALIDATION.md @@ -0,0 +1,110 @@ +# Change Validation Report: openspec-01-intent-trace + +**Validation Date**: 2026-03-05 +**Change Proposal**: [proposal.md](./proposal.md) +**Validation Method**: Dry-run simulation — codebase interface analysis + temporary workspace +**Source Plan**: `specfact-cli-internal/docs/internal/implementation/2026-03-05-CLAUDE-RESEARCH-INTENT-DRIVEN-DEVELOPMENT.md` + +## Executive Summary + +- Breaking Changes: 0 detected +- Dependent Files: 3 files affected (additive, non-breaking) +- Impact Level: Low-Medium (extends existing adapter with optional new capability) +- Validation Result: **Pass** +- User Decision: N/A +- Implementation Constraint Identified: 1 (beartype type-annotation — implementation note, not a blocker) + +## Breaking Changes Detected + +None. All interface extensions are additive and optional: +- `parse_change_proposal()` returns `dict[str, Any]` — adding optional `"intent_trace"` key is non-breaking +- `--import-intent` CLI flag has no default effect (opt-in) +- New files (`intent_trace_validator.py`, `intent-trace.schema.json`) have no existing callers + +## Implementation Constraint (Non-Breaking) + +**Constraint**: `_parse_proposal_content()` at `openspec_parser.py:335` has type annotation `dict[str, str]` (return type). If intent trace data (a nested dict) were added here, `@beartype` would raise a type error. + +**Required implementation approach**: Intent trace extraction MUST be done in `parse_change_proposal()` (returns `dict[str, Any]`) by: +1. Calling `_parse_proposal_content(content)` as usual → returns `dict[str, str]` +2. Separately extracting the YAML fenced block under `## Intent Trace` from `content` +3. Parsing with `yaml.safe_load()` and assigning to `result["intent_trace"]` +4. `parse_change_proposal()` return dict is `dict[str, Any]` — no type violation + +The task at step 5.2 ("Add `## Intent Trace` section parser") should be executed in `parse_change_proposal()`, not in `_parse_proposal_content()`. This is an implementation detail — recommend adding a note to `tasks.md`. + +## Dependencies Affected + +### Critical (hard blockers — must land before `--import-intent` write path) + +| Dependency | Issue | Status | +|---|---|---| +| `requirements-01-data-model` | [#238](https://github.com/nold-ai/specfact-cli/issues/238) | PENDING (Wave 5) | +| `requirements-02-module-commands` | [#239](https://github.com/nold-ai/specfact-cli/issues/239) | PENDING (Wave 5/6) | + +Note: The validation/parsing components (JSON Schema, `validate_intent_trace()`, parser extension) do NOT require requirements-01/02. Only the `--import-intent` write path (creating `.req.yaml` files) requires them. This means parsing and validation can be implemented ahead of Wave 5. + +### Recommended Updates (affected, not breaking) + +| File | Reason | Update Type | +|---|---|---| +| `src/specfact_cli/adapters/openspec_parser.py` | Extend `parse_change_proposal()` with intent trace extraction | Additive | +| `src/specfact_cli/adapters/openspec.py` | Extend `_import_change_proposal()` to pass intent trace to bundle; add `--import-intent` path | Additive | +| `src/specfact_cli/validators/change_proposal_integration.py` | May need to call `validate_intent_trace()` when strict mode enabled | Additive | + +## Impact Assessment + +- **Code Impact**: Low — 2 existing files extended (additive only), 2 new files created +- **Test Impact**: Low — new test files only; no existing test modifications required +- **Documentation Impact**: Medium — `docs/adapters/openspec.md` and `docs/guides/openspec-journey.md` need updates +- **Release Impact**: Minor version bump (new features, no breaking changes) + +## Format Validation + +- **proposal.md Format**: Pass + - `# Change:` title ✓ + - `## Why`, `## What Changes`, `## Capabilities`, `## Impact` sections ✓ + - NEW/EXTEND markers ✓ + - Capabilities linked to spec folders ✓ + - Source Tracking section ✓ +- **tasks.md Format**: Pass + - Hierarchical `## 1.`…`## 10.` structure ✓ + - Task 1 = git worktree creation ✓ + - Task 10 = PR creation (last) ✓ + - Post-merge cleanup section ✓ + - TDD / SDD order section at top ✓ + - Tests before implementation (Tasks 2-3 tests before Tasks 4-5 implementation) ✓ + - `TDD_EVIDENCE.md` recording tasks ✓ + - Quality gate tasks ✓ + - Documentation task included ✓ + - Version and changelog task ✓ + - GitHub issue creation task ✓ + - Module signing verification task: not included — this change has no module-package.yaml changes; acceptable +- **specs Format**: Pass + - `####` for scenario headers ✓ + - `## ADDED Requirements` / `## MODIFIED Requirements` delta format ✓ + - G/W/T format with THEN/AND ✓ + - Every requirement has ≥1 scenario ✓ +- **Config.yaml Compliance**: Pass + +## OpenSpec Validation + +- **Status**: Pass +- **Command**: `openspec validate openspec-01-intent-trace --strict` +- **Output**: `Change 'openspec-01-intent-trace' is valid` +- **Issues Found/Fixed**: 0 + +## Dependency Phasing Note + +Unlike ai-integration-04, this change has **two separable implementation phases**: + +1. **Phase A (can land with Wave 5/6)**: JSON Schema definition, `validate_intent_trace()`, parser extension to extract the intent trace block, `openspec validate --strict` hook. No dependency on requirements-01/02. +2. **Phase B (requires Wave 5 complete)**: `--import-intent` flag and `.req.yaml` artifact writer. Requires `BusinessOutcome`/`BusinessRule` Pydantic models. + +Tasks 2-4 can proceed as soon as the worktree is created. Task 5.3 (`--import-intent` flag) should wait for requirements-01 (#238). + +## Ownership Authority + +- **Intent trace schema** (`openspec/schemas/intent-trace.schema.json`): owned by this change; aligns with `requirements-01-data-model` field definitions (no conflict — requirements-01 owns the Pydantic model, this change owns the JSON Schema) +- **`parse_change_proposal()` return dict** (`openspec_parser.py`): existing authority is `openspec_parser.py` itself; this change adds the `"intent_trace"` key — no conflict +- **`--import-intent` write path** in `openspec.py`: this change is authoritative; no other pending change touches this code path diff --git a/openspec/changes/openspec-01-intent-trace/design.md b/openspec/changes/openspec-01-intent-trace/design.md new file mode 100644 index 0000000..22e7db5 --- /dev/null +++ b/openspec/changes/openspec-01-intent-trace/design.md @@ -0,0 +1,83 @@ +# Design: OpenSpec Intent Trace — Bridge Adapter Integration + +## Context + +SpecFact's OpenSpec bridge adapter (`specfact sync bridge --adapter openspec`) reads proposal and task files from an OpenSpec change directory and imports them into SpecFact's project bundle. Currently it reads: title, description, tasks list, and spec references. It does not read any business intent context. This change adds an optional `## Intent Trace` YAML block to the OpenSpec proposal format and teaches the bridge adapter to import it into the `.specfact/requirements/` storage hierarchy used by requirements-01-data-model. + +The principle is: **"OpenSpec owns the intent. SpecFact owns the evidence."** OpenSpec authors write intent in a human-readable YAML block; SpecFact validates conformance and generates evidence. This separation keeps the intent format tool-agnostic. + +## Goals / Non-Goals + +**Goals:** +- Define the `## Intent Trace` section YAML schema and JSON Schema validator +- Extend the OpenSpec bridge adapter to parse and import intent artifacts when the section is present +- Keep the `## Intent Trace` section strictly optional — existing proposals without it are unaffected +- Validate the section against the JSON Schema during `openspec validate --strict` +- Produce `.specfact/requirements/{id}.req.yaml` artifacts from imported intent data + +**Non-Goals:** +- Forcing all existing OpenSpec proposals to add an `## Intent Trace` section +- Building a new proposal authoring tool — the section is hand-authored YAML in Markdown +- Replacing requirements-01/02 commands — the bridge adapter imports intent; the requirements module validates and traces it + +## Decisions + +### D1: YAML fenced block vs structured Markdown headings for Intent Trace + +**Decision**: YAML fenced block under `## Intent Trace` heading +```yaml +intent_trace: + business_outcomes: + - id: "BO-001" + description: "..." + persona: "..." + business_rules: + - id: "BR-001" + outcome_ref: "BO-001" + given: "..." + when: "..." + then: "..." +``` +**Rationale**: YAML is machine-parseable with a single `yaml.safe_load()` call and maps directly to Pydantic models. Structured Markdown headings require custom parsing logic that is brittle and hard to validate with JSON Schema. YAML fenced blocks are already used in GitHub Actions, Docker Compose, and Kubernetes manifests — authors are familiar with the pattern. +**Alternative rejected**: Structured `### Business Outcomes / ### Business Rules` Markdown sub-sections — readable but not JSON Schema validatable. + +### D2: JSON Schema stored in SpecFact vs in OpenSpec format repo + +**Decision**: JSON Schema at `openspec/schemas/intent-trace.schema.json` within SpecFact's own repo +**Rationale**: SpecFact is the authority for validation. The schema living in SpecFact's repo means the bridge adapter always validates against the version it was built with. When OpenSpec is an external tool (not this repo), the schema reference is still resolvable locally. +**Alternative rejected**: Hosting schema at `openspec.dev/schemas/intent-trace` — external HTTP dependency violates offline-first constraint. + +### D3: `--import-intent` flag vs automatic intent import + +**Decision**: `specfact sync bridge --adapter openspec --import-intent` — opt-in flag +**Rationale**: Not every team using the OpenSpec bridge wants `.specfact/requirements/` files created from every proposal import. The opt-in flag gives teams control. When `## Intent Trace` is present but `--import-intent` is not passed, the bridge still validates the section on `openspec validate --strict` but does not write requirements artifacts. +**Alternative rejected**: Automatic import when section is present — surprising side effect; could overwrite existing requirement files. + +### D4: `requirement_refs` in tasks.md — free-form vs validated IDs + +**Decision**: Free-form string list (`["BR-001", "AC-002"]`) with advisory validation +**Rationale**: Task-level requirement refs are metadata for traceability, not for enforcement. Advisory-mode validation warns if a ref ID does not match any known `BusinessRule` or `ArchitecturalConstraint` in `.specfact/requirements/` but does not block import. Hard enforcement would break workflows where requirements are not yet captured. + +### D5: `evidence` field in archived changes + +**Decision**: Optional string field in change archive metadata: `evidence: ".specfact/evidence/{timestamp}_{run_id}_evidence.json"` +**Rationale**: Minimal — just a file path reference. The evidence file itself is owned by governance-01-evidence-output. The archive metadata is a pointer, not a copy. This keeps the archive lightweight while enabling audit trail navigation. + +## Risks / Trade-offs + +- **[Risk] YAML indentation errors in proposals** — Authors writing `## Intent Trace` blocks manually may introduce YAML syntax errors. Mitigation: `openspec validate --strict` catches YAML parse errors before import; error message shows the line number and suggests a fix. +- **[Risk] ID collision between imported BusinessOutcome IDs and existing requirements** — If a team runs `--import-intent` twice with the same proposal, duplicate `.req.yaml` files may result. Mitigation: bridge adapter checks for existing file with same ID before writing; uses `--overwrite` flag to allow update. +- **[Trade-off] Schema evolution** — As requirements-01-data-model evolves (new fields), the `intent-trace.schema.json` must stay in sync. Mitigation: schema versioning (`schema_version: "1.0"` in the YAML block); bridge adapter rejects unknown schema versions with a clear error. + +## Migration Plan + +1. Land requirements-01-data-model (#238) — `BusinessOutcome` and `BusinessRule` Pydantic models must exist. +2. Define `intent-trace.schema.json` using the Pydantic model fields from requirements-01 as source of truth. +3. Extend bridge adapter parser to detect `## Intent Trace` section and extract the YAML block. +4. Implement `--import-intent` flag and requirements artifact writer. +5. Extend `openspec validate --strict` to call JSON Schema validator on intent trace section. +6. Update existing SpecFact dogfood proposals (this repo's `openspec/changes/`) with `## Intent Trace` sections as the team adopts the format. + +## Open Questions + +- None currently blocking implementation. diff --git a/openspec/changes/openspec-01-intent-trace/proposal.md b/openspec/changes/openspec-01-intent-trace/proposal.md new file mode 100644 index 0000000..40d6ce1 --- /dev/null +++ b/openspec/changes/openspec-01-intent-trace/proposal.md @@ -0,0 +1,56 @@ +# Change: OpenSpec Intent Trace — Bridge Adapter Integration + +## Why + +OpenSpec proposals are plain Markdown with no structured business-intent metadata. When SpecFact imports a proposal via `specfact sync bridge --adapter openspec`, it has no machine-readable context about the business outcomes, business rules, or architectural constraints the change is supposed to satisfy — it only sees tasks and specs. This means the traceability chain starts at the spec level, missing the upstream intent layer entirely. Adding a structured `## Intent Trace` section to OpenSpec proposals (with JSON Schema validation) gives SpecFact the data it needs to construct the full outcome → rule → constraint → spec → code chain automatically on import. + +## Ownership Alignment (2026-04-08) + +- Repository assignment: `nold-ai/specfact-cli-modules` +- Modules-owned scope retained here: bundle-side import and sync runtime behavior for OpenSpec intent-trace workflows. +- Core counterpart retained in `nold-ai/specfact-cli` issue [#350](https://github.com/nold-ai/specfact-cli/issues/350) +- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) -> Story [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) +- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. +- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. + +## What Changes + +- **NEW**: `## Intent Trace` section schema for OpenSpec `proposal.md` files: + - YAML-fenced block under `## Intent Trace` with `intent_trace` root key + - Fields: `business_outcomes` (id, description, persona), `business_rules` (id, outcome_ref, given, when, then), `architectural_constraints` (id, outcome_ref, constraint), `requirement_refs` (list of REQ-NNN strings) + - JSON Schema at `openspec/schemas/intent-trace.schema.json` for validation +- **NEW**: `requirement_refs` optional field on individual tasks in `tasks.md` — links a task to specific `BusinessRule` IDs or `ArchitecturalConstraint` IDs +- **NEW**: `evidence` optional field on archived changes — points to evidence JSON envelope file(s) generated during implementation; creates immutable proposal → intent trace → implementation → evidence → archive chain +- **NEW**: `specfact sync bridge --adapter openspec --import-intent` — reads `## Intent Trace` section from imported proposals and populates `.specfact/requirements/` with `BusinessOutcome` and `BusinessRule` artifacts automatically +- **EXTEND**: `specfact sync bridge --adapter openspec` — when `## Intent Trace` section is present, include intent context in the imported project bundle; backwards-compatible (section is optional) +- **EXTEND**: `openspec validate --strict` — validates `## Intent Trace` section against `intent-trace.schema.json` when present + +## Capabilities + +### New Capabilities + +- `openspec-intent-trace-schema`: JSON Schema definition and validation for the `## Intent Trace` section in OpenSpec proposals — enabling machine-readable business-outcome traceability in change proposals. +- `openspec-bridge-intent-import`: Extended SpecFact OpenSpec bridge adapter that reads, validates, and imports `## Intent Trace` sections from proposals into `.specfact/requirements/` artifacts automatically. + +### Modified Capabilities + +- `openspec-bridge-adapter`: Extended to parse optional `## Intent Trace` section on proposal import; backwards-compatible when section is absent. + +## Impact + +- New file: `openspec/schemas/intent-trace.schema.json` +- Existing bridge adapter: `src/specfact_cli/adapters/` OpenSpec adapter extended with intent-trace parsing +- CLI change: `specfact sync bridge --adapter openspec` — new optional `--import-intent` flag; no breaking change to existing workflows +- Depends on: `requirements-01-data-model` (#238) — `BusinessOutcome` and `BusinessRule` schemas must exist to populate; `requirements-02-module-commands` (#239) — `specfact requirements capture` used for artifact creation +- Wave: aligns with Wave 5/6 (after requirements-01/02 land) +- Docs: new `docs/guides/openspec-journey.md` section on Intent Trace; update `docs/adapters/` for OpenSpec adapter + +--- + +## Source Tracking + + +- **GitHub Issue**: #350 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli +- **Last Synced Status**: proposed diff --git a/openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-adapter/spec.md b/openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-adapter/spec.md new file mode 100644 index 0000000..2012e70 --- /dev/null +++ b/openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-adapter/spec.md @@ -0,0 +1,22 @@ +## MODIFIED Requirements + +### Requirement: OpenSpec Bridge Adapter Import +The system SHALL import OpenSpec change proposals into SpecFact's project bundle with full backwards compatibility when the `## Intent Trace` section is absent, and include intent context when the section is present. + +#### Scenario: Proposal import without Intent Trace section is unchanged +- **GIVEN** an OpenSpec proposal that has no `## Intent Trace` section +- **WHEN** `specfact sync bridge --adapter openspec` is run +- **THEN** the import behaviour is identical to the pre-change behaviour +- **AND** no error, warning, or advisory is emitted related to missing intent trace + +#### Scenario: Proposal import includes intent context when section is present +- **GIVEN** an OpenSpec proposal with a valid `## Intent Trace` section +- **WHEN** `specfact sync bridge --adapter openspec` is run (without `--import-intent`) +- **THEN** the proposal's intent trace metadata is attached to the project bundle as read-only context +- **AND** `specfact project health-check` can report that intent context is available for the change + +#### Scenario: `openspec validate --strict` validates intent trace when present +- **GIVEN** an OpenSpec change with a proposal containing a `## Intent Trace` section +- **WHEN** `openspec validate --strict` is run +- **THEN** the validator checks the YAML block against `intent-trace.schema.json` +- **AND** any schema violations cause a non-zero exit code with descriptive error messages diff --git a/openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-intent-import/spec.md b/openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-intent-import/spec.md new file mode 100644 index 0000000..6d04cad --- /dev/null +++ b/openspec/changes/openspec-01-intent-trace/specs/openspec-bridge-intent-import/spec.md @@ -0,0 +1,49 @@ +## ADDED Requirements + +### Requirement: Bridge Adapter Intent Import +The system SHALL extend `specfact sync bridge --adapter openspec` with an `--import-intent` flag that reads the `## Intent Trace` YAML block from imported proposals and creates corresponding `.specfact/requirements/{id}.req.yaml` artifacts. + +#### Scenario: Intent import creates BusinessOutcome artifacts +- **GIVEN** an OpenSpec proposal with a `## Intent Trace` section containing at least one `business_outcomes` entry +- **WHEN** `specfact sync bridge --adapter openspec --import-intent` is run +- **THEN** a `.specfact/requirements/{id}.req.yaml` file is created for each `BusinessOutcome` in the intent trace +- **AND** each artifact validates against the `BusinessOutcome` Pydantic schema without errors + +#### Scenario: Intent import creates BusinessRule artifacts +- **GIVEN** an OpenSpec proposal with `business_rules` entries in the `## Intent Trace` section +- **WHEN** `specfact sync bridge --adapter openspec --import-intent` is run +- **THEN** each `BusinessRule` (id, outcome_ref, given, when, then) is stored in the corresponding `.req.yaml` artifact under its parent `BusinessOutcome` +- **AND** the `outcome_ref` is resolved to a valid `BusinessOutcome` ID in the imported requirements + +#### Scenario: Intent import skips existing artifacts without --overwrite +- **GIVEN** a `.specfact/requirements/BO-001.req.yaml` file already exists +- **WHEN** `specfact sync bridge --adapter openspec --import-intent` is run without `--overwrite` +- **THEN** the existing file is not modified +- **AND** the CLI output notes the skipped artifact with its ID + +#### Scenario: Intent import overwrites with --overwrite flag +- **GIVEN** a `.specfact/requirements/BO-001.req.yaml` file already exists +- **WHEN** `specfact sync bridge --adapter openspec --import-intent --overwrite` is run +- **THEN** the existing file is updated with the content from the proposal's intent trace section +- **AND** the CLI output confirms the overwritten artifact ID + +#### Scenario: Import without --import-intent ignores intent trace section +- **GIVEN** an OpenSpec proposal with a `## Intent Trace` section +- **WHEN** `specfact sync bridge --adapter openspec` is run without `--import-intent` +- **THEN** no `.specfact/requirements/` artifacts are created +- **AND** the section is validated but not imported + +### Requirement: Task-Level Requirement References +The system SHALL support an optional `requirement_refs` list field on individual tasks in OpenSpec `tasks.md` files, linking tasks to specific `BusinessRule` or `ArchitecturalConstraint` IDs. + +#### Scenario: Bridge adapter parses requirement_refs in tasks +- **GIVEN** a `tasks.md` file with a task containing `requirement_refs: ["BR-001", "AC-002"]` +- **WHEN** the bridge adapter imports the proposal +- **THEN** the imported task record includes the requirement ref IDs +- **AND** they are included in the project bundle's task metadata + +#### Scenario: Advisory validation warns on unresolved requirement refs +- **GIVEN** a task with `requirement_refs: ["BR-999"]` where BR-999 does not exist in `.specfact/requirements/` +- **WHEN** `specfact sync bridge --adapter openspec` is run +- **THEN** the CLI emits an advisory warning: `[ADVISORY] Task X: requirement_refs contains unknown ID BR-999` +- **AND** the import proceeds without failing diff --git a/openspec/changes/openspec-01-intent-trace/specs/openspec-intent-trace-schema/spec.md b/openspec/changes/openspec-01-intent-trace/specs/openspec-intent-trace-schema/spec.md new file mode 100644 index 0000000..b9fa93a --- /dev/null +++ b/openspec/changes/openspec-01-intent-trace/specs/openspec-intent-trace-schema/spec.md @@ -0,0 +1,42 @@ +## ADDED Requirements + +### Requirement: Intent Trace Section Schema +The system SHALL define a JSON Schema at `openspec/schemas/intent-trace.schema.json` that validates the `## Intent Trace` YAML block in OpenSpec proposal files. + +#### Scenario: Valid intent trace section passes schema validation +- **GIVEN** an OpenSpec proposal with a correctly structured `## Intent Trace` YAML block +- **WHEN** `openspec validate --strict` is run +- **THEN** the intent trace section validates without errors +- **AND** the validation output confirms intent trace section is present and valid + +#### Scenario: Invalid intent trace section fails schema validation +- **GIVEN** an OpenSpec proposal with a `## Intent Trace` YAML block missing a required field (e.g., `id` on a `BusinessOutcome`) +- **WHEN** `openspec validate --strict` is run +- **THEN** the validation exits with a non-zero code +- **AND** the error message identifies the specific field violation and the line context + +#### Scenario: Missing intent trace section is valid (section is optional) +- **GIVEN** an OpenSpec proposal without any `## Intent Trace` section +- **WHEN** `openspec validate --strict` is run +- **THEN** the validation passes without intent-trace errors +- **AND** no warning about missing intent trace is emitted in normal mode + +#### Scenario: Intent trace schema includes schema version field +- **GIVEN** an intent trace YAML block with `schema_version: "1.0"` +- **WHEN** the bridge adapter reads the block +- **THEN** it accepts the artifact and records the schema version +- **AND** if the schema version is unknown the adapter emits a clear error with supported versions + +### Requirement: Intent Trace Evidence Field in Archive +The system SHALL support an optional `evidence` field in change archive metadata pointing to the evidence JSON envelope file produced during implementation. + +#### Scenario: Archive metadata includes evidence reference +- **GIVEN** an archived change that generated a governance evidence artifact +- **WHEN** the archive metadata is read +- **THEN** the `evidence` field contains a relative path to the `.specfact/evidence/` JSON file +- **AND** the path resolves to a readable file on disk + +#### Scenario: Archive without evidence field is valid +- **GIVEN** an archived change that did not produce governance evidence +- **WHEN** the archive metadata is validated +- **THEN** validation passes without errors related to the missing evidence field diff --git a/openspec/changes/openspec-01-intent-trace/tasks.md b/openspec/changes/openspec-01-intent-trace/tasks.md new file mode 100644 index 0000000..fc8d320 --- /dev/null +++ b/openspec/changes/openspec-01-intent-trace/tasks.md @@ -0,0 +1,151 @@ +# Tasks: OpenSpec Intent Trace — Bridge Adapter Integration + +## TDD / SDD order (enforced) + +Per `openspec/config.yaml`, tests MUST precede production code for any behavior-changing task. + +Order: +1. Spec deltas (already in `specs/`) +2. Tests derived from spec scenarios — run and expect failure +3. Production code — implement until tests pass + +Do not implement production code until tests exist and have been run (expecting failure). + +--- + +## 1. Create git worktree for this change + +- [ ] 1.1 Fetch latest and create a worktree with a new branch from `origin/dev`. + - [ ] 1.1.1 `git fetch origin` + - [ ] 1.1.2 `git worktree add ../specfact-cli-worktrees/feature/openspec-01-intent-trace -b feature/openspec-01-intent-trace origin/dev` + - [ ] 1.1.3 `cd ../specfact-cli-worktrees/feature/openspec-01-intent-trace` + - [ ] 1.1.4 `python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"` + - [ ] 1.1.5 `git branch --show-current` (verify `feature/openspec-01-intent-trace`) + +## 2. Define Intent Trace JSON Schema + +- [ ] 2.1 Create `openspec/schemas/intent-trace.schema.json`: + - [ ] 2.1.1 Root object with `schema_version` (required string), `intent_trace` object + - [ ] 2.1.2 `business_outcomes` array: each item requires `id` (string), `description` (string), `persona` (string) + - [ ] 2.1.3 `business_rules` array: each item requires `id`, `outcome_ref`, `given`, `when`, `then` + - [ ] 2.1.4 `architectural_constraints` array: each item requires `id`, `outcome_ref`, `constraint` + - [ ] 2.1.5 `requirement_refs` optional array of strings + - [ ] 2.1.6 `additionalProperties: false` on all objects for strict validation +- [ ] 2.2 Write schema unit tests in `tests/unit/specfact_cli/test_intent_trace_schema.py`: + - [ ] 2.2.1 Test valid complete intent trace block passes validation + - [ ] 2.2.2 Test missing required `id` field on BusinessOutcome fails + - [ ] 2.2.3 Test missing intent trace section (None) passes (optional) + - [ ] 2.2.4 Test unknown `schema_version` raises descriptive error +- [ ] 2.3 Run schema tests — expect failure: `hatch test -- tests/unit/specfact_cli/test_intent_trace_schema.py -v` +- [ ] 2.4 Record failing test evidence in `TDD_EVIDENCE.md` + +## 3. Write bridge adapter tests (TDD — expect failure) + +- [ ] 3.1 Review existing OpenSpec bridge adapter tests in `tests/` +- [ ] 3.2 Add `tests/unit/specfact_cli/test_openspec_bridge_intent.py`: + - [ ] 3.2.1 Test bridge import of proposal with `## Intent Trace` creates `.req.yaml` files (with `--import-intent`) + - [ ] 3.2.2 Test bridge import without `## Intent Trace` section is unchanged (backwards compatible) + - [ ] 3.2.3 Test `--import-intent` without `--overwrite` skips existing artifacts + - [ ] 3.2.4 Test `--import-intent --overwrite` updates existing artifacts + - [ ] 3.2.5 Test advisory warning on unresolved `requirement_refs` + - [ ] 3.2.6 Test `requirement_refs` parsed into imported task metadata +- [ ] 3.3 Add `tests/integration/test_openspec_intent_trace_e2e.py`: + - [ ] 3.3.1 End-to-end test: proposal with intent trace → bridge import → `.req.yaml` exists and validates +- [ ] 3.4 Run bridge tests — expect failure: `hatch test -- tests/unit/specfact_cli/test_openspec_bridge_intent.py -v` +- [ ] 3.5 Record failing test evidence in `TDD_EVIDENCE.md` + +## 4. Implement Intent Trace schema validator + +- [ ] 4.1 Add `src/specfact_cli/validators/intent_trace_validator.py`: + - [ ] 4.1.1 `validate_intent_trace(yaml_block: dict | None) -> ValidationResult` with `@require` and `@beartype` + - [ ] 4.1.2 Load `openspec/schemas/intent-trace.schema.json` (bundled resource) + - [ ] 4.1.3 Use `jsonschema.validate()` for schema check + - [ ] 4.1.4 Return structured errors with field path, message, and suggestion +- [ ] 4.2 Register schema file in `pyproject.toml` `[tool.hatch.build.targets.wheel]` force-include + +## 5. Extend OpenSpec bridge adapter with intent import + +> **Implementation constraint (from CHANGE_VALIDATION.md)**: `_parse_proposal_content()` in `openspec_parser.py` has return type `dict[str, str]`. Intent trace extraction MUST be done in `parse_change_proposal()` (returns `dict[str, Any]`) — NOT in `_parse_proposal_content()` — to avoid a `@beartype` type violation. + +- [ ] 5.1 Locate OpenSpec bridge adapter in `src/specfact_cli/adapters/` +- [ ] 5.2 Add `## Intent Trace` section parser: + - [ ] 5.2.1 Extract YAML fenced block under `## Intent Trace` heading from proposal Markdown + - [ ] 5.2.2 Parse YAML with `yaml.safe_load()` + - [ ] 5.2.3 Run `validate_intent_trace()` on the parsed block +- [ ] 5.3 Add `--import-intent` flag to `specfact sync bridge --adapter openspec` command: + - [ ] 5.3.1 `@require`: intent import requires requirements-01 module is installed (advisory check) + - [ ] 5.3.2 Write `.specfact/requirements/{id}.req.yaml` for each `BusinessOutcome` + - [ ] 5.3.3 Embed `BusinessRule` entries in parent `.req.yaml` files + - [ ] 5.3.4 Respect `--overwrite` flag; skip existing files otherwise +- [ ] 5.4 Add `requirement_refs` parsing from `tasks.md` task entries + - [ ] 5.4.1 Parse optional `requirement_refs:` YAML field on task lines + - [ ] 5.4.2 Include in imported task metadata in project bundle + - [ ] 5.4.3 Advisory warning for unresolved IDs +- [ ] 5.5 Extend `openspec validate --strict` hook to call `validate_intent_trace()` when section present +- [ ] 5.6 Add `@require`, `@ensure`, `@beartype` decorators to all new public API functions + +## 6. Passing tests and quality gates + +- [ ] 6.1 Run all new tests — expect passing: `hatch test -- tests/unit/specfact_cli/test_intent_trace*.py tests/unit/specfact_cli/test_openspec_bridge*.py tests/integration/test_openspec_intent_trace*.py -v` +- [ ] 6.2 Record passing test evidence in `TDD_EVIDENCE.md` +- [ ] 6.3 `hatch run format` +- [ ] 6.4 `hatch run type-check` +- [ ] 6.5 `hatch run lint` +- [ ] 6.6 `hatch run yaml-lint` +- [ ] 6.7 `hatch run contract-test` +- [ ] 6.8 `hatch run smart-test` + +## 7. Documentation + +- [ ] 7.1 Update `docs/adapters/openspec.md` (or equivalent): + - [ ] 7.1.1 Document `## Intent Trace` section format with full YAML example + - [ ] 7.1.2 Document `--import-intent` and `--overwrite` flags + - [ ] 7.1.3 Document `requirement_refs` field on tasks +- [ ] 7.2 Update `docs/guides/openspec-journey.md` — add Intent Trace section +- [ ] 7.3 Ensure front-matter on all updated/new doc pages is valid (layout, title, permalink, description) +- [ ] 7.4 Update `docs/_layouts/default.html` sidebar navigation if new pages are added + +## 8. Version and changelog + +- [ ] 8.1 Bump minor version in `pyproject.toml`, `setup.py`, `src/__init__.py`, `src/specfact_cli/__init__.py` +- [ ] 8.2 Add CHANGELOG.md entry under new `[X.Y.Z] - 2026-XX-XX` with Added/Changed sections + +## 9. GitHub issue creation + +- [ ] 9.1 Create GitHub issue: + ```bash + gh issue create \ + --repo nold-ai/specfact-cli \ + --title "[Change] OpenSpec Intent Trace — Bridge Adapter Integration" \ + --body-file /tmp/github-issue-openspec-01.md \ + --label "enhancement" \ + --label "change-proposal" + ``` +- [ ] 9.2 Link issue to project: `gh project item-add 1 --owner nold-ai --url ` +- [ ] 9.3 Update `proposal.md` Source Tracking section with issue number and URL +- [ ] 9.4 Link branch to issue: `gh issue develop --repo nold-ai/specfact-cli --name feature/openspec-01-intent-trace` + +## 10. Pull request + +- [ ] 10.1 `git add` all changed files; commit with `feat: add OpenSpec Intent Trace section and bridge adapter import` +- [ ] 10.2 `git push -u origin feature/openspec-01-intent-trace` +- [ ] 10.3 Create PR: + ```bash + gh pr create \ + --repo nold-ai/specfact-cli \ + --base dev \ + --head feature/openspec-01-intent-trace \ + --title "feat: OpenSpec Intent Trace bridge adapter integration" \ + --body-file /tmp/pr-body-openspec-01.md + ``` +- [ ] 10.4 Link PR to project: `gh project item-add 1 --owner nold-ai --url ` +- [ ] 10.5 Set project status to "In Progress" + +## Post-merge cleanup (after PR is merged) + +- [ ] Return to primary checkout: `cd .../specfact-cli` +- [ ] `git fetch origin` +- [ ] `git worktree remove ../specfact-cli-worktrees/feature/openspec-01-intent-trace` +- [ ] `git branch -d feature/openspec-01-intent-trace` +- [ ] `git worktree prune` +- [ ] (Optional) `git push origin --delete feature/openspec-01-intent-trace` diff --git a/openspec/changes/policy-02-packs-and-modes/.openspec.yaml b/openspec/changes/policy-02-packs-and-modes/.openspec.yaml new file mode 100644 index 0000000..2a45c1f --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/policy-02-packs-and-modes/CHANGE_VALIDATION.md b/openspec/changes/policy-02-packs-and-modes/CHANGE_VALIDATION.md new file mode 100644 index 0000000..a6e30a1 --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/CHANGE_VALIDATION.md @@ -0,0 +1,28 @@ +# Change Validation: policy-02-packs-and-modes + +- **Validated on (UTC):** 2026-03-22T22:28:26+00:00 +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate policy-02-packs-and-modes --strict` +- **Result:** PASS + +## Scope Summary + +- **Primary capabilities:** `policy-engine`, `policy-packs-and-modes` +- **Clean-code delta:** define `specfact/clean-code-principles` as a built-in pack and route all severity handling through existing per-rule mode semantics +- **Declared dependencies:** `profile-01-config-layering`; governance and validation consumers + +## Breaking-Change Analysis (Dry-Run) + +- The delta extends policy-pack inventory rather than changing policy-engine ownership boundaries. +- No second clean-code-specific configuration model was introduced. + +## Dependency and Integration Review + +- The clean-code pack hooks align with profile, governance, and validation downstream consumers. +- No scope-extension request was required after dependency review. + +## Validation Outcome + +- Required artifacts are present and parseable. +- Strict OpenSpec validation passed. +- Change remains authoritative for clean-code enforcement mode semantics. diff --git a/openspec/changes/policy-02-packs-and-modes/design.md b/openspec/changes/policy-02-packs-and-modes/design.md new file mode 100644 index 0000000..bbce1bc --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `policy-02-packs-and-modes` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- Keep all public APIs contract-first with `@icontract` and `@beartype`. +- Make all behavior extensions opt-in or backward-compatible by default. +- Add/modify OpenSpec deltas first so tests can be derived before implementation. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on profile-01-config-layering and policy-engine-01-unified-framework. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/policy-02-packs-and-modes/proposal.md b/openspec/changes/policy-02-packs-and-modes/proposal.md new file mode 100644 index 0000000..152de49 --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/proposal.md @@ -0,0 +1,68 @@ +# Change: Policy Packs & Enforcement Modes (Advisory/Mixed/Hard) + +## Why + + + + +Policy enforcement today is binary — pass or fail. Different team sizes need different enforcement levels: a solo developer needs advisory warnings, a startup needs some hard gates, an enterprise needs full enforcement with tracked exceptions. Additionally, policies should be distributable as reusable packs (DoR/DoD basics, compliance packs, domain-specific rules) so teams don't reinvent quality gates. Three enforcement modes (advisory/mixed/hard) with installable policy packs make governance progressive and composable. + +## Ownership Alignment (2026-04-08) + +- Authoritative implementation owner: `nold-ai/specfact-cli-modules`, backlog bundle story [#158](https://github.com/nold-ai/specfact-cli-modules/issues/158) +- Target hierarchy: modules Epic [#145](https://github.com/nold-ai/specfact-cli-modules/issues/145) -> Feature [#148](https://github.com/nold-ai/specfact-cli-modules/issues/148) -> Story `#158` +- This proposal still owns the mode semantics consumed by sibling governance changes, but the user-facing policy command and runtime implementation are now bundle-owned. +- Implementation MUST NOT proceed in `specfact-cli` core for backlog policy command surfaces; retained core work is limited to cross-change semantic references until a narrower delta is defined. + +## What Changes + + + + +- **NEW**: Three enforcement modes with distinct local and CI behavior: + - **Advisory (shadow)**: Warnings only locally, annotations + exit 0 in CI + - **Mixed**: Configurable per rule (some warn, some block); partial blocking in CI + - **Hard**: All violations block locally and in CI; evidence emission required +- **NEW**: Gradual escalation path: new policies start in shadow mode for a configurable period (default 2 weeks), then auto-promote to the profile's default mode. Manual override available. +- **NEW**: Policy packs — installable bundles of related policy rules: + - `specfact policy install specfact/dor-dod-basics` — install built-in DoR/DoD policy pack + - `specfact policy install specfact/clean-code-principles` — install the built-in clean-code pack that maps the 7 principles to concrete review rules + - `specfact policy install org/payments-compliance` — install org-specific policy pack + - Pack format: YAML manifest + rule definitions, versioned, signable (arch-06) +- **NEW**: `specfact policy list --show-mode` — list active policies with their current enforcement mode (shadow/advisory/mixed/hard) and escalation schedule +- **NEW**: Per-rule mode override in `.specfact/policy.yaml`: + ```yaml + policies: + dor-dod-basics: + mode: mixed + rules: + require-acceptance-criteria: hard + require-business-value: advisory + ``` +- **EXTEND**: Policy engine (policy-engine-01) extended with mode-aware execution — `policy.validate` respects the configured mode per rule and per pack +- **EXTEND**: Profile integration — each profile tier has a default enforcement mode (solo=advisory, startup=advisory→mixed, mid-size=mixed, enterprise=hard), and the clean-code pack inherits those defaults instead of defining a parallel clean-code profile system +- **NEW**: Ownership authority — this change is authoritative for policy mode execution semantics; dependent governance changes must consume this contract without redefining mode behavior. + +## Capabilities +### New Capabilities + +- `policy-packs-and-modes`: Distributable policy packs with three enforcement modes (advisory/mixed/hard), gradual escalation, per-rule mode overrides, and profile-driven defaults. Packs are installable, versioned, and signable. + +### Modified Capabilities + +- `policy-engine`: Extended with mode-aware execution (advisory/mixed/hard per rule), shadow-start for new policies, and gradual escalation scheduling +- `policy-packs-and-modes`: Extended with the built-in `specfact/clean-code-principles` pack and per-rule mode mapping for clean-code review findings + + +--- + +## Source Tracking + + +- **Original GitHub Issue**: nold-ai/specfact-cli#246 (transferred 2026-04-08) +- **GitHub Issue**: #158 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false + diff --git a/openspec/changes/policy-02-packs-and-modes/specs/policy-engine/spec.md b/openspec/changes/policy-02-packs-and-modes/specs/policy-engine/spec.md new file mode 100644 index 0000000..6c271f3 --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/specs/policy-engine/spec.md @@ -0,0 +1,22 @@ +## MODIFIED Requirements + +### Requirement: Policy Engine +The policy engine SHALL support advisory, mixed, and hard enforcement modes with per-rule overrides. + +#### Scenario: Advisory mode never blocks +- **GIVEN** policy mode is advisory +- **WHEN** violations are found +- **THEN** command exits successfully +- **AND** violations are emitted as warnings/annotations. + +#### Scenario: Mixed mode applies per-rule blocking semantics +- **GIVEN** mode is mixed and rule severity map marks one rule as blocking +- **WHEN** that rule fails +- **THEN** command exits non-zero +- **AND** non-blocking rule failures remain advisory. + +#### Scenario: Clean-code rules use policy-engine mode mapping +- **GIVEN** the `specfact/clean-code-principles` pack is installed with mixed mode +- **WHEN** a clean-code rule such as `banned-generic-public-names` is overridden to `hard` +- **THEN** the policy engine evaluates that rule as blocking +- **AND** other clean-code rules continue using their configured per-rule modes diff --git a/openspec/changes/policy-02-packs-and-modes/specs/policy-packs-and-modes/spec.md b/openspec/changes/policy-02-packs-and-modes/specs/policy-packs-and-modes/spec.md new file mode 100644 index 0000000..2482688 --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/specs/policy-packs-and-modes/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Policy Packs And Modes +The system SHALL install policy packs and evaluate them under active enforcement mode. + +#### Scenario: Policy pack install and listing +- **GIVEN** `specfact policy install ` +- **WHEN** installation succeeds +- **THEN** pack metadata is persisted in active configuration +- **AND** `specfact policy list --show-mode` displays pack and mode. + +#### Scenario: New policy starts in shadow/advisory period +- **GIVEN** newly installed pack with gradual rollout enabled +- **WHEN** validation is run during rollout window +- **THEN** failures are advisory +- **AND** mode promotion behavior is traceable in config/evidence. + +#### Scenario: Clean-code pack installs as a first-class built-in pack +- **GIVEN** `specfact policy install specfact/clean-code-principles` +- **WHEN** installation succeeds +- **THEN** the pack exposes rule IDs for naming, kiss, yagni, dry, solid, and code-review checks +- **AND** no separate clean-code-specific configuration system is required outside `.specfact/policy.yaml` diff --git a/openspec/changes/policy-02-packs-and-modes/tasks.md b/openspec/changes/policy-02-packs-and-modes/tasks.md new file mode 100644 index 0000000..c522311 --- /dev/null +++ b/openspec/changes/policy-02-packs-and-modes/tasks.md @@ -0,0 +1,32 @@ +# Tasks: policy-02-packs-and-modes + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/policy-02-packs-and-modes` from `dev` before implementation work: `scripts/worktree.sh create feature/policy-02-packs-and-modes`. +- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. +- [ ] 1.4 Confirm ownership authority for policy mode semantics per `openspec/CHANGE_ORDER.md` before editing shared policy-engine surfaces. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. +- [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. +- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. +- [ ] 3.4 Add the built-in `specfact/clean-code-principles` pack definition and wire its per-rule modes through the existing policy-engine path rather than a new clean-code-specific severity mechanism. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate policy-02-packs-and-modes --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/policy-02-packs-and-modes` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/requirements-02-module-commands/.openspec.yaml b/openspec/changes/requirements-02-module-commands/.openspec.yaml new file mode 100644 index 0000000..2a45c1f --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/requirements-02-module-commands/CHANGE_VALIDATION.md b/openspec/changes/requirements-02-module-commands/CHANGE_VALIDATION.md new file mode 100644 index 0000000..4fb21c6 --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: requirements-02-module-commands + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate requirements-02-module-commands --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** requirements-module +- **Modified capabilities:** module-io-contract,backlog-adapter +- **Declared dependencies:** requirements-01 (data model), arch-07 (#213, schema extensions for ProjectBundle) +- **Proposed affected code paths:** - `modules/requirements/` (new module);- `modules/backlog/src/adapters/` (extend adapters with AC text extraction interface) - `src/specfact_cli/contracts/module_interface.py` (no change — new implementation) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/requirements-02-module-commands/design.md b/openspec/changes/requirements-02-module-commands/design.md new file mode 100644 index 0000000..f70d805 --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `requirements-02-module-commands` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- Keep all public APIs contract-first with `@icontract` and `@beartype`. +- Make all behavior extensions opt-in or backward-compatible by default. +- Add/modify OpenSpec deltas first so tests can be derived before implementation. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-01-data-model and arch-07-schema-extension-system. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/requirements-02-module-commands/proposal.md b/openspec/changes/requirements-02-module-commands/proposal.md new file mode 100644 index 0000000..288918a --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/proposal.md @@ -0,0 +1,120 @@ +# Change: Requirements Module — Extract, Author, Validate Commands + +## Why + + + + +Even with a formal data model (requirements-01), there are no CLI commands for working with business requirements. Teams need to extract structured requirements from existing backlog items (reverse-engineer from AC text), author new requirements with profile-aware templates, and validate requirements completeness — all from the terminal. This module is the primary user-facing entry point for the upstream traceability chain. + +## Ownership Alignment (2026-04-08) + +- Repository assignment: `nold-ai/specfact-cli-modules` +- Modules-owned scope retained here: user-facing runtime command delivery, adapter runtime wiring, and grouped bundle command placement for requirements workflows. +- Core counterpart retained in `nold-ai/specfact-cli` issue [#239](https://github.com/nold-ai/specfact-cli/issues/239) +- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) -> Story [#165](https://github.com/nold-ai/specfact-cli-modules/issues/165) +- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. +- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. + +## Module Package Structure + +``` +modules/requirements/ + module-package.yaml # name: requirements; commands: requirements extract, author, validate, list + src/requirements/ + __init__.py + main.py # typer.Typer app — requirements command group + engine/ + extractor.py # Parse AC text from backlog items → structured BusinessRequirement + author.py # Interactive + template-based requirement authoring + validator.py # Validate requirements completeness per profile schema + coverage.py # Compute requirement coverage (arch/spec/code/test links) + templates/ + story.yaml # User story template (As_a, I_want, So_that + business rules) + feature.yaml # Feature template (outcome, rules, constraints, UX) + spike.yaml # Spike template (hypothesis, success criteria) + commands/ + extract.py # specfact requirements extract --from-backlog + author.py # specfact requirements author --template + validate.py # specfact requirements validate + list.py # specfact requirements list --show-coverage +``` + +**`module-package.yaml` declares:** +- `name: requirements` +- `version: 0.1.0` +- `commands: [requirements extract, requirements author, requirements validate, requirements list]` +- `dependencies: [requirements-01-data-model, arch-07-schema-extension-system]` (needs requirements models and schema extensions) +- `schema_extensions:` — via arch-07 +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +## Module Package Structure + +``` +modules/requirements/ + module-package.yaml # name: requirements; commands: requirements extract, author, validate, list + src/requirements/ + __init__.py + main.py # typer.Typer app — requirements command group + engine/ + extractor.py # Parse AC text from backlog items → structured BusinessRequirement + author.py # Interactive + template-based requirement authoring + validator.py # Validate requirements completeness per profile schema + coverage.py # Compute requirement coverage (arch/spec/code/test links) + templates/ + story.yaml # User story template (As_a, I_want, So_that + business rules) + feature.yaml # Feature template (outcome, rules, constraints, UX) + spike.yaml # Spike template (hypothesis, success criteria) + commands/ + extract.py # specfact requirements extract --from-backlog + author.py # specfact requirements author --template + validate.py # specfact requirements validate + list.py # specfact requirements list --show-coverage +``` + +**`module-package.yaml` declares:** +- `name: requirements` +- `version: 0.1.0` +- `commands: [requirements extract, requirements author, requirements validate, requirements list]` +- `dependencies: [requirements-01-data-model, arch-07-schema-extension-system]` (needs requirements models and schema extensions) +- `schema_extensions:` — via arch-07 +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +## What Changes + + + + +- **NEW**: Requirements module in `modules/requirements/` implementing `ModuleIOContract`: + - `import_to_bundle`: Extract requirements from backlog items into ProjectBundle + - `export_from_bundle`: Generate requirements documents (YAML, Markdown) from bundle + - `sync_with_bundle`: Bidirectional sync between requirements and backlog (read-only in v1) + - `validate_bundle`: Check requirements completeness per profile schema +- **NEW**: `specfact requirements extract --from-backlog --project ` — parse acceptance criteria from existing backlog items, infer business rules, generate `.specfact/requirements/*.req.yaml` files +- **NEW**: `specfact requirements author --template story|feature|spike --story STORY-123` — interactive requirement authoring with profile-aware templates (solo gets 3 fields, enterprise gets full schema) +- **NEW**: `specfact requirements validate --requirements-dir .specfact/requirements/` — validate completeness against active profile's required fields +- **NEW**: `specfact requirements list --show-coverage` — list requirements with traceability coverage status (architecture %, spec %, code %, test %) +- **NEW**: Profile-aware templates: solo requires only As_a/I_want/So_that; startup adds Business_outcome + Business_rules; mid-size uses org-defined schema; enterprise adds Regulatory_reference + Risk_owner + +## Capabilities +### New Capabilities + +- `requirements-module`: CLI commands for extracting requirements from backlog items, authoring with profile-aware templates, validating completeness per profile schema, and listing with traceability coverage status. Implements ModuleIOContract for requirements lifecycle. + +### Modified Capabilities + +- `module-io-contract`: New implementation of ModuleIOContract for the requirements domain (import from backlog, export to YAML/Markdown, sync, validate) +- `backlog-adapter`: Extended with requirement extraction hooks — adapters provide raw AC text, extractor parses into structured BusinessRequirement models + + +--- + +## Source Tracking + + +- **Core Counterpart Issue**: nold-ai/specfact-cli#239 +- **GitHub Issue**: #165 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/requirements-02-module-commands/specs/backlog-adapter/spec.md b/openspec/changes/requirements-02-module-commands/specs/backlog-adapter/spec.md new file mode 100644 index 0000000..9a401ff --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/specs/backlog-adapter/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Backlog Adapter +The system SHALL expose backlog acceptance-criteria content to requirements extraction workflows. + +#### Scenario: Adapter returns acceptance criteria payload for extraction +- **GIVEN** a backlog item selected for extraction +- **WHEN** requirements extraction requests source fields +- **THEN** adapter returns title, description, acceptance-criteria text, and item identity +- **AND** extraction proceeds without provider-specific parsing in command handlers. + +#### Scenario: Missing acceptance criteria is surfaced explicitly +- **GIVEN** a backlog item with no acceptance criteria +- **WHEN** extraction runs +- **THEN** item is reported as incomplete input +- **AND** command output includes the backlog item identifier. diff --git a/openspec/changes/requirements-02-module-commands/specs/module-io-contract/spec.md b/openspec/changes/requirements-02-module-commands/specs/module-io-contract/spec.md new file mode 100644 index 0000000..3a4e15e --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/specs/module-io-contract/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Module Io Contract +The requirements module SHALL implement all `ModuleIOContract` operations. + +#### Scenario: Import operation maps backlog items to requirements +- **GIVEN** backlog input for import +- **WHEN** `import_to_bundle` runs +- **THEN** requirements are added to the bundle with stable IDs +- **AND** parse diagnostics are included for partial failures. + +#### Scenario: Validate operation enforces profile schema +- **GIVEN** requirements bundle and active profile schema +- **WHEN** `validate_bundle` runs +- **THEN** missing required fields are reported +- **AND** validation severity respects active policy mode. diff --git a/openspec/changes/requirements-02-module-commands/specs/requirements-module/spec.md b/openspec/changes/requirements-02-module-commands/specs/requirements-module/spec.md new file mode 100644 index 0000000..769f281 --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/specs/requirements-module/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Requirements Module +The system SHALL provide requirements CLI commands for extract, author, validate, and list. + +#### Scenario: Extract command creates requirement artifacts +- **GIVEN** `specfact requirements extract --from-backlog --output .specfact/requirements/` +- **WHEN** extraction succeeds +- **THEN** one or more `*.req.yaml` files are produced +- **AND** each file includes schema version and source backlog reference. + +#### Scenario: Author command applies profile-aware template fields +- **GIVEN** `specfact requirements author --template story` +- **WHEN** active profile is `solo` +- **THEN** authoring prompts require only solo-required fields +- **AND** optional advanced fields remain non-blocking. + +#### Scenario: Validate and list expose completeness and trace coverage +- **GIVEN** requirement artifacts with trace references +- **WHEN** `specfact requirements validate` and `specfact requirements list --show-coverage` run +- **THEN** completeness and coverage are reported per requirement +- **AND** output is machine-readable when requested. diff --git a/openspec/changes/requirements-02-module-commands/tasks.md b/openspec/changes/requirements-02-module-commands/tasks.md new file mode 100644 index 0000000..592c190 --- /dev/null +++ b/openspec/changes/requirements-02-module-commands/tasks.md @@ -0,0 +1,30 @@ +# Tasks: requirements-02-module-commands + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/requirements-02-module-commands` from `dev` before implementation work: `scripts/worktree.sh create feature/requirements-02-module-commands`. +- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. +- [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. +- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate requirements-02-module-commands --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/requirements-02-module-commands` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/requirements-03-backlog-sync/.openspec.yaml b/openspec/changes/requirements-03-backlog-sync/.openspec.yaml new file mode 100644 index 0000000..2a45c1f --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/requirements-03-backlog-sync/CHANGE_VALIDATION.md b/openspec/changes/requirements-03-backlog-sync/CHANGE_VALIDATION.md new file mode 100644 index 0000000..cedecec --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: requirements-03-backlog-sync + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate requirements-03-backlog-sync --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** requirements-backlog-sync +- **Modified capabilities:** backlog-adapter,requirements-module +- **Declared dependencies:** requirements-02 (requirements module), sync-01 (sync kernel) +- **Proposed affected code paths:** - `modules/requirements/src/requirements/commands/` (new sync, drift commands);- `modules/backlog/src/adapters/` (extend with requirements field methods) - Sync kernel integration hooks + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/requirements-03-backlog-sync/design.md b/openspec/changes/requirements-03-backlog-sync/design.md new file mode 100644 index 0000000..4409f9c --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `requirements-03-backlog-sync` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- Keep all public APIs contract-first with `@icontract` and `@beartype`. +- Make all behavior extensions opt-in or backward-compatible by default. +- Add/modify OpenSpec deltas first so tests can be derived before implementation. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-02-module-commands and sync-01-unified-kernel. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/requirements-03-backlog-sync/proposal.md b/openspec/changes/requirements-03-backlog-sync/proposal.md new file mode 100644 index 0000000..ccb4785 --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/proposal.md @@ -0,0 +1,54 @@ +# Change: Requirements ↔ Backlog Bidirectional Sync + +## Why + + + + +When backlog items change, requirements aren't updated. When requirements change, backlog items aren't updated. The two drift apart silently, creating a traceability gap that grows with every sprint. Teams discover the drift only during audits or after building the wrong thing. A bidirectional sync between backlog items and `.specfact/requirements/` using the sync kernel makes requirements and backlog items a single source of truth — with drift detection as the safety net. + +## Ownership Alignment (2026-04-08) + +- Repository assignment: `nold-ai/specfact-cli-modules` +- Modules-owned scope retained here: runtime synchronization orchestration, backlog/project command delivery, and bundle-side adapter behavior for requirements-backlog flows. +- Core counterpart retained in `nold-ai/specfact-cli` issue [#244](https://github.com/nold-ai/specfact-cli/issues/244) +- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) -> Story [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) +- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. +- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. + +## What Changes + + + + +- **NEW**: `specfact requirements sync --from-backlog --project --preview` — pull structured requirements from backlog AC text, update `.specfact/requirements/` +- **NEW**: `specfact requirements sync --to-backlog --project --preview` — push requirement-derived fields back to backlog items (missing AC, business value gaps, architectural constraints) +- **NEW**: `specfact requirements drift --from-backlog --project ` — detect divergence between local requirements and backlog items without making changes +- **NEW**: Sync operations use the sync kernel (sync-01) for session management, conflict detection, and patch preview +- **NEW**: Backlog adapter extension: adapters provide `extract_requirements_fields()` and `update_requirements_fields()` methods for bidirectional sync +- **EXTEND**: Requirements module (requirements-02) extended with sync commands +- **DESIGN DECISION**: v1 starts with pull-first (backlog → requirements) as primary direction; push (requirements → backlog) is preview-only and requires explicit `--write` confirmation via patch-mode +- **EXTEND**: Spec-Kit backlog extension awareness — before creating issues during push (requirements → backlog), the sync SHALL query `ToolCapabilities.extension_commands` (from speckit-02) to detect active spec-kit backlog extensions (Jira, ADO, Linear, GitHub Projects, Trello). When a spec-kit backlog extension is active, the sync SHALL scan spec-kit feature `tasks.md` files for existing issue references (e.g., `PROJ-123`, `AB#456`) and import them as pre-existing mappings. Issue creation is skipped for tasks that already have spec-kit extension mappings, preventing duplicate issues. This detection is implemented in `speckit-03-change-proposal-bridge` (specfact-cli-modules) and consumed here via the adapter interface. + +## Capabilities +### New Capabilities + +- `requirements-backlog-sync`: Bidirectional sync between `.specfact/requirements/` and backlog items (GitHub, ADO, Jira, Linear) via sync kernel. Includes pull (extract from backlog), push (update backlog), and drift detection. + +### Modified Capabilities + +- `backlog-adapter`: Extended with requirements field extraction and update methods for bidirectional sync; extended with spec-kit backlog extension issue mapping import +- `requirements-module`: Extended with sync and drift commands; extended with spec-kit duplicate issue prevention + + +--- + +## Source Tracking + + +- **Core Counterpart Issue**: nold-ai/specfact-cli#244 +- **GitHub Issue**: #166 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/requirements-03-backlog-sync/specs/backlog-adapter/spec.md b/openspec/changes/requirements-03-backlog-sync/specs/backlog-adapter/spec.md new file mode 100644 index 0000000..78c0ef0 --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/specs/backlog-adapter/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Backlog Adapter +The backlog adapter SHALL support requirement-aware pull and push sync operations. + +#### Scenario: Pull sync maps backlog changes to requirements updates +- **GIVEN** backlog item acceptance criteria changed since last sync +- **WHEN** requirements sync pull runs +- **THEN** corresponding requirement artifact is updated in preview patch +- **AND** changed fields are listed in sync output. + +#### Scenario: Push sync updates backlog fields from requirements +- **GIVEN** requirement has updated business value fields +- **WHEN** push sync apply runs +- **THEN** mapped backlog fields are updated through adapter write APIs +- **AND** optimistic concurrency checks prevent stale overwrites. diff --git a/openspec/changes/requirements-03-backlog-sync/specs/requirements-backlog-sync/spec.md b/openspec/changes/requirements-03-backlog-sync/specs/requirements-backlog-sync/spec.md new file mode 100644 index 0000000..f7d893d --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/specs/requirements-backlog-sync/spec.md @@ -0,0 +1,16 @@ +## ADDED Requirements + +### Requirement: Requirements Backlog Sync +The system SHALL support bidirectional backlog and requirements synchronization using sync-kernel session semantics. + +#### Scenario: Preview-first sync does not write upstream +- **GIVEN** `specfact requirements sync --from-backlog github --preview` +- **WHEN** sync executes +- **THEN** a patch preview is generated +- **AND** no upstream write is performed. + +#### Scenario: Drift is detected and reported +- **GIVEN** backlog and requirement artifacts diverged for the same story +- **WHEN** sync analysis runs +- **THEN** drift is flagged with field-level differences +- **AND** required conflict resolution path is provided. diff --git a/openspec/changes/requirements-03-backlog-sync/specs/requirements-module/spec.md b/openspec/changes/requirements-03-backlog-sync/specs/requirements-module/spec.md new file mode 100644 index 0000000..c6a0159 --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/specs/requirements-module/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Requirements Module +The requirements module SHALL include sync workflows backed by the sync kernel. + +#### Scenario: Sync command uses shared session model +- **GIVEN** requirements sync starts +- **WHEN** session is created +- **THEN** sync output includes session ID and status +- **AND** unresolved conflicts can be resumed later. + +#### Scenario: Sync command supports apply mode explicitly +- **GIVEN** preview output is accepted +- **WHEN** apply mode is requested +- **THEN** patch operations are executed with write guards +- **AND** resulting state is persisted for traceability. diff --git a/openspec/changes/requirements-03-backlog-sync/tasks.md b/openspec/changes/requirements-03-backlog-sync/tasks.md new file mode 100644 index 0000000..456b9a7 --- /dev/null +++ b/openspec/changes/requirements-03-backlog-sync/tasks.md @@ -0,0 +1,30 @@ +# Tasks: requirements-03-backlog-sync + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/requirements-03-backlog-sync` from `dev` before implementation work: `scripts/worktree.sh create feature/requirements-03-backlog-sync`. +- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. +- [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. +- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate requirements-03-backlog-sync --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/requirements-03-backlog-sync` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/sync-01-unified-kernel/.openspec.yaml b/openspec/changes/sync-01-unified-kernel/.openspec.yaml new file mode 100644 index 0000000..2a45c1f --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/sync-01-unified-kernel/CHANGE_VALIDATION.md b/openspec/changes/sync-01-unified-kernel/CHANGE_VALIDATION.md new file mode 100644 index 0000000..d4c2c4c --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: sync-01-unified-kernel + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate sync-01-unified-kernel --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** sync-kernel +- **Modified capabilities:** devops-sync +- **Declared dependencies:** patch-mode-01 (#177, preview/apply gating pattern) +- **Proposed affected code paths:** - `modules/sync-kernel/` (new module);- `modules/sync/src/` (integrate with kernel session management) - `.specfact/sync/journal/` (new offline journal directory) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/sync-01-unified-kernel/design.md b/openspec/changes/sync-01-unified-kernel/design.md new file mode 100644 index 0000000..7008d18 --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `sync-01-unified-kernel` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- Keep all public APIs contract-first with `@icontract` and `@beartype`. +- Make all behavior extensions opt-in or backward-compatible by default. +- Add/modify OpenSpec deltas first so tests can be derived before implementation. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on patch-mode-01-preview-apply. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/sync-01-unified-kernel/proposal.md b/openspec/changes/sync-01-unified-kernel/proposal.md new file mode 100644 index 0000000..4142323 --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/proposal.md @@ -0,0 +1,127 @@ +# Change: Sync Kernel — Unified Session-Based Sync Engine + +## Why + + + + +Sync between backlog, requirements, specs, and code is currently adapter-specific with no unified session management, conflict resolution, or offline support. Each adapter implements its own sync logic, leading to inconsistent behavior: some silently overwrite, some fail on conflict, none provides session resumability. A central, deterministic sync kernel that orchestrates sessions, computes patches, handles conflicts, and queues offline writes gives every sync operation the same safety guarantees — never silent overwrites, always preview first, always resumable. + +## Ownership Alignment (2026-04-08) + +- Authoritative implementation owner: `nold-ai/specfact-cli-modules`, project bundle story [#157](https://github.com/nold-ai/specfact-cli-modules/issues/157) +- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#147](https://github.com/nold-ai/specfact-cli-modules/issues/147) -> Story `#157` +- This modules-repo proposal is the authoritative implementation change for the transferred issue. +- Implementation MUST NOT proceed in `specfact-cli` core from the legacy `modules/sync-kernel/...` paths or old flat `specfact sync ...` command model. + +## Module Package Structure + +``` +modules/sync-kernel/ + module-package.yaml # name: sync-kernel; commands: sync, sync resolve, sync status + src/sync_kernel/ + __init__.py + main.py # typer.Typer app — sync command group + engine/ + session.py # Session management (session_id, cursor, resume) + patch_computer.py # 3-way merge, JSON Patch (RFC 6902) generation + conflict_detector.py # Field-level conflict detection + conflict_resolver.py # Interactive + auto resolution strategies + offline_queue.py # Offline journal: .specfact/sync/journal/ + models/ + sync_session.py # SyncSession, SyncPatch, ConflictRecord models + sync_event.py # CloudEvents-compatible envelope for interop + providers/ + provider_protocol.py # SyncProviderProtocol — adapters implement this + concurrency/ + etag_manager.py # Optimistic concurrency via ETags / If-Match + commands/ + preview.py # specfact sync --preview + apply.py # specfact sync --apply + resolve.py # specfact sync resolve --session + status.py # specfact sync status (show active sessions) +``` + +**`module-package.yaml` declares:** +- `name: sync-kernel` +- `version: 0.1.0` +- `commands: [sync, sync resolve, sync status]` (`--preview` and `--apply` are flags on `sync`) +- `dependencies: [patch-mode-01-preview-apply]` (uses preview/apply write-safety semantics) +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +## Module Package Structure + +``` +modules/sync-kernel/ + module-package.yaml # name: sync-kernel; commands: sync, sync resolve, sync status + src/sync_kernel/ + __init__.py + main.py # typer.Typer app — sync command group + engine/ + session.py # Session management (session_id, cursor, resume) + patch_computer.py # 3-way merge, JSON Patch (RFC 6902) generation + conflict_detector.py # Field-level conflict detection + conflict_resolver.py # Interactive + auto resolution strategies + offline_queue.py # Offline journal: .specfact/sync/journal/ + models/ + sync_session.py # SyncSession, SyncPatch, ConflictRecord models + sync_event.py # CloudEvents-compatible envelope for interop + providers/ + provider_protocol.py # SyncProviderProtocol — adapters implement this + concurrency/ + etag_manager.py # Optimistic concurrency via ETags / If-Match + commands/ + preview.py # specfact sync --preview + apply.py # specfact sync --apply + resolve.py # specfact sync resolve --session + status.py # specfact sync status (show active sessions) +``` + +**`module-package.yaml` declares:** +- `name: sync-kernel` +- `version: 0.1.0` +- `commands: [sync, sync resolve, sync status]` (`--preview` and `--apply` are flags on `sync`) +- `dependencies: [patch-mode-01-preview-apply]` (uses preview/apply write-safety semantics) +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +## What Changes + + + + +- **NEW**: Sync kernel in `modules/sync-kernel/` — central orchestrator for all sync operations +- **NEW**: Session management — each sync has `session_id`, cursor, and can be resumed after interruption or conflict +- **NEW**: 3-way merge with JSON Patch (RFC 6902) computation for structured data +- **NEW**: Field-level conflict detection: when both local and remote changed the same field, flag as conflict (never silent overwrite) +- **NEW**: Conflict resolution strategies: auto-resolve for non-overlapping fields, interactive for text conflicts, explicit resolve command for deferred conflicts +- **NEW**: Optimistic concurrency via ETags / If-Match for all upstream writes — fail-fast on stale data +- **NEW**: Offline journal at `.specfact/sync/journal/` — queue writes when upstream is unavailable, apply on next `sync --apply` +- **NEW**: CloudEvents-compatible event envelope for interoperability with external systems +- **NEW**: `SyncProviderProtocol` — adapters (backlog, requirements, architecture) implement this protocol to participate in sync sessions +- **NEW**: CLI commands: `specfact sync --preview` (dry-run patch), `specfact sync --apply` (execute patches), `specfact sync resolve --session ` (resolve pending conflicts), `specfact sync status` (show active sessions) +- **EXTEND**: Existing sync module behavior preserved — the kernel wraps existing adapter-specific sync calls with session management and conflict detection +- **EXTEND**: Spec-Kit extension interop — the sync kernel SHALL detect when spec-kit's own sync/reconcile/iterate extensions have modified artifacts (via `ToolCapabilities.extension_commands` from speckit-02), and coordinate to avoid conflicting writes. When a spec-kit extension has performed a reconcile, the kernel SHALL treat the reconciled artifact as the authoritative remote state rather than computing its own diff against a stale base. The `SyncProviderProtocol` SHALL include an optional `detect_external_sync_actors()` method that adapters can implement to report which external tools are performing their own sync operations on the same artifacts. + +## Capabilities +### New Capabilities + +- `sync-kernel`: Unified session-based sync engine with 3-way merge, JSON Patch (RFC 6902), optimistic concurrency (ETags), field-level conflict detection, offline journal, and CloudEvents-compatible event model. Provides SyncProviderProtocol for adapter integration. + +### Modified Capabilities + +- `devops-sync`: Existing sync behavior wrapped with kernel session management; no breaking changes to current sync commands +- `bridge-adapter`: SyncProviderProtocol integration — SpecKitAdapter implements `detect_external_sync_actors()` to report spec-kit reconcile/sync/iterate extensions as external sync actors + + +--- + +## Source Tracking + + +- **Original GitHub Issue**: nold-ai/specfact-cli#243 (transferred 2026-04-08) +- **GitHub Issue**: #157 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false + diff --git a/openspec/changes/sync-01-unified-kernel/specs/devops-sync/spec.md b/openspec/changes/sync-01-unified-kernel/specs/devops-sync/spec.md new file mode 100644 index 0000000..cb9730e --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/specs/devops-sync/spec.md @@ -0,0 +1,16 @@ +## MODIFIED Requirements + +### Requirement: Devops Sync +The existing sync behavior SHALL be mediated by unified sync-kernel sessions. + +#### Scenario: Existing sync entry uses session orchestration +- **GIVEN** sync operation starts from supported sync command path +- **WHEN** operation executes +- **THEN** a sync session is created with session ID +- **AND** status can be queried until completion. + +#### Scenario: Sync writes require explicit apply mode +- **GIVEN** sync preview is generated +- **WHEN** apply mode is not requested +- **THEN** no upstream writes are performed +- **AND** output clearly indicates preview-only execution. diff --git a/openspec/changes/sync-01-unified-kernel/specs/sync-kernel/spec.md b/openspec/changes/sync-01-unified-kernel/specs/sync-kernel/spec.md new file mode 100644 index 0000000..d8a3025 --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/specs/sync-kernel/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Sync Kernel +The system SHALL provide a session-based sync kernel with preview/apply safety gates, conflict handling, and offline journaling. + +#### Scenario: Preview mode computes patch set without writing +- **GIVEN** `specfact sync --preview` +- **WHEN** sync analysis runs +- **THEN** JSON patch operations are produced for candidate writes +- **AND** no provider write call is executed. + +#### Scenario: Apply mode enforces optimistic concurrency +- **GIVEN** `specfact sync --apply` and remote data changed after preview +- **WHEN** kernel attempts write +- **THEN** stale writes are rejected using ETag or equivalent concurrency checks +- **AND** conflict records are created for manual resolution. + +#### Scenario: Offline write requests are journaled +- **GIVEN** apply mode is requested while provider is unavailable +- **WHEN** kernel cannot reach upstream +- **THEN** pending writes are stored under `.specfact/sync/journal/` +- **AND** queued writes are eligible for retry in a later session. diff --git a/openspec/changes/sync-01-unified-kernel/tasks.md b/openspec/changes/sync-01-unified-kernel/tasks.md new file mode 100644 index 0000000..3ce6e9c --- /dev/null +++ b/openspec/changes/sync-01-unified-kernel/tasks.md @@ -0,0 +1,30 @@ +# Tasks: sync-01-unified-kernel + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/sync-01-unified-kernel` from `dev` before implementation work: `scripts/worktree.sh create feature/sync-01-unified-kernel`. +- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. +- [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. +- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate sync-01-unified-kernel --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/sync-01-unified-kernel` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/traceability-01-index-and-orphans/.openspec.yaml b/openspec/changes/traceability-01-index-and-orphans/.openspec.yaml new file mode 100644 index 0000000..2a45c1f --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/traceability-01-index-and-orphans/CHANGE_VALIDATION.md b/openspec/changes/traceability-01-index-and-orphans/CHANGE_VALIDATION.md new file mode 100644 index 0000000..578bb2f --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/CHANGE_VALIDATION.md @@ -0,0 +1,31 @@ +# Change Validation: traceability-01-index-and-orphans + +- **Validated on (UTC):** 2026-02-15T21:54:26Z +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate traceability-01-index-and-orphans --strict` +- **Result:** PASS + +## Scope Summary + +- **New capabilities:** traceability-index +- **Modified capabilities:** (none) +- **Declared dependencies:** requirements-02 (requirements module), architecture-01 (architecture module) +- **Proposed affected code paths:** - `modules/trace/` (new module);- `.specfact/trace/index.json` (new generated artifact) + +## Breaking-Change Analysis (Dry-Run) + +- Interface changes are proposal-level only; no production code modifications were performed in this workflow stage. +- Proposed modified capabilities are additive/extension-oriented in the current spec deltas and do not require immediate breaking migrations at proposal time. +- Backward-compatibility risk is primarily sequencing-related (dependency ordering), not signature-level breakage at this stage. + +## Dependency and Integration Review + +- Dependency declarations align with the 2026-02-15 architecture layer integration plan sequencing. +- Cross-change integration points are explicitly represented in proposal/spec/task artifacts. +- No additional mandatory scope expansion was required to pass strict OpenSpec validation. + +## Validation Outcome + +- Required artifacts are present: `proposal.md`, `design.md`, `specs/**/*.md`, `tasks.md`. +- Strict OpenSpec validation passed. +- Change is ready for implementation-phase intake once prerequisites are satisfied. diff --git a/openspec/changes/traceability-01-index-and-orphans/design.md b/openspec/changes/traceability-01-index-and-orphans/design.md new file mode 100644 index 0000000..5d5d144 --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `traceability-01-index-and-orphans` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- Keep all public APIs contract-first with `@icontract` and `@beartype`. +- Make all behavior extensions opt-in or backward-compatible by default. +- Add/modify OpenSpec deltas first so tests can be derived before implementation. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-02-module-commands and architecture-01-solution-layer. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/traceability-01-index-and-orphans/proposal.md b/openspec/changes/traceability-01-index-and-orphans/proposal.md new file mode 100644 index 0000000..bab7939 --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/proposal.md @@ -0,0 +1,114 @@ +# Change: Traceability Index & Orphan Detection + +## Why + + + + +As the number of requirements, specs, and code modules grows, manually tracking traceability becomes impossible. Teams need a fast, queryable index that maps every artifact to its upstream/downstream counterparts — and actively detects orphans (artifacts with broken or missing links). This index is the backbone for the full-chain validation, coverage dashboards, and ceremony enrichment. Without it, traceability is a write-once artifact that decays the moment someone adds a new endpoint without linking it. + +## Ownership Alignment (2026-04-08) + +- Repository assignment: `nold-ai/specfact-cli-modules` +- Modules-owned scope retained here: bundle-side query/report delivery and runtime trace indexing behavior for traceability workflows. +- Core counterpart retained in `nold-ai/specfact-cli` issue [#242](https://github.com/nold-ai/specfact-cli/issues/242) +- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) -> Story [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) +- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. +- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. + +## Module Package Structure + +``` +modules/trace/ + module-package.yaml # name: trace; commands: trace index, trace show, trace orphans, trace matrix + src/trace/ + __init__.py + main.py # typer.Typer app — trace command group + engine/ + indexer.py # Build/rebuild traceability index from all layers + query.py # Query index by requirement, spec, code, or test ID + orphan_detector.py # Find artifacts with broken or missing upstream/downstream links + matrix_generator.py # Generate traceability matrix (markdown, CSV, JSON) + models/ + trace_index.py # TraceIndex, TraceEntry, OrphanReport models + storage/ + index_store.py # Read/write .specfact/trace/index.json (generated, not authored) + commands/ + index.py # specfact trace index --rebuild + show.py # specfact trace show + orphans.py # specfact trace orphans + matrix.py # specfact trace matrix --format markdown|csv|json +``` + +**`module-package.yaml` declares:** +- `name: trace` +- `version: 0.1.0` +- `commands: [trace index, trace show, trace orphans, trace matrix]` +- `dependencies: [requirements-02-module-commands, architecture-01-solution-layer]` +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +## Module Package Structure + +``` +modules/trace/ + module-package.yaml # name: trace; commands: trace index, trace show, trace orphans, trace matrix + src/trace/ + __init__.py + main.py # typer.Typer app — trace command group + engine/ + indexer.py # Build/rebuild traceability index from all layers + query.py # Query index by requirement, spec, code, or test ID + orphan_detector.py # Find artifacts with broken or missing upstream/downstream links + matrix_generator.py # Generate traceability matrix (markdown, CSV, JSON) + models/ + trace_index.py # TraceIndex, TraceEntry, OrphanReport models + storage/ + index_store.py # Read/write .specfact/trace/index.json (generated, not authored) + commands/ + index.py # specfact trace index --rebuild + show.py # specfact trace show + orphans.py # specfact trace orphans + matrix.py # specfact trace matrix --format markdown|csv|json +``` + +**`module-package.yaml` declares:** +- `name: trace` +- `version: 0.1.0` +- `commands: [trace index, trace show, trace orphans, trace matrix]` +- `dependencies: [requirements-02-module-commands, architecture-01-solution-layer]` +- `publisher:` + `integrity:` — arch-06 marketplace readiness + +## What Changes + + + + +- **NEW**: Trace module in `modules/trace/` with auto-maintained traceability index +- **NEW**: `specfact trace index --rebuild` — scan all requirements, architecture, specs, code, and test artifacts to build a comprehensive traceability index stored at `.specfact/trace/index.json` +- **NEW**: `specfact trace show REQ-123` — query upstream/downstream links for any artifact (requirement, component, spec operation, code module, test) +- **NEW**: `specfact trace orphans` — detect orphaned artifacts: specs with no requirement, code with no spec, requirements with no architecture coverage, tests with no code reference +- **NEW**: `specfact trace matrix --format markdown|csv|json` — export traceability matrix showing the full chain for each requirement +- **NEW**: Incremental index updates — when a single file changes, update only affected trace entries (not full rebuild) +- **NEW**: TraceIndex model with bidirectional links: each entry stores both `upstream_refs` and `downstream_refs` + +## Capabilities +### New Capabilities + +- `traceability-index`: Auto-maintained bidirectional traceability index mapping requirements → architecture → specs → code → tests, with orphan detection, incremental updates, and matrix export in markdown/CSV/JSON. + +### Modified Capabilities + +(none) + + +--- + +## Source Tracking + + +- **Core Counterpart Issue**: nold-ai/specfact-cli#242 +- **GitHub Issue**: #170 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/traceability-01-index-and-orphans/specs/traceability-index/spec.md b/openspec/changes/traceability-01-index-and-orphans/specs/traceability-index/spec.md new file mode 100644 index 0000000..82c27e5 --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/specs/traceability-index/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Traceability Index +The system SHALL maintain a queryable index of upstream and downstream links across requirements, architecture, specs, code, and tests. + +#### Scenario: Rebuild index captures all artifact layers +- **GIVEN** `specfact trace index --rebuild` +- **WHEN** index generation completes +- **THEN** `.specfact/trace/index.json` contains entries for requirement, architecture, spec, code, and test artifacts +- **AND** each entry contains both upstream and downstream references. + +#### Scenario: Orphan command reports missing linkage by type +- **GIVEN** at least one artifact has missing required references +- **WHEN** `specfact trace orphans` runs +- **THEN** output groups orphan findings by artifact type +- **AND** each finding includes artifact identifier and missing link category. + +#### Scenario: Matrix export supports machine and human formats +- **GIVEN** a built index +- **WHEN** `specfact trace matrix --format markdown|csv|json` runs +- **THEN** matrix output includes requirement-centered chain rows +- **AND** exported content is deterministic for CI diffs. diff --git a/openspec/changes/traceability-01-index-and-orphans/tasks.md b/openspec/changes/traceability-01-index-and-orphans/tasks.md new file mode 100644 index 0000000..44add5f --- /dev/null +++ b/openspec/changes/traceability-01-index-and-orphans/tasks.md @@ -0,0 +1,30 @@ +# Tasks: traceability-01-index-and-orphans + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/traceability-01-index-and-orphans` from `dev` before implementation work: `scripts/worktree.sh create feature/traceability-01-index-and-orphans`. +- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. +- [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. +- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate traceability-01-index-and-orphans --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/traceability-01-index-and-orphans` to `dev` with spec/test/code/docs evidence. diff --git a/openspec/changes/validation-02-full-chain-engine/.openspec.yaml b/openspec/changes/validation-02-full-chain-engine/.openspec.yaml new file mode 100644 index 0000000..2a45c1f --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-15 diff --git a/openspec/changes/validation-02-full-chain-engine/CHANGE_VALIDATION.md b/openspec/changes/validation-02-full-chain-engine/CHANGE_VALIDATION.md new file mode 100644 index 0000000..6624c20 --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/CHANGE_VALIDATION.md @@ -0,0 +1,28 @@ +# Change Validation: validation-02-full-chain-engine + +- **Validated on (UTC):** 2026-03-22T22:28:26+00:00 +- **Workflow:** /wf-validate-change (proposal-stage dry-run validation) +- **Strict command:** `openspec validate validation-02-full-chain-engine --strict` +- **Result:** PASS + +## Scope Summary + +- **Primary capability:** `full-chain-validation` +- **Clean-code delta:** add optional `--with-code-quality` side-channel reporting without turning clean-code into a traceability layer +- **Declared dependencies:** governance evidence envelope; policy/profile severity consumers + +## Breaking-Change Analysis (Dry-Run) + +- The delta preserves the existing Req → Arch → Spec → Code → Tests layer model. +- The optional side-channel adds evidence only and does not change baseline full-chain behavior. + +## Dependency and Integration Review + +- Validation ownership remains separate from governance envelope ownership. +- No scope expansion was needed beyond the optional review side-channel. + +## Validation Outcome + +- Required artifacts are present and parseable. +- Strict OpenSpec validation passed. +- Change is ready to consume clean-code review output as a parallel quality dimension. diff --git a/openspec/changes/validation-02-full-chain-engine/design.md b/openspec/changes/validation-02-full-chain-engine/design.md new file mode 100644 index 0000000..7cf04d2 --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/design.md @@ -0,0 +1,40 @@ +## Context + +This change implements proposal scope for `validation-02-full-chain-engine` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. + +## Goals / Non-Goals + +**Goals:** +- Define an implementation approach that stays within the proposal scope. +- Keep compatibility with existing module registry, adapter bridge, and contract-first patterns. +- Preserve offline-first behavior and deterministic CLI execution. + +**Non-Goals:** +- No production code implementation in this stage. +- No schema-breaking changes outside declared capabilities. +- No dependency expansion beyond the proposal and plan. + +## Decisions + +- Use module-oriented integration and registry lazy-loading patterns already used in SpecFact CLI. +- Keep all public APIs contract-first with `@icontract` and `@beartype`. +- Make all behavior extensions opt-in or backward-compatible by default. +- Add/modify OpenSpec deltas first so tests can be derived before implementation. + +## Risks / Trade-offs + +- [Dependency ordering drift] -> Mitigation: gate implementation tasks on declared prerequisites. +- [Capability overlap with adjacent changes] -> Mitigation: keep this change scoped to listed capabilities only. +- [Documentation drift] -> Mitigation: include explicit docs update tasks in apply phase. + +## Migration Plan + +1. Implement this change only after listed dependencies are implemented. +2. Add tests from spec scenarios and capture failing-first evidence. +3. Implement minimal production changes needed for passing scenarios. +4. Run quality gates and then open PR to `dev`. + +## Open Questions + +- Dependency summary: Depends on requirements-02-module-commands, architecture-01-solution-layer, and policy-engine-01-unified-framework. +- Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/validation-02-full-chain-engine/proposal.md b/openspec/changes/validation-02-full-chain-engine/proposal.md new file mode 100644 index 0000000..0e75194 --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/proposal.md @@ -0,0 +1,103 @@ +# Change: Full-Chain Validation Engine + +## Why + + + + +Validation today operates only at the spec-code level (`specfact validate` checks spec deltas and contract enforcement). There is no way to validate the entire chain from business requirements through architecture to code and tests. This means a project can pass all technical validations while building entirely the wrong thing. A `--full-chain` validation mode that checks every layer transition — Req → Arch → Spec → Code → Tests — and reports gaps, orphans, and coverage metrics, unlocks the core value proposition: end-to-end traceability with actionable evidence. + +## Ownership Alignment (2026-04-08) + +- Repository assignment: `nold-ai/specfact-cli-modules` +- Modules-owned scope retained here: bundle-side validation engine runtime, command wiring, and executable full-chain checks. +- Core counterpart retained in `nold-ai/specfact-cli` issue [#241](https://github.com/nold-ai/specfact-cli/issues/241) +- Target hierarchy: modules Epic [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162) -> Feature [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163) -> Story [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) +- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. +- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. + +## Module Package Structure + +``` +modules/validate/ + # Extends existing validate module — no new module directory + src/validate/ + engine/ + full_chain.py # Full-chain validation orchestrator + layer_transitions.py # Per-transition validation rules (req→arch, arch→spec, etc.) + coverage_calculator.py # Compute coverage percentages per layer + evidence_writer.py # Write machine-readable evidence JSON + models/ + chain_report.py # FullChainReport, LayerTransitionResult, CoverageMetrics +``` + +## Module Package Structure + +``` +modules/validate/ + # Extends existing validate module — no new module directory + src/validate/ + engine/ + full_chain.py # Full-chain validation orchestrator + layer_transitions.py # Per-transition validation rules (req→arch, arch→spec, etc.) + coverage_calculator.py # Compute coverage percentages per layer + evidence_writer.py # Write machine-readable evidence JSON + models/ + chain_report.py # FullChainReport, LayerTransitionResult, CoverageMetrics +``` + +## What Changes + + + + +- **EXTEND**: `specfact validate` extended with `--full-chain` flag that runs validation across all layer transitions: + - Req → Arch: Every business rule mapped to component; every architectural constraint has ADR + - Arch → Spec: Every component has OpenAPI/AsyncAPI spec + - Spec → Code: Existing spec-delta validation (unchanged) + - Code → Tests: Contract coverage, test existence checks + - Orphan detection: Specs with no requirement, code with no spec +- **EXTEND**: Optional `--with-code-quality` side-channel runs `specfact review` during full-chain validation and passes its clean-code summary into the governance evidence envelope without redefining the chain layers. +- **NEW**: Full-chain validation orchestrator in `modules/validate/src/validate/engine/full_chain.py` — runs all layer transition checks, aggregates results, computes coverage metrics +- **NEW**: Layer transition rules with profile-dependent severity: solo gets advisory-only, enterprise gets hard-fail with evidence +- **NEW**: Machine-readable evidence output (JSON) for CI gates: + ```json + { + "schema_version": "1.0", + "timestamp": "...", + "profile": "enterprise", + "layers": { + "req_to_arch": { "pass": 12, "fail": 2, "advisory": 1 }, + "arch_to_spec": { "pass": 8, "fail": 0, "advisory": 3 }, + "spec_to_code": { "pass": 47, "fail": 0 }, + "orphans": { "specs_without_req": ["GET /legacy/endpoint"] } + }, + "policy_mode": "hard", + "overall": "PASS_WITH_ADVISORY" + } + ``` +- **NEW**: `--evidence-dir .specfact/evidence/` flag for persisting validation evidence artifacts +- **EXTEND**: Policy engine integration — layer transition severities configurable via policy-engine-01 policy rules + +## Capabilities +### New Capabilities + +- `full-chain-validation`: End-to-end validation across all traceability layers (Req → Arch → Spec → Code → Tests) with profile-dependent severity, orphan detection, coverage metrics, and machine-readable evidence output for CI gates. + +### Modified Capabilities + +- `sidecar-validation`: Extended with `--full-chain` flag; existing spec-delta validation preserved as-is when flag is omitted +- `full-chain-validation`: Extended with optional code-quality side-channel reporting that remains parallel to the Req → Arch → Spec → Code → Tests transitions + + +--- + +## Source Tracking + + +- **Core Counterpart Issue**: nold-ai/specfact-cli#241 +- **GitHub Issue**: #171 +- **Issue URL**: +- **Repository**: nold-ai/specfact-cli-modules +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/validation-02-full-chain-engine/specs/full-chain-validation/spec.md b/openspec/changes/validation-02-full-chain-engine/specs/full-chain-validation/spec.md new file mode 100644 index 0000000..7522304 --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/specs/full-chain-validation/spec.md @@ -0,0 +1,28 @@ +## ADDED Requirements + +### Requirement: Full Chain Validation +The system SHALL validate Requirement -> Architecture -> Spec -> Code -> Test transitions and emit layered evidence. + +#### Scenario: Full-chain command emits transition-level results +- **GIVEN** `specfact validate --full-chain --output json --evidence-dir .specfact/evidence/` +- **WHEN** validation runs +- **THEN** report includes transition groups `req_to_arch`, `arch_to_spec`, `spec_to_code`, and `code_to_tests` +- **AND** each group reports pass/fail/advisory counts. + +#### Scenario: Severity respects policy mode and profile +- **GIVEN** enterprise profile with hard mode +- **WHEN** a required Req -> Arch mapping is missing +- **THEN** overall validation exits non-zero +- **AND** evidence marks the violation as blocking. + +#### Scenario: Orphan detection is included in evidence +- **GIVEN** specs without requirement links exist +- **WHEN** full-chain validation runs +- **THEN** orphan entries are listed in evidence +- **AND** orphan summary is included in overall status computation. + +#### Scenario: Code quality can be included without becoming a chain layer +- **GIVEN** `specfact validate --full-chain --with-code-quality` is executed +- **WHEN** the validation run completes +- **THEN** the evidence output includes a `code_quality` summary sourced from `specfact review` +- **AND** the traceability layers remain limited to `req_to_arch`, `arch_to_spec`, `spec_to_code`, and `code_to_tests` diff --git a/openspec/changes/validation-02-full-chain-engine/specs/sidecar-validation/spec.md b/openspec/changes/validation-02-full-chain-engine/specs/sidecar-validation/spec.md new file mode 100644 index 0000000..2d10b97 --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/specs/sidecar-validation/spec.md @@ -0,0 +1,15 @@ +## MODIFIED Requirements + +### Requirement: Sidecar Validation +The sidecar validation capability SHALL support full-chain payload checks in addition to spec-code checks. + +#### Scenario: Sidecar consumes full-chain input set +- **GIVEN** requirement and architecture artifact paths are provided +- **WHEN** sidecar validation runs +- **THEN** sidecar validates layered chain references +- **AND** results are merged into full-chain evidence output. + +#### Scenario: Existing spec-code validation remains supported +- **GIVEN** sidecar is invoked without requirements/architecture inputs +- **WHEN** validation executes +- **THEN** existing spec-code validation behavior continues unchanged. diff --git a/openspec/changes/validation-02-full-chain-engine/tasks.md b/openspec/changes/validation-02-full-chain-engine/tasks.md new file mode 100644 index 0000000..3d6549b --- /dev/null +++ b/openspec/changes/validation-02-full-chain-engine/tasks.md @@ -0,0 +1,31 @@ +# Tasks: validation-02-full-chain-engine + +## 1. Branch and dependency guardrails + +- [ ] 1.1 Create dedicated worktree branch `feature/validation-02-full-chain-engine` from `dev` before implementation work: `scripts/worktree.sh create feature/validation-02-full-chain-engine`. +- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. + +## 2. Spec-first and test-first preparation + +- [ ] 2.1 Finalize `specs/` deltas for all listed capabilities and cross-check scenario completeness. +- [ ] 2.2 Add/update tests mapped to new and modified scenarios. +- [ ] 2.3 Run targeted tests to capture failing-first behavior and record results in `TDD_EVIDENCE.md`. + +## 3. Implementation + +- [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. +- [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. +- [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. +- [ ] 3.4 Add `--with-code-quality` as an optional side-channel and keep clean-code reporting out of the core chain-layer state machine. + +## 4. Validation and documentation + +- [ ] 4.1 Re-run tests and quality gates until all changed scenarios pass. +- [ ] 4.2 Update user-facing docs and navigation for changed/added commands and workflows. +- [ ] 4.3 Run `openspec validate validation-02-full-chain-engine --strict` and resolve all issues. + +## 5. Delivery + +- [ ] 5.1 Update `openspec/CHANGE_ORDER.md` status/dependency notes if implementation sequencing changed. +- [ ] 5.2 Open a PR from `feature/validation-02-full-chain-engine` to `dev` with spec/test/code/docs evidence.