From 10942804f7b240ae45ee1b373d9a1a82f18e2d0d Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Sat, 6 Jun 2026 23:45:13 +0200 Subject: [PATCH 1/3] chore: reposition modules roadmap around validation --- openspec/CHANGE_ORDER.md | 280 ++++++++++-------- .../proposal.md | 122 ++------ .../.openspec.yaml | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/clean-code-analysis/spec.md | 2 +- .../spec.md | 2 +- .../specs/review-finding-model/spec.md | 0 .../specs/review-run-command/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../guided-simplification-review/spec.md | 0 .../specs/review-finding-model/spec.md | 0 .../specs/review-run-command/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../README.md | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/ai-ide-remediation-handoff/spec.md | 0 .../specs/cleanup-forecast-review/spec.md | 0 .../specs/review-finding-model/spec.md | 0 .../specs/review-run-command/spec.md | 0 .../tasks.md | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../code-review-ai-bloat-detection/spec.md | 1 - .../tasks.md | 0 .../.openspec.yaml | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/bundle-packaged-resources/spec.md | 0 .../specs/codebase-import-runtime/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/bundle-overview-pages/spec.md | 2 +- .../modules-docs-command-validation/spec.md | 2 +- .../specs/modules-docs-publishing/spec.md | 2 +- .../modules-pre-commit-quality-parity/spec.md | 2 +- .../specs/review-run-command/spec.md | 2 +- .../tasks.md | 0 .../.openspec.yaml | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/ci-integration/spec.md | 0 .../ci-module-signing-on-approval/spec.md | 0 .../tasks.md | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/project-command-surface/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../CHANGE_VALIDATION.md | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/backlog-add/spec.md | 0 .../specs/backlog-sync/spec.md | 0 .../runtime-artifact-write-safety/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../TDD_EVIDENCE.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/bundle-packaged-resources/spec.md | 0 .../specs/prompt-command-validation/spec.md | 0 .../specs/resource-aware-integrity/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../TDD_EVIDENCE.md | 0 .../proposal.md | 0 .../specs/backlog-delta/spec.md | 2 +- .../code-review-tool-dependencies/spec.md | 2 +- .../specs/module-cli-error-contract/spec.md | 0 .../specs/module-command-overview/spec.md | 0 .../modules-docs-command-validation/spec.md | 2 +- .../tasks.md | 0 .../governance-01-evidence-output/proposal.md | 83 ++---- .../openspec-01-intent-trace/proposal.md | 59 ++-- .../proposal.md | 122 ++------ .../requirements-03-backlog-sync/proposal.md | 52 ++-- .../proposal.md | 109 ++----- .../validation-02-full-chain-engine/design.md | 8 +- .../proposal.md | 104 ++----- .../validation-02-full-chain-engine/tasks.md | 4 +- openspec/parking-lot/README.md | 92 +++--- .../CHANGE_VALIDATION.md | 0 .../proposal.md | 0 .../specs/kanban-flow/spec.md | 0 .../backlog-kanban-01-flow-metrics/tasks.md | 0 .../CHANGE_VALIDATION.md | 0 .../backlog-safe-01-pi-planning/proposal.md | 0 .../specs/safe-pi/spec.md | 0 .../backlog-safe-01-pi-planning/tasks.md | 0 .../CHANGE_VALIDATION.md | 0 .../backlog-safe-02-risk-rollups/proposal.md | 0 .../specs/risk-rollups/spec.md | 0 .../backlog-safe-02-risk-rollups/tasks.md | 0 .../CHANGE_VALIDATION.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/sprint-planning/spec.md | 0 .../backlog-scrum-02-sprint-planning/tasks.md | 0 .../CHANGE_VALIDATION.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/story-complexity/spec.md | 0 .../tasks.md | 0 .../CHANGE_VALIDATION.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/definition-of-done/spec.md | 0 .../tasks.md | 0 .../.openspec.yaml | 0 .../CHANGE_VALIDATION.md | 0 .../design.md | 0 .../proposal.md | 0 .../specs/backlog-refinement/spec.md | 0 .../ceremony-requirements-awareness/spec.md | 0 .../specs/daily-standup/spec.md | 0 .../tasks.md | 0 .../specs/ai-ide-remediation-handoff/spec.md | 23 ++ openspec/specs/backlog-add/spec.md | 18 ++ openspec/specs/backlog-delta/spec.md | 18 ++ openspec/specs/backlog-sync/spec.md | 20 +- openspec/specs/bundle-overview-pages/spec.md | 26 ++ .../specs/bundle-packaged-resources/spec.md | 30 +- openspec/specs/ci-integration/spec.md | 3 +- .../ci-module-signing-on-approval/spec.md | 11 +- openspec/specs/clean-code-analysis/spec.md | 16 + .../specs/cleanup-forecast-review/spec.md | 44 +++ .../code-review-ai-bloat-detection/spec.md | 103 +++++++ .../spec.md | 81 +++++ .../code-review-tool-dependencies/spec.md | 18 ++ .../specs/codebase-import-runtime/spec.md | 59 ++++ .../guided-simplification-review/spec.md | 67 +++++ .../specs/module-cli-error-contract/spec.md | 41 +++ .../specs/module-command-overview/spec.md | 30 ++ .../modules-docs-command-validation/spec.md | 89 ++++++ .../specs/modules-docs-publishing/spec.md | 26 ++ .../modules-pre-commit-quality-parity/spec.md | 26 ++ .../specs/project-command-surface/spec.md | 13 + .../specs/prompt-command-validation/spec.md | 71 +++++ .../specs/resource-aware-integrity/spec.md | 11 +- openspec/specs/review-finding-model/spec.md | 73 +++-- openspec/specs/review-run-command/spec.md | 121 +++++--- .../runtime-artifact-write-safety/spec.md | 34 +++ 159 files changed, 1357 insertions(+), 771 deletions(-) rename openspec/changes/{code-review-11-simplification-feedback-loop => archive/2026-06-06-code-review-11-simplification-feedback-loop}/.openspec.yaml (100%) rename openspec/changes/{code-review-11-simplification-feedback-loop => archive/2026-06-06-code-review-11-simplification-feedback-loop}/TDD_EVIDENCE.md (100%) rename openspec/changes/{code-review-11-simplification-feedback-loop => archive/2026-06-06-code-review-11-simplification-feedback-loop}/design.md (100%) rename openspec/changes/{code-review-11-simplification-feedback-loop => archive/2026-06-06-code-review-11-simplification-feedback-loop}/proposal.md (100%) rename openspec/changes/{code-review-11-simplification-feedback-loop => archive/2026-06-06-code-review-11-simplification-feedback-loop}/specs/clean-code-analysis/spec.md (97%) rename openspec/changes/{code-review-11-simplification-feedback-loop => archive/2026-06-06-code-review-11-simplification-feedback-loop}/specs/code-review-simplification-feedback/spec.md (99%) rename openspec/changes/{code-review-11-simplification-feedback-loop => archive/2026-06-06-code-review-11-simplification-feedback-loop}/specs/review-finding-model/spec.md (100%) rename openspec/changes/{code-review-11-simplification-feedback-loop => archive/2026-06-06-code-review-11-simplification-feedback-loop}/specs/review-run-command/spec.md (100%) rename openspec/changes/{code-review-11-simplification-feedback-loop => archive/2026-06-06-code-review-11-simplification-feedback-loop}/tasks.md (100%) rename openspec/changes/{code-review-12-guided-simplification-enforcement => archive/2026-06-06-code-review-12-guided-simplification-enforcement}/.openspec.yaml (100%) rename openspec/changes/{code-review-12-guided-simplification-enforcement => archive/2026-06-06-code-review-12-guided-simplification-enforcement}/TDD_EVIDENCE.md (100%) rename openspec/changes/{code-review-12-guided-simplification-enforcement => archive/2026-06-06-code-review-12-guided-simplification-enforcement}/design.md (100%) rename openspec/changes/{code-review-12-guided-simplification-enforcement => archive/2026-06-06-code-review-12-guided-simplification-enforcement}/proposal.md (100%) rename openspec/changes/{code-review-12-guided-simplification-enforcement => archive/2026-06-06-code-review-12-guided-simplification-enforcement}/specs/guided-simplification-review/spec.md (100%) rename openspec/changes/{code-review-12-guided-simplification-enforcement => archive/2026-06-06-code-review-12-guided-simplification-enforcement}/specs/review-finding-model/spec.md (100%) rename openspec/changes/{code-review-12-guided-simplification-enforcement => archive/2026-06-06-code-review-12-guided-simplification-enforcement}/specs/review-run-command/spec.md (100%) rename openspec/changes/{code-review-12-guided-simplification-enforcement => archive/2026-06-06-code-review-12-guided-simplification-enforcement}/tasks.md (100%) rename openspec/changes/{code-review-13-cleanup-forecast-agent-handoff => archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff}/.openspec.yaml (100%) rename openspec/changes/{code-review-13-cleanup-forecast-agent-handoff => archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff}/README.md (100%) rename openspec/changes/{code-review-13-cleanup-forecast-agent-handoff => archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff}/TDD_EVIDENCE.md (100%) rename openspec/changes/{code-review-13-cleanup-forecast-agent-handoff => archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff}/design.md (100%) rename openspec/changes/{code-review-13-cleanup-forecast-agent-handoff => archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff}/proposal.md (100%) rename openspec/changes/{code-review-13-cleanup-forecast-agent-handoff => archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff}/specs/ai-ide-remediation-handoff/spec.md (100%) rename openspec/changes/{code-review-13-cleanup-forecast-agent-handoff => archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff}/specs/cleanup-forecast-review/spec.md (100%) rename openspec/changes/{code-review-13-cleanup-forecast-agent-handoff => archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff}/specs/review-finding-model/spec.md (100%) rename openspec/changes/{code-review-13-cleanup-forecast-agent-handoff => archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff}/specs/review-run-command/spec.md (100%) rename openspec/changes/{code-review-13-cleanup-forecast-agent-handoff => archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff}/tasks.md (100%) rename openspec/changes/{code-review-ai-bloat-detection => archive/2026-06-06-code-review-ai-bloat-detection}/TDD_EVIDENCE.md (100%) rename openspec/changes/{code-review-ai-bloat-detection => archive/2026-06-06-code-review-ai-bloat-detection}/design.md (100%) rename openspec/changes/{code-review-ai-bloat-detection => archive/2026-06-06-code-review-ai-bloat-detection}/proposal.md (100%) rename openspec/changes/{code-review-ai-bloat-detection => archive/2026-06-06-code-review-ai-bloat-detection}/specs/code-review-ai-bloat-detection/spec.md (99%) rename openspec/changes/{code-review-ai-bloat-detection => archive/2026-06-06-code-review-ai-bloat-detection}/tasks.md (100%) rename openspec/changes/{codebase-import-runtime-hardening => archive/2026-06-06-codebase-import-runtime-hardening}/.openspec.yaml (100%) rename openspec/changes/{codebase-import-runtime-hardening => archive/2026-06-06-codebase-import-runtime-hardening}/TDD_EVIDENCE.md (100%) rename openspec/changes/{codebase-import-runtime-hardening => archive/2026-06-06-codebase-import-runtime-hardening}/design.md (100%) rename openspec/changes/{codebase-import-runtime-hardening => archive/2026-06-06-codebase-import-runtime-hardening}/proposal.md (100%) rename openspec/changes/{codebase-import-runtime-hardening => archive/2026-06-06-codebase-import-runtime-hardening}/specs/bundle-packaged-resources/spec.md (100%) rename openspec/changes/{codebase-import-runtime-hardening => archive/2026-06-06-codebase-import-runtime-hardening}/specs/codebase-import-runtime/spec.md (100%) rename openspec/changes/{codebase-import-runtime-hardening => archive/2026-06-06-codebase-import-runtime-hardening}/tasks.md (100%) rename openspec/changes/{docs-15-code-review-validation-guardrails => archive/2026-06-06-docs-15-code-review-validation-guardrails}/.openspec.yaml (100%) rename openspec/changes/{docs-15-code-review-validation-guardrails => archive/2026-06-06-docs-15-code-review-validation-guardrails}/TDD_EVIDENCE.md (100%) rename openspec/changes/{docs-15-code-review-validation-guardrails => archive/2026-06-06-docs-15-code-review-validation-guardrails}/design.md (100%) rename openspec/changes/{docs-15-code-review-validation-guardrails => archive/2026-06-06-docs-15-code-review-validation-guardrails}/proposal.md (100%) rename openspec/changes/{docs-15-code-review-validation-guardrails => archive/2026-06-06-docs-15-code-review-validation-guardrails}/specs/bundle-overview-pages/spec.md (98%) rename openspec/changes/{docs-15-code-review-validation-guardrails => archive/2026-06-06-docs-15-code-review-validation-guardrails}/specs/modules-docs-command-validation/spec.md (99%) rename openspec/changes/{docs-15-code-review-validation-guardrails => archive/2026-06-06-docs-15-code-review-validation-guardrails}/specs/modules-docs-publishing/spec.md (98%) rename openspec/changes/{docs-15-code-review-validation-guardrails => archive/2026-06-06-docs-15-code-review-validation-guardrails}/specs/modules-pre-commit-quality-parity/spec.md (98%) rename openspec/changes/{docs-15-code-review-validation-guardrails => archive/2026-06-06-docs-15-code-review-validation-guardrails}/specs/review-run-command/spec.md (98%) rename openspec/changes/{docs-15-code-review-validation-guardrails => archive/2026-06-06-docs-15-code-review-validation-guardrails}/tasks.md (100%) rename openspec/changes/{marketplace-07-pr-auto-sign-updates => archive/2026-06-06-marketplace-07-pr-auto-sign-updates}/.openspec.yaml (100%) rename openspec/changes/{marketplace-07-pr-auto-sign-updates => archive/2026-06-06-marketplace-07-pr-auto-sign-updates}/TDD_EVIDENCE.md (100%) rename openspec/changes/{marketplace-07-pr-auto-sign-updates => archive/2026-06-06-marketplace-07-pr-auto-sign-updates}/design.md (100%) rename openspec/changes/{marketplace-07-pr-auto-sign-updates => archive/2026-06-06-marketplace-07-pr-auto-sign-updates}/proposal.md (100%) rename openspec/changes/{marketplace-07-pr-auto-sign-updates => archive/2026-06-06-marketplace-07-pr-auto-sign-updates}/specs/ci-integration/spec.md (100%) rename openspec/changes/{marketplace-07-pr-auto-sign-updates => archive/2026-06-06-marketplace-07-pr-auto-sign-updates}/specs/ci-module-signing-on-approval/spec.md (100%) rename openspec/changes/{marketplace-07-pr-auto-sign-updates => archive/2026-06-06-marketplace-07-pr-auto-sign-updates}/tasks.md (100%) rename openspec/changes/{project-02-plan-root-command-fix => archive/2026-06-06-project-02-plan-root-command-fix}/TDD_EVIDENCE.md (100%) rename openspec/changes/{project-02-plan-root-command-fix => archive/2026-06-06-project-02-plan-root-command-fix}/design.md (100%) rename openspec/changes/{project-02-plan-root-command-fix => archive/2026-06-06-project-02-plan-root-command-fix}/proposal.md (100%) rename openspec/changes/{project-02-plan-root-command-fix => archive/2026-06-06-project-02-plan-root-command-fix}/specs/project-command-surface/spec.md (100%) rename openspec/changes/{project-02-plan-root-command-fix => archive/2026-06-06-project-02-plan-root-command-fix}/tasks.md (100%) rename openspec/changes/{project-runtime-01-safe-artifact-write-policy => archive/2026-06-06-project-runtime-01-safe-artifact-write-policy}/.openspec.yaml (100%) rename openspec/changes/{project-runtime-01-safe-artifact-write-policy => archive/2026-06-06-project-runtime-01-safe-artifact-write-policy}/CHANGE_VALIDATION.md (100%) rename openspec/changes/{project-runtime-01-safe-artifact-write-policy => archive/2026-06-06-project-runtime-01-safe-artifact-write-policy}/TDD_EVIDENCE.md (100%) rename openspec/changes/{project-runtime-01-safe-artifact-write-policy => archive/2026-06-06-project-runtime-01-safe-artifact-write-policy}/design.md (100%) rename openspec/changes/{project-runtime-01-safe-artifact-write-policy => archive/2026-06-06-project-runtime-01-safe-artifact-write-policy}/proposal.md (100%) rename openspec/changes/{project-runtime-01-safe-artifact-write-policy => archive/2026-06-06-project-runtime-01-safe-artifact-write-policy}/specs/backlog-add/spec.md (100%) rename openspec/changes/{project-runtime-01-safe-artifact-write-policy => archive/2026-06-06-project-runtime-01-safe-artifact-write-policy}/specs/backlog-sync/spec.md (100%) rename openspec/changes/{project-runtime-01-safe-artifact-write-policy => archive/2026-06-06-project-runtime-01-safe-artifact-write-policy}/specs/runtime-artifact-write-safety/spec.md (100%) rename openspec/changes/{project-runtime-01-safe-artifact-write-policy => archive/2026-06-06-project-runtime-01-safe-artifact-write-policy}/tasks.md (100%) rename openspec/changes/{prompt-command-contract-validation => archive/2026-06-06-prompt-command-contract-validation}/.openspec.yaml (100%) rename openspec/changes/{prompt-command-contract-validation => archive/2026-06-06-prompt-command-contract-validation}/TDD_EVIDENCE.md (100%) rename openspec/changes/{prompt-command-contract-validation => archive/2026-06-06-prompt-command-contract-validation}/design.md (100%) rename openspec/changes/{prompt-command-contract-validation => archive/2026-06-06-prompt-command-contract-validation}/proposal.md (100%) rename openspec/changes/{prompt-command-contract-validation => archive/2026-06-06-prompt-command-contract-validation}/specs/bundle-packaged-resources/spec.md (100%) rename openspec/changes/{prompt-command-contract-validation => archive/2026-06-06-prompt-command-contract-validation}/specs/prompt-command-validation/spec.md (100%) rename openspec/changes/{prompt-command-contract-validation => archive/2026-06-06-prompt-command-contract-validation}/specs/resource-aware-integrity/spec.md (100%) rename openspec/changes/{prompt-command-contract-validation => archive/2026-06-06-prompt-command-contract-validation}/tasks.md (100%) rename openspec/changes/{tester-module-cli-reliability => archive/2026-06-06-tester-module-cli-reliability}/.openspec.yaml (100%) rename openspec/changes/{tester-module-cli-reliability => archive/2026-06-06-tester-module-cli-reliability}/TDD_EVIDENCE.md (100%) rename openspec/changes/{tester-module-cli-reliability => archive/2026-06-06-tester-module-cli-reliability}/proposal.md (100%) rename openspec/changes/{tester-module-cli-reliability => archive/2026-06-06-tester-module-cli-reliability}/specs/backlog-delta/spec.md (97%) rename openspec/changes/{tester-module-cli-reliability => archive/2026-06-06-tester-module-cli-reliability}/specs/code-review-tool-dependencies/spec.md (97%) rename openspec/changes/{tester-module-cli-reliability => archive/2026-06-06-tester-module-cli-reliability}/specs/module-cli-error-contract/spec.md (100%) rename openspec/changes/{tester-module-cli-reliability => archive/2026-06-06-tester-module-cli-reliability}/specs/module-command-overview/spec.md (100%) rename openspec/changes/{tester-module-cli-reliability => archive/2026-06-06-tester-module-cli-reliability}/specs/modules-docs-command-validation/spec.md (98%) rename openspec/changes/{tester-module-cli-reliability => archive/2026-06-06-tester-module-cli-reliability}/tasks.md (100%) rename openspec/{changes => parking-lot}/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md (100%) rename openspec/{changes => parking-lot}/backlog-kanban-01-flow-metrics/proposal.md (100%) rename openspec/{changes => parking-lot}/backlog-kanban-01-flow-metrics/specs/kanban-flow/spec.md (100%) rename openspec/{changes => parking-lot}/backlog-kanban-01-flow-metrics/tasks.md (100%) rename openspec/{changes => parking-lot}/backlog-safe-01-pi-planning/CHANGE_VALIDATION.md (100%) rename openspec/{changes => parking-lot}/backlog-safe-01-pi-planning/proposal.md (100%) rename openspec/{changes => parking-lot}/backlog-safe-01-pi-planning/specs/safe-pi/spec.md (100%) rename openspec/{changes => parking-lot}/backlog-safe-01-pi-planning/tasks.md (100%) rename openspec/{changes => parking-lot}/backlog-safe-02-risk-rollups/CHANGE_VALIDATION.md (100%) rename openspec/{changes => parking-lot}/backlog-safe-02-risk-rollups/proposal.md (100%) rename openspec/{changes => parking-lot}/backlog-safe-02-risk-rollups/specs/risk-rollups/spec.md (100%) rename openspec/{changes => parking-lot}/backlog-safe-02-risk-rollups/tasks.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-02-sprint-planning/CHANGE_VALIDATION.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-02-sprint-planning/design.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-02-sprint-planning/proposal.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-02-sprint-planning/tasks.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-03-story-complexity/CHANGE_VALIDATION.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-03-story-complexity/design.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-03-story-complexity/proposal.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-03-story-complexity/tasks.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-04-definition-of-done/CHANGE_VALIDATION.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-04-definition-of-done/design.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-04-definition-of-done/proposal.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md (100%) rename openspec/{changes => parking-lot}/backlog-scrum-04-definition-of-done/tasks.md (100%) rename openspec/{changes => parking-lot}/ceremony-02-requirements-aware-output/.openspec.yaml (100%) rename openspec/{changes => parking-lot}/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md (100%) rename openspec/{changes => parking-lot}/ceremony-02-requirements-aware-output/design.md (100%) rename openspec/{changes => parking-lot}/ceremony-02-requirements-aware-output/proposal.md (100%) rename openspec/{changes => parking-lot}/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md (100%) rename openspec/{changes => parking-lot}/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md (100%) rename openspec/{changes => parking-lot}/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md (100%) rename openspec/{changes => parking-lot}/ceremony-02-requirements-aware-output/tasks.md (100%) create mode 100644 openspec/specs/ai-ide-remediation-handoff/spec.md create mode 100644 openspec/specs/cleanup-forecast-review/spec.md create mode 100644 openspec/specs/code-review-ai-bloat-detection/spec.md create mode 100644 openspec/specs/code-review-simplification-feedback/spec.md create mode 100644 openspec/specs/codebase-import-runtime/spec.md create mode 100644 openspec/specs/guided-simplification-review/spec.md create mode 100644 openspec/specs/module-cli-error-contract/spec.md create mode 100644 openspec/specs/module-command-overview/spec.md create mode 100644 openspec/specs/project-command-surface/spec.md create mode 100644 openspec/specs/prompt-command-validation/spec.md create mode 100644 openspec/specs/runtime-artifact-write-safety/spec.md diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index 2db1d81f..1472a73d 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -1,125 +1,155 @@ -# OpenSpec change order by module and dependency - -## Implemented (archived) - -| Change | Status / Date | -|--------|---------------| -| ✅ backlog-02-migrate-core-commands | archived 2026-03-10 | -| ✅ backlog-bundle-local-source-alignment | archived 2026-03-10 | -| ✅ bugfix-backlog-html-export-validation | archived 2026-03-10 | -| ✅ modules-pre-commit-quality-parity | archived 2026-03-10 | -| ✅ registry-republish-outdated-bundles | archived 2026-03-10 | -| ✅ fix-issue-49-ado-provider-field-type-coercion | archived 2026-03-11 | -| ✅ code-review-02-ruff-radon-runners | archived 2026-03-17 | -| ✅ code-review-04-contract-test-runners | archived 2026-03-17 | -| ✅ code-review-07-house-rules-skill | archived 2026-03-17 | -| ✅ code-review-08-review-run-integration | archived 2026-03-17 | -| ✅ code-review-10-review-scope-modes | archived 2026-03-17 | -| ✅ docs-01-modules-docs-canonical-site | archived 2026-03-17 | -| ✅ fix-backlog-add-ado-custom-field-payload | archived 2026-03-17 | -| ✅ fix-backlog-add-work-item-type-mapping | archived 2026-03-17 | -| ✅ fix-backlog-provider-required-field-mappings | archived 2026-03-17 | -| ✅ review-run-dogfood-followup | archived 2026-03-17 | -| ✅ docs-cli-command-alignment | archived 2026-03-20 | -| ✅ docs-06-modules-site-ia-restructure | archived 2026-04-05 | -| ✅ docs-08-bundle-overview-pages | archived 2026-04-05 | -| ✅ docs-09-missing-command-docs | archived 2026-04-05 | -| ✅ docs-10-workflow-consolidation | archived 2026-04-05 | -| ✅ docs-11-team-enterprise-tier | archived 2026-04-05 | -| ✅ docs-12-docs-validation-ci | archived 2026-04-05 | -| ✅ clean-code-02-expanded-review-module | archived 2026-04-05 | -| ✅ docs-13-nav-search-theme-roles | archived 2026-04-05 | -| ✅ speckit-03-change-proposal-bridge | archived 2026-04-05 | -| ✅ packaging-01-bundle-resource-payloads | archived 2026-04-05 | -| ✅ module-bundle-deps-auto-install | archived 2026-04-05 | -| ✅ governance-03-github-hierarchy-cache | archived 2026-04-09 | -| ✅ marketplace-06-ci-module-signing | archived 2026-04-16; [#185](https://github.com/nold-ai/specfact-cli-modules/issues/185); paired core [specfact-cli#500](https://github.com/nold-ai/specfact-cli/issues/500) | - -## Pending - -### Backlog bundle runtime changes - -| Module | Order | Change folder | GitHub # | Blocked by | -|--------|-------|---------------|----------|------------| -| backlog-core | 00 | tester-module-cli-reliability | [#306](https://github.com/nold-ai/specfact-cli-modules/issues/306); source bugs [specfact-cli#586](https://github.com/nold-ai/specfact-cli/issues/586), [#587](https://github.com/nold-ai/specfact-cli/issues/587), [#588](https://github.com/nold-ai/specfact-cli/issues/588), [#590](https://github.com/nold-ai/specfact-cli/issues/590), [#591](https://github.com/nold-ai/specfact-cli/issues/591), [#592](https://github.com/nold-ai/specfact-cli/issues/592) | paired core `tester-cli-reliability`; Parent Feature: [#305](https://github.com/nold-ai/specfact-cli-modules/issues/305) | -| backlog-scrum | 02 | backlog-scrum-02-sprint-planning | [#160](https://github.com/nold-ai/specfact-cli-modules/issues/160) | Parent Feature: [#151](https://github.com/nold-ai/specfact-cli-modules/issues/151); shared backlog baseline from `specfact-cli#116` | -| backlog-scrum | 03 | backlog-scrum-03-story-complexity | [#153](https://github.com/nold-ai/specfact-cli-modules/issues/153) | Parent Feature: [#151](https://github.com/nold-ai/specfact-cli-modules/issues/151); shared backlog baseline from `specfact-cli#116` | -| backlog-scrum | 04 | backlog-scrum-04-definition-of-done | [#152](https://github.com/nold-ai/specfact-cli-modules/issues/152) | Parent Feature: [#151](https://github.com/nold-ai/specfact-cli-modules/issues/151); shared backlog baseline from `specfact-cli#116`; optional ceremony alias baseline `specfact-cli#185` | -| backlog-kanban | 01 | backlog-kanban-01-flow-metrics | [#155](https://github.com/nold-ai/specfact-cli-modules/issues/155) | Parent Feature: [#149](https://github.com/nold-ai/specfact-cli-modules/issues/149); shared backlog baseline from `specfact-cli#116` | -| backlog-safe | 01 | backlog-safe-01-pi-planning | [#154](https://github.com/nold-ai/specfact-cli-modules/issues/154) | Parent Feature: [#146](https://github.com/nold-ai/specfact-cli-modules/issues/146); shared backlog baseline from `specfact-cli#116` | -| backlog-safe | 02 | backlog-safe-02-risk-rollups | [#156](https://github.com/nold-ai/specfact-cli-modules/issues/156) | Parent Feature: [#146](https://github.com/nold-ai/specfact-cli-modules/issues/146); `#154`; integrates with `#160`, `#153`, and `#155` | -| policy | 02 | policy-02-packs-and-modes | [#158](https://github.com/nold-ai/specfact-cli-modules/issues/158) | Parent Feature: [#148](https://github.com/nold-ai/specfact-cli-modules/issues/148); shared policy/profile semantics from `specfact-cli#176` and `specfact-cli#237` | -| ceremony | 02 | ceremony-02-requirements-aware-output | [#159](https://github.com/nold-ai/specfact-cli-modules/issues/159) | Parent Feature: [#150](https://github.com/nold-ai/specfact-cli-modules/issues/150); requirements contracts from `specfact-cli#239`; ceremony alias baseline `specfact-cli#185` | - -### Project bundle runtime changes - -| Module | Order | Change folder | GitHub # | Blocked by | -|--------|-------|---------------|----------|------------| -| sync | 01 | sync-01-unified-kernel | [#157](https://github.com/nold-ai/specfact-cli-modules/issues/157) | Parent Feature: [#147](https://github.com/nold-ai/specfact-cli-modules/issues/147); preview/apply safety baseline from `specfact-cli#177` | -| project-runtime | 01 | project-runtime-01-safe-artifact-write-policy | [#177](https://github.com/nold-ai/specfact-cli-modules/issues/177) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); paired core change [specfact-cli#490](https://github.com/nold-ai/specfact-cli/issues/490); related bug [specfact-cli#487](https://github.com/nold-ai/specfact-cli/issues/487) | -| project-runtime | 02 | project-02-plan-root-command-fix | [#256](https://github.com/nold-ai/specfact-cli-modules/issues/256) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); blocked by #255 bug analysis context; no additional blockers | - -### Cross-layer runtime follow-ups - -These changes are the modules-side runtime companions to split core changes. Shared schemas, contracts, and cross-change semantics remain in `specfact-cli`. - -| Module | Order | Change folder | GitHub # | Blocked by | -|--------|-------|---------------|----------|------------| -| architecture | 01 | architecture-01-solution-layer | [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); core counterpart `specfact-cli#240`; shared models from `specfact-cli#238` and `specfact-cli#239` | -| requirements | 02 | requirements-02-module-commands | [#165](https://github.com/nold-ai/specfact-cli-modules/issues/165) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); core counterpart `specfact-cli#239`; data model baseline `specfact-cli#238` | -| requirements | 03 | requirements-03-backlog-sync | [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); core counterpart `specfact-cli#244`; runtime sync `#157`; requirements runtime `#165` | -| openspec | 01 | openspec-01-intent-trace | [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); core counterpart `specfact-cli#350`; requirements contracts from `specfact-cli#238` and `specfact-cli#239` | -| traceability | 01 | traceability-01-index-and-orphans | [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) | Parent Feature: [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161); core counterpart `specfact-cli#242`; runtime inputs from `#164` and `#165` | - -### Validation and governance runtime follow-ups - -These changes are the modules-side runtime companions to split core governance and validation changes. Core remains authoritative for schemas and CI/evidence contracts. - -| Module | Order | Change folder | GitHub # | Blocked by | -|--------|-------|---------------|----------|------------| -| governance | 01 | governance-01-evidence-output | [#169](https://github.com/nold-ai/specfact-cli-modules/issues/169) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); core counterpart `specfact-cli#247`; validation runtime `#171` | -| governance | 02 | governance-02-exception-management | [#167](https://github.com/nold-ai/specfact-cli-modules/issues/167) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); core counterpart `specfact-cli#248`; policy runtime `#158` | -| governance | 04 | governance-04-deterministic-agent-governance-loading | [#181](https://github.com/nold-ai/specfact-cli-modules/issues/181) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); paired core [specfact-cli#494](https://github.com/nold-ai/specfact-cli/issues/494); baseline [#178](https://github.com/nold-ai/specfact-cli-modules/issues/178) (implements archived `governance-03-github-hierarchy-cache`, paired core [specfact-cli#491](https://github.com/nold-ai/specfact-cli/issues/491)) | -| validation | 02 | validation-02-full-chain-engine | [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); core counterpart `specfact-cli#241`; runtime inputs from `#164` and `#165`; policy semantics from `#158` | -| docs + validation | 15 | docs-15-code-review-validation-guardrails | [#202](https://github.com/nold-ai/specfact-cli-modules/issues/202) | Parent Feature: [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163); Parent Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); no known blockers | - -### Five-pillar governance and enterprise runtime companions - -These changes are the modules-side runtime companions to the five-pillar governance wave in `specfact-cli`. Core remains authoritative for schemas, scoring, resolution semantics, and shared report contracts; this repo owns the runnable bundle packages, manifests, and packaged tool integrations. - -**Most of this wave is paused.** The core counterparts for FinOps, knowledge, review-resiliency, security, and enterprise have been parked in `specfact-cli` (see [core PR #551](https://github.com/nold-ai/specfact-cli/pull/551)). The corresponding nine modules-side proposals have been moved to [`openspec/parking-lot/`](parking-lot/) until their core contracts are un-parked. See [`parking-lot/README.md`](parking-lot/README.md) for the full mapping and un-park triggers. - -The architecture pillar remains active because `architecture-02-well-architected-review` in core is gated (waiting on `architecture-01` to ship and be used for one cycle), not parked. - -| Module | Order | Change folder | GitHub # | Blocked by | -|--------|-------|---------------|----------|------------| -| architecture | 03 | architecture-02-module-well-architected | [#230](https://github.com/nold-ai/specfact-cli-modules/issues/230) | Parent Epic: [#216](https://github.com/nold-ai/specfact-cli-modules/issues/216); Parent Feature: [#219](https://github.com/nold-ai/specfact-cli-modules/issues/219); core umbrella [specfact-cli#511](https://github.com/nold-ai/specfact-cli/issues/511); paired core change `architecture-02-well-architected-review` (gated on `architecture-01-solution-layer` shipping + 1 usage cycle); boundary rules align with `ALLOWED_IMPORTS.md` | - -### Code review and sidecar validation improvements - -| Module | Order | Change folder | GitHub # | Blocked by | -|--------|-------|---------------|----------|------------| -| code-review + codebase | 01 | code-review-bug-finding-and-sidecar-venv-fix | [#174](https://github.com/nold-ai/specfact-cli-modules/issues/174) | Parent Feature: [#175](https://github.com/nold-ai/specfact-cli-modules/issues/175); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162) | -| codebase + project-runtime | 02 | codebase-import-runtime-hardening | [#235](https://github.com/nold-ai/specfact-cli-modules/issues/235) | Parent Feature: [#234](https://github.com/nold-ai/specfact-cli-modules/issues/234); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); no known blockers | -| code-review + project | 03 | code-review-ai-bloat-detection | [#269](https://github.com/nold-ai/specfact-cli-modules/issues/269) | Parent Feature: [#175](https://github.com/nold-ai/specfact-cli-modules/issues/175); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); no known blockers | -| code-review + project | 04 | code-review-11-simplification-feedback-loop | [#276](https://github.com/nold-ai/specfact-cli-modules/issues/276) | Parent Feature: [#275](https://github.com/nold-ai/specfact-cli-modules/issues/275); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); blocked by `code-review-ai-bloat-detection` / [#269](https://github.com/nold-ai/specfact-cli-modules/issues/269) | -| code-review + project | 05 | code-review-12-guided-simplification-enforcement | [#286](https://github.com/nold-ai/specfact-cli-modules/issues/286) | Parent Feature: [#275](https://github.com/nold-ai/specfact-cli-modules/issues/275); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); blocked by `code-review-11-simplification-feedback-loop` / [#276](https://github.com/nold-ai/specfact-cli-modules/issues/276) | -| code-review + project | 06 | code-review-13-cleanup-forecast-agent-handoff | [#297](https://github.com/nold-ai/specfact-cli-modules/issues/297) | Parent Feature: [#275](https://github.com/nold-ai/specfact-cli-modules/issues/275); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); blocked by `code-review-12-guided-simplification-enforcement` / [#286](https://github.com/nold-ai/specfact-cli-modules/issues/286) | - -### Documentation restructure - -| Module | Order | Change folder | GitHub # | Blocked by | -|--------|-------|---------------|----------|------------| -| docs | 14 | docs-14-module-release-history | [#124](https://github.com/nold-ai/specfact-cli-modules/issues/124) | docs-13 ✅; publish-modules workflow | - -### Packaging and bundle payloads - -| Module | Order | Change folder | GitHub # | Blocked by | -|--------|-------|---------------|----------|------------| -| packaging | 01 | ✅ packaging-01-bundle-resource-payloads (archived 2026-04-05) | [#101](https://github.com/nold-ai/specfact-cli-modules/issues/101) | — | - -### Module bundle peer dependencies - -| Module | Order | Change folder | GitHub # | Blocked by | -|--------|-------|---------------|----------|------------| -| peer-deps | 01 | ✅ module-bundle-deps-auto-install (archived 2026-04-05) | [#135](https://github.com/nold-ai/specfact-cli-modules/issues/135) | — | +# OpenSpec Change Order + +This document is the modules-side source of truth for active OpenSpec work. It +must be read together with the core repo change order in `nold-ai/specfact-cli`. + +## Status Snapshot + +| Bucket | Count | Location | +|---|---:|---| +| **Active** | 12 | [`openspec/changes/`](changes/) | +| **Parked** | 16 | [`openspec/parking-lot/`](parking-lot/) | +| **Archived** | 43 | [`openspec/changes/archive/`](changes/archive/) | + +`openspec list` reflects the active set only. Completed changes are archived +with date-prefixed folders. Parked changes are preserved for later customer pull +but are not implementation-ready. + +## Product Thesis + +The modules repo should make SpecFact feel like **the validation and AI-bloat +defense tool**. The flagship runtime path is `specfact code review run`, +AI-bloat detection, simplification guidance, cleanup forecasts, remediation +handoff, sidecar/codebase hardening, docs guardrails, and deterministic evidence. + +Backlog, Scrum, Kanban, SAFe, ceremony, enterprise, FinOps, and knowledge work +stay parked unless they directly improve validation evidence for a real user. +Spec Kit, OpenSpec, backlog systems, ADRs, specs, contracts, tests, and code are +upstream inputs to validation, not workflows this repo should replace. + +## Recently Archived Validation Work + +The following active changes were already complete or tied to closed GitHub +issues and are now archived: + +| Change | Archive status | +|---|---| +| `tester-module-cli-reliability` | archived 2026-06-06 | +| `project-runtime-01-safe-artifact-write-policy` | archived 2026-06-06 | +| `prompt-command-contract-validation` | archived 2026-06-06 | +| `project-02-plan-root-command-fix` | archived 2026-06-06 | +| `marketplace-07-pr-auto-sign-updates` | archived 2026-06-06 | +| `docs-15-code-review-validation-guardrails` | archived 2026-06-06 | +| `codebase-import-runtime-hardening` | archived 2026-06-06 | +| `code-review-ai-bloat-detection` | archived 2026-06-06 | +| `code-review-11-simplification-feedback-loop` | archived 2026-06-06 | +| `code-review-12-guided-simplification-enforcement` | archived 2026-06-06 | +| `code-review-13-cleanup-forecast-agent-handoff` | archived 2026-06-06 | + +These archived specs are now the shipped basis for the flagship demo: run review, +produce JSON evidence, identify AI-bloat findings, hand remediation packets to an +AI IDE, rerun, and compare improved evidence. + +## Active Tracks + +### Track A - Validation Runtime Spine + +| Order | Change folder | GitHub # | Positioning | Blocked by | +|---:|---|---|---|---| +| 1 | `policy-02-packs-and-modes` | [#158](https://github.com/nold-ai/specfact-cli-modules/issues/158) | Validation severity, rollout modes, and policy-pack execution | core profile/policy semantics | +| 2 | `governance-01-evidence-output` | [#169](https://github.com/nold-ai/specfact-cli-modules/issues/169) | Runtime evidence emitters for JSON/CI/AI handoff | core `governance-01` | +| 3 | `governance-02-exception-management` | [#167](https://github.com/nold-ai/specfact-cli-modules/issues/167) | Runtime exception handling and waiver evidence | governance-01, policy-02 | +| 4 | `validation-02-full-chain-engine` | [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) | Validation evidence graph runtime, not lifecycle orchestration | governance-01, traceability-01 | +| 5 | `traceability-01-index-and-orphans` | [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) | Artifact drift and orphan detection runtime | validation input contracts | +| 6 | `sync-01-unified-kernel` | [#157](https://github.com/nold-ai/specfact-cli-modules/issues/157) | Preview/apply safety only where validation adapters need it | project/runtime safety specs | + +### Track B - Upstream Context Adapters + +| Order | Change folder | GitHub # | Positioning | Blocked by | +|---:|---|---|---|---| +| 1 | `requirements-02-module-commands` | [#165](https://github.com/nold-ai/specfact-cli-modules/issues/165) | Import/normalize requirement context for evidence | core requirements input model | +| 2 | `requirements-03-backlog-sync` | [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) | Read-first backlog drift evidence; no write-back critical path | requirements-02, sync-01 | +| 3 | `architecture-01-solution-layer` | [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) | Architecture-boundary validation input | core architecture-boundary contracts | +| 4 | `openspec-01-intent-trace` | [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) | Optional OpenSpec and Spec Kit evidence import adapter | requirements input contracts | +| Gated | `architecture-02-module-well-architected` | [#230](https://github.com/nold-ai/specfact-cli-modules/issues/230) | Architecture-boundary review findings | architecture-01 shipped plus one usage cycle | + +### Track C - Supporting Docs + +| Order | Change folder | GitHub # | Positioning | Blocked by | +|---:|---|---|---|---| +| 1 | `docs-14-module-release-history` | [#124](https://github.com/nold-ai/specfact-cli-modules/issues/124) | Release-history documentation for shipped modules | docs-13, publish workflow | + +## Modify Queue Before Implementation + +| Change | Required adjustment | +|---|---| +| `validation-02-full-chain-engine` | Rewrite runtime language around validation evidence graph outputs. Do not implement upstream requirements-to-code lifecycle orchestration. | +| `traceability-01-index-and-orphans` | Keep artifact drift, orphan, and linkage evidence. Drop ceremony/dashboard positioning. | +| `requirements-02-module-commands` | Drop requirement authoring as a flagship workflow. Keep import, normalization, validation, and coverage inspection. | +| `requirements-03-backlog-sync` | Keep read-first drift evidence. Write-back remains preview-only and outside the validation critical path. | +| `architecture-01-solution-layer` | Keep architecture-boundary input and validation hooks. Drop architecture generation. | +| `openspec-01-intent-trace` | Reframe as optional OpenSpec/Spec Kit adapter consuming upstream artifacts. | +| `architecture-02-module-well-architected` | Keep gated until architecture-01 ships and is used for one complete cycle. | +| `sync-01-unified-kernel` | Keep only as safety infrastructure for validation/context adapters. | + +## Parked By This Repositioning + +Moved to [`openspec/parking-lot/`](parking-lot/) because they expand upstream +ceremony rather than validation evidence: + +- `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` +- `ceremony-02-requirements-aware-output` + +## Implementation Waves + +### Wave 1 - Cleanup and Scope Alignment + +- Archive completed/closed changes. +- Park upstream ceremony expansions. +- Update active proposals and wiki mirrors to validation positioning. +- Recheck GitHub Project metadata with a token that has project-field access. + +### Wave 2 - Validation Evidence Runtime + +- `policy-02-packs-and-modes` +- `governance-01-evidence-output` +- `governance-02-exception-management` +- `validation-02-full-chain-engine` +- `traceability-01-index-and-orphans` + +### Wave 3 - Context Adapters + +- `requirements-02-module-commands` +- `requirements-03-backlog-sync` +- `architecture-01-solution-layer` +- `openspec-01-intent-trace` + +### Wave 4 - Gated Extensions + +- `architecture-02-module-well-architected` +- `sync-01-unified-kernel` only where adapter safety requires it +- `docs-14-module-release-history` + +## Parent Issues And Epic Framing + +| Issue | Desired framing | +|---|---| +| [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162) | Flagship specfact code / AI-bloat defense epic | +| [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163) | Validation evidence and governance runtime | +| [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) | Context adapters for validation evidence | + +Project-board metadata was not available with the current token in the core +review, so final issue governance must recheck project fields before scoped +implementation starts. + +## Archive Policy + +After a change ships and merges, run `openspec archive ` from the repo +root. Do not manually move completed changes into `openspec/changes/archive/`. +Parking-lot moves are allowed for paused proposals that are explicitly not active +scope. diff --git a/openspec/changes/architecture-01-solution-layer/proposal.md b/openspec/changes/architecture-01-solution-layer/proposal.md index 3572ae19..73ffaa95 100644 --- a/openspec/changes/architecture-01-solution-layer/proposal.md +++ b/openspec/changes/architecture-01-solution-layer/proposal.md @@ -1,124 +1,48 @@ -# Change: Solution Architecture Layer — Derive, Store, Validate +# Change: Architecture Boundary Validation Runtime ## Why +Architecture context is useful when it validates code reality: component +boundaries, ADR references, ownership, interface leaks, and contract mismatch. +SpecFact should not generate architecture or compete with planning tools. +## Ownership Alignment (2026-06-06) - -Architectural decisions live in separate ADRs or Confluence pages with zero programmatic links to requirements or code. This is the layer where the costliest misalignments occur — a wrong architectural choice invalidates entire implementation efforts regardless of code quality. No tool today systematically connects business requirements → architectural decisions → implementation. A solution architecture module that derives, stores, and validates architecture with explicit traceability to requirements closes the biggest blind spot in the end-to-end chain. - -## Ownership Alignment (2026-04-08) - -- Repository assignment: `nold-ai/specfact-cli-modules` -- Modules-owned scope retained here: bundle-side runtime delivery, command wiring, and execution behavior for architecture workflows. -- Core counterpart retained in `nold-ai/specfact-cli` issue [#240](https://github.com/nold-ai/specfact-cli/issues/240) -- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) -> Story [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) -- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. -- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. - -## Module Package Structure - -``` -modules/architecture/ - module-package.yaml # name: architecture; commands: architecture derive, validate-coverage, trace - src/architecture/ - __init__.py - main.py # typer.Typer app — architecture command group - engine/ - deriver.py # Derive architecture from requirements (template + AI-assisted) - coverage_validator.py # Validate architecture covers all requirements - trace_builder.py # Build architecture ↔ requirements traceability links - models/ - solution_architecture.py # SolutionArchitecture, ComponentSpec, DataFlow, ADR models - templates/ - microservice.yaml # Microservice architecture template - monolith.yaml # Modular monolith template - event_driven.yaml # Event-driven architecture template - commands/ - derive.py # specfact architecture derive - validate_coverage.py # specfact architecture validate-coverage - trace.py # specfact architecture trace - storage/ - architecture_store.py # Read/write .specfact/architecture/*.arch.yaml -``` - -**`module-package.yaml` declares:** -- `name: architecture` -- `version: 0.1.0` -- `commands: [architecture derive, architecture validate-coverage, architecture trace]` -- `dependencies: [requirements-01-data-model, requirements-02-module-commands]` -- `schema_extensions:` — via arch-07 -- `publisher:` + `integrity:` — arch-06 marketplace readiness - -## Module Package Structure - -``` -modules/architecture/ - module-package.yaml # name: architecture; commands: architecture derive, validate-coverage, trace - src/architecture/ - __init__.py - main.py # typer.Typer app — architecture command group - engine/ - deriver.py # Derive architecture from requirements (template + AI-assisted) - coverage_validator.py # Validate architecture covers all requirements - trace_builder.py # Build architecture ↔ requirements traceability links - models/ - solution_architecture.py # SolutionArchitecture, ComponentSpec, DataFlow, ADR models - templates/ - microservice.yaml # Microservice architecture template - monolith.yaml # Modular monolith template - event_driven.yaml # Event-driven architecture template - commands/ - derive.py # specfact architecture derive - validate_coverage.py # specfact architecture validate-coverage - trace.py # specfact architecture trace - storage/ - architecture_store.py # Read/write .specfact/architecture/*.arch.yaml -``` - -**`module-package.yaml` declares:** -- `name: architecture` -- `version: 0.1.0` -- `commands: [architecture derive, architecture validate-coverage, architecture trace]` -- `dependencies: [requirements-01-data-model, requirements-02-module-commands]` -- `schema_extensions:` — via arch-07 -- `publisher:` + `integrity:` — arch-06 marketplace readiness +- Modules-owned scope retained here: grouped architecture runtime commands, + imports, validation hooks, and reports. +- Core-owned scope remains the architecture-boundary input model and shared + validation contracts. +- Architecture derivation and authoring are no longer critical-path scope. ## What Changes - - - -- **NEW**: Pydantic domain models in `modules/architecture/src/architecture/models/`: - - `SolutionArchitecture` — architecture ID, requirement IDs (traceability links), components, data flows, ADRs - - `ComponentSpec` — name, responsibility, business rule IDs (from requirements), integrations - - `DataFlow` — source, target, data type, protocol - - `ADR` — ADR ID, decision, rationale (links to architectural constraints from requirements), alternatives considered, tradeoff -- **NEW**: `specfact architecture derive --requirements .specfact/requirements/ --suggest-components --interactive` — derive architecture from requirements using templates and optional AI assistance -- **NEW**: `specfact architecture validate-coverage` — verify every business rule maps to a component, every architectural constraint has an ADR, every component has spec coverage -- **NEW**: `specfact architecture trace --format table|json|markdown` — show traceability matrix: requirements ↔ components ↔ ADRs ↔ specs -- **NEW**: Storage convention: `.specfact/architecture/{architecture_id}.arch.yaml` -- **NEW**: Architecture templates for common patterns (microservice, monolith, event-driven) — profile-aware complexity -- **EXTEND**: `ProjectBundle` extended with optional `architecture` field via arch-07 schema extensions (namespace: `architecture.solution_architecture`) +- **NEW**: Import/runtime handling for architecture-boundary records sourced from + existing ADRs, docs, diagrams, Spec Kit plans, or OpenSpec designs. +- **NEW**: Validation for missing ADR links, interface leaks, component ownership + gaps, and mismatched contract boundaries. +- **NEW**: Runtime output that can feed traceability-01 and validation-02. +- **REMOVED FROM CRITICAL PATH**: AI-assisted architecture generation and + template-based architecture authoring. ## Capabilities + ### New Capabilities -- `solution-architecture`: Derive, store, and validate solution architecture with explicit traceability to business requirements. Includes component specs, data flows, ADRs, and coverage validation. +- `architecture-boundary-validation-runtime`: Runtime commands and reports for + architecture-boundary evidence. ### Modified Capabilities -- `data-models`: ProjectBundle extended with architecture field via arch-07 schema extensions - +- `data-models`: Project bundle integration consumes the core architecture input + namespace when present. --- ## Source Tracking -- **Core Counterpart Issue**: nold-ai/specfact-cli#240 - **GitHub Issue**: #164 - **Issue URL**: -- **Repository**: nold-ai/specfact-cli-modules +- **Core Counterpart**: nold-ai/specfact-cli#240 - **Last Synced Status**: proposed - **Sanitized**: false diff --git a/openspec/changes/code-review-11-simplification-feedback-loop/.openspec.yaml b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/.openspec.yaml similarity index 100% rename from openspec/changes/code-review-11-simplification-feedback-loop/.openspec.yaml rename to openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/.openspec.yaml diff --git a/openspec/changes/code-review-11-simplification-feedback-loop/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/code-review-11-simplification-feedback-loop/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/TDD_EVIDENCE.md diff --git a/openspec/changes/code-review-11-simplification-feedback-loop/design.md b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/design.md similarity index 100% rename from openspec/changes/code-review-11-simplification-feedback-loop/design.md rename to openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/design.md diff --git a/openspec/changes/code-review-11-simplification-feedback-loop/proposal.md b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/proposal.md similarity index 100% rename from openspec/changes/code-review-11-simplification-feedback-loop/proposal.md rename to openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/proposal.md diff --git a/openspec/changes/code-review-11-simplification-feedback-loop/specs/clean-code-analysis/spec.md b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/specs/clean-code-analysis/spec.md similarity index 97% rename from openspec/changes/code-review-11-simplification-feedback-loop/specs/clean-code-analysis/spec.md rename to openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/specs/clean-code-analysis/spec.md index 6c46c519..254711bd 100644 --- a/openspec/changes/code-review-11-simplification-feedback-loop/specs/clean-code-analysis/spec.md +++ b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/specs/clean-code-analysis/spec.md @@ -1,4 +1,4 @@ -## ADDED Requirements +## MODIFIED Requirements ### Requirement: Clean-code signals can contribute to simplification feedback diff --git a/openspec/changes/code-review-11-simplification-feedback-loop/specs/code-review-simplification-feedback/spec.md b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/specs/code-review-simplification-feedback/spec.md similarity index 99% rename from openspec/changes/code-review-11-simplification-feedback-loop/specs/code-review-simplification-feedback/spec.md rename to openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/specs/code-review-simplification-feedback/spec.md index d9bfde18..5bfa78a7 100644 --- a/openspec/changes/code-review-11-simplification-feedback-loop/specs/code-review-simplification-feedback/spec.md +++ b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/specs/code-review-simplification-feedback/spec.md @@ -1,4 +1,4 @@ -## ADDED Requirements +## MODIFIED Requirements ### Requirement: Review findings carry optional simplification metadata diff --git a/openspec/changes/code-review-11-simplification-feedback-loop/specs/review-finding-model/spec.md b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/specs/review-finding-model/spec.md similarity index 100% rename from openspec/changes/code-review-11-simplification-feedback-loop/specs/review-finding-model/spec.md rename to openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/specs/review-finding-model/spec.md diff --git a/openspec/changes/code-review-11-simplification-feedback-loop/specs/review-run-command/spec.md b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/specs/review-run-command/spec.md similarity index 100% rename from openspec/changes/code-review-11-simplification-feedback-loop/specs/review-run-command/spec.md rename to openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/specs/review-run-command/spec.md diff --git a/openspec/changes/code-review-11-simplification-feedback-loop/tasks.md b/openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/tasks.md similarity index 100% rename from openspec/changes/code-review-11-simplification-feedback-loop/tasks.md rename to openspec/changes/archive/2026-06-06-code-review-11-simplification-feedback-loop/tasks.md diff --git a/openspec/changes/code-review-12-guided-simplification-enforcement/.openspec.yaml b/openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/.openspec.yaml similarity index 100% rename from openspec/changes/code-review-12-guided-simplification-enforcement/.openspec.yaml rename to openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/.openspec.yaml diff --git a/openspec/changes/code-review-12-guided-simplification-enforcement/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/code-review-12-guided-simplification-enforcement/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/TDD_EVIDENCE.md diff --git a/openspec/changes/code-review-12-guided-simplification-enforcement/design.md b/openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/design.md similarity index 100% rename from openspec/changes/code-review-12-guided-simplification-enforcement/design.md rename to openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/design.md diff --git a/openspec/changes/code-review-12-guided-simplification-enforcement/proposal.md b/openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/proposal.md similarity index 100% rename from openspec/changes/code-review-12-guided-simplification-enforcement/proposal.md rename to openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/proposal.md diff --git a/openspec/changes/code-review-12-guided-simplification-enforcement/specs/guided-simplification-review/spec.md b/openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/specs/guided-simplification-review/spec.md similarity index 100% rename from openspec/changes/code-review-12-guided-simplification-enforcement/specs/guided-simplification-review/spec.md rename to openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/specs/guided-simplification-review/spec.md diff --git a/openspec/changes/code-review-12-guided-simplification-enforcement/specs/review-finding-model/spec.md b/openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/specs/review-finding-model/spec.md similarity index 100% rename from openspec/changes/code-review-12-guided-simplification-enforcement/specs/review-finding-model/spec.md rename to openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/specs/review-finding-model/spec.md diff --git a/openspec/changes/code-review-12-guided-simplification-enforcement/specs/review-run-command/spec.md b/openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/specs/review-run-command/spec.md similarity index 100% rename from openspec/changes/code-review-12-guided-simplification-enforcement/specs/review-run-command/spec.md rename to openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/specs/review-run-command/spec.md diff --git a/openspec/changes/code-review-12-guided-simplification-enforcement/tasks.md b/openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/tasks.md similarity index 100% rename from openspec/changes/code-review-12-guided-simplification-enforcement/tasks.md rename to openspec/changes/archive/2026-06-06-code-review-12-guided-simplification-enforcement/tasks.md diff --git a/openspec/changes/code-review-13-cleanup-forecast-agent-handoff/.openspec.yaml b/openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/.openspec.yaml similarity index 100% rename from openspec/changes/code-review-13-cleanup-forecast-agent-handoff/.openspec.yaml rename to openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/.openspec.yaml diff --git a/openspec/changes/code-review-13-cleanup-forecast-agent-handoff/README.md b/openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/README.md similarity index 100% rename from openspec/changes/code-review-13-cleanup-forecast-agent-handoff/README.md rename to openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/README.md diff --git a/openspec/changes/code-review-13-cleanup-forecast-agent-handoff/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/code-review-13-cleanup-forecast-agent-handoff/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/TDD_EVIDENCE.md diff --git a/openspec/changes/code-review-13-cleanup-forecast-agent-handoff/design.md b/openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/design.md similarity index 100% rename from openspec/changes/code-review-13-cleanup-forecast-agent-handoff/design.md rename to openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/design.md diff --git a/openspec/changes/code-review-13-cleanup-forecast-agent-handoff/proposal.md b/openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/proposal.md similarity index 100% rename from openspec/changes/code-review-13-cleanup-forecast-agent-handoff/proposal.md rename to openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/proposal.md diff --git a/openspec/changes/code-review-13-cleanup-forecast-agent-handoff/specs/ai-ide-remediation-handoff/spec.md b/openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/specs/ai-ide-remediation-handoff/spec.md similarity index 100% rename from openspec/changes/code-review-13-cleanup-forecast-agent-handoff/specs/ai-ide-remediation-handoff/spec.md rename to openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/specs/ai-ide-remediation-handoff/spec.md diff --git a/openspec/changes/code-review-13-cleanup-forecast-agent-handoff/specs/cleanup-forecast-review/spec.md b/openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/specs/cleanup-forecast-review/spec.md similarity index 100% rename from openspec/changes/code-review-13-cleanup-forecast-agent-handoff/specs/cleanup-forecast-review/spec.md rename to openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/specs/cleanup-forecast-review/spec.md diff --git a/openspec/changes/code-review-13-cleanup-forecast-agent-handoff/specs/review-finding-model/spec.md b/openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/specs/review-finding-model/spec.md similarity index 100% rename from openspec/changes/code-review-13-cleanup-forecast-agent-handoff/specs/review-finding-model/spec.md rename to openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/specs/review-finding-model/spec.md diff --git a/openspec/changes/code-review-13-cleanup-forecast-agent-handoff/specs/review-run-command/spec.md b/openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/specs/review-run-command/spec.md similarity index 100% rename from openspec/changes/code-review-13-cleanup-forecast-agent-handoff/specs/review-run-command/spec.md rename to openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/specs/review-run-command/spec.md diff --git a/openspec/changes/code-review-13-cleanup-forecast-agent-handoff/tasks.md b/openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/tasks.md similarity index 100% rename from openspec/changes/code-review-13-cleanup-forecast-agent-handoff/tasks.md rename to openspec/changes/archive/2026-06-06-code-review-13-cleanup-forecast-agent-handoff/tasks.md diff --git a/openspec/changes/code-review-ai-bloat-detection/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/code-review-ai-bloat-detection/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/TDD_EVIDENCE.md diff --git a/openspec/changes/code-review-ai-bloat-detection/design.md b/openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/design.md similarity index 100% rename from openspec/changes/code-review-ai-bloat-detection/design.md rename to openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/design.md diff --git a/openspec/changes/code-review-ai-bloat-detection/proposal.md b/openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/proposal.md similarity index 100% rename from openspec/changes/code-review-ai-bloat-detection/proposal.md rename to openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/proposal.md diff --git a/openspec/changes/code-review-ai-bloat-detection/specs/code-review-ai-bloat-detection/spec.md b/openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/specs/code-review-ai-bloat-detection/spec.md similarity index 99% rename from openspec/changes/code-review-ai-bloat-detection/specs/code-review-ai-bloat-detection/spec.md rename to openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/specs/code-review-ai-bloat-detection/spec.md index e0a51581..5bd9699f 100644 --- a/openspec/changes/code-review-ai-bloat-detection/specs/code-review-ai-bloat-detection/spec.md +++ b/openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/specs/code-review-ai-bloat-detection/spec.md @@ -89,7 +89,6 @@ The `specfact-project` bundle SHALL ship a prompt resource at `resources/prompts - **AND** the prompt SHALL ask the user to accept, reject, skip, or request explanation before applying any edit - **AND** the prompt SHALL apply only the edits the user accepts -## MODIFIED Requirements ### Requirement: The clean-code policy pack documentation SHALL note the parallel ai-bloat pack diff --git a/openspec/changes/code-review-ai-bloat-detection/tasks.md b/openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/tasks.md similarity index 100% rename from openspec/changes/code-review-ai-bloat-detection/tasks.md rename to openspec/changes/archive/2026-06-06-code-review-ai-bloat-detection/tasks.md diff --git a/openspec/changes/codebase-import-runtime-hardening/.openspec.yaml b/openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/.openspec.yaml similarity index 100% rename from openspec/changes/codebase-import-runtime-hardening/.openspec.yaml rename to openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/.openspec.yaml diff --git a/openspec/changes/codebase-import-runtime-hardening/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/codebase-import-runtime-hardening/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/TDD_EVIDENCE.md diff --git a/openspec/changes/codebase-import-runtime-hardening/design.md b/openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/design.md similarity index 100% rename from openspec/changes/codebase-import-runtime-hardening/design.md rename to openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/design.md diff --git a/openspec/changes/codebase-import-runtime-hardening/proposal.md b/openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/proposal.md similarity index 100% rename from openspec/changes/codebase-import-runtime-hardening/proposal.md rename to openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/proposal.md diff --git a/openspec/changes/codebase-import-runtime-hardening/specs/bundle-packaged-resources/spec.md b/openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/specs/bundle-packaged-resources/spec.md similarity index 100% rename from openspec/changes/codebase-import-runtime-hardening/specs/bundle-packaged-resources/spec.md rename to openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/specs/bundle-packaged-resources/spec.md diff --git a/openspec/changes/codebase-import-runtime-hardening/specs/codebase-import-runtime/spec.md b/openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/specs/codebase-import-runtime/spec.md similarity index 100% rename from openspec/changes/codebase-import-runtime-hardening/specs/codebase-import-runtime/spec.md rename to openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/specs/codebase-import-runtime/spec.md diff --git a/openspec/changes/codebase-import-runtime-hardening/tasks.md b/openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/tasks.md similarity index 100% rename from openspec/changes/codebase-import-runtime-hardening/tasks.md rename to openspec/changes/archive/2026-06-06-codebase-import-runtime-hardening/tasks.md diff --git a/openspec/changes/docs-15-code-review-validation-guardrails/.openspec.yaml b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/.openspec.yaml similarity index 100% rename from openspec/changes/docs-15-code-review-validation-guardrails/.openspec.yaml rename to openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/.openspec.yaml diff --git a/openspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/docs-15-code-review-validation-guardrails/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/TDD_EVIDENCE.md diff --git a/openspec/changes/docs-15-code-review-validation-guardrails/design.md b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/design.md similarity index 100% rename from openspec/changes/docs-15-code-review-validation-guardrails/design.md rename to openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/design.md diff --git a/openspec/changes/docs-15-code-review-validation-guardrails/proposal.md b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/proposal.md similarity index 100% rename from openspec/changes/docs-15-code-review-validation-guardrails/proposal.md rename to openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/proposal.md diff --git a/openspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md similarity index 98% rename from openspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md rename to openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md index 71c0dd67..3233658e 100644 --- a/openspec/changes/docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md +++ b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/bundle-overview-pages/spec.md @@ -1,6 +1,6 @@ # Bundle overview pages -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Bundle overview links SHALL resolve as published URLs diff --git a/openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.md b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.md similarity index 99% rename from openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.md rename to openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.md index 62cddbcf..12b6da35 100644 --- a/openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.md +++ b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/modules-docs-command-validation/spec.md @@ -1,6 +1,6 @@ # Modules docs command validation -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Docs validation SHALL validate published-route body links diff --git a/openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.md b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.md similarity index 98% rename from openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.md rename to openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.md index 1e305958..af296e8d 100644 --- a/openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.md +++ b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/modules-docs-publishing/spec.md @@ -1,6 +1,6 @@ # Modules docs publishing -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Docs publishing SHALL validate generated-site readiness before deploy diff --git a/openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md similarity index 98% rename from openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md rename to openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md index e467772a..08227a46 100644 --- a/openspec/changes/docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md +++ b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/modules-pre-commit-quality-parity/spec.md @@ -1,6 +1,6 @@ # Modules pre-commit quality parity -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Docs-only pre-commit changes SHALL run docs validation before safe bypass diff --git a/openspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md similarity index 98% rename from openspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md rename to openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md index e0fb1744..1c64d244 100644 --- a/openspec/changes/docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md +++ b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/specs/review-run-command/spec.md @@ -1,6 +1,6 @@ # Review run command (docs) -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Code Review run docs SHALL cover the public option surface diff --git a/openspec/changes/docs-15-code-review-validation-guardrails/tasks.md b/openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/tasks.md similarity index 100% rename from openspec/changes/docs-15-code-review-validation-guardrails/tasks.md rename to openspec/changes/archive/2026-06-06-docs-15-code-review-validation-guardrails/tasks.md diff --git a/openspec/changes/marketplace-07-pr-auto-sign-updates/.openspec.yaml b/openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/.openspec.yaml similarity index 100% rename from openspec/changes/marketplace-07-pr-auto-sign-updates/.openspec.yaml rename to openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/.openspec.yaml diff --git a/openspec/changes/marketplace-07-pr-auto-sign-updates/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/marketplace-07-pr-auto-sign-updates/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/TDD_EVIDENCE.md diff --git a/openspec/changes/marketplace-07-pr-auto-sign-updates/design.md b/openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/design.md similarity index 100% rename from openspec/changes/marketplace-07-pr-auto-sign-updates/design.md rename to openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/design.md diff --git a/openspec/changes/marketplace-07-pr-auto-sign-updates/proposal.md b/openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/proposal.md similarity index 100% rename from openspec/changes/marketplace-07-pr-auto-sign-updates/proposal.md rename to openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/proposal.md diff --git a/openspec/changes/marketplace-07-pr-auto-sign-updates/specs/ci-integration/spec.md b/openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/specs/ci-integration/spec.md similarity index 100% rename from openspec/changes/marketplace-07-pr-auto-sign-updates/specs/ci-integration/spec.md rename to openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/specs/ci-integration/spec.md diff --git a/openspec/changes/marketplace-07-pr-auto-sign-updates/specs/ci-module-signing-on-approval/spec.md b/openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/specs/ci-module-signing-on-approval/spec.md similarity index 100% rename from openspec/changes/marketplace-07-pr-auto-sign-updates/specs/ci-module-signing-on-approval/spec.md rename to openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/specs/ci-module-signing-on-approval/spec.md diff --git a/openspec/changes/marketplace-07-pr-auto-sign-updates/tasks.md b/openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/tasks.md similarity index 100% rename from openspec/changes/marketplace-07-pr-auto-sign-updates/tasks.md rename to openspec/changes/archive/2026-06-06-marketplace-07-pr-auto-sign-updates/tasks.md diff --git a/openspec/changes/project-02-plan-root-command-fix/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-project-02-plan-root-command-fix/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/project-02-plan-root-command-fix/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-project-02-plan-root-command-fix/TDD_EVIDENCE.md diff --git a/openspec/changes/project-02-plan-root-command-fix/design.md b/openspec/changes/archive/2026-06-06-project-02-plan-root-command-fix/design.md similarity index 100% rename from openspec/changes/project-02-plan-root-command-fix/design.md rename to openspec/changes/archive/2026-06-06-project-02-plan-root-command-fix/design.md diff --git a/openspec/changes/project-02-plan-root-command-fix/proposal.md b/openspec/changes/archive/2026-06-06-project-02-plan-root-command-fix/proposal.md similarity index 100% rename from openspec/changes/project-02-plan-root-command-fix/proposal.md rename to openspec/changes/archive/2026-06-06-project-02-plan-root-command-fix/proposal.md diff --git a/openspec/changes/project-02-plan-root-command-fix/specs/project-command-surface/spec.md b/openspec/changes/archive/2026-06-06-project-02-plan-root-command-fix/specs/project-command-surface/spec.md similarity index 100% rename from openspec/changes/project-02-plan-root-command-fix/specs/project-command-surface/spec.md rename to openspec/changes/archive/2026-06-06-project-02-plan-root-command-fix/specs/project-command-surface/spec.md diff --git a/openspec/changes/project-02-plan-root-command-fix/tasks.md b/openspec/changes/archive/2026-06-06-project-02-plan-root-command-fix/tasks.md similarity index 100% rename from openspec/changes/project-02-plan-root-command-fix/tasks.md rename to openspec/changes/archive/2026-06-06-project-02-plan-root-command-fix/tasks.md diff --git a/openspec/changes/project-runtime-01-safe-artifact-write-policy/.openspec.yaml b/openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/.openspec.yaml similarity index 100% rename from openspec/changes/project-runtime-01-safe-artifact-write-policy/.openspec.yaml rename to openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/.openspec.yaml diff --git a/openspec/changes/project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.md b/openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.md rename to openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/CHANGE_VALIDATION.md diff --git a/openspec/changes/project-runtime-01-safe-artifact-write-policy/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/project-runtime-01-safe-artifact-write-policy/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/TDD_EVIDENCE.md diff --git a/openspec/changes/project-runtime-01-safe-artifact-write-policy/design.md b/openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/design.md similarity index 100% rename from openspec/changes/project-runtime-01-safe-artifact-write-policy/design.md rename to openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/design.md diff --git a/openspec/changes/project-runtime-01-safe-artifact-write-policy/proposal.md b/openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/proposal.md similarity index 100% rename from openspec/changes/project-runtime-01-safe-artifact-write-policy/proposal.md rename to openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/proposal.md diff --git a/openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md b/openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md similarity index 100% rename from openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md rename to openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md diff --git a/openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md b/openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md similarity index 100% rename from openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md rename to openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md diff --git a/openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.md b/openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.md similarity index 100% rename from openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.md rename to openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/specs/runtime-artifact-write-safety/spec.md diff --git a/openspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.md b/openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/tasks.md similarity index 100% rename from openspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.md rename to openspec/changes/archive/2026-06-06-project-runtime-01-safe-artifact-write-policy/tasks.md diff --git a/openspec/changes/prompt-command-contract-validation/.openspec.yaml b/openspec/changes/archive/2026-06-06-prompt-command-contract-validation/.openspec.yaml similarity index 100% rename from openspec/changes/prompt-command-contract-validation/.openspec.yaml rename to openspec/changes/archive/2026-06-06-prompt-command-contract-validation/.openspec.yaml diff --git a/openspec/changes/prompt-command-contract-validation/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-prompt-command-contract-validation/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/prompt-command-contract-validation/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-prompt-command-contract-validation/TDD_EVIDENCE.md diff --git a/openspec/changes/prompt-command-contract-validation/design.md b/openspec/changes/archive/2026-06-06-prompt-command-contract-validation/design.md similarity index 100% rename from openspec/changes/prompt-command-contract-validation/design.md rename to openspec/changes/archive/2026-06-06-prompt-command-contract-validation/design.md diff --git a/openspec/changes/prompt-command-contract-validation/proposal.md b/openspec/changes/archive/2026-06-06-prompt-command-contract-validation/proposal.md similarity index 100% rename from openspec/changes/prompt-command-contract-validation/proposal.md rename to openspec/changes/archive/2026-06-06-prompt-command-contract-validation/proposal.md diff --git a/openspec/changes/prompt-command-contract-validation/specs/bundle-packaged-resources/spec.md b/openspec/changes/archive/2026-06-06-prompt-command-contract-validation/specs/bundle-packaged-resources/spec.md similarity index 100% rename from openspec/changes/prompt-command-contract-validation/specs/bundle-packaged-resources/spec.md rename to openspec/changes/archive/2026-06-06-prompt-command-contract-validation/specs/bundle-packaged-resources/spec.md diff --git a/openspec/changes/prompt-command-contract-validation/specs/prompt-command-validation/spec.md b/openspec/changes/archive/2026-06-06-prompt-command-contract-validation/specs/prompt-command-validation/spec.md similarity index 100% rename from openspec/changes/prompt-command-contract-validation/specs/prompt-command-validation/spec.md rename to openspec/changes/archive/2026-06-06-prompt-command-contract-validation/specs/prompt-command-validation/spec.md diff --git a/openspec/changes/prompt-command-contract-validation/specs/resource-aware-integrity/spec.md b/openspec/changes/archive/2026-06-06-prompt-command-contract-validation/specs/resource-aware-integrity/spec.md similarity index 100% rename from openspec/changes/prompt-command-contract-validation/specs/resource-aware-integrity/spec.md rename to openspec/changes/archive/2026-06-06-prompt-command-contract-validation/specs/resource-aware-integrity/spec.md diff --git a/openspec/changes/prompt-command-contract-validation/tasks.md b/openspec/changes/archive/2026-06-06-prompt-command-contract-validation/tasks.md similarity index 100% rename from openspec/changes/prompt-command-contract-validation/tasks.md rename to openspec/changes/archive/2026-06-06-prompt-command-contract-validation/tasks.md diff --git a/openspec/changes/tester-module-cli-reliability/.openspec.yaml b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/.openspec.yaml similarity index 100% rename from openspec/changes/tester-module-cli-reliability/.openspec.yaml rename to openspec/changes/archive/2026-06-06-tester-module-cli-reliability/.openspec.yaml diff --git a/openspec/changes/tester-module-cli-reliability/TDD_EVIDENCE.md b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/TDD_EVIDENCE.md similarity index 100% rename from openspec/changes/tester-module-cli-reliability/TDD_EVIDENCE.md rename to openspec/changes/archive/2026-06-06-tester-module-cli-reliability/TDD_EVIDENCE.md diff --git a/openspec/changes/tester-module-cli-reliability/proposal.md b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/proposal.md similarity index 100% rename from openspec/changes/tester-module-cli-reliability/proposal.md rename to openspec/changes/archive/2026-06-06-tester-module-cli-reliability/proposal.md diff --git a/openspec/changes/tester-module-cli-reliability/specs/backlog-delta/spec.md b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/backlog-delta/spec.md similarity index 97% rename from openspec/changes/tester-module-cli-reliability/specs/backlog-delta/spec.md rename to openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/backlog-delta/spec.md index 33306ca7..90dad4e6 100644 --- a/openspec/changes/tester-module-cli-reliability/specs/backlog-delta/spec.md +++ b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/backlog-delta/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Backlog delta status resolves documented defaults diff --git a/openspec/changes/tester-module-cli-reliability/specs/code-review-tool-dependencies/spec.md b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/code-review-tool-dependencies/spec.md similarity index 97% rename from openspec/changes/tester-module-cli-reliability/specs/code-review-tool-dependencies/spec.md rename to openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/code-review-tool-dependencies/spec.md index 4a208bad..ab7fb8bc 100644 --- a/openspec/changes/tester-module-cli-reliability/specs/code-review-tool-dependencies/spec.md +++ b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/code-review-tool-dependencies/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Tool dependency diagnostics use active environment context diff --git a/openspec/changes/tester-module-cli-reliability/specs/module-cli-error-contract/spec.md b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/module-cli-error-contract/spec.md similarity index 100% rename from openspec/changes/tester-module-cli-reliability/specs/module-cli-error-contract/spec.md rename to openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/module-cli-error-contract/spec.md diff --git a/openspec/changes/tester-module-cli-reliability/specs/module-command-overview/spec.md b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/module-command-overview/spec.md similarity index 100% rename from openspec/changes/tester-module-cli-reliability/specs/module-command-overview/spec.md rename to openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/module-command-overview/spec.md diff --git a/openspec/changes/tester-module-cli-reliability/specs/modules-docs-command-validation/spec.md b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/modules-docs-command-validation/spec.md similarity index 98% rename from openspec/changes/tester-module-cli-reliability/specs/modules-docs-command-validation/spec.md rename to openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/modules-docs-command-validation/spec.md index 183e8bd9..ebb48f87 100644 --- a/openspec/changes/tester-module-cli-reliability/specs/modules-docs-command-validation/spec.md +++ b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/specs/modules-docs-command-validation/spec.md @@ -1,4 +1,4 @@ -## MODIFIED Requirements +## ADDED Requirements ### Requirement: Module docs command examples are validated diff --git a/openspec/changes/tester-module-cli-reliability/tasks.md b/openspec/changes/archive/2026-06-06-tester-module-cli-reliability/tasks.md similarity index 100% rename from openspec/changes/tester-module-cli-reliability/tasks.md rename to openspec/changes/archive/2026-06-06-tester-module-cli-reliability/tasks.md diff --git a/openspec/changes/governance-01-evidence-output/proposal.md b/openspec/changes/governance-01-evidence-output/proposal.md index 8551fc89..e24fc6d1 100644 --- a/openspec/changes/governance-01-evidence-output/proposal.md +++ b/openspec/changes/governance-01-evidence-output/proposal.md @@ -1,86 +1,47 @@ -# Change: Evidence & Audit Output for CI/CD Pipelines +# Change: Runtime Evidence Output for CI and AI Handoff ## Why +SpecFact needs machine-readable evidence that validation ran, policies were +enforced, drift and AI-bloat findings were classified, and exceptions were +tracked. The modules repo owns the runtime emitters that write those artifacts +for CI, docs, and AI IDE remediation loops. +## Ownership Alignment (2026-06-06) - -Enterprise environments require machine-readable evidence that policies were enforced, traceability exists, and exceptions are tracked. Current validation output is human-readable (Markdown/terminal) but not suitable for CI gates, audit systems, or compliance dashboards. A standardized evidence JSON output format — covering policy results, traceability coverage, exception status, and timestamps — makes SpecFact validation results consumable by any CI/CD pipeline, audit tool, or governance platform. - -## Ownership Alignment (2026-04-08) - -- Repository assignment: `nold-ai/specfact-cli-modules` -- Modules-owned scope retained here: bundle-side evidence emission and runtime output behavior built on top of the core evidence envelope contract. -- Core counterpart retained in `nold-ai/specfact-cli` issue [#247](https://github.com/nold-ai/specfact-cli/issues/247) -- Target hierarchy: modules Epic [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162) -> Feature [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163) -> Story [#169](https://github.com/nold-ai/specfact-cli-modules/issues/169) -- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. -- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. +- Modules-owned scope retained here: runtime emitter flags, file writing, command + integration, and module packaging. +- Core-owned scope remains the evidence envelope schema and CI contract. ## What Changes - - - -- **NEW**: Evidence writer producing standardized JSON artifacts: - ```json - { - "schema_version": "1.0", - "run_id": "uuid", - "timestamp": "ISO-8601", - "profile": "enterprise", - "policy_mode": "hard", - "validation_results": { - "full_chain": { "pass": 67, "fail": 2, "advisory": 5 }, - "layers": { ... }, - "orphans": { ... } - }, - "code_quality": { - "clean_code_score": 95, - "findings_by_category": { "naming": 0, "kiss": 1, "yagni": 0, "dry": 0, "solid": 0 }, - "verdict": "PASS_WITH_ADVISORY" - }, - "coverage": { - "req_to_arch": "92%", - "arch_to_spec": "100%", - "spec_to_code": "100%", - "code_to_test": "87%" - }, - "exceptions": [ - { "id": "EXC-001", "policy": "...", "expires": "2026-12-31", "status": "active" } - ], - "overall_verdict": "PASS_WITH_ADVISORY", - "ci_exit_code": 0 - } - ``` -- **NEW**: `--evidence-dir .specfact/evidence/` flag on `specfact validate --full-chain` to persist evidence artifacts per run -- **NEW**: `--ci-mode` flag that sets exit codes based on profile enforcement mode: advisory=always 0, mixed=1 for hard-fail rules only, hard=1 for any failure -- **NEW**: Evidence artifact naming: `{timestamp}_{run_id}_evidence.json` for audit trail -- **NEW**: Evidence summary on terminal: human-readable table alongside JSON output -- **EXTEND**: Full-chain validation (validation-02) extended to produce evidence artifacts -- **EXTEND**: Full-chain validation can append `code_quality` as a parallel section when the run includes review-based clean-code checks -- **EXTEND**: Policy engine results formatted as evidence-compatible structures -- **NEW**: Ownership authority — this change is authoritative for evidence JSON envelope/schema; sibling governance changes may add fields only through this envelope contract. +- **NEW**: Runtime evidence writer for validation and code-review runs. +- **NEW**: `--evidence-dir .specfact/evidence/` persistence behavior where the + owning command supports evidence output. +- **NEW**: CI mode exit-code handling based on profile/policy mode. +- **NEW**: Evidence artifact naming and terminal summaries. +- **EXTEND**: Validation graph, policy, exception, code quality, cleanup forecast, + and `ai_bloat` results are emitted through the shared evidence envelope. ## Capabilities + ### New Capabilities -- `governance-evidence-output`: Machine-readable JSON evidence artifacts for CI/CD gates and audit systems, with per-run persistence, CI exit code modes, coverage percentages, exception status, and profile-aware verdicts. +- `runtime-governance-evidence-output`: Runtime evidence writers for CI gates and + AI remediation handoff. ### Modified Capabilities -- `full-chain-validation`: Extended with evidence artifact generation via `--evidence-dir` and `--ci-mode` flags -- `policy-engine`: Results formatted as evidence-compatible structures with run_id and timestamps -- `governance-evidence-output`: Extended with a `code_quality` section that remains parallel to `validation_results` rather than introducing a new traceability layer - +- `validation-evidence-graph-runtime`: Extended with evidence persistence. +- `policy-engine`: Results formatted as evidence-compatible structures. --- ## Source Tracking -- **Core Counterpart Issue**: nold-ai/specfact-cli#247 - **GitHub Issue**: #169 - **Issue URL**: -- **Repository**: nold-ai/specfact-cli-modules +- **Core Counterpart**: nold-ai/specfact-cli#247 - **Last Synced Status**: proposed - **Sanitized**: false diff --git a/openspec/changes/openspec-01-intent-trace/proposal.md b/openspec/changes/openspec-01-intent-trace/proposal.md index 40d6ce1d..075a50f4 100644 --- a/openspec/changes/openspec-01-intent-trace/proposal.md +++ b/openspec/changes/openspec-01-intent-trace/proposal.md @@ -1,56 +1,47 @@ -# Change: OpenSpec Intent Trace — Bridge Adapter Integration +# Change: OpenSpec and Spec Kit Evidence Import Runtime ## Why -OpenSpec proposals are plain Markdown with no structured business-intent metadata. When SpecFact imports a proposal via `specfact sync bridge --adapter openspec`, it has no machine-readable context about the business outcomes, business rules, or architectural constraints the change is supposed to satisfy — it only sees tasks and specs. This means the traceability chain starts at the spec level, missing the upstream intent layer entirely. Adding a structured `## Intent Trace` section to OpenSpec proposals (with JSON Schema validation) gives SpecFact the data it needs to construct the full outcome → rule → constraint → spec → code chain automatically on import. +OpenSpec and Spec Kit already own upstream planning artifacts. The modules repo +should provide optional import runtime that maps those artifacts into SpecFact +validation evidence when useful, without requiring upstream tools to adopt a new +intent schema. -## Ownership Alignment (2026-04-08) +## Ownership Alignment (2026-06-06) -- Repository assignment: `nold-ai/specfact-cli-modules` -- Modules-owned scope retained here: bundle-side import and sync runtime behavior for OpenSpec intent-trace workflows. -- Core counterpart retained in `nold-ai/specfact-cli` issue [#350](https://github.com/nold-ai/specfact-cli/issues/350) -- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) -> Story [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) -- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. -- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. +- Modules-owned scope retained here: bridge/import runtime, optional metadata + parsing, source attribution, and generated evidence inputs. +- Core-owned scope remains optional adapter contracts and validation behavior. ## What Changes -- **NEW**: `## Intent Trace` section schema for OpenSpec `proposal.md` files: - - YAML-fenced block under `## Intent Trace` with `intent_trace` root key - - Fields: `business_outcomes` (id, description, persona), `business_rules` (id, outcome_ref, given, when, then), `architectural_constraints` (id, outcome_ref, constraint), `requirement_refs` (list of REQ-NNN strings) - - JSON Schema at `openspec/schemas/intent-trace.schema.json` for validation -- **NEW**: `requirement_refs` optional field on individual tasks in `tasks.md` — links a task to specific `BusinessRule` IDs or `ArchitecturalConstraint` IDs -- **NEW**: `evidence` optional field on archived changes — points to evidence JSON envelope file(s) generated during implementation; creates immutable proposal → intent trace → implementation → evidence → archive chain -- **NEW**: `specfact sync bridge --adapter openspec --import-intent` — reads `## Intent Trace` section from imported proposals and populates `.specfact/requirements/` with `BusinessOutcome` and `BusinessRule` artifacts automatically -- **EXTEND**: `specfact sync bridge --adapter openspec` — when `## Intent Trace` section is present, include intent context in the imported project bundle; backwards-compatible (section is optional) -- **EXTEND**: `openspec validate --strict` — validates `## Intent Trace` section against `intent-trace.schema.json` when present +- **NEW**: Optional import support for OpenSpec proposals and Spec Kit feature + folders. +- **NEW**: Source-attributed mapping of tasks, spec deltas, acceptance checks, + requirement references, and evidence links when present. +- **NEW**: Strict metadata validation only when optional metadata exists. +- **EXTEND**: Project sync/import commands avoid duplicate planning artifacts and + instead feed validation evidence. ## Capabilities ### New Capabilities -- `openspec-intent-trace-schema`: JSON Schema definition and validation for the `## Intent Trace` section in OpenSpec proposals — enabling machine-readable business-outcome traceability in change proposals. -- `openspec-bridge-intent-import`: Extended SpecFact OpenSpec bridge adapter that reads, validates, and imports `## Intent Trace` sections from proposals into `.specfact/requirements/` artifacts automatically. +- `openspec-speckit-evidence-import-runtime`: Optional runtime adapter for + OpenSpec and Spec Kit artifacts consumed by validation. ### Modified Capabilities -- `openspec-bridge-adapter`: Extended to parse optional `## Intent Trace` section on proposal import; backwards-compatible when section is absent. - -## Impact - -- New file: `openspec/schemas/intent-trace.schema.json` -- Existing bridge adapter: `src/specfact_cli/adapters/` OpenSpec adapter extended with intent-trace parsing -- CLI change: `specfact sync bridge --adapter openspec` — new optional `--import-intent` flag; no breaking change to existing workflows -- Depends on: `requirements-01-data-model` (#238) — `BusinessOutcome` and `BusinessRule` schemas must exist to populate; `requirements-02-module-commands` (#239) — `specfact requirements capture` used for artifact creation -- Wave: aligns with Wave 5/6 (after requirements-01/02 land) -- Docs: new `docs/guides/openspec-journey.md` section on Intent Trace; update `docs/adapters/` for OpenSpec adapter +- `openspec-bridge-adapter`: Extended to parse optional metadata and evidence + links without requiring them. --- ## Source Tracking - -- **GitHub Issue**: #350 -- **Issue URL**: -- **Repository**: nold-ai/specfact-cli + +- **GitHub Issue**: #168 +- **Issue URL**: +- **Core Counterpart**: nold-ai/specfact-cli#350 - **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/requirements-02-module-commands/proposal.md b/openspec/changes/requirements-02-module-commands/proposal.md index 288918a7..222a1425 100644 --- a/openspec/changes/requirements-02-module-commands/proposal.md +++ b/openspec/changes/requirements-02-module-commands/proposal.md @@ -1,120 +1,52 @@ -# Change: Requirements Module — Extract, Author, Validate Commands +# Change: Requirements Import and Validation Runtime ## Why +SpecFact needs module commands that import, normalize, validate, and inspect +upstream requirement context for evidence. It should not become the authoring +stack for requirements. +## Ownership Alignment (2026-06-06) - -Even with a formal data model (requirements-01), there are no CLI commands for working with business requirements. Teams need to extract structured requirements from existing backlog items (reverse-engineer from AC text), author new requirements with profile-aware templates, and validate requirements completeness — all from the terminal. This module is the primary user-facing entry point for the upstream traceability chain. - -## Ownership Alignment (2026-04-08) - -- Repository assignment: `nold-ai/specfact-cli-modules` -- Modules-owned scope retained here: user-facing runtime command delivery, adapter runtime wiring, and grouped bundle command placement for requirements workflows. -- Core counterpart retained in `nold-ai/specfact-cli` issue [#239](https://github.com/nold-ai/specfact-cli/issues/239) -- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) -> Story [#165](https://github.com/nold-ai/specfact-cli-modules/issues/165) -- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. -- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. - -## Module Package Structure - -``` -modules/requirements/ - module-package.yaml # name: requirements; commands: requirements extract, author, validate, list - src/requirements/ - __init__.py - main.py # typer.Typer app — requirements command group - engine/ - extractor.py # Parse AC text from backlog items → structured BusinessRequirement - author.py # Interactive + template-based requirement authoring - validator.py # Validate requirements completeness per profile schema - coverage.py # Compute requirement coverage (arch/spec/code/test links) - templates/ - story.yaml # User story template (As_a, I_want, So_that + business rules) - feature.yaml # Feature template (outcome, rules, constraints, UX) - spike.yaml # Spike template (hypothesis, success criteria) - commands/ - extract.py # specfact requirements extract --from-backlog - author.py # specfact requirements author --template - validate.py # specfact requirements validate - list.py # specfact requirements list --show-coverage -``` - -**`module-package.yaml` declares:** -- `name: requirements` -- `version: 0.1.0` -- `commands: [requirements extract, requirements author, requirements validate, requirements list]` -- `dependencies: [requirements-01-data-model, arch-07-schema-extension-system]` (needs requirements models and schema extensions) -- `schema_extensions:` — via arch-07 -- `publisher:` + `integrity:` — arch-06 marketplace readiness - -## Module Package Structure - -``` -modules/requirements/ - module-package.yaml # name: requirements; commands: requirements extract, author, validate, list - src/requirements/ - __init__.py - main.py # typer.Typer app — requirements command group - engine/ - extractor.py # Parse AC text from backlog items → structured BusinessRequirement - author.py # Interactive + template-based requirement authoring - validator.py # Validate requirements completeness per profile schema - coverage.py # Compute requirement coverage (arch/spec/code/test links) - templates/ - story.yaml # User story template (As_a, I_want, So_that + business rules) - feature.yaml # Feature template (outcome, rules, constraints, UX) - spike.yaml # Spike template (hypothesis, success criteria) - commands/ - extract.py # specfact requirements extract --from-backlog - author.py # specfact requirements author --template - validate.py # specfact requirements validate - list.py # specfact requirements list --show-coverage -``` - -**`module-package.yaml` declares:** -- `name: requirements` -- `version: 0.1.0` -- `commands: [requirements extract, requirements author, requirements validate, requirements list]` -- `dependencies: [requirements-01-data-model, arch-07-schema-extension-system]` (needs requirements models and schema extensions) -- `schema_extensions:` — via arch-07 -- `publisher:` + `integrity:` — arch-06 marketplace readiness +- Modules-owned scope retained here: grouped command runtime, adapters, and + validation behavior for normalized requirement inputs. +- Core-owned scope remains the shared requirements input model and evidence + contracts. +- Requirement authoring templates are no longer critical-path scope. ## What Changes - - - -- **NEW**: Requirements module in `modules/requirements/` implementing `ModuleIOContract`: - - `import_to_bundle`: Extract requirements from backlog items into ProjectBundle - - `export_from_bundle`: Generate requirements documents (YAML, Markdown) from bundle - - `sync_with_bundle`: Bidirectional sync between requirements and backlog (read-only in v1) - - `validate_bundle`: Check requirements completeness per profile schema -- **NEW**: `specfact requirements extract --from-backlog --project ` — parse acceptance criteria from existing backlog items, infer business rules, generate `.specfact/requirements/*.req.yaml` files -- **NEW**: `specfact requirements author --template story|feature|spike --story STORY-123` — interactive requirement authoring with profile-aware templates (solo gets 3 fields, enterprise gets full schema) -- **NEW**: `specfact requirements validate --requirements-dir .specfact/requirements/` — validate completeness against active profile's required fields -- **NEW**: `specfact requirements list --show-coverage` — list requirements with traceability coverage status (architecture %, spec %, code %, test %) -- **NEW**: Profile-aware templates: solo requires only As_a/I_want/So_that; startup adds Business_outcome + Business_rules; mid-size uses org-defined schema; enterprise adds Regulatory_reference + Risk_owner +- **NEW**: Import commands for backlog items, OpenSpec proposals, Spec Kit feature + folders, and local requirement records. +- **NEW**: Normalization into source-attributed records compatible with the core + requirements input model. +- **NEW**: Validation and coverage inspection for evidence usefulness by profile. +- **NEW**: Adapter hooks return bounded records instead of free-form planning + prose. +- **REMOVED FROM CRITICAL PATH**: Interactive requirement authoring and full + requirement lifecycle management. ## Capabilities + ### New Capabilities -- `requirements-module`: CLI commands for extracting requirements from backlog items, authoring with profile-aware templates, validating completeness per profile schema, and listing with traceability coverage status. Implements ModuleIOContract for requirements lifecycle. +- `requirements-validation-runtime`: Runtime commands for importing, + normalizing, validating, and inspecting upstream requirement context. ### Modified Capabilities -- `module-io-contract`: New implementation of ModuleIOContract for the requirements domain (import from backlog, export to YAML/Markdown, sync, validate) -- `backlog-adapter`: Extended with requirement extraction hooks — adapters provide raw AC text, extractor parses into structured BusinessRequirement models - +- `module-io-contract`: Requirements implementation focuses on import and + validation hooks for evidence. +- `backlog-adapter`: Backlog adapters can provide source-attributed requirement + snippets. --- ## Source Tracking -- **Core Counterpart Issue**: nold-ai/specfact-cli#239 - **GitHub Issue**: #165 - **Issue URL**: -- **Repository**: nold-ai/specfact-cli-modules +- **Core Counterpart**: nold-ai/specfact-cli#239 - **Last Synced Status**: proposed - **Sanitized**: false diff --git a/openspec/changes/requirements-03-backlog-sync/proposal.md b/openspec/changes/requirements-03-backlog-sync/proposal.md index ccb47857..97c1793c 100644 --- a/openspec/changes/requirements-03-backlog-sync/proposal.md +++ b/openspec/changes/requirements-03-backlog-sync/proposal.md @@ -1,54 +1,48 @@ -# Change: Requirements ↔ Backlog Bidirectional Sync +# Change: Backlog Requirement Drift Runtime ## Why +Backlog items and local validation inputs drift. The useful SpecFact runtime +value is read-first import, conflict preview, and drift evidence before code +merges, not bidirectional product-management sync. +## Ownership Alignment (2026-06-06) - -When backlog items change, requirements aren't updated. When requirements change, backlog items aren't updated. The two drift apart silently, creating a traceability gap that grows with every sprint. Teams discover the drift only during audits or after building the wrong thing. A bidirectional sync between backlog items and `.specfact/requirements/` using the sync kernel makes requirements and backlog items a single source of truth — with drift detection as the safety net. - -## Ownership Alignment (2026-04-08) - -- Repository assignment: `nold-ai/specfact-cli-modules` -- Modules-owned scope retained here: runtime synchronization orchestration, backlog/project command delivery, and bundle-side adapter behavior for requirements-backlog flows. -- Core counterpart retained in `nold-ai/specfact-cli` issue [#244](https://github.com/nold-ai/specfact-cli/issues/244) -- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) -> Story [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) -- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. -- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. +- Modules-owned scope retained here: backlog adapter runtime, read-first drift + detection, preview safety, and evidence emission. +- Core-owned scope remains drift evidence contracts and duplicate-creation + safeguards. +- Write-back remains preview-only and outside the validation critical path. ## What Changes - - - -- **NEW**: `specfact requirements sync --from-backlog --project --preview` — pull structured requirements from backlog AC text, update `.specfact/requirements/` -- **NEW**: `specfact requirements sync --to-backlog --project --preview` — push requirement-derived fields back to backlog items (missing AC, business value gaps, architectural constraints) -- **NEW**: `specfact requirements drift --from-backlog --project ` — detect divergence between local requirements and backlog items without making changes -- **NEW**: Sync operations use the sync kernel (sync-01) for session management, conflict detection, and patch preview -- **NEW**: Backlog adapter extension: adapters provide `extract_requirements_fields()` and `update_requirements_fields()` methods for bidirectional sync -- **EXTEND**: Requirements module (requirements-02) extended with sync commands -- **DESIGN DECISION**: v1 starts with pull-first (backlog → requirements) as primary direction; push (requirements → backlog) is preview-only and requires explicit `--write` confirmation via patch-mode -- **EXTEND**: Spec-Kit backlog extension awareness — before creating issues during push (requirements → backlog), the sync SHALL query `ToolCapabilities.extension_commands` (from speckit-02) to detect active spec-kit backlog extensions (Jira, ADO, Linear, GitHub Projects, Trello). When a spec-kit backlog extension is active, the sync SHALL scan spec-kit feature `tasks.md` files for existing issue references (e.g., `PROJ-123`, `AB#456`) and import them as pre-existing mappings. Issue creation is skipped for tasks that already have spec-kit extension mappings, preventing duplicate issues. This detection is implemented in `speckit-03-change-proposal-bridge` (specfact-cli-modules) and consumed here via the adapter interface. +- **NEW**: Read-first import from backlog systems into normalized validation + inputs. +- **NEW**: Drift categories for missing acceptance criteria, stale local records, + changed issue status, missing source links, and ambiguous mappings. +- **NEW**: Preview-only write-back MAY exist later behind explicit confirmation. +- **EXTEND**: Spec Kit backlog-extension awareness prevents duplicate issue + creation when upstream artifacts already contain tracker mappings. ## Capabilities + ### New Capabilities -- `requirements-backlog-sync`: Bidirectional sync between `.specfact/requirements/` and backlog items (GitHub, ADO, Jira, Linear) via sync kernel. Includes pull (extract from backlog), push (update backlog), and drift detection. +- `backlog-requirement-drift-runtime`: Runtime detection of drift between backlog + items and normalized validation inputs. ### Modified Capabilities -- `backlog-adapter`: Extended with requirements field extraction and update methods for bidirectional sync; extended with spec-kit backlog extension issue mapping import -- `requirements-module`: Extended with sync and drift commands; extended with spec-kit duplicate issue prevention - +- `backlog-adapter`: Extended with source-attributed import and drift hooks. +- `requirements-validation-runtime`: Extended with backlog drift evidence. --- ## Source Tracking -- **Core Counterpart Issue**: nold-ai/specfact-cli#244 - **GitHub Issue**: #166 - **Issue URL**: -- **Repository**: nold-ai/specfact-cli-modules +- **Core Counterpart**: nold-ai/specfact-cli#244 - **Last Synced Status**: proposed - **Sanitized**: false diff --git a/openspec/changes/traceability-01-index-and-orphans/proposal.md b/openspec/changes/traceability-01-index-and-orphans/proposal.md index bab7939d..73a1309a 100644 --- a/openspec/changes/traceability-01-index-and-orphans/proposal.md +++ b/openspec/changes/traceability-01-index-and-orphans/proposal.md @@ -1,114 +1,47 @@ -# Change: Traceability Index & Orphan Detection +# Change: Artifact Evidence Index and Orphan Detection Runtime ## Why +Validation evidence needs a runtime index that can find stale links, missing +source references, orphaned implementation artifacts, and ambiguous mappings. +This is useful as a validation input, not as a ceremony dashboard or planning +system. +## Ownership Alignment (2026-06-06) - -As the number of requirements, specs, and code modules grows, manually tracking traceability becomes impossible. Teams need a fast, queryable index that maps every artifact to its upstream/downstream counterparts — and actively detects orphans (artifacts with broken or missing links). This index is the backbone for the full-chain validation, coverage dashboards, and ceremony enrichment. Without it, traceability is a write-once artifact that decays the moment someone adds a new endpoint without linking it. - -## Ownership Alignment (2026-04-08) - -- Repository assignment: `nold-ai/specfact-cli-modules` -- Modules-owned scope retained here: bundle-side query/report delivery and runtime trace indexing behavior for traceability workflows. -- Core counterpart retained in `nold-ai/specfact-cli` issue [#242](https://github.com/nold-ai/specfact-cli/issues/242) -- Target hierarchy: modules Epic [#144](https://github.com/nold-ai/specfact-cli-modules/issues/144) -> Feature [#161](https://github.com/nold-ai/specfact-cli-modules/issues/161) -> Story [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) -- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. -- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. - -## Module Package Structure - -``` -modules/trace/ - module-package.yaml # name: trace; commands: trace index, trace show, trace orphans, trace matrix - src/trace/ - __init__.py - main.py # typer.Typer app — trace command group - engine/ - indexer.py # Build/rebuild traceability index from all layers - query.py # Query index by requirement, spec, code, or test ID - orphan_detector.py # Find artifacts with broken or missing upstream/downstream links - matrix_generator.py # Generate traceability matrix (markdown, CSV, JSON) - models/ - trace_index.py # TraceIndex, TraceEntry, OrphanReport models - storage/ - index_store.py # Read/write .specfact/trace/index.json (generated, not authored) - commands/ - index.py # specfact trace index --rebuild - show.py # specfact trace show - orphans.py # specfact trace orphans - matrix.py # specfact trace matrix --format markdown|csv|json -``` - -**`module-package.yaml` declares:** -- `name: trace` -- `version: 0.1.0` -- `commands: [trace index, trace show, trace orphans, trace matrix]` -- `dependencies: [requirements-02-module-commands, architecture-01-solution-layer]` -- `publisher:` + `integrity:` — arch-06 marketplace readiness - -## Module Package Structure - -``` -modules/trace/ - module-package.yaml # name: trace; commands: trace index, trace show, trace orphans, trace matrix - src/trace/ - __init__.py - main.py # typer.Typer app — trace command group - engine/ - indexer.py # Build/rebuild traceability index from all layers - query.py # Query index by requirement, spec, code, or test ID - orphan_detector.py # Find artifacts with broken or missing upstream/downstream links - matrix_generator.py # Generate traceability matrix (markdown, CSV, JSON) - models/ - trace_index.py # TraceIndex, TraceEntry, OrphanReport models - storage/ - index_store.py # Read/write .specfact/trace/index.json (generated, not authored) - commands/ - index.py # specfact trace index --rebuild - show.py # specfact trace show - orphans.py # specfact trace orphans - matrix.py # specfact trace matrix --format markdown|csv|json -``` - -**`module-package.yaml` declares:** -- `name: trace` -- `version: 0.1.0` -- `commands: [trace index, trace show, trace orphans, trace matrix]` -- `dependencies: [requirements-02-module-commands, architecture-01-solution-layer]` -- `publisher:` + `integrity:` — arch-06 marketplace readiness +- Modules-owned scope retained here: runtime indexing, query/report commands, and + generated `.specfact/` state. +- Core-owned scope remains artifact identity, linkage semantics, and orphan + classification contracts. ## What Changes - - - -- **NEW**: Trace module in `modules/trace/` with auto-maintained traceability index -- **NEW**: `specfact trace index --rebuild` — scan all requirements, architecture, specs, code, and test artifacts to build a comprehensive traceability index stored at `.specfact/trace/index.json` -- **NEW**: `specfact trace show REQ-123` — query upstream/downstream links for any artifact (requirement, component, spec operation, code module, test) -- **NEW**: `specfact trace orphans` — detect orphaned artifacts: specs with no requirement, code with no spec, requirements with no architecture coverage, tests with no code reference -- **NEW**: `specfact trace matrix --format markdown|csv|json` — export traceability matrix showing the full chain for each requirement -- **NEW**: Incremental index updates — when a single file changes, update only affected trace entries (not full rebuild) -- **NEW**: TraceIndex model with bidirectional links: each entry stores both `upstream_refs` and `downstream_refs` +- **NEW**: Runtime index over Spec Kit, OpenSpec, backlog, ADR, spec, contract, + code, test, policy, and review artifacts. +- **NEW**: Orphan/drift detection for missing, stale, contradictory, or ambiguous + evidence. +- **NEW**: Incremental update behavior where a changed file can refresh affected + links without a full rebuild. +- **NEW**: JSON export consumed by validation-02 and governance-01. ## Capabilities + ### New Capabilities -- `traceability-index`: Auto-maintained bidirectional traceability index mapping requirements → architecture → specs → code → tests, with orphan detection, incremental updates, and matrix export in markdown/CSV/JSON. +- `artifact-evidence-index-runtime`: Runtime index and orphan/drift detection for + validation evidence. ### Modified Capabilities (none) - --- ## Source Tracking -- **Core Counterpart Issue**: nold-ai/specfact-cli#242 - **GitHub Issue**: #170 - **Issue URL**: -- **Repository**: nold-ai/specfact-cli-modules +- **Core Counterpart**: nold-ai/specfact-cli#242 - **Last Synced Status**: proposed - **Sanitized**: false diff --git a/openspec/changes/validation-02-full-chain-engine/design.md b/openspec/changes/validation-02-full-chain-engine/design.md index 7cf04d2a..c81d9b89 100644 --- a/openspec/changes/validation-02-full-chain-engine/design.md +++ b/openspec/changes/validation-02-full-chain-engine/design.md @@ -1,18 +1,18 @@ ## Context -This change implements proposal scope for `validation-02-full-chain-engine` from the 2026-02-15 architecture-layer integration plan. It is proposal-stage only and defines implementation strategy without changing runtime code. +This change implements the narrowed validation evidence graph runtime scope for `validation-02-full-chain-engine`. 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. +- Define an implementation approach that stays within the validation evidence graph 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. +- No ownership of upstream planning, requirement authoring, or architecture generation. ## Decisions @@ -36,5 +36,5 @@ This change implements proposal scope for `validation-02-full-chain-engine` from ## Open Questions -- Dependency summary: Depends on requirements-02-module-commands, architecture-01-solution-layer, and policy-engine-01-unified-framework. +- Dependency summary: Depends on governance-01-evidence-output, traceability-01-index-and-orphans, policy-02-packs-and-modes, and optional context adapters when present. - Whether additional cross-change sequencing constraints should be hard-blocked in `openspec/CHANGE_ORDER.md`. diff --git a/openspec/changes/validation-02-full-chain-engine/proposal.md b/openspec/changes/validation-02-full-chain-engine/proposal.md index 0e75194b..4176947a 100644 --- a/openspec/changes/validation-02-full-chain-engine/proposal.md +++ b/openspec/changes/validation-02-full-chain-engine/proposal.md @@ -1,103 +1,51 @@ -# Change: Full-Chain Validation Engine +# Change: Validation Evidence Graph Runtime ## Why +The modules repo owns the executable runtime for SpecFact validation. That runtime +should not implement a requirements-to-code product lifecycle. It should consume +existing artifacts from Spec Kit, OpenSpec, backlog systems, architecture notes, +contracts, specs, code, tests, policy, and code review, then emit deterministic +evidence about drift, gaps, orphans, and AI-bloat remediation status. +## Ownership Alignment (2026-06-06) - -Validation today operates only at the spec-code level (`specfact validate` checks spec deltas and contract enforcement). There is no way to validate the entire chain from business requirements through architecture to code and tests. This means a project can pass all technical validations while building entirely the wrong thing. A `--full-chain` validation mode that checks every layer transition — Req → Arch → Spec → Code → Tests — and reports gaps, orphans, and coverage metrics, unlocks the core value proposition: end-to-end traceability with actionable evidence. - -## Ownership Alignment (2026-04-08) - -- Repository assignment: `nold-ai/specfact-cli-modules` -- Modules-owned scope retained here: bundle-side validation engine runtime, command wiring, and executable full-chain checks. -- Core counterpart retained in `nold-ai/specfact-cli` issue [#241](https://github.com/nold-ai/specfact-cli/issues/241) -- Target hierarchy: modules Epic [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162) -> Feature [#163](https://github.com/nold-ai/specfact-cli-modules/issues/163) -> Story [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) -- Shared schemas, contracts, and cross-change semantics remain owned by the core counterpart and MUST NOT be redefined here. -- Package and command examples below describe the runtime follow-up only and must be adapted to the canonical grouped bundle surface during implementation. - -## Module Package Structure - -``` -modules/validate/ - # Extends existing validate module — no new module directory - src/validate/ - engine/ - full_chain.py # Full-chain validation orchestrator - layer_transitions.py # Per-transition validation rules (req→arch, arch→spec, etc.) - coverage_calculator.py # Compute coverage percentages per layer - evidence_writer.py # Write machine-readable evidence JSON - models/ - chain_report.py # FullChainReport, LayerTransitionResult, CoverageMetrics -``` - -## Module Package Structure - -``` -modules/validate/ - # Extends existing validate module — no new module directory - src/validate/ - engine/ - full_chain.py # Full-chain validation orchestrator - layer_transitions.py # Per-transition validation rules (req→arch, arch→spec, etc.) - coverage_calculator.py # Compute coverage percentages per layer - evidence_writer.py # Write machine-readable evidence JSON - models/ - chain_report.py # FullChainReport, LayerTransitionResult, CoverageMetrics -``` +- Modules-owned scope retained here: executable validation graph runtime, + command wiring, evidence aggregation, and module packaging. +- Core-owned scope remains the shared evidence graph contract, severity semantics, + and governance envelope. +- Implementation MUST NOT ship upstream requirements/architecture authoring or + lifecycle orchestration. ## What Changes - - - -- **EXTEND**: `specfact validate` extended with `--full-chain` flag that runs validation across all layer transitions: - - Req → Arch: Every business rule mapped to component; every architectural constraint has ADR - - Arch → Spec: Every component has OpenAPI/AsyncAPI spec - - Spec → Code: Existing spec-delta validation (unchanged) - - Code → Tests: Contract coverage, test existence checks - - Orphan detection: Specs with no requirement, code with no spec -- **EXTEND**: Optional `--with-code-quality` side-channel runs `specfact review` during full-chain validation and passes its clean-code summary into the governance evidence envelope without redefining the chain layers. -- **NEW**: Full-chain validation orchestrator in `modules/validate/src/validate/engine/full_chain.py` — runs all layer transition checks, aggregates results, computes coverage metrics -- **NEW**: Layer transition rules with profile-dependent severity: solo gets advisory-only, enterprise gets hard-fail with evidence -- **NEW**: Machine-readable evidence output (JSON) for CI gates: - ```json - { - "schema_version": "1.0", - "timestamp": "...", - "profile": "enterprise", - "layers": { - "req_to_arch": { "pass": 12, "fail": 2, "advisory": 1 }, - "arch_to_spec": { "pass": 8, "fail": 0, "advisory": 3 }, - "spec_to_code": { "pass": 47, "fail": 0 }, - "orphans": { "specs_without_req": ["GET /legacy/endpoint"] } - }, - "policy_mode": "hard", - "overall": "PASS_WITH_ADVISORY" - } - ``` -- **NEW**: `--evidence-dir .specfact/evidence/` flag for persisting validation evidence artifacts -- **EXTEND**: Policy engine integration — layer transition severities configurable via policy-engine-01 policy rules +- **NEW**: Runtime graph builder over existing artifacts and adapter outputs. +- **NEW**: Graph validators for missing evidence, stale links, orphaned code, + weak tests, uncovered contracts, and unresolved AI-bloat remediation. +- **NEW**: Evidence JSON emitted through governance-01 contracts. +- **EXTEND**: Existing validation commands MAY keep compatibility aliases, but + user-facing docs and data contracts use validation evidence graph terminology. +- **EXTEND**: Code-review output can attach clean-code, cleanup forecast, and + `ai_bloat` summaries as evidence graph inputs. ## Capabilities + ### New Capabilities -- `full-chain-validation`: End-to-end validation across all traceability layers (Req → Arch → Spec → Code → Tests) with profile-dependent severity, orphan detection, coverage metrics, and machine-readable evidence output for CI gates. +- `validation-evidence-graph-runtime`: Executable validation graph runtime that + consumes upstream artifacts and emits deterministic evidence. ### Modified Capabilities -- `sidecar-validation`: Extended with `--full-chain` flag; existing spec-delta validation preserved as-is when flag is omitted -- `full-chain-validation`: Extended with optional code-quality side-channel reporting that remains parallel to the Req → Arch → Spec → Code → Tests transitions - +- `sidecar-validation`: Extended to publish graph-compatible evidence. --- ## Source Tracking -- **Core Counterpart Issue**: nold-ai/specfact-cli#241 - **GitHub Issue**: #171 - **Issue URL**: -- **Repository**: nold-ai/specfact-cli-modules +- **Core Counterpart**: nold-ai/specfact-cli#241 - **Last Synced Status**: proposed - **Sanitized**: false diff --git a/openspec/changes/validation-02-full-chain-engine/tasks.md b/openspec/changes/validation-02-full-chain-engine/tasks.md index 3d6549b5..169b2583 100644 --- a/openspec/changes/validation-02-full-chain-engine/tasks.md +++ b/openspec/changes/validation-02-full-chain-engine/tasks.md @@ -4,7 +4,7 @@ - [ ] 1.1 Create dedicated worktree branch `feature/validation-02-full-chain-engine` from `dev` before implementation work: `scripts/worktree.sh create feature/validation-02-full-chain-engine`. - [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. -- [ ] 1.3 Reconfirm scope against the 2026-02-15 architecture integration plan and this proposal. +- [ ] 1.3 Reconfirm scope against the validation evidence graph positioning and this proposal. ## 2. Spec-first and test-first preparation @@ -17,7 +17,7 @@ - [ ] 3.1 Implement minimal production code required to satisfy the new scenarios. - [ ] 3.2 Add/update contract decorators and type enforcement on public APIs. - [ ] 3.3 Update command wiring, adapters, and models required by this change scope only. -- [ ] 3.4 Add `--with-code-quality` as an optional side-channel and keep clean-code reporting out of the core chain-layer state machine. +- [ ] 3.4 Attach code-review output as optional evidence and keep clean-code reporting out of any upstream planning state machine. ## 4. Validation and documentation diff --git a/openspec/parking-lot/README.md b/openspec/parking-lot/README.md index d1af6fc6..bc74759d 100644 --- a/openspec/parking-lot/README.md +++ b/openspec/parking-lot/README.md @@ -1,59 +1,59 @@ # Parking Lot (modules side) -These module-runtime change proposals are **paused, not abandoned**, because -their core-side counterparts in `nold-ai/specfact-cli` have been parked. A -module runtime cannot land before the core contracts it implements, so these -nine proposals are pinned to whatever signal un-parks the core side. +These module-runtime change proposals are paused, not abandoned. They are not +active implementation scope until a concrete validation need or customer signal +justifies bringing them back. -For background and the parent triage rationale, see: +## Why this directory exists -- Core PR: -- Core parking-lot README: +The modules roadmap is now centered on SpecFact as the validation and AI-bloat +defense CLI. Work that mainly expands upstream ceremonies, enterprise platforms, +FinOps, knowledge systems, or security suites stays here unless it directly +strengthens validation evidence for real users. -## Restoration policy +## Restoration Policy -A modules-side proposal can be returned to `openspec/changes/` only after: +A modules-side proposal can return to `openspec/changes/` only after: -1. The core counterpart has itself been un-parked (i.e. moved back into - `nold-ai/specfact-cli/openspec/changes/`). -2. The current core API surface has been re-validated against this module's - proposal — six months of drift may have invalidated assumptions. -3. The directory is moved back under `openspec/changes/` here, and - `openspec validate ` passes. +1. A concrete trigger is documented in an issue or implementation plan. +2. The paired core contract, if any, is active and validated. +3. The proposal is rechecked against current module command topology and shipped + specs. +4. `openspec validate --strict` passes after the move. -## Contents and un-park triggers +## Contents and Un-Park Triggers | Modules change | Paired core change | GH issue | Un-park trigger | |---|---|---|---| -| `enterprise-01-module-policy-client` | `enterprise-01-policy-resolution-extension` | [#231](https://github.com/nold-ai/specfact-cli-modules/issues/231) | Core enterprise-01 un-parked | -| `enterprise-02-module-audit-client` | `enterprise-02-rbac-and-audit-trail` | [#232](https://github.com/nold-ai/specfact-cli-modules/issues/232) | Core enterprise-02 un-parked | -| `finops-01-module-cost-outcome` | `finops-01-telemetry-and-outcomes` | [#223](https://github.com/nold-ai/specfact-cli-modules/issues/223) | Core finops-01 un-parked | -| `knowledge-01-module-memory-runtime` | `knowledge-01-distillation-engine` | [#224](https://github.com/nold-ai/specfact-cli-modules/issues/224) | Core knowledge-01 un-parked | -| `knowledge-02-module-writeback` | `knowledge-02-preflight-context-assembly` | [#225](https://github.com/nold-ai/specfact-cli-modules/issues/225) | Core knowledge-02 un-parked | -| `review-resiliency-01-module` | `review-resiliency-01-contracts` | [#226](https://github.com/nold-ai/specfact-cli-modules/issues/226) | Core review-resiliency-01 un-parked | -| `security-01-module-sast-sca-secret` | `security-01-unified-findings-model` | [#227](https://github.com/nold-ai/specfact-cli-modules/issues/227) | Core security-01 un-parked | -| `security-02-module-license-compliance` | `security-01-unified-findings-model` (license findings aspect) | [#228](https://github.com/nold-ai/specfact-cli-modules/issues/228) | Core security-01 un-parked | -| `security-03-module-pii-gdpr-eu` | `security-02-eu-gdpr-baseline` (GDPR aspect) | [#229](https://github.com/nold-ai/specfact-cli-modules/issues/229) | Core security-02 un-parked | - -## Not parked here (still active) - -The following modules-side proposals remain in `openspec/changes/` because -their core counterparts are still active or in the core repo's modify queue: - -- `architecture-01-solution-layer` *(paired core: active)* -- `architecture-02-module-well-architected` *(paired core: gated, not parked)* -- `requirements-02-module-commands`, `requirements-03-backlog-sync` -- `traceability-01-index-and-orphans`, `validation-02-full-chain-engine` +| `enterprise-01-module-policy-client` | `enterprise-01-policy-resolution-extension` | [#231](https://github.com/nold-ai/specfact-cli-modules/issues/231) | Core enterprise-01 un-parked and paying enterprise policy pull exists | +| `enterprise-02-module-audit-client` | `enterprise-02-rbac-and-audit-trail` | [#232](https://github.com/nold-ai/specfact-cli-modules/issues/232) | Core enterprise-02 un-parked and audit/RBAC pull exists | +| `finops-01-module-cost-outcome` | `finops-01-telemetry-and-outcomes` | [#223](https://github.com/nold-ai/specfact-cli-modules/issues/223) | Heavy in-product LLM workloads or customer spend-evidence pull | +| `knowledge-01-module-memory-runtime` | `knowledge-01-distillation-engine` | [#224](https://github.com/nold-ai/specfact-cli-modules/issues/224) | Large evidence corpus with proven rule-mining value | +| `knowledge-02-module-writeback` | `knowledge-02-preflight-context-assembly` | [#225](https://github.com/nold-ai/specfact-cli-modules/issues/225) | knowledge-01 ships useful validation rules in practice | +| `review-resiliency-01-module` | `review-resiliency-01-contracts` | [#226](https://github.com/nold-ai/specfact-cli-modules/issues/226) | Code-review users report a real resiliency evidence gap | +| `security-01-module-sast-sca-secret` | `security-01-unified-findings-model` | [#227](https://github.com/nold-ai/specfact-cli-modules/issues/227) | Customer asks for unified security finding output inside validation evidence | +| `security-02-module-license-compliance` | `security-01-unified-findings-model` | [#228](https://github.com/nold-ai/specfact-cli-modules/issues/228) | Customer asks for license findings inside validation evidence | +| `security-03-module-pii-gdpr-eu` | `security-02-eu-gdpr-baseline` | [#229](https://github.com/nold-ai/specfact-cli-modules/issues/229) | Regulated customer asks for GDPR evidence gates | +| `backlog-scrum-02-sprint-planning` | none active | [#160](https://github.com/nold-ai/specfact-cli-modules/issues/160) | Validation evidence requires sprint-planning data, not ceremony expansion | +| `backlog-scrum-03-story-complexity` | none active | [#153](https://github.com/nold-ai/specfact-cli-modules/issues/153) | Validation evidence requires complexity signals from real users | +| `backlog-scrum-04-definition-of-done` | none active | [#152](https://github.com/nold-ai/specfact-cli-modules/issues/152) | Validation evidence requires DoD fields as gate inputs | +| `backlog-kanban-01-flow-metrics` | none active | [#155](https://github.com/nold-ai/specfact-cli-modules/issues/155) | Validation evidence requires flow metrics for a real delivery gate | +| `backlog-safe-01-pi-planning` | none active | [#154](https://github.com/nold-ai/specfact-cli-modules/issues/154) | Paying customer needs PI-planning data as validation input | +| `backlog-safe-02-risk-rollups` | none active | [#156](https://github.com/nold-ai/specfact-cli-modules/issues/156) | Paying customer needs risk rollups as validation input | +| `ceremony-02-requirements-aware-output` | none active | [#159](https://github.com/nold-ai/specfact-cli-modules/issues/159) | Validation evidence needs ceremony output fields from a real workflow | + +## Still Active + +The following remain active because they support validation evidence, runtime +trust, or optional upstream context adapters: + +- `policy-02-packs-and-modes` - `governance-01-evidence-output`, `governance-02-exception-management` -- `policy-02-packs-and-modes`, `sync-01-unified-kernel`, - `ceremony-02-requirements-aware-output` -- `openspec-01-intent-trace` *(paired core: in modify queue, will be trimmed)* -- All `backlog-*` and `docs-*` changes -- `codebase-import-runtime-hardening`, `project-runtime-01-safe-artifact-write-policy` - -## Completed / awaiting archive - -- `marketplace-07-pr-auto-sign-updates` +- `validation-02-full-chain-engine`, `traceability-01-index-and-orphans` +- `requirements-02-module-commands`, `requirements-03-backlog-sync` +- `architecture-01-solution-layer`, `architecture-02-module-well-architected` +- `openspec-01-intent-trace` +- `sync-01-unified-kernel` +- `docs-14-module-release-history` -The core marketplace-06 work (`marketplace-06-ci-module-signing`) was already -archived here on 2026-04-16 — no parking action needed. +Completed validation and AI-bloat changes are archived, not parked. diff --git a/openspec/changes/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md b/openspec/parking-lot/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md rename to openspec/parking-lot/backlog-kanban-01-flow-metrics/CHANGE_VALIDATION.md diff --git a/openspec/changes/backlog-kanban-01-flow-metrics/proposal.md b/openspec/parking-lot/backlog-kanban-01-flow-metrics/proposal.md similarity index 100% rename from openspec/changes/backlog-kanban-01-flow-metrics/proposal.md rename to openspec/parking-lot/backlog-kanban-01-flow-metrics/proposal.md diff --git a/openspec/changes/backlog-kanban-01-flow-metrics/specs/kanban-flow/spec.md b/openspec/parking-lot/backlog-kanban-01-flow-metrics/specs/kanban-flow/spec.md similarity index 100% rename from openspec/changes/backlog-kanban-01-flow-metrics/specs/kanban-flow/spec.md rename to openspec/parking-lot/backlog-kanban-01-flow-metrics/specs/kanban-flow/spec.md diff --git a/openspec/changes/backlog-kanban-01-flow-metrics/tasks.md b/openspec/parking-lot/backlog-kanban-01-flow-metrics/tasks.md similarity index 100% rename from openspec/changes/backlog-kanban-01-flow-metrics/tasks.md rename to openspec/parking-lot/backlog-kanban-01-flow-metrics/tasks.md diff --git a/openspec/changes/backlog-safe-01-pi-planning/CHANGE_VALIDATION.md b/openspec/parking-lot/backlog-safe-01-pi-planning/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/backlog-safe-01-pi-planning/CHANGE_VALIDATION.md rename to openspec/parking-lot/backlog-safe-01-pi-planning/CHANGE_VALIDATION.md diff --git a/openspec/changes/backlog-safe-01-pi-planning/proposal.md b/openspec/parking-lot/backlog-safe-01-pi-planning/proposal.md similarity index 100% rename from openspec/changes/backlog-safe-01-pi-planning/proposal.md rename to openspec/parking-lot/backlog-safe-01-pi-planning/proposal.md diff --git a/openspec/changes/backlog-safe-01-pi-planning/specs/safe-pi/spec.md b/openspec/parking-lot/backlog-safe-01-pi-planning/specs/safe-pi/spec.md similarity index 100% rename from openspec/changes/backlog-safe-01-pi-planning/specs/safe-pi/spec.md rename to openspec/parking-lot/backlog-safe-01-pi-planning/specs/safe-pi/spec.md diff --git a/openspec/changes/backlog-safe-01-pi-planning/tasks.md b/openspec/parking-lot/backlog-safe-01-pi-planning/tasks.md similarity index 100% rename from openspec/changes/backlog-safe-01-pi-planning/tasks.md rename to openspec/parking-lot/backlog-safe-01-pi-planning/tasks.md diff --git a/openspec/changes/backlog-safe-02-risk-rollups/CHANGE_VALIDATION.md b/openspec/parking-lot/backlog-safe-02-risk-rollups/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/backlog-safe-02-risk-rollups/CHANGE_VALIDATION.md rename to openspec/parking-lot/backlog-safe-02-risk-rollups/CHANGE_VALIDATION.md diff --git a/openspec/changes/backlog-safe-02-risk-rollups/proposal.md b/openspec/parking-lot/backlog-safe-02-risk-rollups/proposal.md similarity index 100% rename from openspec/changes/backlog-safe-02-risk-rollups/proposal.md rename to openspec/parking-lot/backlog-safe-02-risk-rollups/proposal.md diff --git a/openspec/changes/backlog-safe-02-risk-rollups/specs/risk-rollups/spec.md b/openspec/parking-lot/backlog-safe-02-risk-rollups/specs/risk-rollups/spec.md similarity index 100% rename from openspec/changes/backlog-safe-02-risk-rollups/specs/risk-rollups/spec.md rename to openspec/parking-lot/backlog-safe-02-risk-rollups/specs/risk-rollups/spec.md diff --git a/openspec/changes/backlog-safe-02-risk-rollups/tasks.md b/openspec/parking-lot/backlog-safe-02-risk-rollups/tasks.md similarity index 100% rename from openspec/changes/backlog-safe-02-risk-rollups/tasks.md rename to openspec/parking-lot/backlog-safe-02-risk-rollups/tasks.md diff --git a/openspec/changes/backlog-scrum-02-sprint-planning/CHANGE_VALIDATION.md b/openspec/parking-lot/backlog-scrum-02-sprint-planning/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/backlog-scrum-02-sprint-planning/CHANGE_VALIDATION.md rename to openspec/parking-lot/backlog-scrum-02-sprint-planning/CHANGE_VALIDATION.md diff --git a/openspec/changes/backlog-scrum-02-sprint-planning/design.md b/openspec/parking-lot/backlog-scrum-02-sprint-planning/design.md similarity index 100% rename from openspec/changes/backlog-scrum-02-sprint-planning/design.md rename to openspec/parking-lot/backlog-scrum-02-sprint-planning/design.md diff --git a/openspec/changes/backlog-scrum-02-sprint-planning/proposal.md b/openspec/parking-lot/backlog-scrum-02-sprint-planning/proposal.md similarity index 100% rename from openspec/changes/backlog-scrum-02-sprint-planning/proposal.md rename to openspec/parking-lot/backlog-scrum-02-sprint-planning/proposal.md diff --git a/openspec/changes/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md b/openspec/parking-lot/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md similarity index 100% rename from openspec/changes/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md rename to openspec/parking-lot/backlog-scrum-02-sprint-planning/specs/sprint-planning/spec.md diff --git a/openspec/changes/backlog-scrum-02-sprint-planning/tasks.md b/openspec/parking-lot/backlog-scrum-02-sprint-planning/tasks.md similarity index 100% rename from openspec/changes/backlog-scrum-02-sprint-planning/tasks.md rename to openspec/parking-lot/backlog-scrum-02-sprint-planning/tasks.md diff --git a/openspec/changes/backlog-scrum-03-story-complexity/CHANGE_VALIDATION.md b/openspec/parking-lot/backlog-scrum-03-story-complexity/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/backlog-scrum-03-story-complexity/CHANGE_VALIDATION.md rename to openspec/parking-lot/backlog-scrum-03-story-complexity/CHANGE_VALIDATION.md diff --git a/openspec/changes/backlog-scrum-03-story-complexity/design.md b/openspec/parking-lot/backlog-scrum-03-story-complexity/design.md similarity index 100% rename from openspec/changes/backlog-scrum-03-story-complexity/design.md rename to openspec/parking-lot/backlog-scrum-03-story-complexity/design.md diff --git a/openspec/changes/backlog-scrum-03-story-complexity/proposal.md b/openspec/parking-lot/backlog-scrum-03-story-complexity/proposal.md similarity index 100% rename from openspec/changes/backlog-scrum-03-story-complexity/proposal.md rename to openspec/parking-lot/backlog-scrum-03-story-complexity/proposal.md diff --git a/openspec/changes/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md b/openspec/parking-lot/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md similarity index 100% rename from openspec/changes/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md rename to openspec/parking-lot/backlog-scrum-03-story-complexity/specs/story-complexity/spec.md diff --git a/openspec/changes/backlog-scrum-03-story-complexity/tasks.md b/openspec/parking-lot/backlog-scrum-03-story-complexity/tasks.md similarity index 100% rename from openspec/changes/backlog-scrum-03-story-complexity/tasks.md rename to openspec/parking-lot/backlog-scrum-03-story-complexity/tasks.md diff --git a/openspec/changes/backlog-scrum-04-definition-of-done/CHANGE_VALIDATION.md b/openspec/parking-lot/backlog-scrum-04-definition-of-done/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/backlog-scrum-04-definition-of-done/CHANGE_VALIDATION.md rename to openspec/parking-lot/backlog-scrum-04-definition-of-done/CHANGE_VALIDATION.md diff --git a/openspec/changes/backlog-scrum-04-definition-of-done/design.md b/openspec/parking-lot/backlog-scrum-04-definition-of-done/design.md similarity index 100% rename from openspec/changes/backlog-scrum-04-definition-of-done/design.md rename to openspec/parking-lot/backlog-scrum-04-definition-of-done/design.md diff --git a/openspec/changes/backlog-scrum-04-definition-of-done/proposal.md b/openspec/parking-lot/backlog-scrum-04-definition-of-done/proposal.md similarity index 100% rename from openspec/changes/backlog-scrum-04-definition-of-done/proposal.md rename to openspec/parking-lot/backlog-scrum-04-definition-of-done/proposal.md diff --git a/openspec/changes/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md b/openspec/parking-lot/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md similarity index 100% rename from openspec/changes/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md rename to openspec/parking-lot/backlog-scrum-04-definition-of-done/specs/definition-of-done/spec.md diff --git a/openspec/changes/backlog-scrum-04-definition-of-done/tasks.md b/openspec/parking-lot/backlog-scrum-04-definition-of-done/tasks.md similarity index 100% rename from openspec/changes/backlog-scrum-04-definition-of-done/tasks.md rename to openspec/parking-lot/backlog-scrum-04-definition-of-done/tasks.md diff --git a/openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml b/openspec/parking-lot/ceremony-02-requirements-aware-output/.openspec.yaml similarity index 100% rename from openspec/changes/ceremony-02-requirements-aware-output/.openspec.yaml rename to openspec/parking-lot/ceremony-02-requirements-aware-output/.openspec.yaml diff --git a/openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md b/openspec/parking-lot/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md similarity index 100% rename from openspec/changes/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md rename to openspec/parking-lot/ceremony-02-requirements-aware-output/CHANGE_VALIDATION.md diff --git a/openspec/changes/ceremony-02-requirements-aware-output/design.md b/openspec/parking-lot/ceremony-02-requirements-aware-output/design.md similarity index 100% rename from openspec/changes/ceremony-02-requirements-aware-output/design.md rename to openspec/parking-lot/ceremony-02-requirements-aware-output/design.md diff --git a/openspec/changes/ceremony-02-requirements-aware-output/proposal.md b/openspec/parking-lot/ceremony-02-requirements-aware-output/proposal.md similarity index 100% rename from openspec/changes/ceremony-02-requirements-aware-output/proposal.md rename to openspec/parking-lot/ceremony-02-requirements-aware-output/proposal.md diff --git a/openspec/changes/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md b/openspec/parking-lot/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md similarity index 100% rename from openspec/changes/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md rename to openspec/parking-lot/ceremony-02-requirements-aware-output/specs/backlog-refinement/spec.md diff --git a/openspec/changes/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md b/openspec/parking-lot/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md similarity index 100% rename from openspec/changes/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md rename to openspec/parking-lot/ceremony-02-requirements-aware-output/specs/ceremony-requirements-awareness/spec.md diff --git a/openspec/changes/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md b/openspec/parking-lot/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md similarity index 100% rename from openspec/changes/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md rename to openspec/parking-lot/ceremony-02-requirements-aware-output/specs/daily-standup/spec.md diff --git a/openspec/changes/ceremony-02-requirements-aware-output/tasks.md b/openspec/parking-lot/ceremony-02-requirements-aware-output/tasks.md similarity index 100% rename from openspec/changes/ceremony-02-requirements-aware-output/tasks.md rename to openspec/parking-lot/ceremony-02-requirements-aware-output/tasks.md diff --git a/openspec/specs/ai-ide-remediation-handoff/spec.md b/openspec/specs/ai-ide-remediation-handoff/spec.md new file mode 100644 index 00000000..14c103a7 --- /dev/null +++ b/openspec/specs/ai-ide-remediation-handoff/spec.md @@ -0,0 +1,23 @@ +# ai-ide-remediation-handoff Specification + +## Purpose +TBD - created by archiving change code-review-13-cleanup-forecast-agent-handoff. Update Purpose after archive. +## Requirements +### Requirement: Review JSON is the portable AI IDE handoff contract + +The Code Review bundle SHALL expose cleanup guidance through machine-readable JSON so Claude, Codex, Cursor, Copilot, and other assistants can act without vendor-specific prompt assumptions. + +#### Scenario: Remediation packets guide AI cleanup + +- **WHEN** a simplify-focused report contains cleanup findings +- **THEN** each actionable finding SHALL include or be able to derive a remediation packet +- **AND** the packet SHALL state whether the finding may be auto-fixed, needs tests, needs design judgment, or should be preserved +- **AND** the packet SHALL include a validation plan for any accepted cleanup + +#### Scenario: AI instructions prioritize the JSON contract + +- **WHEN** `specfact code review run --instructions` is executed +- **THEN** the instructions SHALL tell assistants to generate simplify evidence first +- **AND** they SHALL tell assistants to sort findings by `guidance_kind`, inspect `cleanup_forecast`, and follow remediation packets before editing +- **AND** they SHALL prohibit treating `ai_bloat` findings as proof of AI authorship + diff --git a/openspec/specs/backlog-add/spec.md b/openspec/specs/backlog-add/spec.md index a1539a73..f4faf332 100644 --- a/openspec/specs/backlog-add/spec.md +++ b/openspec/specs/backlog-add/spec.md @@ -39,3 +39,21 @@ The system SHALL provide `specfact backlog add` command that creates backlog ite - **THEN** the command forwards to `specfact backlog add` - **AND** all add options are available +### Requirement: Backlog add config updates SHALL preserve unrelated `.specfact` settings + +Any `specfact backlog add` helper flow that updates `.specfact/backlog-config.yaml` or related field-mapping config SHALL preserve unrelated user-managed settings while updating only the declared SpecFact-managed subtree. + +#### Scenario: Provider settings merge keeps unrelated config intact + +- **WHEN** a backlog-add helper updates provider settings in `.specfact/backlog-config.yaml` +- **AND** the file already contains unrelated provider settings or user-managed metadata +- **THEN** the command SHALL preserve the unrelated settings +- **AND** SHALL update only the targeted provider settings subtree + +#### Scenario: Mapping update preserves unrelated config state + +- **WHEN** `specfact backlog map-fields` refreshes mapping metadata under `.specfact/templates/backlog/` +- **AND** the corresponding `.specfact/backlog-config.yaml` already contains unrelated settings +- **THEN** the command SHALL keep the unrelated settings intact +- **AND** SHALL NOT silently replace the full config file + diff --git a/openspec/specs/backlog-delta/spec.md b/openspec/specs/backlog-delta/spec.md index a3776608..c9cfcc94 100644 --- a/openspec/specs/backlog-delta/spec.md +++ b/openspec/specs/backlog-delta/spec.md @@ -24,3 +24,21 @@ The system SHALL provide `specfact backlog delta` with subcommands for backlog c - **WHEN** the user runs `specfact backlog delta rollback-analysis` - **THEN** safe rollback paths and risks are presented +### Requirement: Backlog delta status resolves documented defaults + +`backlog delta status` SHALL resolve project and repository inputs consistently with other backlog commands where configuration defaults are available. + +#### Scenario: Delta status uses configured GitHub repository defaults + +- **GIVEN** `.specfact/backlog-config.yaml` contains a default GitHub repository owner and name +- **WHEN** the user runs `specfact backlog delta status github` +- **THEN** the command resolves the repository owner and name from configuration +- **AND** it does not require undocumented repo parameters. + +#### Scenario: Delta status exposes missing repository inputs + +- **GIVEN** required repository inputs are not present in CLI arguments or configuration +- **WHEN** the user runs `specfact backlog delta status` +- **THEN** the command help and error output names the missing kebab-case options +- **AND** the command does not emit raw internal names such as `repo_owner` or `repo_name`. + diff --git a/openspec/specs/backlog-sync/spec.md b/openspec/specs/backlog-sync/spec.md index 920e0b8e..f7139962 100644 --- a/openspec/specs/backlog-sync/spec.md +++ b/openspec/specs/backlog-sync/spec.md @@ -3,9 +3,7 @@ ## Purpose TBD - created by archiving change backlog-02-migrate-core-commands. Update Purpose after archive. - ## Requirements - ### Requirement: Restore backlog sync command functionality The system SHALL provide `specfact backlog sync` command for bidirectional backlog synchronization, and related governance workflows SHALL resolve current Epic and Feature planning metadata from **`.specfact/backlog/github_hierarchy_cache.md`**, with deterministic sync state in **`.specfact/backlog/github_hierarchy_cache_state.json`**, before performing manual GitHub lookups. Tools that participate in backlog or OpenSpec workflows MUST read and write those exact paths (or invoke `python scripts/sync_github_hierarchy_cache.py`, which uses them by default) and MUST fall back to live GitHub lookup only when the files are missing, unreadable, or stale per governance rules. @@ -59,3 +57,21 @@ The backlog sync system SHALL check for existing issue mappings from external to - **WHEN** `specfact backlog sync` runs - **THEN** the sync creates issues for all tasks as before (no behavior change) - **AND** no spec-kit extension detection is attempted + +### Requirement: Backlog sync SHALL distinguish managed `.specfact` state from external output targets + +Any `specfact backlog sync` local artifact path SHALL distinguish between fully owned managed state under `.specfact` and explicit output targets outside `.specfact`. + +#### Scenario: Default managed baseline state updates deterministically + +- **WHEN** backlog sync updates its default baseline state under `.specfact` +- **THEN** the command MAY rewrite that managed artifact deterministically +- **AND** SHALL treat it as SpecFact-managed state rather than a user-owned external file + +#### Scenario: Explicit external baseline target is not silently overwritten + +- **WHEN** backlog sync is configured to write a baseline or comparable output path outside `.specfact` +- **AND** the target file already exists +- **THEN** the command SHALL fail safe, merge safely, or require explicit replacement according to the declared ownership mode +- **AND** SHALL NOT silently overwrite the existing user-owned file + diff --git a/openspec/specs/bundle-overview-pages/spec.md b/openspec/specs/bundle-overview-pages/spec.md index 231af17b..7c267076 100644 --- a/openspec/specs/bundle-overview-pages/spec.md +++ b/openspec/specs/bundle-overview-pages/spec.md @@ -43,3 +43,29 @@ Each official bundle SHALL have a single overview page that lists its commands, - **AND** subsequent links SHALL point to each command deep-dive page under that bundle's directory - **AND** no link SHALL point to the generic `/reference/commands/` placeholder +### Requirement: Bundle overview links SHALL resolve as published URLs + +Bundle overview pages SHALL use links that resolve correctly from the published overview permalink route, including "See also", prerequisite, deep-dive, and related-bundle links. + +#### Scenario: Code Review overview links to run page + +- **WHEN** the Code Review overview page is published at `/bundles/code-review/overview/` +- **THEN** its "Code review run" link resolves to `/bundles/code-review/run/` +- **AND** the link does not resolve to `/bundles/code-review/overview/run/` + +#### Scenario: Cross-bundle overview link resolves + +- **WHEN** a bundle overview page links to another bundle overview page +- **THEN** the link resolves to the target bundle's canonical published overview route +- **AND** docs validation fails if the link resolves to a route nested under the source overview page + +### Requirement: Bundle overview-related links SHALL be covered by docs validation tests + +The bundle overview docs test suite SHALL include coverage that fails when any overview page contains a body link that is valid by source-file path but broken under published permalink semantics. + +#### Scenario: Source-valid but published-broken link is rejected + +- **WHEN** an overview page links to a sibling page using a source-file-relative shorthand that would publish below the overview permalink +- **THEN** the overview link test reports the generated public route mismatch +- **AND** the test fails before the docs can be published + diff --git a/openspec/specs/bundle-packaged-resources/spec.md b/openspec/specs/bundle-packaged-resources/spec.md index 4a9bf1df..089aadfc 100644 --- a/openspec/specs/bundle-packaged-resources/spec.md +++ b/openspec/specs/bundle-packaged-resources/spec.md @@ -4,30 +4,18 @@ TBD - created by archiving change packaging-01-bundle-resource-payloads. Update Purpose after archive. ## Requirements ### Requirement: Official bundles SHALL ship module-owned resource payloads -Each official bundle package SHALL include the prompt templates and other non-code resources that are owned by that bundle's workflows or commands. Bundle-owned resources SHALL not depend on fallback storage under the core CLI repository. -#### Scenario: Official bundles ship the audited prompt inventory -- **WHEN** the audited prompt inventory from `RESOURCE_OWNERSHIP_AUDIT.md` is inspected -- **THEN** each prompt template's canonical packaged source exists under the owning official bundle package -- **AND** the ownership mapping covers the codebase, project, spec, govern, and backlog bundles for the currently supported prompt set +Each official bundle package SHALL include the prompt templates and other non-code resources that are owned by that bundle's workflows or commands. Bundle-owned resources SHALL not depend on fallback storage under the core CLI repository. -#### Scenario: Backlog bundle ships the restored slash-prompt inventory -- **WHEN** the backlog bundle package is inspected from source or from an installed artifact -- **THEN** `resources/prompts/` contains `specfact.backlog-add.md`, `specfact.backlog-daily.md`, `specfact.backlog-refine.md`, and `specfact.sync-backlog.md` -- **AND** those prompt files are treated as canonical bundle-owned sources rather than historical leftovers +#### Scenario: Project runtime generators ship required Jinja2 templates -#### Scenario: Prompt companion resources ship with prompt payloads -- **WHEN** an exported prompt template references a companion file by relative path, such as `./shared/cli-enforcement.md` -- **THEN** the owning bundle package contains that companion resource in a stable relative location -- **AND** prompt export/copy flows can preserve a resolvable relative layout in the target IDE workspace +- **WHEN** the project bundle is built, installed, or imported from an editable checkout +- **THEN** every generator template referenced by the project runtime exists under the bundle-owned packaged resource paths +- **AND** runtime template lookup resolves those packaged templates without depending on files from the core CLI repository -#### Scenario: Backlog bundle ships workspace-template seed resources -- **WHEN** the backlog bundle package is inspected from source or from an installed artifact -- **THEN** the package contains the backlog field mapping templates that `specfact init` or related flows need to copy into workspace state -- **AND** the packaged set includes both ADO and non-ADO seed templates required by supported backlog flows +#### Scenario: Missing generator templates fail bundle payload validation -#### Scenario: Core no longer remains the source of truth for bundle prompts -- **WHEN** a workflow prompt belongs to an extracted bundle rather than to core lifecycle commands -- **THEN** that prompt's canonical packaged source exists in the owning bundle package -- **AND** release packaging does not rely on the core CLI repo as the canonical source for that prompt +- **WHEN** a required project runtime template such as `protocol.yaml.j2` or `github-action.yml.j2` is absent from the package payload +- **THEN** bundle resource validation SHALL fail before release +- **AND** the failure message SHALL name the missing template path so the packaging defect can be corrected before publish diff --git a/openspec/specs/ci-integration/spec.md b/openspec/specs/ci-integration/spec.md index 91984337..f7c3d812 100644 --- a/openspec/specs/ci-integration/spec.md +++ b/openspec/specs/ci-integration/spec.md @@ -44,7 +44,7 @@ for pull requests or pushes targeting `dev`; it SHALL enforce `--require-signatu #### Scenario: Dev-to-main PR after CI signing commit - **WHEN** a pull request targets `main` -- **AND** the CI `sign-modules-on-approval` workflow has committed signed manifests to the PR branch +- **AND** the CI signing workflow has committed signed manifests to the PR branch - **THEN** the `verify-module-signatures` job SHALL pass with `--require-signature` - **AND** the PR SHALL be unblocked (subject to other required checks) @@ -70,3 +70,4 @@ The repository pre-commit hook that runs `verify-modules-signature.py` SHALL app - **WHEN** a developer commits on branch `main` - **AND** any `packages/*/module-package.yaml` lacks a valid signature under `--require-signature` - **THEN** the pre-commit signature hook SHALL fail + diff --git a/openspec/specs/ci-module-signing-on-approval/spec.md b/openspec/specs/ci-module-signing-on-approval/spec.md index aa8509e5..c0b9129f 100644 --- a/openspec/specs/ci-module-signing-on-approval/spec.md +++ b/openspec/specs/ci-module-signing-on-approval/spec.md @@ -11,18 +11,17 @@ and SHALL commit the signed manifests back to the PR branch. #### Scenario: PR to dev approved with package module changes -- **WHEN** a pull request targeting `dev` is approved by a reviewer +- **WHEN** a pull request targeting `dev` is approved by a trusted reviewer - **AND** the PR contains changes to one or more files under `packages/` - **THEN** the CI signing workflow SHALL discover all `packages/*/module-package.yaml` manifests - whose payload changed on the PR branch since the merge-base with `origin/dev` (not merely - divergent from the moving `origin/dev` tip) + whose payload changed on the PR branch since the merge-base with `origin/dev` - **AND** SHALL sign them using `SPECFACT_MODULE_PRIVATE_SIGN_KEY` and `SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE` - **AND** SHALL commit the updated manifests back to the PR branch #### Scenario: PR to main approved with package module changes -- **WHEN** a pull request targeting `main` is approved +- **WHEN** a pull request targeting `main` is approved by a trusted reviewer - **AND** the PR contains changes to one or more files under `packages/` - **THEN** the CI signing workflow SHALL sign all changed manifests relative to the merge-base between the PR head and `origin/main` @@ -52,8 +51,7 @@ and SHALL commit the signed manifests back to the PR branch. - **WHEN** a pull request targets `dev` or `main` but the head branch lives in a fork (`head.repo` differs from the base repository) -- **THEN** the signing workflow SHALL NOT run (the default `GITHUB_TOKEN` cannot push to the - contributor fork; maintainers sign or merge via same-repo branches instead) +- **THEN** the signing workflow SHALL NOT run ### Requirement: Manifest discovery covers packages directory @@ -72,3 +70,4 @@ from `src/specfact_cli/modules/` or `modules/` (which do not exist in this repos - **WHEN** the signing workflow runs twice on the same package payload - **THEN** the resulting `integrity:` block SHALL be byte-for-byte identical - **AND** the second run SHALL produce no git diff and SHALL skip the commit + diff --git a/openspec/specs/clean-code-analysis/spec.md b/openspec/specs/clean-code-analysis/spec.md index e78a250b..50991a94 100644 --- a/openspec/specs/clean-code-analysis/spec.md +++ b/openspec/specs/clean-code-analysis/spec.md @@ -18,3 +18,19 @@ The review bundle SHALL emit governed findings for the clean-code categories req - **THEN** the checks run without introducing a Node.js dependency - **AND** each finding is attributed to `solid`, `yagni`, or `dry` respectively +### Requirement: Clean-code signals can contribute to simplification feedback + +The clean-code analysis layer SHALL allow high-confidence `dry` and `kiss` findings to contribute to the simplification feedback queue when they include deterministic rewrite or consolidation evidence. This SHALL NOT change the existing clean-code category semantics or blocking policy. + +#### Scenario: High-confidence duplicate shape contributes related locations + +- **WHEN** AST clean-code analysis detects duplicate intent with stable related locations +- **THEN** the finding MAY include simplification metadata such as `intent_key`, `rewrite_hint`, and `related_locations` +- **AND** the finding SHALL retain its governed category, such as `dry`, when that category is the primary principle + +#### Scenario: Clean-code policy remains unchanged + +- **WHEN** a clean-code finding contributes to the simplification queue +- **THEN** its existing category and severity semantics SHALL remain unchanged +- **AND** inclusion in `--focus simplify` SHALL NOT by itself make the finding more severe + diff --git a/openspec/specs/cleanup-forecast-review/spec.md b/openspec/specs/cleanup-forecast-review/spec.md new file mode 100644 index 00000000..7880fde2 --- /dev/null +++ b/openspec/specs/cleanup-forecast-review/spec.md @@ -0,0 +1,44 @@ +# cleanup-forecast-review Specification + +## Purpose +TBD - created by archiving change code-review-13-cleanup-forecast-agent-handoff. Update Purpose after archive. +## Requirements +### Requirement: Simplify review reports include cleanup forecasts + +Simplify-focused review reports SHALL include a cleanup forecast that quantifies likely cleanup impact without treating estimates as guaranteed deletions. + +#### Scenario: Forecast summarizes reviewed LOC and deletion estimates + +- **WHEN** `specfact code review run --focus simplify --json` emits guided simplification findings +- **THEN** the report SHALL include `cleanup_forecast.reviewed_loc` +- **AND** it SHALL include low, expected, and high estimated deletion-line totals +- **AND** it SHALL include deletion estimates grouped by `guidance_kind` +- **AND** legacy report consumers SHALL still be able to ignore the new field + +#### Scenario: Forecast exposes normalized AI-bloat index + +- **WHEN** a cleanup forecast is present +- **THEN** it SHALL include normalized metrics per KLOC for finding density, weighted bloat points, and cleanup yield +- **AND** the default weights SHALL be `safe_mechanical=1.0`, `needs_tests=0.6`, `design_judgment=0.25`, and `preserve=0.0` +- **AND** preserve findings SHALL contribute no weighted bloat points + +### Requirement: Cleanup forecasts distinguish advice from proof + +The cleanup forecast SHALL distinguish estimate-only signals from previewed or mutation-backed proof. + +#### Scenario: Preview evidence upgrades forecast confidence + +- **WHEN** `--preview-fixes` computes a patch forecast for safe-mechanical findings +- **THEN** the cleanup forecast SHALL include preview evidence for affected findings +- **AND** the preview SHALL report added, removed, and net line counts without editing tracked files + +#### Scenario: Mutation evidence is opt-in + +- **WHEN** `--with-mutation` is not provided +- **THEN** the review SHALL NOT run mutation testing +- **AND** the report SHALL NOT imply mutation-backed proof exists + +- **WHEN** `--with-mutation` is provided for simplify focus +- **THEN** mutation outcomes SHALL be recorded as evidence for candidate findings +- **AND** timeouts or unavailable mutation tooling SHALL be recorded as inconclusive rather than safe cleanup proof + diff --git a/openspec/specs/code-review-ai-bloat-detection/spec.md b/openspec/specs/code-review-ai-bloat-detection/spec.md new file mode 100644 index 00000000..6d15706e --- /dev/null +++ b/openspec/specs/code-review-ai-bloat-detection/spec.md @@ -0,0 +1,103 @@ +# code-review-ai-bloat-detection Specification + +## Purpose +TBD - created by archiving change code-review-ai-bloat-detection. Update Purpose after archive. +## Requirements +### Requirement: The code-review runner SHALL emit findings under a new `ai_bloat` principle category + +The code-review pipeline SHALL recognise `ai_bloat` as a valid value of the `category` field on `ReviewFinding` and as the policy-pack `principle` for all AI-bloat rules. The new category SHALL surface in `.specfact/code-review.json` alongside the existing categories `naming | kiss | yagni | dry | solid | clean_code | architecture` through an additive strict-schema update. Findings under `ai_bloat` SHALL emit at `info` severity only (the non-blocking severity already accepted by `ReviewFinding`); the runner SHALL never emit `ai_bloat` findings at `warning` or `error` severity in this iteration. The `advisory` framing is carried at the policy-pack layer via `default_mode: advisory`, not by introducing a new per-finding severity value. `ai_bloat` findings SHALL be score-neutral in v1. + +#### Scenario: Review run on a fixture with a manual-loop comprehension emits an ai_bloat finding + +- **WHEN** `specfact code review run --json --out .specfact/code-review.json --scope full` runs against a fixture file containing a `for x in xs: out.append(...)` loop whose shape matches the `ai-bloat.manual-loop-comprehension` rule +- **THEN** the resulting JSON SHALL contain at least one finding whose `category` equals `ai_bloat`, `severity` equals `info`, and whose rule ID is `ai-bloat.manual-loop-comprehension` +- **AND** the finding SHALL reference the source file path and the starting line of the matched loop + +#### Scenario: Review scoring ignores ai_bloat findings + +- **WHEN** a review report contains only `ai_bloat` findings at `info` severity +- **THEN** those findings SHALL NOT reduce the governed review score +- **AND** the report SHALL remain non-blocking + +#### Scenario: Review run on the simplified equivalent emits no ai_bloat finding + +- **WHEN** the same review command runs against a fixture file containing only the simplified comprehension equivalent +- **THEN** the resulting JSON SHALL NOT contain any finding with `category=ai_bloat` for that file + +#### Scenario: Pre-commit hook does not block on ai_bloat findings + +- **WHEN** the pre-commit hook at `scripts/pre_commit_code_review.py` runs and the resulting JSON contains `ai_bloat` findings at `info` severity but no findings at `error` severity +- **THEN** the hook SHALL exit with status zero +- **AND** the hook SHALL surface `ai_bloat` findings in `.specfact/code-review.json` regardless of the hook's `--level` block-threshold filter, so the JSON evidence is complete even when only `error`-severity findings would block the commit +- **AND** the hook SHALL still print a human-readable summary of the `ai_bloat` findings to stderr so the user is aware before committing + +### Requirement: A packaged semgrep rule pack SHALL detect pattern-shape AI bloat + +The `specfact-code-review` bundle SHALL ship a semgrep rule pack at `resources/semgrep-rules/ai-bloat.yaml` containing detectors for `ai-bloat.manual-loop-comprehension`, `ai-bloat.passthrough-lambda`, `ai-bloat.identity-try-except`, `ai-bloat.none-then-none`, and `ai-bloat.single-call-wrapper`. The semgrep runner SHALL load this pack alongside the existing rule packs and SHALL map each new rule ID to `category=ai_bloat` in `SEMGREP_RULE_CATEGORY`. + +#### Scenario: Each pattern-shape rule flags its bloated fixture + +- **WHEN** the semgrep runner is invoked on a fixture file containing the bloated form for any of the five pattern-shape rules +- **THEN** the runner SHALL emit a finding for that file with the corresponding rule ID and `category=ai_bloat` + +#### Scenario: Each pattern-shape rule ignores its simplified fixture + +- **WHEN** the semgrep runner is invoked on a fixture file containing only the simplified equivalent +- **THEN** the runner SHALL NOT emit a finding under any of the five pattern-shape rule IDs for that file + +### Requirement: A packaged AST runner SHALL detect semantic AI bloat + +The `specfact-code-review` bundle SHALL ship an AST runner at `src/specfact_code_review/tools/ai_bloat_runner.py` implementing conservative local detectors for `ai-bloat.unused-optional-param`, `ai-bloat.dead-branch`, `ai-bloat.loc-vs-complexity`, and `ai-bloat.redundant-intermediate`. The LOC-vs-complexity detector SHALL use default thresholds of LOC >= 40 and local branch/call complexity <= 4. The runner SHALL be wired into the review orchestration so its findings flow into the same `ReviewFinding` stream as the other tool runners. + +#### Scenario: Unused-Optional-param detector flags a parameter that is never tested for None + +- **WHEN** the AST runner analyses a function whose signature includes a parameter annotated `Optional[T] = None` and whose body never references the parameter inside an `is None` or `is not None` check +- **THEN** the runner SHALL emit a finding with rule ID `ai-bloat.unused-optional-param` and `category=ai_bloat` + +#### Scenario: LOC-vs-complexity detector flags long but linear functions + +- **WHEN** the AST runner analyses a function with line count at or above the configured LOC floor and cyclomatic complexity at or below the configured complexity ceiling +- **THEN** the runner SHALL emit a finding with rule ID `ai-bloat.loc-vs-complexity` and `category=ai_bloat` + +#### Scenario: Detectors are silent on idiomatic code + +- **WHEN** the AST runner analyses a function whose `Optional` parameters all branch on `None`, whose branches are all reachable, whose LOC-to-complexity ratio is within thresholds, and whose intermediate variables either are read multiple times or carry naming clarity +- **THEN** the runner SHALL NOT emit any `ai_bloat` finding for that function + +### Requirement: A dedicated policy pack SHALL register the new rules under `principle: ai_bloat` + +The `specfact-code-review` bundle SHALL ship a policy pack at `resources/policy-packs/specfact/ai-bloat-patterns.yaml` with `pack_ref: specfact/ai-bloat-patterns`, `default_mode: advisory`, and one entry per rule ID listed above, each tagged `principle: ai_bloat`. The pack SHALL be parallel to `clean-code-principles.yaml` so adopters can enable or disable the two packs independently. + +#### Scenario: Policy pack references only existing rules + +- **WHEN** the contract test loads `ai-bloat-patterns.yaml` +- **THEN** every rule ID in the pack SHALL exist either in the semgrep rule pack `resources/semgrep-rules/ai-bloat.yaml` or as a detector emitted by `ai_bloat_runner.py` +- **AND** every rule entry in the pack SHALL specify `principle: ai_bloat` + +### Requirement: An IDE slash-command prompt SHALL drive targeted rewrites + +The `specfact-project` bundle SHALL ship a prompt resource at `resources/prompts/specfact.08-simplify.md` that drives an LLM-assisted rewrite workflow in the user's IDE. The prompt SHALL: read `.specfact/code-review.json`, filter findings where `category=ai_bloat`, group by file and then by rule ID, present each candidate with a rewrite hint, drive a per-change accept/reject/skip/explain loop, apply accepted edits via the IDE's edit tool, and suggest re-running the review afterwards. The prompt SHALL NOT edit files autonomously and SHALL NOT skip the per-change confirmation step. + +#### Scenario: Slash command runs with no ai_bloat findings present + +- **WHEN** the user invokes `/specfact.08-simplify` in an IDE session whose `.specfact/code-review.json` contains no findings with `category=ai_bloat` +- **THEN** the prompt SHALL report that there are no ai-bloat candidates and exit without modifying any files + +#### Scenario: Slash command walks the user through findings with confirmation + +- **WHEN** the user invokes `/specfact.08-simplify` and the JSON contains one or more `ai_bloat` findings +- **THEN** the prompt SHALL present each finding in turn with its source snippet, rule ID, and rewrite hint +- **AND** the prompt SHALL ask the user to accept, reject, skip, or request explanation before applying any edit +- **AND** the prompt SHALL apply only the edits the user accepts + +### Requirement: The clean-code policy pack documentation SHALL note the parallel ai-bloat pack + +The clean-code policy-pack documentation SHALL note that `ai-bloat-patterns.yaml` is a parallel policy pack with independent enable/disable semantics, an `advisory`-only severity model, and a dedicated `ai_bloat` principle category. The documentation SHALL state that adopting `clean-code-principles.yaml` does not automatically enable `ai-bloat-patterns.yaml` and vice versa. + +#### Scenario: Documentation describes the two packs as independent + +- **WHEN** a reader consults the clean-code policy-pack documentation +- **THEN** the documentation SHALL state explicitly that `ai-bloat-patterns.yaml` is a separate policy pack +- **AND** SHALL state that its severity model is `advisory`-only +- **AND** SHALL state that its principle category is `ai_bloat`, distinct from the existing principle categories (`naming | kiss | yagni | dry | solid | clean_code | architecture`) + diff --git a/openspec/specs/code-review-simplification-feedback/spec.md b/openspec/specs/code-review-simplification-feedback/spec.md new file mode 100644 index 00000000..5760dcd2 --- /dev/null +++ b/openspec/specs/code-review-simplification-feedback/spec.md @@ -0,0 +1,81 @@ +# code-review-simplification-feedback Specification + +## Purpose +TBD - created by archiving change code-review-11-simplification-feedback-loop. Update Purpose after archive. +## Requirements +### Requirement: Review findings carry optional simplification metadata + +The code-review report SHALL support optional simplification metadata on each finding so IDE prompts can prioritize and explain advisory cleanup without inferring intent from free-form messages. The metadata SHALL be additive and SHALL NOT remove or rename existing `ReviewFinding` fields. + +#### Scenario: Finding includes simplification metadata + +- **WHEN** a simplification-capable detector emits a finding +- **THEN** the finding MAY include `confidence`, `rewrite_hint`, `canonical_pattern`, `intent_key`, `estimated_deletion_lines`, and `related_locations` +- **AND** each included metadata field SHALL be serializable in `.specfact/code-review.json` +- **AND** existing required fields such as `category`, `severity`, `tool`, `rule`, `file`, `line`, `message`, and `fixable` SHALL remain present + +#### Scenario: Consumer ignores simplification metadata + +- **WHEN** an existing consumer reads a report containing simplification metadata +- **THEN** the existing consumer SHALL be able to rely on the original required finding fields +- **AND** the metadata SHALL be optional so consumers that do not understand it can ignore it + +### Requirement: Simplification analyzers detect deterministic overengineering patterns + +The code-review bundle SHALL emit advisory simplification findings for deterministic Python overengineering patterns where a standard language or library pattern is safer and simpler than custom control flow. + +#### Scenario: Analyzer flags a verbose pattern with a standard rewrite hint + +- **WHEN** the analyzer finds a manual accumulator loop, verbose boolean return, redundant `None` branch, wrapper chain, pass-through defensive `try/except`, one-use temporary, table-lookup candidate, or stdlib replacement candidate +- **THEN** the report SHALL include an advisory simplification finding +- **AND** the finding SHALL include a `rewrite_hint` describing the standard pattern to consider +- **AND** the finding SHALL NOT be emitted at `error` severity + +#### Scenario: Analyzer stays silent on ambiguous code + +- **WHEN** the analyzer cannot determine a simpler standard pattern with high confidence +- **THEN** it SHALL NOT emit a simplification finding for that code + +### Requirement: Duplicate-intent grouping is deterministic and domain-aware + +The code-review bundle SHALL group likely duplicate-intent functions only when deterministic static evidence indicates that the functions serve the same business or domain purpose. + +#### Scenario: Same-intent functions are grouped + +- **WHEN** two or more reviewed functions have compatible normalized AST shapes, compatible call roots or imported APIs, and matching package/domain vocabulary +- **THEN** the review report SHALL include a simplification finding with a stable `intent_key` +- **AND** the finding SHALL include `related_locations` for the other functions in the group +- **AND** the finding message SHALL describe the group as a consolidation candidate rather than a correctness failure + +#### Scenario: Similar names alone do not create a group + +- **WHEN** two functions have similar names but incompatible AST shape, call roots, or domain context +- **THEN** the duplicate-intent detector SHALL NOT group them solely because of name similarity + +### Requirement: Simplification feedback remains advisory and score-neutral + +Simplification findings SHALL remain advisory, score-neutral, and non-blocking in v1. + +#### Scenario: Simplification-only report remains non-blocking + +- **WHEN** a review report contains only simplification findings +- **THEN** those findings SHALL NOT reduce the governed review score +- **AND** the review SHALL NOT fail because of those findings +- **AND** the findings SHALL remain available in `.specfact/code-review.json` for IDE feedback + +### Requirement: IDE simplify prompt consumes grouped evidence + +The `/specfact.08-simplify` prompt SHALL consume simplification metadata from `.specfact/code-review-simplify.json` and use it to guide one confirmed rewrite at a time. + +#### Scenario: Prompt groups by intent before proposing rewrites + +- **WHEN** `.specfact/code-review-simplify.json` contains findings with `intent_key` values +- **THEN** `/specfact.08-simplify` SHALL group candidates by `intent_key`, then by file or domain and rule +- **AND** it SHALL show related locations before drafting a rewrite for a grouped candidate + +#### Scenario: Prompt preserves explicit confirmation + +- **WHEN** `/specfact.08-simplify` presents a simplification candidate +- **THEN** it SHALL ask the user to accept, reject, skip, or request explanation before applying any edit +- **AND** it SHALL apply only edits the user accepts + diff --git a/openspec/specs/code-review-tool-dependencies/spec.md b/openspec/specs/code-review-tool-dependencies/spec.md index 04b4ac46..392e8a9d 100644 --- a/openspec/specs/code-review-tool-dependencies/spec.md +++ b/openspec/specs/code-review-tool-dependencies/spec.md @@ -68,3 +68,21 @@ The repository SHALL include an automated check (unit test or small validation s - **WHEN** that package is removed from `pip_dependencies` without updating the map - **THEN** `hatch run test` (or the chosen gate) fails with a clear assertion message +### Requirement: Tool dependency diagnostics use active environment context + +Tool dependency checks SHALL probe the active uv, hatch, pip, or pipx execution context before reporting a tool as unavailable. + +#### Scenario: Semgrep available through uv is detected + +- **GIVEN** a project where `uv run semgrep --version` succeeds +- **WHEN** a codebase or code-review module checks semgrep availability +- **THEN** semgrep is reported as available +- **AND** the diagnostic does not tell the user to install semgrep with a pip-only command. + +#### Scenario: Missing tool hints match active manager + +- **GIVEN** a required tool is unavailable +- **WHEN** a module emits an installation hint +- **THEN** the hint matches the active manager context when known +- **AND** the output identifies which manager context was checked. + diff --git a/openspec/specs/codebase-import-runtime/spec.md b/openspec/specs/codebase-import-runtime/spec.md new file mode 100644 index 00000000..f8c9cf02 --- /dev/null +++ b/openspec/specs/codebase-import-runtime/spec.md @@ -0,0 +1,59 @@ +# codebase-import-runtime Specification + +## Purpose +TBD - created by archiving change codebase-import-runtime-hardening. Update Purpose after archive. +## Requirements +### Requirement: Import runtime SHALL prune hidden and heavyweight trees before discovery + +`specfact code import` SHALL apply one deterministic ignore policy before any repository traversal phase counts, discovers, or analyzes candidate files. The default policy SHALL exclude dot-prefixed directories, virtual environments, build outputs, dependency caches, and other heavyweight artifact roots unless the user explicitly targets a path inside them. + +The implementation MUST apply ignore policies in the following explicit order: + +1. First, load the deterministic default ignore policy +2. Then, read and merge `.specfact/.specfactignore` patterns +3. Finally, apply explicit user target paths (which override ignored paths) + +#### Scenario: Default traversal skips hidden and heavyweight directories + +- **WHEN** the user runs `specfact code import` against a repository root that contains directories such as `.git/`, `.specfact/`, `.venv/`, `venv/`, `node_modules/`, `build/`, `dist/`, or `__pycache__/` +- **THEN** import discovery SHALL prune those directories before recursive traversal +- **AND** those files SHALL NOT contribute to scanned-file counts, analyzer inputs, or relationship extraction inputs + +#### Scenario: Repo-local ignore file extends the default policy + +- **WHEN** the repository contains `.specfact/.specfactignore` with additional ignore patterns +- **THEN** `specfact code import` SHALL merge those patterns with the default ignore policy for every traversal phase +- **AND** matching files or directories SHALL be pruned before traversal rather than filtered only after discovery + +### Requirement: Import runtime SHALL surface large-artifact warnings + +The import runtime SHALL warn when repository traversal encounters unusually large ignored artifact trees or unexpectedly high file volumes that are likely to dominate wall-clock time on slow environments. + +#### Scenario: Encountering a heavy artifact tree emits a warning + +- **WHEN** import discovery encounters an ignored directory whose file count crosses the runtime's heavy-artifact threshold +- **THEN** the command SHALL emit a warning that names the directory or pattern class +- **AND** the warning SHALL explain that the tree was ignored to avoid inflated import duration + +#### Scenario: Encountering unusually large candidate file volume emits a warning + +- **WHEN** the import runtime discovers a candidate file volume that exceeds its large-repository warning threshold after pruning ignored trees +- **THEN** the command SHALL warn that repository size and environment overhead can materially extend import duration +- **AND** it SHALL avoid promising a fixed-duration expectation such as "about five minutes" + +### Requirement: Import progress SHALL use discovered-versus-processed work + +Long-running import phases SHALL derive percentage and remaining-time feedback from the amount of real work discovered after ignore pruning, not from optimistic static estimates or totals that include skipped files. + +#### Scenario: Analyzer progress total reflects analyzable files only + +- **WHEN** the analyzer computes its progress task for a repository import +- **THEN** the total work units SHALL equal the filtered set of analyzable files after ignore pruning +- **AND** progress completion SHALL be able to reach 100 percent without stalling below the total because skipped files were counted + +#### Scenario: Remaining time updates from live discovered work + +- **WHEN** the command has discovered part of the repository and has processed a subset of that discovered work +- **THEN** the remaining-time display SHALL be derived from processed-versus-discovered work at the current runtime rate +- **AND** any early estimate before full discovery SHALL be labeled as provisional rather than a fixed promise + diff --git a/openspec/specs/guided-simplification-review/spec.md b/openspec/specs/guided-simplification-review/spec.md new file mode 100644 index 00000000..c3f30c39 --- /dev/null +++ b/openspec/specs/guided-simplification-review/spec.md @@ -0,0 +1,67 @@ +# guided-simplification-review Specification + +## Purpose +TBD - created by archiving change code-review-12-guided-simplification-enforcement. Update Purpose after archive. +## Requirements +### Requirement: Simplification findings classify cleanup safety + +Simplify-focused review findings SHALL classify each simplification candidate into a guidance kind that tells developers and LLM agents how to act safely. + +#### Scenario: Finding describes safe mechanical cleanup + +- **WHEN** a deterministic simplification rule identifies behavior-preserving cleanup +- **THEN** the finding SHALL include `guidance_kind="safe_mechanical"` +- **AND** it SHALL include `recommended_action`, `rationale`, `clean_code_principle`, and `safety_checks` +- **AND** the recommended action SHALL be specific enough for an LLM to explain or apply without inferring intent from the free-form message + +#### Scenario: Finding preserves meaningful structure + +- **WHEN** a candidate occurs in a meaningful contract, interface, public compatibility, CLI boundary, or domain predicate context +- **THEN** the finding SHALL use `guidance_kind="preserve"` or `guidance_kind="design_judgment"` +- **AND** `preserve` findings SHALL include a `preserve_reason` +- **AND** the finding SHALL NOT be eligible for automatic cleanup + +### Requirement: Guided simplification reports summarize recommendations and outcomes + +Review reports containing guided simplification findings SHALL summarize what was recommended, applied, kept, skipped, failed, and still present. + +#### Scenario: Report contains guidance summary + +- **WHEN** a simplify-focused run emits guided simplification findings +- **THEN** the report SHALL include a `simplification_summary` +- **AND** the summary SHALL count findings by `guidance_kind` +- **AND** it SHALL count findings by `action_status` when status is present +- **AND** it SHALL include the number of blocking simplification findings under simplify enforcement + +#### Scenario: Auto-fix records improvement evidence + +- **WHEN** `--focus simplify --fix` applies a safe mechanical rewrite +- **THEN** the resulting report SHALL indicate that the finding was applied or cleared +- **AND** it SHALL record before/after references or improvement evidence sufficient for an LLM to summarize what changed + +### Requirement: Interactive simplify prompt adapts to user level + +The `/specfact.08-simplify` prompt SHALL adapt guidance depth and confirmation behavior to the user's walkthrough level. + +#### Scenario: Prompt asks for walkthrough level + +- **WHEN** the prompt starts without an explicit level argument +- **THEN** it SHALL ask whether the user wants vibe-coder, junior developer, senior/pro, or headless-agent guidance +- **AND** it SHALL explain the practical difference between those levels before proceeding + +#### Scenario: Headless mode stays conservative + +- **WHEN** the prompt or skill is used in headless-agent mode +- **THEN** it SHALL default to review-only behavior unless the user explicitly requested safe automatic application +- **AND** it SHALL apply only findings marked safe for automatic cleanup + +### Requirement: Skill carries the guided simplify decision policy + +The `specfact-code-review` skill SHALL guide LLMs to interpret simplify-focused findings consistently across IDE and CLI contexts. + +#### Scenario: Skill explains action policy + +- **WHEN** an LLM uses the `specfact-code-review` skill to act on simplify findings +- **THEN** the skill SHALL instruct it to apply `safe_mechanical`, test `needs_tests`, inspect `design_judgment`, and keep `preserve` +- **AND** it SHALL prohibit treating AI-bloat findings as proof of AI authorship + diff --git a/openspec/specs/module-cli-error-contract/spec.md b/openspec/specs/module-cli-error-contract/spec.md new file mode 100644 index 00000000..bfe0c801 --- /dev/null +++ b/openspec/specs/module-cli-error-contract/spec.md @@ -0,0 +1,41 @@ +# module-cli-error-contract Specification + +## Purpose +TBD - created by archiving change tester-module-cli-reliability. Update Purpose after archive. +## Requirements +### Requirement: Module Commands Follow Shared CLI Error Contract + +Module command groups and leaf commands SHALL render actionable help for missing subcommands and missing required parameters. + +#### Scenario: Backlog auth without subcommand shows help and missing-subcommand guidance + +- **GIVEN** the user invokes `specfact backlog auth` +- **WHEN** no auth subcommand is provided +- **THEN** the output includes `backlog auth` help +- **AND** it states that a subcommand is required +- **AND** it lists provider/status/clear subcommands +- **AND** the command exits with a usage-error status. + +#### Scenario: Backlog delta status names missing required inputs + +- **GIVEN** the user invokes `specfact backlog delta status` without resolvable project or repository inputs +- **WHEN** required inputs cannot be resolved from CLI arguments or configuration +- **THEN** the output includes command help +- **AND** it names the missing CLI options using kebab-case option names +- **AND** it does not emit undocumented snake_case parameter names. + +#### Scenario: Code import legacy option ordering is actionable + +- **GIVEN** the user invokes `specfact code import --repo .` +- **WHEN** that ordering is not accepted by the command contract +- **THEN** the output includes help or migration guidance +- **AND** it shows the canonical supported invocation +- **AND** it does not report only `No such command '--repo'`. + +#### Scenario: Project regenerate null bundle data is typed + +- **GIVEN** project bundle processing encounters missing or null bundle data +- **WHEN** `specfact project regenerate` runs +- **THEN** the command reports a typed validation or bundle-data diagnostic +- **AND** it does not crash with a raw `NoneType` attribute error. + diff --git a/openspec/specs/module-command-overview/spec.md b/openspec/specs/module-command-overview/spec.md new file mode 100644 index 00000000..274f6e70 --- /dev/null +++ b/openspec/specs/module-command-overview/spec.md @@ -0,0 +1,30 @@ +# module-command-overview Specification + +## Purpose +TBD - created by archiving change tester-module-cli-reliability. Update Purpose after archive. +## Requirements +### Requirement: Modules Publish Generated Command Overview Artifacts + +The modules repository SHALL generate deterministic command overview artifacts from the actual module command tree. + +#### Scenario: Module command overview artifacts are generated + +- **GIVEN** the module command overview generator runs in the modules repository +- **WHEN** it writes artifacts +- **THEN** it produces `llms.txt`, `docs/reference/commands.generated.md`, and `docs/reference/commands.generated.json` +- **AND** every command record includes command path, owning repo, owning module package, install prerequisite, short help, arguments/options, subcommands, source import path when known, and hidden/deprecated status +- **AND** generated output is stable for the same source tree. + +#### Scenario: README links generated overview + +- **GIVEN** a user or AI agent opens the modules repository README +- **WHEN** they look for command usage +- **THEN** the README links to the generated module command overview artifact. + +#### Scenario: Stale generated artifacts fail checks + +- **GIVEN** module command source, module manifests, prompt resources, docs, or command validation scripts change +- **WHEN** the command overview freshness check runs +- **THEN** it fails if generated artifacts are stale +- **AND** it reports the command needed to regenerate them. + diff --git a/openspec/specs/modules-docs-command-validation/spec.md b/openspec/specs/modules-docs-command-validation/spec.md index 33397833..71c10d4b 100644 --- a/openspec/specs/modules-docs-command-validation/spec.md +++ b/openspec/specs/modules-docs-command-validation/spec.md @@ -66,3 +66,92 @@ The docs validation script SHALL verify that every URL in `_data/nav.yml` corres - **THEN** every URL in the nav file matches an existing page's permalink - **AND** the check passes +### Requirement: Module docs command examples are validated + +Module documentation command examples SHALL be validated against the generated module command overview. + +#### Scenario: Legacy flat sync command fails validation + +- **GIVEN** module docs, help examples, prompts, Jinja2 templates, YAML/JSON resources, or text guidance contain `specfact sync bridge` +- **WHEN** docs command validation runs +- **THEN** validation fails unless the reference is explicitly marked as historical migration material +- **AND** the finding identifies `specfact project sync bridge` as the canonical command when appropriate. + +#### Scenario: Prompt validators do not whitelist removed flat mounts + +- **GIVEN** a validator scans module prompt resources +- **WHEN** it builds the command contract +- **THEN** it uses generated module command overview data +- **AND** it does not accept removed flat mounts such as `specfact import`, `specfact sync`, `specfact plan`, or `specfact migrate` as canonical command groups. + +#### Scenario: Invalid option ordering fails validation + +- **GIVEN** docs or prompts contain `specfact code import --repo .` +- **WHEN** validation runs +- **THEN** the validator rejects the example if the command contract does not support that order +- **AND** the finding includes the canonical supported command form. + +### Requirement: Docs validation SHALL validate published-route body links + +The modules docs validation command SHALL validate internal links in authored page bodies using the page's published permalink route as the URL base, and SHALL fail when a link resolves to a route that is not backed by a published page or an accepted redirect route. + +#### Scenario: Overview relative link fails under published route semantics + +- **WHEN** a page with permalink `/bundles/code-review/overview/` contains a body link `run/` +- **THEN** docs validation resolves the link as `/bundles/code-review/overview/run/` +- **AND** docs validation reports a `published-link` finding when that route is not published or redirected +- **AND** the validation command exits non-zero + +#### Scenario: Published-route-safe link passes + +- **WHEN** a page with permalink `/bundles/code-review/overview/` links to `/bundles/code-review/run/` +- **THEN** docs validation resolves the link to the published Code Review run page +- **AND** no `published-link` finding is emitted for that link + +### Requirement: Docs validation SHALL reject incomplete published page front matter + +The modules docs validation command SHALL reject published Markdown pages whose front matter is missing required route and display metadata, including `layout`, `title`, and `permalink`, unless the page has an explicit documented exemption recognized by the validator. + +#### Scenario: Redirect page missing title fails + +- **WHEN** a published Markdown redirect page has `layout` and `permalink` but no `title` +- **THEN** docs validation reports a `frontmatter` finding for the missing `title` +- **AND** the validation command exits non-zero + +#### Scenario: Complete published page passes front matter validation + +- **WHEN** a published Markdown page defines `layout`, `title`, and `permalink` +- **THEN** docs validation accepts the page front matter +- **AND** no `frontmatter` finding is emitted for that page + +### Requirement: Docs validation SHALL expose stable finding categories + +The modules docs validation command SHALL emit stable category names for each class of documentation defect so CI logs, pre-commit output, and tests can assert category coverage without matching brittle prose. + +#### Scenario: Multiple docs defect categories are reported together + +- **WHEN** docs validation finds an unknown command example, a broken published route link, and incomplete front matter +- **THEN** the output includes `command`, `published-link`, and `frontmatter` categories +- **AND** the validation command exits non-zero after reporting all discovered docs findings + +### Requirement: Docs validation SHALL detect docs build dependency drift + +The modules docs validation workflow SHALL include a docs build dependency health check that fails when the checked-in Jekyll dependency lock cannot be installed for the docs site. + +#### Scenario: Stale Gemfile lock fails docs dependency validation + +- **WHEN** the docs dependency install command cannot resolve a locked gem version from the configured sources +- **THEN** the docs workflow reports a `docs-build-dependency` failure +- **AND** Pages publication does not proceed as healthy + +### Requirement: Bundle permalink pages SHALL validate parent-segment links against browser routes + +For pages whose canonical published route is under `/bundles/`, docs validation SHALL treat Markdown links whose path contains parent-directory segments (`..`) as unsafe unless the filesystem-resolved target file matches the target resolved from the page permalink using browser URL rules. + +#### Scenario: Deep bundle overview rejects filesystem-only match for `../../` links + +- **WHEN** a bundle overview page is published under `/bundles//overview/` (or another deep `/bundles/` permalink) +- **AND** its body uses a `../` or `../../` link that reaches a markdown file on disk but resolves to a different or missing public route +- **THEN** docs validation reports a `published-link` finding (missing route or route mismatch) +- **AND** the validation command exits non-zero + diff --git a/openspec/specs/modules-docs-publishing/spec.md b/openspec/specs/modules-docs-publishing/spec.md index 808c1d3d..5bb7d737 100644 --- a/openspec/specs/modules-docs-publishing/spec.md +++ b/openspec/specs/modules-docs-publishing/spec.md @@ -49,3 +49,29 @@ The modules documentation site SHALL maintain a published reference page that ex - **WHEN** a guide is moved under `bundles/`, `integrations/`, or `authoring/` with a new canonical `permalink` - **THEN** the page includes `jekyll-redirect-from` entries for the previous modules URL (as required by the IA restructure change) +### Requirement: Docs publishing SHALL validate generated-site readiness before deploy + +The docs publishing workflow SHALL run docs dependency installation, Jekyll build, and generated-site validation before uploading or deploying the Pages artifact. + +#### Scenario: Dependency install failure blocks Pages artifact + +- **WHEN** `bundle install` fails for the docs site +- **THEN** the docs publishing workflow fails before `jekyll build` +- **AND** no Pages artifact is uploaded from that run + +#### Scenario: Generated site contains broken internal link + +- **WHEN** the generated `_site` HTML contains an internal `modules.specfact.io` link whose route is not present in the generated site or redirect set +- **THEN** generated-site validation reports the broken route +- **AND** the docs publishing workflow fails before deployment + +### Requirement: Docs review CI SHALL run the same deterministic docs validators as local checks + +The docs review workflow SHALL run the deterministic docs validators used by local pre-commit, plus the docs unit tests, so PR and local validation enforce the same defect categories. + +#### Scenario: Docs-only pull request has broken published link + +- **WHEN** a pull request changes only Markdown files under `docs/` +- **THEN** the docs review workflow runs published-route link validation +- **AND** the workflow fails when the changed docs introduce a broken published-route link + diff --git a/openspec/specs/modules-pre-commit-quality-parity/spec.md b/openspec/specs/modules-pre-commit-quality-parity/spec.md index 7c61762d..fbbd12b5 100644 --- a/openspec/specs/modules-pre-commit-quality-parity/spec.md +++ b/openspec/specs/modules-pre-commit-quality-parity/spec.md @@ -25,3 +25,29 @@ The modules repo pre-commit configuration SHALL run a consolidated local quality - **AND** that helper script performs formatter safety checks - **AND** it invokes the relevant modules repo validation commands for yaml, import boundaries, and fast test coverage. +### Requirement: Docs-only pre-commit changes SHALL run docs validation before safe bypass + +The modules repo pre-commit helper SHALL run deterministic docs validation for staged docs-only changes before skipping code-specific review and contract-test stages. + +#### Scenario: Docs-only commit with broken link fails pre-commit + +- **WHEN** only docs files are staged and one staged docs page introduces a broken published-route link +- **THEN** pre-commit runs docs validation +- **AND** pre-commit fails before reporting the change as safe + +#### Scenario: Docs-only commit with valid docs skips code-specific checks + +- **WHEN** only docs files are staged and docs validation passes +- **THEN** pre-commit may skip code review and contract-test stages +- **AND** pre-commit reports that docs validation passed before applying the safe-change bypass + +### Requirement: Pre-commit and CI docs gates SHALL share validation categories + +The local pre-commit docs gate and CI docs review workflow SHALL report the same docs validation categories for matching defects. + +#### Scenario: Same broken docs route reports same category locally and in CI + +- **WHEN** a docs change introduces a broken generated public route +- **THEN** local pre-commit reports a `published-link` finding +- **AND** the docs review CI workflow reports a `published-link` finding for the same defect category + diff --git a/openspec/specs/project-command-surface/spec.md b/openspec/specs/project-command-surface/spec.md new file mode 100644 index 00000000..80d61733 --- /dev/null +++ b/openspec/specs/project-command-surface/spec.md @@ -0,0 +1,13 @@ +# project-command-surface Specification + +## Purpose +TBD - created by archiving change project-02-plan-root-command-fix. Update Purpose after archive. +## Requirements +### Requirement: Project bundle exposes plan command group +The `nold-ai/specfact-project` bundle SHALL declare both `project` and `plan` in its manifest command list so installed bundle routing can delegate `specfact plan ...` calls. + +#### Scenario: Manifest includes plan command group +- **WHEN** a consumer inspects `packages/specfact-project/module-package.yaml` +- **THEN** the `commands` list contains `plan` +- **AND** docs for module command categories and marketplace bundle summary mention plan as part of the project bundle surface. + diff --git a/openspec/specs/prompt-command-validation/spec.md b/openspec/specs/prompt-command-validation/spec.md new file mode 100644 index 00000000..f2fd806d --- /dev/null +++ b/openspec/specs/prompt-command-validation/spec.md @@ -0,0 +1,71 @@ +# prompt-command-validation Specification + +## Purpose +TBD - created by archiving change prompt-command-contract-validation. Update Purpose after archive. +## Requirements +### Requirement: Bundle prompt command references SHALL match mounted CLI contracts + +The modules repository SHALL validate command paths and option names embedded in bundle-owned prompt resources against the mounted SpecFact CLI command tree discoverable from the current checkout. + +#### Scenario: Valid prompt command example passes + +- **GIVEN** a bundle prompt references an implemented command such as `specfact code repro --repo .` +- **WHEN** prompt command validation runs +- **THEN** the command path resolves through the mounted CLI command tree +- **AND** referenced options are accepted by that command or by an ancestor command context + +#### Scenario: Invalid prompt command path fails + +- **GIVEN** a bundle prompt references a stale command such as `specfact repro --repo .` +- **WHEN** prompt command validation runs +- **THEN** the validator reports the prompt path and line number +- **AND** the validation command exits non-zero + +#### Scenario: Invalid prompt option fails + +- **GIVEN** a bundle prompt references an option that is not accepted by the resolved command path +- **WHEN** prompt command validation runs +- **THEN** the validator reports the stale option, prompt path, and line number +- **AND** the validation command exits non-zero + +### Requirement: Prompt guidance SHALL self-check CLI reality + +Bundle-owned prompts SHALL tell AI IDE assistants that prompt text is operational guidance and that current CLI help or validation output is authoritative when prompt instructions disagree with the installed CLI. + +#### Scenario: Prompt contains CLI reality check guidance + +- **GIVEN** a shipped bundle prompt contains executable SpecFact command guidance +- **WHEN** prompt command validation inspects that prompt +- **THEN** the prompt includes a CLI reality-check instruction +- **AND** the prompt tells the assistant to prefer current CLI help over stale prompt prose + +#### Scenario: Broken prompt instruction gives self-healing behavior + +- **GIVEN** an assistant using a prompt finds that a referenced command or option is unavailable +- **WHEN** the prompt includes self-healing guidance +- **THEN** the assistant is instructed to inspect the nearest valid `--help` output +- **AND** continue only with a corrected command or ask the user when no safe correction is clear + +### Requirement: Prompt validation SHALL run in local and CI gates + +Prompt command validation SHALL be available as a Hatch command and SHALL run automatically in local pre-commit and Markdown/resource-triggered CI when bundle prompt resources or validation tooling change. + +#### Scenario: Hatch command exposes prompt validation + +- **WHEN** a contributor runs `hatch run validate-prompt-commands` +- **THEN** the bundle prompt validation script runs +- **AND** exits non-zero on any blocking prompt command finding + +#### Scenario: Pre-commit validates staged prompt edits before safe-change skipping + +- **GIVEN** a staged edit changes `packages/specfact-project/resources/prompts/specfact.02-plan.md` +- **WHEN** `scripts/pre-commit-quality-checks.sh block2` runs +- **THEN** prompt command validation runs before the script decides whether Block 2 can be skipped as a safe change + +#### Scenario: CI validates prompt edits + +- **GIVEN** a pull request changes a bundle prompt Markdown file +- **WHEN** the docs review workflow runs +- **THEN** prompt command validation runs with logs +- **AND** stale command references fail the workflow + diff --git a/openspec/specs/resource-aware-integrity/spec.md b/openspec/specs/resource-aware-integrity/spec.md index e834cd9c..dc8c3733 100644 --- a/openspec/specs/resource-aware-integrity/spec.md +++ b/openspec/specs/resource-aware-integrity/spec.md @@ -4,16 +4,25 @@ TBD - created by archiving change packaging-01-bundle-resource-payloads. Update Purpose after archive. ## Requirements ### Requirement: Bundle integrity SHALL cover resource payloads -Bundle signing, verification, and publish validation SHALL treat bundled resource files as part of the signed module payload so that resource-only changes are detected as bundle changes. + +Bundle signing, verification, and publish validation SHALL treat bundled resource files as part of the signed module payload so that resource-only changes are detected as bundle changes. Prompt resource edits SHALL also be covered by prompt command validation before release. #### Scenario: Resource edit changes signed payload + - **WHEN** a prompt template or other bundled resource file changes inside a bundle package - **THEN** integrity verification detects a payload change until the manifest version and signature are refreshed #### Scenario: Resource-only change triggers version-bump enforcement + - **WHEN** a bundled resource file changes but the bundle manifest version is not incremented - **THEN** the modules-repo version-bump enforcement reports that the bundle payload changed without a version bump +#### Scenario: Prompt resource edit triggers command-contract validation + +- **WHEN** a bundled prompt resource changes +- **THEN** the local and CI validation gates run prompt command validation +- **AND** stale command paths or options are reported before the changed resource can ship + ### Requirement: Bundle resource layout SHALL be discoverable by core CLI Bundled resources SHALL live at stable paths inside the bundle package so that the core CLI can resolve them from an installed bundle root without hardcoded core-repo fallbacks. diff --git a/openspec/specs/review-finding-model/spec.md b/openspec/specs/review-finding-model/spec.md index 5b04e995..7d4542eb 100644 --- a/openspec/specs/review-finding-model/spec.md +++ b/openspec/specs/review-finding-model/spec.md @@ -1,12 +1,22 @@ # Review Finding Model Specification -## Overview +## Purpose The `ReviewFinding` model represents structured code-review findings emitted by the `specfact-code-review` bundle. This specification defines the canonical schema, category enumeration, and tool mapping for all review runners. +## Requirements +### Requirement: ReviewFinding schema defines governed code-review findings -## Schema Definition +The ReviewFinding model SHALL define core fields, governed categories, tool origins, validation rules, and backward compatibility for structured code-review findings. -### Core Fields +#### Scenario: Valid finding payload preserves governed fields + +- **WHEN** a review runner emits a finding payload +- **THEN** the payload includes the required governed fields +- **AND** category, severity, tool, rule, file, line, and message values satisfy the validation rules. + +#### Schema Definition + +#### Core Fields | Field | Type | Description | Required | Constraints | |-------|------|-------------|----------|-------------| @@ -19,7 +29,7 @@ The `ReviewFinding` model represents structured code-review findings emitted by | `message` | string | User-facing finding message | Yes | Non-empty string | | `fixable` | boolean | Whether finding can be auto-fixed | No | Default: false | -### Category Enumeration +##### Category Enumeration The following categories are supported: @@ -37,7 +47,7 @@ The following categories are supported: - `dry`: DRY principle violations (Don't Repeat Yourself) - `solid`: SOLID principle violations -### Tool Enumeration +##### Tool Enumeration The following tools are officially supported: @@ -52,38 +62,38 @@ The following tools are officially supported: - `checklist`: PR checklist validator - `ast`: AST-based clean-code analyzer -## Category-Tool Mapping +#### Category-Tool Mapping -### Clean Code Tools +#### Clean Code Tools - `radon`: Emits `clean_code` findings for cyclomatic complexity - `radon-kiss`: Emits `kiss` findings for LOC, nesting, and parameter counts - `ast`: Emits `naming`, `kiss`, `yagni`, `dry`, `solid` findings from AST analysis -### Style Tools +#### Style Tools - `ruff`: Emits `style` findings for formatting and conventions -### Type Safety Tools +#### Type Safety Tools - `basedpyright`: Emits `type_safety` findings for type violations -### Architecture Tools +#### Architecture Tools - `pylint`: Emits `architecture` findings for design issues -### Testing Tools +#### Testing Tools - `pytest`: Emits `testing` findings for test failures and coverage - `contract_runner`: Emits `contracts` findings for contract violations -### Checklist Tools +#### Checklist Tools - `checklist`: Emits `clean_code` findings for PR checklist items -## Examples +#### Examples -### KISS Violation +#### KISS Violation ```json { @@ -98,7 +108,7 @@ The following tools are officially supported: } ``` -### Naming Violation +#### Naming Violation ```json { @@ -113,7 +123,7 @@ The following tools are officially supported: } ``` -### SOLID Violation +#### SOLID Violation ```json { @@ -128,7 +138,7 @@ The following tools are officially supported: } ``` -## Validation Rules +#### Validation Rules 1. All string fields must be non-empty after stripping whitespace 2. The `line` field must be a positive integer (≥ 1) @@ -136,6 +146,31 @@ The following tools are officially supported: 4. The `severity` field must be one of: "error", "warning", "info" 5. Tool names should match the official tool enumeration where possible -## Backward Compatibility +#### Backward Compatibility + +This specification is backward compatible with existing `ReviewFinding` consumers. New categories (`naming`, `kiss`, `yagni`, `dry`, `solid`) and tools (`ast`, `checklist`) extend rather than replace the existing schema. + +### Requirement: ReviewFinding schema supports additive simplification metadata + +The `ReviewFinding` model SHALL accept optional simplification metadata while preserving the existing governed finding fields and category/severity validation. The report schema version SHALL advance additively when simplification metadata, guided simplification metadata, cleanup forecast metadata, or AI IDE handoff metadata is emitted. + +#### Scenario: Finding carries signal trace evidence + +- **WHEN** a `ReviewFinding` payload includes `signal_trace` +- **THEN** model validation SHALL accept deterministic signal entries with tool/source name, fired status, optional score/value, evidence references, and explanation +- **AND** legacy finding payloads without `signal_trace` SHALL remain valid + +#### Scenario: Finding carries preserve reasons + +- **WHEN** a `ReviewFinding` payload includes `preserve_reasons` +- **THEN** each reason SHALL come from a closed taxonomy of preserve contexts +- **AND** the finding SHALL NOT be considered safe for automatic cleanup while a preserve reason is present +- **AND** the preserve reason SHALL include enough evidence for a developer or AI agent to explain why cleanup was not applied + +#### Scenario: Finding carries remediation packet + +- **WHEN** a simplify-focused finding includes `remediation_packet` +- **THEN** the packet SHALL include a plain-language issue, recommended action, possible keep reason, safety checks, validation plan, and safe-to-autofix flag +- **AND** the packet MAY include patch forecast references when preview evidence exists +- **AND** AI IDE prompts and skills SHALL treat the JSON packet as authoritative over prompt prose -This specification is backward compatible with existing `ReviewFinding` consumers. New categories (`naming`, `kiss`, `yagni`, `dry`, `solid`) and tools (`ast`, `checklist`) extend rather than replace the existing schema. \ No newline at end of file diff --git a/openspec/specs/review-run-command/spec.md b/openspec/specs/review-run-command/spec.md index 09dc3a88..ac6ebedd 100644 --- a/openspec/specs/review-run-command/spec.md +++ b/openspec/specs/review-run-command/spec.md @@ -5,55 +5,28 @@ TBD - created by archiving change code-review-08-review-run-integration. Update ## Requirements ### Requirement: End-to-End `specfact code review run` in modules repo -The `specfact-code-review` bundle SHALL provide a fully wired -`specfact code review run` command that orchestrates the existing tool runners -and emits a governed `ReviewReport` with correct exit codes. - -#### Scenario: Representative modules-repo source can be reviewed without command failure -- **GIVEN** a real Python source file from this repository -- **WHEN** `specfact code review run --json ` is executed in the modules repo -- **THEN** the command writes a `ReviewReport` JSON file -- **AND** the command does not fail because of command wiring, path handling, or tool invocation bugs in the bundle - -#### Scenario: JSON output uses file-based routing -- **GIVEN** `specfact code review run --json` -- **WHEN** the command executes successfully -- **THEN** it writes the governed `ReviewReport` JSON payload to a file path -- **AND** `--out` overrides the default JSON output path - -#### Scenario: Interactive runs ask whether to include test files -- **GIVEN** `specfact code review run` executes in interactive mode -- **WHEN** test-file inclusion has not been specified explicitly -- **THEN** the CLI asks whether test files should be included in the review scope -- **AND** the answer controls whether changed files under `tests/` are reviewed - -#### Scenario: Auto-detected review scope includes untracked Python files -- **GIVEN** Python files exist in the workspace that are not yet tracked by Git -- **WHEN** `specfact code review run` auto-detects review scope -- **THEN** those untracked Python files are included in review scope -- **AND** test-file inclusion rules still apply to untracked files under `tests/` - -#### Scenario: Known low-signal findings are suppressible by default -- **GIVEN** a review run includes test files or other paths that can emit - known low-signal findings -- **WHEN** noise suppression is enabled -- **THEN** the report omits those known low-signal findings -- **AND** a command option allows users to include the suppressed findings for a - strict/full review - -#### Scenario: Bundled skill instructs whether to include tests -- **GIVEN** the bundled `specfact-code-review` skill is installed -- **WHEN** it guides a review workflow -- **THEN** it instructs the reviewer to decide whether tests should be included - before running the review - -#### Scenario: Long-running review runs surface progress -- **GIVEN** a review run executes multiple tool steps that can take noticeable - time -- **WHEN** the command is running -- **THEN** the CLI shows which review step is currently executing -- **AND** progress feedback does not replace the primary stdout contract such as - the final JSON output path +The `specfact-code-review` bundle SHALL provide a fully wired `specfact code review run` command that orchestrates the existing tool runners, supports scoped file selection, emits governed review reports, and provides simplify-specific cleanup forecast and handoff controls. + +#### Scenario: Run command previews simplify fixes without mutating files + +- **WHEN** `specfact code review run --focus simplify --preview-fixes --json --out ` is executed +- **THEN** the command SHALL compute preview evidence for supported safe-mechanical simplification fixers +- **AND** it SHALL write the forecast evidence to the JSON report +- **AND** it SHALL NOT edit tracked source files + +#### Scenario: Run command rejects preview and fix together + +- **WHEN** `specfact code review run --focus simplify --preview-fixes --fix` is executed +- **THEN** the command SHALL fail before review execution with a clear invalid-combination error + +#### Scenario: Run command scopes mutation proof to simplify focus + +- **WHEN** `specfact code review run --with-mutation` is executed without `--focus simplify` +- **THEN** the command SHALL fail before review execution with a clear invalid-combination error + +- **WHEN** `specfact code review run --focus simplify --with-mutation` is executed +- **THEN** the command SHALL run mutation proof only for candidate cleanup findings +- **AND** it SHALL record mutation outcomes in the report without making mutation proof part of the default review path ### Requirement: Developer runtime validation helper for local modules @@ -186,3 +159,53 @@ The command SHALL accept `--level error` or `--level warning` to filter findings - **WHEN** `specfact code review run --json` runs without `--level` - **THEN** all severities appear in output as they do today +### Requirement: Code Review run docs SHALL cover the public option surface + +The Code Review run documentation SHALL describe every supported public `specfact code review run` option that affects targeting, output, exit behavior, analysis depth, or filtering. + +#### Scenario: Newly added review options are documented + +- **WHEN** the `specfact code review run` Typer command exposes `--bug-hunt`, `--mode`, `--focus`, and `--level` +- **THEN** the Code Review run guide documents those options in its key option table or equivalent option section +- **AND** docs validation fails if any of those public options are missing from the run guide + +#### Scenario: Invalid option combinations are documented + +- **WHEN** the command rejects combinations such as positional files with `--scope` or `--path`, or `--focus` with `--include-tests` +- **THEN** the Code Review docs describe the invalid combination behavior +- **AND** the docs include a user-facing alternative for the supported targeting style aligned with the public **`run`** signature (**`files: list[Path]`**): pass explicit **positional files** (file paths) for a fixed review set, or use **`--scope`** / **`--path`** (without positional files) to auto-discover targets from the repo + +### Requirement: Code Review docs SHALL stay aligned with review behavior + +The Code Review docs SHALL describe current review run behavior for JSON output, shadow/enforce mode, progress output, focus filtering, severity filtering, bug-hunt budgets, and test inclusion semantics. + +#### Scenario: Docs parity check detects missing behavior section + +- **WHEN** the command implementation includes a public behavior that affects output, exit code, target selection, or analysis cost +- **THEN** docs parity validation checks that the behavior is represented in the Code Review run docs +- **AND** the validation fails when the behavior is absent from the docs + +### Requirement: Review run supports simplify focus + +The `specfact code review run` command SHALL accept `--focus simplify` as a targeted review focus for simplification feedback. The focus SHALL retain findings that belong in the simplification queue and SHALL classify them with actionable guidance. + +#### Scenario: Simplify focus emits guided simplification queue + +- **WHEN** `specfact code review run --focus simplify --json --out .specfact/code-review.json` completes +- **THEN** the JSON report SHALL retain simplification-focused findings +- **AND** retained findings SHALL include guidance metadata for actionability, preservation, or design judgment +- **AND** the report SHALL include a simplification summary when guided findings are present + +#### Scenario: Simplify enforce blocks only safe mechanical debt + +- **WHEN** `specfact code review run --focus simplify --mode enforce` runs +- **THEN** the process SHALL fail only when unresolved findings with `guidance_kind="safe_mechanical"` remain +- **AND** findings classified as `needs_tests`, `design_judgment`, or `preserve` SHALL NOT make the run fail + +#### Scenario: Simplify fix applies only safe mechanical rewrites + +- **WHEN** `specfact code review run --focus simplify --fix` runs +- **THEN** automatic rewrites SHALL be limited to deterministic safe-mechanical findings +- **AND** the command SHALL rerun review after applying rewrites +- **AND** the JSON report SHALL record applied, failed, and still-recommended outcomes + diff --git a/openspec/specs/runtime-artifact-write-safety/spec.md b/openspec/specs/runtime-artifact-write-safety/spec.md new file mode 100644 index 00000000..f1e6b22b --- /dev/null +++ b/openspec/specs/runtime-artifact-write-safety/spec.md @@ -0,0 +1,34 @@ +# runtime-artifact-write-safety Specification + +## Purpose +TBD - created by archiving change project-runtime-01-safe-artifact-write-policy. Update Purpose after archive. +## Requirements +### Requirement: Bundle runtime commands SHALL distinguish sanctioned external artifacts from SpecFact-managed artifacts + +Bundle runtime commands SHALL treat files outside `.specfact` as user-owned by default and SHALL treat files inside `.specfact` as SpecFact-managed unless a command explicitly documents a narrower ownership split. + +#### Scenario: Runtime command targets a sanctioned external user-owned artifact +- **WHEN** a bundle runtime command mutates a sanctioned path outside `.specfact` +- **THEN** it SHALL reuse the paired core safe-write contract +- **AND** SHALL NOT silently overwrite the existing user-owned file + +#### Scenario: Runtime command targets a fully owned SpecFact artifact +- **WHEN** a bundle runtime command updates a fully owned artifact under `.specfact` +- **THEN** it MAY rewrite that artifact deterministically according to the command's managed-state contract +- **AND** it SHALL NOT treat the file as a user-owned external artifact by default + +### Requirement: Partially user-tuned `.specfact` config SHALL preserve unrelated content + +Bundle commands that update partially owned config files under `.specfact` SHALL preserve unrelated user-managed keys or sections during supported updates. + +#### Scenario: Supported config merge preserves unrelated provider settings +- **WHEN** a regression fixture contains an existing `.specfact` config file with additional user-managed settings +- **AND** a bundle command updates only a declared SpecFact-managed subtree +- **THEN** unrelated keys or sections SHALL remain intact +- **AND** only the managed subtree SHALL change + +#### Scenario: Unsupported config shape fails safe +- **WHEN** a bundle command encounters an existing `.specfact` config shape that it cannot reconcile safely +- **THEN** the command SHALL fail with actionable guidance +- **AND** SHALL leave the existing file unchanged by default + From 2533f1380b8b8720c9826b94b57a29da40efa425 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Sun, 7 Jun 2026 00:19:04 +0200 Subject: [PATCH 2/3] fix: address modules roadmap review feedback --- openspec/CHANGE_ORDER.md | 19 +++++++++++-------- .../validation-02-full-chain-engine/tasks.md | 8 +++++--- .../code-review-ai-bloat-detection/spec.md | 13 ++++++++----- .../specs/codebase-import-runtime/spec.md | 8 ++++++-- .../specs/module-cli-error-contract/spec.md | 9 +++++++-- .../specs/project-command-surface/spec.md | 12 ++++++++---- .../runtime-artifact-write-safety/spec.md | 9 +++++++-- 7 files changed, 52 insertions(+), 26 deletions(-) diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index 1472a73d..997e0ea5 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -59,18 +59,18 @@ AI IDE, rerun, and compare improved evidence. | 1 | `policy-02-packs-and-modes` | [#158](https://github.com/nold-ai/specfact-cli-modules/issues/158) | Validation severity, rollout modes, and policy-pack execution | core profile/policy semantics | | 2 | `governance-01-evidence-output` | [#169](https://github.com/nold-ai/specfact-cli-modules/issues/169) | Runtime evidence emitters for JSON/CI/AI handoff | core `governance-01` | | 3 | `governance-02-exception-management` | [#167](https://github.com/nold-ai/specfact-cli-modules/issues/167) | Runtime exception handling and waiver evidence | governance-01, policy-02 | -| 4 | `validation-02-full-chain-engine` | [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) | Validation evidence graph runtime, not lifecycle orchestration | governance-01, traceability-01 | -| 5 | `traceability-01-index-and-orphans` | [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) | Artifact drift and orphan detection runtime | validation input contracts | -| 6 | `sync-01-unified-kernel` | [#157](https://github.com/nold-ai/specfact-cli-modules/issues/157) | Preview/apply safety only where validation adapters need it | project/runtime safety specs | +| 4 | `traceability-01-index-and-orphans` | [#170](https://github.com/nold-ai/specfact-cli-modules/issues/170) | Artifact drift and orphan detection runtime | validation input contracts | +| 5 | `validation-02-full-chain-engine` | [#171](https://github.com/nold-ai/specfact-cli-modules/issues/171) | Validation evidence graph runtime, not lifecycle orchestration | governance-01, traceability-01 | ### Track B - Upstream Context Adapters | Order | Change folder | GitHub # | Positioning | Blocked by | |---:|---|---|---|---| | 1 | `requirements-02-module-commands` | [#165](https://github.com/nold-ai/specfact-cli-modules/issues/165) | Import/normalize requirement context for evidence | core requirements input model | -| 2 | `requirements-03-backlog-sync` | [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) | Read-first backlog drift evidence; no write-back critical path | requirements-02, sync-01 | -| 3 | `architecture-01-solution-layer` | [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) | Architecture-boundary validation input | core architecture-boundary contracts | -| 4 | `openspec-01-intent-trace` | [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) | Optional OpenSpec and Spec Kit evidence import adapter | requirements input contracts | +| 2 | `sync-01-unified-kernel` | [#157](https://github.com/nold-ai/specfact-cli-modules/issues/157) | Preview/apply safety only where validation adapters need it | project/runtime safety specs | +| 3 | `requirements-03-backlog-sync` | [#166](https://github.com/nold-ai/specfact-cli-modules/issues/166) | Read-first backlog drift evidence; no write-back critical path | requirements-02, sync-01 | +| 4 | `architecture-01-solution-layer` | [#164](https://github.com/nold-ai/specfact-cli-modules/issues/164) | Architecture-boundary validation input | core architecture-boundary contracts | +| 5 | `openspec-01-intent-trace` | [#168](https://github.com/nold-ai/specfact-cli-modules/issues/168) | Optional OpenSpec and Spec Kit evidence import adapter | requirements input contracts | | Gated | `architecture-02-module-well-architected` | [#230](https://github.com/nold-ai/specfact-cli-modules/issues/230) | Architecture-boundary review findings | architecture-01 shipped plus one usage cycle | ### Track C - Supporting Docs @@ -113,18 +113,22 @@ ceremony rather than validation evidence: - Park upstream ceremony expansions. - Update active proposals and wiki mirrors to validation positioning. - Recheck GitHub Project metadata with a token that has project-field access. +- Required blocking gate: review all paired public change artifacts in + `nold-ai/specfact-cli` before scoped implementation or shared + workflow-semantic changes proceed. ### Wave 2 - Validation Evidence Runtime - `policy-02-packs-and-modes` - `governance-01-evidence-output` - `governance-02-exception-management` -- `validation-02-full-chain-engine` - `traceability-01-index-and-orphans` +- `validation-02-full-chain-engine` ### Wave 3 - Context Adapters - `requirements-02-module-commands` +- `sync-01-unified-kernel` - `requirements-03-backlog-sync` - `architecture-01-solution-layer` - `openspec-01-intent-trace` @@ -132,7 +136,6 @@ ceremony rather than validation evidence: ### Wave 4 - Gated Extensions - `architecture-02-module-well-architected` -- `sync-01-unified-kernel` only where adapter safety requires it - `docs-14-module-release-history` ## Parent Issues And Epic Framing diff --git a/openspec/changes/validation-02-full-chain-engine/tasks.md b/openspec/changes/validation-02-full-chain-engine/tasks.md index 169b2583..c8ac67d6 100644 --- a/openspec/changes/validation-02-full-chain-engine/tasks.md +++ b/openspec/changes/validation-02-full-chain-engine/tasks.md @@ -2,9 +2,11 @@ ## 1. Branch and dependency guardrails -- [ ] 1.1 Create dedicated worktree branch `feature/validation-02-full-chain-engine` from `dev` before implementation work: `scripts/worktree.sh create feature/validation-02-full-chain-engine`. -- [ ] 1.2 Verify prerequisite changes are implemented or explicitly accepted as parallel work. -- [ ] 1.3 Reconfirm scope against the validation evidence graph positioning and this proposal. +- [ ] 1.1 Recheck GitHub Project metadata using a token with project-field access before scoped implementation starts. +- [ ] 1.2 Review paired `specfact-cli` public-artifact changes before widening shared workflow semantics. +- [ ] 1.3 Create dedicated worktree branch `feature/validation-02-full-chain-engine` from `dev` before implementation work: `scripts/worktree.sh create feature/validation-02-full-chain-engine`. +- [ ] 1.4 Verify prerequisite changes are implemented or explicitly accepted as parallel work. +- [ ] 1.5 Reconfirm scope against the validation evidence graph positioning and this proposal. ## 2. Spec-first and test-first preparation diff --git a/openspec/specs/code-review-ai-bloat-detection/spec.md b/openspec/specs/code-review-ai-bloat-detection/spec.md index 6d15706e..e0d91118 100644 --- a/openspec/specs/code-review-ai-bloat-detection/spec.md +++ b/openspec/specs/code-review-ai-bloat-detection/spec.md @@ -1,7 +1,11 @@ # code-review-ai-bloat-detection Specification ## Purpose -TBD - created by archiving change code-review-ai-bloat-detection. Update Purpose after archive. + +This spec defines the advisory AI-bloat detection contract for SpecFact code +review, including finding categories, policy-pack registration, score-neutral +reporting, and the IDE simplification prompt input model. + ## Requirements ### Requirement: The code-review runner SHALL emit findings under a new `ai_bloat` principle category @@ -76,16 +80,16 @@ The `specfact-code-review` bundle SHALL ship a policy pack at `resources/policy- ### Requirement: An IDE slash-command prompt SHALL drive targeted rewrites -The `specfact-project` bundle SHALL ship a prompt resource at `resources/prompts/specfact.08-simplify.md` that drives an LLM-assisted rewrite workflow in the user's IDE. The prompt SHALL: read `.specfact/code-review.json`, filter findings where `category=ai_bloat`, group by file and then by rule ID, present each candidate with a rewrite hint, drive a per-change accept/reject/skip/explain loop, apply accepted edits via the IDE's edit tool, and suggest re-running the review afterwards. The prompt SHALL NOT edit files autonomously and SHALL NOT skip the per-change confirmation step. +The `specfact-project` bundle SHALL ship a prompt resource at `resources/prompts/specfact.08-simplify.md` that drives an LLM-assisted rewrite workflow in the user's IDE. The prompt SHALL read `.specfact/code-review-simplify.json` as the primary simplify input, filter findings where `category=ai_bloat`, group by file and then by rule ID, present each candidate with a rewrite hint, drive a per-change accept/reject/skip/explain loop, apply accepted edits via the IDE's edit tool, and suggest re-running the review afterward. If `.specfact/code-review-simplify.json` is missing, the prompt MAY fall back to `.specfact/code-review.json` in legacy mode only after normalizing AI-bloat findings into the simplify input model. The prompt SHALL NOT edit files autonomously and SHALL NOT skip the per-change confirmation step. #### Scenario: Slash command runs with no ai_bloat findings present -- **WHEN** the user invokes `/specfact.08-simplify` in an IDE session whose `.specfact/code-review.json` contains no findings with `category=ai_bloat` +- **WHEN** the user invokes `/specfact.08-simplify` in an IDE session whose `.specfact/code-review-simplify.json` contains no findings with `category=ai_bloat` - **THEN** the prompt SHALL report that there are no ai-bloat candidates and exit without modifying any files #### Scenario: Slash command walks the user through findings with confirmation -- **WHEN** the user invokes `/specfact.08-simplify` and the JSON contains one or more `ai_bloat` findings +- **WHEN** the user invokes `/specfact.08-simplify` and the simplify JSON contains one or more `ai_bloat` findings - **THEN** the prompt SHALL present each finding in turn with its source snippet, rule ID, and rewrite hint - **AND** the prompt SHALL ask the user to accept, reject, skip, or request explanation before applying any edit - **AND** the prompt SHALL apply only the edits the user accepts @@ -100,4 +104,3 @@ The clean-code policy-pack documentation SHALL note that `ai-bloat-patterns.yaml - **THEN** the documentation SHALL state explicitly that `ai-bloat-patterns.yaml` is a separate policy pack - **AND** SHALL state that its severity model is `advisory`-only - **AND** SHALL state that its principle category is `ai_bloat`, distinct from the existing principle categories (`naming | kiss | yagni | dry | solid | clean_code | architecture`) - diff --git a/openspec/specs/codebase-import-runtime/spec.md b/openspec/specs/codebase-import-runtime/spec.md index f8c9cf02..5ab55a6a 100644 --- a/openspec/specs/codebase-import-runtime/spec.md +++ b/openspec/specs/codebase-import-runtime/spec.md @@ -1,7 +1,12 @@ # codebase-import-runtime Specification ## Purpose -TBD - created by archiving change codebase-import-runtime-hardening. Update Purpose after archive. + +This spec defines validation-runtime behavior for `specfact code import` so +repository discovery remains deterministic, bounded, and honest about ignored +or heavyweight artifacts. It governs traversal pruning, warning diagnostics, and +safe import inputs for downstream codebase validation. + ## Requirements ### Requirement: Import runtime SHALL prune hidden and heavyweight trees before discovery @@ -56,4 +61,3 @@ Long-running import phases SHALL derive percentage and remaining-time feedback f - **WHEN** the command has discovered part of the repository and has processed a subset of that discovered work - **THEN** the remaining-time display SHALL be derived from processed-versus-discovered work at the current runtime rate - **AND** any early estimate before full discovery SHALL be labeled as provisional rather than a fixed promise - diff --git a/openspec/specs/module-cli-error-contract/spec.md b/openspec/specs/module-cli-error-contract/spec.md index bfe0c801..066e22a4 100644 --- a/openspec/specs/module-cli-error-contract/spec.md +++ b/openspec/specs/module-cli-error-contract/spec.md @@ -1,7 +1,13 @@ # module-cli-error-contract Specification ## Purpose -TBD - created by archiving change tester-module-cli-reliability. Update Purpose after archive. + +This spec defines the shared CLI error contract for module commands that was +proven by the archived tester-module-cli-reliability work. It is the +self-contained contract for module implementers, docs authors, and test suites +covering missing subcommands, missing inputs, legacy invocation boundaries, and +typed diagnostics so module CLIs stay actionable and consistent. + ## Requirements ### Requirement: Module Commands Follow Shared CLI Error Contract @@ -38,4 +44,3 @@ Module command groups and leaf commands SHALL render actionable help for missing - **WHEN** `specfact project regenerate` runs - **THEN** the command reports a typed validation or bundle-data diagnostic - **AND** it does not crash with a raw `NoneType` attribute error. - diff --git a/openspec/specs/project-command-surface/spec.md b/openspec/specs/project-command-surface/spec.md index 80d61733..96968d3a 100644 --- a/openspec/specs/project-command-surface/spec.md +++ b/openspec/specs/project-command-surface/spec.md @@ -1,13 +1,17 @@ # project-command-surface Specification ## Purpose -TBD - created by archiving change project-02-plan-root-command-fix. Update Purpose after archive. + +This spec defines the installed command surface for the `specfact-project` +bundle, including the root `project` group and delegated `plan` commands. It +keeps manifest declarations, docs, and marketplace summaries aligned so routing +tests can prove both command groups remain available. + ## Requirements ### Requirement: Project bundle exposes plan command group The `nold-ai/specfact-project` bundle SHALL declare both `project` and `plan` in its manifest command list so installed bundle routing can delegate `specfact plan ...` calls. #### Scenario: Manifest includes plan command group - **WHEN** a consumer inspects `packages/specfact-project/module-package.yaml` -- **THEN** the `commands` list contains `plan` -- **AND** docs for module command categories and marketplace bundle summary mention plan as part of the project bundle surface. - +- **THEN** the `commands` list contains both `project` and `plan` +- **AND** docs for module command categories and marketplace bundle summary mention both command groups as part of the project bundle surface. diff --git a/openspec/specs/runtime-artifact-write-safety/spec.md b/openspec/specs/runtime-artifact-write-safety/spec.md index f1e6b22b..3ae0cb54 100644 --- a/openspec/specs/runtime-artifact-write-safety/spec.md +++ b/openspec/specs/runtime-artifact-write-safety/spec.md @@ -1,7 +1,13 @@ # runtime-artifact-write-safety Specification ## Purpose -TBD - created by archiving change project-runtime-01-safe-artifact-write-policy. Update Purpose after archive. + +This spec defines safe runtime artifact writes for bundle commands, preserving +user-owned files while allowing deterministic updates to SpecFact-managed +artifacts. It carries the archived project-runtime safe-artifact-write policy +into a baseline contract that implementers must use for ownership decisions, +merge behavior, recovery expectations, and fail-safe outcomes. + ## Requirements ### Requirement: Bundle runtime commands SHALL distinguish sanctioned external artifacts from SpecFact-managed artifacts @@ -31,4 +37,3 @@ Bundle commands that update partially owned config files under `.specfact` SHALL - **WHEN** a bundle command encounters an existing `.specfact` config shape that it cannot reconcile safely - **THEN** the command SHALL fail with actionable guidance - **AND** SHALL leave the existing file unchanged by default - From a624b133345640f13b6b19c9f3a320d210d44eb8 Mon Sep 17 00:00:00 2001 From: Dominikus Nold Date: Sun, 7 Jun 2026 01:22:14 +0200 Subject: [PATCH 3/3] fix: address PR 316 review feedback --- .../specs/ai-ide-remediation-handoff/spec.md | 6 +- openspec/specs/backlog-sync/spec.md | 8 ++- .../specs/bundle-packaged-resources/spec.md | 36 +++++++++++- openspec/specs/ci-integration/spec.md | 9 ++- .../ci-module-signing-on-approval/spec.md | 13 ++++- .../code-review-ai-bloat-detection/spec.md | 4 +- .../spec.md | 7 ++- .../guided-simplification-review/spec.md | 8 ++- .../specs/module-command-overview/spec.md | 6 +- .../specs/modules-docs-publishing/spec.md | 10 ++-- .../specs/prompt-command-validation/spec.md | 6 +- openspec/specs/review-finding-model/spec.md | 57 ++++++++++++++++++- openspec/specs/review-run-command/spec.md | 56 +++++++++++++++++- 13 files changed, 193 insertions(+), 33 deletions(-) diff --git a/openspec/specs/ai-ide-remediation-handoff/spec.md b/openspec/specs/ai-ide-remediation-handoff/spec.md index 14c103a7..d60d1e43 100644 --- a/openspec/specs/ai-ide-remediation-handoff/spec.md +++ b/openspec/specs/ai-ide-remediation-handoff/spec.md @@ -1,7 +1,10 @@ # ai-ide-remediation-handoff Specification ## Purpose -TBD - created by archiving change code-review-13-cleanup-forecast-agent-handoff. Update Purpose after archive. +This specification defines the portable remediation-packet contract that lets +AI IDEs consume SpecFact review evidence, prioritize cleanup work, and rerun +validation without relying on vendor-specific prompt prose. + ## Requirements ### Requirement: Review JSON is the portable AI IDE handoff contract @@ -20,4 +23,3 @@ The Code Review bundle SHALL expose cleanup guidance through machine-readable JS - **THEN** the instructions SHALL tell assistants to generate simplify evidence first - **AND** they SHALL tell assistants to sort findings by `guidance_kind`, inspect `cleanup_forecast`, and follow remediation packets before editing - **AND** they SHALL prohibit treating `ai_bloat` findings as proof of AI authorship - diff --git a/openspec/specs/backlog-sync/spec.md b/openspec/specs/backlog-sync/spec.md index f7139962..ee3edb61 100644 --- a/openspec/specs/backlog-sync/spec.md +++ b/openspec/specs/backlog-sync/spec.md @@ -2,7 +2,10 @@ ## Purpose -TBD - created by archiving change backlog-02-migrate-core-commands. Update Purpose after archive. +This specification defines the modules-owned backlog synchronization contract, +including issue/task sync behavior, external artifact ownership boundaries, and +managed `.specfact` state updates. + ## Requirements ### Requirement: Restore backlog sync command functionality @@ -65,7 +68,7 @@ Any `specfact backlog sync` local artifact path SHALL distinguish between fully #### Scenario: Default managed baseline state updates deterministically - **WHEN** backlog sync updates its default baseline state under `.specfact` -- **THEN** the command MAY rewrite that managed artifact deterministically +- **THEN** the command SHALL rewrite that managed artifact deterministically when its computed baseline content changes - **AND** SHALL treat it as SpecFact-managed state rather than a user-owned external file #### Scenario: Explicit external baseline target is not silently overwritten @@ -74,4 +77,3 @@ Any `specfact backlog sync` local artifact path SHALL distinguish between fully - **AND** the target file already exists - **THEN** the command SHALL fail safe, merge safely, or require explicit replacement according to the declared ownership mode - **AND** SHALL NOT silently overwrite the existing user-owned file - diff --git a/openspec/specs/bundle-packaged-resources/spec.md b/openspec/specs/bundle-packaged-resources/spec.md index 089aadfc..31c43563 100644 --- a/openspec/specs/bundle-packaged-resources/spec.md +++ b/openspec/specs/bundle-packaged-resources/spec.md @@ -1,12 +1,45 @@ # bundle-packaged-resources Specification ## Purpose -TBD - created by archiving change packaging-01-bundle-resource-payloads. Update Purpose after archive. +This specification governs which non-code resources official SpecFact bundles +must package as module-owned payloads, so installed and editable bundles do not +depend on the core CLI repository as a hidden source of truth. + ## Requirements ### Requirement: Official bundles SHALL ship module-owned resource payloads Each official bundle package SHALL include the prompt templates and other non-code resources that are owned by that bundle's workflows or commands. Bundle-owned resources SHALL not depend on fallback storage under the core CLI repository. +#### Scenario: Official bundles ship the audited prompt inventory + +- **WHEN** the audited prompt inventory from `RESOURCE_OWNERSHIP_AUDIT.md` is inspected +- **THEN** each prompt template's canonical packaged source exists under the owning official bundle package +- **AND** the ownership mapping covers the codebase, project, spec, govern, and backlog bundles for the currently supported prompt set + +#### Scenario: Backlog bundle ships the restored slash-prompt inventory + +- **WHEN** the backlog bundle package is inspected from source or from an installed artifact +- **THEN** `resources/prompts/` contains `specfact.backlog-add.md`, `specfact.backlog-daily.md`, `specfact.backlog-refine.md`, and `specfact.sync-backlog.md` +- **AND** those prompt files are treated as canonical bundle-owned sources rather than historical leftovers + +#### Scenario: Prompt companion resources ship with prompt payloads + +- **WHEN** an exported prompt template references a companion file by relative path, such as `./shared/cli-enforcement.md` +- **THEN** the owning bundle package contains that companion resource in a stable relative location +- **AND** prompt export/copy flows can preserve a resolvable relative layout in the target IDE workspace + +#### Scenario: Backlog bundle ships workspace-template seed resources + +- **WHEN** the backlog bundle package is inspected from source or from an installed artifact +- **THEN** the package contains the backlog field mapping templates that `specfact init` or related flows need to copy into workspace state +- **AND** the packaged set includes both ADO and non-ADO seed templates required by supported backlog flows + +#### Scenario: Core no longer remains the source of truth for bundle prompts + +- **WHEN** a workflow prompt belongs to an extracted bundle rather than to core lifecycle commands +- **THEN** that prompt's canonical packaged source exists in the owning bundle package +- **AND** release packaging does not rely on the core CLI repo as the canonical source for that prompt + #### Scenario: Project runtime generators ship required Jinja2 templates - **WHEN** the project bundle is built, installed, or imported from an editable checkout @@ -18,4 +51,3 @@ Each official bundle package SHALL include the prompt templates and other non-co - **WHEN** a required project runtime template such as `protocol.yaml.j2` or `github-action.yml.j2` is absent from the package payload - **THEN** bundle resource validation SHALL fail before release - **AND** the failure message SHALL name the missing template path so the packaging defect can be corrected before publish - diff --git a/openspec/specs/ci-integration/spec.md b/openspec/specs/ci-integration/spec.md index f7c3d812..18ef5a63 100644 --- a/openspec/specs/ci-integration/spec.md +++ b/openspec/specs/ci-integration/spec.md @@ -1,7 +1,10 @@ # ci-integration Specification ## Purpose -TBD - created by archiving change marketplace-06-ci-module-signing. Update Purpose after archive. +This specification governs module-signature behavior in CI, including when PR +workflows repair same-repo package manifests and when verification requires +cryptographic signatures. + ## Requirements ### Requirement: pr-orchestrator skips signature requirement for dev-targeting events @@ -23,9 +26,10 @@ for pull requests or pushes targeting `dev`; it SHALL enforce `--require-signatu - **WHEN** a same-repo pull request targets `dev` or `main` - **AND** a later `pull_request` `synchronize` event adds review-fix commits that change module payloads -- **THEN** the CI signing workflow SHALL re-sign the changed manifests on the PR head branch +- **THEN** `.github/workflows/sign-modules.yml` SHALL re-sign the changed manifests on the PR head branch - **AND** SHALL commit `chore(modules): ci sign changed modules` only when the manifests changed - **AND** the workflow SHALL skip this remediation for its own bot-authored signing commit +- **AND** `.github/workflows/sign-modules-on-approval.yml` SHALL remain limited to trusted approval review events rather than `synchronize` events #### Scenario: Fork PR remains verify-only @@ -70,4 +74,3 @@ The repository pre-commit hook that runs `verify-modules-signature.py` SHALL app - **WHEN** a developer commits on branch `main` - **AND** any `packages/*/module-package.yaml` lacks a valid signature under `--require-signature` - **THEN** the pre-commit signature hook SHALL fail - diff --git a/openspec/specs/ci-module-signing-on-approval/spec.md b/openspec/specs/ci-module-signing-on-approval/spec.md index c0b9129f..86191646 100644 --- a/openspec/specs/ci-module-signing-on-approval/spec.md +++ b/openspec/specs/ci-module-signing-on-approval/spec.md @@ -1,7 +1,10 @@ # ci-module-signing-on-approval Specification ## Purpose -TBD - created by archiving change marketplace-06-ci-module-signing. Update Purpose after archive. +This specification defines the approval-triggered module signing workflow for +same-repo pull requests, including reviewer trust, changed-manifest discovery, +idempotent output, and fork safety. + ## Requirements ### Requirement: Sign packages manifests on PR approval @@ -9,12 +12,17 @@ The system SHALL automatically sign changed `packages/*/module-package.yaml` man secrets when a same-repo pull request targeting `dev` or `main` receives a trusted approval review, and SHALL commit the signed manifests back to the PR branch. +A trusted reviewer SHALL be a repository collaborator whose approval review is +accepted by GitHub branch protection for the target branch and whose identity is +not the workflow automation actor committing signatures. + #### Scenario: PR to dev approved with package module changes - **WHEN** a pull request targeting `dev` is approved by a trusted reviewer - **AND** the PR contains changes to one or more files under `packages/` - **THEN** the CI signing workflow SHALL discover all `packages/*/module-package.yaml` manifests - whose payload changed on the PR branch since the merge-base with `origin/dev` + whose payload changed on the PR branch since the merge-base commit with `origin/dev` +- **AND** discovery SHALL compare against that merge-base snapshot rather than a moving `origin/dev` tip - **AND** SHALL sign them using `SPECFACT_MODULE_PRIVATE_SIGN_KEY` and `SPECFACT_MODULE_PRIVATE_SIGN_KEY_PASSPHRASE` - **AND** SHALL commit the updated manifests back to the PR branch @@ -70,4 +78,3 @@ from `src/specfact_cli/modules/` or `modules/` (which do not exist in this repos - **WHEN** the signing workflow runs twice on the same package payload - **THEN** the resulting `integrity:` block SHALL be byte-for-byte identical - **AND** the second run SHALL produce no git diff and SHALL skip the commit - diff --git a/openspec/specs/code-review-ai-bloat-detection/spec.md b/openspec/specs/code-review-ai-bloat-detection/spec.md index e0d91118..bc602c28 100644 --- a/openspec/specs/code-review-ai-bloat-detection/spec.md +++ b/openspec/specs/code-review-ai-bloat-detection/spec.md @@ -9,7 +9,7 @@ reporting, and the IDE simplification prompt input model. ## Requirements ### Requirement: The code-review runner SHALL emit findings under a new `ai_bloat` principle category -The code-review pipeline SHALL recognise `ai_bloat` as a valid value of the `category` field on `ReviewFinding` and as the policy-pack `principle` for all AI-bloat rules. The new category SHALL surface in `.specfact/code-review.json` alongside the existing categories `naming | kiss | yagni | dry | solid | clean_code | architecture` through an additive strict-schema update. Findings under `ai_bloat` SHALL emit at `info` severity only (the non-blocking severity already accepted by `ReviewFinding`); the runner SHALL never emit `ai_bloat` findings at `warning` or `error` severity in this iteration. The `advisory` framing is carried at the policy-pack layer via `default_mode: advisory`, not by introducing a new per-finding severity value. `ai_bloat` findings SHALL be score-neutral in v1. +The code-review pipeline SHALL recognise `ai_bloat` as a valid value of the `category` field on `ReviewFinding` and as the policy-pack `principle` for all AI-bloat rules. The category enumeration SHALL include `ai_bloat` with the governed categories `naming | kiss | yagni | dry | solid | clean_code | architecture | ai_bloat` through an additive strict-schema update. Findings under `ai_bloat` SHALL emit at `info` severity only (the non-blocking severity already accepted by `ReviewFinding`); the runner SHALL never emit `ai_bloat` findings at `warning` or `error` severity in this iteration. The `advisory` framing is carried at the policy-pack layer via `default_mode: advisory`, not by introducing a new per-finding severity value. `ai_bloat` findings SHALL be score-neutral in v1. #### Scenario: Review run on a fixture with a manual-loop comprehension emits an ai_bloat finding @@ -103,4 +103,4 @@ The clean-code policy-pack documentation SHALL note that `ai-bloat-patterns.yaml - **WHEN** a reader consults the clean-code policy-pack documentation - **THEN** the documentation SHALL state explicitly that `ai-bloat-patterns.yaml` is a separate policy pack - **AND** SHALL state that its severity model is `advisory`-only -- **AND** SHALL state that its principle category is `ai_bloat`, distinct from the existing principle categories (`naming | kiss | yagni | dry | solid | clean_code | architecture`) +- **AND** SHALL state that its principle category is `ai_bloat`, distinct from the clean-code principle categories (`naming | kiss | yagni | dry | solid | clean_code | architecture`) diff --git a/openspec/specs/code-review-simplification-feedback/spec.md b/openspec/specs/code-review-simplification-feedback/spec.md index 5760dcd2..22a82122 100644 --- a/openspec/specs/code-review-simplification-feedback/spec.md +++ b/openspec/specs/code-review-simplification-feedback/spec.md @@ -1,7 +1,10 @@ # code-review-simplification-feedback Specification ## Purpose -TBD - created by archiving change code-review-11-simplification-feedback-loop. Update Purpose after archive. +This specification defines advisory simplification feedback for code review: +deterministic overengineering detectors, additive finding metadata, duplicate +intent grouping, and IDE prompt consumption. + ## Requirements ### Requirement: Review findings carry optional simplification metadata @@ -12,6 +15,7 @@ The code-review report SHALL support optional simplification metadata on each fi - **WHEN** a simplification-capable detector emits a finding - **THEN** the finding MAY include `confidence`, `rewrite_hint`, `canonical_pattern`, `intent_key`, `estimated_deletion_lines`, and `related_locations` - **AND** each included metadata field SHALL be serializable in `.specfact/code-review.json` +- **AND** each included metadata field SHALL conform to the canonical optional simplification fields defined by the `review-finding-model` specification - **AND** existing required fields such as `category`, `severity`, `tool`, `rule`, `file`, `line`, `message`, and `fixable` SHALL remain present #### Scenario: Consumer ignores simplification metadata @@ -78,4 +82,3 @@ The `/specfact.08-simplify` prompt SHALL consume simplification metadata from `. - **WHEN** `/specfact.08-simplify` presents a simplification candidate - **THEN** it SHALL ask the user to accept, reject, skip, or request explanation before applying any edit - **AND** it SHALL apply only edits the user accepts - diff --git a/openspec/specs/guided-simplification-review/spec.md b/openspec/specs/guided-simplification-review/spec.md index c3f30c39..aa39399a 100644 --- a/openspec/specs/guided-simplification-review/spec.md +++ b/openspec/specs/guided-simplification-review/spec.md @@ -1,7 +1,10 @@ # guided-simplification-review Specification ## Purpose -TBD - created by archiving change code-review-12-guided-simplification-enforcement. Update Purpose after archive. +This specification defines how simplify-focused review findings classify cleanup +safety, preserve meaningful code, summarize outcomes, and guide AI assistants +without turning advisory cleanup into default blocking behavior. + ## Requirements ### Requirement: Simplification findings classify cleanup safety @@ -18,7 +21,7 @@ Simplify-focused review findings SHALL classify each simplification candidate in - **WHEN** a candidate occurs in a meaningful contract, interface, public compatibility, CLI boundary, or domain predicate context - **THEN** the finding SHALL use `guidance_kind="preserve"` or `guidance_kind="design_judgment"` -- **AND** `preserve` findings SHALL include a `preserve_reason` +- **AND** `preserve` findings SHALL include `preserve_reasons` from the closed taxonomy defined by the `review-finding-model` specification - **AND** the finding SHALL NOT be eligible for automatic cleanup ### Requirement: Guided simplification reports summarize recommendations and outcomes @@ -64,4 +67,3 @@ The `specfact-code-review` skill SHALL guide LLMs to interpret simplify-focused - **WHEN** an LLM uses the `specfact-code-review` skill to act on simplify findings - **THEN** the skill SHALL instruct it to apply `safe_mechanical`, test `needs_tests`, inspect `design_judgment`, and keep `preserve` - **AND** it SHALL prohibit treating AI-bloat findings as proof of AI authorship - diff --git a/openspec/specs/module-command-overview/spec.md b/openspec/specs/module-command-overview/spec.md index 274f6e70..57e14238 100644 --- a/openspec/specs/module-command-overview/spec.md +++ b/openspec/specs/module-command-overview/spec.md @@ -1,7 +1,10 @@ # module-command-overview Specification ## Purpose -TBD - created by archiving change tester-module-cli-reliability. Update Purpose after archive. +This specification defines deterministic module command overview artifacts and +the docs validation checks that keep published module command references aligned +with the actual command tree. + ## Requirements ### Requirement: Modules Publish Generated Command Overview Artifacts @@ -27,4 +30,3 @@ The modules repository SHALL generate deterministic command overview artifacts f - **WHEN** the command overview freshness check runs - **THEN** it fails if generated artifacts are stale - **AND** it reports the command needed to regenerate them. - diff --git a/openspec/specs/modules-docs-publishing/spec.md b/openspec/specs/modules-docs-publishing/spec.md index 5bb7d737..7133f13c 100644 --- a/openspec/specs/modules-docs-publishing/spec.md +++ b/openspec/specs/modules-docs-publishing/spec.md @@ -1,7 +1,10 @@ # modules-docs-publishing Specification ## Purpose -TBD - created by archiving change docs-01-modules-docs-canonical-site. Update Purpose after archive. +This specification governs the modules documentation publishing contract, +including deterministic site inputs, generated navigation, and published-link +validation for changed docs. + ## Requirements ### Requirement: Modules docs site is the canonical home for official bundle documentation @@ -72,6 +75,5 @@ The docs review workflow SHALL run the deterministic docs validators used by loc #### Scenario: Docs-only pull request has broken published link - **WHEN** a pull request changes only Markdown files under `docs/` -- **THEN** the docs review workflow runs published-route link validation -- **AND** the workflow fails when the changed docs introduce a broken published-route link - +- **THEN** the docs review workflow runs `published-link` validation +- **AND** the workflow fails when the changed docs introduce a broken `published-link` diff --git a/openspec/specs/prompt-command-validation/spec.md b/openspec/specs/prompt-command-validation/spec.md index f2fd806d..bda0e48a 100644 --- a/openspec/specs/prompt-command-validation/spec.md +++ b/openspec/specs/prompt-command-validation/spec.md @@ -1,7 +1,10 @@ # prompt-command-validation Specification ## Purpose -TBD - created by archiving change prompt-command-contract-validation. Update Purpose after archive. +This specification defines validation for CLI command references embedded in +bundle-owned prompt resources, so prompt guidance stays aligned with the +mounted SpecFact command tree and can self-heal when prose is stale. + ## Requirements ### Requirement: Bundle prompt command references SHALL match mounted CLI contracts @@ -68,4 +71,3 @@ Prompt command validation SHALL be available as a Hatch command and SHALL run au - **WHEN** the docs review workflow runs - **THEN** prompt command validation runs with logs - **AND** stale command references fail the workflow - diff --git a/openspec/specs/review-finding-model/spec.md b/openspec/specs/review-finding-model/spec.md index 7d4542eb..1c534549 100644 --- a/openspec/specs/review-finding-model/spec.md +++ b/openspec/specs/review-finding-model/spec.md @@ -3,6 +3,7 @@ ## Purpose The `ReviewFinding` model represents structured code-review findings emitted by the `specfact-code-review` bundle. This specification defines the canonical schema, category enumeration, and tool mapping for all review runners. + ## Requirements ### Requirement: ReviewFinding schema defines governed code-review findings @@ -28,6 +29,15 @@ The ReviewFinding model SHALL define core fields, governed categories, tool orig | `line` | integer | 1-based source line number | Yes | Must be ≥ 1 | | `message` | string | User-facing finding message | Yes | Non-empty string | | `fixable` | boolean | Whether finding can be auto-fixed | No | Default: false | +| `confidence` | number | Optional simplification confidence score | No | 0.0 through 1.0 when present | +| `rewrite_hint` | string | Optional suggested simpler idiom or standard pattern | No | Non-empty string when present | +| `canonical_pattern` | string | Optional stable detector pattern name | No | Non-empty string when present | +| `intent_key` | string | Optional deterministic duplicate-intent grouping key | No | Non-empty string when present | +| `estimated_deletion_lines` | integer | Optional estimated net line reduction | No | Must be ≥ 0 when present | +| `related_locations` | array | Optional related source locations for grouped findings | No | Each entry names file and line | +| `signal_trace` | array | Optional detector evidence trace | No | Entries name source/tool and fired status | +| `preserve_reasons` | array | Optional closed-taxonomy reasons to keep structure | No | Values from preserve-reason taxonomy | +| `remediation_packet` | object | Optional AI IDE remediation contract | No | Must satisfy remediation packet requirements | ##### Category Enumeration @@ -46,6 +56,7 @@ The following categories are supported: - `yagni`: YAGNI principle violations (You Aren't Gonna Need It) - `dry`: DRY principle violations (Don't Repeat Yourself) - `solid`: SOLID principle violations +- `ai_bloat`: Advisory AI-bloat and simplification-defense findings ##### Tool Enumeration @@ -91,6 +102,27 @@ The following tools are officially supported: - `checklist`: Emits `clean_code` findings for PR checklist items +#### Simplification Metadata + +Optional simplification metadata SHALL remain additive to the core finding +schema. Producers MAY include these fields on advisory simplification and +AI-bloat findings, and consumers SHALL ignore unknown optional metadata without +rejecting otherwise valid findings. + +The closed preserve-reason taxonomy SHALL contain: + +- `compatibility_boundary` +- `public_contract` +- `domain_predicate` +- `test_oracle` +- `performance_sensitive` +- `human_readability` +- `insufficient_confidence` + +When `preserve_reasons` is present and non-empty, the finding SHALL NOT be +eligible for automatic cleanup. When `related_locations` is present, each entry +SHALL include a repository-relative `file` and positive integer `line`. + #### Examples #### KISS Violation @@ -123,6 +155,26 @@ The following tools are officially supported: } ``` +#### AI-Bloat Advisory + +```json +{ + "category": "ai_bloat", + "severity": "info", + "tool": "ast", + "rule": "ai-bloat.manual-loop-comprehension", + "file": "src/module.py", + "line": 64, + "message": "Manual accumulator loop can be expressed as a comprehension.", + "fixable": false, + "confidence": 0.91, + "rewrite_hint": "Consider a list comprehension when the loop has no side effects.", + "canonical_pattern": "manual_loop_comprehension", + "estimated_deletion_lines": 3, + "preserve_reasons": [] +} +``` + #### SOLID Violation ```json @@ -145,10 +197,12 @@ The following tools are officially supported: 3. The `category` field must be one of the enumerated values 4. The `severity` field must be one of: "error", "warning", "info" 5. Tool names should match the official tool enumeration where possible +6. Optional simplification metadata must satisfy the type and range constraints in the core fields table +7. `preserve_reasons` values must come from the closed preserve-reason taxonomy #### Backward Compatibility -This specification is backward compatible with existing `ReviewFinding` consumers. New categories (`naming`, `kiss`, `yagni`, `dry`, `solid`) and tools (`ast`, `checklist`) extend rather than replace the existing schema. +This specification is backward compatible with existing `ReviewFinding` consumers. New categories (`naming`, `kiss`, `yagni`, `dry`, `solid`, `ai_bloat`), optional simplification metadata, and tools (`ast`, `checklist`) extend rather than replace the existing schema. ### Requirement: ReviewFinding schema supports additive simplification metadata @@ -173,4 +227,3 @@ The `ReviewFinding` model SHALL accept optional simplification metadata while pr - **THEN** the packet SHALL include a plain-language issue, recommended action, possible keep reason, safety checks, validation plan, and safe-to-autofix flag - **AND** the packet MAY include patch forecast references when preview evidence exists - **AND** AI IDE prompts and skills SHALL treat the JSON packet as authoritative over prompt prose - diff --git a/openspec/specs/review-run-command/spec.md b/openspec/specs/review-run-command/spec.md index ac6ebedd..0eb43124 100644 --- a/openspec/specs/review-run-command/spec.md +++ b/openspec/specs/review-run-command/spec.md @@ -1,12 +1,63 @@ # review-run-command Specification ## Purpose -TBD - created by archiving change code-review-08-review-run-integration. Update Purpose after archive. +This specification defines the public `specfact code review run` contract for +the modules repository: target selection, orchestration, governed JSON reports, +exit behavior, cleanup forecast controls, and documentation parity. + ## Requirements ### Requirement: End-to-End `specfact code review run` in modules repo The `specfact-code-review` bundle SHALL provide a fully wired `specfact code review run` command that orchestrates the existing tool runners, supports scoped file selection, emits governed review reports, and provides simplify-specific cleanup forecast and handoff controls. +#### Scenario: Representative modules-repo source can be reviewed without command failure + +- **GIVEN** a real Python source file from this repository +- **WHEN** `specfact code review run --json ` is executed in the modules repo +- **THEN** the command writes a `ReviewReport` JSON file +- **AND** the command does not fail because of command wiring, path handling, or tool invocation bugs in the bundle + +#### Scenario: JSON output uses file-based routing + +- **GIVEN** `specfact code review run --json` +- **WHEN** the command executes successfully +- **THEN** it writes the governed `ReviewReport` JSON payload to a file path +- **AND** `--out` overrides the default JSON output path + +#### Scenario: Interactive runs ask whether to include test files + +- **GIVEN** `specfact code review run` executes in interactive mode +- **WHEN** test-file inclusion has not been specified explicitly +- **THEN** the CLI asks whether test files should be included in the review scope +- **AND** the answer controls whether changed files under `tests/` are reviewed + +#### Scenario: Auto-detected review scope includes untracked Python files + +- **GIVEN** Python files exist in the workspace that are not yet tracked by Git +- **WHEN** `specfact code review run` auto-detects review scope +- **THEN** those untracked Python files are included in review scope +- **AND** test-file inclusion rules still apply to untracked files under `tests/` + +#### Scenario: Known low-signal findings are suppressible by default + +- **GIVEN** a review run includes test files or other paths that can emit known low-signal findings +- **WHEN** noise suppression is enabled +- **THEN** the report omits those known low-signal findings +- **AND** a command option allows users to include the suppressed findings for a strict/full review + +#### Scenario: Bundled skill instructs whether to include tests + +- **GIVEN** the bundled `specfact-code-review` skill is installed +- **WHEN** it guides a review workflow +- **THEN** it instructs the reviewer to decide whether tests should be included before running the review + +#### Scenario: Long-running review runs surface progress + +- **GIVEN** a review run executes multiple tool steps that can take noticeable time +- **WHEN** the command is running +- **THEN** the CLI shows which review step is currently executing +- **AND** progress feedback does not replace the primary stdout contract such as the final JSON output path + #### Scenario: Run command previews simplify fixes without mutating files - **WHEN** `specfact code review run --focus simplify --preview-fixes --json --out ` is executed @@ -173,7 +224,7 @@ The Code Review run documentation SHALL describe every supported public `specfac - **WHEN** the command rejects combinations such as positional files with `--scope` or `--path`, or `--focus` with `--include-tests` - **THEN** the Code Review docs describe the invalid combination behavior -- **AND** the docs include a user-facing alternative for the supported targeting style aligned with the public **`run`** signature (**`files: list[Path]`**): pass explicit **positional files** (file paths) for a fixed review set, or use **`--scope`** / **`--path`** (without positional files) to auto-discover targets from the repo +- **AND** the docs include a user-facing alternative for the supported targeting style: pass explicit positional file paths for a fixed review set, or use **`--scope`** / **`--path`** without positional files to auto-discover targets from the repo ### Requirement: Code Review docs SHALL stay aligned with review behavior @@ -208,4 +259,3 @@ The `specfact code review run` command SHALL accept `--focus simplify` as a targ - **THEN** automatic rewrites SHALL be limited to deterministic safe-mechanical findings - **AND** the command SHALL rerun review after applying rewrites - **AND** the JSON report SHALL record applied, failed, and still-recommended outcomes -