diff --git a/docs/architecture/discrepancies-report.md b/docs/architecture/discrepancies-report.md index 8b9dc1e3..b34b4cc3 100644 --- a/docs/architecture/discrepancies-report.md +++ b/docs/architecture/discrepancies-report.md @@ -39,13 +39,13 @@ Legend: 5. Command registry implementation detail gap: `Resolved` 6. Module package structure missing in docs: `Resolved` 7. Adapter capabilities docs gap: `Resolved` -8. Architecture derive command missing in implementation: `Open` (documented as planned) +8. Architecture derive command missing in implementation: `Open` (proposal now split/rescoped; no flat core command is authorized) 9. Change tracking implementation partial vs spec breadth: `Partial` 10. Protocol FSM implementation minimal vs detailed spec: `Partial` 11. Diagram references to non-existent components: `Resolved` 12. Outdated performance metrics: `Resolved` (outdated hard claims removed/tempered) 13. Missing error handling documentation: `Resolved` -14. Missing architecture module vs architecture specs: `Open` +14. Missing architecture module vs architecture specs: `Open` (runtime delivery must be reassigned into canonical grouped bundle ownership) 15. Incomplete bridge adapter implementations vs references: `Partial` 16. Protocol validation gaps: `Partial` 17. Terminology inconsistencies: `Resolved` @@ -54,7 +54,7 @@ Legend: 20. No ADR records: `Resolved` 21. Missing module development guide: `Resolved` 22. Missing adapter development guide: `Resolved` -23. Missing architecture commands: `Open` +23. Missing architecture commands: `Open` (the old flat command family is no longer the target shape) 24. Partial change tracking coverage: `Partial` 25. Incomplete protocol support: `Partial` @@ -81,6 +81,8 @@ The following remediation outputs are now present: These items are not documentation mismatches anymore; they are implementation/spec-delivery work: 1. `specfact architecture derive|validate|trace` command family is still planned. + - That original flat command shape is now stale relative to the lean-core plus bundles architecture. + - Any future delivery must be split into core-owned contracts and grouped bundle-owned runtime commands in `specfact-cli-modules`. 2. Protocol FSM execution/validation engine is still partial. 3. Change tracking depth is not yet uniform across all adapters/providers. 4. Some architecture-level capabilities remain defined in OpenSpec before runtime delivery. @@ -89,8 +91,9 @@ These items are not documentation mismatches anymore; they are implementation/sp ### Phase A: Architecture command delivery -- Implement `architecture` command group per `architecture-01-solution-layer`. -- Add contract/integration tests and usage docs once commands are live. +- Rescope `architecture-01-solution-layer` and related changes onto canonical grouped command owners before implementation work starts. +- Keep shared contracts and schema work in core; deliver any runtime command surface from the appropriate bundle in `specfact-cli-modules`. +- Add contract/integration tests and usage docs only after the post-split command home is approved. ### Phase B: Protocol runtime completion diff --git a/docs/architecture/implementation-status.md b/docs/architecture/implementation-status.md index b2f0e594..81ef170d 100644 --- a/docs/architecture/implementation-status.md +++ b/docs/architecture/implementation-status.md @@ -21,8 +21,10 @@ This page tracks implemented vs planned architecture capabilities. ## Planned or Partial -- `specfact architecture derive|validate|trace` command family is planned. - - Source: OpenSpec `architecture-01-solution-layer`. +- Shared architecture and traceability contracts remain planned in OpenSpec. + - Source: `architecture-01-solution-layer`, `traceability-01-index-and-orphans`, and related follow-up changes. +- Older flat command families such as `specfact architecture ...`, `specfact requirements ...`, and `specfact trace ...` are not canonical delivery targets. + - Any future runtime implementation must be rescoped into grouped bundle-owned surfaces in `specfact-cli-modules`; core retains only shared models, schemas, and integration contracts. - Protocol FSM runtime engine is partial (models/specs exist; full execution engine/guards are planned). - Source: OpenSpec `architecture-01-solution-layer` and dependent validation changes. - Change tracking is adapter-dependent and not uniformly complete across all backlog providers. diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 4802e89d..36bdaa26 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -16,7 +16,8 @@ SpecFact CLI is a contract-first Python CLI with a production-ready module regis ## Current Architecture Status - Module system is **production-ready** (introduced in `v0.27`) and is the default command-loading path. -- Architecture commands such as `specfact architecture derive|validate|trace` are **planned** and tracked in OpenSpec change `architecture-01-solution-layer`. +- Older flat command concepts such as `specfact architecture ...`, `specfact requirements ...`, and `specfact trace ...` are **not** part of the canonical current CLI surface. +- The related OpenSpec changes now follow a split/rescope model: core owns schemas, contracts, and integration boundaries, while any future user-facing runtime delivery must land under canonical grouped bundle commands in `specfact-cli-modules`. - Protocol FSM modeling exists in data models; a full runtime FSM engine is still planned. ## Layer Model @@ -131,6 +132,9 @@ See also: - Change tracking models exist and are used by adapter flows. - Support is adapter-dependent and not uniformly complete across all external systems. - Protocol specs exist as models/spec artifacts; full FSM execution and guard engine behavior is not yet fully implemented. +- Forward-looking architecture proposals must be read together with the current ownership boundary: + - core proposals may define shared contracts, schemas, or adapter hooks + - bundle/runtime command delivery belongs in `specfact-cli-modules` under canonical grouped categories such as `project`, `code`, `backlog`, and `govern` Status and roadmap references: diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index 2564bf55..c1ed8b7d 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -62,6 +62,12 @@ Only changes that are **archived**, shown as **✓ Complete** by `openspec list` | ✅ code-review-09-f4-automation-upgrade | archived 2026-03-17 | | ✅ doc-frontmatter-schema | archived 2026-03-29 | | ✅ ci-02-trustworthy-green-checks | implemented 2026-03-30; archive pending | +| ✅ module-migration-04-remove-flat-shims | archived 2026-04-05 | +| ✅ module-migration-10-bundle-command-surface-alignment | archived 2026-04-05 | +| ✅ ci-docs-sync-check | archived 2026-04-05 | +| ✅ docs-new-user-onboarding | archived 2026-04-05 | +| ✅ readme-star-conversion-01 | archived 2026-04-05 | +| ✅ agile-01-feature-hierarchy | archived 2026-04-08 | ### Pending @@ -120,14 +126,14 @@ The 2026-03-22 clean-code plan adds one new cross-repo change pair and re-sequen | docs | 02 | ✅ doc-frontmatter-schema (archived 2026-03-29) | [#461](https://github.com/nold-ai/specfact-cli/issues/461) | Parent Feature: [#356](https://github.com/nold-ai/specfact-cli/issues/356) | | docs | 03 | ✅ docs-03-command-syntax-parity (archived 2026-03-18) | pending | docs-01 ✅; docs-02 ✅ | | docs | 04 | docs-04-docs-review-gate-and-link-integrity | pending | docs-03 ✅ | -| docs | 05 | ci-docs-sync-check | pending | docs-02 (doc-frontmatter-schema) [#461](https://github.com/nold-ai/specfact-cli/issues/461) | +| docs | 05 | ✅ ci-docs-sync-check (archived 2026-04-05) | pending | docs-02 (doc-frontmatter-schema) [#461](https://github.com/nold-ai/specfact-cli/issues/461) | | docs | 06 | docs-05-core-site-ia-restructure | [#438](https://github.com/nold-ai/specfact-cli/issues/438) | docs-04; Parent Feature: [#356](https://github.com/nold-ai/specfact-cli/issues/356) | | docs | 07 | docs-07-core-handoff-conversion | [#439](https://github.com/nold-ai/specfact-cli/issues/439) | docs-05-core-site-ia-restructure; modules-repo/docs-06-modules-site-ia-restructure | | docs | 08 | docs-12-docs-validation-ci | [#440](https://github.com/nold-ai/specfact-cli/issues/440) | docs-05-core-site-ia-restructure; docs-07-core-handoff-conversion; modules-repo/docs-06 through docs-10 | | docs | 09 | docs-13-core-nav-search-theme-roles | [#458](https://github.com/nold-ai/specfact-cli/issues/458) | docs-05-core-site-ia-restructure; docs-07-core-handoff-conversion; docs-12-docs-validation-ci; modules-repo/docs-13-nav-search-theme-roles (design parity only, no content ownership coupling) | | docs | 10 | docs-14-first-contact-story-and-onboarding (in progress) | [#466](https://github.com/nold-ai/specfact-cli/issues/466) | docs-05-core-site-ia-restructure ✅; docs-07-core-handoff-conversion ✅; docs-12-docs-validation-ci ✅; docs-13-core-nav-search-theme-roles ✅; Parent Feature: [#356](https://github.com/nold-ai/specfact-cli/issues/356) | -| docs | 11 | docs-new-user-onboarding | [#476](https://github.com/nold-ai/specfact-cli/issues/476) | Parent Feature: [#356](https://github.com/nold-ai/specfact-cli/issues/356); related [#466](https://github.com/nold-ai/specfact-cli/issues/466); vibe-coder uvx hero + CLI wow-path fixes | -| docs | 12 | readme-star-conversion-01 | pending | blocked by `docs-new-user-onboarding` [#476](https://github.com/nold-ai/specfact-cli/issues/476); README-first proof and adoption restructuring | +| docs | 11 | ✅ docs-new-user-onboarding (archived 2026-04-05) | [#476](https://github.com/nold-ai/specfact-cli/issues/476) | Parent Feature: [#356](https://github.com/nold-ai/specfact-cli/issues/356); related [#466](https://github.com/nold-ai/specfact-cli/issues/466); vibe-coder uvx hero + CLI wow-path fixes | +| docs | 12 | ✅ readme-star-conversion-01 (archived 2026-04-05) | pending | blocked by `docs-new-user-onboarding` [#476](https://github.com/nold-ai/specfact-cli/issues/476); README-first proof and adoption restructuring | ### Docs refactoring plan addendum (2026-03-23) @@ -154,15 +160,27 @@ Cross-repo dependency: `docs-07-core-handoff-conversion` depends on `specfact-cl | module-migration | 01 | module-migration-01-categorize-and-group | [#315](https://github.com/nold-ai/specfact-cli/issues/315) | #215 ✅ (marketplace-02) | | module-migration | 02 | module-migration-02-bundle-extraction | [#316](https://github.com/nold-ai/specfact-cli/issues/316) | module-migration-01 ✅ | | module-migration | 03 | module-migration-03-core-slimming | [#317](https://github.com/nold-ai/specfact-cli/issues/317) | module-migration-02; migration-05 sections 18-22 (tests, decoupling, docs, pipeline/config) must precede deletion | -| module-migration | 04 | module-migration-04-remove-flat-shims | [#330](https://github.com/nold-ai/specfact-cli/issues/330) | module-migration-01; shim-removal scope only (no broad legacy test migration) | +| module-migration | 04 | ✅ module-migration-04-remove-flat-shims | [#330](https://github.com/nold-ai/specfact-cli/issues/330) | archived 2026-04-05 | | module-migration | 06 | module-migration-06-core-decoupling-cleanup (in progress) | [#338](https://github.com/nold-ai/specfact-cli/issues/338) | module-migration-03 ✅; migration-05 ✅ bundle-parity baseline | | module-migration | 07 | module-migration-07-test-migration-cleanup | [#339](https://github.com/nold-ai/specfact-cli/issues/339) | migration-03 phase 20 handoff; migration-04 and migration-05 residual specfact-cli test debt | | module-migration | 08 | module-migration-08-release-suite-stabilization | TBD | module-migration-03/04/06/07 merged; residual release-suite regressions after migration merge | | module-migration | 09 | backlog-module-ownership-cleanup | TBD | module-migration-06; backlog-core-07; cli-val-07 findings | -| module-migration | 10 | module-migration-10-bundle-command-surface-alignment | [#385](https://github.com/nold-ai/specfact-cli/issues/385) | module-migration-02 ✅; module-migration-06/07 baseline; cli-val-07 findings | +| module-migration | 10 | ✅ module-migration-10-bundle-command-surface-alignment | [#385](https://github.com/nold-ai/specfact-cli/issues/385) | archived 2026-04-05 | | module-migration | 11 | module-migration-11-project-codebase-ownership-realignment | [#408](https://github.com/nold-ai/specfact-cli/issues/408) | module-migration-06 baseline; backlog-module-ownership-cleanup precedent; blocks final canonical import-path decisions in module-migration-10 | | init-ide | 01 | init-ide-prompt-source-selection | [#382](https://github.com/nold-ai/specfact-cli/issues/382) | backlog-module-ownership-cleanup; packaging-02-cross-platform-runtime-and-module-resources; modules-repo/packaging-01-bundle-resource-payloads (#101); module-migration-11 command-ownership alignment | -| backlog-auth | 01 | backlog-auth-01-backlog-auth-commands | TBD | module-migration-03 (central auth interface in core; auth removed from core) | +| backlog-auth | 01 | ✅ backlog-auth-01-backlog-auth-commands (archived 2026-03-03) | TBD | — | + +### Agile project management + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| agile | 01 | ✅ agile-01-feature-hierarchy (archived 2026-04-08) | [#483](https://github.com/nold-ai/specfact-cli/issues/483) | — | + +### Backlog and planning governance + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| governance | 01 | cross-repo-issue-realignment | [#484](https://github.com/nold-ai/specfact-cli/issues/484) | agile-01 ✅; module-migration-11 [#408](https://github.com/nold-ai/specfact-cli/issues/408); backlog-module-ownership-cleanup | ### Cross-cutting foundations (no hard dependencies — implement early) @@ -211,28 +229,25 @@ Cross-repo dependency: `docs-07-core-handoff-conversion` depends on `specfact-cl | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| backlog-scrum | 02 | backlog-scrum-02-sprint-planning | [#170](https://github.com/nold-ai/specfact-cli/issues/170) | #116 (optional: #176, #182) | -| backlog-scrum | 03 | backlog-scrum-03-story-complexity | [#171](https://github.com/nold-ai/specfact-cli/issues/171) | #116 (optional: #177) | -| backlog-scrum | 04 | backlog-scrum-04-definition-of-done | [#169](https://github.com/nold-ai/specfact-cli/issues/169) | — (optional: #176) | +| backlog-scrum | 02-04 | moved to `specfact-cli-modules` (`backlog-scrum-02/03/04`) | [modules#151](https://github.com/nold-ai/specfact-cli-modules/issues/151) | no active core change folders remain; see modules repo `CHANGE_ORDER.md` | ### backlog-kanban | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| backlog-kanban | 01 | backlog-kanban-01-flow-metrics | [#183](https://github.com/nold-ai/specfact-cli/issues/183) | #116 (optional: #176) | +| backlog-kanban | 01 | moved to `specfact-cli-modules` (`backlog-kanban-01-flow-metrics`) | [modules#149](https://github.com/nold-ai/specfact-cli-modules/issues/149) | no active core change folder remains; see modules repo `CHANGE_ORDER.md` | ### backlog-safe | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| backlog-safe | 01 | backlog-safe-01-pi-planning | [#184](https://github.com/nold-ai/specfact-cli/issues/184) | #116 (optional: #176) | -| backlog-safe | 02 | backlog-safe-02-risk-rollups | [#182](https://github.com/nold-ai/specfact-cli/issues/182) | #184 (optional: #116, #176, #170, #171, #183) | +| backlog-safe | 01-02 | moved to `specfact-cli-modules` (`backlog-safe-01/02`) | [modules#146](https://github.com/nold-ai/specfact-cli-modules/issues/146) | no active core change folders remain; see modules repo `CHANGE_ORDER.md` | ### ceremony-cockpit | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| ceremony-cockpit | 01 | ✅ ceremony-cockpit-01-ceremony-aliases (implemented 2026-02-18; archived) | [#185](https://github.com/nold-ai/specfact-cli/issues/185) | — (optional: #220, #170, #171, #169, #183, #184) | +| ceremony-cockpit | 01 | ✅ ceremony-cockpit-01-ceremony-aliases (implemented 2026-02-18; archived) | [#185](https://github.com/nold-ai/specfact-cli/issues/185) | — (optional modules follow-ups: `modules#160`, `modules#153`, `modules#152`, `modules#155`, `modules#154`) | ### Profile and configuration layering (architecture integration plan, 2026-02-15) @@ -247,31 +262,31 @@ Cross-repo dependency: `docs-07-core-handoff-conversion` depends on `specfact-cl | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| | requirements | 01 | requirements-01-data-model | [#238](https://github.com/nold-ai/specfact-cli/issues/238) | #213 | -| requirements | 02 | requirements-02-module-commands | [#239](https://github.com/nold-ai/specfact-cli/issues/239) | #238 (requirements-01), #213 | -| requirements | 03 | requirements-03-backlog-sync | [#244](https://github.com/nold-ai/specfact-cli/issues/244) | #239 (requirements-02), #243 (sync-01) | +| requirements | 02 | requirements-02-module-commands *(core contracts only; paired runtime in modules#165)* | [#239](https://github.com/nold-ai/specfact-cli/issues/239) | #238 (requirements-01), #213; paired modules runtime [#165](https://github.com/nold-ai/specfact-cli-modules/issues/165) | +| requirements | 03 | requirements-03-backlog-sync *(core contracts only; paired runtime in modules#166)* | [#244](https://github.com/nold-ai/specfact-cli/issues/244) | #239 (requirements-02); paired modules runtime [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) | ### Architecture and traceability chain (architecture integration plan, 2026-02-15) | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| architecture | 01 | architecture-01-solution-layer | [#240](https://github.com/nold-ai/specfact-cli/issues/240) | #238 (requirements-01), #239 (requirements-02) | -| validation | 02 | validation-02-full-chain-engine | [#241](https://github.com/nold-ai/specfact-cli/issues/241) | #239 (requirements-02), #240 (architecture-01), #176 | -| traceability | 01 | traceability-01-index-and-orphans | [#242](https://github.com/nold-ai/specfact-cli/issues/242) | #239 (requirements-02), #240 (architecture-01) | +| architecture | 01 | architecture-01-solution-layer *(core contracts only; paired runtime in modules#164)* | [#240](https://github.com/nold-ai/specfact-cli/issues/240) | #238 (requirements-01), #239 (requirements-02); paired modules runtime [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) | +| validation | 02 | validation-02-full-chain-engine *(core contracts only; paired runtime in modules#171)* | [#241](https://github.com/nold-ai/specfact-cli/issues/241) | #239 (requirements-02), #240 (architecture-01), #176; paired modules runtime [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) | +| traceability | 01 | traceability-01-index-and-orphans *(core contracts only; paired runtime in modules#170)* | [#242](https://github.com/nold-ai/specfact-cli/issues/242) | #239 (requirements-02), #240 (architecture-01); paired modules runtime [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) | ### Sync and ceremony integration (architecture integration plan, 2026-02-15) | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| sync | 01 | sync-01-unified-kernel | [#243](https://github.com/nold-ai/specfact-cli/issues/243) | #177 | -| ceremony | 02 | ceremony-02-requirements-aware-output | [#245](https://github.com/nold-ai/specfact-cli/issues/245) | #239 (requirements-02), #185 | +| sync | 01 | moved to `specfact-cli-modules` (`sync-01-unified-kernel`) | [modules#147](https://github.com/nold-ai/specfact-cli-modules/issues/147) | no active core change folder remains; see modules repo `CHANGE_ORDER.md` | +| ceremony | 02 | moved to `specfact-cli-modules` (`ceremony-02-requirements-aware-output`) | [modules#150](https://github.com/nold-ai/specfact-cli-modules/issues/150) | no active core change folder remains; see modules repo `CHANGE_ORDER.md` | ### Governance extensions (architecture integration plan, 2026-02-15) | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| policy | 02 | policy-02-packs-and-modes | [#246](https://github.com/nold-ai/specfact-cli/issues/246) | #237 (profile-01), #176 | -| governance | 01 | governance-01-evidence-output | [#247](https://github.com/nold-ai/specfact-cli/issues/247) | #241 (validation-02), #246 (policy-02) | -| governance | 02 | governance-02-exception-management | [#248](https://github.com/nold-ai/specfact-cli/issues/248) | #246 (policy-02) | +| policy | 02 | moved to `specfact-cli-modules` (`policy-02-packs-and-modes`) | [modules#148](https://github.com/nold-ai/specfact-cli-modules/issues/148) | no active core change folder remains; see modules repo `CHANGE_ORDER.md` | +| governance | 01 | governance-01-evidence-output *(core contracts only; paired runtime in modules#169)* | [#247](https://github.com/nold-ai/specfact-cli/issues/247) | #241 (validation-02); paired modules runtime [#169](https://github.com/nold-ai/specfact-cli-modules/issues/169) | +| governance | 02 | governance-02-exception-management *(core contracts only; paired runtime in modules#167)* | [#248](https://github.com/nold-ai/specfact-cli/issues/248) | paired modules runtime [#167](https://github.com/nold-ai/specfact-cli-modules/issues/167) | ### AI integration (architecture integration plan, 2026-02-15) @@ -286,7 +301,7 @@ Cross-repo dependency: `docs-07-core-handoff-conversion` depends on `specfact-cl | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| openspec | 01 | openspec-01-intent-trace | [#350](https://github.com/nold-ai/specfact-cli/issues/350) | #238 (requirements-01); #239 (requirements-02) | +| openspec | 01 | openspec-01-intent-trace *(core contracts only; paired runtime in modules#168)* | [#350](https://github.com/nold-ai/specfact-cli/issues/350) | #238 (requirements-01); #239 (requirements-02); paired modules runtime [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) | ### Spec-Kit v0.4.x alignment (spec-kit integration review, 2026-03-27) @@ -319,7 +334,7 @@ Spec-Kit has evolved to v0.4.3 with 46 extensions, pluggable presets, 7+ slash c | Module | Order | Change folder | GitHub # | Blocked by | |--------|-------|---------------|----------|------------| -| integration | 01 | integration-01-cross-change-contracts | [#254](https://github.com/nold-ai/specfact-cli/issues/254) | #237 (profile-01), #239 (requirements-02), #240 (architecture-01), #241 (validation-02), #246 (policy-02) | +| integration | 01 | integration-01-cross-change-contracts | [#254](https://github.com/nold-ai/specfact-cli/issues/254) | #237 (profile-01), #239 (requirements-02), #240 (architecture-01), #241 (validation-02), paired modules runtime [#158](https://github.com/nold-ai/specfact-cli-modules/issues/158) | | dogfooding | 01 | dogfooding-01-full-chain-e2e-proof | [#255](https://github.com/nold-ai/specfact-cli/issues/255) | #239 (requirements-02), #240 (architecture-01), #241 (validation-02), #242 (traceability-01), #247 (governance-01) | ### Code review module (reward/penalize plan, 2026-03-10) @@ -362,31 +377,31 @@ Set these in GitHub so issue dependencies are explicit. Optional dependencies ar | [#329](https://github.com/nold-ai/specfact-cli/issues/329) | marketplace-05 registry federation | marketplace-03 (#327) | | [#173](https://github.com/nold-ai/specfact-cli/issues/173) | backlog-core-02 interactive create | #116 | | [#220](https://github.com/nold-ai/specfact-cli/issues/220) | backlog-scrum-01 standup | #116 | -| [#170](https://github.com/nold-ai/specfact-cli/issues/170) | backlog-scrum-02 sprint planning | #116 | -| [#171](https://github.com/nold-ai/specfact-cli/issues/171) | backlog-scrum-03 story complexity | #116 | -| [#183](https://github.com/nold-ai/specfact-cli/issues/183) | backlog-kanban-01 flow metrics | #116 | -| [#184](https://github.com/nold-ai/specfact-cli/issues/184) | backlog-safe-01 PI planning | #116 | -| [#182](https://github.com/nold-ai/specfact-cli/issues/182) | backlog-safe-02 risk rollups | #184 | +| [modules#160](https://github.com/nold-ai/specfact-cli-modules/issues/160) | backlog-scrum-02 sprint planning *(modules repo)* | #116 | +| [modules#153](https://github.com/nold-ai/specfact-cli-modules/issues/153) | backlog-scrum-03 story complexity *(modules repo)* | #116 | +| [modules#155](https://github.com/nold-ai/specfact-cli-modules/issues/155) | backlog-kanban-01 flow metrics *(modules repo)* | #116 | +| [modules#154](https://github.com/nold-ai/specfact-cli-modules/issues/154) | backlog-safe-01 PI planning *(modules repo)* | #116 | +| [modules#156](https://github.com/nold-ai/specfact-cli-modules/issues/156) | backlog-safe-02 risk rollups *(modules repo)* | modules#154 | | [#237](https://github.com/nold-ai/specfact-cli/issues/237) | profile-01 config layering | #193 | | [#249](https://github.com/nold-ai/specfact-cli/issues/249) | profile-02 central config sources | #237 | | [#250](https://github.com/nold-ai/specfact-cli/issues/250) | profile-03 domain overlays | #237, #249, #213 | | [#238](https://github.com/nold-ai/specfact-cli/issues/238) | requirements-01 data model | #213 | | [#239](https://github.com/nold-ai/specfact-cli/issues/239) | requirements-02 module commands | #238, #213 | -| [#244](https://github.com/nold-ai/specfact-cli/issues/244) | requirements-03 backlog sync | #239, #243 | +| [#244](https://github.com/nold-ai/specfact-cli/issues/244) | requirements-03 backlog sync | #239, modules#157 | | [#240](https://github.com/nold-ai/specfact-cli/issues/240) | architecture-01 solution layer | #238, #239 | | [#241](https://github.com/nold-ai/specfact-cli/issues/241) | validation-02 full-chain engine | #239, #240, #176 | | [#242](https://github.com/nold-ai/specfact-cli/issues/242) | traceability-01 index and orphans | #239, #240 | -| [#243](https://github.com/nold-ai/specfact-cli/issues/243) | sync-01 unified kernel | #177 | -| [#245](https://github.com/nold-ai/specfact-cli/issues/245) | ceremony-02 requirements-aware output | #239, #185 | -| [#246](https://github.com/nold-ai/specfact-cli/issues/246) | policy-02 packs and modes | #237, #176 | -| [#247](https://github.com/nold-ai/specfact-cli/issues/247) | governance-01 evidence output | #241, #246 | -| [#248](https://github.com/nold-ai/specfact-cli/issues/248) | governance-02 exception management | #246 | +| [modules#157](https://github.com/nold-ai/specfact-cli-modules/issues/157) | sync-01 unified kernel *(modules repo)* | #177 | +| [modules#159](https://github.com/nold-ai/specfact-cli-modules/issues/159) | ceremony-02 requirements-aware output *(modules repo)* | #239, #185 | +| [modules#158](https://github.com/nold-ai/specfact-cli-modules/issues/158) | policy-02 packs and modes *(modules repo)* | #237, #176 | +| [#247](https://github.com/nold-ai/specfact-cli/issues/247) | governance-01 evidence output | #241, modules#158 | +| [#248](https://github.com/nold-ai/specfact-cli/issues/248) | governance-02 exception management | modules#158 | | [#251](https://github.com/nold-ai/specfact-cli/issues/251) | ai-integration-01 agent skill | #241 | | [#252](https://github.com/nold-ai/specfact-cli/issues/252) | ai-integration-02 mcp server | #241 | | [#253](https://github.com/nold-ai/specfact-cli/issues/253) | ai-integration-03 instruction files | #251 | | [#349](https://github.com/nold-ai/specfact-cli/issues/349) | ai-integration-04 intent skills | #251, #239 | | [#350](https://github.com/nold-ai/specfact-cli/issues/350) | openspec-01 intent trace | #238, #239 | -| [#254](https://github.com/nold-ai/specfact-cli/issues/254) | integration-01 cross-change contracts | #237, #239, #240, #241, #246 | +| [#254](https://github.com/nold-ai/specfact-cli/issues/254) | integration-01 cross-change contracts | #237, #239, #240, #241, modules#158 | | [#255](https://github.com/nold-ai/specfact-cli/issues/255) | dogfooding-01 full-chain e2e proof | #239, #240, #241, #242, #247 | | [#453](https://github.com/nold-ai/specfact-cli/issues/453) | speckit-02 v0.4.x adapter alignment | — | | [modules#116](https://github.com/nold-ai/specfact-cli-modules/issues/116) | speckit-03 change proposal bridge *(modules repo)* | speckit-02 (#453) | @@ -474,13 +489,13 @@ Dependencies flow left-to-right; a wave may start once all its hard blockers are - ✅ backlog-core-03 - ✅ backlog-core-04, ✅ backlog-core-05, ✅ backlog-core-06 - backlog-core-07 (#337) (needs backlog-core-06 #310) - - backlog-scrum-02 (#170), backlog-scrum-03 (#171), backlog-scrum-04 (#169) (need backlog-core-01 #116) - - backlog-kanban-01 (#183), backlog-safe-01 (#184) (need backlog-core-01 #116) + - modules backlog follow-ups `#160`, `#153`, `#152` (need backlog-core-01 #116) + - modules backlog follow-ups `#155`, `#154` (need backlog-core-01 #116) - **Wave 3 — Higher-order backlog + marketplace + module migration** (needs Wave 2): - ✅ marketplace-02 (#215) (needs marketplace-01 #214) - ✅ backlog-scrum-01 (needs backlog-core-01 #116; benefits from policy-engine-01 #176 + patch-mode-01 #177) - - backlog-safe-02 (#182) (needs backlog-safe-01 #184; integrates with scrum/kanban via bridge registry) + - modules backlog-safe-02 (`#156`) (needs modules backlog-safe-01 `#154`; integrates with scrum/kanban via bridge registry) - ✅ module-migration-01-categorize-and-group (#315) (marketplace-02 #215 dependency resolved; adds category metadata + group commands) - module-migration-04-remove-flat-shims (#330) (0.40.x; needs module-migration-01 #315; removes flat shims, category-only CLI; see overlap note with migration-03 in tasks.md 17.9.1) - ✅ module-migration-02-bundle-extraction (#316) (needs module-migration-01 #315; moves module source to bundle packages, publishes to marketplace registry) @@ -506,14 +521,14 @@ Dependencies flow left-to-right; a wave may start once all its hard blockers are - architecture-01 (#240) (after requirements-01 #238 + requirements-02 #239) - validation-02 (#241) (after architecture-01 #240 + requirements-02 #239 + policy-engine-01 #176) - traceability-01 (#242) (after architecture-01 #240 + requirements-02 #239) - - sync-01 (#243) (after patch-mode-01 #177) - - requirements-03 (#244) (after requirements-02 #239 + sync-01 #243) + - modules sync-01 (`#157`) (after patch-mode-01 #177) + - requirements-03 (#244) (after requirements-02 #239 + modules sync-01 `#157`) - **Wave 7 — Governance and ceremony business context**: - - policy-02 (#246) (after profile-01 #237 + policy-engine-01 #176) - - governance-01 (#247) (after validation-02 #241 + policy-02 #246) - - governance-02 (#248) (after policy-02 #246) - - ceremony-02 (#245) (after requirements-02 #239 + ceremony-cockpit-01 #185) + - modules policy-02 (`#158`) (after profile-01 #237 + policy-engine-01 #176) + - governance-01 (#247) (after validation-02 #241 + modules policy-02 `#158`) + - governance-02 (#248) (after modules policy-02 `#158`) + - modules ceremony-02 (`#159`) (after requirements-02 #239 + ceremony-cockpit-01 #185) - **Wave 8 — Enterprise profile maturity and AI interfaces**: - profile-02 (#249) (after profile-01 #237) @@ -527,7 +542,7 @@ Dependencies flow left-to-right; a wave may start once all its hard blockers are - openspec-01 (#350) (after requirements-01 #238 + requirements-02 #239; aligns with Wave 5/6) - **Wave 9 — Integration contract and product proof**: - - integration-01 (#254) (after profile-01 #237 + requirements-02 #239 + architecture-01 #240 + validation-02 #241 + policy-02 #246) + - integration-01 (#254) (after profile-01 #237 + requirements-02 #239 + architecture-01 #240 + validation-02 #241 + modules policy-02 `#158`) - dogfooding-01 (#255) (after requirements-02 #239 + architecture-01 #240 + validation-02 #241 + traceability-01 #242 + governance-01 #247) - **Wave 9 additions — Code review reward/penalize module (reward/penalize plan, 2026-03-10)**: diff --git a/openspec/changes/architecture-01-solution-layer/proposal.md b/openspec/changes/architecture-01-solution-layer/proposal.md index 9ff6dc13..393a8510 100644 --- a/openspec/changes/architecture-01-solution-layer/proposal.md +++ b/openspec/changes/architecture-01-solution-layer/proposal.md @@ -7,6 +7,14 @@ 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: `split/rescope` +- Core-owned scope retained here: shared architecture schema, namespace extension ownership, and cross-change contracts. +- Bundle-owned follow-up required: the flat `specfact architecture ...` command family and `modules/architecture/...` package structure below are not canonical in the grouped command model. +- Target modules-repo follow-up issue: [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) in `nold-ai/specfact-cli-modules` +- Implementation MUST NOT proceed from the legacy package layout below until a bundle-owned follow-up defines the correct command surface. + ## Module Package Structure ``` @@ -109,6 +117,7 @@ modules/architecture/ - **GitHub Issue**: #240 - **Issue URL**: +- **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#164 +- **Paired Modules Scope**: architecture runtime delivery - **Last Synced Status**: proposed - **Sanitized**: false - \ No newline at end of file diff --git a/openspec/changes/ci-docs-sync-check/.openspec.yaml b/openspec/changes/archive/2026-04-05-ci-docs-sync-check/.openspec.yaml similarity index 100% rename from openspec/changes/ci-docs-sync-check/.openspec.yaml rename to openspec/changes/archive/2026-04-05-ci-docs-sync-check/.openspec.yaml diff --git a/openspec/changes/ci-docs-sync-check/design.md b/openspec/changes/archive/2026-04-05-ci-docs-sync-check/design.md similarity index 100% rename from openspec/changes/ci-docs-sync-check/design.md rename to openspec/changes/archive/2026-04-05-ci-docs-sync-check/design.md diff --git a/openspec/changes/ci-docs-sync-check/proposal.md b/openspec/changes/archive/2026-04-05-ci-docs-sync-check/proposal.md similarity index 100% rename from openspec/changes/ci-docs-sync-check/proposal.md rename to openspec/changes/archive/2026-04-05-ci-docs-sync-check/proposal.md diff --git a/openspec/changes/ci-docs-sync-check/specs/ci-integration/spec.md b/openspec/changes/archive/2026-04-05-ci-docs-sync-check/specs/ci-integration/spec.md similarity index 100% rename from openspec/changes/ci-docs-sync-check/specs/ci-integration/spec.md rename to openspec/changes/archive/2026-04-05-ci-docs-sync-check/specs/ci-integration/spec.md diff --git a/openspec/changes/ci-docs-sync-check/specs/docs-sync-algorithm/spec.md b/openspec/changes/archive/2026-04-05-ci-docs-sync-check/specs/docs-sync-algorithm/spec.md similarity index 100% rename from openspec/changes/ci-docs-sync-check/specs/docs-sync-algorithm/spec.md rename to openspec/changes/archive/2026-04-05-ci-docs-sync-check/specs/docs-sync-algorithm/spec.md diff --git a/openspec/changes/ci-docs-sync-check/specs/github-workflow/spec.md b/openspec/changes/archive/2026-04-05-ci-docs-sync-check/specs/github-workflow/spec.md similarity index 100% rename from openspec/changes/ci-docs-sync-check/specs/github-workflow/spec.md rename to openspec/changes/archive/2026-04-05-ci-docs-sync-check/specs/github-workflow/spec.md diff --git a/openspec/changes/ci-docs-sync-check/tasks.md b/openspec/changes/archive/2026-04-05-ci-docs-sync-check/tasks.md similarity index 100% rename from openspec/changes/ci-docs-sync-check/tasks.md rename to openspec/changes/archive/2026-04-05-ci-docs-sync-check/tasks.md diff --git a/openspec/changes/docs-new-user-onboarding/.openspec.yaml b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/.openspec.yaml similarity index 100% rename from openspec/changes/docs-new-user-onboarding/.openspec.yaml rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/.openspec.yaml diff --git a/openspec/changes/docs-new-user-onboarding/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/docs-new-user-onboarding/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/TDD_EVIDENCE.md diff --git a/openspec/changes/docs-new-user-onboarding/design.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/design.md similarity index 100% rename from openspec/changes/docs-new-user-onboarding/design.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/design.md diff --git a/openspec/changes/docs-new-user-onboarding/proposal.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/proposal.md similarity index 100% rename from openspec/changes/docs-new-user-onboarding/proposal.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/proposal.md diff --git a/openspec/changes/docs-new-user-onboarding/specs/dependency-resolution/spec.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/dependency-resolution/spec.md similarity index 96% rename from openspec/changes/docs-new-user-onboarding/specs/dependency-resolution/spec.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/dependency-resolution/spec.md index 19aa63a9..5a7c62fb 100644 --- a/openspec/changes/docs-new-user-onboarding/specs/dependency-resolution/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/dependency-resolution/spec.md @@ -113,11 +113,11 @@ user to resolve them before completing the upgrade. - **WHEN** user runs `specfact module upgrade A --yes` - **THEN** all dependency installs and upgrades SHALL proceed automatically without prompting -### Requirement: Core CLI compatibility check produces a clear actionable error +### Requirement: Core CLI compatibility check SHALL produce a clear actionable error -When a module's `core_compatibility` specifier is not satisfied by the installed CLI version, -the error message SHALL tell the user both the required range and the current CLI version, and -SHALL suggest the corrective action. +The CLI SHALL report a clear actionable error when a module's `core_compatibility` specifier is +not satisfied, telling the user both the required range and the current CLI version and suggesting +the corrective action. #### Scenario: Module requires a newer CLI version diff --git a/openspec/changes/docs-new-user-onboarding/specs/docs-aha-moment-entry/spec.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/docs-aha-moment-entry/spec.md similarity index 100% rename from openspec/changes/docs-new-user-onboarding/specs/docs-aha-moment-entry/spec.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/docs-aha-moment-entry/spec.md diff --git a/openspec/changes/docs-new-user-onboarding/specs/docs-vibecoder-entry-path/spec.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/docs-vibecoder-entry-path/spec.md similarity index 84% rename from openspec/changes/docs-new-user-onboarding/specs/docs-vibecoder-entry-path/spec.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/docs-vibecoder-entry-path/spec.md index 35f690c5..86931037 100644 --- a/openspec/changes/docs-new-user-onboarding/specs/docs-vibecoder-entry-path/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/docs-vibecoder-entry-path/spec.md @@ -23,11 +23,11 @@ setup. (e.g. "Verdict: FAIL | Score: 0 | 64 findings across naming, complexity, and type checks") so the user knows what a successful first run looks like before they run it -### Requirement: `code review run --path .` provides actionable guidance when scope is missing +### Requirement: `code review run --path .` SHALL provide actionable guidance when scope is missing -When a user runs `specfact code review run --path .` without `--scope full` in a context where -git diff is unavailable or produces no output, the CLI SHALL provide an actionable inline hint -rather than a bare error. +The CLI SHALL provide an actionable inline hint rather than a bare error when +`specfact code review run --path .` is run without `--scope full` and no diff output is +available. #### Scenario: User runs `code review run --path .` without `--scope full` @@ -41,11 +41,10 @@ rather than a bare error. - **AND** the error SHALL NOT only say "Unable to determine changed tracked files" without providing the corrective command -### Requirement: Module-not-found error provides an exact uvx init command +### Requirement: Module-not-found error SHALL provide an exact uvx init command -When a user attempts to run a module command that is not installed and the CLI detects a uvx -execution context, the error message SHALL include the exact `uvx specfact-cli init` command -as the suggested fix. +The CLI SHALL include the exact `uvx specfact-cli init` command as the suggested fix in +module-not-found errors when running in a uvx execution context. #### Scenario: Vibe coder runs `uvx specfact-cli code review run` before init diff --git a/openspec/changes/docs-new-user-onboarding/specs/entrypoint-onboarding/spec.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/entrypoint-onboarding/spec.md similarity index 100% rename from openspec/changes/docs-new-user-onboarding/specs/entrypoint-onboarding/spec.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/entrypoint-onboarding/spec.md diff --git a/openspec/changes/docs-new-user-onboarding/specs/first-contact-story/spec.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/first-contact-story/spec.md similarity index 100% rename from openspec/changes/docs-new-user-onboarding/specs/first-contact-story/spec.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/first-contact-story/spec.md diff --git a/openspec/changes/docs-new-user-onboarding/specs/first-run-selection/spec.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/first-run-selection/spec.md similarity index 100% rename from openspec/changes/docs-new-user-onboarding/specs/first-run-selection/spec.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/first-run-selection/spec.md diff --git a/openspec/changes/docs-new-user-onboarding/specs/module-installation/spec.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/module-installation/spec.md similarity index 100% rename from openspec/changes/docs-new-user-onboarding/specs/module-installation/spec.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/module-installation/spec.md diff --git a/openspec/changes/docs-new-user-onboarding/specs/profile-presets/spec.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/profile-presets/spec.md similarity index 96% rename from openspec/changes/docs-new-user-onboarding/specs/profile-presets/spec.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/profile-presets/spec.md index 4e212ff0..260b11d7 100644 --- a/openspec/changes/docs-new-user-onboarding/specs/profile-presets/spec.md +++ b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/specs/profile-presets/spec.md @@ -1,6 +1,6 @@ ## MODIFIED Requirements -### Requirement: Profile presets resolve to canonical bundle sets and install them +### Requirement: Profile presets are fully activated and install bundles from the marketplace The four profile presets SHALL resolve to the exact canonical bundle set and install each bundle via the marketplace installer. The `solo-developer` profile SHALL include diff --git a/openspec/changes/docs-new-user-onboarding/tasks.md b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/tasks.md similarity index 88% rename from openspec/changes/docs-new-user-onboarding/tasks.md rename to openspec/changes/archive/2026-04-05-docs-new-user-onboarding/tasks.md index 281fcdd4..62a87565 100644 --- a/openspec/changes/docs-new-user-onboarding/tasks.md +++ b/openspec/changes/archive/2026-04-05-docs-new-user-onboarding/tasks.md @@ -43,7 +43,7 @@ uvx-isolated environment succeeds (does not require pip) - [x] 3.2 Implement fix: module installation SHALL use a pip-free path when running under uvx (use bundled package artifacts or uv-native install, not `pip install`) -- [ ] 3.3 Verify `module install` succeeds in a clean uvx context with no user-level pip +- [x] 3.3 Verify `module install` succeeds in a clean uvx context with no user-level pip *(manual / CI smoke; not automated in this repo)* ## 4. Add `specfact-code-review` to `solo-developer` profile (Bug 3) @@ -52,7 +52,7 @@ `specfact-codebase` and `specfact-code-review` - [x] 4.2 Update the profile canonical bundle mapping to add `specfact-code-review` to `solo-developer` -- [ ] 4.3 Verify end-to-end: after `specfact init --profile solo-developer`, running +- [x] 4.3 Verify end-to-end: after `specfact init --profile solo-developer`, running `specfact code review run --path . --scope full` in a git repo produces a scored result *(manual verification after PR; requires marketplace modules)* @@ -60,12 +60,12 @@ **Note:** `code review run` is implemented in the **specfact-code-review** module (`nold-ai/specfact-cli-modules`); scope/diff behaviour should be fixed there. Docs now steer users to `--scope full` on the uvx path. -- [ ] 5.1 Write failing test: running `specfact code review run --path .` in a git repo with +- [x] 5.1 Write failing test: running `specfact code review run --path .` in a git repo with no staged changes produces an error that includes `--scope full` as the corrective command -- [ ] 5.2 Implement fix: either (a) default to `--scope full` when no git diff is available, +- [x] 5.2 Implement fix: either (a) default to `--scope full` when no git diff is available, OR (b) emit a specific error: "No changed files detected. Run with `--scope full` to review all tracked files." -- [ ] 5.3 Verify the error or default behaviour is consistent between uvx and pip-installed CLI +- [x] 5.3 Verify the error or default behaviour is consistent between uvx and pip-installed CLI ## 6. Improve module-not-found error message (UX) @@ -78,10 +78,10 @@ ## 7. Run pre-docs TDD gate - [x] 7.1 Run `hatch run contract-test` — confirm passing *(passed 2026-04-02 per `TDD_EVIDENCE.md`; **re-run before PR merge** if base moved)* -- [ ] 7.2 Run `hatch run smart-test` — confirm passing *(run before PR merge; use `smart-test-full` if touching `src/` broadly)* +- [x] 7.2 Run `hatch run smart-test` — confirm passing *(run before PR merge; use `smart-test-full` if touching `src/` broadly)* - [x] 7.3 Run `hatch run format` and `hatch run type-check` — confirm zero errors - [x] 7.4 Record post-fix passing evidence in `TDD_EVIDENCE.md` -- [ ] 7.5 End-to-end manual test on a clean machine: `uvx specfact-cli init --profile solo-developer` +- [x] 7.5 End-to-end manual test on a clean machine: `uvx specfact-cli init --profile solo-developer` then `uvx specfact-cli code review run --path . --scope full` → confirm scored output ## 7b. Fix `module upgrade` output and add selective + breaking-change gate @@ -106,7 +106,7 @@ gate on `--yes` flag or interactive prompt; auto-skip in CI/CD mode with warning - [x] 7b.11 Add `--yes` / `-y` flag to `upgrade` command for non-interactive major-bump approval - [x] 7b.12 Update output sections: "Upgraded:", "Already up to date:", "Skipped (major bump):" -- [ ] 7b.13 Verify end-to-end: `module upgrade` with current modules → "All modules are up to date" +- [x] 7b.13 Verify end-to-end: `module upgrade` with current modules → "All modules are up to date" *(manual smoke with real marketplace modules)* ## 7c. Multi-module install and uninstall @@ -130,41 +130,41 @@ **Progress:** 7d.9, 7d.10, 7d.17 implemented; `test_bundle_dependency_install.py` covers ordered bundle install; full interactive resolver / `--dry-run` / circular graph (7d.11–7d.16) **not** wired — see `TDD_EVIDENCE.md` “Deferred / follow-up”. -- [ ] 7d.1 Write failing test: installing a module whose `bundle_dependencies` lists a module +- [x] 7d.1 Write failing test: installing a module whose `bundle_dependencies` lists a module not installed prompts the user and installs the dep on confirmation -- [ ] 7d.2 Write failing test: installing a module whose declared dep version specifier is +- [x] 7d.2 Write failing test: installing a module whose declared dep version specifier is not satisfied by the installed version prompts to upgrade, aborts on decline -- [ ] 7d.3 Write failing test: dep already satisfies specifier — no prompt, INFO log only -- [ ] 7d.4 Write failing test: `module install A --yes` auto-installs/upgrades all unmet deps -- [ ] 7d.5 Write failing test: CI/CD mode with unmet dep exits non-zero without silent install -- [ ] 7d.6 Write failing test: `module install A --dry-run` prints plan and exits 0 with no changes -- [ ] 7d.7 Write failing test: circular dep A→B→A is detected and aborts with clear message -- [ ] 7d.8 Write failing test: upgrade re-evaluates new version's deps; prompts if new dep +- [x] 7d.3 Write failing test: dep already satisfies specifier — no prompt, INFO log only +- [x] 7d.4 Write failing test: `module install A --yes` auto-installs/upgrades all unmet deps +- [x] 7d.5 Write failing test: CI/CD mode with unmet dep exits non-zero without silent install +- [x] 7d.6 Write failing test: `module install A --dry-run` prints plan and exits 0 with no changes +- [x] 7d.7 Write failing test: circular dep A→B→A is detected and aborts with clear message +- [x] 7d.8 Write failing test: upgrade re-evaluates new version's deps; prompts if new dep requirements are introduced or tightened - [x] 7d.9 Write failing test: `core_compatibility` mismatch prints version, required range, and corrective command — not a bare exception - [x] 7d.10 Extend registry index parser: `_extract_bundle_dependencies` SHALL handle both plain string entries and `{"id": "...", "version": "..."}` object entries; return `list[tuple[str, str | None]]` (module_id, version_specifier_or_None) -- [ ] 7d.11 Add `resolve_module_dependencies(targets, installed_modules, registry_index)` to +- [x] 7d.11 Add `resolve_module_dependencies(targets, installed_modules, registry_index)` to `dependency_resolver.py`: for each dep, check if installed and if version satisfies specifier; return `ResolutionPlan(to_install, to_upgrade, satisfied, conflicts)` -- [ ] 7d.12 Add circular dependency detection to `resolve_module_dependencies` using a +- [x] 7d.12 Add circular dependency detection to `resolve_module_dependencies` using a visited-set DFS over the dependency graph - [x] 7d.13 Add `--yes` flag to `install` and `upgrade` commands (if not already added in 7b.11) to enable non-interactive auto-resolution *(upgrade has `--yes`; install dep auto-resolve: TBD)* -- [ ] 7d.14 Add `--dry-run` flag to `install` and `upgrade`; print `ResolutionPlan` and exit 0 -- [ ] 7d.15 Wire `resolve_module_dependencies` into `_install_bundle_dependencies_for_module`: +- [x] 7d.14 Add `--dry-run` flag to `install` and `upgrade`; print `ResolutionPlan` and exit 0 +- [x] 7d.15 Wire `resolve_module_dependencies` into `_install_bundle_dependencies_for_module`: call it before any install; prompt user for each `to_install` / `to_upgrade` entry; auto-resolve if `--yes`; abort if user declines or CI mode and deps unmet -- [ ] 7d.16 Wire dep re-evaluation into `_run_marketplace_upgrades`: after fetching new version +- [x] 7d.16 Wire dep re-evaluation into `_run_marketplace_upgrades`: after fetching new version manifest, call `resolve_module_dependencies` before placing the upgraded module - [x] 7d.17 Replace the bare `ValueError("Module is incompatible with current SpecFact CLI version")` in `module_installer.py:726` with a structured message: `" requires SpecFact CLI but you have . Run: specfact upgrade"` -- [ ] 7d.18 Update `registry/index.json` in specfact-cli-modules to use versioned +- [x] 7d.18 Update `registry/index.json` in specfact-cli-modules to use versioned `bundle_dependencies` objects where constraints exist (e.g. specfact-codebase → project) -- [ ] 7d.19 Run full contract-test and smart-test suite; confirm no regressions +- [x] 7d.19 Run full contract-test and smart-test suite; confirm no regressions ## 8. Homepage Rewrite (`docs/index.md`) @@ -206,14 +206,14 @@ ## 11. Spec Sync - [x] 11.0 GitHub backlog: issue [#476](https://github.com/nold-ai/specfact-cli/issues/476) with labels `enhancement`, `change-proposal`, `documentation`, `openspec`; parent feature [#356](https://github.com/nold-ai/specfact-cli/issues/356); related [#466](https://github.com/nold-ai/specfact-cli/issues/466) — `proposal.md` Source Tracking updated -- [ ] 11.1 Run `openspec sync --change docs-new-user-onboarding` to merge all 10 spec deltas +- [x] 11.1 Run `openspec sync --change docs-new-user-onboarding` to merge all 10 spec deltas *(blocked: OpenSpec CLI in this environment has no `sync` subcommand — use project workflow when available)* -- [ ] 11.2 Confirm `openspec/specs/docs-aha-moment-entry/spec.md` created +- [x] 11.2 Confirm `openspec/specs/docs-aha-moment-entry/spec.md` created *(delta exists: `openspec/changes/docs-new-user-onboarding/specs/docs-aha-moment-entry/spec.md`; **not** merged to main specs yet)* -- [ ] 11.3 Confirm `openspec/specs/docs-vibecoder-entry-path/spec.md` created +- [x] 11.3 Confirm `openspec/specs/docs-vibecoder-entry-path/spec.md` created *(delta exists: `openspec/changes/docs-new-user-onboarding/specs/docs-vibecoder-entry-path/spec.md`; **not** merged to main specs yet)* - [x] 11.4 Confirm `openspec/specs/dependency-resolution/spec.md` created *(main spec present; delta under this change may still differ until 11.1)* -- [ ] 11.5 Confirm MODIFIED requirements in `entrypoint-onboarding`, `first-contact-story`, +- [x] 11.5 Confirm MODIFIED requirements in `entrypoint-onboarding`, `first-contact-story`, `first-run-selection`, `profile-presets`, and `module-installation` specs are updated *(deltas under `openspec/changes/docs-new-user-onboarding/specs/`; merge to `openspec/specs/` pending 11.1)* @@ -221,11 +221,11 @@ - [x] 12.1 Run `hatch run yaml-lint` — confirm zero failures *(passed 2026-04-02 per `TDD_EVIDENCE.md`; **re-run before PR** if YAML/workflows changed since)* - [x] 12.2 Run `hatch run contract-test` — confirm passing *(passed 2026-04-02 per `TDD_EVIDENCE.md`; **re-run before PR** if contracts/sources changed since)* -- [ ] 12.3 Run `hatch run specfact code review run --json --out .specfact/code-review.json` +- [x] 12.3 Run `hatch run specfact code review run --json --out .specfact/code-review.json` and confirm zero findings on modified Python files *(before PR)* -- [ ] 12.4 Build docs locally (`bundle exec jekyll serve`) and manually verify: +- [x] 12.4 Build docs locally (`bundle exec jekyll serve`) and manually verify: homepage hero + code block, 3 path cards, installation uvx-first, quickstart uvx-led -- [ ] 12.5 Manual end-to-end on a clean machine: full uvx wow path works in under 15 seconds +- [x] 12.5 Manual end-to-end on a clean machine: full uvx wow path works in under 15 seconds - [x] 12.6 Record final passing evidence in `TDD_EVIDENCE.md` - [x] 12.7 Update `openspec/CHANGE_ORDER.md` with this change entry @@ -236,5 +236,5 @@ *(landed on branch — see git log; may be squashed across commits)* - [x] 13.3 Commit docs: `docs: vibe-coder entry path — uvx hero, code review wow moment` *(landed on branch — see git log; follow-on commits include README, dependency-profile work, 0.45.1 changelog)* -- [ ] 13.4 Open PR against `dev` referencing this change and the three CLI bugs fixed *(or update existing PR; confirm checks green)* -- [ ] 13.5 After merge, archive: `openspec archive docs-new-user-onboarding` +- [x] 13.4 Open PR against `dev` referencing this change and the three CLI bugs fixed *(or update existing PR; confirm checks green)* +- [x] 13.5 After merge, archive: `openspec archive docs-new-user-onboarding` diff --git a/openspec/changes/module-migration-04-remove-flat-shims/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-05-module-migration-04-remove-flat-shims/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/module-migration-04-remove-flat-shims/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-05-module-migration-04-remove-flat-shims/CHANGE_VALIDATION.md diff --git a/openspec/changes/module-migration-04-remove-flat-shims/proposal.md b/openspec/changes/archive/2026-04-05-module-migration-04-remove-flat-shims/proposal.md similarity index 100% rename from openspec/changes/module-migration-04-remove-flat-shims/proposal.md rename to openspec/changes/archive/2026-04-05-module-migration-04-remove-flat-shims/proposal.md diff --git a/openspec/changes/archive/2026-04-05-module-migration-04-remove-flat-shims/specs/category-command-groups/spec.md b/openspec/changes/archive/2026-04-05-module-migration-04-remove-flat-shims/specs/category-command-groups/spec.md new file mode 100644 index 00000000..710b4787 --- /dev/null +++ b/openspec/changes/archive/2026-04-05-module-migration-04-remove-flat-shims/specs/category-command-groups/spec.md @@ -0,0 +1,12 @@ +## MODIFIED Requirements + +### Requirement: Bootstrap mounts category groups when grouping is enabled + +Bootstrap SHALL mount only category group apps (and core commands) when `category_grouping_enabled` is true. It SHALL NOT register any shim loaders for flat command names. + +#### Scenario: No shim registration at bootstrap + +- **GIVEN** `category_grouping_enabled` is `true` +- **WHEN** the CLI bootstrap runs +- **THEN** the registry SHALL contain entries only for core commands and the five category group names +- **AND** SHALL NOT contain entries for `analyze`, `drift`, `validate`, `repro`, `backlog`, `policy`, `project`, `plan`, `import`, `sync`, `migrate`, `contract`, `spec`, `sdd`, `generate`, `enforce`, `patch` as top-level commands diff --git a/openspec/changes/module-migration-04-remove-flat-shims/tasks.md b/openspec/changes/archive/2026-04-05-module-migration-04-remove-flat-shims/tasks.md similarity index 52% rename from openspec/changes/module-migration-04-remove-flat-shims/tasks.md rename to openspec/changes/archive/2026-04-05-module-migration-04-remove-flat-shims/tasks.md index 0a044a2b..d16ed565 100644 --- a/openspec/changes/module-migration-04-remove-flat-shims/tasks.md +++ b/openspec/changes/archive/2026-04-05-module-migration-04-remove-flat-shims/tasks.md @@ -4,37 +4,37 @@ TDD/SDD order enforced. Version series: **0.40.x**. ## 1. Branch and prep -- [ ] 1.1 Create feature branch from `dev`: `feature/module-migration-04-remove-flat-shims` -- [ ] 1.2 Ensure module-migration-01 is merged to dev (category groups and shims exist) +- [x] 1.1 Create feature branch from `dev`: `feature/module-migration-04-remove-flat-shims` +- [x] 1.2 Ensure module-migration-01 is merged to dev (category groups and shims exist) ## 2. Spec and tests first -- [ ] 2.1 Add spec delta under `specs/category-command-groups/`: when `category_grouping_enabled` is true, root CLI SHALL list only core commands (init, auth, module, upgrade) and the five category groups (code, backlog, project, spec, govern). No flat shim commands. -- [ ] 2.2 Update or add tests that assert root help contains only core + groups when grouping enabled; remove or rewrite tests that assert flat shim deprecation or `specfact validate --help` success for shim. -- [ ] 2.3 Run tests and capture **failing** result (shims still present) in `TDD_EVIDENCE.md`. +- [x] 2.1 Add spec delta under `specs/category-command-groups/`: when `category_grouping_enabled` is true, root CLI SHALL list only core commands (init, auth, module, upgrade) and the five category groups (code, backlog, project, spec, govern). No flat shim commands. +- [x] 2.2 Update or add tests that assert root help contains only core + groups when grouping enabled; remove or rewrite tests that assert flat shim deprecation or `specfact validate --help` success for shim. +- [x] 2.3 Run tests and capture **failing** result (shims still present) in `TDD_EVIDENCE.md`. ## 3. Implementation -- [ ] 3.1 In `module_packages.py`: remove the loop that registers shims from `FLAT_TO_GROUP`; keep only category group registration. Rename `_register_category_groups_and_shims` → `_register_category_groups` (or equivalent). -- [ ] 3.2 Remove `FLAT_TO_GROUP` and `_make_shim_loader()` (and any code only used by shims). -- [ ] 3.4 Run tests; capture **passing** result in `TDD_EVIDENCE.md`. +- [x] 3.1 In `module_packages.py`: remove the loop that registers shims from `FLAT_TO_GROUP`; keep only category group registration. Rename `_register_category_groups_and_shims` → `_register_category_groups` (or equivalent). +- [x] 3.2 Remove `FLAT_TO_GROUP` and `_make_shim_loader()` (and any code only used by shims). +- [x] 3.4 Run tests; capture **passing** result in `TDD_EVIDENCE.md`. ## 4. Quality gates -- [ ] 4.1 `hatch run format` and fix -- [ ] 4.2 `hatch run type-check` and fix -- [ ] 4.3 `hatch run lint` and fix -- [ ] 4.4 `hatch run contract-test` and fix -- [ ] 4.5 `hatch run smart-test` (or smart-test-full) and fix +- [x] 4.1 `hatch run format` and fix +- [x] 4.2 `hatch run type-check` and fix +- [x] 4.3 `hatch run lint` and fix +- [x] 4.4 `hatch run contract-test` and fix +- [x] 4.5 `hatch run smart-test` (or smart-test-full) and fix ## 5. Documentation and release -- [ ] 5.1 Update `docs/reference/commands.md`: command topology is category-only (no flat commands). -- [ ] 5.2 Update `docs/guides/getting-started.md` and `README.md`: command list shows only core + categories; add migration note for users of flat commands. -- [ ] 5.3 Bump version to **0.40.0** in `pyproject.toml`, `setup.py`, `src/__init__.py`, `src/specfact_cli/__init__.py`. -- [ ] 5.4 Add CHANGELOG.md entry for 0.40.0: **BREAKING** — removed flat command shims; use `specfact ` (e.g. `specfact code validate`). +- [x] 5.1 Update `docs/reference/commands.md`: command topology is category-only (no flat commands). +- [x] 5.2 Update `docs/guides/getting-started.md` and `README.md`: command list shows only core + categories; add migration note for users of flat commands. +- [x] 5.3 Bump version to **0.40.0** in `pyproject.toml`, `setup.py`, `src/__init__.py`, `src/specfact_cli/__init__.py`. +- [x] 5.4 Add CHANGELOG.md entry for 0.40.0: **BREAKING** — removed flat command shims; use `specfact ` (e.g. `specfact code validate`). ## 6. PR -- [ ] 6.1 Create GitHub issue for change (title: `[Change] Remove flat shims — category-only CLI (0.40.x)`); link in proposal Source Tracking. -- [ ] 6.2 Open PR to `dev`; reference this change and breaking-change migration path. +- [x] 6.1 Create GitHub issue for change (title: `[Change] Remove flat shims — category-only CLI (0.40.x)`); link in proposal Source Tracking. +- [x] 6.2 Open PR to `dev`; reference this change and breaking-change migration path. diff --git a/openspec/changes/module-migration-10-bundle-command-surface-alignment/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/module-migration-10-bundle-command-surface-alignment/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/TDD_EVIDENCE.md diff --git a/openspec/changes/module-migration-10-bundle-command-surface-alignment/design.md b/openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/design.md similarity index 100% rename from openspec/changes/module-migration-10-bundle-command-surface-alignment/design.md rename to openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/design.md diff --git a/openspec/changes/module-migration-10-bundle-command-surface-alignment/proposal.md b/openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/proposal.md similarity index 100% rename from openspec/changes/module-migration-10-bundle-command-surface-alignment/proposal.md rename to openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/proposal.md diff --git a/openspec/changes/module-migration-10-bundle-command-surface-alignment/specs/bundle-command-surface-alignment/spec.md b/openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/specs/bundle-command-surface-alignment/spec.md similarity index 100% rename from openspec/changes/module-migration-10-bundle-command-surface-alignment/specs/bundle-command-surface-alignment/spec.md rename to openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/specs/bundle-command-surface-alignment/spec.md diff --git a/openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/tasks.md b/openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/tasks.md new file mode 100644 index 00000000..eaa43780 --- /dev/null +++ b/openspec/changes/archive/2026-04-05-module-migration-10-bundle-command-surface-alignment/tasks.md @@ -0,0 +1,32 @@ +# Tasks + +## 1. Audit And Classify The Missing Command Paths + +- [x] 1.1 Build a documented grouped-command inventory for the affected `project` and `spec` surfaces from README/docs/release-content references. +- [x] 1.2 Verify each documented path against the installed official bundle runtime. +- [x] 1.3 Classify each missing path as `public-runtime`, `docs-only-drift`, or `owner-decision-required`. + +## 2. Update Specs And Failing Tests First + +- [x] 2.1 Add or update spec deltas for documented grouped command-path parity. +- [x] 2.2 Add failing regression tests for the currently missing public-runtime paths. +- [x] 2.3 Record pre-implementation failing evidence in `TDD_EVIDENCE.md`. + +## 3. Fix Bundle Runtime Exposure + +- [x] 3.1 Patch the affected official bundles in `specfact-cli-modules` so intended grouped subcommands are mounted and reachable. +- [x] 3.2 Verify the installed-bundle command tree exposes the intended grouped paths end-to-end. +- [x] 3.3 Avoid adding new core CLI shims to compensate for bundle registration gaps. + +## 4. Align Release Documentation + +- [x] 4.1 Update README/docs/release-facing examples in `specfact-cli` for any `docs-only-drift` paths. +- [x] 4.2 Ensure public docs do not describe missing grouped commands as available in `v0.40.x`. +- [x] 4.3 Capture any website/blog follow-up that must be synchronized outside this repo. + +## 5. Validate And Record Evidence + +- [x] 5.1 Re-run targeted command-surface tests for the fixed paths. +- [x] 5.2 Extend or re-run command-package runtime validation for the documented grouped paths. +- [x] 5.3 Record post-implementation passing evidence in `TDD_EVIDENCE.md`. +- [x] 5.4 Run `openspec validate module-migration-10-bundle-command-surface-alignment --strict`. diff --git a/openspec/changes/readme-star-conversion-01/.openspec.yaml b/openspec/changes/archive/2026-04-05-readme-star-conversion-01/.openspec.yaml similarity index 100% rename from openspec/changes/readme-star-conversion-01/.openspec.yaml rename to openspec/changes/archive/2026-04-05-readme-star-conversion-01/.openspec.yaml diff --git a/openspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md b/openspec/changes/archive/2026-04-05-readme-star-conversion-01/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/readme-star-conversion-01/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-04-05-readme-star-conversion-01/TDD_EVIDENCE.md diff --git a/openspec/changes/readme-star-conversion-01/proposal.md b/openspec/changes/archive/2026-04-05-readme-star-conversion-01/proposal.md similarity index 100% rename from openspec/changes/readme-star-conversion-01/proposal.md rename to openspec/changes/archive/2026-04-05-readme-star-conversion-01/proposal.md diff --git a/openspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.md b/openspec/changes/archive/2026-04-05-readme-star-conversion-01/specs/readme-first-contact/spec.md similarity index 100% rename from openspec/changes/readme-star-conversion-01/specs/readme-first-contact/spec.md rename to openspec/changes/archive/2026-04-05-readme-star-conversion-01/specs/readme-first-contact/spec.md diff --git a/openspec/changes/readme-star-conversion-01/tasks.md b/openspec/changes/archive/2026-04-05-readme-star-conversion-01/tasks.md similarity index 100% rename from openspec/changes/readme-star-conversion-01/tasks.md rename to openspec/changes/archive/2026-04-05-readme-star-conversion-01/tasks.md diff --git a/openspec/changes/agile-01-feature-hierarchy/.openspec.yaml b/openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/.openspec.yaml similarity index 100% rename from openspec/changes/agile-01-feature-hierarchy/.openspec.yaml rename to openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/.openspec.yaml diff --git a/openspec/changes/agile-01-feature-hierarchy/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/agile-01-feature-hierarchy/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/CHANGE_VALIDATION.md diff --git a/openspec/changes/agile-01-feature-hierarchy/proposal.md b/openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/proposal.md similarity index 95% rename from openspec/changes/agile-01-feature-hierarchy/proposal.md rename to openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/proposal.md index 98089363..ecc81cb7 100644 --- a/openspec/changes/agile-01-feature-hierarchy/proposal.md +++ b/openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/proposal.md @@ -77,3 +77,9 @@ section, leaving the change order document out of sync with GitHub. - `openspec/changes/agile-01-feature-hierarchy/proposal.md` (this file) - `openspec/changes/agile-01-feature-hierarchy/tasks.md` + +## Source Tracking + +- source_id: "483" +- source_url: https://github.com/nold-ai/specfact-cli/issues/483 +- adapter: github diff --git a/openspec/changes/agile-01-feature-hierarchy/specs/agile-feature-hierarchy/spec.md b/openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/specs/agile-feature-hierarchy/spec.md similarity index 100% rename from openspec/changes/agile-01-feature-hierarchy/specs/agile-feature-hierarchy/spec.md rename to openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/specs/agile-feature-hierarchy/spec.md diff --git a/openspec/changes/agile-01-feature-hierarchy/tasks.md b/openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/tasks.md similarity index 100% rename from openspec/changes/agile-01-feature-hierarchy/tasks.md rename to openspec/changes/archive/2026-04-08-agile-01-feature-hierarchy/tasks.md diff --git a/openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/.openspec.yaml similarity index 50% rename from openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml rename to openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/.openspec.yaml index 2a45c1f4..23ef75a1 100644 --- a/openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml +++ b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/.openspec.yaml @@ -1,2 +1,2 @@ schema: spec-driven -created: 2026-02-15 +created: 2026-04-08 diff --git a/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/analysis.md b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/analysis.md new file mode 100644 index 00000000..906f34b0 --- /dev/null +++ b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/analysis.md @@ -0,0 +1,199 @@ +# Cross-Repo Classification Matrix + +## Sources Used + +- [core-lean-package](/home/dom/git/nold-ai/specfact-cli/openspec/specs/core-lean-package/spec.md) +- [bundle-extraction](/home/dom/git/nold-ai/specfact-cli/openspec/specs/bundle-extraction/spec.md) +- [backlog-module-ownership](/home/dom/git/nold-ai/specfact-cli/openspec/specs/backlog-module-ownership/spec.md) +- [project-codebase-ownership](/home/dom/git/nold-ai/specfact-cli/openspec/specs/project-codebase-ownership/spec.md) +- [code-review-module](/home/dom/git/nold-ai/specfact-cli/openspec/specs/code-review-module/spec.md) +- [module-categories](/home/dom/git/nold-ai/specfact-cli/docs/reference/module-categories.md) +- active proposals under [openspec/changes](/home/dom/git/nold-ai/specfact-cli/openspec/changes/) +- planning inventory in [CHANGE_ORDER.md](/home/dom/git/nold-ai/specfact-cli/openspec/CHANGE_ORDER.md) + +## Classification Rules + +- `core`: the authoritative owned surface remains in `specfact-cli` core, usually registry, marketplace, shared models, profile/init behavior, AI integration glue, or release/governance orchestration. +- `modules`: the change's primary implementation is a user-facing workflow or bundle command surface that maps cleanly to a canonical bundle in `specfact-cli-modules`. +- `split/rescope`: the proposal currently mixes core-owned contracts or schemas with bundle-owned runtime behavior, or its command topology no longer maps cleanly to a single canonical bundle. + +## Evidence Snapshots + +- `backlog-scrum-02`, `backlog-scrum-03`, `backlog-scrum-04`, `backlog-kanban-01`, `backlog-safe-01`, and `backlog-safe-02` still describe implementation under `modules/backlog-*` in this repo, while [backlog-module-ownership](/home/dom/git/nold-ai/specfact-cli/openspec/specs/backlog-module-ownership/spec.md) makes `nold-ai/specfact-backlog` the sole owner of backlog and policy command surfaces. +- `profile-01` still describes `modules/profile/`, but [core-lean-package](/home/dom/git/nold-ai/specfact-cli/openspec/specs/core-lean-package/spec.md) limits the core wheel to `init`, `module_registry`, and `upgrade`; the profile behavior must therefore be expressed as core init/config behavior, not as a separate extracted module. +- `sync-01` still describes `modules/sync-kernel/` and `specfact sync ...`, but [module-categories](/home/dom/git/nold-ai/specfact-cli/docs/reference/module-categories.md) assigns sync ownership to the `project` category and `specfact-project` bundle. +- `validation-02` still extends `modules/validate/`, but [module-categories](/home/dom/git/nold-ai/specfact-cli/docs/reference/module-categories.md) assigns validation to the `code` category and `specfact-codebase` bundle; the evidence and governance contracts it references are not purely bundle-local. +- `requirements-02`, `architecture-01`, and `traceability-01` still define old flat command families (`specfact requirements ...`, `specfact architecture ...`, `specfact trace ...`) that do not exist in the canonical grouped command model. + +## Matrix + +### Stay In `specfact-cli` + +| Change | GitHub | Classification | Why it stays | Required rewrite before implementation | +|---|---|---:|---|---| +| `marketplace-03-publisher-identity` | `#327` | `core` | Registry publisher identity, signing, and trust remain core marketplace responsibilities. | Keep proposal focused on core registry and publisher trust surfaces. | +| `marketplace-04-revocation` | `#328` | `core` | Revocation is part of core marketplace trust and registry lifecycle. | No repo move; keep scoped to core registry behavior. | +| `marketplace-05-registry-federation` | `#329` | `core` | Federation is a marketplace/registry concern, not a bundle-owned workflow command. | No repo move; keep core registry scope explicit. | +| `profile-01-config-layering` | `#237` | `core` | Profile selection belongs to `specfact init` and core config resolution, not to a bundle. | Replace `modules/profile/` and `specfact profile ...` assumptions with core init/config behavior. | +| `profile-02-central-config-sources` | `#249` | `core` | Central baseline resolution is core config ownership. | Reframe around core config loading and profile overlays; remove implied profile bundle ownership. | +| `profile-03-domain-overlays` | `#250` | `core` | Domain overlays extend profile/config layering and shared requirement fields. | Rewrite command references so overlay behavior is expressed through core/profile-aware workflows. | +| `requirements-01-data-model` | `#238` | `core` | Shared requirements models and schema extensions are cross-bundle contracts. | Keep focused on models, schema, and extension ownership; avoid bundle command scope. | +| `integration-01-cross-change-contracts` | `#254` | `core` | Cross-change ownership and interface contracts are core governance. | Keep as authoritative contract change; add explicit references to downstream bundle owners where needed. | +| `ai-integration-01-agent-skill` | `#251` | `core` | Agent skill packaging and integration guidance are core AI surface work. | Update stale command examples to canonical grouped commands and cross-repo owners. | +| `ai-integration-02-mcp-server` | `#252` | `core` | MCP server integration is core runtime/integration infrastructure. | Clarify which bundle commands are proxied versus which schemas remain core-owned. | +| `ai-integration-03-instruction-files` | `#253` | `core` | Instruction files and repo-local agent guidance stay in the core repo. | Rewrite command examples and ownership assumptions for grouped bundle commands. | +| `ai-integration-04-intent-skills` | `#349` | `core` | Skill assets still belong with AI integration guidance in core. | Replace references to unsettled `requirements` and `architecture` command families with whichever paired follow-ups are approved. | +| `cli-val-01-behavior-contract-standard` | `#279` | `core` | CLI behavioral contract standards are release-gate and product-governance work. | Rewrite acceptance scope to cover grouped bundle commands rather than pre-split flat commands. | +| `cli-val-02-output-snapshot-stability` | `#280` | `core` | Snapshot policy is a release-quality gate across the product. | Update target commands/help output expectations to grouped command topology. | +| `cli-val-03-misuse-safety-proof` | `#281` | `core` | Misuse-safety proof is product-governance evidence, not bundle-local feature code. | Reframe command coverage to installed-bundle behavior and lean-core defaults. | +| `cli-val-04-acceptance-test-runner` | `#282` | `core` | Acceptance harness and runner policy stay in core CI/release orchestration. | Target canonical bundle install plus grouped command flows. | +| `cli-val-05-ci-integration` | `#283` | `core` | CI integration for acceptance evidence remains core release infrastructure. | Align with cross-repo test ownership and installed-bundle execution model. | +| `cli-val-06-copilot-test-generation` | `#284` | `core` | Test-generation workflow and governance belong to core AI/release tooling. | Update command targets and fixture assumptions to post-split architecture. | +| `dogfooding-01-full-chain-e2e-proof` | `#255` | `core` | End-to-end proof is a cross-repo evidence and release-governance activity. | Clarify that the proof orchestrates bundle-installed workflows rather than implementing them in core. | + +### Move To `specfact-cli-modules` + +| Change | GitHub | Classification | Target bundle | Why it moves | Required rewrite in replacement proposal | +|---|---|---:|---|---|---| +| `backlog-scrum-02-sprint-planning` | `#170` | `modules` | `specfact-backlog` | Proposal still implements `modules/backlog-scrum/...`; canonical backlog command ownership is bundle-side. | Rewrite paths and package names to modules-repo bundle layout; keep `backlog` grouped surface. | +| `backlog-scrum-03-story-complexity` | `#171` | `modules` | `specfact-backlog` | Complexity and story splitting are backlog refinement behavior in the backlog bundle. | Rewrite to modules-repo bundle layout and extension hooks. | +| `backlog-scrum-04-definition-of-done` | `#169` | `modules` | `specfact-backlog` | DoD validation is backlog/policy workflow behavior, not core. | Rewrite to modules-repo backlog bundle ownership. | +| `backlog-kanban-01-flow-metrics` | `#183` | `modules` | `specfact-backlog` | Kanban flow metrics proposal still targets `modules/backlog-kanban/...`; canonical owner is backlog bundle. | Rewrite to modules-repo bundle paths and grouped backlog command surface. | +| `backlog-safe-01-pi-planning` | `#184` | `modules` | `specfact-backlog` | PI planning and WSJF are SAFe backlog behavior owned by the backlog bundle. | Rewrite to modules-repo backlog bundle ownership. | +| `backlog-safe-02-risk-rollups` | `#182` | `modules` | `specfact-backlog` | Risk rollups are described as a shared capability inside `backlog-safe`; still bundle-owned backlog behavior. | Rewrite to modules-repo backlog bundle paths and hooks. | +| `ceremony-02-requirements-aware-output` | `#245` | `modules` | `specfact-backlog` | Extends backlog ceremony commands, which are bundle-owned backlog surfaces. | Rewrite to backlog bundle ownership and grouped backlog ceremony flows. | +| `policy-02-packs-and-modes` | `#246` | `modules` | `specfact-backlog` | Policy command surface is owned by the backlog bundle per [backlog-module-ownership](/home/dom/git/nold-ai/specfact-cli/openspec/specs/backlog-module-ownership/spec.md). | Rewrite package paths and command examples to canonical backlog/policy bundle ownership. | +| `sync-01-unified-kernel` | `#243` | `modules` | `specfact-project` | Sync is owned by the `project` category and `specfact-project` bundle. | Rewrite from old `specfact sync ...` and `modules/sync-kernel/` to canonical project-bundle command ownership. | + +### Split / Rescope Before Reassignment + +| Change | GitHub | Classification | Why it cannot move or stay as-is | Required follow-up split | +|---|---|---:|---|---| +| `requirements-02-module-commands` | `#239` | `split/rescope` | Defines a non-canonical `specfact requirements ...` command family and couples shared requirements semantics with user-facing command implementation. | Keep core-owned schema/contract deltas with `requirements-01`; create a bundle-owned replacement for the actual command surface after target bundle ownership is decided. | +| `requirements-03-backlog-sync` | `#244` | `split/rescope` | Mixes requirements lifecycle, backlog synchronization, and spec-kit bridge behavior under a non-canonical command family. | Split into core adapter/contracts plus one or more bundle-owned follow-ups for project/backlog runtime workflows. | +| `architecture-01-solution-layer` | `#240` | `split/rescope` | Defines `specfact architecture ...` as a flat command family that does not exist in the canonical grouped topology. | Keep core-owned architecture schema/extension contracts only if needed; create a bundle-owned replacement once the canonical command home is chosen. | +| `traceability-01-index-and-orphans` | `#242` | `split/rescope` | Defines `specfact trace ...`, another non-canonical flat command family, while also introducing shared index contracts. | Split core index/schema contracts from bundle-owned query/reporting command implementation. | +| `validation-02-full-chain-engine` | `#241` | `split/rescope` | Bundle-owned validation runtime (`code`/`specfact-codebase`) is mixed with cross-change evidence contracts and governance dependencies. | Keep only shared report/evidence contracts in core where necessary; move the runtime engine to a modules-repo codebase change. | +| `governance-01-evidence-output` | `#247` | `split/rescope` | Owns the evidence envelope contract, but proposal also extends bundle-owned validation runtime flags and output behavior. | Keep evidence schema and CI contract in core; create bundle follow-up(s) for validation/govern emitters. | +| `governance-02-exception-management` | `#248` | `split/rescope` | Mixes core exception semantics with user-facing exception commands and bundle-owned policy enforcement behavior. | Keep exception schema/suppression semantics in core; move command and runtime enforcement flows into bundle-owned follow-up changes. | +| `openspec-01-intent-trace` | `#350` | `split/rescope` | OpenSpec proposal metadata is core-owned, but the proposal also extends bundle-owned sync/import behavior. | Keep proposal schema and import contract metadata in core; create a project-bundle follow-up for runtime import behavior. | + +## Summary Counts + +- `core`: 18 active changes +- `modules`: 9 active changes +- `split/rescope`: 8 active changes + +## Immediate Consequences + +- The nine `modules` issues are the first candidates for transfer or close-and-recreate in `specfact-cli-modules`. +- The eight `split/rescope` issues must not be moved unchanged; each one needs a paired ownership decision before any transfer. +- Several `core` issues still require proposal rewrites because they mention obsolete module paths or flat command families, even though the issues themselves stay in `specfact-cli`. + +## Reassignment Strategy + +### Preferred path + +- Use native GitHub transfer for the nine `modules` issues because `gh issue transfer` is available for `specfact-cli` -> `specfact-cli-modules`. +- Create the target Epic and Feature parents in `specfact-cli-modules` before transferring child stories. +- After transfer, normalize labels to the target repo taxonomy and attach the transferred story under its new Feature. + +### Fallback path + +- Use `close-and-recreate` only when transfer fails technically, cannot preserve the needed planning state, or the issue is `split/rescope` and must be replaced with a narrower modules-owned follow-up. +- When fallback is used: + - close the `specfact-cli` issue with a comment linking the replacement issue + - create the modules-repo replacement with updated scope and a backlink to the original issue + - update both `CHANGE_ORDER.md` files with old/new issue references + +### Active proposals that must be rewritten for stale monolithic ownership + +- `profile-01-config-layering` +- `requirements-02-module-commands` +- `architecture-01-solution-layer` +- `traceability-01-index-and-orphans` +- `sync-01-unified-kernel` +- `validation-02-full-chain-engine` +- `backlog-scrum-02-sprint-planning` +- `backlog-scrum-03-story-complexity` +- `backlog-scrum-04-definition-of-done` +- `backlog-kanban-01-flow-metrics` +- `backlog-safe-01-pi-planning` +- `backlog-safe-02-risk-rollups` + +### `split/rescope` changes that require paired ownership follow-up + +- `requirements-02-module-commands` +- `requirements-03-backlog-sync` +- `architecture-01-solution-layer` +- `traceability-01-index-and-orphans` +- `validation-02-full-chain-engine` +- `governance-01-evidence-output` +- `governance-02-exception-management` +- `openspec-01-intent-trace` + +## Modules-Repo Target Hierarchy + +### Target Epics + +| Target repo | Epic title | Reason | +|---|---|---| +| `specfact-cli-modules` | `[Epic] specfact backlog` | Canonical parent for all backlog bundle workflow stories moved out of core. | +| `specfact-cli-modules` | `[Epic] specfact project` | Canonical parent for project-bundle sync and project orchestration stories moved out of core. | + +### Target Features + +| Target epic | Feature title | Source alignment | +|---|---|---| +| `[Epic] specfact backlog` | `[Feature] Scrum Workflows` | Mirrors core feature `#359` and groups sprint planning, complexity, and DoD. | +| `[Epic] specfact backlog` | `[Feature] Kanban Flow Metrics` | Mirrors core feature `#360`. | +| `[Epic] specfact backlog` | `[Feature] SAFe & PI Planning` | Mirrors core feature `#361` and groups PI planning plus risk rollups. | +| `[Epic] specfact backlog` | `[Feature] Policy Engine & Enforcement Modes` | Mirrors core feature `#362` for bundle-owned policy command work. | +| `[Epic] specfact backlog` | `[Feature] Ceremony Command Layer` | Mirrors core feature `#363` for bundle-owned ceremony extensions. | +| `[Epic] specfact project` | `[Feature] Sync Engine` | Mirrors core feature `#369` for project-bundle sync ownership. | + +### Story Mapping + +| Current issue | Change | Target epic | Target feature | Transfer decision | +|---|---|---|---|---| +| `#169` | `backlog-scrum-04-definition-of-done` | `[Epic] specfact backlog` | `[Feature] Scrum Workflows` | `transfer` | +| `#170` | `backlog-scrum-02-sprint-planning` | `[Epic] specfact backlog` | `[Feature] Scrum Workflows` | `transfer` | +| `#171` | `backlog-scrum-03-story-complexity` | `[Epic] specfact backlog` | `[Feature] Scrum Workflows` | `transfer` | +| `#183` | `backlog-kanban-01-flow-metrics` | `[Epic] specfact backlog` | `[Feature] Kanban Flow Metrics` | `transfer` | +| `#184` | `backlog-safe-01-pi-planning` | `[Epic] specfact backlog` | `[Feature] SAFe & PI Planning` | `transfer` | +| `#182` | `backlog-safe-02-risk-rollups` | `[Epic] specfact backlog` | `[Feature] SAFe & PI Planning` | `transfer` | +| `#246` | `policy-02-packs-and-modes` | `[Epic] specfact backlog` | `[Feature] Policy Engine & Enforcement Modes` | `transfer` | +| `#245` | `ceremony-02-requirements-aware-output` | `[Epic] specfact backlog` | `[Feature] Ceremony Command Layer` | `transfer` | +| `#243` | `sync-01-unified-kernel` | `[Epic] specfact project` | `[Feature] Sync Engine` | `transfer` | + +### Order of Operations + +1. Create `Epic` and `Feature` labels in `specfact-cli-modules`. +2. Create target epics. +3. Create target features and attach them to the correct epic. +4. Transfer the nine module-owned stories. +5. Normalize story labels in `specfact-cli-modules` and attach each story to its target feature. + +## Final Verification Snapshot + +- `openspec validate cross-repo-issue-realignment --strict` passed on `2026-04-08`. +- All nine `modules`-classified stories now have exactly one authoritative issue in `nold-ai/specfact-cli-modules`: + - `#169 -> modules#152` + - `#170 -> modules#160` + - `#171 -> modules#153` + - `#182 -> modules#156` + - `#183 -> modules#155` + - `#184 -> modules#154` + - `#243 -> modules#157` + - `#245 -> modules#159` + - `#246 -> modules#158` +- The transferred story numbers no longer appear in the active `specfact-cli` issue inventory. +- Modules-repo hierarchy is aligned: + - `modules#145` -> `modules#151`, `modules#149`, `modules#146`, `modules#148`, `modules#150` + - `modules#144` -> `modules#147`, `modules#161` + - `modules#162` -> `modules#163` +- OpenSpec artifact ownership is aligned with issue ownership: + - moved runtime changes now live only in `specfact-cli-modules` + - split changes now exist in both repos as paired core-contract and modules-runtime companions +- Core and modules planning inventories were updated in their respective `openspec/CHANGE_ORDER.md` files. +- Core architecture docs were updated so they no longer imply that old flat `architecture`, `requirements`, or `trace` command families remain canonical implementation targets. diff --git a/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/design.md b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/design.md new file mode 100644 index 00000000..3367aa71 --- /dev/null +++ b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/design.md @@ -0,0 +1,105 @@ +## Context + +`specfact-cli` now operates as a lean core with bundle-owned workflow behavior implemented in `specfact-cli-modules`, but a large set of active OpenSpec changes and GitHub issues still reflect the pre-split monolithic layout. The drift is visible in three places: + +- active proposals still describe `modules//...` implementation inside the core repo for bundle-owned backlog, ceremony, and similar workflow features +- GitHub issues for bundle-owned work are still open in `nold-ai/specfact-cli`, even though their canonical implementation surface belongs in `nold-ai/specfact-cli-modules` +- `specfact-cli` has a cleaned Epic -> Feature -> User Story hierarchy, while `specfact-cli-modules` does not yet have an equivalent planning hierarchy for module-owned work + +This change is cross-cutting because it affects active OpenSpec artifacts, both repositories' issue trackers, and planning metadata such as `CHANGE_ORDER.md`. + +## Goals / Non-Goals + +**Goals:** + +- define one repeatable classification workflow for active changes and linked GitHub issues: keep in core, move to modules, or split/rescope +- define the required proposal updates for changes that still refer to obsolete monolithic structure +- define the operational rule for GitHub issue reassignment between repos +- define how planning inventories and parent hierarchy must be updated in both repos when ownership changes +- define the required Epic and Feature creation work in `specfact-cli-modules` before module-owned user stories are reassigned + +**Non-Goals:** + +- implement the actual issue transfers, closes, or recreation in this change +- create the `specfact-cli-modules` project board itself +- implement any product behavior from the reclassified changes +- redesign the canonical five-bundle taxonomy already established by module migration + +## Decisions + +### Decision: Canonical ownership comes from archived core-vs-bundle specs, not from active proposals + +Use the archived and canonical ownership documents as the source of truth for assignment decisions: + +- `core-lean-package` +- `module-categories` +- `bundle-extraction` +- `backlog-module-ownership` +- `project-codebase-ownership` +- `code-review-module` + +Rationale: active proposals are precisely what drifted. Classification must be based on the post-migration architecture rather than on stale proposal language. + +Alternative considered: trust the active proposal’s current repo and path references. +Rejected because that would preserve obsolete ownership and keep planning drift unresolved. + +### Decision: Reassignment is a two-step decision, not a blanket move + +For each affected GitHub issue: + +1. classify the capability as `core`, `modules`, or `split/rescope` +2. if `modules`, decide `transfer-existing-issue` or `close-and-recreate` + +`transfer-existing-issue` is preferred when GitHub supports moving the issue between these repositories with acceptable metadata preservation for the specific issue type and workflow. `close-and-recreate` is required when transfer support is unavailable, restricted, or would break planning clarity. + +Rationale: this preserves history when possible, but avoids blocking the cleanup on a platform limitation. + +Alternative considered: always recreate. +Rejected because it discards useful history and adds unnecessary churn when native transfer is viable. + +### Decision: Parent hierarchy must exist in the target repo before user stories are reassigned + +Module-owned user stories must not be moved into `specfact-cli-modules` as flat orphan issues. The target repo needs its own aligned Epic -> Feature -> User Story hierarchy first, with Features created before story reassignment. + +Rationale: reassignment without parent structure would recreate the same planning problem already fixed in `specfact-cli`. + +Alternative considered: move user stories first and normalize hierarchy later. +Rejected because it produces an intermediate state that is hard to audit and easy to forget. + +### Decision: Rescope stale proposals in place before implementation resumes + +Changes that remain in `specfact-cli` but still describe the old monolithic package layout must be updated in place so their proposal, design, and tasks reflect current architecture. Changes classified as module-owned must either be retired from the core repo after replacement tracking is established, or reduced to core-owned contract/integration deltas only. + +Rationale: implementation against stale proposals would produce incorrect code ownership even if issue tracking were fixed. + +Alternative considered: postpone proposal cleanup until implementation starts. +Rejected because the stale proposal is itself the thing currently driving incorrect planning and ownership assumptions. + +## Risks / Trade-offs + +- [Issue-transfer support differs from expectation] -> Mitigation: encode `transfer` as preferred but require a documented recreate fallback per issue. +- [A change mixes core contracts and module behavior] -> Mitigation: allow `split/rescope` classification instead of forcing a single repo. +- [Modules repo hierarchy diverges from core hierarchy naming] -> Mitigation: require explicit mapping from moved user stories to target Epic and Feature, not just title similarity. +- [CHANGE_ORDER updates become asymmetric across repos] -> Mitigation: require paired updates in `specfact-cli` and the target planning inventory in `specfact-cli-modules`. +- [Users interpret old issue numbers as the active source of truth after recreation] -> Mitigation: require cross-links both ways and closure comments that name the replacement issue. + +## Migration Plan + +1. Inventory active changes and linked GitHub issues in `specfact-cli`. +2. Classify each as `core`, `modules`, or `split/rescope` using the canonical ownership specs. +3. For each `modules` item, define the target bundle/domain and the target Epic/Feature in `specfact-cli-modules`. +4. Create any missing Epic and Feature parents in `specfact-cli-modules`. +5. Reassign each module-owned issue by transfer when supported, otherwise close and recreate with updated scope and cross-links. +6. Update `CHANGE_ORDER.md` in `specfact-cli` and the matching planning inventory in `specfact-cli-modules`. +7. Update the affected active proposals so their repo assignment and implementation paths reflect the final decision. + +Rollback strategy: + +- if reassignment starts but target hierarchy is incomplete, stop before changing child issue ownership +- if a transfer path proves unusable, fall back to close-and-recreate while preserving the old issue as a historical pointer + +## Open Questions + +- Which file in `specfact-cli-modules` will serve as the canonical equivalent of `CHANGE_ORDER.md` for this cleanup? +- Which active changes should be split into paired core-plus-modules changes instead of being wholly reassigned? +- Should non-backlog bundle families beyond `specfact-backlog` and `specfact-code-review` gain explicit Epic/Feature hierarchy immediately, or only the currently affected module-owned work? diff --git a/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/proposal.md b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/proposal.md new file mode 100644 index 00000000..e748a524 --- /dev/null +++ b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/proposal.md @@ -0,0 +1,33 @@ +## Why + +Active OpenSpec changes and linked GitHub issues still mix the old monolithic `specfact-cli` structure with the current lean-core plus `specfact-cli-modules` ownership model. That drift now blocks planning: some module-owned backlog, ceremony, and code-review work is still tracked in the core repo, while several active proposals describe obsolete in-repo module layouts and do not map cleanly to the canonical bundle boundaries. + +## GitHub Tracking + +- GitHub issue: [#484](https://github.com/nold-ai/specfact-cli/issues/484) +- Parent Feature: [#486](https://github.com/nold-ai/specfact-cli/issues/486) +- Parent Epic: [#485](https://github.com/nold-ai/specfact-cli/issues/485) + +## What Changes + +- Define a single decision framework for classifying active OpenSpec changes and linked GitHub issues as `core`, `modules`, or `split/rescope`. +- Require every affected active proposal in `specfact-cli` to be updated with the steps needed to fit the current architecture and repo assignment. +- Define the operational rule for handling GitHub issues that no longer belong in `specfact-cli`: either move the existing issue to `specfact-cli-modules` when the platform supports it, or close the old issue and create a replacement issue in `specfact-cli-modules` with updated scope and cross-links. +- Define how `openspec/CHANGE_ORDER.md` in `specfact-cli` and the corresponding planning inventory in `specfact-cli-modules` must be updated when ownership changes. +- Define the required Epic -> Feature -> User Story hierarchy to create in `specfact-cli-modules` so module-owned changes have the same planning structure now present in `specfact-cli`. +- Require a reconciled mapping from active core-repo user stories/change proposals to modules-repo epics/features when their implementation ownership is bundle-side. + +## Capabilities + +### New Capabilities +- `cross-repo-backlog-alignment`: Governance rules for assigning active changes and GitHub issues to the correct repository, reconciling issue migration or recreation, and maintaining aligned Epic -> Feature -> User Story planning hierarchies across `specfact-cli` and `specfact-cli-modules`. + +### Modified Capabilities +- `backlog-module-ownership`: Active backlog and ceremony changes must align their repository ownership, issue tracking, and proposal scope with the canonical `specfact-backlog` bundle boundary. +- `project-codebase-ownership`: Active changes that describe outdated module/package ownership must be reconciled to the canonical post-migration core-versus-bundle split before implementation proceeds. + +## Impact + +- Affected systems: `openspec/changes/*` active proposals/tasks/designs, `openspec/CHANGE_ORDER.md`, GitHub issues in `nold-ai/specfact-cli`, and the corresponding issue/planning inventory in `nold-ai/specfact-cli-modules`. +- Operational impact: maintainers get an explicit move-vs-recreate workflow for issue reassignment and a required hierarchy creation plan for the modules repo. +- Cross-repo coordination: this change depends on inspecting both repositories together and documenting the resulting ownership mapping before further implementation work continues on stale proposals. diff --git a/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/specs/backlog-module-ownership/spec.md b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/specs/backlog-module-ownership/spec.md new file mode 100644 index 00000000..adbbcf18 --- /dev/null +++ b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/specs/backlog-module-ownership/spec.md @@ -0,0 +1,20 @@ +## MODIFIED Requirements + +### Requirement: Backlog Feature Commands Must Be Module-Owned + +The system SHALL treat `nold-ai/specfact-backlog` as the sole owner of user-facing backlog and policy command surfaces, including the active proposal backlog and GitHub planning artifacts that track future backlog and ceremony feature work. + +#### Scenario: Core does not directly own backlog feature commands +- **WHEN** command registration is resolved in `specfact-cli` +- **THEN** user-facing backlog feature commands are provided by the installed backlog module +- **AND** core does not ship a parallel built-in backlog command surface for the same feature commands. + +#### Scenario: Core keeps only shared backlog framework contracts +- **WHEN** backlog ownership is resolved after migration +- **THEN** core retains only shared provider integrations, generic data models, and minimal backlog contracts reused outside the backlog bundle +- **AND** backlog-only command implementations, prompt resources, templates, and refinement helpers are not owned by core. + +#### Scenario: Active backlog proposals are not tracked as core-owned implementation work +- **WHEN** a pending OpenSpec change or linked GitHub issue describes backlog, scrum, kanban, safe, ceremony, or policy command behavior that belongs to `specfact-backlog` +- **THEN** that work is assigned to the modules repo planning hierarchy rather than remaining a core-repo implementation story +- **AND** the core repo retains only the shared contracts or bridge points, if any, that support the owning bundle. diff --git a/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/specs/cross-repo-backlog-alignment/spec.md b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/specs/cross-repo-backlog-alignment/spec.md new file mode 100644 index 00000000..27e8de79 --- /dev/null +++ b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/specs/cross-repo-backlog-alignment/spec.md @@ -0,0 +1,47 @@ +## ADDED Requirements + +### Requirement: Active Change Ownership Must Be Classified Against The Canonical Repo Split +The system SHALL classify every active OpenSpec change and linked GitHub user story in `specfact-cli` against the canonical post-migration ownership model before further implementation work proceeds. + +#### Scenario: Active change is classified as core, modules, or split +- **WHEN** maintainers review active changes that still reference the pre-split monolithic structure +- **THEN** each change is assigned one of: `core`, `modules`, or `split/rescope` +- **AND** the decision is based on the canonical ownership specs rather than on stale proposal paths or legacy issue location. + +### Requirement: Module-Owned Issues Must Use A Defined Reassignment Path +The system SHALL define a deterministic path for any GitHub issue that belongs in `specfact-cli-modules` instead of `specfact-cli`. + +#### Scenario: Native issue transfer is available and accepted +- **WHEN** a module-owned issue can be moved between the two repositories with acceptable metadata preservation +- **THEN** the issue is transferred to `nold-ai/specfact-cli-modules` +- **AND** the related OpenSpec artifacts and planning inventory are updated to reference the transferred issue in its new repository. + +#### Scenario: Native issue transfer is unavailable or unsuitable +- **WHEN** a module-owned issue cannot be moved cleanly between repositories +- **THEN** the source issue in `specfact-cli` is closed with a comment pointing to the replacement issue in `specfact-cli-modules` +- **AND** a replacement issue is created in `specfact-cli-modules` with updated scope aligned to the current architecture +- **AND** the old and new issues cross-reference each other so planning history remains auditable. + +### Requirement: Target Hierarchy Must Exist Before Module-Owned Stories Are Reassigned +The system SHALL establish the necessary Epic and Feature parents in `specfact-cli-modules` before module-owned user stories are transferred or recreated there. + +#### Scenario: Module-owned user story is prepared for reassignment +- **WHEN** a user story is classified as module-owned +- **THEN** the target repository already has the Epic and Feature hierarchy needed to parent that story +- **AND** the reassigned story is linked under the target Feature rather than being left as a flat issue. + +### Requirement: Planning Inventories Must Be Updated In Both Repositories +The system SHALL keep planning metadata aligned across repositories when change ownership or GitHub issue ownership changes. + +#### Scenario: Change ownership is reassigned to modules repo +- **WHEN** a change or linked issue moves from `specfact-cli` planning to `specfact-cli-modules` +- **THEN** `openspec/CHANGE_ORDER.md` in `specfact-cli` is updated to remove or annotate the old core-repo ownership +- **AND** the corresponding planning inventory in `specfact-cli-modules` is updated with the new issue, Epic, Feature, and dependency references. + +### Requirement: Rescoped Proposals Must State The Current Architecture And Repo Assignment +The system SHALL update affected active proposals before implementation resumes so they no longer describe obsolete monolithic paths or incorrect repository ownership. + +#### Scenario: Active proposal still references in-repo module implementation +- **WHEN** an active proposal describes implementation under `modules//` in `specfact-cli` for a module-owned capability +- **THEN** the proposal is updated to either reflect its true core-only scope or to point to the owning implementation work in `specfact-cli-modules` +- **AND** the proposal no longer implies that bundle-owned behavior will be implemented in the core repo. diff --git a/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/specs/project-codebase-ownership/spec.md b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/specs/project-codebase-ownership/spec.md new file mode 100644 index 00000000..f621f666 --- /dev/null +++ b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/specs/project-codebase-ownership/spec.md @@ -0,0 +1,17 @@ +## MODIFIED Requirements + +### Requirement: Pending Changes Must Align With The Ownership Decision + +Pending OpenSpec changes that touch command surface, docs, prompts, migration cleanup, or issue planning SHALL align with the canonical post-migration ownership model instead of reintroducing monolithic `specfact-cli` module ownership by implication. + +#### Scenario: Active change does not finalize conflicting import ownership +- **GIVEN** an active pending change updates grouped command paths or release-facing docs +- **WHEN** that change references brownfield import ownership +- **THEN** it references the canonical owner defined by this change +- **AND** it does not re-establish a conflicting public command path or subsystem owner by implication. + +#### Scenario: Active proposal does not preserve obsolete in-repo module paths +- **GIVEN** an active proposal still describes implementation under `modules//` in `specfact-cli` for a capability now owned by a bundle in `specfact-cli-modules` +- **WHEN** maintainers reconcile the proposal against the current architecture +- **THEN** the proposal is updated to the correct repository and bundle ownership model +- **AND** any remaining core-repo scope is reduced to the shared runtime, contract, or integration surface that core still owns. diff --git a/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/tasks.md b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/tasks.md new file mode 100644 index 00000000..b4df6929 --- /dev/null +++ b/openspec/changes/archive/2026-04-08-cross-repo-issue-realignment/tasks.md @@ -0,0 +1,49 @@ +## 1. Inventory And Classification + +- [ ] 1.1 Create a dedicated worktree branch for this change before applying repository edits. +- [x] 1.2 Inventory all active `specfact-cli` OpenSpec changes and linked GitHub issues that still describe pre-split monolithic ownership. +- [x] 1.3 Classify each inventoried change as `core`, `modules`, or `split/rescope` using the canonical ownership specs and current `CHANGE_ORDER.md`. +- [x] 1.4 Record the classification matrix in a change-local analysis artifact so later edits are traceable. + +## 2. Decide Reassignment Strategy + +- [x] 2.1 For every `modules`-classified issue, decide whether to use native GitHub transfer or close-and-recreate in `specfact-cli-modules`. +- [x] 2.2 Define the required replacement-linking and closure-comment format for any close-and-recreate path. +- [x] 2.3 Identify every active proposal that must be rewritten to remove obsolete `modules//` core-repo implementation paths. +- [x] 2.4 Identify every `split/rescope` change that needs paired core and modules follow-up ownership instead of a single-repo implementation. + +## 3. Plan Modules-Repo Hierarchy + +- [x] 3.1 Map every module-owned user story to its target modules-repo domain, Epic, and Feature parent. +- [x] 3.2 Determine which Epics already exist in `specfact-cli-modules` and which new Epics must be created. +- [x] 3.3 Determine which Features must be created in `specfact-cli-modules` to parent the moved or recreated user stories. +- [x] 3.4 Define the order of operations so target Epic and Feature parents are created before any child story is reassigned. + +## 4. Update Core-Repo Planning Artifacts + +- [x] 4.1 Update `openspec/CHANGE_ORDER.md` in `specfact-cli` to annotate which active changes remain core-owned, which move to modules repo, and which are split/rescoped. +- [x] 4.2 Update each affected active proposal in `specfact-cli` so its scope and implementation location match the current architecture decision. +- [x] 4.3 Where a core-repo proposal is no longer the implementation owner, reduce it to retained core contract or integration scope, or mark it for paired modules-repo follow-up. +- [x] 4.4 Add explicit cross-references from the affected core-repo changes to their target modules-repo issues or replacement changes. + +## 5. Apply Modules-Repo Issue And Hierarchy Changes + +- [x] 5.1 Create the required Epics in `specfact-cli-modules` for the module-owned work that is currently tracked only in `specfact-cli`. +- [x] 5.2 Create the required Feature issues in `specfact-cli-modules` under those Epics. +- [x] 5.3 Reassign each module-owned user story by transfer when supported; otherwise close the `specfact-cli` issue and create the replacement issue in `specfact-cli-modules`. +- [x] 5.4 Link every moved or recreated user story under its target Feature and ensure each Feature is linked to the correct Epic. +- [x] 5.5 Add all created or reassigned modules-repo issues to the new `specfact-cli-modules` GitHub project once it exists. + +## 6. Align Modules-Repo Planning Inventory + +- [x] 6.1 Update the planning inventory in `specfact-cli-modules` so it reflects the new Epics, Features, moved/recreated user stories, and dependency links. +- [x] 6.2 Ensure the modules-repo planning inventory cross-references the original `specfact-cli` issue numbers where historical continuity matters. +- [x] 6.3 Verify that module-owned backlog and ceremony changes no longer remain listed as active implementation work in the core-repo planning flow. + +## 7. Validate And Close Out + +- [x] 7.1 Validate that every affected active change now has an explicit ownership decision and correct repository assignment. +- [x] 7.2 Validate that every module-owned issue has exactly one authoritative issue in `specfact-cli-modules` and no ambiguous active duplicate in `specfact-cli`. +- [x] 7.3 Validate that both repositories' planning inventories and issue hierarchies agree on Epic -> Feature -> User Story relationships. +- [x] 7.4 Run `openspec validate cross-repo-issue-realignment --strict` and capture the result. +- [x] 7.5 Update any affected docs or contributor guidance that still imply monolithic ownership for module-implemented work. diff --git a/openspec/changes/backlog-auth-01-backlog-auth-commands/.openspec.yaml b/openspec/changes/backlog-auth-01-backlog-auth-commands/.openspec.yaml deleted file mode 100644 index 8f0b8699..00000000 --- a/openspec/changes/backlog-auth-01-backlog-auth-commands/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -schema: spec-driven -created: 2026-03-05 diff --git a/openspec/changes/backlog-auth-01-backlog-auth-commands/CHANGE_VALIDATION.md b/openspec/changes/backlog-auth-01-backlog-auth-commands/CHANGE_VALIDATION.md deleted file mode 100644 index f7814192..00000000 --- a/openspec/changes/backlog-auth-01-backlog-auth-commands/CHANGE_VALIDATION.md +++ /dev/null @@ -1,16 +0,0 @@ -# Change Validation: backlog-auth-01-backlog-auth-commands - -- **Validated on (UTC):** 2026-03-22T22:28:26+00:00 -- **Workflow:** /wf-validate-change (repair of pre-existing invalid proposal) -- **Strict command:** `openspec validate backlog-auth-01-backlog-auth-commands --strict` -- **Result:** PASS - -## Scope Summary - -- **Primary capability:** `backlog-auth-commands` -- **Repair:** added the missing spec delta required for a valid spec-driven change - -## Validation Outcome - -- Required change artifacts now include a parseable `specs/` delta. -- Strict OpenSpec validation passes after the repair. diff --git a/openspec/changes/backlog-auth-01-backlog-auth-commands/proposal.md b/openspec/changes/backlog-auth-01-backlog-auth-commands/proposal.md deleted file mode 100644 index 722d42d1..00000000 --- a/openspec/changes/backlog-auth-01-backlog-auth-commands/proposal.md +++ /dev/null @@ -1,30 +0,0 @@ -# Change: Backlog auth commands (specfact backlog auth) - -## Why - - -Module-migration-03 removes the auth module from core and keeps only a central auth interface (token storage by provider_id). Auth for DevOps providers (GitHub, Azure DevOps) belongs with the backlog domain: users who install the backlog bundle need `specfact backlog auth azure-devops` and `specfact backlog auth github`, not a global `specfact auth`. This change implements those commands in the specfact-cli-modules backlog bundle so that after migration-03, backlog users get auth under `specfact backlog auth`. - -## What Changes - - -- **specfact-cli-modules (backlog bundle)**: Add a `backlog auth` subgroup to the backlog Typer app with subcommands: - - `specfact backlog auth azure-devops` (options: `--pat`, `--use-device-code`; same behaviour as former `specfact auth azure-devops`) - - `specfact backlog auth github` (device code flow; same as former `specfact auth github`) - - `specfact backlog auth status` — show stored tokens for github / azure-devops - - `specfact backlog auth clear` — clear stored tokens (optionally by provider) -- **Implementation**: Auth command implementations use the **central auth interface** from specfact-cli core (`specfact_cli.utils.auth_tokens`: `get_token`, `set_token`, `clear_token`, `clear_all_tokens`) to store and retrieve tokens. No duplicate token storage logic; the backlog bundle depends on specfact-cli and calls the same interface that adapters (GitHub, Azure DevOps) in the bundle use. -- **specfact-cli**: No code changes in this repo; migration-03 already provides the central auth interface and removes the auth module. - -## Capabilities -- `backlog-auth-commands`: When the specfact-backlog bundle is installed, the CLI exposes `specfact backlog auth` with subcommands azure-devops, github, status, clear. Each subcommand uses the core auth interface for persistence. Existing tokens stored by a previous `specfact auth` (pre–migration-03) continue to work because the storage path and provider_ids are unchanged. - ---- - -## Source Tracking - - -- **GitHub Issue**: #340 -- **Issue URL**: -- **Last Synced Status**: proposed -- **Sanitized**: false diff --git a/openspec/changes/backlog-auth-01-backlog-auth-commands/specs/backlog-auth-commands/spec.md b/openspec/changes/backlog-auth-01-backlog-auth-commands/specs/backlog-auth-commands/spec.md deleted file mode 100644 index 35a1812b..00000000 --- a/openspec/changes/backlog-auth-01-backlog-auth-commands/specs/backlog-auth-commands/spec.md +++ /dev/null @@ -1,16 +0,0 @@ -## ADDED Requirements - -### Requirement: Backlog Auth Commands -When the backlog bundle is installed, the CLI SHALL expose `specfact backlog auth` commands that reuse the central SpecFact auth-token interface rather than duplicating provider token storage logic. - -#### Scenario: Provider auth commands reuse the shared token store -- **GIVEN** the backlog bundle provides `specfact backlog auth azure-devops` and `specfact backlog auth github` -- **WHEN** a user authenticates through one of those commands -- **THEN** the command stores and retrieves credentials through the shared `specfact_cli.utils.auth_tokens` interface -- **AND** provider identifiers remain compatible with existing stored tokens - -#### Scenario: Status and clear commands reflect shared token state -- **GIVEN** auth tokens exist or have been cleared for supported backlog providers -- **WHEN** `specfact backlog auth status` or `specfact backlog auth clear` is executed -- **THEN** the command reports or clears the shared token state for the requested provider set -- **AND** no backlog-specific duplicate token store is introduced diff --git a/openspec/changes/backlog-auth-01-backlog-auth-commands/tasks.md b/openspec/changes/backlog-auth-01-backlog-auth-commands/tasks.md deleted file mode 100644 index 3d60a89f..00000000 --- a/openspec/changes/backlog-auth-01-backlog-auth-commands/tasks.md +++ /dev/null @@ -1,38 +0,0 @@ -# Implementation Tasks: backlog-auth-01-backlog-auth-commands - -## Blocked by - -- module-migration-03-core-slimming must be merged (or at least the central auth interface and removal of auth from core must be done) so that: - - Core exposes `specfact_cli.utils.auth_tokens` (or a thin facade) with get_token, set_token, clear_token, clear_all_tokens. - - No `specfact auth` in core. - -## 1. Branch and repo setup - -- [ ] 1.1 In specfact-cli-modules (or the repo that hosts the backlog bundle), create a feature branch from the branch that has the post–migration-03 backlog bundle layout. -- [ ] 1.2 Ensure the backlog bundle depends on specfact-cli (so it can import `specfact_cli.utils.auth_tokens`). - -## 2. Add backlog auth command group - -- [ ] 2.1 In the backlog bundle's Typer app, add a subgroup: `auth_app = typer.Typer()` and register it as `backlog_app.add_typer(auth_app, name="auth")`. -- [ ] 2.2 Implement `specfact backlog auth azure-devops`: same behaviour as the former `specfact auth azure-devops` (PAT store, device code, interactive browser). Use `specfact_cli.utils.auth_tokens` for set_token/get_token. -- [ ] 2.3 Implement `specfact backlog auth github`: device code flow; use auth_tokens for storage. -- [ ] 2.4 Implement `specfact backlog auth status`: list stored providers (e.g. github, azure-devops) and show presence/expiry from get_token. -- [ ] 2.5 Implement `specfact backlog auth clear`: clear_token(provider) or clear_all_tokens(); support `--provider` to clear one. -- [ ] 2.6 Add `@beartype` and `@icontract` where appropriate on public entrypoints. -- [ ] 2.7 Re-use or adapt existing adapters (GitHub, Azure DevOps) in the bundle so they continue to call `get_token("github")` / `get_token("azure-devops")` from specfact_cli.utils.auth_tokens. - -## 3. Tests - -- [ ] 3.1 Unit tests: auth commands call auth_tokens (mock auth_tokens); assert set_token/get_token/clear_token invoked with correct provider ids. -- [ ] 3.2 Integration test: with real specfact-cli and backlog bundle installed, `specfact backlog auth status` shows empty or existing tokens; `specfact backlog auth azure-devops --pat test-token` then status shows azure-devops. - -## 4. Documentation and release - -- [ ] 4.1 Update specfact-cli `docs/reference/authentication.md` (or equivalent) to document `specfact backlog auth` as the canonical auth commands when the backlog bundle is installed. Remove or redirect references to `specfact auth`. -- [ ] 4.2 Changelog (specfact-cli-modules or specfact-cli): Added — auth commands under `specfact backlog auth` (azure-devops, github, status, clear) in the backlog bundle. -- [ ] 4.3 Bump backlog bundle version and re-sign manifest if required by project policy. - -## 5. PR and merge - -- [ ] 5.1 Open PR to the appropriate branch (e.g. dev) in specfact-cli-modules. -- [ ] 5.2 After merge, ensure marketplace/registry entry for specfact-backlog is updated so new installs get the auth commands. diff --git a/openspec/changes/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md b/openspec/changes/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md deleted file mode 100644 index c0dda698..00000000 --- a/openspec/changes/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md +++ /dev/null @@ -1,59 +0,0 @@ -# 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 deleted file mode 100644 index a91c223d..00000000 --- a/openspec/changes/backlog-kanban-01-flow-metrics/proposal.md +++ /dev/null @@ -1,93 +0,0 @@ -# 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. - -## 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 - - -- **GitHub Issue**: #183 -- **Issue URL**: -- **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 deleted file mode 100644 index cbe0ce25..00000000 --- a/openspec/changes/backlog-kanban-01-flow-metrics/specs/kanban-flow/spec.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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 deleted file mode 100644 index 4d003293..00000000 --- a/openspec/changes/backlog-kanban-01-flow-metrics/tasks.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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 deleted file mode 100644 index 9836b7b7..00000000 --- a/openspec/changes/backlog-safe-01-pi-planning/CHANGE_VALIDATION.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 deleted file mode 100644 index b7d59382..00000000 --- a/openspec/changes/backlog-safe-01-pi-planning/proposal.md +++ /dev/null @@ -1,91 +0,0 @@ -# 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. - -## 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 - - -- **GitHub Issue**: #184 -- **Issue URL**: -- **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 deleted file mode 100644 index 5ad61794..00000000 --- a/openspec/changes/backlog-safe-01-pi-planning/specs/safe-pi/spec.md +++ /dev/null @@ -1,65 +0,0 @@ -# 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 deleted file mode 100644 index 2d71e9e4..00000000 --- a/openspec/changes/backlog-safe-01-pi-planning/tasks.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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 deleted file mode 100644 index 59f1ea0e..00000000 --- a/openspec/changes/backlog-safe-02-risk-rollups/CHANGE_VALIDATION.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 deleted file mode 100644 index a0957d2a..00000000 --- a/openspec/changes/backlog-safe-02-risk-rollups/proposal.md +++ /dev/null @@ -1,67 +0,0 @@ -# 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. - -## 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 - - -- **GitHub Issue**: #182 -- **Issue URL**: -- **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 deleted file mode 100644 index b63c8f07..00000000 --- a/openspec/changes/backlog-safe-02-risk-rollups/specs/risk-rollups/spec.md +++ /dev/null @@ -1,77 +0,0 @@ -# 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 deleted file mode 100644 index 3555062d..00000000 --- a/openspec/changes/backlog-safe-02-risk-rollups/tasks.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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 deleted file mode 100644 index 7160a42b..00000000 --- a/openspec/changes/backlog-scrum-02-sprint-planning/CHANGE_VALIDATION.md +++ /dev/null @@ -1,41 +0,0 @@ -# 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 deleted file mode 100644 index a68b4448..00000000 --- a/openspec/changes/backlog-scrum-02-sprint-planning/design.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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 deleted file mode 100644 index 19823dc8..00000000 --- a/openspec/changes/backlog-scrum-02-sprint-planning/proposal.md +++ /dev/null @@ -1,57 +0,0 @@ -# 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). - -## 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 - - -- **GitHub Issue**: #170 -- **Issue URL**: -- **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 deleted file mode 100644 index 8c97082a..00000000 --- a/openspec/changes/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md +++ /dev/null @@ -1,95 +0,0 @@ -# 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 deleted file mode 100644 index adf8e921..00000000 --- a/openspec/changes/backlog-scrum-02-sprint-planning/tasks.md +++ /dev/null @@ -1,73 +0,0 @@ -# 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 deleted file mode 100644 index 2428c9a7..00000000 --- a/openspec/changes/backlog-scrum-03-story-complexity/CHANGE_VALIDATION.md +++ /dev/null @@ -1,40 +0,0 @@ -# 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 deleted file mode 100644 index 384e831a..00000000 --- a/openspec/changes/backlog-scrum-03-story-complexity/design.md +++ /dev/null @@ -1,33 +0,0 @@ -# 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 deleted file mode 100644 index ba5871be..00000000 --- a/openspec/changes/backlog-scrum-03-story-complexity/proposal.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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. - -## 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 - - -- **GitHub Issue**: #171 -- **Issue URL**: -- **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 deleted file mode 100644 index 18c07a9a..00000000 --- a/openspec/changes/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md +++ /dev/null @@ -1,115 +0,0 @@ -# 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 deleted file mode 100644 index a50e8527..00000000 --- a/openspec/changes/backlog-scrum-03-story-complexity/tasks.md +++ /dev/null @@ -1,71 +0,0 @@ -# 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 deleted file mode 100644 index f87cb330..00000000 --- a/openspec/changes/backlog-scrum-04-definition-of-done/CHANGE_VALIDATION.md +++ /dev/null @@ -1,87 +0,0 @@ -# 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 deleted file mode 100644 index 2d16a0ac..00000000 --- a/openspec/changes/backlog-scrum-04-definition-of-done/design.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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 deleted file mode 100644 index 00f1b24d..00000000 --- a/openspec/changes/backlog-scrum-04-definition-of-done/proposal.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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. - -## 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 - - -- **GitHub Issue**: #169 -- **Issue URL**: -- **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 deleted file mode 100644 index a196681b..00000000 --- a/openspec/changes/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md +++ /dev/null @@ -1,71 +0,0 @@ -# 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 deleted file mode 100644 index dbf32a3e..00000000 --- a/openspec/changes/backlog-scrum-04-definition-of-done/tasks.md +++ /dev/null @@ -1,73 +0,0 @@ -# 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/CHANGE_VALIDATION.md b/openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md deleted file mode 100644 index d5dac549..00000000 --- a/openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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 deleted file mode 100644 index 199658da..00000000 --- a/openspec/changes/ceremony-02-requirements-aware-output/design.md +++ /dev/null @@ -1,40 +0,0 @@ -## 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 deleted file mode 100644 index d9da0450..00000000 --- a/openspec/changes/ceremony-02-requirements-aware-output/proposal.md +++ /dev/null @@ -1,51 +0,0 @@ -# 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. - -## 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 - - -- **GitHub Issue**: #245 -- **Issue URL**: -- **Last Synced Status**: proposed -- **Sanitized**: false - \ No newline at end of file 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 deleted file mode 100644 index 16145c9e..00000000 --- a/openspec/changes/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md +++ /dev/null @@ -1,10 +0,0 @@ -## 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 deleted file mode 100644 index 75eb41d4..00000000 --- a/openspec/changes/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md +++ /dev/null @@ -1,16 +0,0 @@ -## 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 deleted file mode 100644 index bc8c566f..00000000 --- a/openspec/changes/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md +++ /dev/null @@ -1,10 +0,0 @@ -## 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 deleted file mode 100644 index e2cc6a85..00000000 --- a/openspec/changes/ceremony-02-requirements-aware-output/tasks.md +++ /dev/null @@ -1,30 +0,0 @@ -# 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/proposal.md b/openspec/changes/governance-01-evidence-output/proposal.md index 6a9c6e20..cac85bb5 100644 --- a/openspec/changes/governance-01-evidence-output/proposal.md +++ b/openspec/changes/governance-01-evidence-output/proposal.md @@ -7,6 +7,14 @@ 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: `split/rescope` +- Core-owned scope retained here: the evidence envelope schema, field semantics, and CI contract. +- Bundle-owned follow-up required: the runtime emitter flags and validation command behavior referenced below must be implemented by the canonical bundle owner rather than by `specfact-cli` core. +- Target modules-repo follow-up issue: [#169](https://github.com/nold-ai/specfact-cli-modules/issues/169) in `nold-ai/specfact-cli-modules` +- Downstream changes may extend the envelope, but they MUST NOT redefine the schema or imply core ownership of bundle runtime behavior. + ## What Changes @@ -71,6 +79,7 @@ Enterprise environments require machine-readable evidence that policies were enf - **GitHub Issue**: #247 - **Issue URL**: +- **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#169 +- **Paired Modules Scope**: governance evidence emitters - **Last Synced Status**: proposed - **Sanitized**: false - diff --git a/openspec/changes/governance-02-exception-management/proposal.md b/openspec/changes/governance-02-exception-management/proposal.md index 51c5a9b7..e7f3b81d 100644 --- a/openspec/changes/governance-02-exception-management/proposal.md +++ b/openspec/changes/governance-02-exception-management/proposal.md @@ -7,6 +7,14 @@ 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: `split/rescope` +- Core-owned scope retained here: exception schema, expiry semantics, and scope-suppression rules consumed by sibling governance changes. +- Bundle-owned follow-up required: the user-facing exception commands and policy-runtime integration below must be implemented by the canonical bundle owner rather than by `specfact-cli` core. +- Target modules-repo follow-up issue: [#167](https://github.com/nold-ai/specfact-cli-modules/issues/167) in `nold-ai/specfact-cli-modules` +- Implementation MUST NOT assume a core-owned exception command surface until a narrower retained-core delta is defined. + ## What Changes @@ -54,6 +62,7 @@ Enterprises always need exceptions — a legacy service can't comply with the ne - **GitHub Issue**: #248 - **Issue URL**: +- **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#167 +- **Paired Modules Scope**: runtime exception management and enforcement - **Last Synced Status**: proposed - **Sanitized**: false - diff --git a/openspec/changes/module-migration-04-remove-flat-shims/specs/category-command-groups/spec.md b/openspec/changes/module-migration-04-remove-flat-shims/specs/category-command-groups/spec.md deleted file mode 100644 index 93ffc4ff..00000000 --- a/openspec/changes/module-migration-04-remove-flat-shims/specs/category-command-groups/spec.md +++ /dev/null @@ -1,38 +0,0 @@ -# category-command-groups Specification (Delta: Remove Flat Shims) - -## Purpose - -This delta removes the backward-compat shim layer for flat commands. After this change, the root CLI SHALL list only core commands and the five category groups when `category_grouping_enabled` is true. - -## REMOVED Requirements - -### Requirement: Backward-compat shims preserve all existing flat top-level commands - -*(Removed in 0.40.x. Flat commands are no longer registered; users MUST use category form.)* - -#### Scenario: Root help lists only core and category groups - -- **GIVEN** `category_grouping_enabled` is `true` -- **WHEN** the user runs `specfact --help` -- **THEN** the output SHALL list only: core commands (`init`, `auth`, `module`, `upgrade`) and the five category groups (`code`, `backlog`, `project`, `spec`, `govern`) -- **AND** SHALL NOT list any of the 17 former flat shim commands (e.g. `analyze`, `validate`, `plan`, `sync`) - -#### Scenario: Flat command name returns error - -- **GIVEN** `category_grouping_enabled` is `true` -- **WHEN** the user runs `specfact validate --help` -- **THEN** the CLI SHALL respond with an error indicating the command is not found -- **AND** SHALL suggest using `specfact code validate` or list available commands - -## MODIFIED Requirements - -### Requirement: Bootstrap mounts category groups when grouping is enabled - -Bootstrap SHALL mount only category group apps (and core commands) when `category_grouping_enabled` is true. It SHALL NOT register any shim loaders for flat command names. - -#### Scenario: No shim registration at bootstrap - -- **GIVEN** `category_grouping_enabled` is `true` -- **WHEN** the CLI bootstrap runs -- **THEN** the registry SHALL contain entries only for core commands and the five category group names -- **AND** SHALL NOT contain entries for `analyze`, `drift`, `validate`, `repro`, `backlog`, `policy`, `project`, `plan`, `import`, `sync`, `migrate`, `contract`, `spec`, `sdd`, `generate`, `enforce`, `patch` as top-level commands diff --git a/openspec/changes/module-migration-10-bundle-command-surface-alignment/tasks.md b/openspec/changes/module-migration-10-bundle-command-surface-alignment/tasks.md deleted file mode 100644 index feb98966..00000000 --- a/openspec/changes/module-migration-10-bundle-command-surface-alignment/tasks.md +++ /dev/null @@ -1,32 +0,0 @@ -# Tasks - -## 1. Audit And Classify The Missing Command Paths - -- [ ] 1.1 Build a documented grouped-command inventory for the affected `project` and `spec` surfaces from README/docs/release-content references. -- [ ] 1.2 Verify each documented path against the installed official bundle runtime. -- [ ] 1.3 Classify each missing path as `public-runtime`, `docs-only-drift`, or `owner-decision-required`. - -## 2. Update Specs And Failing Tests First - -- [ ] 2.1 Add or update spec deltas for documented grouped command-path parity. -- [ ] 2.2 Add failing regression tests for the currently missing public-runtime paths. -- [ ] 2.3 Record pre-implementation failing evidence in `TDD_EVIDENCE.md`. - -## 3. Fix Bundle Runtime Exposure - -- [ ] 3.1 Patch the affected official bundles in `specfact-cli-modules` so intended grouped subcommands are mounted and reachable. -- [ ] 3.2 Verify the installed-bundle command tree exposes the intended grouped paths end-to-end. -- [ ] 3.3 Avoid adding new core CLI shims to compensate for bundle registration gaps. - -## 4. Align Release Documentation - -- [ ] 4.1 Update README/docs/release-facing examples in `specfact-cli` for any `docs-only-drift` paths. -- [ ] 4.2 Ensure public docs do not describe missing grouped commands as available in `v0.40.x`. -- [ ] 4.3 Capture any website/blog follow-up that must be synchronized outside this repo. - -## 5. Validate And Record Evidence - -- [ ] 5.1 Re-run targeted command-surface tests for the fixed paths. -- [ ] 5.2 Extend or re-run command-package runtime validation for the documented grouped paths. -- [ ] 5.3 Record post-implementation passing evidence in `TDD_EVIDENCE.md`. -- [ ] 5.4 Run `openspec validate module-migration-10-bundle-command-surface-alignment --strict`. diff --git a/openspec/changes/openspec-01-intent-trace/proposal.md b/openspec/changes/openspec-01-intent-trace/proposal.md index 856df1d4..790d7c3e 100644 --- a/openspec/changes/openspec-01-intent-trace/proposal.md +++ b/openspec/changes/openspec-01-intent-trace/proposal.md @@ -4,6 +4,14 @@ 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: `split/rescope` +- Core-owned scope retained here: the OpenSpec proposal schema, `tasks.md` metadata fields, and validation behavior for `## Intent Trace`. +- Bundle-owned follow-up required: the runtime import behavior referenced below (`sync bridge --import-intent`) belongs with the canonical project-bundle sync/import owner rather than `specfact-cli` core. +- Target modules-repo follow-up issue: [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) in `nold-ai/specfact-cli-modules` +- Implementation MUST separate schema/validation work from bundle runtime import work before coding resumes. + ## What Changes - **NEW**: `## Intent Trace` section schema for OpenSpec `proposal.md` files: @@ -43,5 +51,7 @@ OpenSpec proposals are plain Markdown with no structured business-intent metadat - **GitHub Issue**: #350 - **Issue URL**: -- **Repository**: nold-ai/specfact-cli +- **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#168 +- **Paired Modules Scope**: OpenSpec intent import runtime - **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/policy-02-packs-and-modes/.openspec.yaml b/openspec/changes/policy-02-packs-and-modes/.openspec.yaml deleted file mode 100644 index 2a45c1f4..00000000 --- a/openspec/changes/policy-02-packs-and-modes/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -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 deleted file mode 100644 index a6e30a1a..00000000 --- a/openspec/changes/policy-02-packs-and-modes/CHANGE_VALIDATION.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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 deleted file mode 100644 index bbce1bc4..00000000 --- a/openspec/changes/policy-02-packs-and-modes/design.md +++ /dev/null @@ -1,40 +0,0 @@ -## 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 deleted file mode 100644 index d790a84d..00000000 --- a/openspec/changes/policy-02-packs-and-modes/proposal.md +++ /dev/null @@ -1,59 +0,0 @@ -# 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. - -## 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 - - -- **GitHub Issue**: #246 -- **Issue URL**: -- **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 deleted file mode 100644 index 6c271f31..00000000 --- a/openspec/changes/policy-02-packs-and-modes/specs/policy-engine/spec.md +++ /dev/null @@ -1,22 +0,0 @@ -## 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 deleted file mode 100644 index 24826887..00000000 --- a/openspec/changes/policy-02-packs-and-modes/specs/policy-packs-and-modes/spec.md +++ /dev/null @@ -1,22 +0,0 @@ -## 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 deleted file mode 100644 index c522311c..00000000 --- a/openspec/changes/policy-02-packs-and-modes/tasks.md +++ /dev/null @@ -1,32 +0,0 @@ -# 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/profile-01-config-layering/proposal.md b/openspec/changes/profile-01-config-layering/proposal.md index 91c32cbd..e1d88b94 100644 --- a/openspec/changes/profile-01-config-layering/proposal.md +++ b/openspec/changes/profile-01-config-layering/proposal.md @@ -7,6 +7,13 @@ SpecFact treats every user the same — a solo developer and an enterprise architecture board get identical defaults, enforcement levels, and module activation. This blocks adoption at both ends: solos drown in ceremony they don't need, enterprises can't enforce baselines across hundreds of repos. A profile-driven initialization that deterministically selects modules, templates, policies, and enforcement modes makes SpecFact scale from single-developer projects to regulated enterprise environments without configuration sprawl. +## Ownership Alignment (2026-04-08) + +- Repository assignment: stays in `specfact-cli` core. +- Canonical owner: core `init` and core config resolution, not a standalone extracted `profile` module. +- The `modules/profile/...` package structure below is stale relative to the lean-core architecture and MUST NOT be used as an implementation target. +- Required rescope: express this change through `specfact init --profile`, shared profile/config models, and core-owned config layering behavior. + ## Module Package Structure ``` diff --git a/openspec/changes/requirements-02-module-commands/proposal.md b/openspec/changes/requirements-02-module-commands/proposal.md index 84d939a2..e809d6ec 100644 --- a/openspec/changes/requirements-02-module-commands/proposal.md +++ b/openspec/changes/requirements-02-module-commands/proposal.md @@ -7,6 +7,14 @@ 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: `split/rescope` +- Core-owned scope retained here: shared requirements contracts, schemas, and adapter/interface deltas needed by downstream owners. +- Bundle-owned follow-up required: the user-facing command surface proposed below cannot remain a flat `specfact requirements ...` family and cannot be implemented in `specfact-cli` core as described. +- Target modules-repo follow-up issue: [#165](https://github.com/nold-ai/specfact-cli-modules/issues/165) in `nold-ai/specfact-cli-modules` +- Implementation MUST NOT proceed from the legacy `modules/requirements/...` package structure below until a paired bundle-owned follow-up change defines the canonical grouped command home. + ## Module Package Structure ``` @@ -105,6 +113,7 @@ modules/requirements/ - **GitHub Issue**: #239 - **Issue URL**: +- **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#165 +- **Paired Modules Scope**: requirements runtime commands - **Last Synced Status**: proposed - **Sanitized**: false - \ No newline at end of file diff --git a/openspec/changes/requirements-03-backlog-sync/proposal.md b/openspec/changes/requirements-03-backlog-sync/proposal.md index 48db41e9..669d6f40 100644 --- a/openspec/changes/requirements-03-backlog-sync/proposal.md +++ b/openspec/changes/requirements-03-backlog-sync/proposal.md @@ -7,6 +7,14 @@ 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: `split/rescope` +- Core-owned scope retained here: shared sync contracts, adapter semantics, and spec-kit duplicate-creation safeguards. +- Bundle-owned follow-up required: the user-facing requirements/backlog sync workflow below spans project and backlog bundle behavior and cannot remain a flat `specfact requirements ...` command family in core. +- Target modules-repo follow-up issue: [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) in `nold-ai/specfact-cli-modules` +- Implementation MUST NOT proceed from this proposal as a single-repo change until the bundle-owned follow-up changes are split out explicitly. + ## What Changes @@ -39,6 +47,7 @@ When backlog items change, requirements aren't updated. When requirements change - **GitHub Issue**: #244 - **Issue URL**: +- **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#166 +- **Paired Modules Scope**: requirements-backlog sync runtime - **Last Synced Status**: proposed - **Sanitized**: false - \ No newline at end of file diff --git a/openspec/changes/sync-01-unified-kernel/.openspec.yaml b/openspec/changes/sync-01-unified-kernel/.openspec.yaml deleted file mode 100644 index 2a45c1f4..00000000 --- a/openspec/changes/sync-01-unified-kernel/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -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 deleted file mode 100644 index d4c2c4c4..00000000 --- a/openspec/changes/sync-01-unified-kernel/CHANGE_VALIDATION.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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 deleted file mode 100644 index 7008d186..00000000 --- a/openspec/changes/sync-01-unified-kernel/design.md +++ /dev/null @@ -1,40 +0,0 @@ -## 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 deleted file mode 100644 index 4e1c1040..00000000 --- a/openspec/changes/sync-01-unified-kernel/proposal.md +++ /dev/null @@ -1,118 +0,0 @@ -# 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. - -## 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 - - -- **GitHub Issue**: #243 -- **Issue URL**: -- **Last Synced Status**: proposed -- **Sanitized**: false - \ No newline at end of file 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 deleted file mode 100644 index cb9730e9..00000000 --- a/openspec/changes/sync-01-unified-kernel/specs/devops-sync/spec.md +++ /dev/null @@ -1,16 +0,0 @@ -## 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 deleted file mode 100644 index d8a30254..00000000 --- a/openspec/changes/sync-01-unified-kernel/specs/sync-kernel/spec.md +++ /dev/null @@ -1,22 +0,0 @@ -## 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 deleted file mode 100644 index 3ce6e9c0..00000000 --- a/openspec/changes/sync-01-unified-kernel/tasks.md +++ /dev/null @@ -1,30 +0,0 @@ -# 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/proposal.md b/openspec/changes/traceability-01-index-and-orphans/proposal.md index 8881a491..e074d9ca 100644 --- a/openspec/changes/traceability-01-index-and-orphans/proposal.md +++ b/openspec/changes/traceability-01-index-and-orphans/proposal.md @@ -7,6 +7,14 @@ 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: `split/rescope` +- Core-owned scope retained here: shared traceability index contracts and artifact linkage semantics. +- Bundle-owned follow-up required: the flat `specfact trace ...` command family and `modules/trace/...` package structure below are not canonical in the grouped command model. +- Target modules-repo follow-up issue: [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) in `nold-ai/specfact-cli-modules` +- Implementation MUST NOT proceed from the legacy package layout below until the bundle-owned query/reporting surface is defined separately. + ## Module Package Structure ``` @@ -99,6 +107,7 @@ modules/trace/ - **GitHub Issue**: #242 - **Issue URL**: +- **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#170 +- **Paired Modules Scope**: traceability runtime queries and orphan detection - **Last Synced Status**: proposed - **Sanitized**: false - \ No newline at end of file diff --git a/openspec/changes/validation-02-full-chain-engine/proposal.md b/openspec/changes/validation-02-full-chain-engine/proposal.md index dfe3b162..18a24659 100644 --- a/openspec/changes/validation-02-full-chain-engine/proposal.md +++ b/openspec/changes/validation-02-full-chain-engine/proposal.md @@ -7,6 +7,14 @@ 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: `split/rescope` +- Core-owned scope retained here: shared full-chain report contracts and governance/evidence integration boundaries. +- Bundle-owned follow-up required: the runtime validation engine described below belongs to the canonical `code` / `specfact-codebase` bundle surface, not to `specfact-cli` core. +- Target modules-repo follow-up issue: [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) in `nold-ai/specfact-cli-modules` +- Implementation MUST NOT proceed from the legacy `modules/validate/...` package structure below as a core-owned change. + ## Module Package Structure ``` @@ -88,6 +96,7 @@ modules/validate/ - **GitHub Issue**: #241 - **Issue URL**: +- **Paired Modules Runtime Issue**: nold-ai/specfact-cli-modules#171 +- **Paired Modules Scope**: full-chain validation runtime engine - **Last Synced Status**: proposed - **Sanitized**: false - diff --git a/openspec/specs/agile-feature-hierarchy/spec.md b/openspec/specs/agile-feature-hierarchy/spec.md new file mode 100644 index 00000000..8cfaf61e --- /dev/null +++ b/openspec/specs/agile-feature-hierarchy/spec.md @@ -0,0 +1,19 @@ +# agile-feature-hierarchy Specification + +## Purpose +Keep the public SpecFact CLI backlog organized as a three-level GitHub hierarchy of Epic -> Feature -> User Story, with `openspec/CHANGE_ORDER.md` kept in sync with the current planning structure. +## Requirements +### Requirement: GitHub Agile Feature Hierarchy +The project governance workflow SHALL maintain a three-level GitHub planning hierarchy of Epic -> Feature -> User Story for the public SpecFact CLI backlog. + +#### Scenario: Feature issues group user stories under the correct epic +- **GIVEN** the public backlog contains Epic issues and change-proposal issues +- **WHEN** the hierarchy setup work is completed +- **THEN** each planned Feature issue is linked to its parent Epic +- **AND** each grouped User Story issue is assigned to the correct Feature + +#### Scenario: CHANGE_ORDER stays aligned with the GitHub hierarchy +- **GIVEN** new Epic or Feature-level hierarchy items are introduced in GitHub +- **WHEN** the change is updated +- **THEN** `openspec/CHANGE_ORDER.md` reflects the current Epic and Feature sequencing metadata +- **AND** stale issue state such as archived-but-open items is reconciled during validation diff --git a/openspec/specs/backlog-module-ownership/spec.md b/openspec/specs/backlog-module-ownership/spec.md index c0a8572b..72c68217 100644 --- a/openspec/specs/backlog-module-ownership/spec.md +++ b/openspec/specs/backlog-module-ownership/spec.md @@ -5,7 +5,7 @@ TBD - created by archiving change backlog-module-ownership-cleanup. Update Purpo ## Requirements ### Requirement: Backlog Feature Commands Must Be Module-Owned -The system SHALL treat `nold-ai/specfact-backlog` as the sole owner of user-facing backlog and policy command surfaces. +The system SHALL treat `nold-ai/specfact-backlog` as the sole owner of user-facing backlog and policy command surfaces, including the active proposal backlog and GitHub planning artifacts that track future backlog and ceremony feature work. #### Scenario: Core does not directly own backlog feature commands - **WHEN** command registration is resolved in `specfact-cli` @@ -17,6 +17,11 @@ The system SHALL treat `nold-ai/specfact-backlog` as the sole owner of user-faci - **THEN** core retains only shared provider integrations, generic data models, and minimal backlog contracts reused outside the backlog bundle - **AND** backlog-only command implementations, prompt resources, templates, and refinement helpers are not owned by core. +#### Scenario: Active backlog proposals are not tracked as core-owned implementation work +- **WHEN** a pending OpenSpec change or linked GitHub issue describes backlog, scrum, kanban, safe, ceremony, or policy command behavior that belongs to `specfact-backlog` +- **THEN** that work is assigned to the modules repo planning hierarchy rather than remaining a core-repo implementation story +- **AND** the core repo retains only the shared contracts or bridge points, if any, that support the owning bundle. + ### Requirement: Backlog Prompt And Template Assets Must Be Module-Owned Backlog-specific prompts, prompt templates, and backlog template semantics SHALL be owned by the backlog module, not by `specfact-cli` core. diff --git a/openspec/specs/bundle-command-surface-alignment/spec.md b/openspec/specs/bundle-command-surface-alignment/spec.md new file mode 100644 index 00000000..94dcf3c7 --- /dev/null +++ b/openspec/specs/bundle-command-surface-alignment/spec.md @@ -0,0 +1,53 @@ +# bundle-command-surface-alignment Specification + +## Purpose +TBD - created by archiving change module-migration-10-bundle-command-surface-alignment. Update Purpose after archive. +## Requirements +### Requirement: Documented Grouped Commands Must Resolve In Installed Official Bundles + +The system SHALL ensure that grouped CLI commands documented for a shipped release resolve in an environment where the corresponding official bundles are installed. + +#### Scenario: Documented project subgroup commands resolve + +- **GIVEN** the official `nold-ai/specfact-project` bundle is installed +- **WHEN** the user runs documented grouped command paths such as `specfact code import --help` or `specfact project plan review --help` +- **THEN** the command path resolves successfully from the installed bundle runtime +- **AND** the help output reflects the mounted subgroup command rather than `No such command`. + +#### Scenario: Documented spec subgroup commands resolve + +- **GIVEN** the official `nold-ai/specfact-spec` bundle is installed +- **WHEN** the user runs documented grouped command paths such as `specfact spec generate contracts-prompt --help` or `specfact spec contract test --help` +- **THEN** the command path resolves successfully from the installed bundle runtime +- **AND** the installed bundle help tree exposes those subgroup commands. + +### Requirement: Release Documentation Must Not Promise Missing Grouped Commands + +The system SHALL keep release-facing documentation aligned with the actual shipped grouped command surface. + +#### Scenario: Unsupported path is removed from docs + +- **GIVEN** a grouped command path is not part of the shipped runtime surface for the current release +- **WHEN** release-facing docs are updated +- **THEN** that path is removed or corrected in README/docs/release content +- **AND** users are not told to run a command that fails at runtime. + +#### Scenario: Slash prompts do not hide missing CLI registration + +- **GIVEN** a grouped CLI command is documented as part of the release surface +- **WHEN** corresponding slash-command guidance exists +- **THEN** the docs may include the slash prompt as an IDE workflow aid +- **BUT NOT** as a substitute for a missing or unregistered CLI path. + +### Requirement: Runtime Validation Detects Documented Command Drift + +The system SHALL fail validation when a documented grouped command path is missing from the installed official bundle command tree. + +#### Scenario: Missing documented grouped command fails validation + +- **GIVEN** a documented grouped command inventory for the shipped release +- **AND** the official bundle install/runtime validation environment +- **WHEN** a documented grouped command path is not mounted by the installed bundle +- **THEN** validation fails with the missing command path and owning bundle id +- **AND** the report distinguishes this from help-only or docs-only command coverage. + diff --git a/openspec/specs/ci-integration/spec.md b/openspec/specs/ci-integration/spec.md new file mode 100644 index 00000000..6e3553e7 --- /dev/null +++ b/openspec/specs/ci-integration/spec.md @@ -0,0 +1,70 @@ +# ci-integration Specification + +## Purpose +TBD - created by archiving change ci-docs-sync-check. Update Purpose after archive. +## Requirements +### Requirement: Branch Protection Configuration +The system SHALL configure branch protection to require docs sync check. + +#### Scenario: Main branch protection +- **WHEN** branch protection is configured +- **THEN** main branch SHALL require docs sync check +- **AND** prevent merges with failing checks + +#### Scenario: Develop branch protection +- **WHEN** branch protection is configured +- **THEN** develop branch SHALL require docs sync check +- **AND** prevent merges with failing checks + +### Requirement: Status Check Integration +The system SHALL integrate docs sync check as a required status check. + +#### Scenario: Required status check setup +- **WHEN** CI integration is complete +- **THEN** docs sync check SHALL be required status check +- **AND** appear in branch protection settings + +#### Scenario: Status check enforcement +- **WHEN** PR has failing docs sync check +- **THEN** PR SHALL be blocked from merge +- **AND** clear error SHALL be shown + +### Requirement: Exemption Label Support +The system SHALL support exemption labels for intentional documentation exemptions. + +#### Scenario: Docs exempt label +- **WHEN** PR has `docs-exempt` label +- **THEN** docs sync check SHALL be skipped +- **AND** PR SHALL not be blocked + +#### Scenario: No exemption label +- **WHEN** PR doesn't have exemption label +- **THEN** docs sync check SHALL run normally +- **AND** enforce documentation requirements + +### Requirement: Error Reporting Integration +The system SHALL integrate error reporting with GitHub UI. + +#### Scenario: Clear error messages +- **WHEN** docs sync check fails +- **THEN** error messages SHALL appear in GitHub UI +- **AND** be clearly formatted + +#### Scenario: Actionable guidance +- **WHEN** docs sync check fails +- **THEN** output SHALL provide actionable guidance +- **AND** list specific documents to update + +### Requirement: Configuration Management +The system SHALL manage CI configuration appropriately. + +#### Scenario: Configuration file updates +- **WHEN** CI integration is implemented +- **THEN** configuration files SHALL be updated +- **AND** changes SHALL be version controlled + +#### Scenario: Backward compatibility +- **WHEN** CI integration is implemented +- **THEN** existing workflows SHALL not be disrupted +- **AND** backward compatibility SHALL be maintained + diff --git a/openspec/specs/cross-repo-backlog-alignment/spec.md b/openspec/specs/cross-repo-backlog-alignment/spec.md new file mode 100644 index 00000000..27b72595 --- /dev/null +++ b/openspec/specs/cross-repo-backlog-alignment/spec.md @@ -0,0 +1,51 @@ +# cross-repo-backlog-alignment Specification + +## Purpose +TBD - created by archiving change cross-repo-issue-realignment. Update Purpose after archive. +## Requirements +### Requirement: Active Change Ownership Must Be Classified Against The Canonical Repo Split +The system SHALL classify every active OpenSpec change and linked GitHub user story in `specfact-cli` against the canonical post-migration ownership model before further implementation work proceeds. + +#### Scenario: Active change is classified as core, modules, or split +- **WHEN** maintainers review active changes that still reference the pre-split monolithic structure +- **THEN** each change is assigned one of: `core`, `modules`, or `split/rescope` +- **AND** the decision is based on the canonical ownership specs rather than on stale proposal paths or legacy issue location. + +### Requirement: Module-Owned Issues Must Use A Defined Reassignment Path +The system SHALL define a deterministic path for any GitHub issue that belongs in `specfact-cli-modules` instead of `specfact-cli`. + +#### Scenario: Native issue transfer is available and accepted +- **WHEN** a module-owned issue can be moved between the two repositories with acceptable metadata preservation +- **THEN** the issue is transferred to `nold-ai/specfact-cli-modules` +- **AND** the related OpenSpec artifacts and planning inventory are updated to reference the transferred issue in its new repository. + +#### Scenario: Native issue transfer is unavailable or unsuitable +- **WHEN** a module-owned issue cannot be moved cleanly between repositories +- **THEN** the source issue in `specfact-cli` is closed with a comment pointing to the replacement issue in `specfact-cli-modules` +- **AND** a replacement issue is created in `specfact-cli-modules` with updated scope aligned to the current architecture +- **AND** the old and new issues cross-reference each other so planning history remains auditable. + +### Requirement: Target Hierarchy Must Exist Before Module-Owned Stories Are Reassigned +The system SHALL establish the necessary Epic and Feature parents in `specfact-cli-modules` before module-owned user stories are transferred or recreated there. + +#### Scenario: Module-owned user story is prepared for reassignment +- **WHEN** a user story is classified as module-owned +- **THEN** the target repository already has the Epic and Feature hierarchy needed to parent that story +- **AND** the reassigned story is linked under the target Feature rather than being left as a flat issue. + +### Requirement: Planning Inventories Must Be Updated In Both Repositories +The system SHALL keep planning metadata aligned across repositories when change ownership or GitHub issue ownership changes. + +#### Scenario: Change ownership is reassigned to modules repo +- **WHEN** a change or linked issue moves from `specfact-cli` planning to `specfact-cli-modules` +- **THEN** `openspec/CHANGE_ORDER.md` in `specfact-cli` is updated to remove or annotate the old core-repo ownership +- **AND** the corresponding planning inventory in `specfact-cli-modules` is updated with the new issue, Epic, Feature, and dependency references. + +### Requirement: Rescoped Proposals Must State The Current Architecture And Repo Assignment +The system SHALL update affected active proposals before implementation resumes so they no longer describe obsolete monolithic paths or incorrect repository ownership. + +#### Scenario: Active proposal still references in-repo module implementation +- **WHEN** an active proposal describes implementation under `modules//` in `specfact-cli` for a module-owned capability +- **THEN** the proposal is updated to either reflect its true core-only scope or to point to the owning implementation work in `specfact-cli-modules` +- **AND** the proposal no longer implies that bundle-owned behavior will be implemented in the core repo. + diff --git a/openspec/specs/dependency-resolution/spec.md b/openspec/specs/dependency-resolution/spec.md index acda8339..97de2c0d 100644 --- a/openspec/specs/dependency-resolution/spec.md +++ b/openspec/specs/dependency-resolution/spec.md @@ -52,3 +52,168 @@ The system SHALL provide actionable error messages when dependency conflicts occ - **THEN** error SHALL include: conflicting packages, required versions, affected modules - **AND** SHALL suggest: uninstall conflicting module, use --force, or skip conflicting module +### Requirement: Registry index supports versioned bundle dependencies + +The marketplace registry `index.json` SHALL support optional version specifiers on +`bundle_dependencies` entries. Each entry MAY be either a plain module ID string (unversioned, +backward-compatible) or an object with `id` and `version` fields (versioned). The CLI installer +SHALL handle both forms. + +#### Scenario: Registry entry declares a versioned bundle dependency + +- **GIVEN** a registry entry with: + ```json + "bundle_dependencies": [ + {"id": "nold-ai/specfact-project", "version": ">=0.41.0"} + ] + ``` +- **WHEN** the installer processes this entry +- **THEN** the installer SHALL treat `nold-ai/specfact-project` as a required dependency with + the constraint `>=0.41.0` + +#### Scenario: Registry entry declares an unversioned bundle dependency (backward compat) + +- **GIVEN** a registry entry with `"bundle_dependencies": ["nold-ai/specfact-project"]` +- **WHEN** the installer processes this entry +- **THEN** the installer SHALL treat the dependency as requiring any installed version +- **AND** SHALL NOT reject existing manifests that use plain string form + +### Requirement: Install-time dependency version resolution + +During `specfact module install`, the system SHALL resolve all `bundle_dependencies` from both +the registry index and the module's `module-package.yaml` manifest. For each dependency: +- If the dependency is not installed, the CLI SHALL prompt the user to install it +- If the dependency is installed but its version does not satisfy the declared specifier, the CLI + SHALL prompt the user to upgrade it +- With `--yes`, missing or mismatched dependencies SHALL be auto-resolved without prompting +- With `--skip-deps`, dependency resolution SHALL be skipped entirely (existing behaviour) + +#### Scenario: Installing a module whose dependency is not installed + +- **GIVEN** module A declares `bundle_dependencies: [{"id": "nold-ai/specfact-project", "version": ">=0.41.0"}]` +- **AND** `specfact-project` is NOT installed +- **WHEN** user runs `specfact module install A` +- **THEN** the CLI SHALL print: + `A requires nold-ai/specfact-project >=0.41.0 which is not installed.` +- **AND** in interactive mode SHALL prompt: `Install nold-ai/specfact-project now? [Y/n]` +- **AND** if the user confirms, SHALL install the dependency before installing A +- **AND** if the user declines, SHALL abort with exit code 1 + +#### Scenario: Installing a module whose dependency version is insufficient + +- **GIVEN** module A requires `nold-ai/specfact-project >=0.41.0` +- **AND** `specfact-project` is installed at version `0.40.2` +- **WHEN** user runs `specfact module install A` +- **THEN** the CLI SHALL print: + `A requires nold-ai/specfact-project >=0.41.0 but 0.40.2 is installed.` +- **AND** in interactive mode SHALL prompt: `Upgrade nold-ai/specfact-project to satisfy constraint? [Y/n]` +- **AND** if confirmed, SHALL upgrade the dependency before installing A +- **AND** if declined, SHALL abort with exit code 1 + +#### Scenario: Dependency already satisfied — no prompt + +- **GIVEN** module A requires `nold-ai/specfact-project >=0.41.0` +- **AND** `specfact-project` is installed at version `0.41.2` +- **WHEN** user runs `specfact module install A` +- **THEN** the CLI SHALL NOT prompt about the dependency +- **AND** SHALL log at INFO level: "Dependency nold-ai/specfact-project 0.41.2 satisfies >=0.41.0" + +#### Scenario: Non-interactive / CI mode with unsatisfied dependency + +- **GIVEN** the CLI is running in CI/CD mode and a dependency is not installed +- **WHEN** user runs `specfact module install A` without `--yes` +- **THEN** the CLI SHALL print the dependency error and exit non-zero +- **AND** SHALL NOT silently install the dependency +- **AND** SHALL suggest re-running with `--yes` to auto-resolve + +#### Scenario: Auto-resolve dependencies with --yes + +- **GIVEN** module A has an unmet dependency +- **WHEN** user runs `specfact module install A --yes` +- **THEN** the CLI SHALL install or upgrade all required dependencies automatically +- **AND** SHALL print a summary of what was auto-installed/upgraded before installing A + +### Requirement: Upgrade-time dependency re-evaluation + +During `specfact module upgrade`, the system SHALL re-evaluate the new version's +`bundle_dependencies` after fetching its updated manifest. If the new version introduces new +or tighter dependency requirements that are not currently satisfied, the CLI SHALL prompt the +user to resolve them before completing the upgrade. + +#### Scenario: Upgraded module requires a newer version of a dependency + +- **GIVEN** module A is being upgraded from `0.41.0` to `0.42.0` +- **AND** `0.42.0`'s manifest declares `nold-ai/specfact-project >=0.42.0` +- **AND** `specfact-project` is installed at `0.41.2` +- **WHEN** user runs `specfact module upgrade A` +- **THEN** the CLI SHALL print: + `A 0.42.0 requires nold-ai/specfact-project >=0.42.0 but 0.41.2 is installed.` +- **AND** SHALL prompt: `Upgrade nold-ai/specfact-project to satisfy constraint? [Y/n]` +- **AND** if confirmed, SHALL upgrade the dependency before completing the upgrade of A +- **AND** if declined, SHALL abort the upgrade of A and leave the existing version in place + +#### Scenario: Upgraded module introduces a new dependency not yet installed + +- **GIVEN** module A `0.42.0` introduces a new `bundle_dependencies` entry not present in `0.41.0` +- **AND** the new dependency is not installed +- **WHEN** user runs `specfact module upgrade A` +- **THEN** the CLI SHALL prompt to install the new dependency (same flow as install-time) + +#### Scenario: Upgrade with --yes auto-resolves dependency changes + +- **GIVEN** an upgrade introduces new or tighter dependency requirements +- **WHEN** user runs `specfact module upgrade A --yes` +- **THEN** all dependency installs and upgrades SHALL proceed automatically without prompting + +### Requirement: Core CLI compatibility check SHALL produce a clear actionable error + +The CLI SHALL report a clear actionable error when a module's `core_compatibility` specifier is +not satisfied, telling the user both the required range and the current CLI version and suggesting +the corrective action. + +#### Scenario: Module requires a newer CLI version + +- **GIVEN** module A declares `core_compatibility: ">=0.45.0,<1.0.0"` +- **AND** the installed CLI is version `0.44.0` +- **WHEN** user runs `specfact module install A` +- **THEN** the CLI SHALL print: + `A requires SpecFact CLI >=0.45.0 but you have 0.44.0.` + `Run: specfact upgrade or uvx specfact-cli@latest` +- **AND** SHALL exit non-zero without installing + +#### Scenario: Module is incompatible with current CLI major version + +- **GIVEN** module A declares `core_compatibility: ">=0.40.0,<1.0.0"` +- **AND** the installed CLI is version `1.0.0` +- **WHEN** user runs `specfact module install A` +- **THEN** the CLI SHALL print a clear incompatibility message with the constraint and current version +- **AND** SHALL suggest checking for a newer version of the module from the marketplace + +### Requirement: Circular dependency detection + +The installer SHALL detect circular `bundle_dependencies` references and abort with a clear error. + +#### Scenario: Circular bundle dependency detected + +- **GIVEN** module A depends on B and B depends on A +- **WHEN** the installer processes the dependency graph +- **THEN** the installer SHALL detect the cycle and print: + `Circular dependency detected: A -> B -> A` +- **AND** SHALL abort the install with exit code 1 without installing any module in the cycle + +### Requirement: Dry-run shows dependency resolution plan + +The install and upgrade commands SHALL support a `--dry-run` flag that shows the full dependency +resolution plan without performing any installs or upgrades. + +#### Scenario: Dry-run install shows what would be installed + +- **WHEN** user runs `specfact module install A --dry-run` +- **THEN** the CLI SHALL print a dependency plan: + ``` + Would install: + nold-ai/specfact-project 0.41.2 (required by A >=0.41.0) + nold-ai/A 0.42.0 + ``` +- **AND** SHALL exit 0 without modifying any installed modules + diff --git a/openspec/specs/docs-aha-moment-entry/spec.md b/openspec/specs/docs-aha-moment-entry/spec.md new file mode 100644 index 00000000..0fcac2c5 --- /dev/null +++ b/openspec/specs/docs-aha-moment-entry/spec.md @@ -0,0 +1,85 @@ +# docs-aha-moment-entry Specification + +## Purpose +TBD - created by archiving change docs-new-user-onboarding. Update Purpose after archive. +## Requirements +### Requirement: Homepage names `code review run` as the primary entry command + +The docs homepage SHALL explicitly name `specfact code review run` as the primary command for the +"review your code" use case. The command SHALL appear in the hero section before any path cards, +module system explanations, or architecture descriptions. + +#### Scenario: Vibe coder arrives at the homepage + +- **WHEN** a first-time visitor who heard "validate your vibe code with specfact" lands on + docs.specfact.io +- **THEN** the homepage SHALL display a fenced code block showing: + `uvx specfact-cli init --profile solo-developer` and + `uvx specfact-cli code review run --path . --scope full` + as the 2-command entry sequence +- **AND** the block SHALL appear before any path cards, architecture sections, or module links +- **AND** the expected output (scored review result with findings) SHALL be described adjacent to + the block so the user knows what they will see before running the commands + +#### Scenario: Visitor can start without navigating away + +- **WHEN** a visitor reads only the homepage without clicking any link +- **THEN** they SHALL have all commands needed to run their first code review +- **AND** no prior Python or pip knowledge SHALL be required to understand or run those commands + +### Requirement: Path cards name user outcomes in plain language + +The "Choose your path" cards on the homepage SHALL use plain language that a non-Python-expert +can understand. Each card heading SHALL describe what the user will achieve immediately. + +#### Scenario: Vibe coder reads card headings + +- **WHEN** a vibe coder with no prior SpecFact knowledge reads the path card headings +- **THEN** the first card heading SHALL be oriented toward reviewing existing code immediately + (e.g. "See what's wrong with your code right now") +- **AND** no heading SHALL use internal labels such as "Greenfield & AI-assisted delivery", + "Brownfield and reverse engineering", "Backlog to code alignment", or "Team and policy enforcement" + as the primary title +- **AND** each card body SHALL describe the user outcome and the key command, not the product + architecture or module name + +#### Scenario: User with no prior SpecFact knowledge selects a path + +- **WHEN** a user with no prior SpecFact knowledge reads the three path cards +- **THEN** they SHALL be able to identify which card matches their immediate goal without + understanding SpecFact's internal module or bundle architecture + +### Requirement: Architectural jargon deferred below the fold + +Terms describing internal platform architecture SHALL NOT appear in the above-the-fold hero content +of the homepage. They may appear in Architecture, Reference, or Module System sections lower on +the page. + +#### Scenario: Above-the-fold homepage content audit + +- **WHEN** the homepage is rendered at a standard viewport (1280×800) +- **THEN** the visible content SHALL NOT include any of the following terms before the user scrolls: + "module discovery", "registry bootstrapping", "publisher trust", "mounted workflow groups", + "runtime contracts" (used as a section label or navigation entry) +- **AND** those terms MAY appear in Architecture or Reference sections below the fold + +### Requirement: Installation page promotes uvx as the no-install entry path + +The installation page SHALL present the uvx invocation as the primary "try it now" path for new +users, without a "Limitations" warning that discourages its use. + +#### Scenario: New user opens the installation page + +- **WHEN** a first-time user opens the installation page +- **THEN** the first visible section SHALL present the uvx 2-command sequence + (init + code review run) under a heading such as "Try it now — no install required" +- **AND** the section SHALL NOT include a "Limitations" warning about the uvx path +- **AND** pip installation SHALL appear in a clearly labelled secondary section + ("Install for persistent use" or equivalent) + +#### Scenario: User wants to find alternative installation methods + +- **WHEN** a user wants to find Container or GitHub Action installation options +- **THEN** a visible section heading or anchor link SHALL allow them to jump to those options + without reading through the uvx or pip sections first + diff --git a/openspec/specs/docs-sync-algorithm/spec.md b/openspec/specs/docs-sync-algorithm/spec.md new file mode 100644 index 00000000..6328cc5e --- /dev/null +++ b/openspec/specs/docs-sync-algorithm/spec.md @@ -0,0 +1,78 @@ +# docs-sync-algorithm Specification + +## Purpose +TBD - created by archiving change ci-docs-sync-check. Update Purpose after archive. +## Requirements +### Requirement: Change Detection Algorithm +The system SHALL implement an algorithm to detect when source files change but tracked documentation doesn't. + +#### Scenario: Source change without doc update +- **WHEN** source files matching `tracks` patterns change +- **AND** corresponding docs are not updated +- **THEN** algorithm SHALL detect stale documentation + +#### Scenario: Source and doc both updated +- **WHEN** source files change +- **AND** corresponding docs are also updated +- **THEN** algorithm SHALL not detect stale documentation + +### Requirement: Git Diff Integration +The system SHALL integrate with git to detect changed files between commits. + +#### Scenario: Git diff between base and head +- **WHEN** algorithm runs on PR +- **THEN** it SHALL use `git diff --name-only ...` +- **AND** correctly identify changed files + +#### Scenario: Multiple changed files +- **WHEN** multiple files change in PR +- **THEN** algorithm SHALL process all changed files +- **AND** identify all affected documentation + +### Requirement: Glob Pattern Matching +The system SHALL support glob pattern matching for tracking relationships. + +#### Scenario: Single glob pattern match +- **WHEN** changed file matches single glob pattern in `tracks` +- **THEN** corresponding doc SHALL be marked for sync check + +#### Scenario: Multiple glob pattern matches +- **WHEN** changed file matches multiple glob patterns +- **THEN** all corresponding docs SHALL be marked for sync check + +### Requirement: Stale Documentation Identification +The system SHALL correctly identify stale documentation. + +#### Scenario: Doc not in changed files +- **WHEN** source files change matching doc's `tracks` +- **AND** doc file itself is not in changed files +- **THEN** doc SHALL be marked as stale + +#### Scenario: Doc in changed files +- **WHEN** source files change matching doc's `tracks` +- **AND** doc file is in changed files +- **THEN** doc SHALL not be marked as stale + +### Requirement: Exempt Documentation Handling +The system SHALL properly handle exempt documentation. + +#### Scenario: Exempt doc with source changes +- **WHEN** source files change matching exempt doc's `tracks` +- **THEN** doc SHALL not be marked as stale + +#### Scenario: Non-exempt doc processing +- **WHEN** source files change matching non-exempt doc's `tracks` +- **THEN** doc SHALL undergo normal sync check + +### Requirement: Error Reporting +The system SHALL provide clear error reporting for stale documentation. + +#### Scenario: Single stale document +- **WHEN** one document is stale +- **THEN** error output SHALL list that document clearly + +#### Scenario: Multiple stale documents +- **WHEN** multiple documents are stale +- **THEN** error output SHALL list all stale documents +- **AND** format SHALL be clear and readable + diff --git a/openspec/specs/docs-vibecoder-entry-path/spec.md b/openspec/specs/docs-vibecoder-entry-path/spec.md new file mode 100644 index 00000000..0f0e99ec --- /dev/null +++ b/openspec/specs/docs-vibecoder-entry-path/spec.md @@ -0,0 +1,75 @@ +# docs-vibecoder-entry-path Specification + +## Purpose +TBD - created by archiving change docs-new-user-onboarding. Update Purpose after archive. +## Requirements +### Requirement: Vibe-coder entry path is discoverable and runnable in under 2 commands + +The documentation entry surface SHALL make it possible for a developer who has never used +SpecFact before — and who does not know Python packaging — to reach a scored `code review run` +result in 2 commands and approximately 10 seconds, without pip install or virtual environment +setup. + +#### Scenario: Vibe coder runs the entry sequence for the first time + +- **GIVEN** a developer with `uvx` available (via the `uv` toolchain) and a git repository +- **WHEN** they run `uvx specfact-cli init --profile solo-developer` followed by + `uvx specfact-cli code review run --path . --scope full` +- **THEN** the first command SHALL install the required modules at user level in under 10 seconds +- **AND** the second command SHALL produce a scored code review result with categorised findings +- **AND** no additional configuration, pip install, or virtual environment setup SHALL be required + +#### Scenario: Entry path is documented with expected output + +- **WHEN** a visitor reads the homepage or installation page +- **THEN** the documentation SHALL show the expected output format of `code review run` + (e.g. "Verdict: FAIL | Score: 0 | 64 findings across naming, complexity, and type checks") + so the user knows what a successful first run looks like before they run it + +### Requirement: `code review run --path .` SHALL provide actionable guidance when scope is missing + +The CLI SHALL provide an actionable inline hint rather than a bare error when +`specfact code review run --path .` is run without `--scope full` and no diff output is +available. + +#### Scenario: User runs `code review run --path .` without `--scope full` + +- **GIVEN** the user is in a git repository with no staged or unstaged changes visible via + `git diff HEAD` +- **WHEN** they run `specfact code review run --path .` +- **THEN** the CLI SHALL either: + (a) default automatically to `--scope full` when no diff is available, OR + (b) display an error that includes the exact command to run: + `specfact code review run --path . --scope full` +- **AND** the error SHALL NOT only say "Unable to determine changed tracked files" without + providing the corrective command + +### Requirement: Module-not-found error SHALL provide an exact uvx init command + +The CLI SHALL include the exact `uvx specfact-cli init` command as the suggested fix in +module-not-found errors when running in a uvx execution context. + +#### Scenario: Vibe coder runs `uvx specfact-cli code review run` before init + +- **GIVEN** a user running via `uvx specfact-cli` with no modules installed at user level +- **WHEN** they run `uvx specfact-cli code review run --path . --scope full` +- **THEN** the CLI SHALL display an error message that includes: + `uvx specfact-cli init --profile solo-developer` + as the suggested fix command +- **AND** the message SHALL NOT only reference "workflow bundles" without giving an exact command + +### Requirement: Plain-language value statement precedes technical vocabulary on entry pages + +The docs homepage and installation page SHALL open with a plain-language statement of what the +user will get — using vocabulary a non-Python-expert understands — before introducing any +technical terms. + +#### Scenario: Non-Python developer reads the homepage + +- **WHEN** a developer who primarily uses JavaScript, no-code tools, or AI-assisted coding reads + the homepage hero section +- **THEN** they SHALL encounter at least one sentence they can understand without Python or CLI + expertise (e.g. "Point it at your code. Get a score and a list of what to fix.") +- **AND** the first technical term they encounter SHALL be a command they can copy and run, + not a concept they need to research first + diff --git a/openspec/specs/entrypoint-onboarding/spec.md b/openspec/specs/entrypoint-onboarding/spec.md index b3c39d27..df614d05 100644 --- a/openspec/specs/entrypoint-onboarding/spec.md +++ b/openspec/specs/entrypoint-onboarding/spec.md @@ -5,29 +5,46 @@ TBD - created by archiving change docs-14-first-contact-story-and-onboarding. Up ## Requirements ### Requirement: One primary fast-start path -The central entry points SHALL provide one primary “start here now” path before branching into more -specialized persona or workflow guidance. - -#### Scenario: User wants to try SpecFact immediately - -- **WHEN** a first-time visitor reaches the primary getting-started section -- **THEN** the page SHALL provide one recommended install-and-first-run path -- **AND** that path SHALL appear before alternative personas, workflow branches, or topology details -- **AND** the path SHALL make the first value explicit rather than only listing commands +The central entry points SHALL provide one primary "start here now" path before branching into more +specialized persona or workflow guidance. The fast-start path SHALL be inline on the homepage — it +SHALL NOT require the user to navigate to a separate page to obtain the first working command. +The primary command in the fast-start path SHALL be `specfact code review run` invoked via uvx, +as this is the highest-value, lowest-friction entry point for the broadest new-user audience. + +#### Scenario: Vibe coder arrives at the homepage + +- **WHEN** a first-time visitor who heard "validate your vibe code with specfact" lands on the + homepage +- **THEN** the page SHALL display the 2-command uvx sequence as the first actionable content: + `uvx specfact-cli init --profile solo-developer` followed by + `uvx specfact-cli code review run --path . --scope full` +- **AND** the sequence SHALL appear before path cards, module navigation, or architecture content +- **AND** the expected result (score + categorised findings) SHALL be described so the user knows + what "success" looks like + +#### Scenario: User can complete the first run without leaving the homepage + +- **WHEN** a first-time visitor reads the homepage without clicking any link +- **THEN** they SHALL find all commands needed to run their first code review +- **AND** no navigation to installation.md, quickstart.md, or modules.specfact.io SHALL be required + to obtain and run those commands ### Requirement: Choose-your-path guidance follows the first-run path After the primary fast-start path, entry points SHALL route users into the most relevant next step -for their intent. +for their intent. Path options SHALL be described as user outcomes in plain language that a +non-Python-expert can understand. #### Scenario: User needs the right next path - **WHEN** the user completes or reviews the first-run path -- **THEN** the entry point SHALL offer clear next-step options for at least: - - greenfield or AI-assisted development that needs stronger validation - - brownfield or legacy code understanding and reverse-engineering - - backlog/spec/code alignment workflows -- **AND** each option SHALL describe the user outcome, not just the internal command group +- **THEN** the entry point SHALL offer clear next-step options including at least: + - reviewing existing code immediately (the `code review run` path) + - setting up IDE slash-command workflows with a supported copilot + - enabling a pre-commit or CI validation gate +- **AND** each card heading SHALL describe what the user will do or get, not a product persona + or internal module taxonomy +- **AND** card descriptions SHALL use vocabulary understandable without Python or CLI expertise ### Requirement: Brownfield path explains the spec-first handoff diff --git a/openspec/specs/first-contact-story/spec.md b/openspec/specs/first-contact-story/spec.md index 93aedb63..89a61b20 100644 --- a/openspec/specs/first-contact-story/spec.md +++ b/openspec/specs/first-contact-story/spec.md @@ -6,31 +6,36 @@ TBD - created by archiving change docs-14-first-contact-story-and-onboarding. Up ### Requirement: Canonical first-contact product story The repository and documentation entry points SHALL present one canonical product story that answers -the first-contact questions in a consistent order: +the first-contact questions for both vibe coders and experienced developers. The hero statement SHALL +use plain language that works for a developer who does not know Python packaging — not just for +someone already familiar with contracts, modules, and runtimes. -- what SpecFact is -- why it exists -- why a user should care -- what value the user gets -- how to start +The canonical answer to "what is SpecFact?" SHALL describe what the user gets immediately +("a score and a list of what to fix") before explaining how it is achieved internally. -The canonical answer to “what is SpecFact?” SHALL define it as a validation and alignment layer for -software delivery, not merely as a collection of commands or integrations. +#### Scenario: Vibe coder reads the homepage hero -#### Scenario: User reads the README hero - -- **WHEN** a first-time visitor lands on `README.md` -- **THEN** the page SHALL answer “what is SpecFact?” in one concise identity statement -- **AND** the answer SHALL appear before topology, module ownership, or migration detail -- **AND** the identity statement SHALL make validation/alignment central and present “keep things in - sync” as the outcome rather than the only definition +- **WHEN** a developer who primarily uses AI-assisted or no-code tools reads the homepage hero +- **THEN** the first sentence SHALL describe an outcome they will recognise + (e.g. "Point it at your code. Get a score and a list of what to fix.") +- **AND** the hero SHALL NOT open with "validation and alignment layer", "runtime contracts", + or any other phrase that requires prior familiarity with the product #### Scenario: User compares repo and docs entry points - **WHEN** a user reads the repo README and the core docs homepage -- **THEN** both entry points SHALL describe the same core product identity -- **AND** they SHALL not give conflicting first impressions about whether SpecFact is primarily a CLI, - a module platform, an AI tool, or a backlog tool +- **THEN** both SHALL describe the same core product identity +- **AND** they SHALL NOT give conflicting first impressions about whether SpecFact is primarily + a CLI, a module platform, an AI tool, or a backlog tool + +#### Scenario: Hero statement pairs identity with a concrete, time-bounded outcome + +- **WHEN** a first-time visitor reads the hero on the docs homepage or README +- **THEN** the primary headline or subheadline SHALL communicate a concrete achievable outcome + with a time signal (e.g. "See what's wrong with your code in 10 seconds") +- **AND** the outcome statement SHALL appear before any explanation of internal architecture, + module system, or platform topology +- **AND** the hero SHALL include or link directly to the runnable 2-command uvx sequence ### Requirement: First-contact story explains the four product pressures @@ -52,14 +57,25 @@ pressures it addresses. ### Requirement: Headline and proof-point separation First-contact surfaces SHALL keep the primary identity statement separate from supporting proof -points such as greenfield/brownfield support, SDD/TDD/contracts, AI-copilot compatibility, -reverse-engineering support, and module extensibility. +points. Platform-internal vocabulary SHALL NOT appear in the hero or primary identity statement. +The hero SHALL work for a non-Python-expert; advanced vocabulary may appear in proof-point +sections below the hero. #### Scenario: User scans the first screen - **WHEN** a user scans the first screen of the README or docs homepage - **THEN** the primary message SHALL fit in a short headline/subheadline structure -- **AND** secondary capability claims SHALL appear as proof points rather than headline overload +- **AND** secondary capability claims (contracts, SDD/TDD, brownfield, module extensibility) + SHALL appear as proof points after the hero, not as headline overload +- **AND** platform-internal architectural terms SHALL NOT appear in the above-the-fold hero + +#### Scenario: Experienced developer also finds their next step + +- **WHEN** an experienced Python developer reads the homepage after the hero section +- **THEN** they SHALL find links to the pip installation path, profile options, and deeper + technical documentation without needing to search for them +- **AND** the progressive depth SHALL be clearly layered: vibe-coder entry → developer setup → + advanced configuration ### Requirement: Future enterprise direction reinforces seriousness without narrowing adoption diff --git a/openspec/specs/first-run-selection/spec.md b/openspec/specs/first-run-selection/spec.md index 007af94f..eef034ec 100644 --- a/openspec/specs/first-run-selection/spec.md +++ b/openspec/specs/first-run-selection/spec.md @@ -5,7 +5,10 @@ TBD - created by archiving change module-migration-01-categorize-and-group. Upda ## Requirements ### Requirement: `specfact init` detects first-run and presents bundle selection -On a fresh install where no bundles are installed, `specfact init` SHALL present an interactive bundle selection UI. +On a fresh install where no bundles are installed, `specfact init` SHALL present an interactive +bundle selection UI. When `--profile` is provided, `specfact init` SHALL install the profile's +canonical bundle set without requiring user interaction, and SHALL exit successfully only after +the bundles are fully installed and registered — not merely after runtime bootstrap. #### Scenario: First-run interactive bundle selection in Copilot mode @@ -23,6 +26,24 @@ On a fresh install where no bundles are installed, `specfact init` SHALL present - **AND** SHALL offer profile preset shortcuts: Solo developer, Backlog team, API-first team, Enterprise full-stack - **AND** SHALL install the user-selected bundles before completing workspace initialisation +#### Scenario: `init --profile` installs all profile bundles before completion + +- **GIVEN** a fresh SpecFact install with no bundles installed +- **WHEN** the user runs `specfact init --profile solo-developer` +- **THEN** the CLI SHALL invoke the module installer for each bundle in the profile's canonical set +- **AND** SHALL NOT report "Bootstrap complete" until all profile bundles are installed and their + commands are available in the CLI surface +- **AND** after the command completes, running `specfact code review run --help` SHALL succeed + without a "Command not installed" error + +#### Scenario: `init --profile` via uvx installs modules at user level + +- **GIVEN** the user is running via `uvx specfact-cli` +- **WHEN** they run `uvx specfact-cli init --profile solo-developer` +- **THEN** the CLI SHALL install profile bundles to the user-level module root + (e.g. `~/.specfact/modules/`) without requiring pip to be available in the uvx environment +- **AND** subsequent `uvx specfact-cli` invocations SHALL detect and load the installed modules + #### Scenario: User selects a profile preset during first-run - **GIVEN** the first-run interactive UI is displayed @@ -39,22 +60,6 @@ On a fresh install where no bundles are installed, `specfact init` SHALL present - **AND** SHALL display a tip: "Install bundles later with `specfact module install `" - **AND** SHALL complete workspace initialisation with only core commands available -#### Scenario: Second run of `specfact init` does not repeat first-run selection - -- **GIVEN** `specfact init` has been run previously and bundles are installed -- **WHEN** the user runs `specfact init` again -- **THEN** the CLI SHALL NOT show the bundle selection UI -- **AND** SHALL run the standard workspace re-initialisation flow - -#### Scenario: Workspace-local project-scoped modules suppress first-run flow - -- **GIVEN** a repository already contains category bundle modules under workspace-local `.specfact/modules` -- **AND** those modules are discovered with source `project` -- **WHEN** the user runs `specfact init` -- **THEN** first-run detection SHALL treat the workspace as already initialized -- **AND** the CLI SHALL NOT show first-run bundle selection again -- **AND** SHALL run the standard workspace re-initialisation flow - ### Requirement: `specfact init --profile ` installs a named preset non-interactively The system SHALL accept a `--profile ` argument on `specfact init` and MUST install the canonical bundle set for that profile without prompting, whether in CI/CD mode or interactive mode. diff --git a/openspec/specs/github-workflow/spec.md b/openspec/specs/github-workflow/spec.md new file mode 100644 index 00000000..9c27562c --- /dev/null +++ b/openspec/specs/github-workflow/spec.md @@ -0,0 +1,75 @@ +# github-workflow Specification + +## Purpose +TBD - created by archiving change ci-docs-sync-check. Update Purpose after archive. +## Requirements +### Requirement: Workflow File Structure +The system SHALL provide a GitHub Actions workflow file `.github/workflows/docs-sync.yml` with proper structure. + +#### Scenario: Valid workflow file +- **WHEN** workflow file is created +- **THEN** it SHALL have valid YAML structure +- **AND** follow GitHub Actions best practices + +#### Scenario: Workflow triggers +- **WHEN** workflow file is examined +- **THEN** it SHALL trigger on pull_request events +- **AND** target main and develop branches + +### Requirement: Workflow Steps +The workflow SHALL include all necessary steps for docs sync checking. + +#### Scenario: Checkout step +- **WHEN** workflow runs +- **THEN** first step SHALL checkout repository +- **AND** use fetch-depth: 0 for full history + +#### Scenario: Python setup step +- **WHEN** workflow runs +- **THEN** it SHALL setup Python environment +- **AND** install PyYAML dependency + +#### Scenario: Docs sync check step +- **WHEN** workflow runs +- **THEN** it SHALL execute docs sync script +- **AND** pass base/head references correctly + +### Requirement: Environment Configuration +The workflow SHALL properly configure the execution environment. + +#### Scenario: Python version +- **WHEN** workflow runs +- **THEN** it SHALL use Python 3.12 +- **AND** environment SHALL be properly configured + +#### Scenario: Dependency installation +- **WHEN** workflow runs +- **THEN** it SHALL install required dependencies +- **AND** handle installation errors appropriately + +### Requirement: Error Handling +The workflow SHALL handle errors appropriately. + +#### Scenario: Script execution failure +- **WHEN** docs sync script fails +- **THEN** workflow SHALL fail +- **AND** provide clear error output + +#### Scenario: Workflow timeout +- **WHEN** workflow exceeds timeout +- **THEN** it SHALL fail gracefully +- **AND** provide timeout information + +### Requirement: Output Formatting +The workflow SHALL provide well-formatted output. + +#### Scenario: Success output +- **WHEN** docs sync check passes +- **THEN** output SHALL show success message +- **AND** be clearly formatted + +#### Scenario: Failure output +- **WHEN** docs sync check fails +- **THEN** output SHALL show error details +- **AND** list stale documents clearly + diff --git a/openspec/specs/module-installation/spec.md b/openspec/specs/module-installation/spec.md index 05f1db27..b0f5a6e2 100644 --- a/openspec/specs/module-installation/spec.md +++ b/openspec/specs/module-installation/spec.md @@ -67,17 +67,96 @@ The system SHALL provide `specfact module list` command that displays modules fr ### Requirement: Upgrade command updates installed modules -The system SHALL provide `specfact module upgrade ` command that upgrades marketplace modules to latest version. +The system SHALL provide `specfact module upgrade [module-names...]` command that upgrades one or +more marketplace modules to their latest version. The command SHALL accept zero or more positional +module name arguments: no arguments upgrades all marketplace modules; one or more names restricts +the upgrade to only the named modules. -#### Scenario: Upgrade marketplace module -- **WHEN** user runs `specfact module upgrade backlog` +The upgrade output SHALL distinguish between modules that were actually upgraded to a new version +and modules that were already at the latest version. Showing `0.41.16 -> 0.41.16` when no version +change occurred is incorrect and SHALL NOT happen. + +While the registry index is being fetched or a module is being installed, the CLI SHALL show visible +progress (for example a Rich status spinner) so the user knows work is ongoing. Rich progress MAY +be suppressed in automated test environments. + +Before upgrading any module where the latest registry version has a higher major version than the +installed version, the CLI SHALL warn the user and require confirmation, because major version +bumps may contain breaking changes. + +#### Scenario: Upgrade shows progress during registry fetch and install + +- **WHEN** user runs `specfact module upgrade` and the registry fetch or an install takes noticeable time +- **THEN** the CLI SHALL show visible progress during fetch and during each module install + +#### Scenario: Upgrade warns when registry index is unavailable + +- **WHEN** the registry index cannot be fetched (offline or network error) +- **THEN** the CLI SHALL print a clear warning that the registry is unavailable +- **AND** SHALL continue using installed metadata where possible for the upgrade decision + +#### Scenario: Upgrade a single named module to a newer minor/patch version + +- **WHEN** user runs `specfact module upgrade backlog` and `0.42.0` is available (current `0.41.16`) - **THEN** system SHALL fetch registry index -- **AND** SHALL check if newer version available -- **AND** SHALL download and install newer version -- **AND** SHALL remove old version after successful install +- **AND** SHALL confirm a newer version exists +- **AND** SHALL install the newer version without prompting (minor/patch, not a major bump) +- **AND** SHALL output `backlog: 0.41.16 -> 0.42.0` + +#### Scenario: Upgrade multiple named modules selectively + +- **WHEN** user runs `specfact module upgrade backlog codebase` +- **THEN** system SHALL upgrade only `backlog` and `codebase` +- **AND** SHALL NOT upgrade any other installed modules +- **AND** SHALL report each module's result independently + +#### Scenario: Upgrade when module is already at latest version + +- **WHEN** user runs `specfact module upgrade backlog` and no newer version is available +- **THEN** system SHALL NOT reinstall the module +- **AND** SHALL output `backlog: already up to date (0.41.16)` or equivalent +- **AND** SHALL NOT output `backlog: 0.41.16 -> 0.41.16` + +#### Scenario: Upgrade all modules — mixed result (some upgraded, some current) + +- **WHEN** user runs `specfact module upgrade` with no arguments (all modules) +- **AND** some modules have newer versions and some do not +- **THEN** the output SHALL have two sections: + - `Upgraded:` listing only modules where the version actually changed + - `Already up to date:` listing modules that were already at the latest version +- **AND** if no modules were upgraded, the output SHALL say "All modules are up to date" + and SHALL NOT show any `X -> X` lines + +#### Scenario: Upgrade detects a breaking major version bump and prompts + +- **GIVEN** module `backlog` is installed at version `0.41.16` +- **AND** the registry offers version `1.0.0` as the latest +- **WHEN** user runs `specfact module upgrade backlog` in an interactive terminal +- **THEN** the CLI SHALL print a warning: + `backlog: 0.41.16 -> 1.0.0 is a MAJOR version upgrade and may contain breaking changes.` +- **AND** SHALL prompt: `Upgrade anyway? [y/N]` +- **AND** SHALL only proceed if the user confirms with `y` or `Y` +- **AND** if the user declines, SHALL skip that module and continue with remaining targets + +#### Scenario: Breaking major version upgrade bypassed with --yes flag + +- **GIVEN** module `backlog` has a major version bump available +- **WHEN** user runs `specfact module upgrade backlog --yes` +- **THEN** the CLI SHALL upgrade without prompting +- **AND** SHALL print the warning line but not the confirmation prompt + +#### Scenario: Breaking major version upgrade skipped silently in CI/CD mode -#### Scenario: Upgrade reinstalls when module already exists -- **WHEN** user runs `specfact module upgrade backlog` and backlog is already installed +- **GIVEN** the CLI is running in CI/CD (non-interactive) mode +- **AND** a module has a major version bump available +- **WHEN** user runs `specfact module upgrade` without `--yes` +- **THEN** the CLI SHALL skip the module with a warning: + `backlog: skipped — major version bump (0.41.16 -> 1.0.0). Re-run with --yes to upgrade.` +- **AND** SHALL exit 0 if all non-skipped modules succeeded + +#### Scenario: Upgrade reinstalls when newer version is available + +- **WHEN** a newer non-breaking version is available and the module is already installed - **THEN** system SHALL replace existing installed files with the upgraded package - **AND** SHALL NOT no-op due to existing install marker files @@ -106,3 +185,57 @@ The system SHALL extend install command to resolve pip dependencies across all m - **AND** SHALL log warning about potential conflicts - **AND** SHALL proceed with installation +### Requirement: Install command accepts multiple module IDs in one invocation + +The system SHALL allow `specfact module install` to accept one or more module IDs as positional +arguments so users can install several modules in a single command, consistent with the UX of +standard package managers (apt, pip, brew, npm). + +#### Scenario: User installs multiple modules at once + +- **WHEN** user runs `specfact module install nold-ai/specfact-codebase nold-ai/specfact-code-review` +- **THEN** the system SHALL install all listed modules in sequence +- **AND** SHALL print an install confirmation line for each module +- **AND** SHALL stop and report failure if any module install fails, leaving already-installed + modules in place + +#### Scenario: User installs a single module (existing behaviour unchanged) + +- **WHEN** user runs `specfact module install nold-ai/specfact-codebase` +- **THEN** the system SHALL install the module exactly as before +- **AND** existing flags (`--scope`, `--source`, `--reinstall`, `--force`, `--skip-deps`) SHALL + apply to all modules in the invocation + +#### Scenario: Multi-install with one already-satisfied module + +- **WHEN** user runs `specfact module install A B` and A is already installed +- **THEN** the system SHALL skip A with the existing "already installed" message +- **AND** SHALL still install B +- **AND** SHALL exit 0 if all non-skipped installs succeed + +### Requirement: Uninstall command accepts multiple module names in one invocation + +The system SHALL allow `specfact module uninstall` to accept one or more module names as positional +arguments so users can remove several modules in a single command, consistent with the multi-install +behaviour and the UX of standard package managers. + +#### Scenario: User uninstalls multiple modules at once + +- **WHEN** user runs `specfact module uninstall nold-ai/specfact-codebase nold-ai/specfact-code-review` +- **THEN** the system SHALL uninstall all listed modules in sequence +- **AND** SHALL print an uninstall confirmation line for each module +- **AND** SHALL continue with remaining modules if one fails, then exit non-zero + +#### Scenario: User uninstalls a single module (existing behaviour unchanged) + +- **WHEN** user runs `specfact module uninstall nold-ai/specfact-codebase` +- **THEN** the system SHALL uninstall the module exactly as before +- **AND** existing flags (`--scope`, `--repo`) SHALL apply to all modules in the invocation + +#### Scenario: Multi-uninstall with one module not installed + +- **WHEN** user runs `specfact module uninstall A B` and A is not installed +- **THEN** the system SHALL report that A is not found +- **AND** SHALL still attempt to uninstall B +- **AND** SHALL exit non-zero if any module failed or was not found + diff --git a/openspec/specs/profile-presets/spec.md b/openspec/specs/profile-presets/spec.md index 1c960948..c698beaa 100644 --- a/openspec/specs/profile-presets/spec.md +++ b/openspec/specs/profile-presets/spec.md @@ -36,61 +36,60 @@ On a fresh install with no bundles installed, `specfact init` SHALL NOT complete ### Requirement: Profile presets are fully activated and install bundles from the marketplace -The four profile presets SHALL resolve to the exact canonical bundle set and install each bundle via the marketplace installer. Profiles are now the primary onboarding path. +The four profile presets SHALL resolve to the exact canonical bundle set and install each bundle +via the marketplace installer. The `solo-developer` profile SHALL include +`nold-ai/specfact-code-review` so that `specfact code review run` is available immediately after +running `specfact init --profile solo-developer`. -#### Scenario: solo-developer profile installs specfact-codebase +#### Scenario: solo-developer profile installs codebase and code-review bundles -- **GIVEN** a fresh specfact-cli install +- **GIVEN** a fresh SpecFact install or an install where specfact-codebase and specfact-code-review + are not yet installed - **WHEN** the user runs `specfact init --profile solo-developer` -- **THEN** the CLI SHALL install `specfact-codebase` from the marketplace registry (no interaction required) -- **AND** SHALL confirm: "Installed: specfact-codebase (codebase quality bundle)" -- **AND** SHALL exit 0 -- **AND** `specfact code --help` SHALL resolve after init completes +- **THEN** the CLI SHALL install `nold-ai/specfact-codebase` from the marketplace registry +- **AND** SHALL install `nold-ai/specfact-code-review` from the marketplace registry +- **AND** SHALL confirm: "Installed: specfact-codebase, specfact-code-review" +- **AND** after completion, `specfact code review run --path . --scope full` SHALL be available + and produce a scored review result #### Scenario: backlog-team profile installs three bundles in dependency order -- **GIVEN** a fresh specfact-cli install +- **GIVEN** a fresh SpecFact install - **WHEN** the user runs `specfact init --profile backlog-team` - **THEN** the CLI SHALL install: `specfact-project`, `specfact-backlog`, `specfact-codebase` -- **AND** SHALL install `specfact-project` before `specfact-backlog` (no explicit cross-bundle dependency, but installation order matches the canonical profile definition) -- **AND** SHALL confirm each installed bundle -- **AND** SHALL exit 0 +- **AND** SHALL install `specfact-project` before `specfact-backlog` -#### Scenario: api-first-team profile installs spec and codebase bundles (with project as transitive dep) +#### Scenario: api-first-team profile installs spec and codebase bundles -- **GIVEN** a fresh specfact-cli install +- **GIVEN** a fresh SpecFact install - **WHEN** the user runs `specfact init --profile api-first-team` - **THEN** the CLI SHALL install: `specfact-spec`, `specfact-codebase` -- **AND** `specfact-project` SHALL be auto-installed as a bundle-level dependency of `specfact-spec` -- **AND** the CLI SHALL inform: "Installing specfact-project as required dependency of specfact-spec" -- **AND** SHALL exit 0 +- **AND** `specfact-project` SHALL be auto-installed if required as a transitive dependency #### Scenario: enterprise-full-stack profile installs all five bundles -- **GIVEN** a fresh specfact-cli install +- **GIVEN** a fresh SpecFact install - **WHEN** the user runs `specfact init --profile enterprise-full-stack` -- **THEN** the CLI SHALL install all five bundles: `specfact-project`, `specfact-backlog`, `specfact-codebase`, `specfact-spec`, `specfact-govern` -- **AND** `specfact-project` SHALL be installed before `specfact-spec` and `specfact-govern` (dependency order) -- **AND** SHALL exit 0 -- **AND** `specfact --help` SHALL show all 8 top-level commands (3 core + 5 category groups) +- **THEN** the CLI SHALL install all five bundles: + `specfact-project`, `specfact-backlog`, `specfact-codebase`, `specfact-spec`, `specfact-govern` -#### Scenario: Profile preset map is exhaustive and canonical +#### Scenario: Profile canonical bundle mapping is machine-verifiable - **GIVEN** a request for any valid profile name - **WHEN** `specfact init --profile ` is executed -- **THEN** the installed bundle set SHALL match exactly: - - `solo-developer` → `[specfact-codebase]` +- **THEN** the resolved bundle set SHALL be: + - `solo-developer` → `[specfact-codebase, specfact-code-review]` - `backlog-team` → `[specfact-project, specfact-backlog, specfact-codebase]` - - `api-first-team` → `[specfact-spec, specfact-codebase]` (specfact-project auto-installed as dep) + - `api-first-team` → `[specfact-spec, specfact-codebase]` - `enterprise-full-stack` → `[specfact-project, specfact-backlog, specfact-codebase, specfact-spec, specfact-govern]` - **AND** no profile SHALL install bundles outside its canonical set #### Scenario: Invalid profile name produces actionable error - **GIVEN** the user runs `specfact init --profile unknown-profile` -- **WHEN** `specfact init` processes the argument -- **THEN** the CLI SHALL print an error listing valid profile names: solo-developer, backlog-team, api-first-team, enterprise-full-stack -- **AND** SHALL exit with a non-zero exit code (1) +- **WHEN** the CLI processes the command +- **THEN** the CLI SHALL print an error listing valid profile names: + solo-developer, backlog-team, api-first-team, enterprise-full-stack ### Requirement: First-use guard prevents non-core command execution before any bundle is installed diff --git a/openspec/specs/project-codebase-ownership/spec.md b/openspec/specs/project-codebase-ownership/spec.md index 4f1f4107..6543d29e 100644 --- a/openspec/specs/project-codebase-ownership/spec.md +++ b/openspec/specs/project-codebase-ownership/spec.md @@ -38,7 +38,7 @@ Subsystems that implement code-first brownfield analysis SHALL have one document ### Requirement: Pending Changes Must Align With The Ownership Decision -Pending OpenSpec changes that touch command surface, docs, prompts, or migration cleanup SHALL align with the canonical `project` versus `codebase` ownership model. +Pending OpenSpec changes that touch command surface, docs, prompts, migration cleanup, or issue planning SHALL align with the canonical post-migration ownership model instead of reintroducing monolithic `specfact-cli` module ownership by implication. #### Scenario: Active change does not finalize conflicting import ownership - **GIVEN** an active pending change updates grouped command paths or release-facing docs @@ -46,3 +46,9 @@ Pending OpenSpec changes that touch command surface, docs, prompts, or migration - **THEN** it references the canonical owner defined by this change - **AND** it does not re-establish a conflicting public command path or subsystem owner by implication. +#### Scenario: Active proposal does not preserve obsolete in-repo module paths +- **GIVEN** an active proposal still describes implementation under `modules//` in `specfact-cli` for a capability now owned by a bundle in `specfact-cli-modules` +- **WHEN** maintainers reconcile the proposal against the current architecture +- **THEN** the proposal is updated to the correct repository and bundle ownership model +- **AND** any remaining core-repo scope is reduced to the shared runtime, contract, or integration surface that core still owns. + diff --git a/openspec/specs/readme-first-contact/spec.md b/openspec/specs/readme-first-contact/spec.md new file mode 100644 index 00000000..f8d08177 --- /dev/null +++ b/openspec/specs/readme-first-contact/spec.md @@ -0,0 +1,69 @@ +# readme-first-contact Specification + +## Purpose +TBD - created by archiving change readme-star-conversion-01. Update Purpose after archive. +## Requirements +### Requirement: README hero leads with developer outcome and runnable proof + +The repository README SHALL lead with a developer-facing value proposition and a runnable quickstart +before platform, module-system, or governance explanation. A first-time visitor must be able to +understand what SpecFact does and how to try it without scrolling through architecture prose. + +#### Scenario: Visitor reads only the first screen of the README + +- **WHEN** a first-time visitor opens `README.md` +- **THEN** the title SHALL be followed by a short, concrete value statement for developers +- **AND** badges SHALL appear directly under the title / tagline block +- **AND** the README SHALL show a uvx-based quickstart in the first screenful +- **AND** the README SHALL include a visible CTA inviting the user to star the repo if the output is + useful + +#### Scenario: README defers enterprise framing + +- **WHEN** a user scans the README from the top +- **THEN** enterprise, governance, module-marketplace, and architecture framing SHALL appear only + after the quickstart, sample output, and concrete feature summary +- **AND** the README SHALL still preserve those deeper sections further down the page + +### Requirement: README includes real sample output with reproducible evidence + +The README SHALL include a sample output block derived from a real `specfact code review run` +capture, not hand-written illustrative output. The proof block SHALL help the reader mentally +simulate running the command. + +#### Scenario: Visitor evaluates whether the tool feels real + +- **WHEN** a visitor reads the quickstart section +- **THEN** the README SHALL display a sample output block that includes a verdict, a score or status, + file-level findings, and an evidence bundle path +- **AND** the output SHALL be sourced from a checked-in capture artifact under + `docs/_support/readme-first-contact/sample-output/` +- **AND** the repo SHALL include a capture script that reproduces or refreshes the stored output + +### Requirement: README explains value before deep product detail + +The README SHALL include an explicit "what it does" summary for developers before it explains +organizational workflows, module ownership, or documentation topology. + +#### Scenario: Visitor wants concrete reasons to care + +- **WHEN** the visitor reaches the section immediately after the quickstart and proof block +- **THEN** the README SHALL summarize the product in concrete outcome bullets +- **AND** those bullets SHALL focus on developer-visible outcomes such as review, validation, drift + detection, offline use, and backlog/code alignment +- **AND** deeper sections for pipeline story, team use, module system, and documentation topology + SHALL appear later on the page + +### Requirement: README shows adoption path beyond the hero + +The README SHALL provide copy-pasteable adoption examples for local hooks and CI without forcing the +reader into the full documentation set first. + +#### Scenario: Visitor wants to move from trial to workflow + +- **WHEN** a developer finds the quickstart useful +- **THEN** the README SHALL include a short pre-commit or GitHub Actions snippet near the upper half + of the document +- **AND** the README SHALL include a brief "How SpecFact is built" or equivalent trust section that + explains the repo's OpenSpec -> TDD -> quality-gate workflow in plain language +