diff --git a/docs/authoring/publishing-modules.md b/docs/authoring/publishing-modules.md index 96e3784..f3aa0cb 100644 --- a/docs/authoring/publishing-modules.md +++ b/docs/authoring/publishing-modules.md @@ -28,6 +28,13 @@ Recommended layout: commands.py # or app.py, etc. ``` +Official bundles may also ship **bundle-owned resources** next to the manifest (included in the signed module payload), for example: + +- `resources/prompts/` — workflow prompt templates and `resources/prompts/shared/` companion files referenced by relative paths from those prompts +- `resources/templates/backlog/field_mappings/` — backlog field-mapping seed YAML copied by init/install flows (mirrored under `src//resources/...` when the runtime must resolve them via `find_package_resources_path`) + +Any change under `resources/` is part of the module payload: bump `version` in `module-package.yaml` and re-sign integrity metadata the same way as for code changes. + Exclude from the package: `.git`, `__pycache__`, `tests`, `.pytest_cache`, `*.pyc`, `*.pyo`. ## Script: publish-module.py diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index e60fb3f..2eb988e 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -30,6 +30,12 @@ ## Pending +### Packaging and bundle payloads + +| Module | Order | Change folder | GitHub # | Blocked by | +|--------|-------|---------------|----------|------------| +| packaging | 01 | packaging-01-bundle-resource-payloads | [#101](https://github.com/nold-ai/specfact-cli-modules/issues/101) | specfact-cli/packaging-02-cross-platform-runtime-and-module-resources defines the consuming installed-resource contract; specfact-cli/init-ide-prompt-source-selection ([#382](https://github.com/nold-ai/specfact-cli/issues/382)) owns runtime selection/export orchestration | + ### Code review bundle expansion | Module | Order | Change folder | GitHub # | Blocked by | diff --git a/openspec/changes/docs-08-bundle-overview-pages/proposal.md b/openspec/changes/docs-08-bundle-overview-pages/proposal.md index 899f012..6f23cfa 100644 --- a/openspec/changes/docs-08-bundle-overview-pages/proposal.md +++ b/openspec/changes/docs-08-bundle-overview-pages/proposal.md @@ -7,7 +7,7 @@ Users of specific bundles cannot quickly find all available commands, understand ## What Changes - Write 6 new bundle overview pages, one per official bundle: backlog, project, codebase, spec, govern, code-review -- Each overview page contains: bundle purpose, prerequisites, full command listing with brief descriptions, quick example for each major command group, and links to deep-dive guides +- Each overview page contains: bundle purpose, prerequisites, bundle-owned resource/setup notes where relevant, full command listing with brief descriptions, quick example for each major command group, and links to deep-dive guides - All command examples validated against actual `--help` output ## Capabilities @@ -20,6 +20,7 @@ Users of specific bundles cannot quickly find all available commands, understand - New files: `docs/bundles/backlog/overview.md`, `docs/bundles/project/overview.md`, `docs/bundles/codebase/overview.md`, `docs/bundles/spec/overview.md`, `docs/bundles/govern/overview.md`, `docs/bundles/code-review/overview.md` - Depends on: `docs-06-modules-site-ia-restructure` (bundles/ directory structure must exist) +- Aligns with: `packaging-01-bundle-resource-payloads` for bundle-owned prompts/templates and `specfact init ide` resource ownership - User-facing: each bundle has a clear entry point for discovering all available commands ## Source Tracking diff --git a/openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md b/openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md index 95575a2..449a940 100644 --- a/openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md +++ b/openspec/changes/docs-08-bundle-overview-pages/specs/bundle-overview-pages/spec.md @@ -1,24 +1,26 @@ -# Capability: bundle-overview-pages - -Each official bundle has a single overview page listing all commands, prerequisites, and quick examples. - -## Scenarios - -### Scenario: Overview page lists all bundle commands - -Given a bundle overview page (e.g., bundles/backlog/overview.md) -When a user reads the page -Then every registered command and subcommand for that bundle is listed -And each command has a brief description - -### Scenario: Overview page includes quick examples - -Given a bundle overview page -When a user reads the page -Then at least one practical example is shown for each major command group - -### Scenario: Command examples match actual CLI - -Given a command example in an overview page -When compared against the actual `specfact --help` output -Then the command name, arguments, and key options match +## ADDED Requirements + +### Requirement: Bundle overview pages SHALL provide complete bundle entry points +Each official bundle SHALL have a single overview page that lists its commands, prerequisites, examples, and relevant bundle-owned resource setup guidance. + +#### Scenario: Overview page lists all bundle commands +- **GIVEN** a bundle overview page such as `bundles/backlog/overview.md` +- **WHEN** a user reads the page +- **THEN** every registered command and subcommand for that bundle is listed +- **AND** each command has a brief description + +#### Scenario: Overview page includes quick examples +- **GIVEN** a bundle overview page +- **WHEN** a user reads the page +- **THEN** at least one practical example is shown for each major command group + +#### Scenario: Overview page explains bundle-owned resource setup when relevant +- **GIVEN** a bundle overview page for a bundle that ships prompts or workspace templates +- **WHEN** a user reads the page +- **THEN** the page explains which resources are bundled with that package +- **AND** it points to the supported setup flow such as `specfact init ide` or bundle-specific template/bootstrap commands + +#### Scenario: Command examples match actual CLI +- **GIVEN** a command example in an overview page +- **WHEN** compared against the actual `specfact --help` output +- **THEN** the command name, arguments, and key options match diff --git a/openspec/changes/docs-08-bundle-overview-pages/tasks.md b/openspec/changes/docs-08-bundle-overview-pages/tasks.md index c432ebf..2c7d361 100644 --- a/openspec/changes/docs-08-bundle-overview-pages/tasks.md +++ b/openspec/changes/docs-08-bundle-overview-pages/tasks.md @@ -5,15 +5,16 @@ ## 2. Write Overview Pages -- [ ] 2.1 Write `bundles/backlog/overview.md`: ceremony, daily, refine, add, analyze-deps, sync, diff, promote, verify-readiness, delta, policy, init-config, map-fields -- [ ] 2.2 Write `bundles/project/overview.md`: link-backlog, health-check, snapshot, regenerate, export-roadmap, version, sync bridge, devops-flow, plan init, import, migrate, add-feature, add-story -- [ ] 2.3 Write `bundles/codebase/overview.md`: import, analyze contracts, drift detect, validate sidecar, repro -- [ ] 2.4 Write `bundles/spec/overview.md`: contract (init/validate/coverage/serve/verify/test), generate, sdd -- [ ] 2.5 Write `bundles/govern/overview.md`: enforce (stage/sdd), patch +- [ ] 2.1 Write `bundles/backlog/overview.md`: ceremony, daily, refine, add, analyze-deps, sync, diff, promote, verify-readiness, delta, policy, init-config, map-fields, plus bundled template/bootstrap notes +- [ ] 2.2 Write `bundles/project/overview.md`: link-backlog, health-check, snapshot, regenerate, export-roadmap, version, sync bridge, devops-flow, plan init, import, migrate, add-feature, add-story, plan review, plan harden, plan compare, plus bundled prompt notes +- [ ] 2.3 Write `bundles/codebase/overview.md`: import, analyze contracts, drift detect, validate sidecar, repro, plus bundled prompt notes +- [ ] 2.4 Write `bundles/spec/overview.md`: contract (init/validate/coverage/serve/verify/test), generate, sdd, plus bundled prompt notes where relevant +- [ ] 2.5 Write `bundles/govern/overview.md`: enforce (stage/sdd), patch, plus bundled prompt notes - [ ] 2.6 Write `bundles/code-review/overview.md`: run, ledger, rules ## 3. Verification - [ ] 3.1 Validate every command example against `--help` output -- [ ] 3.2 Verify all internal links resolve -- [ ] 3.3 Run `bundle exec jekyll build` with zero warnings +- [ ] 3.2 Verify bundle overview pages do not describe migrated prompts/templates as core-owned assets +- [ ] 3.3 Verify all internal links resolve +- [ ] 3.4 Run `bundle exec jekyll build` with zero warnings diff --git a/openspec/changes/docs-09-missing-command-docs/proposal.md b/openspec/changes/docs-09-missing-command-docs/proposal.md index 8171266..72aa6ec 100644 --- a/openspec/changes/docs-09-missing-command-docs/proposal.md +++ b/openspec/changes/docs-09-missing-command-docs/proposal.md @@ -7,7 +7,7 @@ The spec, govern, code-review, and codebase bundles have minimal or no documenta ## What Changes - Write 11 new command reference pages covering all undocumented commands across 4 bundles -- Each page contains: command purpose, prerequisites, full option reference, practical examples, common patterns, and links to related commands +- Each page contains: command purpose, prerequisites, bundle-owned resource/setup notes where relevant, full option reference, practical examples, common patterns, and links to related commands - All examples validated against actual implementations ## Capabilities @@ -23,6 +23,7 @@ The spec, govern, code-review, and codebase bundles have minimal or no documenta - New files (11): `bundles/spec/validate.md`, `bundles/spec/generate-tests.md`, `bundles/spec/mock.md`, `bundles/govern/enforce.md`, `bundles/govern/patch.md`, `bundles/code-review/run.md`, `bundles/code-review/ledger.md`, `bundles/code-review/rules.md`, `bundles/codebase/analyze.md`, `bundles/codebase/drift.md`, `bundles/codebase/repro.md` - Depends on: `docs-06-modules-site-ia-restructure` (bundles/ directory structure must exist) +- Aligns with: `packaging-01-bundle-resource-payloads` so docs describe migrated bundle-owned prompts/templates consistently ## Source Tracking diff --git a/openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md b/openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md index d33d5d7..2f503fd 100644 --- a/openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md +++ b/openspec/changes/docs-09-missing-command-docs/specs/missing-command-docs/spec.md @@ -1,30 +1,31 @@ -# Capability: missing-command-docs - -Reference documentation for all previously undocumented commands across spec, govern, code-review, and codebase bundles. - -## Scenarios - -### Scenario: Each command page documents full option reference - -Given a command reference page (e.g., bundles/govern/enforce.md) -When a user reads the page -Then every option and argument from the command's --help output is documented -And practical examples demonstrate common usage patterns - -### Scenario: Spec bundle has complete documentation - -Given the spec bundle overview links to deep-dive pages -When a user follows links to validate, generate-tests, and mock -Then each page exists and contains command reference, examples, and related commands - -### Scenario: Govern bundle has complete documentation - -Given the govern bundle overview links to deep-dive pages -When a user follows links to enforce and patch -Then each page exists and contains command reference, examples, and related commands - -### Scenario: Code review bundle has complete documentation - -Given the code-review bundle overview links to deep-dive pages -When a user follows links to run, ledger, and rules -Then each page exists and contains command reference, examples, and related commands +## ADDED Requirements + +### Requirement: Missing command reference pages SHALL document the implemented command surface +Previously undocumented command pages SHALL describe the current option surface, examples, and relevant bundle-owned resource guidance for their commands. + +#### Scenario: Each command page documents full option reference +- **GIVEN** a command reference page such as `bundles/govern/enforce.md` +- **WHEN** a user reads the page +- **THEN** every option and argument from the command's `--help` output is documented +- **AND** practical examples demonstrate common usage patterns + +#### Scenario: Command pages explain bundle-owned resources where they affect usage +- **GIVEN** a command reference page for a command that depends on migrated bundle-owned prompts or templates +- **WHEN** a user reads the page +- **THEN** the page explains the relevant setup or bootstrap path +- **AND** it does not direct users to legacy core-owned resource locations + +#### Scenario: Spec bundle has complete documentation +- **GIVEN** the spec bundle overview links to deep-dive pages +- **WHEN** a user follows links to validate, generate-tests, and mock +- **THEN** each page exists and contains command reference, examples, and related commands + +#### Scenario: Govern bundle has complete documentation +- **GIVEN** the govern bundle overview links to deep-dive pages +- **WHEN** a user follows links to enforce and patch +- **THEN** each page exists and contains command reference, examples, and related commands + +#### Scenario: Code review bundle has complete documentation +- **GIVEN** the code-review bundle overview links to deep-dive pages +- **WHEN** a user follows links to run, ledger, and rules +- **THEN** each page exists and contains command reference, examples, and related commands diff --git a/openspec/changes/docs-09-missing-command-docs/tasks.md b/openspec/changes/docs-09-missing-command-docs/tasks.md index 0bf5da5..32865a2 100644 --- a/openspec/changes/docs-09-missing-command-docs/tasks.md +++ b/openspec/changes/docs-09-missing-command-docs/tasks.md @@ -29,5 +29,6 @@ ## 6. Verification - [ ] 6.1 Validate all command examples against `--help` output -- [ ] 6.2 Verify all internal links resolve -- [ ] 6.3 Run `bundle exec jekyll build` with zero warnings +- [ ] 6.2 Verify command docs that mention prompts/templates use bundle-owned resource language consistent with `packaging-01-bundle-resource-payloads` +- [ ] 6.3 Verify all internal links resolve +- [ ] 6.4 Run `bundle exec jekyll build` with zero warnings diff --git a/openspec/changes/docs-10-workflow-consolidation/proposal.md b/openspec/changes/docs-10-workflow-consolidation/proposal.md index 6cb6808..32fb882 100644 --- a/openspec/changes/docs-10-workflow-consolidation/proposal.md +++ b/openspec/changes/docs-10-workflow-consolidation/proposal.md @@ -13,6 +13,7 @@ Multiple brownfield guides overlap (brownfield-engineer, brownfield-journey, bro - Write new `workflows/daily-devops-routine.md`: morning standup -> refine -> commit -> review cycle - Write new `workflows/ci-cd-pipeline.md`: CI integration patterns with SpecFact commands - Validate and update existing `command-chains.md` against current command surface +- Fold bundle-owned prompt/template setup into the workflow docs where IDE export or workspace-template bootstrap is a prerequisite, so resource migration does not require a separate follow-up docs change ## Capabilities @@ -30,6 +31,7 @@ Multiple brownfield guides overlap (brownfield-engineer, brownfield-journey, bro - New files: `workflows/cross-module-chains.md`, `workflows/daily-devops-routine.md`, `workflows/ci-cd-pipeline.md` - Merged files: brownfield-engineer + brownfield-journey -> brownfield-modernization, brownfield-faq + brownfield-roi -> brownfield-faq-and-roi, 3 examples -> brownfield-examples - Updated: `workflows/command-chains.md` (validated against current commands) +- Aligns with: `packaging-01-bundle-resource-payloads` for module-owned prompt/template setup steps - Depends on: `docs-06-modules-site-ia-restructure` ## Source Tracking diff --git a/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md b/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md index 1a6a3b1..cd2009b 100644 --- a/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md +++ b/openspec/changes/docs-10-workflow-consolidation/specs/cross-module-workflow-docs/spec.md @@ -1,26 +1,28 @@ -# Capability: cross-module-workflow-docs - -Documented end-to-end flows showing how to chain commands across multiple bundles. - -## Scenarios - -### Scenario: Cross-module chain covers full lifecycle - -Given the cross-module-chains workflow doc -When a user reads the page -Then it shows a complete flow: backlog ceremony -> code import -> spec validate -> govern enforce -And each step shows the exact command with practical arguments - -### Scenario: Daily routine covers a full work day - -Given the daily-devops-routine workflow doc -When a user reads the page -Then it shows: morning standup, refinement, development, review, and end-of-day patterns -And each step links to the relevant bundle command reference - -### Scenario: CI pipeline doc covers automation patterns - -Given the ci-cd-pipeline workflow doc -When a user reads the page -Then it shows: pre-commit hooks, GitHub Actions integration, and CI/CD stage mapping -And all specfact commands shown are valid and current +## ADDED Requirements + +### Requirement: Workflow docs SHALL cover current cross-module flows and setup prerequisites +Workflow documentation SHALL show valid multi-bundle command chains and include resource-bootstrap steps when migrated bundle-owned prompts or templates are prerequisites. + +#### Scenario: Cross-module chain covers full lifecycle +- **GIVEN** the `cross-module-chains` workflow doc +- **WHEN** a user reads the page +- **THEN** it shows a complete flow such as backlog ceremony -> code import -> spec validate -> govern enforce +- **AND** each step shows the exact command with practical arguments + +#### Scenario: Daily routine covers a full work day +- **GIVEN** the `daily-devops-routine` workflow doc +- **WHEN** a user reads the page +- **THEN** it shows morning standup, refinement, development, review, and end-of-day patterns +- **AND** each step links to the relevant bundle command reference + +#### Scenario: Workflow docs explain resource bootstrap before dependent flows +- **GIVEN** a workflow doc that uses AI IDE prompts or backlog workspace templates +- **WHEN** a user reads the page +- **THEN** the workflow includes the supported resource bootstrap step such as `specfact init ide` +- **AND** it does not rely on legacy core-owned resource paths + +#### Scenario: CI pipeline doc covers automation patterns +- **GIVEN** the `ci-cd-pipeline` workflow doc +- **WHEN** a user reads the page +- **THEN** it shows pre-commit hooks, GitHub Actions integration, and CI/CD stage mapping +- **AND** all SpecFact commands shown are valid and current diff --git a/openspec/changes/docs-10-workflow-consolidation/tasks.md b/openspec/changes/docs-10-workflow-consolidation/tasks.md index c8a29d9..890ad1d 100644 --- a/openspec/changes/docs-10-workflow-consolidation/tasks.md +++ b/openspec/changes/docs-10-workflow-consolidation/tasks.md @@ -14,6 +14,7 @@ - [ ] 3.1 Write `workflows/cross-module-chains.md`: backlog -> code -> spec -> govern end-to-end flow - [ ] 3.2 Write `workflows/daily-devops-routine.md`: morning standup -> refine -> commit -> review cycle - [ ] 3.3 Write `workflows/ci-cd-pipeline.md`: CI integration with pre-commit hooks, GitHub Actions +- [ ] 3.4 Add bundle-owned prompt/template bootstrap steps where workflows depend on migrated resources ## 4. Update Existing @@ -23,5 +24,6 @@ ## 5. Verification - [ ] 5.1 Verify all command examples in workflow docs match actual `--help` output -- [ ] 5.2 Verify all internal links resolve -- [ ] 5.3 Run `bundle exec jekyll build` with zero warnings +- [ ] 5.2 Verify workflow docs do not reference legacy core-owned prompt/template paths +- [ ] 5.3 Verify all internal links resolve +- [ ] 5.4 Run `bundle exec jekyll build` with zero warnings diff --git a/openspec/changes/docs-11-team-enterprise-tier/proposal.md b/openspec/changes/docs-11-team-enterprise-tier/proposal.md index 4716279..dfeeb50 100644 --- a/openspec/changes/docs-11-team-enterprise-tier/proposal.md +++ b/openspec/changes/docs-11-team-enterprise-tier/proposal.md @@ -10,6 +10,7 @@ All existing docs assume individual developer usage. There is no guidance for te - Expand agile-scrum-workflows.md into a team onboarding playbook for Scrum and Kanban teams - Write new multi-repo setup guide for teams working across multiple repositories - Write new enterprise configuration guide covering custom profiles, domain overlays, and central config management +- Document how teams manage bundle-owned prompts/templates through installed module versions and shared bootstrap flows after `packaging-01-bundle-resource-payloads` ## Capabilities @@ -22,6 +23,7 @@ All existing docs assume individual developer usage. There is no guidance for te - Expanded files: `team-and-enterprise/team-collaboration.md`, `team-and-enterprise/agile-scrum-setup.md` - New files: `team-and-enterprise/multi-repo.md`, `team-and-enterprise/enterprise-config.md` +- Aligns with: `packaging-01-bundle-resource-payloads` for team-facing prompt/template ownership and rollout guidance - Depends on: `docs-06-modules-site-ia-restructure` ## Source Tracking diff --git a/openspec/changes/docs-11-team-enterprise-tier/specs/team-enterprise-docs/spec.md b/openspec/changes/docs-11-team-enterprise-tier/specs/team-enterprise-docs/spec.md index b468c7d..649b548 100644 --- a/openspec/changes/docs-11-team-enterprise-tier/specs/team-enterprise-docs/spec.md +++ b/openspec/changes/docs-11-team-enterprise-tier/specs/team-enterprise-docs/spec.md @@ -1,23 +1,25 @@ -# Capability: team-enterprise-docs - -Documentation tier for team and enterprise adoption of SpecFact. - -## Scenarios - -### Scenario: Team setup guide covers onboarding - -Given the team-collaboration doc -When a team lead reads the page -Then it covers: initial setup for a team, shared configuration, role-based workflows, and recommended ceremony schedules - -### Scenario: Enterprise config guide covers customization - -Given the enterprise-config doc -When an enterprise admin reads the page -Then it covers: custom profiles, domain overlays, central configuration, and multi-registry setups - -### Scenario: Multi-repo guide covers cross-repo workflows - -Given the multi-repo doc -When a user managing multiple repositories reads the page -Then it covers: shared bundle configuration, cross-repo sync, and repository-specific overrides +## ADDED Requirements + +### Requirement: Team and enterprise docs SHALL cover operational setup and resource ownership +Team and enterprise guidance SHALL explain onboarding, configuration, multi-repo operations, and how bundle-owned prompts/templates are rolled out and kept in sync. + +#### Scenario: Team setup guide covers onboarding +- **GIVEN** the team-collaboration doc +- **WHEN** a team lead reads the page +- **THEN** it covers initial setup for a team, shared configuration, role-based workflows, and recommended ceremony schedules + +#### Scenario: Enterprise config guide covers customization +- **GIVEN** the enterprise-config doc +- **WHEN** an enterprise admin reads the page +- **THEN** it covers custom profiles, domain overlays, central configuration, and multi-registry setups + +#### Scenario: Multi-repo guide covers cross-repo workflows +- **GIVEN** the multi-repo doc +- **WHEN** a user managing multiple repositories reads the page +- **THEN** it covers shared bundle configuration, cross-repo sync, and repository-specific overrides + +#### Scenario: Team docs explain bundle-owned resource rollout +- **GIVEN** the team or enterprise setup docs +- **WHEN** a team lead reads the page +- **THEN** the docs explain that prompts and bundle-specific workspace templates ship from installed bundles +- **AND** they describe how teams keep those resources aligned through supported bootstrap commands and version management diff --git a/openspec/changes/docs-11-team-enterprise-tier/tasks.md b/openspec/changes/docs-11-team-enterprise-tier/tasks.md index 77315d0..2fa75ee 100644 --- a/openspec/changes/docs-11-team-enterprise-tier/tasks.md +++ b/openspec/changes/docs-11-team-enterprise-tier/tasks.md @@ -12,9 +12,11 @@ - [ ] 3.1 Write `team-and-enterprise/multi-repo.md`: multi-repo setups with shared bundles - [ ] 3.2 Write `team-and-enterprise/enterprise-config.md`: custom profiles, domain overlays, central config +- [ ] 3.3 Document team rollout/versioning guidance for bundle-owned prompts and workspace templates ## 4. Verification - [ ] 4.1 Verify all command examples match actual CLI -- [ ] 4.2 Verify all internal links resolve -- [ ] 4.3 Run `bundle exec jekyll build` with zero warnings +- [ ] 4.2 Verify team/enterprise docs describe migrated resources as bundle-owned rather than core-owned +- [ ] 4.3 Verify all internal links resolve +- [ ] 4.4 Run `bundle exec jekyll build` with zero warnings diff --git a/openspec/changes/docs-12-docs-validation-ci/proposal.md b/openspec/changes/docs-12-docs-validation-ci/proposal.md index 6572fa0..871c2a1 100644 --- a/openspec/changes/docs-12-docs-validation-ci/proposal.md +++ b/openspec/changes/docs-12-docs-validation-ci/proposal.md @@ -8,6 +8,7 @@ Documentation command examples can drift from actual module implementations. Cro - Add a script that extracts command registrations from all `packages/*/src/**/commands.py` and compares against command examples in `docs/bundles/` - Add cross-site link validation for links from modules docs to core docs +- Add checks that docs do not point users at legacy core-owned prompt/template paths when those resources are bundle-owned - Integrate into CI workflow ## Capabilities diff --git a/openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md b/openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md index 589dce0..888abbc 100644 --- a/openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md +++ b/openspec/changes/docs-12-docs-validation-ci/specs/modules-docs-command-validation/spec.md @@ -1,19 +1,22 @@ -# Capability: modules-docs-command-validation +## ADDED Requirements -CI validation that module docs command examples match actual bundle implementations. +### Requirement: Docs validation SHALL reject stale command and resource references +The modules-side docs validation workflow SHALL reject command examples that do not match implemented bundle commands and SHALL also reject stale references to migrated core-owned resource paths. -## Scenarios +#### Scenario: Valid command example passes +- **GIVEN** a docs page references `specfact backlog ceremony standup` +- **WHEN** the validation runs +- **THEN** it finds a matching registration in the backlog package source +- **AND** the check passes -### Scenario: Valid command example passes +#### Scenario: Invalid command example fails +- **GIVEN** a docs page references `specfact backlog nonexistent` +- **WHEN** the validation runs +- **THEN** it reports the mismatch +- **AND** the check fails -Given a docs page references `specfact backlog ceremony standup` -When the validation runs -Then it finds a matching registration in the backlog package source -And the check passes - -### Scenario: Invalid command example fails - -Given a docs page references `specfact backlog nonexistent` -When the validation runs -Then it reports the mismatch -And the check fails +#### Scenario: Legacy core-owned resource path reference fails +- **GIVEN** a docs page instructs users to fetch a migrated prompt or template from a legacy core-owned path +- **WHEN** the validation runs +- **THEN** it reports the stale resource reference +- **AND** the check fails diff --git a/openspec/changes/docs-12-docs-validation-ci/tasks.md b/openspec/changes/docs-12-docs-validation-ci/tasks.md index 3b08bf2..0fae25b 100644 --- a/openspec/changes/docs-12-docs-validation-ci/tasks.md +++ b/openspec/changes/docs-12-docs-validation-ci/tasks.md @@ -7,6 +7,7 @@ - [ ] 2.1 Write `scripts/check-docs-commands.py` to extract command registrations from `packages/*/src/**/commands.py` - [ ] 2.2 Compare extracted commands against code blocks in `docs/bundles/` and `docs/reference/commands.md` +- [ ] 2.3 Flag stale references to legacy core-owned prompt/template locations that were migrated by `packaging-01-bundle-resource-payloads` ## 3. Cross-Site Link Validation @@ -19,4 +20,5 @@ ## 5. Verification - [ ] 5.1 Run validation locally and verify it catches broken examples -- [ ] 5.2 Run CI workflow end-to-end +- [ ] 5.2 Run validation locally and verify it catches stale core-owned resource path references +- [ ] 5.3 Run CI workflow end-to-end diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/.openspec.yaml b/openspec/changes/packaging-01-bundle-resource-payloads/.openspec.yaml new file mode 100644 index 0000000..2ca4bc8 --- /dev/null +++ b/openspec/changes/packaging-01-bundle-resource-payloads/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-24 diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/CHANGE_VALIDATION.md b/openspec/changes/packaging-01-bundle-resource-payloads/CHANGE_VALIDATION.md new file mode 100644 index 0000000..15b2c84 --- /dev/null +++ b/openspec/changes/packaging-01-bundle-resource-payloads/CHANGE_VALIDATION.md @@ -0,0 +1,10 @@ +# Change Validation + +- Date: 2026-03-24 +- Command: `openspec validate packaging-01-bundle-resource-payloads --strict` +- Result: `Change 'packaging-01-bundle-resource-payloads' is valid` + +## Notes + +- Validation completed after proposal, design, specs, and tasks were created. +- The change is apply-ready and tracked in `openspec/CHANGE_ORDER.md` under Packaging and bundle payloads. diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/RESOURCE_OWNERSHIP_AUDIT.md b/openspec/changes/packaging-01-bundle-resource-payloads/RESOURCE_OWNERSHIP_AUDIT.md new file mode 100644 index 0000000..6494fb4 --- /dev/null +++ b/openspec/changes/packaging-01-bundle-resource-payloads/RESOURCE_OWNERSHIP_AUDIT.md @@ -0,0 +1,74 @@ +# Resource Ownership Audit + +Date: 2026-03-25 + +## Reviewed Core Resource Inventory + +### Prompt templates currently in `specfact-cli/resources/prompts` + +| Core path | Owning bundle | Notes | +| --- | --- | --- | +| `resources/prompts/specfact.01-import.md` | `specfact-codebase` | Executes `specfact import from-code` from the codebase bundle surface. | +| `resources/prompts/specfact.02-plan.md` | `specfact-project` | Covers `specfact plan *` plan-management flows. | +| `resources/prompts/specfact.03-review.md` | `specfact-project` | Covers `specfact plan review`. This is distinct from the `code review` bundle. | +| `resources/prompts/specfact.04-sdd.md` | `specfact-project` | Executes `specfact plan harden`; naming is historical but command ownership is project-bundle. | +| `resources/prompts/specfact.05-enforce.md` | `specfact-govern` | Covers `specfact enforce sdd`. | +| `resources/prompts/specfact.06-sync.md` | `specfact-project` | Covers `specfact sync bridge`. | +| `resources/prompts/specfact.07-contracts.md` | `specfact-spec` | Covers contract enhancement flows under the spec bundle. | +| `resources/prompts/specfact.compare.md` | `specfact-project` | Covers `specfact plan compare`. | +| `resources/prompts/specfact.validate.md` | `specfact-codebase` | Covers `specfact repro`. | +| `resources/prompts/shared/cli-enforcement.md` | Shared companion resource | Referenced by prompt templates via relative path; export is broken if this file is not shipped/copied with prompts. | + +### Historical prompt leftovers observed outside the current source tree + +- Installed prompt caches in the sibling `specfact-cli` environment still include backlog prompts such as `specfact.backlog-add.md`, `specfact.backlog-daily.md`, `specfact.backlog-refine.md`, and `specfact.sync-backlog.md`. +- Those files are not present in the current canonical source tree under `specfact-cli/resources/prompts`, so they are treated as historical residue rather than the current migration source of truth for this change. + +### Backlog workspace-template seeds still living in `specfact-cli` + +Canonical source today: + +- `.specfact/templates/backlog/field_mappings/ado_agile.yaml` +- `.specfact/templates/backlog/field_mappings/ado_custom.yaml` +- `.specfact/templates/backlog/field_mappings/ado_default.yaml` +- `.specfact/templates/backlog/field_mappings/ado_kanban.yaml` +- `.specfact/templates/backlog/field_mappings/ado_safe.yaml` +- `.specfact/templates/backlog/field_mappings/ado_scrum.yaml` +- `.specfact/templates/backlog/field_mappings/github_custom.yaml` + +Audit result: + +- These are backlog-bundle-owned workspace-template seeds. +- Goal 3 requires migrating the full set, not only `ado_*.yaml`, because current copy flows and backlog commands also rely on non-ADO templates such as `github_custom.yaml`. + +### Resources reviewed and retained as core-owned + +These remain in core unless a later audit proves otherwise: + +- `resources/keys/*` +- `resources/mappings/*` +- `resources/schemas/*` +- `resources/templates/github-action.yml.j2` +- `resources/templates/persona/*` +- `resources/templates/policies/*` +- `resources/templates/plan.bundle.yaml.j2` +- `resources/templates/pr-template.md.j2` +- `resources/templates/protocol.yaml.j2` +- `resources/templates/telemetry.yaml.example` +- `.specify/templates/*` +- `src/specfact_cli/templates/*` + +### Resources already bundle-local in `specfact-cli-modules` + +These are already package-owned and are not migration inputs from the core resource tree: + +- `packages/specfact-backlog/src/specfact_backlog/backlog_core/resources/backlog-templates/*` +- `packages/specfact-code-review/src/specfact_code_review/resources/skills/specfact-code-review/SKILL.md` +- `packages/specfact-code-review/src/specfact_code_review/resources/supabase/review_ledger_ddl.sql` + +## Review Conclusions + +1. `packaging-01` must explicitly cover the prompt inventory above, not just “move prompts to corresponding bundles.” +2. Prompt companion files are part of the prompt payload contract because exported prompts reference them by relative path. +3. Backlog template migration must include the entire workspace seed set used by init/install flows, including `github_custom.yaml`. +4. Docs changes `docs-08` through `docs-12` need to describe bundle-owned prompts/templates and reject stale core-owned path references so no separate docs change is required. diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/TDD_EVIDENCE.md b/openspec/changes/packaging-01-bundle-resource-payloads/TDD_EVIDENCE.md new file mode 100644 index 0000000..75e9bad --- /dev/null +++ b/openspec/changes/packaging-01-bundle-resource-payloads/TDD_EVIDENCE.md @@ -0,0 +1,26 @@ +# TDD evidence — packaging-01-bundle-resource-payloads + +## Failing-first (design) + +- Added `tests/unit/test_bundle_resource_payloads.py` asserting stable `packages//resources/...` paths for audited prompts, `shared/cli-enforcement.md`, backlog field-mapping seeds (including non-ADO `github_custom.yaml`), integrity payload sensitivity to resource edits, and version-bump helper behavior. + +## Passing (implementation) + +- 2026-03-25: `python -m pytest tests/unit/test_bundle_resource_payloads.py` — 9 passed. +- Bundles now ship resources under each module package root (`resources/prompts`, `resources/templates/backlog/field_mappings`) with a mirror under `src/specfact_backlog/resources/...` for `find_package_resources_path("specfact_backlog", ...)`. +- `specfact_backlog.backlog.field_mapping_resources.load_ado_framework_template_config` prefers backlog bundle + module-root paths before legacy `specfact_cli` templates (logic extracted from `commands.py` for clarity and reviewability). +- Docs: `docs/authoring/publishing-modules.md` documents bundle-owned `resources/` and version/signature expectations. + +## packaging-02 path contract (task 4.2) + +- **Module install layout**: `.specfact/modules//resources/prompts`, `.specfact/modules//resources/templates/backlog/field_mappings` (module root = directory containing `module-package.yaml`). +- **Python package layout (backlog)**: `specfact_backlog/resources/templates/backlog/field_mappings` for installed-package resolution. + +## docs-08 … docs-12 (task 4.4) + +- User-facing path updates for bundle-owned prompts/templates are expected to land in the active docs changes (`docs-08`–`docs-12`); this change does not add a separate docs change id. + +## Signing note + +- Local signing used `scripts/sign-modules.py --allow-unsigned --payload-from-filesystem` when encrypted private key passphrase was unavailable. +- Before opening a PR, re-run signing with the repository private key so `integrity.signature` is present for `verify-modules-signature.py --require-signature`. diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/design.md b/openspec/changes/packaging-01-bundle-resource-payloads/design.md new file mode 100644 index 0000000..8f3547d --- /dev/null +++ b/openspec/changes/packaging-01-bundle-resource-payloads/design.md @@ -0,0 +1,67 @@ +## Context + +The modules repo currently packages official bundles as mostly code-and-manifest payloads. At the same time, the core CLI repository still carries workflow prompt templates under `resources/prompts`, and core init logic separately copies backlog field mapping templates from a core-owned `resources/templates/backlog/field_mappings` location. + +That split is no longer coherent after bundle extraction: + +- prompts belong to the workflow bundles, not to core lifecycle commands +- backlog field mapping templates belong to the backlog bundle, not to core +- prompt companion assets such as `shared/cli-enforcement.md` travel with those prompts and must remain resolvable after export +- installed bundle packages need a stable on-disk resource layout so core CLI can discover resources from installed bundles rather than from fallback core directories + +The audit result is explicit: the official bundle package directories in `specfact-cli-modules` do not currently contain `resources/prompts` trees, so a modules-repo change is required. + +## Goals / Non-Goals + +**Goals:** + +- package prompt templates inside the owning official bundles +- package prompt companion assets required by those prompts, starting with `resources/prompts/shared/cli-enforcement.md` +- package other module-owned resources that still live in core, beginning with the full backlog field mapping template seed set +- standardize a resource layout that can be discovered from installed bundle roots +- prove that signing and verification remain resource-aware and fail when bundled resources change without a version/signature update + +**Non-Goals:** + +- implement the core CLI discovery/export logic itself; that belongs to specfact-cli +- redesign prompt content or workflow semantics +- move resources that are still genuinely core-owned, such as global signing keys, unless ownership analysis proves otherwise + +## Decisions + +### 1. Co-locate resources under each owning bundle package + +Each official bundle should carry a `resources/` subtree inside its package directory for assets that travel with that bundle. At minimum this change covers: + +- prompt templates for bundle-owned workflows +- prompt companion resources referenced by those prompt templates +- backlog field mapping templates under the backlog bundle, including non-ADO templates copied into workspace state + +This keeps installation, packaging, signature, and ownership boundaries aligned. + +### 2. Treat resource changes as bundle payload changes + +The modules repo already computes integrity hashes from full module payloads. This change will preserve that behavior and add tests/documentation so resource additions and edits are explicitly covered by version-bump and signature workflows. + +### 3. Keep the contract with core CLI path-based and package-rooted + +The bundle packages should expose resources through a stable package-root layout rather than through bespoke manifest-only indirection. Core CLI can then discover `resources/prompts`, prompt companion files under the same prompt root, or other agreed subpaths from installed bundle roots. + +## Risks / Trade-offs + +- `[Resource ownership audit misses a leftover core-owned file]` -> record the audited inventory and explicit keep-in-core list in a change-local audit artifact. +- `[Prompts copy successfully but relative includes break]` -> treat prompt companion files as part of the prompt payload contract, not optional extras. +- `[Bundle packages gain more non-code files]` -> accept slightly larger artifacts in exchange for correct ownership and install behavior. +- `[Core and modules repos drift on expected resource paths]` -> keep the path contract explicit and cross-reference the specfact-cli packaging change. + +## Migration Plan + +1. Audit which current core resources are bundle-owned. +2. Move prompt templates, prompt companion assets, and backlog field mapping templates into the owning bundle packages. +3. Add tests for package-resource presence and integrity/version-bump enforcement. +4. Update docs/manifests as needed and sync dependency notes back to the core packaging change. + +## Open Questions + +- Whether any non-backlog template directories under core resources also belong to extracted bundles after the audit in `RESOURCE_OWNERSHIP_AUDIT.md`. +- Whether bundle manifests should later gain explicit resource catalog metadata, or whether stable subpaths are sufficient for the first iteration. diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/proposal.md b/openspec/changes/packaging-01-bundle-resource-payloads/proposal.md new file mode 100644 index 0000000..96ae498 --- /dev/null +++ b/openspec/changes/packaging-01-bundle-resource-payloads/proposal.md @@ -0,0 +1,41 @@ +## Why + +Bundle-owned prompt templates and other workflow resources still live in the core CLI repository, while the bundle packages that actually own those workflows ship without those assets. That breaks package ownership, prevents `specfact init ide` and install flows from discovering the right source payloads, and leaves resource movement dependent on core-only fallbacks instead of bundle packaging. + +## What Changes + +- Add bundle-packaged resource payloads for official bundles so prompts and other module-owned assets ship from the bundle that owns them. +- Move workflow prompt templates out of `specfact-cli/resources/prompts` into the corresponding bundle packages in `specfact-cli-modules`. +- Move any other module-owned assets that still live in core, starting with backlog field mapping templates, into the owning bundle package. +- Preserve prompt companion assets such as `resources/prompts/shared/cli-enforcement.md` so exported prompts do not ship broken relative references. +- Audit and migrate the complete backlog workspace-template seed set required by init/install flows, not just `ado_*.yaml`. +- Define and test a consistent package layout for bundle resources so the core CLI can discover them from installed bundle locations. +- Lock resource payloads into signing, verification, and publish/version-bump workflows so bundle updates are resource-aware. +- Keep `specfact-cli` runtime discovery, source selection, and `specfact init ide` export orchestration out of scope here; that work is tracked in `specfact-cli` change `init-ide-prompt-source-selection` (`nold-ai/specfact-cli#382`). + +## Capabilities + +### New Capabilities +- `bundle-packaged-resources`: Official bundle packages ship their prompt templates and other module-owned resources within the bundle package tree. +- `resource-aware-integrity`: Bundle resource payloads participate in signing, verification, and version-bump enforcement so resource changes are treated as publishable bundle changes. + +### Modified Capabilities + +None. + +## Impact + +- Affected code: `packages/specfact-*/`, module manifests, packaging/publish/signature scripts, and modules-repo tests. +- Affected systems: bundle packaging, registry publish validation, signature verification, and core CLI installed-resource discovery. +- Audit artifact: `openspec/changes/packaging-01-bundle-resource-payloads/RESOURCE_OWNERSHIP_AUDIT.md` +- Cross-repo dependency: this change provides the resource payloads consumed by specfact-cli change `packaging-02-cross-platform-runtime-and-module-resources` and the narrowed core-side orchestration/selectability change `init-ide-prompt-source-selection` (`nold-ai/specfact-cli#382`). + +--- + +## Source Tracking + + +- **GitHub Issue**: #101 +- **Issue URL**: +- **Last Synced Status**: proposed +- **Sanitized**: false diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/specs/bundle-packaged-resources/spec.md b/openspec/changes/packaging-01-bundle-resource-payloads/specs/bundle-packaged-resources/spec.md new file mode 100644 index 0000000..dadf4c9 --- /dev/null +++ b/openspec/changes/packaging-01-bundle-resource-payloads/specs/bundle-packaged-resources/spec.md @@ -0,0 +1,24 @@ +## ADDED 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 at least the codebase, project, spec, and govern bundles for the currently exported core prompt set + +#### Scenario: Prompt companion resources ship with prompt payloads +- **WHEN** an exported prompt template references a companion file by relative path, such as `./shared/cli-enforcement.md` +- **THEN** the owning bundle package contains that companion resource in a stable relative location +- **AND** prompt export/copy flows can preserve a resolvable relative layout in the target IDE workspace + +#### Scenario: Backlog bundle ships workspace-template seed resources +- **WHEN** the backlog bundle package is inspected from source or from an installed artifact +- **THEN** the package contains the backlog field mapping templates that `specfact init` or related flows need to copy into workspace state +- **AND** the packaged set includes both ADO and non-ADO seed templates required by supported backlog flows + +#### Scenario: Core no longer remains the source of truth for bundle prompts +- **WHEN** a workflow prompt belongs to an extracted bundle rather than to core lifecycle commands +- **THEN** that prompt's canonical packaged source exists in the owning bundle package +- **AND** release packaging does not rely on the core CLI repo as the canonical source for that prompt diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/specs/resource-aware-integrity/spec.md b/openspec/changes/packaging-01-bundle-resource-payloads/specs/resource-aware-integrity/spec.md new file mode 100644 index 0000000..0da017f --- /dev/null +++ b/openspec/changes/packaging-01-bundle-resource-payloads/specs/resource-aware-integrity/spec.md @@ -0,0 +1,29 @@ +## ADDED Requirements + +### Requirement: Bundle integrity SHALL cover resource payloads +Bundle signing, verification, and publish validation SHALL treat bundled resource files as part of the signed module payload so that resource-only changes are detected as bundle changes. + +#### Scenario: Resource edit changes signed payload +- **WHEN** a prompt template or other bundled resource file changes inside a bundle package +- **THEN** integrity verification detects a payload change until the manifest version and signature are refreshed + +#### Scenario: Resource-only change triggers version-bump enforcement +- **WHEN** a bundled resource file changes but the bundle manifest version is not incremented +- **THEN** the modules-repo version-bump enforcement reports that the bundle payload changed without a version bump + +### Requirement: Bundle resource layout SHALL be discoverable by core CLI +Bundled resources SHALL live at stable paths inside the bundle package so that the core CLI can resolve them from an installed bundle root without hardcoded core-repo fallbacks. + +#### Scenario: Core resolves prompt resources from installed bundle root +- **WHEN** the core CLI inspects an installed official bundle package +- **THEN** the bundle contains a stable prompt resource path that can be discovered without scanning the core CLI repository + +#### Scenario: Core resolves prompt companion resources with exported prompts +- **WHEN** the core CLI exports a prompt that depends on a companion file such as `shared/cli-enforcement.md` +- **THEN** the companion resource is discoverable from the same installed bundle root +- **AND** the exported prompt does not contain a broken relative reference after copy + +#### Scenario: Core resolves backlog workspace-template seeds from installed bundle root +- **WHEN** the core CLI inspects an installed backlog bundle package +- **THEN** the bundle contains a stable template resource path for backlog field mapping templates +- **AND** that path exposes every seed template the init/install flows are expected to copy diff --git a/openspec/changes/packaging-01-bundle-resource-payloads/tasks.md b/openspec/changes/packaging-01-bundle-resource-payloads/tasks.md new file mode 100644 index 0000000..ce24552 --- /dev/null +++ b/openspec/changes/packaging-01-bundle-resource-payloads/tasks.md @@ -0,0 +1,31 @@ +## 1. Scope And Ownership Audit + +- [x] 1.1 Enumerate prompt templates currently stored in specfact-cli core and map each one to the owning official bundle. +- [x] 1.2 Record prompt companion assets required by those prompts, starting with `resources/prompts/shared/cli-enforcement.md`, and map how they will be packaged and exported. +- [x] 1.3 Audit other core `resources/` assets for bundle ownership, starting with the complete backlog field mapping template seed set used by init/install flows. +- [x] 1.4 Record any assets that remain legitimately core-owned so the migration boundary is explicit. +- [x] 1.5 Save the ownership inventory and keep-in-core list in `RESOURCE_OWNERSHIP_AUDIT.md`. + +## 2. Test-First Packaging Coverage + +- [x] 2.1 Add failing tests that assert official bundles package their owned prompt resources at stable bundle resource paths. +- [x] 2.2 Add failing tests that assert prompt companion assets referenced by exported prompts are packaged and discoverable with those prompts. +- [x] 2.3 Add failing tests that assert the backlog bundle packages all field mapping templates needed by init/install flows, including non-ADO templates. +- [x] 2.4 Add failing tests for integrity/version-bump enforcement when bundled resources change. +- [x] 2.5 Add failing tests or fixtures that exercise the stable resource paths expected by `specfact init ide` and related copy flows. +- [x] 2.6 Record failing evidence in `TDD_EVIDENCE.md`. + +## 3. Bundle Resource Migration + +- [x] 3.1 Move prompt templates from core-owned storage into the owning official bundle packages. +- [x] 3.2 Move prompt companion assets needed by migrated prompts into the stable bundle prompt layout. +- [x] 3.3 Move backlog field mapping templates and any other audited bundle-owned resources into the owning bundle packages. +- [x] 3.4 Update manifests, package data, and publish-time expectations so the resources are included in released bundle artifacts. + +## 4. Validation + +- [x] 4.1 Re-run packaging and integrity tests and record passing evidence in `TDD_EVIDENCE.md`. +- [x] 4.2 Verify the packaged layout matches the path contract consumed by specfact-cli change `packaging-02-cross-platform-runtime-and-module-resources`. +- [x] 4.3 Update docs or package guidance for bundle-owned resources and publish/version-bump expectations. +- [x] 4.4 Confirm docs changes `docs-08` through `docs-12` absorb the user-facing documentation fallout from migrated resources so no extra docs change is required. +- [x] 4.5 Run `openspec validate packaging-01-bundle-resource-payloads --strict`. diff --git a/packages/specfact-backlog/module-package.yaml b/packages/specfact-backlog/module-package.yaml index d90a709..3c7f86d 100644 --- a/packages/specfact-backlog/module-package.yaml +++ b/packages/specfact-backlog/module-package.yaml @@ -1,5 +1,5 @@ name: nold-ai/specfact-backlog -version: 0.41.12 +version: 0.41.14 commands: - backlog tier: official @@ -17,5 +17,5 @@ schema_extensions: project_metadata: - backlog_core.backlog_config integrity: - checksum: sha256:dfce9f30ec710fe4686b3083aebe55f0211d61394509b81b84ef341833f555cf - signature: k+50QZUgW6+BdBtbv8SLa62KN9tFOCSLML323x8jlNQT4z/pbxcwncmIHvr5qfHLwBxAaIVgCQpC2ao0Kl13AQ== + checksum: sha256:edda19b7862d2fc6f4510d148b71e7f74e5d3ff18cc4852018b0912592729c58 + signature: eQ86/44q9ZKUkkNIv/HzyZ7Oc3QXPyPZLpFtoMMTF5QjWWbE1RFntJs/8BWKHniV23iJnRUBlBnm4YIP30UQAQ== diff --git a/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_agile.yaml b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_agile.yaml new file mode 100644 index 0000000..22e94ac --- /dev/null +++ b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_agile.yaml @@ -0,0 +1,24 @@ +# ADO Agile process template field mapping +# Optimized for Agile process template with User Stories, Story Points + +framework: agile + +# Field mappings: ADO field name -> canonical field name +field_mappings: + System.Description: description + System.AcceptanceCriteria: acceptance_criteria + Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative field name + Microsoft.VSTS.Scheduling.StoryPoints: story_points + Microsoft.VSTS.Common.BusinessValue: business_value + Microsoft.VSTS.Common.Priority: priority + System.WorkItemType: work_item_type + System.IterationPath: iteration + System.AreaPath: area + +# Work item type mappings: ADO work item type -> canonical work item type +work_item_type_mappings: + User Story: User Story + Bug: Bug + Task: Task + Epic: Epic + Feature: Feature diff --git a/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_custom.yaml b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_custom.yaml new file mode 100644 index 0000000..af58ac7 --- /dev/null +++ b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_custom.yaml @@ -0,0 +1,4 @@ +# Starter template for team-specific ADO field mappings (edited via map-fields / backlog flows) +framework: custom +field_mappings: {} +work_item_type_mappings: {} diff --git a/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_default.yaml b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_default.yaml new file mode 100644 index 0000000..74dd319 --- /dev/null +++ b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_default.yaml @@ -0,0 +1,24 @@ +# Default ADO field mapping template +# Generic mappings that work across most ADO process templates + +framework: default + +# Field mappings: ADO field name -> canonical field name +field_mappings: + System.Description: description + System.AcceptanceCriteria: acceptance_criteria + Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative field name + Microsoft.VSTS.Common.StoryPoints: story_points + Microsoft.VSTS.Scheduling.StoryPoints: story_points + Microsoft.VSTS.Common.BusinessValue: business_value + Microsoft.VSTS.Common.Priority: priority + System.WorkItemType: work_item_type + +# Work item type mappings: ADO work item type -> canonical work item type +work_item_type_mappings: + Product Backlog Item: User Story + User Story: User Story + Feature: Feature + Epic: Epic + Task: Task + Bug: Bug diff --git a/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_kanban.yaml b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_kanban.yaml new file mode 100644 index 0000000..4753282 --- /dev/null +++ b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_kanban.yaml @@ -0,0 +1,26 @@ +# ADO Kanban process template field mapping +# Optimized for Kanban workflow with work item types, state transitions, no sprint requirement + +framework: kanban + +# Field mappings: ADO field name -> canonical field name +field_mappings: + System.Description: description + System.AcceptanceCriteria: acceptance_criteria + Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative field name + Microsoft.VSTS.Common.Priority: priority + System.WorkItemType: work_item_type + System.State: state + System.AreaPath: area + # Kanban doesn't require story points, but may have them + Microsoft.VSTS.Scheduling.StoryPoints: story_points + Microsoft.VSTS.Common.StoryPoints: story_points + +# Work item type mappings: ADO work item type -> canonical work item type +# Kanban supports various work item types without strict hierarchy +work_item_type_mappings: + User Story: User Story + Task: Task + Bug: Bug + Feature: Feature + Epic: Epic diff --git a/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_safe.yaml b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_safe.yaml new file mode 100644 index 0000000..17c666f --- /dev/null +++ b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_safe.yaml @@ -0,0 +1,29 @@ +# ADO SAFe process template field mapping +# Optimized for SAFe process template with Epic → Feature → Story → Task hierarchy, +# Value Points, WSJF prioritization + +framework: safe + +# Field mappings: ADO field name -> canonical field name +field_mappings: + System.Description: description + System.AcceptanceCriteria: acceptance_criteria + Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative field name + Microsoft.VSTS.Scheduling.StoryPoints: story_points + Microsoft.VSTS.Common.BusinessValue: business_value + Microsoft.VSTS.Common.Priority: priority + System.WorkItemType: work_item_type + System.IterationPath: iteration + System.AreaPath: area + # SAFe-specific fields (if available) + Microsoft.VSTS.Common.ValueArea: value_points + Microsoft.VSTS.Common.Risk: priority + +# Work item type mappings: ADO work item type -> canonical work item type +# SAFe hierarchy: Epic → Feature → User Story → Task +work_item_type_mappings: + Epic: Epic + Feature: Feature + User Story: User Story + Task: Task + Bug: Bug diff --git a/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_scrum.yaml b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_scrum.yaml new file mode 100644 index 0000000..df055c5 --- /dev/null +++ b/packages/specfact-backlog/resources/templates/backlog/field_mappings/ado_scrum.yaml @@ -0,0 +1,24 @@ +# ADO Scrum process template field mapping +# Optimized for Scrum process template with Product Backlog Items, Story Points, Sprint tracking + +framework: scrum + +# Field mappings: ADO field name -> canonical field name +field_mappings: + System.Description: description + System.AcceptanceCriteria: acceptance_criteria + Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative field name + Microsoft.VSTS.Scheduling.StoryPoints: story_points + Microsoft.VSTS.Common.BusinessValue: business_value + Microsoft.VSTS.Common.Priority: priority + System.WorkItemType: work_item_type + System.IterationPath: iteration + System.AreaPath: area + +# Work item type mappings: ADO work item type -> canonical work item type +work_item_type_mappings: + Product Backlog Item: User Story + Bug: Bug + Task: Task + Impediment: Task + Epic: Epic diff --git a/packages/specfact-backlog/resources/templates/backlog/field_mappings/github_custom.yaml b/packages/specfact-backlog/resources/templates/backlog/field_mappings/github_custom.yaml new file mode 100644 index 0000000..0acafb9 --- /dev/null +++ b/packages/specfact-backlog/resources/templates/backlog/field_mappings/github_custom.yaml @@ -0,0 +1,25 @@ +# Starter GitHub hierarchy / type mapping seed (extended by map-fields and backlog flows) +type_mapping: + epic: epic + feature: feature + story: story + task: task + bug: bug +creation_hierarchy: + epic: [] + feature: [epic] + story: [feature, epic] + task: [story, feature] + bug: [story, feature, epic] + spike: [feature, epic] + custom: [epic, feature, story] +dependency_rules: + blocks: blocks + blocked_by: blocks + relates: relates_to +status_mapping: + open: todo + closed: done + todo: todo + in progress: in_progress + done: done diff --git a/packages/specfact-backlog/src/specfact_backlog/backlog/commands.py b/packages/specfact-backlog/src/specfact_backlog/backlog/commands.py index d8a5335..0dc53e5 100644 --- a/packages/specfact-backlog/src/specfact_backlog/backlog/commands.py +++ b/packages/specfact-backlog/src/specfact_backlog/backlog/commands.py @@ -48,6 +48,7 @@ from specfact_backlog.backlog.adapters.interface import BacklogAdapter from specfact_backlog.backlog.ai_refiner import BacklogAIRefiner from specfact_backlog.backlog.auth_commands import auth_app +from specfact_backlog.backlog.field_mapping_resources import load_ado_framework_template_config from specfact_backlog.backlog.filters import BacklogFilters from specfact_backlog.backlog.template_detector import TemplateDetector, get_effective_required_sections @@ -2110,47 +2111,6 @@ def _build_adapter_kwargs( return kwargs -@beartype -def _load_ado_framework_template_config(framework: str) -> dict[str, Any]: - """ - Load built-in ADO field mapping template config for a framework. - - Returns a dict with keys: framework, field_mappings, work_item_type_mappings. - Falls back to ado_default.yaml when framework-specific file is unavailable. - """ - normalized = (framework or "default").strip().lower() or "default" - candidates = [f"ado_{normalized}.yaml", "ado_default.yaml"] - - candidate_roots: list[Path] = [] - with contextlib.suppress(Exception): - from specfact_cli.utils.ide_setup import find_package_resources_path - - packaged = find_package_resources_path("specfact_cli", "resources/templates/backlog/field_mappings") - if packaged and packaged.exists(): - candidate_roots.append(packaged) - - repo_root = Path(__file__).parent.parent.parent.parent.parent.parent - candidate_roots.append(repo_root / "resources" / "templates" / "backlog" / "field_mappings") - - for root in candidate_roots: - if not root.exists(): - continue - for filename in candidates: - file_path = root / filename - if file_path.exists(): - with contextlib.suppress(Exception): - from specfact_backlog.backlog.mappers.template_config import FieldMappingConfig - - cfg = FieldMappingConfig.from_file(file_path) - return cfg.model_dump() - - return { - "framework": "default", - "field_mappings": {}, - "work_item_type_mappings": {}, - } - - def _extract_body_from_block(block: str) -> str: """ Extract **Body** content from a refined export block, handling nested fenced code. @@ -5418,7 +5378,7 @@ def _detect_ado_framework_from_work_item_types() -> str | None: console.print(f"[dim]Using ADO framework:[/dim] {selected_framework}") - framework_template = _load_ado_framework_template_config(selected_framework) + framework_template = load_ado_framework_template_config(selected_framework) framework_field_mappings = framework_template.get("field_mappings", {}) framework_work_item_type_mappings = framework_template.get("work_item_type_mappings", {}) diff --git a/packages/specfact-backlog/src/specfact_backlog/backlog/field_mapping_resources.py b/packages/specfact-backlog/src/specfact_backlog/backlog/field_mapping_resources.py new file mode 100644 index 0000000..335333f --- /dev/null +++ b/packages/specfact-backlog/src/specfact_backlog/backlog/field_mapping_resources.py @@ -0,0 +1,62 @@ +"""Locate packaged ADO field-mapping template YAML for the backlog bundle.""" + +from __future__ import annotations + +import contextlib +from pathlib import Path +from typing import Any + +from beartype import beartype +from icontract import ensure, require +from specfact_cli.utils.ide_setup import find_package_resources_path + +from specfact_backlog.backlog.mappers.template_config import FieldMappingConfig + + +@beartype +@require(lambda framework: isinstance(framework, str), "framework must be str") +@ensure(lambda result: isinstance(result, dict), "Must return dict") +def load_ado_framework_template_config(framework: str) -> dict[str, Any]: + """ + Load built-in ADO field mapping template config for a framework. + + Returns a dict with keys: framework, field_mappings, work_item_type_mappings. + Falls back to ado_default.yaml when framework-specific file is unavailable. + """ + normalized = (framework or "default").strip().lower() or "default" + candidates = [f"ado_{normalized}.yaml", "ado_default.yaml"] + + candidate_roots: list[Path] = [] + with contextlib.suppress(Exception): + backlog_packaged = find_package_resources_path( + "specfact_backlog", + "resources/templates/backlog/field_mappings", + ) + if backlog_packaged and backlog_packaged.exists(): + candidate_roots.append(backlog_packaged) + + core_packaged = find_package_resources_path( + "specfact_cli", + "resources/templates/backlog/field_mappings", + ) + if core_packaged and core_packaged.exists(): + candidate_roots.append(core_packaged) + + module_root = Path(__file__).resolve().parents[3] + candidate_roots.append(module_root / "resources" / "templates" / "backlog" / "field_mappings") + + for root in candidate_roots: + if not root.exists(): + continue + for filename in candidates: + file_path = root / filename + if file_path.exists(): + with contextlib.suppress(Exception): + cfg = FieldMappingConfig.from_file(file_path) + return cfg.model_dump() + + return { + "framework": "default", + "field_mappings": {}, + "work_item_type_mappings": {}, + } diff --git a/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_agile.yaml b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_agile.yaml new file mode 100644 index 0000000..22e94ac --- /dev/null +++ b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_agile.yaml @@ -0,0 +1,24 @@ +# ADO Agile process template field mapping +# Optimized for Agile process template with User Stories, Story Points + +framework: agile + +# Field mappings: ADO field name -> canonical field name +field_mappings: + System.Description: description + System.AcceptanceCriteria: acceptance_criteria + Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative field name + Microsoft.VSTS.Scheduling.StoryPoints: story_points + Microsoft.VSTS.Common.BusinessValue: business_value + Microsoft.VSTS.Common.Priority: priority + System.WorkItemType: work_item_type + System.IterationPath: iteration + System.AreaPath: area + +# Work item type mappings: ADO work item type -> canonical work item type +work_item_type_mappings: + User Story: User Story + Bug: Bug + Task: Task + Epic: Epic + Feature: Feature diff --git a/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_custom.yaml b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_custom.yaml new file mode 100644 index 0000000..af58ac7 --- /dev/null +++ b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_custom.yaml @@ -0,0 +1,4 @@ +# Starter template for team-specific ADO field mappings (edited via map-fields / backlog flows) +framework: custom +field_mappings: {} +work_item_type_mappings: {} diff --git a/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_default.yaml b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_default.yaml new file mode 100644 index 0000000..74dd319 --- /dev/null +++ b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_default.yaml @@ -0,0 +1,24 @@ +# Default ADO field mapping template +# Generic mappings that work across most ADO process templates + +framework: default + +# Field mappings: ADO field name -> canonical field name +field_mappings: + System.Description: description + System.AcceptanceCriteria: acceptance_criteria + Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative field name + Microsoft.VSTS.Common.StoryPoints: story_points + Microsoft.VSTS.Scheduling.StoryPoints: story_points + Microsoft.VSTS.Common.BusinessValue: business_value + Microsoft.VSTS.Common.Priority: priority + System.WorkItemType: work_item_type + +# Work item type mappings: ADO work item type -> canonical work item type +work_item_type_mappings: + Product Backlog Item: User Story + User Story: User Story + Feature: Feature + Epic: Epic + Task: Task + Bug: Bug diff --git a/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_kanban.yaml b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_kanban.yaml new file mode 100644 index 0000000..4753282 --- /dev/null +++ b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_kanban.yaml @@ -0,0 +1,26 @@ +# ADO Kanban process template field mapping +# Optimized for Kanban workflow with work item types, state transitions, no sprint requirement + +framework: kanban + +# Field mappings: ADO field name -> canonical field name +field_mappings: + System.Description: description + System.AcceptanceCriteria: acceptance_criteria + Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative field name + Microsoft.VSTS.Common.Priority: priority + System.WorkItemType: work_item_type + System.State: state + System.AreaPath: area + # Kanban doesn't require story points, but may have them + Microsoft.VSTS.Scheduling.StoryPoints: story_points + Microsoft.VSTS.Common.StoryPoints: story_points + +# Work item type mappings: ADO work item type -> canonical work item type +# Kanban supports various work item types without strict hierarchy +work_item_type_mappings: + User Story: User Story + Task: Task + Bug: Bug + Feature: Feature + Epic: Epic diff --git a/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_safe.yaml b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_safe.yaml new file mode 100644 index 0000000..17c666f --- /dev/null +++ b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_safe.yaml @@ -0,0 +1,29 @@ +# ADO SAFe process template field mapping +# Optimized for SAFe process template with Epic → Feature → Story → Task hierarchy, +# Value Points, WSJF prioritization + +framework: safe + +# Field mappings: ADO field name -> canonical field name +field_mappings: + System.Description: description + System.AcceptanceCriteria: acceptance_criteria + Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative field name + Microsoft.VSTS.Scheduling.StoryPoints: story_points + Microsoft.VSTS.Common.BusinessValue: business_value + Microsoft.VSTS.Common.Priority: priority + System.WorkItemType: work_item_type + System.IterationPath: iteration + System.AreaPath: area + # SAFe-specific fields (if available) + Microsoft.VSTS.Common.ValueArea: value_points + Microsoft.VSTS.Common.Risk: priority + +# Work item type mappings: ADO work item type -> canonical work item type +# SAFe hierarchy: Epic → Feature → User Story → Task +work_item_type_mappings: + Epic: Epic + Feature: Feature + User Story: User Story + Task: Task + Bug: Bug diff --git a/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_scrum.yaml b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_scrum.yaml new file mode 100644 index 0000000..df055c5 --- /dev/null +++ b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/ado_scrum.yaml @@ -0,0 +1,24 @@ +# ADO Scrum process template field mapping +# Optimized for Scrum process template with Product Backlog Items, Story Points, Sprint tracking + +framework: scrum + +# Field mappings: ADO field name -> canonical field name +field_mappings: + System.Description: description + System.AcceptanceCriteria: acceptance_criteria + Microsoft.VSTS.Common.AcceptanceCriteria: acceptance_criteria # Alternative field name + Microsoft.VSTS.Scheduling.StoryPoints: story_points + Microsoft.VSTS.Common.BusinessValue: business_value + Microsoft.VSTS.Common.Priority: priority + System.WorkItemType: work_item_type + System.IterationPath: iteration + System.AreaPath: area + +# Work item type mappings: ADO work item type -> canonical work item type +work_item_type_mappings: + Product Backlog Item: User Story + Bug: Bug + Task: Task + Impediment: Task + Epic: Epic diff --git a/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/github_custom.yaml b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/github_custom.yaml new file mode 100644 index 0000000..0acafb9 --- /dev/null +++ b/packages/specfact-backlog/src/specfact_backlog/resources/templates/backlog/field_mappings/github_custom.yaml @@ -0,0 +1,25 @@ +# Starter GitHub hierarchy / type mapping seed (extended by map-fields and backlog flows) +type_mapping: + epic: epic + feature: feature + story: story + task: task + bug: bug +creation_hierarchy: + epic: [] + feature: [epic] + story: [feature, epic] + task: [story, feature] + bug: [story, feature, epic] + spike: [feature, epic] + custom: [epic, feature, story] +dependency_rules: + blocks: blocks + blocked_by: blocks + relates: relates_to +status_mapping: + open: todo + closed: done + todo: todo + in progress: in_progress + done: done diff --git a/packages/specfact-codebase/module-package.yaml b/packages/specfact-codebase/module-package.yaml index 8da091d..abab82f 100644 --- a/packages/specfact-codebase/module-package.yaml +++ b/packages/specfact-codebase/module-package.yaml @@ -1,5 +1,5 @@ name: nold-ai/specfact-codebase -version: 0.41.1 +version: 0.41.3 commands: - code tier: official @@ -13,5 +13,5 @@ description: Official SpecFact codebase bundle package. category: codebase bundle_group_command: code integrity: - checksum: sha256:2d1ef419e6e185fe94a49269af3b8d26f48b58e5f9b085a9553fa3dfc58bd7a3 - signature: gCs8+jE2i2DN7fXZ/Wjgv0iq417/C33vfJea6jh8k71EY7ldOL1c/VAkJdpYkm4XfLe6fs3VwOwMq3NC85MGAA== + checksum: sha256:bdd12151c2ba736e254552adf472d7e217036dfe7fdf661e90204e74be44a2da + signature: VMeonMTm8x/ZFn8CBzr6mcZHi0WcldLMiAQl1Ihhs6DuwK+cF1BI/U+G05j21rbdPE9+5qZyZ5QZVEj4V3yECQ== diff --git a/packages/specfact-codebase/resources/prompts/shared/cli-enforcement.md b/packages/specfact-codebase/resources/prompts/shared/cli-enforcement.md new file mode 100644 index 0000000..b8aab9a --- /dev/null +++ b/packages/specfact-codebase/resources/prompts/shared/cli-enforcement.md @@ -0,0 +1,119 @@ +# CLI Usage Enforcement Rules + +## Core Principle + +**ALWAYS use SpecFact CLI commands. Never create artifacts directly.** + +## CLI vs LLM Capabilities + +### CLI-Only Operations (CI/CD Mode - No LLM Required) + +The CLI can perform these operations **without LLM**: + +- ✅ Tool execution (ruff, pylint, basedpyright, mypy, semgrep, specmatic) +- ✅ Bundle management (create, load, save, validate structure) +- ✅ Metadata management (timestamps, hashes, telemetry) +- ✅ Planning operations (init, add-feature, add-story, update-idea, update-feature) +- ✅ AST/Semgrep-based analysis (code structure, patterns, relationships) +- ✅ Specmatic validation (OpenAPI/AsyncAPI contract validation) +- ✅ Format validation (YAML/JSON schema compliance) +- ✅ Source tracking and drift detection + +**CRITICAL LIMITATIONS**: + +- ❌ **CANNOT generate code** - No LLM available in CLI-only mode +- ❌ **CANNOT do reasoning** - No semantic understanding without LLM + +### LLM-Required Operations (AI IDE Mode - Via Slash Prompts) + +These operations **require LLM** and are only available via AI IDE slash prompts: + +- ✅ Code generation (requires LLM reasoning) +- ✅ Code enhancement (contracts, refactoring, improvements) +- ✅ Semantic understanding (business logic, context, priorities) +- ✅ Plan enrichment (missing features, confidence adjustments, business context) +- ✅ Code reasoning (why decisions were made, trade-offs, constraints) + +**Access**: Only available via AI IDE slash prompts (Cursor, CoPilot, etc.) +**Pattern**: Slash prompt → LLM generates → CLI validates → Apply if valid + +## LLM Grounding Rules + +- Treat CLI artifacts as the source of truth for keys, structure, and metadata. +- Scan the codebase only when asked to infer missing behavior/context or explain deviations; respect `--entry-point` scope when provided. +- Use codebase findings to propose updates via CLI (enrichment report, plan update commands), never to rewrite artifacts directly. + +## Rules + +1. **Execute CLI First**: Always run CLI commands before any analysis +2. **Use CLI for Writes**: All write operations must go through CLI +3. **Read for Display Only**: Use file reading tools for display/analysis only +4. **Never Modify .specfact/**: Do not create/modify files in `.specfact/` directly +5. **Never Bypass Validation**: CLI ensures schema compliance and metadata +6. **Code Generation Requires LLM**: Code generation is only possible via AI IDE slash prompts, not CLI-only + +## Standard Validation Loop Pattern (For LLM-Generated Code) + +When generating or enhancing code via LLM, **ALWAYS** follow this pattern: + +```text +1. CLI Prompt Generation (Required) + ↓ + CLI generates structured prompt → saved to .specfact/prompts/ + (e.g., `generate contracts-prompt`, future: `generate code-prompt`) + +2. LLM Execution (Required - AI IDE Only) + ↓ + LLM reads prompt → generates enhanced code → writes to TEMPORARY file + (NEVER writes directly to original artifacts) + Pattern: `enhanced_.py` or `generated_.py` + +3. CLI Validation Loop (Required, up to N retries) + ↓ + CLI validates temp file with all relevant tools: + - Syntax validation (py_compile) + - File size check (must be >= original) + - AST structure comparison (preserve functions/classes) + - Contract imports verification + - Code quality checks (ruff, pylint, basedpyright, mypy) + - Test execution (contract-test, pytest) + ↓ + If validation fails: + - CLI provides detailed error feedback + - LLM fixes issues in temp file + - Re-validate (max 3 attempts) + ↓ + If validation succeeds: + - CLI applies changes to original file + - CLI removes temporary file + - CLI updates metadata/telemetry +``` + +**This pattern must be used for**: + +- ✅ Contract enhancement (`generate contracts-prompt` / `contracts-apply`) - Already implemented +- ⏳ Code generation (future: `generate code-prompt` / `code-apply`) - Needs implementation +- ⏳ Plan enrichment (future: `plan enrich-prompt` / `enrich-apply`) - Needs implementation +- ⏳ Any LLM-enhanced artifact modification - Needs implementation + +## What Happens If You Don't Follow + +- ❌ Artifacts may not match CLI schema versions +- ❌ Missing metadata and telemetry +- ❌ Format inconsistencies +- ❌ Validation failures +- ❌ Works only in Copilot mode, fails in CI/CD +- ❌ Code generation attempts in CLI-only mode will fail (no LLM available) + +## Available CLI Commands + +- `specfact plan init ` - Initialize project bundle +- `specfact plan select ` - Set active plan (used as default for other commands) +- `specfact code import [] --repo ` - Import from codebase (uses active plan if bundle not specified) +- `specfact plan review []` - Review plan (uses active plan if bundle not specified) +- `specfact plan harden []` - Create SDD manifest (uses active plan if bundle not specified) +- `specfact enforce sdd []` - Validate SDD (uses active plan if bundle not specified) +- `specfact sync bridge --adapter --repo ` - Sync with external tools +- See [Command Reference](../../docs/reference/commands.md) for full list + +**Note**: Most commands now support active plan fallback. If `--bundle` is not specified, commands automatically use the active plan set via `plan select`. This improves workflow efficiency in AI IDE environments. diff --git a/packages/specfact-codebase/resources/prompts/specfact.01-import.md b/packages/specfact-codebase/resources/prompts/specfact.01-import.md new file mode 100644 index 0000000..388f628 --- /dev/null +++ b/packages/specfact-codebase/resources/prompts/specfact.01-import.md @@ -0,0 +1,263 @@ +--- +description: Import codebase → plan bundle. CLI extracts routes/schemas/relationships. LLM enriches with context. +--- + +# SpecFact Import Command + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Purpose + +Import codebase → plan bundle. CLI extracts routes/schemas/relationships/contracts. LLM enriches context/"why"/completeness. + +## Parameters + +**Target/Input**: `--bundle NAME` (optional, defaults to active plan), `--repo PATH`, `--entry-point PATH`, `--enrichment PATH` +**Output/Results**: `--report PATH` +**Behavior/Options**: `--shadow-only`, `--enrich-for-speckit/--no-enrich-for-speckit` (default: enabled, uses PlanEnricher for consistent enrichment) +**Advanced/Configuration**: `--confidence FLOAT` (0.0-1.0), `--key-format FORMAT` (classname|sequential) + +## Workflow + +1. **Execute CLI**: `specfact [GLOBAL OPTIONS] import from-code [] --repo [options]` + - CLI extracts: routes (FastAPI/Flask/Django), schemas (Pydantic), relationships, contracts (OpenAPI scaffolds), source tracking + - Uses active plan if bundle not specified + - Note: `--no-interactive` is a global option and must appear before the subcommand (e.g., `specfact --no-interactive import from-code ...`). + - **Auto-enrichment enabled by default**: Automatically enhances vague acceptance criteria, incomplete requirements, and generic tasks using PlanEnricher (same logic as `plan review --auto-enrich`) + - Use `--no-enrich-for-speckit` to disable auto-enrichment + - **Contract extraction**: OpenAPI contracts are extracted automatically **only** for features with `source_tracking.implementation_files` and detectable API endpoints (FastAPI/Flask patterns). For enrichment-added features or Django apps, use `specfact contract init` after enrichment (see Phase 4) + +2. **LLM Enrichment** (Copilot-only, before applying `--enrichment`): + - Read CLI artifacts: `.specfact/projects//enrichment_context.md`, feature YAMLs, contract scaffolds, and brownfield reports + - Scan the codebase within `--entry-point` (and adjacent modules) to identify missing features, dependencies, and behavior; do **not** rely solely on AST-derived YAML + - Compare code findings vs CLI artifacts, then add missing features/stories, reasoning, and acceptance criteria (each added feature must include at least one story) + - Save the enrichment report to `.specfact/projects//reports/enrichment/-.enrichment.md` (bundle-specific, Phase 8.5) + - **CRITICAL**: Follow the exact enrichment report format (see "Enrichment Report Format" section below) to ensure successful parsing + +3. **Present**: Bundle location, report path, summary (features/stories/contracts/relationships) + +## CLI Enforcement + +**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details. + +**Rules:** + +- Execute CLI first - never create artifacts directly +- Use the global `--no-interactive` flag in CI/CD environments (must appear before the subcommand) +- Never modify `.specfact/` directly +- Use CLI output as grounding for validation +- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only) + +## Dual-Stack Workflow (Copilot Mode) + +When in copilot mode, follow this three-phase workflow: + +### Phase 1: CLI Grounding (REQUIRED) + +```bash +# Execute CLI to get structured output +specfact --no-interactive import from-code [] --repo +``` + +**Capture**: + +- CLI-generated artifacts (plan bundles, reports) +- Metadata (timestamps, confidence scores) +- Telemetry (execution time, file counts) + +### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only) + +**Purpose**: Add semantic understanding to CLI output + +**What to do**: + +- Read CLI-generated artifacts (use file reading tools for display only) +- Scan the codebase within `--entry-point` for missing features/behavior and compare against CLI artifacts +- Identify missing features/stories and add reasoning/acceptance criteria (no direct edits to `.specfact/`) +- Suggest confidence adjustments and extract business context +- **CRITICAL**: Generate enrichment report in the exact format specified below (see "Enrichment Report Format" section) + +**What NOT to do**: + +- ❌ Create YAML/JSON artifacts directly +- ❌ Modify CLI artifacts directly (use CLI commands to update) +- ❌ Bypass CLI validation +- ❌ Write to `.specfact/` folder directly (always use CLI) +- ❌ Use direct file manipulation tools for writing (use CLI commands) +- ❌ Deviate from the enrichment report format (will cause parsing failures) + +**Output**: Generate enrichment report (Markdown) saved to `.specfact/projects//reports/enrichment/` (bundle-specific, Phase 8.5) + +**Enrichment Report Format** (REQUIRED for successful parsing): + +The enrichment parser expects a specific Markdown format. Follow this structure exactly: + +```markdown +# [Bundle Name] Enrichment Report + +**Date**: YYYY-MM-DDTHH:MM:SS +**Bundle**: + +--- + +## Missing Features + +1. **Feature Title** (Key: FEATURE-XXX) + - Confidence: 0.85 + - Outcomes: outcome1, outcome2, outcome3 + - Stories: + 1. Story title here + - Acceptance: criterion1, criterion2, criterion3 + 2. Another story title + - Acceptance: criterion1, criterion2 + +2. **Another Feature** (Key: FEATURE-YYY) + - Confidence: 0.80 + - Outcomes: outcome1, outcome2 + - Stories: + 1. Story title + - Acceptance: criterion1, criterion2, criterion3 + +## Confidence Adjustments + +- FEATURE-EXISTING-KEY: 0.90 (reason: improved understanding after code review) + +## Business Context + +- Priority: High priority feature for core functionality +- Constraint: Must support both REST and GraphQL APIs +- Risk: Potential performance issues with large datasets +``` + +**Format Requirements**: + +1. **Section Header**: Must use `## Missing Features` (case-insensitive, but prefer this exact format) +2. **Feature Format**: + - Numbered list: `1. **Feature Title** (Key: FEATURE-XXX)` + - **Bold title** is required (use `**Title**`) + - **Key in parentheses**: `(Key: FEATURE-XXX)` - must be uppercase, alphanumeric with hyphens/underscores + - Fields on separate lines with `-` prefix: + - `- Confidence: 0.85` (float between 0.0-1.0) + - `- Outcomes: comma-separated or line-separated list` + - `- Stories:` (required - each feature must have at least one story) +3. **Stories Format**: + - Numbered list under `Stories:` section: `1. Story title` + - **Indentation**: Stories must be indented (2-4 spaces) under the feature + - **Acceptance Criteria**: `- Acceptance: criterion1, criterion2, criterion3` + - Can be comma-separated on one line + - Or multi-line (each criterion on new line) + - Must start with `- Acceptance:` +4. **Optional Sections**: + - `## Confidence Adjustments`: List existing features with confidence updates + - `## Business Context`: Priorities, constraints, risks (bullet points) +5. **File Naming**: `-.enrichment.md` (e.g., `djangogoat-2025-12-23T23-50-00.enrichment.md`) + +**Example** (working format): + +```markdown +## Missing Features + +1. **User Authentication** (Key: FEATURE-USER-AUTHENTICATION) + - Confidence: 0.85 + - Outcomes: User registration, login, profile management + - Stories: + 1. User can sign up for new account + - Acceptance: sign_up view processes POST requests, creates User automatically, user is logged in after signup, redirects to profile page + 2. User can log in with credentials + - Acceptance: log_in view authenticates username/password, on success user is logged in and redirected, on failure error message is displayed +``` + +**Common Mistakes to Avoid**: + +- ❌ Missing `(Key: FEATURE-XXX)` - parser needs this to identify features +- ❌ Missing `Stories:` section - every feature must have at least one story +- ❌ Stories not indented - parser expects indented numbered lists +- ❌ Missing `- Acceptance:` prefix - acceptance criteria won't be parsed +- ❌ Using bullet points (`-`) instead of numbers (`1.`) for stories +- ❌ Feature title not in bold (`**Title**`) - parser may not extract title correctly + +### Phase 3: CLI Artifact Creation (REQUIRED) + +```bash +# Use enrichment to update plan via CLI +specfact --no-interactive import from-code [] --repo --enrichment +``` + +**Result**: Final artifacts are CLI-generated with validated enrichments + +**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code)) + +### Phase 4: OpenAPI Contract Generation (REQUIRED for Sidecar Validation) + +**When contracts are generated automatically:** + +The `import from-code` command attempts to extract OpenAPI contracts automatically, but **only if**: + +1. Features have `source_tracking.implementation_files` (AST-detected features) +2. The OpenAPI extractor finds API endpoints (FastAPI/Flask patterns like `@app.get`, `@router.post`, `@app.route`) + +**When contracts are NOT generated:** + +Contracts are **NOT** generated automatically when: + +- Features were added via enrichment (no `source_tracking.implementation_files`) +- Django applications (Django `path()` patterns are not detected by the extractor) +- Features without API endpoints (models, utilities, middleware, etc.) +- Framework SDKs or libraries without web endpoints + +**How to generate contracts manually:** + +For features that need OpenAPI contracts (e.g., for sidecar validation with CrossHair), use: + +```bash +# Generate contract for a single feature +specfact --no-interactive contract init --bundle --feature --repo + +# Example: Generate contracts for all enrichment-added features +specfact --no-interactive contract init --bundle djangogoat-validation --feature FEATURE-USER-AUTHENTICATION --repo . +specfact --no-interactive contract init --bundle djangogoat-validation --feature FEATURE-NOTES-MANAGEMENT --repo . +# ... repeat for each feature that needs a contract +``` + +**When to apply contract generation:** + +- **After Phase 3** (enrichment applied): Check which features have contracts in `.specfact/projects//contracts/` +- **Before sidecar validation**: All features that will be analyzed by CrossHair/Specmatic need OpenAPI contracts +- **For Django apps**: Always generate contracts manually after enrichment, as Django URL patterns are not auto-detected + +**Verification:** + +```bash +# Check which features have contracts +ls .specfact/projects//contracts/*.yaml + +# Compare with total features +ls .specfact/projects//features/*.yaml +``` + +If the contract count is less than the feature count, generate missing contracts using `contract init`. + +## Expected Output + +**Success**: Bundle location, report path, summary (features/stories/contracts/relationships) +**Error**: Missing bundle name or bundle already exists + +## Common Patterns + +```bash +/specfact.01-import --repo . # Uses active plan, auto-enrichment enabled by default +/specfact.01-import --bundle legacy-api --repo . # Auto-enrichment enabled +/specfact.01-import --repo . --no-enrich-for-speckit # Disable auto-enrichment +/specfact.01-import --repo . --entry-point src/auth/ +/specfact.01-import --repo . --enrichment report.md +``` + +## Context + +{ARGS} diff --git a/packages/specfact-codebase/resources/prompts/specfact.validate.md b/packages/specfact-codebase/resources/prompts/specfact.validate.md new file mode 100644 index 0000000..2548a8e --- /dev/null +++ b/packages/specfact-codebase/resources/prompts/specfact.validate.md @@ -0,0 +1,166 @@ +--- +description: Run full validation suite for reproducibility and contract compliance. +--- + +# SpecFact Validate Command + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Purpose + +Run full validation suite for reproducibility and contract compliance. Executes linting, type checking, contract exploration, and tests. + +**When to use:** Before committing, in CI/CD pipelines, validating contract compliance. + +**Quick:** `/specfact.validate --repo .` or `/specfact.validate --verbose --budget 120` + +## Parameters + +### Target/Input + +- `--repo PATH` - Path to repository. Default: current directory (.) + +### Output/Results + +- `--out PATH` - Output report path. Default: bundle-specific .specfact/projects//reports/enforcement/report-.yaml (Phase 8.5), or global .specfact/reports/enforcement/ if no bundle context + +### Behavior/Options + +- `--verbose` - Verbose output. Default: False +- `--fail-fast` - Stop on first failure. Default: False +- `--fix` - Apply auto-fixes where available. Default: False + +### Advanced/Configuration + +- `--budget SECONDS` - Time budget in seconds. Default: 120 (must be > 0) + +## Workflow + +### Step 1: Parse Arguments + +- Extract repository path (default: current directory) +- Extract validation options (verbose, fail-fast, fix, budget) + +### Step 2: Execute CLI + +```bash +specfact repro --repo [--verbose] [--fail-fast] [--fix] [--budget ] [--out ] +``` + +### Step 3: Present Results + +- Display validation summary table +- Show check results (pass/fail/timeout) +- Present report location +- Indicate exit code + +## CLI Enforcement + +**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details. + +**Rules:** + +- Execute CLI first - never create artifacts directly +- Use `--no-interactive` flag in CI/CD environments +- Never modify `.specfact/` directly +- Use CLI output as grounding for validation results +- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only) + +## Dual-Stack Workflow (Copilot Mode) + +When in copilot mode, follow this three-phase workflow: + +### Phase 1: CLI Grounding (REQUIRED) + +```bash +# Execute CLI to get structured output +specfact repro --repo [options] --no-interactive +``` + +**Capture**: + +- CLI-generated validation report +- Check results (pass/fail/timeout) +- Exit code + +### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only) + +**Purpose**: Add semantic understanding to validation results + +**What to do**: + +- Read CLI-generated validation report (use file reading tools for display only) +- Treat the validation report as the source of truth; scan codebase only to explain failures +- Research codebase for context on failures +- Suggest fixes for validation failures + +**What NOT to do**: + +- ❌ Create YAML/JSON artifacts directly +- ❌ Modify CLI artifacts directly (use CLI commands to update) +- ❌ Bypass CLI validation +- ❌ Write to `.specfact/` folder directly (always use CLI) + +**Output**: Generate fix suggestions report (Markdown) + +### Phase 3: CLI Artifact Creation (REQUIRED) + +```bash +# Apply fixes via CLI commands, then re-validate +specfact plan update-feature [--bundle ] [options] --no-interactive +specfact repro --repo --no-interactive +``` + +**Result**: Final artifacts are CLI-generated with validated fixes + +**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code)) + +## Expected Output + +### Success + +```text +✓ All validations passed! + +Check Summary: + Lint (ruff) ✓ Passed + Async Patterns ✓ Passed + Type Checking ✓ Passed + Contract Exploration ✓ Passed + Property Tests ✓ Passed + Smoke Tests ✓ Passed + +Report saved to: .specfact/projects//reports/enforcement/report-2025-11-26T10-30-00.yaml +``` + +### Failure + +```text +✗ Some validations failed + +Check Summary: + Lint (ruff) ✓ Passed + Async Patterns ✗ Failed (2 issues) + Type Checking ✓ Passed + ... +``` + +## Common Patterns + +```bash +/specfact.validate --repo . +/specfact.validate --verbose +/specfact.validate --fix +/specfact.validate --fail-fast +/specfact.validate --budget 300 +``` + +## Context + +{ARGS} diff --git a/packages/specfact-govern/module-package.yaml b/packages/specfact-govern/module-package.yaml index ddc356e..d222e2a 100644 --- a/packages/specfact-govern/module-package.yaml +++ b/packages/specfact-govern/module-package.yaml @@ -1,5 +1,5 @@ name: nold-ai/specfact-govern -version: 0.40.17 +version: 0.40.19 commands: - govern tier: official @@ -13,5 +13,5 @@ description: Official SpecFact governance bundle package. category: govern bundle_group_command: govern integrity: - checksum: sha256:84e5bc023345713ae31aac362035d791c5f1edd96abd3b86d86666767d921f16 - signature: Fd++Hwz+TJbB2OlpWoI2OWJlQFvGFRFkj8Ph1ko1pWKn6bot3tMQxlnZfPfpTW7sBxqwRiviq8ocR6QJQpcFDQ== + checksum: sha256:cc214acd8e184ec36380eccb86ee0a8fe550e125209f4f461e03393a7886f203 + signature: N90cvb+lukJwUwGyVoj8ofmO8N3unlE13PQ5hYhMaDBdYQVMSY/9OL9TC8RLF+0LBSsRJ2IQ00188ZXRZWi1BA== diff --git a/packages/specfact-govern/resources/prompts/shared/cli-enforcement.md b/packages/specfact-govern/resources/prompts/shared/cli-enforcement.md new file mode 100644 index 0000000..b8aab9a --- /dev/null +++ b/packages/specfact-govern/resources/prompts/shared/cli-enforcement.md @@ -0,0 +1,119 @@ +# CLI Usage Enforcement Rules + +## Core Principle + +**ALWAYS use SpecFact CLI commands. Never create artifacts directly.** + +## CLI vs LLM Capabilities + +### CLI-Only Operations (CI/CD Mode - No LLM Required) + +The CLI can perform these operations **without LLM**: + +- ✅ Tool execution (ruff, pylint, basedpyright, mypy, semgrep, specmatic) +- ✅ Bundle management (create, load, save, validate structure) +- ✅ Metadata management (timestamps, hashes, telemetry) +- ✅ Planning operations (init, add-feature, add-story, update-idea, update-feature) +- ✅ AST/Semgrep-based analysis (code structure, patterns, relationships) +- ✅ Specmatic validation (OpenAPI/AsyncAPI contract validation) +- ✅ Format validation (YAML/JSON schema compliance) +- ✅ Source tracking and drift detection + +**CRITICAL LIMITATIONS**: + +- ❌ **CANNOT generate code** - No LLM available in CLI-only mode +- ❌ **CANNOT do reasoning** - No semantic understanding without LLM + +### LLM-Required Operations (AI IDE Mode - Via Slash Prompts) + +These operations **require LLM** and are only available via AI IDE slash prompts: + +- ✅ Code generation (requires LLM reasoning) +- ✅ Code enhancement (contracts, refactoring, improvements) +- ✅ Semantic understanding (business logic, context, priorities) +- ✅ Plan enrichment (missing features, confidence adjustments, business context) +- ✅ Code reasoning (why decisions were made, trade-offs, constraints) + +**Access**: Only available via AI IDE slash prompts (Cursor, CoPilot, etc.) +**Pattern**: Slash prompt → LLM generates → CLI validates → Apply if valid + +## LLM Grounding Rules + +- Treat CLI artifacts as the source of truth for keys, structure, and metadata. +- Scan the codebase only when asked to infer missing behavior/context or explain deviations; respect `--entry-point` scope when provided. +- Use codebase findings to propose updates via CLI (enrichment report, plan update commands), never to rewrite artifacts directly. + +## Rules + +1. **Execute CLI First**: Always run CLI commands before any analysis +2. **Use CLI for Writes**: All write operations must go through CLI +3. **Read for Display Only**: Use file reading tools for display/analysis only +4. **Never Modify .specfact/**: Do not create/modify files in `.specfact/` directly +5. **Never Bypass Validation**: CLI ensures schema compliance and metadata +6. **Code Generation Requires LLM**: Code generation is only possible via AI IDE slash prompts, not CLI-only + +## Standard Validation Loop Pattern (For LLM-Generated Code) + +When generating or enhancing code via LLM, **ALWAYS** follow this pattern: + +```text +1. CLI Prompt Generation (Required) + ↓ + CLI generates structured prompt → saved to .specfact/prompts/ + (e.g., `generate contracts-prompt`, future: `generate code-prompt`) + +2. LLM Execution (Required - AI IDE Only) + ↓ + LLM reads prompt → generates enhanced code → writes to TEMPORARY file + (NEVER writes directly to original artifacts) + Pattern: `enhanced_.py` or `generated_.py` + +3. CLI Validation Loop (Required, up to N retries) + ↓ + CLI validates temp file with all relevant tools: + - Syntax validation (py_compile) + - File size check (must be >= original) + - AST structure comparison (preserve functions/classes) + - Contract imports verification + - Code quality checks (ruff, pylint, basedpyright, mypy) + - Test execution (contract-test, pytest) + ↓ + If validation fails: + - CLI provides detailed error feedback + - LLM fixes issues in temp file + - Re-validate (max 3 attempts) + ↓ + If validation succeeds: + - CLI applies changes to original file + - CLI removes temporary file + - CLI updates metadata/telemetry +``` + +**This pattern must be used for**: + +- ✅ Contract enhancement (`generate contracts-prompt` / `contracts-apply`) - Already implemented +- ⏳ Code generation (future: `generate code-prompt` / `code-apply`) - Needs implementation +- ⏳ Plan enrichment (future: `plan enrich-prompt` / `enrich-apply`) - Needs implementation +- ⏳ Any LLM-enhanced artifact modification - Needs implementation + +## What Happens If You Don't Follow + +- ❌ Artifacts may not match CLI schema versions +- ❌ Missing metadata and telemetry +- ❌ Format inconsistencies +- ❌ Validation failures +- ❌ Works only in Copilot mode, fails in CI/CD +- ❌ Code generation attempts in CLI-only mode will fail (no LLM available) + +## Available CLI Commands + +- `specfact plan init ` - Initialize project bundle +- `specfact plan select ` - Set active plan (used as default for other commands) +- `specfact code import [] --repo ` - Import from codebase (uses active plan if bundle not specified) +- `specfact plan review []` - Review plan (uses active plan if bundle not specified) +- `specfact plan harden []` - Create SDD manifest (uses active plan if bundle not specified) +- `specfact enforce sdd []` - Validate SDD (uses active plan if bundle not specified) +- `specfact sync bridge --adapter --repo ` - Sync with external tools +- See [Command Reference](../../docs/reference/commands.md) for full list + +**Note**: Most commands now support active plan fallback. If `--bundle` is not specified, commands automatically use the active plan set via `plan select`. This improves workflow efficiency in AI IDE environments. diff --git a/packages/specfact-govern/resources/prompts/specfact.05-enforce.md b/packages/specfact-govern/resources/prompts/specfact.05-enforce.md new file mode 100644 index 0000000..0d0c227 --- /dev/null +++ b/packages/specfact-govern/resources/prompts/specfact.05-enforce.md @@ -0,0 +1,166 @@ +--- +description: Validate SDD manifest against project bundle and contracts, check coverage thresholds. +--- + +# SpecFact SDD Enforcement Command + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Purpose + +Validate SDD manifest against project bundle and contracts. Checks hash matching, coverage thresholds, and contract density. + +**When to use:** After creating/updating SDD, before promotion, in CI/CD pipelines. + +**Quick:** `/specfact.05-enforce` (uses active plan) or `/specfact.05-enforce legacy-api` + +## Parameters + +### Target/Input + +- `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`) +- `--sdd PATH` - Path to SDD manifest. Default: bundle-specific .specfact/projects//sdd. (Phase 8.5), with fallback to legacy .specfact/sdd/. + +### Output/Results + +- `--output-format FORMAT` - Output format (yaml, json, markdown). Default: yaml +- `--out PATH` - Output file path. Default: bundle-specific .specfact/projects//reports/enforcement/report-. (Phase 8.5) + +### Behavior/Options + +- `--no-interactive` - Non-interactive mode (for CI/CD). Default: False (interactive mode) + +## Workflow + +### Step 1: Parse Arguments + +- Extract bundle name (defaults to active plan if not specified) +- Extract optional parameters (sdd path, output format, etc.) + +### Step 2: Execute CLI + +```bash +specfact enforce sdd [] [--sdd ] [--output-format ] [--out ] +# Uses active plan if bundle not specified +``` + +### Step 3: Present Results + +- Display validation summary (passed/failed) +- Show deviation counts by severity +- Present coverage metrics vs thresholds +- Indicate hash match status +- Provide fix hints for failures + +## CLI Enforcement + +**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details. + +**Rules:** + +- Execute CLI first - never create artifacts directly +- Use `--no-interactive` flag in CI/CD environments +- Never modify `.specfact/` directly +- Use CLI output as grounding for validation +- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only) + +## Dual-Stack Workflow (Copilot Mode) + +When in copilot mode, follow this three-phase workflow: + +### Phase 1: CLI Grounding (REQUIRED) + +```bash +# Execute CLI to get structured output +specfact enforce sdd [] [--sdd ] --no-interactive +``` + +**Capture**: + +- CLI-generated validation report +- Deviation counts and severity +- Coverage metrics vs thresholds + +### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only) + +**Purpose**: Add semantic understanding to validation results + +**What to do**: + +- Read CLI-generated validation report (use file reading tools for display only) +- Treat the CLI report as the source of truth; scan codebase only to explain deviations or propose fixes +- Research codebase for context on deviations +- Suggest fixes for validation failures + +**What NOT to do**: + +- ❌ Create YAML/JSON artifacts directly +- ❌ Modify CLI artifacts directly (use CLI commands to update) +- ❌ Bypass CLI validation +- ❌ Write to `.specfact/` folder directly (always use CLI) + +**Output**: Generate fix suggestions report (Markdown) + +### Phase 3: CLI Artifact Creation (REQUIRED) + +```bash +# Apply fixes via CLI commands, then re-validate +specfact plan update-feature [--bundle ] [options] --no-interactive +specfact enforce sdd [] --no-interactive +``` + +**Result**: Final artifacts are CLI-generated with validated fixes + +**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code)) + +## Expected Output + +### Success + +```text +✓ SDD validation passed + +Validation Summary +Total deviations: 0 + High: 0 + Medium: 0 + Low: 0 + +Report saved to: .specfact/projects//reports/enforcement/report-2025-11-26T10-30-00.yaml +``` + +### Failure (Hash Mismatch) + +```text +✗ SDD validation failed + +Issues Found: + +1. Hash Mismatch (HIGH) + The project bundle has been modified since the SDD manifest was created. + SDD hash: abc123def456... + Bundle hash: xyz789ghi012... + + Hash changes when modifying features, stories, or product/idea/business sections. + Note: Clarifications don't affect hash (review metadata). Hash stable across review sessions. + Fix: Run `specfact plan harden ` to update SDD manifest. +``` + +## Common Patterns + +```bash +/specfact.05-enforce # Uses active plan +/specfact.05-enforce legacy-api # Specific bundle +/specfact.05-enforce --output-format json --out report.json +/specfact.05-enforce --no-interactive # CI/CD mode +``` + +## Context + +{ARGS} diff --git a/packages/specfact-project/module-package.yaml b/packages/specfact-project/module-package.yaml index 797c816..03bff28 100644 --- a/packages/specfact-project/module-package.yaml +++ b/packages/specfact-project/module-package.yaml @@ -1,5 +1,5 @@ name: nold-ai/specfact-project -version: 0.40.21 +version: 0.40.23 commands: - project tier: official @@ -12,5 +12,5 @@ description: Official SpecFact project bundle package. category: project bundle_group_command: project integrity: - checksum: sha256:2a05f3172e563842e000c855160d10b5e7c68174498c9172f82ed6aa9989158e - signature: mgDXqPGeP2OweZyoOHxiCs+i7OaaettBYm3Hf3vjr8jYnUAy0v5PL2s9e1unTV0nlXeabITppNkJcRziMg0aDA== + checksum: sha256:76f1c212eda3831b4d759ccafc336d315ae810cb6c3e00b961edb5660305ae08 + signature: ouJhKYaOvbl8xI6fDlVZd3B4xoNLx4AJ4yvLvhsbktenHj7ToFFostOcfnuhP8mVB2i0iiqEOnUPiWb3vG6UBw== diff --git a/packages/specfact-project/resources/prompts/shared/cli-enforcement.md b/packages/specfact-project/resources/prompts/shared/cli-enforcement.md new file mode 100644 index 0000000..b8aab9a --- /dev/null +++ b/packages/specfact-project/resources/prompts/shared/cli-enforcement.md @@ -0,0 +1,119 @@ +# CLI Usage Enforcement Rules + +## Core Principle + +**ALWAYS use SpecFact CLI commands. Never create artifacts directly.** + +## CLI vs LLM Capabilities + +### CLI-Only Operations (CI/CD Mode - No LLM Required) + +The CLI can perform these operations **without LLM**: + +- ✅ Tool execution (ruff, pylint, basedpyright, mypy, semgrep, specmatic) +- ✅ Bundle management (create, load, save, validate structure) +- ✅ Metadata management (timestamps, hashes, telemetry) +- ✅ Planning operations (init, add-feature, add-story, update-idea, update-feature) +- ✅ AST/Semgrep-based analysis (code structure, patterns, relationships) +- ✅ Specmatic validation (OpenAPI/AsyncAPI contract validation) +- ✅ Format validation (YAML/JSON schema compliance) +- ✅ Source tracking and drift detection + +**CRITICAL LIMITATIONS**: + +- ❌ **CANNOT generate code** - No LLM available in CLI-only mode +- ❌ **CANNOT do reasoning** - No semantic understanding without LLM + +### LLM-Required Operations (AI IDE Mode - Via Slash Prompts) + +These operations **require LLM** and are only available via AI IDE slash prompts: + +- ✅ Code generation (requires LLM reasoning) +- ✅ Code enhancement (contracts, refactoring, improvements) +- ✅ Semantic understanding (business logic, context, priorities) +- ✅ Plan enrichment (missing features, confidence adjustments, business context) +- ✅ Code reasoning (why decisions were made, trade-offs, constraints) + +**Access**: Only available via AI IDE slash prompts (Cursor, CoPilot, etc.) +**Pattern**: Slash prompt → LLM generates → CLI validates → Apply if valid + +## LLM Grounding Rules + +- Treat CLI artifacts as the source of truth for keys, structure, and metadata. +- Scan the codebase only when asked to infer missing behavior/context or explain deviations; respect `--entry-point` scope when provided. +- Use codebase findings to propose updates via CLI (enrichment report, plan update commands), never to rewrite artifacts directly. + +## Rules + +1. **Execute CLI First**: Always run CLI commands before any analysis +2. **Use CLI for Writes**: All write operations must go through CLI +3. **Read for Display Only**: Use file reading tools for display/analysis only +4. **Never Modify .specfact/**: Do not create/modify files in `.specfact/` directly +5. **Never Bypass Validation**: CLI ensures schema compliance and metadata +6. **Code Generation Requires LLM**: Code generation is only possible via AI IDE slash prompts, not CLI-only + +## Standard Validation Loop Pattern (For LLM-Generated Code) + +When generating or enhancing code via LLM, **ALWAYS** follow this pattern: + +```text +1. CLI Prompt Generation (Required) + ↓ + CLI generates structured prompt → saved to .specfact/prompts/ + (e.g., `generate contracts-prompt`, future: `generate code-prompt`) + +2. LLM Execution (Required - AI IDE Only) + ↓ + LLM reads prompt → generates enhanced code → writes to TEMPORARY file + (NEVER writes directly to original artifacts) + Pattern: `enhanced_.py` or `generated_.py` + +3. CLI Validation Loop (Required, up to N retries) + ↓ + CLI validates temp file with all relevant tools: + - Syntax validation (py_compile) + - File size check (must be >= original) + - AST structure comparison (preserve functions/classes) + - Contract imports verification + - Code quality checks (ruff, pylint, basedpyright, mypy) + - Test execution (contract-test, pytest) + ↓ + If validation fails: + - CLI provides detailed error feedback + - LLM fixes issues in temp file + - Re-validate (max 3 attempts) + ↓ + If validation succeeds: + - CLI applies changes to original file + - CLI removes temporary file + - CLI updates metadata/telemetry +``` + +**This pattern must be used for**: + +- ✅ Contract enhancement (`generate contracts-prompt` / `contracts-apply`) - Already implemented +- ⏳ Code generation (future: `generate code-prompt` / `code-apply`) - Needs implementation +- ⏳ Plan enrichment (future: `plan enrich-prompt` / `enrich-apply`) - Needs implementation +- ⏳ Any LLM-enhanced artifact modification - Needs implementation + +## What Happens If You Don't Follow + +- ❌ Artifacts may not match CLI schema versions +- ❌ Missing metadata and telemetry +- ❌ Format inconsistencies +- ❌ Validation failures +- ❌ Works only in Copilot mode, fails in CI/CD +- ❌ Code generation attempts in CLI-only mode will fail (no LLM available) + +## Available CLI Commands + +- `specfact plan init ` - Initialize project bundle +- `specfact plan select ` - Set active plan (used as default for other commands) +- `specfact code import [] --repo ` - Import from codebase (uses active plan if bundle not specified) +- `specfact plan review []` - Review plan (uses active plan if bundle not specified) +- `specfact plan harden []` - Create SDD manifest (uses active plan if bundle not specified) +- `specfact enforce sdd []` - Validate SDD (uses active plan if bundle not specified) +- `specfact sync bridge --adapter --repo ` - Sync with external tools +- See [Command Reference](../../docs/reference/commands.md) for full list + +**Note**: Most commands now support active plan fallback. If `--bundle` is not specified, commands automatically use the active plan set via `plan select`. This improves workflow efficiency in AI IDE environments. diff --git a/packages/specfact-project/resources/prompts/specfact.02-plan.md b/packages/specfact-project/resources/prompts/specfact.02-plan.md new file mode 100644 index 0000000..66c7c01 --- /dev/null +++ b/packages/specfact-project/resources/prompts/specfact.02-plan.md @@ -0,0 +1,177 @@ +--- +description: Manage project bundles - create, add features/stories, and update plan metadata. +--- + +# SpecFact Plan Management Command + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Purpose + +Manage project bundles: initialize, add features/stories, update metadata (idea/features/stories). + +**When to use:** Creating bundles, adding features/stories, updating metadata. + +**Quick:** `/specfact.02-plan init legacy-api` or `/specfact.02-plan add-feature --key FEATURE-001 --title "User Auth"` + +## Parameters + +### Target/Input + +- `--bundle NAME` - Project bundle name (optional, defaults to active plan set via `plan select`) +- `--key KEY` - Feature/story key (e.g., FEATURE-001, STORY-001) +- `--feature KEY` - Parent feature key (for story operations) + +### Output/Results + +- (No output-specific parameters for plan management) + +### Behavior/Options + +- `--interactive/--no-interactive` - Interactive mode. Default: True (interactive) +- `--scaffold/--no-scaffold` - Create directory structure. Default: True (scaffold enabled) + +### Advanced/Configuration + +- `--title TEXT` - Feature/story title +- `--outcomes TEXT` - Expected outcomes (comma-separated) +- `--acceptance TEXT` - Acceptance criteria (comma-separated) +- `--constraints TEXT` - Constraints (comma-separated) +- `--confidence FLOAT` - Confidence score (0.0-1.0) +- `--draft/--no-draft` - Mark as draft + +## Workflow + +### Step 1: Parse Arguments + +- Determine operation: `init`, `add-feature`, `add-story`, `update-idea`, `update-feature`, `update-story` +- Extract parameters (bundle name defaults to active plan if not specified, keys, etc.) + +### Step 2: Execute CLI + +```bash +specfact plan init [--interactive/--no-interactive] [--scaffold/--no-scaffold] +specfact plan add-feature [--bundle ] --key --title [--outcomes <outcomes>] [--acceptance <acceptance>] +specfact plan add-story [--bundle <name>] --feature <feature-key> --key <story-key> --title <title> [--acceptance <acceptance>] +specfact plan update-idea [--bundle <name>] [--title <title>] [--narrative <narrative>] [--target-users <users>] [--value-hypothesis <hypothesis>] [--constraints <constraints>] +specfact plan update-feature [--bundle <name>] --key <key> [--title <title>] [--outcomes <outcomes>] [--acceptance <acceptance>] [--constraints <constraints>] [--confidence <score>] [--draft/--no-draft] +specfact plan update-story [--bundle <name>] --feature <feature-key> --key <story-key> [--title <title>] [--acceptance <acceptance>] [--story-points <points>] [--value-points <points>] [--confidence <score>] [--draft/--no-draft] +# --bundle defaults to active plan if not specified +``` + +### Step 3: Present Results + +- Display bundle location +- Show created/updated features/stories +- Present summary of changes + +## CLI Enforcement + +**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details. + +**Rules:** + +- Execute CLI first - never create artifacts directly +- Use `--no-interactive` flag in CI/CD environments +- Never modify `.specfact/` directly +- Use CLI output as grounding for validation +- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only) + +## Dual-Stack Workflow (Copilot Mode) + +When in copilot mode, follow this three-phase workflow: + +### Phase 1: CLI Grounding (REQUIRED) + +```bash +# Execute CLI to get structured output +specfact plan <operation> [--bundle <name>] [options] --no-interactive +``` + +**Capture**: + +- CLI-generated artifacts (plan bundles, features, stories) +- Metadata (timestamps, confidence scores) +- Telemetry (execution time, file counts) + +### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only) + +**Purpose**: Add semantic understanding to CLI output + +**What to do**: + +- Read CLI-generated artifacts (use file reading tools for display only) +- Use CLI artifacts as the source of truth for keys/structure/metadata +- Scan codebase only if asked to align the plan with implementation or to add missing features +- When scanning, compare findings against CLI artifacts and propose updates via CLI commands +- Identify missing features/stories +- Suggest confidence adjustments +- Extract business context + +**What NOT to do**: + +- ❌ Create YAML/JSON artifacts directly +- ❌ Modify CLI artifacts directly (use CLI commands to update) +- ❌ Bypass CLI validation +- ❌ Write to `.specfact/` folder directly (always use CLI) +- ❌ Use direct file manipulation tools for writing (use CLI commands) + +**Output**: Generate enrichment report (Markdown) or use `--batch-updates` JSON/YAML file + +### Phase 3: CLI Artifact Creation (REQUIRED) + +```bash +# Use enrichment to update plan via CLI +specfact plan update-feature [--bundle <name>] --key <key> [options] --no-interactive +# Or use batch updates: +specfact plan update-feature [--bundle <name>] --batch-updates <updates.json> --no-interactive +``` + +**Result**: Final artifacts are CLI-generated with validated enrichments + +**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code)) + +## Expected Output + +## Success (Init) + +```text +✓ Project bundle created: .specfact/projects/legacy-api/ +✓ Bundle initialized with scaffold structure +``` + +## Success (Add Feature) + +```text +✓ Feature 'FEATURE-001' added successfully +Feature: User Authentication +Outcomes: Secure login, Session management +``` + +## Error (Missing Bundle) + +```text +✗ Project bundle name is required (or set active plan with 'plan select') +Usage: specfact plan <operation> [--bundle <name>] [options] +``` + +## Common Patterns + +```bash +/specfact.02-plan init legacy-api +/specfact.02-plan add-feature --key FEATURE-001 --title "User Auth" --outcomes "Secure login" --acceptance "Users can log in" +/specfact.02-plan add-story --feature FEATURE-001 --key STORY-001 --title "Login API" --acceptance "API returns JWT" +/specfact.02-plan update-feature --key FEATURE-001 --title "Updated Title" --confidence 0.9 +/specfact.02-plan update-idea --target-users "Developers, DevOps" --value-hypothesis "Reduce technical debt" +# --bundle defaults to active plan if not specified +``` + +## Context + +{ARGS} diff --git a/packages/specfact-project/resources/prompts/specfact.03-review.md b/packages/specfact-project/resources/prompts/specfact.03-review.md new file mode 100644 index 0000000..a66a6fe --- /dev/null +++ b/packages/specfact-project/resources/prompts/specfact.03-review.md @@ -0,0 +1,714 @@ +--- +description: Review project bundle to identify ambiguities, resolve gaps, and prepare for promotion. +--- + +# SpecFact Review Command + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Purpose + +Review project bundle to identify/resolve ambiguities and missing information. Asks targeted questions for promotion readiness. + +**When to use:** After import/creation, before promotion, when clarification needed. + +**Quick:** `/specfact.03-review` (uses active plan) or `/specfact.03-review legacy-api` + +## Interactive Question Presentation + +**CRITICAL**: When presenting questions interactively, **ALWAYS** generate and display multiple answer options in a table format. This makes it easier for users to select appropriate answers. + +### Answer Options Format + +For each question, generate 3-5 reasonable answer options based on: + +- **Code analysis**: Review existing patterns, similar features, error handling approaches +- **Domain knowledge**: Best practices, common scenarios, industry standards +- **Business context**: Product requirements, user needs, feature relationships + +**Present options in a numbered table with recommended answer:** + +```text +Question 1/5 +Category: Interaction & UX Flow +Q: What error/empty states should be handled for story STORY-XXX? + +Current Plan Settings: +Story STORY-XXX Acceptance: [current acceptance criteria] + +Answer Options: +┌─────┬─────────────────────────────────────────────────────────────────┐ +│ No. │ Option │ +├─────┼─────────────────────────────────────────────────────────────────┤ +│ 1 │ Error handling: Invalid input produces clear error messages │ +│ │ Empty states: Missing data shows "No data available" message │ +│ │ Validation: Required fields validated before processing │ +│ │ ⭐ Recommended (based on code analysis) │ +├─────┼─────────────────────────────────────────────────────────────────┤ +│ 2 │ Error handling: Network failures retry with exponential backoff │ +│ │ Empty states: Show empty state UI with helpful guidance │ +│ │ Validation: Schema-based validation with clear error messages │ +├─────┼─────────────────────────────────────────────────────────────────┤ +│ 3 │ Error handling: Errors logged to stderr with exit codes (CLI) │ +│ │ Empty states: Sensible defaults when data is missing │ +│ │ Validation: Covered in OpenAPI contract files │ +├─────┼─────────────────────────────────────────────────────────────────┤ +│ 4 │ Not applicable - error handling covered in contract files │ +├─────┼─────────────────────────────────────────────────────────────────┤ +│ 5 │ [Custom answer - type your own] │ +└─────┴─────────────────────────────────────────────────────────────────┘ + +Your answer (1-5, or type custom answer): [1] ⭐ Recommended +``` + +**CRITICAL**: Always provide a **recommended answer** (marked with ⭐) based on: + +- Code analysis (what the actual implementation does) +- Best practices (industry standards, common patterns) +- Domain knowledge (what makes sense for this feature) + +The recommendation helps less-experienced users make informed decisions. + +### Guidelines for Answer Options + +- **Option 1-3**: Specific, actionable options based on code analysis and domain knowledge +- **Option 4**: "Not applicable" or "Covered elsewhere" when appropriate +- **Option 5**: Always include "[Custom answer - type your own]" as the last option +- **Base options on research**: Review codebase, similar features, existing patterns +- **Make options specific**: Avoid generic responses - be concrete and actionable +- **Use numbered selection**: Allow users to select by number (1-5) or letter (A-E) +- **⭐ Always provide a recommended answer**: Mark one option as recommended (⭐) based on: + - Code analysis (what the actual implementation does or should do) + - Best practices (industry standards, common patterns) + - Domain knowledge (what makes sense for this specific feature) + - The recommendation helps less-experienced users make informed decisions + +## Parameters + +### Target/Input + +- `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`) +- `--category CATEGORY` - Focus on specific taxonomy category. Default: None (all categories) + +### Output/Results + +- `--list-questions` - Output questions in JSON format. Default: False +- `--output-questions PATH` - Save questions directly to file (JSON format). Use with `--list-questions` to save instead of stdout. Default: None +- `--list-findings` - Output all findings in structured format. Default: False +- `--output-findings PATH` - Save findings directly to file (JSON/YAML format). Use with `--list-findings` to save instead of stdout. Default: None +- `--findings-format FORMAT` - Output format: json, yaml, or table. Default: json for non-interactive, table for interactive + +### Behavior/Options + +- `--no-interactive` - Non-interactive mode (for CI/CD). Default: False (interactive mode) +- `--answers JSON` - JSON object with question_id -> answer mappings. Default: None +- `--auto-enrich` - Automatically enrich vague acceptance criteria using PlanEnricher (same enrichment logic as `import from-code`). Default: False (opt-in for review, but import has auto-enrichment enabled by default) + +**Important**: `--auto-enrich` will **NOT** resolve partial findings such as: + +- Missing error handling specifications ("Interaction & UX Flow" category) +- Vague acceptance criteria requiring domain knowledge ("Completion Signals" category) +- Business context questions requiring human judgment + +For these cases, use the **export-to-file → LLM reasoning → import-from-file** workflow (see Step 4). + +### Advanced/Configuration + +- `--max-questions INT` - Maximum questions per session. Default: 5 (range: 1-10) + + **Important**: This limits the number of questions asked per review session, not the total number of available questions. If there are more questions than the limit, you may need to run the review multiple times to answer all questions. Each session will ask different questions (avoiding duplicates from previous sessions). + +## Workflow + +### Step 1: Parse Arguments + +- Extract bundle name (defaults to active plan if not specified) +- Extract optional parameters (max-questions, category, etc.) + +### Step 2: Execute CLI to Export Questions + +**CRITICAL**: Always use `/tmp/` for temporary artifacts to avoid polluting the codebase. Never create temporary files in the project root. + +**CRITICAL**: Question IDs are generated per run and can change if you re-run review. +**Do not** re-run `plan review` between exporting questions and applying answers. Always answer using the exact exported questions file for that session. + +**Note**: The `--max-questions` parameter (default: 5) limits the number of questions per session, not the total number of available questions. If there are more questions available, you may need to run the review multiple times to answer all questions. Each session will ask different questions (avoiding duplicates from previous sessions). + +**Export questions to file for LLM reasoning:** + +```bash +# Export questions to file (REQUIRED for LLM enrichment workflow) +# Use /tmp/ to avoid polluting the codebase +specfact plan review [<bundle-name>] --list-questions --output-questions /tmp/questions.json --no-interactive +# Uses active plan if bundle not specified +``` + +**Optional: Get findings for comprehensive analysis:** + +```bash +# Get findings (saves to stdout - can redirect to /tmp/) +# Use /tmp/ to avoid polluting the codebase +# Option 1: Redirect output (includes CLI banner - not recommended) +specfact plan review [<bundle-name>] --list-findings --findings-format json --no-interactive > /tmp/findings.json + +# Option 2: Save directly to file (recommended - clean JSON only) +specfact plan review [<bundle-name>] --list-findings --output-findings /tmp/findings.json --no-interactive +``` + +**Note**: The `--output-questions` option saves questions directly to a file, avoiding the need for complex JSON parsing. The ambiguity scanner now recognizes the simplified format (e.g., "Must verify X works correctly (see contract examples)") as valid and will not flag it as vague. + +**Important**: Always use `/tmp/` for temporary files (`questions.json`, `findings.json`, etc.) to keep the project root clean and avoid accidental commits of temporary artifacts. + +### Step 3: LLM Reasoning and Answer Generation + +**CRITICAL**: For partial findings (missing error handling, vague acceptance criteria, business context), `--auto-enrich` will **NOT** resolve them. You must use LLM reasoning. + +**CRITICAL WORKFLOW**: Present questions with answer options **IN THE CHAT**, wait for user selection, then add selected answers to file. + +**Workflow:** + +1. **Read the exported questions file** (`/tmp/questions.json`): + + - Review all questions in the file + - Identify which questions require code/feature analysis + - Determine which questions need domain knowledge or business context + +2. **Research codebase and features** (as needed): + + - For error handling questions: Check existing error handling patterns in the codebase + - For acceptance criteria questions: Review related features and stories + - For business context questions: Review `idea.yaml`, `product.yaml`, and related documentation + +3. **Present questions with answer options IN THE CHAT** (REQUIRED): + + **DO NOT add answers to the file yet!** Present each question with answer options in the chat conversation and wait for user selection. + + For each question: + + - **Generate 3-5 reasonable answer options** based on: + - Code analysis (existing patterns, similar features) + - Domain knowledge (best practices, common scenarios) + - Business context (product requirements, user needs) + - **Present options in a table format** in the chat with numbered choices: + + ```text + Question 1/5 + Category: Interaction & UX Flow + Q: What error/empty states should be handled for story STORY-XXX? + + Current Plan Settings: + Story STORY-XXX Acceptance: [current acceptance criteria] + + Answer Options: + ┌─────┬─────────────────────────────────────────────────────────────────┐ + │ No. │ Option │ + ├─────┼─────────────────────────────────────────────────────────────────┤ + │ 1 │ Error handling: Invalid input produces clear error messages │ + │ │ Empty states: Missing data shows "No data available" message │ + │ │ Validation: Required fields validated before processing │ + │ │ ⭐ Recommended (based on code analysis) │ + ├─────┼─────────────────────────────────────────────────────────────────┤ + │ 2 │ Error handling: Network failures retry with exponential backoff │ + │ │ Empty states: Show empty state UI with helpful guidance │ + │ │ Validation: Schema-based validation with clear error messages │ + ├─────┼─────────────────────────────────────────────────────────────────┤ + │ 3 │ Error handling: Errors logged to stderr with exit codes (CLI) │ + │ │ Empty states: Sensible defaults when data is missing │ + │ │ Validation: Covered in OpenAPI contract files │ + ├─────┼─────────────────────────────────────────────────────────────────┤ + │ 4 │ Not applicable - error handling covered in contract files │ + ├─────┼─────────────────────────────────────────────────────────────────┤ + │ 5 │ [Custom answer - type your own] │ + └─────┴─────────────────────────────────────────────────────────────────┘ + + Your answer (1-5, or type custom answer): [1] ⭐ Recommended + ``` + + - **Wait for user to select an answer** (number 1-5, letter A-E, or custom text) + - **Option 5 (or last option)** should always be "[Custom answer - type your own]" to allow free-form input + - **Base options on code analysis** - review similar features, existing error handling patterns, and domain knowledge + - **Make options specific and actionable** - not generic responses + - **⭐ Always provide a recommended answer** - mark one option as recommended (⭐) based on code analysis, best practices, and domain knowledge. This helps less-experienced users make informed decisions. + - **Present one question at a time** and wait for user selection before moving to the next + +4. **After user has selected all answers**: + + - **THEN** export the selected answers to a separate file `/tmp/answers.json` + - Map user selections to the actual answer text (if user selected option 1, use the text from option 1) + - If user selected a custom answer, use that text directly + - **Export format**: Create a JSON object with `question_id -> answer` mappings + - **DO NOT** add answers to the file until user has selected all answers + - **CRITICAL**: Export answers to `/tmp/answers.json` (not `/tmp/questions.json`) for CLI import + +**Example `/tmp/questions.json` structure:** + +```json +{ + "questions": [ + { + "id": "Q001", + "category": "Interaction & UX Flow", + "question": "What error/empty states should be handled for story STORY-XXX?", + "related_sections": ["features.FEATURE-XXX.stories.STORY-XXX.acceptance"] + } + ], + "total": 5 +} +``` + +**Example `/tmp/answers.json` structure (exported after user selections):** + +```json +{ + "Q001": "Error handling should include: network failures (retry with exponential backoff), invalid input (clear validation messages), empty results (show 'No data available' message), timeout errors (show progress indicator and allow cancellation). Based on analysis of similar features in the codebase.", + "Q002": "Answer for question 2 based on code review..." +} +``` + +**CRITICAL**: Export answers to `/tmp/answers.json` (separate file), not to `/tmp/questions.json`. The CLI expects a file path for `--answers`, not a JSON string extracted from the questions file. + +### Step 4: Apply Enrichment via CLI + +**REQUIRED workflow for partial findings:** + +1. **Export questions to file** (already done in Step 2): + + ```bash + # Use /tmp/ to avoid polluting the codebase + specfact plan review [<bundle-name>] --list-questions --output-questions /tmp/questions.json --no-interactive + ``` + +2. **LLM reasoning and user selection** (Step 3): + + - LLM presents questions with answer options **IN THE CHAT** + - User selects answers (1-5, A-E, or custom text) + - **After user has selected all answers**, LLM adds selected answers to `/tmp/questions.json` + +3. **Import answers via CLI** (after user selections are complete): + + ```bash + # Import answers from exported file + # Use /tmp/ to avoid polluting the codebase + specfact plan review [<bundle-name>] --answers /tmp/answers.json --no-interactive + ``` + +**CRITICAL**: + +- Do NOT add answers to the file until the user has selected all answers +- Present questions in chat, wait for selections +- Export answers to `/tmp/answers.json` (separate file, not `/tmp/questions.json`) +- Import via CLI using the file path: `--answers /tmp/answers.json` + +**Alternative approaches** (for non-partial findings only): + +#### Option B: Update idea fields directly via CLI + +Use `plan update-idea` to update idea fields from enrichment recommendations: + +```bash +specfact plan update-idea --bundle [<bundle-name>] --value-hypothesis "..." --narrative "..." --target-users "..." +``` + +#### Option C: Apply enrichment via import (only if bundle needs regeneration) + +```bash +specfact code import [<bundle-name>] --repo . --enrichment enrichment-report.md +``` + +**Note:** + +- **For partial findings**: Always use Option A (export → LLM reasoning → import) +- **For business context only**: Option B (update-idea) may be sufficient +- **For bundle regeneration**: Only use Option C if you need to regenerate the bundle +- **CRITICAL**: Never manually edit `.specfact/` files directly - always use CLI commands + - This includes `idea.yaml`, `product.yaml`, feature files, story files, etc. + - Even if a file doesn't exist yet, use CLI commands to create it (e.g., `plan update-idea` will create `idea.yaml` if needed) + - Direct file modification bypasses validation and can cause inconsistencies + +- **Preferred**: Use Option A (answers) or Option B (update-idea) for most cases +- Only use Option C if you need to regenerate the bundle +- **CRITICAL**: Never manually edit `.specfact/` files directly - always use CLI commands + - This includes `idea.yaml`, `product.yaml`, feature files, story files, etc. + - Even if a file doesn't exist yet, use CLI commands to create it (e.g., `plan update-idea` will create `idea.yaml` if needed) + - Direct file modification bypasses validation and can cause inconsistencies + +### Step 5: Present Results + +- Display Q&A, sections touched, coverage summary (initial/updated) +- Note: Clarifications don't affect hash (stable across review sessions) +- If enrichment report was created, summarize what was addressed + +## CLI Enforcement + +**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details. + +**Rules:** + +- Execute CLI first - never create artifacts directly +- Use `--no-interactive` flag in CI/CD environments +- **NEVER modify `.specfact/` files directly** - always use CLI commands + - ❌ **DO NOT** edit `idea.yaml`, `product.yaml`, feature files, or any other artifacts directly + - ❌ **DO NOT** create new artifact files manually (even if they don't exist yet) + - ✅ **DO** use CLI commands: `plan update-idea`, `plan update-feature`, `plan update-story`, etc. + - ✅ **DO** use CLI commands to create new artifacts: `plan init`, `plan add-feature`, etc. +- Use CLI output as grounding for validation +- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only) + +**Important**: If an artifact file doesn't exist yet, use the appropriate CLI command to create it. Never create or modify `.specfact/` files manually, as this bypasses validation and can cause inconsistencies. + +## Dual-Stack Workflow (Copilot Mode) + +When in copilot mode, follow this three-phase workflow: + +### Phase 1: CLI Grounding (REQUIRED) + +```bash +# Option 1: Get findings (redirect to /tmp/ to avoid polluting codebase) +# Option 1: Save findings directly to file (recommended - clean JSON only) +specfact plan review [<bundle-name>] --list-findings --output-findings /tmp/findings.json --no-interactive + +# Option 2: Get questions and save directly to /tmp/ (recommended - avoids JSON parsing) +specfact plan review [<bundle-name>] --list-questions --output-questions /tmp/questions.json --no-interactive +``` + +**Capture**: + +- CLI-generated findings (ambiguities, missing information) +- Questions saved directly to file (no complex parsing needed) +- Structured JSON/YAML output for bulk processing +- Metadata (timestamps, confidence scores) + +**Note**: Use `--output-questions` to save questions directly to a file. This avoids the need for complex on-the-fly Python code to extract JSON from CLI output. + +**CRITICAL**: Always use `/tmp/` for temporary artifacts (`questions.json`, `findings.json`, etc.) to avoid polluting the codebase and prevent accidental commits of temporary files. + +### Phase 2: LLM Enrichment (REQUIRED for Partial Findings) + +**Purpose**: Add semantic understanding and domain knowledge to CLI findings + +**CRITICAL**: `--auto-enrich` will **NOT** resolve partial findings. LLM reasoning is **REQUIRED** for: + +- Missing error handling specifications ("Interaction & UX Flow" category) +- Vague acceptance criteria requiring domain knowledge ("Completion Signals" category) +- Business context questions requiring human judgment + +**What to do**: + +0. **Grounding rule**: + - Treat CLI-exported questions as the source of truth; consult codebase/docs only to answer them (do not invent new artifacts) + - **Feature/Story Completeness note**: Answers here are clarifications only. They do **NOT** create stories. + For missing stories, use `specfact plan add-story` (or `plan update-story --batch-updates` if stories already exist). + +1. **Read exported questions file** (`/tmp/questions.json`): + - Review all questions and their categories + - Identify questions requiring code/feature analysis + - Determine questions needing domain knowledge + +2. **Research codebase**: + - For error handling: Analyze existing error handling patterns + - For acceptance criteria: Review related features and stories + - For business context: Review `idea.yaml`, `product.yaml`, documentation + +3. **Present questions with answer options IN THE CHAT** (REQUIRED): + + **DO NOT add answers to the file yet!** Present each question with answer options in the chat conversation. + + **For each question:** + + - Generate 3-5 reasonable options based on code analysis and domain knowledge + - Present in a numbered table (1-5) or lettered table (A-E) **IN THE CHAT** + - Include a "[Custom answer]" option as the last choice + - Make options specific and actionable, not generic + - **Wait for user to select an answer** before moving to the next question + + **Example format (present in chat):** + + ```text + Question 1/5 + Category: Interaction & UX Flow + Q: What error/empty states should be handled for story STORY-XXX? + + Answer Options: + ┌─────┬─────────────────────────────────────────────────────────────┐ + │ No. │ Option │ + ├─────┼─────────────────────────────────────────────────────────────┤ + │ 1 │ [Option based on code analysis - specific and actionable] │ + │ │ ⭐ Recommended (based on code analysis) │ + │ 2 │ [Option based on best practices - domain knowledge] │ + │ 3 │ [Option based on similar features - pattern matching] │ + │ 4 │ [Not applicable / covered elsewhere] │ + │ 5 │ [Custom answer - type your own] │ + └─────┴─────────────────────────────────────────────────────────────┘ + + Your answer (1-5, or type custom answer): [1] ⭐ Recommended + ``` + +4. **After user has selected all answers**: + + - **THEN** add the selected answers to `/tmp/questions.json` in the `answers` object + - Map user selections (1-5) to the actual answer text from the options + - If user selected a custom answer, use that text directly + - **DO NOT** add answers to the file until user has selected all answers + +**What NOT to do**: + +- ❌ Use `--auto-enrich` expecting it to resolve partial findings +- ❌ Create YAML/JSON artifacts directly (even if they don't exist yet) +- ❌ Modify CLI artifacts directly (use CLI commands to update) +- ❌ Edit `idea.yaml`, `product.yaml`, feature files, or story files manually +- ❌ Create new artifact files manually - use CLI commands instead +- ❌ Bypass CLI validation +- ❌ Write to `.specfact/` folder directly (always use CLI) +- ❌ Create temporary files in project root (always use `/tmp/`) + +**Output**: Updated `/tmp/questions.json` file with `answers` object populated + +### Phase 3: CLI Artifact Creation (REQUIRED) + +**For partial findings (REQUIRED workflow):** + +```bash +# Import answers from /tmp/questions.json file +# Use /tmp/ to avoid polluting the codebase +specfact plan review [<bundle-name>] --answers "$(jq -c '.answers' /tmp/questions.json)" --no-interactive +``` + +**For non-partial findings only:** + +```bash +# Use auto-enrich for simple vague criteria (not partial findings) +specfact plan review [<bundle-name>] --auto-enrich --no-interactive + +# Or use batch updates for feature updates +specfact plan update-feature [--bundle <name>] --batch-updates <updates.json> --no-interactive +``` + +**Result**: Final artifacts are CLI-generated with validated enrichments + +**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code)) + +## Expected Output + +### Success + +```text +✓ Review complete: 5 question(s) answered + +Project Bundle: legacy-api +Questions Asked: 5 + +Sections Touched: + • idea.narrative + • features[FEATURE-001].acceptance + • features[FEATURE-002].outcomes + +Coverage Summary: + ✅ Functional Scope: clear + ✅ Technical Constraints: clear + ⚠️ Business Context: partial +``` + +### Error (Missing Bundle) + +```text +✗ Project bundle 'legacy-api' not found +Create one with: specfact plan init legacy-api +``` + +## Common Patterns + +```bash +# Get findings first +/specfact.03-review --list-findings # List all findings +/specfact.03-review --list-findings --findings-format json # JSON format for enrichment +/specfact.03-review --list-findings --output-findings /tmp/findings.json # Save findings to file (clean JSON) + +# Interactive review +/specfact.03-review # Uses active plan (default: 5 questions per session) +/specfact.03-review legacy-api # Specific bundle +/specfact.03-review --max-questions 3 # Limit questions per session (may need multiple runs) +/specfact.03-review --category "Functional Scope" # Focus category +/specfact.03-review --max-questions 10 # Ask more questions per session (up to 10) + +# Non-interactive with answers +/specfact.03-review --answers '{"Q001": "answer"}' # Provide answers directly +/specfact.03-review --list-questions # Output questions as JSON to stdout +/specfact.03-review --list-questions --output-questions /tmp/questions.json # Save questions to /tmp/ + +# Auto-enrichment (NOTE: Will NOT resolve partial findings - use export/LLM/import workflow instead) +/specfact.03-review --auto-enrich # Auto-enrich simple vague criteria only + +# Recommended workflow for partial findings (use /tmp/ to avoid polluting codebase) +/specfact.03-review --list-questions --output-questions /tmp/questions.json # Export questions (default: 5 per session) +# [LLM reasoning: present questions in chat, wait for user selections, then export answers] +/specfact.03-review --answers /tmp/answers.json # Import answers from file +# [Repeat if more questions available - each session asks different questions] +/specfact.03-review --list-questions --output-questions /tmp/questions.json # Export next batch +/specfact.03-review --answers /tmp/answers.json # Import next batch +``` + +## Enrichment Workflow + +**CRITICAL**: `--auto-enrich` will **NOT** resolve partial findings such as: + +- Missing error handling specifications ("Interaction & UX Flow" category) +- Vague acceptance criteria requiring domain knowledge ("Completion Signals" category) +- Business context questions requiring human judgment + +**For partial findings, use this REQUIRED workflow:** + +1. **Export questions to file** (use `/tmp/` to avoid polluting codebase): + + ```bash + specfact plan review [<bundle-name>] --list-questions --output-questions /tmp/questions.json --no-interactive + ``` + +2. **Get findings** (optional, for comprehensive analysis - use `/tmp/`): + + ```bash + specfact plan review [<bundle-name>] --list-findings --output-findings /tmp/findings.json --no-interactive + ``` + +3. **LLM reasoning and user selection** (REQUIRED for partial findings): + + **CRITICAL**: Present questions with answer options **IN THE CHAT**, wait for user selections, then add selected answers to file. + + - Read `/tmp/questions.json` file + - Research codebase for error handling patterns, feature relationships, domain knowledge + - **Present each question with answer options IN THE CHAT** (see Step 3 for format) + - **Wait for user to select answers** (1-5, A-E, or custom text) + - **After user has selected all answers**, export selected answers to `/tmp/answers.json` (separate file) + - Map user selections to actual answer text (if user selected option 1, use the text from option 1) + - **Export format**: Create a JSON object with `question_id -> answer` mappings + - **DO NOT** export answers to file until user has selected all answers + - **CRITICAL**: Export to `/tmp/answers.json` (not `/tmp/questions.json`) for CLI import + +4. **Import answers via CLI** (after user selections are complete): + + ```bash + # Import answers from exported file + specfact plan review [<bundle-name>] --answers /tmp/answers.json --no-interactive + ``` + + **CRITICAL**: Use the file path `/tmp/answers.json` (not a JSON string extracted from `/tmp/questions.json`) + +5. **Verify**: Run `plan review` again to confirm improvements + + **Important**: The `--max-questions` parameter (default: 5) limits questions per session, not the total available. If there are more questions, repeat the workflow (Steps 2-4) until all are answered. Each session asks different questions, avoiding duplicates from previous sessions. + +**For non-partial findings only:** + +- **During import**: Auto-enrichment happens automatically (enabled by default) +- **After import**: Use `specfact plan review --auto-enrich` for simple vague criteria +- **Note**: The scanner now recognizes simplified format (e.g., "Must verify X works correctly (see contract examples)") as valid + +**Alternative approaches** (for business context only): + +- Use `plan update-idea` to update idea fields directly +- If bundle needs regeneration, use `import from-code --enrichment` + +**Note on OpenAPI Contracts:** + +After applying enrichment or review updates, check if features need OpenAPI contracts for sidecar validation: + +- Features added via enrichment typically don't have contracts (no `source_tracking`) +- Django applications require manual contract generation (Django URL patterns not auto-detected) +- Use `specfact contract init --bundle <bundle> --feature <FEATURE_KEY>` to generate contracts for features that need them + +**Enrichment Report Format** (for `import from-code --enrichment`): + +When generating enrichment reports for use with `import from-code --enrichment`, follow this exact format: + +```markdown +# [Bundle Name] Enrichment Report + +**Date**: YYYY-MM-DDTHH:MM:SS +**Bundle**: <bundle-name> + +--- + +## Missing Features + +1. **Feature Title** (Key: FEATURE-XXX) + - Confidence: 0.85 + - Outcomes: outcome1, outcome2, outcome3 + - Stories: + 1. Story title here + - Acceptance: criterion1, criterion2, criterion3 + 2. Another story title + - Acceptance: criterion1, criterion2 + +2. **Another Feature** (Key: FEATURE-YYY) + - Confidence: 0.80 + - Outcomes: outcome1, outcome2 + - Stories: + 1. Story title + - Acceptance: criterion1, criterion2, criterion3 + +## Confidence Adjustments + +- FEATURE-EXISTING-KEY: 0.90 (reason: improved understanding after code review) + +## Business Context + +- Priority: High priority feature for core functionality +- Constraint: Must support both REST and GraphQL APIs +- Risk: Potential performance issues with large datasets +``` + +**Format Requirements**: + +1. **Section Header**: Must use `## Missing Features` (case-insensitive, but prefer this exact format) +2. **Feature Format**: + - Numbered list: `1. **Feature Title** (Key: FEATURE-XXX)` + - **Bold title** is required (use `**Title**`) + - **Key in parentheses**: `(Key: FEATURE-XXX)` - must be uppercase, alphanumeric with hyphens/underscores + - Fields on separate lines with `-` prefix: + - `- Confidence: 0.85` (float between 0.0-1.0) + - `- Outcomes: comma-separated or line-separated list` + - `- Stories:` (required - each feature must have at least one story) +3. **Stories Format**: + - Numbered list under `Stories:` section: `1. Story title` + - **Indentation**: Stories must be indented (2-4 spaces) under the feature + - **Acceptance Criteria**: `- Acceptance: criterion1, criterion2, criterion3` + - Can be comma-separated on one line + - Or multi-line (each criterion on new line) + - Must start with `- Acceptance:` +4. **Optional Sections**: + - `## Confidence Adjustments`: List existing features with confidence updates + - `## Business Context`: Priorities, constraints, risks (bullet points) +5. **File Naming**: `<bundle-name>-<timestamp>.enrichment.md` (e.g., `djangogoat-2025-12-23T23-50-00.enrichment.md`) + +**Example** (working format): + +```markdown +## Missing Features + +1. **User Authentication** (Key: FEATURE-USER-AUTHENTICATION) + - Confidence: 0.85 + - Outcomes: User registration, login, profile management + - Stories: + 1. User can sign up for new account + - Acceptance: sign_up view processes POST requests, creates User automatically, user is logged in after signup, redirects to profile page + 2. User can log in with credentials + - Acceptance: log_in view authenticates username/password, on success user is logged in and redirected, on failure error message is displayed +``` + +**Common Mistakes to Avoid**: + +- ❌ Missing `(Key: FEATURE-XXX)` - parser needs this to identify features +- ❌ Missing `Stories:` section - every feature must have at least one story +- ❌ Stories not indented - parser expects indented numbered lists +- ❌ Missing `- Acceptance:` prefix - acceptance criteria won't be parsed +- ❌ Using bullet points (`-`) instead of numbers (`1.`) for stories +- ❌ Feature title not in bold (`**Title**`) - parser may not extract title correctly + +## Context + +{ARGS} diff --git a/packages/specfact-project/resources/prompts/specfact.04-sdd.md b/packages/specfact-project/resources/prompts/specfact.04-sdd.md new file mode 100644 index 0000000..6e40699 --- /dev/null +++ b/packages/specfact-project/resources/prompts/specfact.04-sdd.md @@ -0,0 +1,160 @@ +--- +description: Create or update SDD manifest (hard spec) from project bundle with WHY/WHAT/HOW extraction. +--- + +# SpecFact SDD Creation Command + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Purpose + +Create/update SDD manifest from project bundle. Captures WHY (intent/constraints), WHAT (capabilities/acceptance), HOW (architecture/invariants/contracts). + +**When to use:** After plan review, before promotion, when plan changes. + +**Quick:** `/specfact.04-sdd` (uses active plan) or `/specfact.04-sdd legacy-api` + +## Parameters + +### Target/Input + +- `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`) +- `--sdd PATH` - Output SDD manifest path. Default: bundle-specific .specfact/projects/<bundle-name>/sdd.<format> (Phase 8.5) + +### Output/Results + +- `--output-format FORMAT` - SDD manifest format (yaml or json). Default: global --output-format (yaml) + +### Behavior/Options + +- `--interactive/--no-interactive` - Interactive mode with prompts. Default: True (interactive, auto-detect) + +## Workflow + +### Step 1: Parse Arguments + +- Extract bundle name (defaults to active plan if not specified) +- Extract optional parameters (sdd path, output format, etc.) + +### Step 2: Execute CLI + +```bash +specfact plan harden [<bundle-name>] [--sdd <path>] [--output-format <format>] +# Uses active plan if bundle not specified +``` + +### Step 3: Present Results + +- Display SDD location, WHY/WHAT/HOW summary, coverage metrics +- Hash excludes clarifications (stable across review sessions) + +## CLI Enforcement + +**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details. + +**Rules:** + +- Execute CLI first - never create artifacts directly +- Use `--no-interactive` flag in CI/CD environments +- Never modify `.specfact/` directly +- Use CLI output as grounding for validation +- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only) + +## Dual-Stack Workflow (Copilot Mode) + +When in copilot mode, follow this three-phase workflow: + +### Phase 1: CLI Grounding (REQUIRED) + +```bash +# Execute CLI to get structured output +specfact plan harden [<bundle-name>] [--sdd <path>] --no-interactive +``` + +**Capture**: + +- CLI-generated SDD manifest +- Metadata (hash, coverage metrics) +- Telemetry (execution time, file counts) + +### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only) + +**Purpose**: Add semantic understanding to SDD content + +**What to do**: + +- Read CLI-generated SDD (use file reading tools for display only) +- Treat CLI SDD as the source of truth; scan codebase only to enrich WHY/WHAT/HOW context +- Research codebase for additional context +- Suggest improvements to WHY/WHAT/HOW sections + +**What NOT to do**: + +- ❌ Create YAML/JSON artifacts directly +- ❌ Modify CLI artifacts directly (use CLI commands to update) +- ❌ Bypass CLI validation +- ❌ Write to `.specfact/` folder directly (always use CLI) + +**Output**: Generate enrichment report (Markdown) with suggestions + +### Phase 3: CLI Artifact Creation (REQUIRED) + +```bash +# Use enrichment to update plan via CLI, then regenerate SDD +specfact plan update-idea [--bundle <name>] [options] --no-interactive +specfact plan harden [<bundle-name>] --no-interactive +``` + +**Result**: Final SDD is CLI-generated with validated enrichments + +**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code)) + +## Expected Output + +### Success + +```text +✓ SDD manifest created: .specfact/projects/legacy-api/sdd.yaml + +SDD Manifest Summary: +Project Bundle: .specfact/projects/legacy-api/ +Bundle Hash: abc123def456... +SDD Path: .specfact/projects/legacy-api/sdd.yaml + +WHY (Intent): + Build secure authentication system +Constraints: 2 + +WHAT (Capabilities): 12 + +HOW (Architecture): + Microservices architecture with JWT tokens... +Invariants: 8 +Contracts: 15 +``` + +### Error (Missing Bundle) + +```text +✗ Project bundle 'legacy-api' not found +Create one with: specfact plan init legacy-api +``` + +## Common Patterns + +```bash +/specfact.04-sdd # Uses active plan +/specfact.04-sdd legacy-api # Specific bundle +/specfact.04-sdd --output-format json # JSON format +/specfact.04-sdd --sdd .specfact/projects/custom-bundle/sdd.yaml +``` + +## Context + +{ARGS} diff --git a/packages/specfact-project/resources/prompts/specfact.06-sync.md b/packages/specfact-project/resources/prompts/specfact.06-sync.md new file mode 100644 index 0000000..4902781 --- /dev/null +++ b/packages/specfact-project/resources/prompts/specfact.06-sync.md @@ -0,0 +1,202 @@ +--- +description: Sync changes between external tool artifacts and SpecFact using bridge architecture. +--- + +# SpecFact Sync Command + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Purpose + +Synchronize artifacts from external tools (Spec-Kit, Linear, Jira) with SpecFact project bundles using bridge mappings. Supports bidirectional sync. + +**When to use:** Syncing with Spec-Kit, integrating external tools, maintaining consistency. + +**Quick:** `/specfact.06-sync --adapter speckit --repo . --bidirectional` or `/specfact.06-sync --bundle legacy-api --watch` + +## Parameters + +### Target/Input + +- `--repo PATH` - Path to repository. Default: current directory (.) +- `--bundle NAME` - Project bundle name for SpecFact → tool conversion. Default: auto-detect + +### Behavior/Options + +- `--bidirectional` - Enable bidirectional sync (tool ↔ SpecFact). Default: False +- `--overwrite` - Overwrite existing tool artifacts. Default: False +- `--watch` - Watch mode for continuous sync. Default: False +- `--ensure-compliance` - Validate and auto-enrich for tool compliance. Default: False + +### Advanced/Configuration + +- `--adapter TYPE` - Adapter type (speckit, generic-markdown, openspec, github, ado). Default: auto-detect +- `--interval SECONDS` - Watch interval in seconds. Default: 5 (range: 1+) + +**GitHub Adapter Options (for backlog sync):** + +- `--repo-owner OWNER` - GitHub repository owner (required for GitHub backlog sync) +- `--repo-name NAME` - GitHub repository name (required for GitHub backlog sync) +- `--github-token TOKEN` - GitHub API token (optional, uses GITHUB_TOKEN env var or gh CLI if not provided) +- `--use-gh-cli/--no-gh-cli` - Use GitHub CLI (`gh auth token`) to get token automatically (default: True) + +**Azure DevOps Adapter Options (for backlog sync):** + +- `--ado-org ORG` - Azure DevOps organization (required for ADO backlog sync) +- `--ado-project PROJECT` - Azure DevOps project (required for ADO backlog sync) +- `--ado-base-url URL` - Azure DevOps base URL (optional, defaults to <https://dev.azure.com>). Use for Azure DevOps Server (on-prem) +- `--ado-token TOKEN` - Azure DevOps PAT (optional, uses AZURE_DEVOPS_TOKEN env var if not provided) +- `--ado-work-item-type TYPE` - Azure DevOps work item type (optional, derived from process template if not provided) + +## Workflow + +### Step 1: Parse Arguments + +- Extract repository path (default: current directory) +- Extract adapter type (default: auto-detect) +- Extract sync options (bidirectional, overwrite, watch, etc.) + +### Step 2: Execute CLI + +```bash +# Spec-Kit adapter (default) +specfact sync bridge --adapter speckit --repo <path> [--bidirectional] [--bundle <name>] [--overwrite] [--watch] [--interval <seconds>] + +# GitHub adapter (for backlog sync) +specfact sync bridge --adapter github --repo <path> --repo-owner <owner> --repo-name <name> [--bidirectional] [--bundle <name>] [--github-token <token>] [--use-gh-cli] + +# Azure DevOps adapter (for backlog sync) +specfact sync bridge --adapter ado --repo <path> --ado-org <org> --ado-project <project> [--bidirectional] [--bundle <name>] [--ado-token <token>] [--ado-base-url <url>] + +# --bundle defaults to active plan if not specified +``` + +### Step 3: Present Results + +- Display sync direction and adapter used +- Show artifacts synchronized +- Present conflict resolution (if any) +- Indicate watch status (if enabled) + +## CLI Enforcement + +**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details. + +**Rules:** + +- Execute CLI first - never create artifacts directly +- Use `--no-interactive` flag in CI/CD environments +- Never modify `.specfact/` or `.specify/` directly +- Use CLI output as grounding for validation +- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only) + +## Dual-Stack Workflow (Copilot Mode) + +When in copilot mode, follow this three-phase workflow: + +### Phase 1: CLI Grounding (REQUIRED) + +```bash +# Execute CLI to get structured output +specfact sync bridge --adapter <adapter> --repo <path> [options] --no-interactive +``` + +**Capture**: + +- CLI-generated sync results +- Artifacts synchronized +- Conflict resolution status + +### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only) + +**Purpose**: Add semantic understanding to sync results + +**What to do**: + +- Read CLI-generated sync results (use file reading tools for display only) +- Treat CLI sync output as the source of truth; scan codebase only to explain conflicts +- Research codebase for context on conflicts +- Suggest resolution strategies + +**What NOT to do**: + +- ❌ Create YAML/JSON artifacts directly +- ❌ Modify CLI artifacts directly (use CLI commands to update) +- ❌ Bypass CLI validation +- ❌ Write to `.specfact/` or `.specify/` folders directly (always use CLI) + +**Output**: Generate conflict resolution suggestions (Markdown) + +### Phase 3: CLI Artifact Creation (REQUIRED) + +```bash +# Apply resolutions via CLI commands, then re-sync +specfact plan update-feature [--bundle <name>] [options] --no-interactive +specfact sync bridge --adapter <adapter> --repo <path> --no-interactive +``` + +**Result**: Final artifacts are CLI-generated with validated resolutions + +**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code)) + +## Expected Output + +### Success + +```text +✓ Sync complete: Spec-Kit ↔ SpecFact (bidirectional) + +Adapter: speckit +Repository: /path/to/repo + +Artifacts Synchronized: + - Spec-Kit → SpecFact: 12 features, 45 stories + - SpecFact → Spec-Kit: 3 new features, 8 updated stories + +Conflicts Resolved: 2 +``` + +### Error (Missing Adapter) + +```text +✗ Unsupported adapter: invalid-adapter +Supported adapters: speckit, generic-markdown, openspec, github, ado +``` + +### Error (Missing Required Parameters) + +```text +✗ GitHub adapter requires both --repo-owner and --repo-name options +Example: specfact sync bridge --adapter github --repo-owner 'nold-ai' --repo-name 'specfact-cli' --bidirectional +``` + +```text +✗ Azure DevOps adapter requires both --ado-org and --ado-project options +Example: specfact sync bridge --adapter ado --ado-org 'my-org' --ado-project 'my-project' --bidirectional +``` + +## Common Patterns + +```bash +# Spec-Kit adapter +/specfact.06-sync --adapter speckit --repo . --bidirectional +/specfact.06-sync --adapter speckit --repo . --bundle legacy-api +/specfact.06-sync --adapter speckit --repo . --watch --interval 5 +/specfact.06-sync --repo . --bidirectional # Auto-detect adapter + +# GitHub adapter (backlog sync) +/specfact.06-sync --adapter github --repo . --repo-owner nold-ai --repo-name specfact-cli --bidirectional + +# Azure DevOps adapter (backlog sync) +/specfact.06-sync --adapter ado --repo . --ado-org my-org --ado-project my-project --bidirectional +``` + +## Context + +{ARGS} diff --git a/packages/specfact-project/resources/prompts/specfact.compare.md b/packages/specfact-project/resources/prompts/specfact.compare.md new file mode 100644 index 0000000..637c198 --- /dev/null +++ b/packages/specfact-project/resources/prompts/specfact.compare.md @@ -0,0 +1,159 @@ +--- +description: Compare manual and auto-derived plans to detect code vs plan drift and deviations. +--- + +# SpecFact Compare Command + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Purpose + +Compare two project bundles (or legacy plan bundles) to detect deviations, mismatches, and missing features. Identifies code vs plan drift. + +**When to use:** After import to compare with manual plan, detecting spec/implementation drift, validating completeness. + +**Quick:** `/specfact.compare --bundle legacy-api` or `/specfact.compare --code-vs-plan` + +## Parameters + +### Target/Input + +- `--bundle NAME` - Project bundle name. If specified, compares bundles instead of legacy plan files. Default: None +- `--manual PATH` - Manual plan bundle path. Default: active plan in .specfact/plans. Ignored if --bundle specified +- `--auto PATH` - Auto-derived plan bundle path. Default: latest in .specfact/plans/. Ignored if --bundle specified + +### Output/Results + +- `--output-format FORMAT` - Output format (markdown, json, yaml). Default: markdown +- `--out PATH` - Output file path. Default: bundle-specific .specfact/projects/<bundle-name>/reports/comparison/report-<timestamp>.md (Phase 8.5), or global .specfact/reports/comparison/ if no bundle context + +### Behavior/Options + +- `--code-vs-plan` - Alias for comparing code-derived plan vs manual plan. Default: False + +## Workflow + +### Step 1: Parse Arguments + +- Extract comparison targets (bundle, manual plan, auto plan) +- Determine comparison mode (bundle vs bundle, or legacy plan files) + +### Step 2: Execute CLI + +```bash +specfact plan compare [--bundle <bundle-name>] [--manual <path>] [--auto <path>] [--code-vs-plan] [--output-format <format>] [--out <path>] +# --bundle defaults to active plan if not specified +``` + +### Step 3: Present Results + +- Display deviation summary (by type and severity) +- Show missing features in each plan +- Present drift analysis +- Indicate comparison report location + +## CLI Enforcement + +**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details. + +**Rules:** + +- Execute CLI first - never create artifacts directly +- Use `--no-interactive` flag in CI/CD environments +- Never modify `.specfact/` directly +- Use CLI output as grounding for validation +- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only) + +## Dual-Stack Workflow (Copilot Mode) + +When in copilot mode, follow this three-phase workflow: + +### Phase 1: CLI Grounding (REQUIRED) + +```bash +# Execute CLI to get structured output +specfact plan compare [--bundle <name>] [options] --no-interactive +``` + +**Capture**: + +- CLI-generated comparison report +- Deviation counts and severity +- Missing features analysis + +### Phase 2: LLM Enrichment (OPTIONAL, Copilot Only) + +**Purpose**: Add semantic understanding to comparison results + +**What to do**: + +- Read CLI-generated comparison report (use file reading tools for display only) +- Treat the comparison report as the source of truth; scan codebase only to explain or confirm deviations +- Research codebase for context on deviations +- Suggest fixes for missing features or mismatches + +**What NOT to do**: + +- ❌ Create YAML/JSON artifacts directly +- ❌ Modify CLI artifacts directly (use CLI commands to update) +- ❌ Bypass CLI validation +- ❌ Write to `.specfact/` folder directly (always use CLI) + +**Output**: Generate fix suggestions report (Markdown) + +### Phase 3: CLI Artifact Creation (REQUIRED) + +```bash +# Apply fixes via CLI commands, then re-compare +specfact plan update-feature [--bundle <name>] [options] --no-interactive +specfact plan compare [--bundle <name>] --no-interactive +``` + +**Result**: Final artifacts are CLI-generated with validated fixes + +**Note**: If code generation is needed, use the validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code)) + +## Expected Output + +### Success + +```text +✓ Comparison complete + +Comparison Report: .specfact/projects/<bundle-name>/reports/comparison/report-2025-11-26T10-30-00.md + +Deviations Summary: + Total: 5 + High: 1 (Missing Feature) + Medium: 3 (Feature Mismatch) + Low: 1 (Story Difference) + +Missing in Manual Plan: 2 features +Missing in Auto Plan: 1 feature +``` + +### Error (Missing Plans) + +```text +✗ Default manual plan not found: .specfact/plans/main.bundle.yaml +Create one with: specfact plan init --interactive +``` + +## Common Patterns + +```bash +/specfact.compare --bundle legacy-api +/specfact.compare --code-vs-plan +/specfact.compare --manual <path> --auto <path> +/specfact.compare --code-vs-plan --output-format json +``` + +## Context + +{ARGS} diff --git a/packages/specfact-spec/module-package.yaml b/packages/specfact-spec/module-package.yaml index ddd880a..3e2bea7 100644 --- a/packages/specfact-spec/module-package.yaml +++ b/packages/specfact-spec/module-package.yaml @@ -1,5 +1,5 @@ name: nold-ai/specfact-spec -version: 0.40.14 +version: 0.40.16 commands: - spec tier: official @@ -13,5 +13,5 @@ description: Official SpecFact specification bundle package. category: spec bundle_group_command: spec integrity: - checksum: sha256:5f1bc4758088c8a3c513bb26473392bffd09cdfa40638c48170a8a3ec89feee5 - signature: ooAlA0BeZg3YteavLGXkQXvAlkWskFNj/roeCe5eRkRPu8c5JF6+pRlNQ0S4xUkRagPrapTHs+kHd/WNAVB7DQ== + checksum: sha256:28ad2375fff8965efda0e9e7816549f7ab05140a99010170d0da1607eb8f037f + signature: t9D2viaejsv6WQmAqvAFz1Ll6VXO0Q8wGwkVIvMt32amqI2MZN3++ecmeytiiTjzEGGHWQ1+xZm/zQYu51BMAg== diff --git a/packages/specfact-spec/resources/prompts/shared/cli-enforcement.md b/packages/specfact-spec/resources/prompts/shared/cli-enforcement.md new file mode 100644 index 0000000..b8aab9a --- /dev/null +++ b/packages/specfact-spec/resources/prompts/shared/cli-enforcement.md @@ -0,0 +1,119 @@ +# CLI Usage Enforcement Rules + +## Core Principle + +**ALWAYS use SpecFact CLI commands. Never create artifacts directly.** + +## CLI vs LLM Capabilities + +### CLI-Only Operations (CI/CD Mode - No LLM Required) + +The CLI can perform these operations **without LLM**: + +- ✅ Tool execution (ruff, pylint, basedpyright, mypy, semgrep, specmatic) +- ✅ Bundle management (create, load, save, validate structure) +- ✅ Metadata management (timestamps, hashes, telemetry) +- ✅ Planning operations (init, add-feature, add-story, update-idea, update-feature) +- ✅ AST/Semgrep-based analysis (code structure, patterns, relationships) +- ✅ Specmatic validation (OpenAPI/AsyncAPI contract validation) +- ✅ Format validation (YAML/JSON schema compliance) +- ✅ Source tracking and drift detection + +**CRITICAL LIMITATIONS**: + +- ❌ **CANNOT generate code** - No LLM available in CLI-only mode +- ❌ **CANNOT do reasoning** - No semantic understanding without LLM + +### LLM-Required Operations (AI IDE Mode - Via Slash Prompts) + +These operations **require LLM** and are only available via AI IDE slash prompts: + +- ✅ Code generation (requires LLM reasoning) +- ✅ Code enhancement (contracts, refactoring, improvements) +- ✅ Semantic understanding (business logic, context, priorities) +- ✅ Plan enrichment (missing features, confidence adjustments, business context) +- ✅ Code reasoning (why decisions were made, trade-offs, constraints) + +**Access**: Only available via AI IDE slash prompts (Cursor, CoPilot, etc.) +**Pattern**: Slash prompt → LLM generates → CLI validates → Apply if valid + +## LLM Grounding Rules + +- Treat CLI artifacts as the source of truth for keys, structure, and metadata. +- Scan the codebase only when asked to infer missing behavior/context or explain deviations; respect `--entry-point` scope when provided. +- Use codebase findings to propose updates via CLI (enrichment report, plan update commands), never to rewrite artifacts directly. + +## Rules + +1. **Execute CLI First**: Always run CLI commands before any analysis +2. **Use CLI for Writes**: All write operations must go through CLI +3. **Read for Display Only**: Use file reading tools for display/analysis only +4. **Never Modify .specfact/**: Do not create/modify files in `.specfact/` directly +5. **Never Bypass Validation**: CLI ensures schema compliance and metadata +6. **Code Generation Requires LLM**: Code generation is only possible via AI IDE slash prompts, not CLI-only + +## Standard Validation Loop Pattern (For LLM-Generated Code) + +When generating or enhancing code via LLM, **ALWAYS** follow this pattern: + +```text +1. CLI Prompt Generation (Required) + ↓ + CLI generates structured prompt → saved to .specfact/prompts/ + (e.g., `generate contracts-prompt`, future: `generate code-prompt`) + +2. LLM Execution (Required - AI IDE Only) + ↓ + LLM reads prompt → generates enhanced code → writes to TEMPORARY file + (NEVER writes directly to original artifacts) + Pattern: `enhanced_<filename>.py` or `generated_<feature>.py` + +3. CLI Validation Loop (Required, up to N retries) + ↓ + CLI validates temp file with all relevant tools: + - Syntax validation (py_compile) + - File size check (must be >= original) + - AST structure comparison (preserve functions/classes) + - Contract imports verification + - Code quality checks (ruff, pylint, basedpyright, mypy) + - Test execution (contract-test, pytest) + ↓ + If validation fails: + - CLI provides detailed error feedback + - LLM fixes issues in temp file + - Re-validate (max 3 attempts) + ↓ + If validation succeeds: + - CLI applies changes to original file + - CLI removes temporary file + - CLI updates metadata/telemetry +``` + +**This pattern must be used for**: + +- ✅ Contract enhancement (`generate contracts-prompt` / `contracts-apply`) - Already implemented +- ⏳ Code generation (future: `generate code-prompt` / `code-apply`) - Needs implementation +- ⏳ Plan enrichment (future: `plan enrich-prompt` / `enrich-apply`) - Needs implementation +- ⏳ Any LLM-enhanced artifact modification - Needs implementation + +## What Happens If You Don't Follow + +- ❌ Artifacts may not match CLI schema versions +- ❌ Missing metadata and telemetry +- ❌ Format inconsistencies +- ❌ Validation failures +- ❌ Works only in Copilot mode, fails in CI/CD +- ❌ Code generation attempts in CLI-only mode will fail (no LLM available) + +## Available CLI Commands + +- `specfact plan init <bundle-name>` - Initialize project bundle +- `specfact plan select <bundle-name>` - Set active plan (used as default for other commands) +- `specfact code import [<bundle-name>] --repo <path>` - Import from codebase (uses active plan if bundle not specified) +- `specfact plan review [<bundle-name>]` - Review plan (uses active plan if bundle not specified) +- `specfact plan harden [<bundle-name>]` - Create SDD manifest (uses active plan if bundle not specified) +- `specfact enforce sdd [<bundle-name>]` - Validate SDD (uses active plan if bundle not specified) +- `specfact sync bridge --adapter <adapter> --repo <path>` - Sync with external tools +- See [Command Reference](../../docs/reference/commands.md) for full list + +**Note**: Most commands now support active plan fallback. If `--bundle` is not specified, commands automatically use the active plan set via `plan select`. This improves workflow efficiency in AI IDE environments. diff --git a/packages/specfact-spec/resources/prompts/specfact.07-contracts.md b/packages/specfact-spec/resources/prompts/specfact.07-contracts.md new file mode 100644 index 0000000..0511859 --- /dev/null +++ b/packages/specfact-spec/resources/prompts/specfact.07-contracts.md @@ -0,0 +1,364 @@ +--- +description: Analyze contract coverage, generate enhancement prompts, and apply contracts sequentially with careful review. +--- + +# SpecFact Contract Enhancement Workflow + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Purpose + +Complete contract enhancement workflow: analyze coverage → generate prompts → apply contracts sequentially with careful review. + +**When to use:** After codebase analysis, when adding contracts to existing code, improving contract coverage. + +**Quick:** `/specfact.07-contracts` (uses active plan) or `/specfact.07-contracts legacy-api` + +## Parameters + +### Target/Input + +- `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`) +- `--repo PATH` - Repository path. Default: current directory (.) +- `--apply CONTRACTS` - Contract types to apply: 'all-contracts', 'beartype', 'icontract', 'crosshair', or comma-separated list. Default: 'all-contracts' +- `--min-priority PRIORITY` - Minimum priority for files to process: 'high', 'medium', 'low'. Default: 'low' (process all files missing contracts) + +### Behavior/Options + +- `--no-interactive` - Non-interactive mode (for CI/CD). Default: False (interactive mode with careful review) +- `--auto-apply` - Automatically apply contracts after validation (skips confirmation). Default: False (requires confirmation) +- `--batch-size INT` - Number of files to process before pausing for review. Default: 1 (one file at a time for careful review) + +## Workflow + +### Step 1: Analyze Contract Coverage + +**First, identify files missing contracts:** + +```bash +specfact analyze contracts --repo <repo-path> --bundle <bundle-name> +# Uses active plan if bundle not specified +``` + +**Parse the output to identify:** + +- Files missing beartype (marked with ✗) +- Files missing icontract (marked with ✗) +- Files missing crosshair (marked with ✗ or dim ✗) +- Files that need attention (prioritized in the table) + +**Extract file list:** + +- Focus on files marked with ✗ for beartype or icontract +- Crosshair is optional (marked with dim ✗), but can be included if user requests +- Filter out pure data model files (they use Pydantic validation) + +**Present summary:** + +- Total files analyzed +- Files missing contracts (by type) +- Files recommended for enhancement + +### Step 2: Generate Enhancement Prompts + +**For each file missing contracts, generate a prompt:** + +```bash +specfact generate contracts-prompt <file-path> --apply <contract-types> --bundle <bundle-name> +``` + +**Important:** + +- Generate prompts for ALL files missing contracts (or based on --min-priority) +- Prompts are saved to `.specfact/projects/<bundle-name>/prompts/enhance-<filename>-<contracts>.md` +- If no bundle, prompts saved to `.specfact/prompts/` +- Each prompt file contains instructions for the AI IDE to enhance the file + +**Present prompt generation summary:** + +- Number of prompts generated +- Location of prompt files +- List of files ready for enhancement + +### Step 3: User Review and Selection + +**Present files for user selection:** + +```text +Files ready for contract enhancement: +1. src/auth/login.py (missing: beartype, icontract) +2. src/api/users.py (missing: beartype, icontract, crosshair) +3. src/utils/helpers.py (missing: beartype) +... + +Select files to enhance (comma-separated numbers, 'all', or 'skip'): +``` + +**Wait for user input:** + +- If user selects specific files, process only those +- If user selects 'all', process all files sequentially +- If user selects 'skip', move to next step or exit + +**In non-interactive mode:** + +- Process all files automatically (or based on --min-priority) +- Still process sequentially (one at a time) for careful validation + +### Step 4: Apply Contracts Sequentially + +**For each selected file, apply contracts one at a time:** + +**4.1: Read the prompt file:** + +```bash +# Prompt file location: .specfact/projects/<bundle-name>/prompts/enhance-<filename>-<contracts>.md +# Or: .specfact/prompts/enhance-<filename>-<contracts>.md +``` + +**4.2: Enhance the code using AI IDE:** + +- Read the original file +- Apply contracts according to the prompt instructions +- Write enhanced code to temporary file: `enhanced_<filename>.py` +- **DO NOT modify the original file directly** + +**4.3: Validate enhanced code:** + +```bash +specfact generate contracts-apply enhanced_<filename>.py --original <original-file-path> +``` + +**Validation includes:** + +- File size check +- Syntax validation +- AST structure comparison +- Contract imports verification +- Code quality checks (ruff, pylint, basedpyright, mypy if available) +- Test execution (scoped to relevant test files) + +**4.4: Handle validation results:** + +**If validation fails:** + +- Review error messages +- Fix issues in enhanced code +- Re-validate (up to 3 attempts) +- If still failing after 3 attempts, skip this file and continue to next + +**If validation succeeds:** + +- Show diff preview (what will change) +- If `--auto-apply` is False, ask for confirmation: + + ```text + Validation passed. Apply changes to <original-file>? (y/n): + ``` + +- If confirmed (or `--auto-apply` is True), apply changes automatically +- If not confirmed, skip this file and continue to next + +#### 4.5: Pause for review (if --batch-size > 1) + +After processing `--batch-size` files, pause and show summary: + +```text +Processed 3/10 files: +✓ src/auth/login.py - Contracts applied successfully +✓ src/api/users.py - Contracts applied successfully +⏭ src/utils/helpers.py - Skipped (user declined) + +Continue with next batch? (y/n): +``` + +### Step 5: Final Summary + +**After all files processed, show final summary:** + +```text +Contract Enhancement Complete + +Summary: +- Files analyzed: 25 +- Files processed: 18 +- Files enhanced: 15 +- Files skipped: 3 +- Files failed: 0 + +Enhanced files: +✓ src/auth/login.py (beartype, icontract) +✓ src/api/users.py (beartype, icontract, crosshair) +... + +Next steps: +1. Verify contract coverage: specfact analyze contracts --bundle <bundle-name> +2. Run full test suite: pytest (or your project's test command) +3. Review changes: git diff +4. Commit enhanced code +``` + +## CLI Enforcement + +**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details. + +**Rules:** + +- Execute CLI commands in sequence (analyze → generate → apply) +- Never modify `.specfact/` directly +- Always validate before applying changes +- Process files sequentially for careful review +- Use `--no-interactive` only in CI/CD environments +- Use CLI output as grounding for all operations +- Code generation requires LLM (only via AI IDE slash prompts, not CLI-only) + +## Dual-Stack Workflow (Copilot Mode) + +This command **already implements** the standard validation loop pattern (see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code)): + +### Phase 1: CLI Prompt Generation (REQUIRED) + +```bash +# CLI generates structured prompt +specfact generate contracts-prompt <file-path> --apply <contract-types> --bundle <bundle-name> +``` + +**Result**: Prompt saved to `.specfact/projects/<bundle-name>/prompts/enhance-<filename>-<contracts>.md` + +### Phase 2: LLM Execution (REQUIRED - AI IDE Only) + +- LLM reads prompt → generates enhanced code → writes to TEMPORARY file (`enhanced_<filename>.py`) +- **NEVER writes directly to original artifacts** + +### Phase 3: CLI Validation Loop (REQUIRED, up to 3 retries) + +```bash +# CLI validates temp file with all relevant tools +specfact generate contracts-apply enhanced_<filename>.py --original <original-file> +``` + +**Validation includes**: + +- Syntax validation (py_compile) +- File size check (must be >= original) +- AST structure comparison (preserve functions/classes) +- Contract imports verification +- Code quality checks (ruff, pylint, basedpyright, mypy) +- Test execution (contract-test, pytest) + +**If validation fails**: CLI provides detailed error feedback → LLM fixes → Re-validate (max 3 attempts) + +**If validation succeeds**: CLI applies changes to original file → CLI removes temporary file → CLI updates metadata/telemetry + +**This is the standard pattern for all LLM-generated code** - see [CLI Enforcement Rules](./shared/cli-enforcement.md#standard-validation-loop-pattern-for-llm-generated-code) for details. + +## Expected Output + +### Step 1: Analysis Results + +```text +Contract Coverage Analysis: legacy-api +Repository: /path/to/repo + +┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┓ +┃ File ┃ beartype ┃ icontract ┃ crosshair ┃ Coverage ┃ +┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━┩ +│ src/auth/login.py │ ✗ │ ✗ │ ✗ │ 0% │ +│ src/api/users.py │ ✗ │ ✗ │ ✗ │ 0% │ +... + +Summary: + Files analyzed: 25 + Files with beartype: 7 (28.0%) + Files with icontract: 7 (28.0%) + Files with crosshair: 2 (8.0%) + +Found 18 files missing contracts. +``` + +### Step 2: Prompt Generation + +```text +Generating enhancement prompts... + +✓ Generated prompt for: src/auth/login.py + Location: .specfact/projects/legacy-api/prompts/enhance-login.py-all-contracts.md + +✓ Generated prompt for: src/api/users.py + Location: .specfact/projects/legacy-api/prompts/enhance-users.py-all-contracts.md + +... + +✓ Generated 18 prompts successfully +``` + +### Step 3: User Selection + +```text +Files ready for contract enhancement: +1. src/auth/login.py (missing: beartype, icontract, crosshair) +2. src/api/users.py (missing: beartype, icontract, crosshair) +3. src/utils/helpers.py (missing: beartype) +... + +Select files to enhance (comma-separated numbers, 'all', or 'skip'): all +``` + +### Step 4: Sequential Application + +```text +Processing file 1/18: src/auth/login.py + +[Reading prompt file...] +[Enhancing code with AI IDE...] +[Writing enhanced code to: enhanced_login.py] + +Validating enhanced code... +✓ File size check: passed +✓ Syntax validation: passed +✓ AST structure: passed (15 definitions preserved) +✓ Contract imports: verified +✓ Code quality checks: passed (ruff, pylint) +✓ Tests: 12/12 passed + +Diff preview: ++ from beartype import beartype ++ from icontract import require, ensure +... + +Apply changes to src/auth/login.py? (y/n): y +✓ Contracts applied successfully + +[Pausing for review... Press Enter to continue to next file] +``` + +## Common Patterns + +```bash +/specfact.07-contracts # Uses active plan, all-contracts, interactive +/specfact.07-contracts legacy-api # Specific bundle +/specfact.07-contracts --apply beartype,icontract # Specific contract types +/specfact.07-contracts --min-priority high # Only high-priority files +/specfact.07-contracts --batch-size 3 # Process 3 files before pausing +/specfact.07-contracts --auto-apply # Auto-apply after validation (no confirmation) +/specfact.07-contracts --no-interactive # CI/CD mode (still sequential for safety) +``` + +## Important Notes + +1. **Sequential Processing**: Files are processed one at a time (or in small batches) to allow careful review +2. **Validation Required**: All enhanced code must pass validation before applying +3. **User Control**: User can skip files, pause between files, or stop the process +4. **Data Model Files**: Pure Pydantic/dataclass files are automatically excluded (they use Pydantic validation) +5. **Prompt Location**: Prompts are saved to bundle-specific directories when bundle is provided +6. **Temporary Files**: Enhanced code is written to temporary files (`enhanced_<filename>.py`) for validation before applying + +## Context + +{ARGS} diff --git a/registry/index.json b/registry/index.json index fec36af..1ce7815 100644 --- a/registry/index.json +++ b/registry/index.json @@ -2,9 +2,9 @@ "modules": [ { "id": "nold-ai/specfact-project", - "latest_version": "0.40.21", - "download_url": "modules/specfact-project-0.40.21.tar.gz", - "checksum_sha256": "d64015312bf129068c11345eec371ba503714db3e91a9f92b5a97072ba57312f", + "latest_version": "0.40.23", + "download_url": "modules/specfact-project-0.40.23.tar.gz", + "checksum_sha256": "6a75ab583e5f54122b457aeda6c81019a5575fccb8f4d61d14c11a69a0435ae3", "tier": "official", "publisher": { "name": "nold-ai", @@ -15,9 +15,9 @@ }, { "id": "nold-ai/specfact-backlog", - "latest_version": "0.41.12", - "download_url": "modules/specfact-backlog-0.41.12.tar.gz", - "checksum_sha256": "28f6a30868b42fdd1928a035aa30c78e6d1230c0c768bfa17dff6a6b269a8907", + "latest_version": "0.41.14", + "download_url": "modules/specfact-backlog-0.41.14.tar.gz", + "checksum_sha256": "124b51ee51f5dd91453f38708a662c2b65527be02e0dacde302da64cce1d8968", "tier": "official", "publisher": { "name": "nold-ai", @@ -28,9 +28,9 @@ }, { "id": "nold-ai/specfact-codebase", - "latest_version": "0.41.1", - "download_url": "modules/specfact-codebase-0.41.1.tar.gz", - "checksum_sha256": "565cb4dbad429c9cc348dce343f46b177d636082db121aa4cd72174f39cd29c9", + "latest_version": "0.41.3", + "download_url": "modules/specfact-codebase-0.41.3.tar.gz", + "checksum_sha256": "389a2d0095bbcc670857b6f20e6716402e5b4e0622155cc7d602eb44093fcb6e", "tier": "official", "publisher": { "name": "nold-ai", @@ -43,9 +43,9 @@ }, { "id": "nold-ai/specfact-spec", - "latest_version": "0.40.14", - "download_url": "modules/specfact-spec-0.40.14.tar.gz", - "checksum_sha256": "e2e47b514449f2e0636847d574f911d513343da9cb0be0942d3194f1edcd45c2", + "latest_version": "0.40.16", + "download_url": "modules/specfact-spec-0.40.16.tar.gz", + "checksum_sha256": "5daf94c624df09bf04ddf55df3f79cf1e98fdddd2fd6be254a5155746f913d4a", "tier": "official", "publisher": { "name": "nold-ai", @@ -58,9 +58,9 @@ }, { "id": "nold-ai/specfact-govern", - "latest_version": "0.40.17", - "download_url": "modules/specfact-govern-0.40.17.tar.gz", - "checksum_sha256": "7564e1ee44386dffde50fb9099cbc27e37bfcd19943039035e889655be53d9d5", + "latest_version": "0.40.19", + "download_url": "modules/specfact-govern-0.40.19.tar.gz", + "checksum_sha256": "5406ba35bf516e5d47fa59674ca63438caf345a03729ca28fc23c98edb370caf", "tier": "official", "publisher": { "name": "nold-ai", diff --git a/registry/modules/specfact-backlog-0.41.14.tar.gz b/registry/modules/specfact-backlog-0.41.14.tar.gz new file mode 100644 index 0000000..807ab11 Binary files /dev/null and b/registry/modules/specfact-backlog-0.41.14.tar.gz differ diff --git a/registry/modules/specfact-backlog-0.41.14.tar.gz.sha256 b/registry/modules/specfact-backlog-0.41.14.tar.gz.sha256 new file mode 100644 index 0000000..52ea88e --- /dev/null +++ b/registry/modules/specfact-backlog-0.41.14.tar.gz.sha256 @@ -0,0 +1 @@ +124b51ee51f5dd91453f38708a662c2b65527be02e0dacde302da64cce1d8968 diff --git a/registry/modules/specfact-codebase-0.41.3.tar.gz b/registry/modules/specfact-codebase-0.41.3.tar.gz new file mode 100644 index 0000000..e74f282 Binary files /dev/null and b/registry/modules/specfact-codebase-0.41.3.tar.gz differ diff --git a/registry/modules/specfact-codebase-0.41.3.tar.gz.sha256 b/registry/modules/specfact-codebase-0.41.3.tar.gz.sha256 new file mode 100644 index 0000000..5e1403d --- /dev/null +++ b/registry/modules/specfact-codebase-0.41.3.tar.gz.sha256 @@ -0,0 +1 @@ +389a2d0095bbcc670857b6f20e6716402e5b4e0622155cc7d602eb44093fcb6e diff --git a/registry/modules/specfact-govern-0.40.19.tar.gz b/registry/modules/specfact-govern-0.40.19.tar.gz new file mode 100644 index 0000000..25e54a6 Binary files /dev/null and b/registry/modules/specfact-govern-0.40.19.tar.gz differ diff --git a/registry/modules/specfact-govern-0.40.19.tar.gz.sha256 b/registry/modules/specfact-govern-0.40.19.tar.gz.sha256 new file mode 100644 index 0000000..293227e --- /dev/null +++ b/registry/modules/specfact-govern-0.40.19.tar.gz.sha256 @@ -0,0 +1 @@ +5406ba35bf516e5d47fa59674ca63438caf345a03729ca28fc23c98edb370caf diff --git a/registry/modules/specfact-project-0.40.23.tar.gz b/registry/modules/specfact-project-0.40.23.tar.gz new file mode 100644 index 0000000..c7473fe Binary files /dev/null and b/registry/modules/specfact-project-0.40.23.tar.gz differ diff --git a/registry/modules/specfact-project-0.40.23.tar.gz.sha256 b/registry/modules/specfact-project-0.40.23.tar.gz.sha256 new file mode 100644 index 0000000..f85fc30 --- /dev/null +++ b/registry/modules/specfact-project-0.40.23.tar.gz.sha256 @@ -0,0 +1 @@ +6a75ab583e5f54122b457aeda6c81019a5575fccb8f4d61d14c11a69a0435ae3 diff --git a/registry/modules/specfact-spec-0.40.16.tar.gz b/registry/modules/specfact-spec-0.40.16.tar.gz new file mode 100644 index 0000000..ba1d561 Binary files /dev/null and b/registry/modules/specfact-spec-0.40.16.tar.gz differ diff --git a/registry/modules/specfact-spec-0.40.16.tar.gz.sha256 b/registry/modules/specfact-spec-0.40.16.tar.gz.sha256 new file mode 100644 index 0000000..96d602f --- /dev/null +++ b/registry/modules/specfact-spec-0.40.16.tar.gz.sha256 @@ -0,0 +1 @@ +5daf94c624df09bf04ddf55df3f79cf1e98fdddd2fd6be254a5155746f913d4a diff --git a/registry/signatures/specfact-backlog-0.41.14.tar.sig b/registry/signatures/specfact-backlog-0.41.14.tar.sig new file mode 100644 index 0000000..ec10d66 --- /dev/null +++ b/registry/signatures/specfact-backlog-0.41.14.tar.sig @@ -0,0 +1 @@ +eQ86/44q9ZKUkkNIv/HzyZ7Oc3QXPyPZLpFtoMMTF5QjWWbE1RFntJs/8BWKHniV23iJnRUBlBnm4YIP30UQAQ== diff --git a/registry/signatures/specfact-codebase-0.41.3.tar.sig b/registry/signatures/specfact-codebase-0.41.3.tar.sig new file mode 100644 index 0000000..769bfea --- /dev/null +++ b/registry/signatures/specfact-codebase-0.41.3.tar.sig @@ -0,0 +1 @@ +VMeonMTm8x/ZFn8CBzr6mcZHi0WcldLMiAQl1Ihhs6DuwK+cF1BI/U+G05j21rbdPE9+5qZyZ5QZVEj4V3yECQ== diff --git a/registry/signatures/specfact-govern-0.40.19.tar.sig b/registry/signatures/specfact-govern-0.40.19.tar.sig new file mode 100644 index 0000000..1a4fb88 --- /dev/null +++ b/registry/signatures/specfact-govern-0.40.19.tar.sig @@ -0,0 +1 @@ +N90cvb+lukJwUwGyVoj8ofmO8N3unlE13PQ5hYhMaDBdYQVMSY/9OL9TC8RLF+0LBSsRJ2IQ00188ZXRZWi1BA== diff --git a/registry/signatures/specfact-project-0.40.23.tar.sig b/registry/signatures/specfact-project-0.40.23.tar.sig new file mode 100644 index 0000000..329ba28 --- /dev/null +++ b/registry/signatures/specfact-project-0.40.23.tar.sig @@ -0,0 +1 @@ +ouJhKYaOvbl8xI6fDlVZd3B4xoNLx4AJ4yvLvhsbktenHj7ToFFostOcfnuhP8mVB2i0iiqEOnUPiWb3vG6UBw== diff --git a/registry/signatures/specfact-spec-0.40.16.tar.sig b/registry/signatures/specfact-spec-0.40.16.tar.sig new file mode 100644 index 0000000..25a97ed --- /dev/null +++ b/registry/signatures/specfact-spec-0.40.16.tar.sig @@ -0,0 +1 @@ +t9D2viaejsv6WQmAqvAFz1Ll6VXO0Q8wGwkVIvMt32amqI2MZN3++ecmeytiiTjzEGGHWQ1+xZm/zQYu51BMAg== diff --git a/tests/unit/test_bundle_resource_payloads.py b/tests/unit/test_bundle_resource_payloads.py new file mode 100644 index 0000000..02587cc --- /dev/null +++ b/tests/unit/test_bundle_resource_payloads.py @@ -0,0 +1,138 @@ +"""Official bundles ship audited prompt and backlog template resources at stable paths.""" + +from __future__ import annotations + +import hashlib +from pathlib import Path + +import pytest +import yaml + +from tests.unit._script_test_utils import load_module_from_path + + +REPO_ROOT = Path(__file__).resolve().parents[2] +SIGN_SCRIPT = REPO_ROOT / "scripts" / "sign-modules.py" + + +_EXPECTED_PROMPTS: dict[str, tuple[str, ...]] = { + "specfact-codebase": ( + "specfact.01-import.md", + "specfact.validate.md", + ), + "specfact-project": ( + "specfact.02-plan.md", + "specfact.03-review.md", + "specfact.04-sdd.md", + "specfact.06-sync.md", + "specfact.compare.md", + ), + "specfact-govern": ("specfact.05-enforce.md",), + "specfact-spec": ("specfact.07-contracts.md",), +} + +_COMPANION = "shared/cli-enforcement.md" + +_FIELD_MAPPING_SEEDS = ( + "ado_agile.yaml", + "ado_custom.yaml", + "ado_default.yaml", + "ado_kanban.yaml", + "ado_safe.yaml", + "ado_scrum.yaml", + "github_custom.yaml", +) + + +@pytest.mark.parametrize("bundle,prompts", list(_EXPECTED_PROMPTS.items())) +def test_official_bundles_package_expected_prompt_files(bundle: str, prompts: tuple[str, ...]) -> None: + root = REPO_ROOT / "packages" / bundle / "resources" / "prompts" + for name in prompts: + path = root / name + assert path.is_file(), f"missing prompt {path}" + companion = root / _COMPANION + assert companion.is_file(), f"missing companion {companion}" + + +def test_prompt_companion_resolves_relative_to_prompt_root() -> None: + """IDE/export layouts preserve ./shared/cli-enforcement.md next to prompt files.""" + for bundle, names in _EXPECTED_PROMPTS.items(): + first = REPO_ROOT / "packages" / bundle / "resources" / "prompts" / names[0] + text = first.read_text(encoding="utf-8") + if "./shared/cli-enforcement.md" in text: + companion = REPO_ROOT / "packages" / bundle / "resources" / "prompts" / "shared" / "cli-enforcement.md" + assert companion.is_file(), bundle + + +def test_backlog_bundle_packages_field_mapping_seed_set() -> None: + module_root = REPO_ROOT / "packages" / "specfact-backlog" + roots = ( + module_root / "resources" / "templates" / "backlog" / "field_mappings", + module_root / "src" / "specfact_backlog" / "resources" / "templates" / "backlog" / "field_mappings", + ) + for name in _FIELD_MAPPING_SEEDS: + for base in roots: + path = base / name + assert path.is_file(), f"missing field mapping seed {path}" + + +def test_github_custom_seed_includes_bug_parent_hierarchy() -> None: + """Aligns packaged seed with map-fields defaults so bugs keep valid parent constraints after init copy.""" + module_root = REPO_ROOT / "packages" / "specfact-backlog" + expected_bug = ["story", "feature", "epic"] + for rel in ( + "resources/templates/backlog/field_mappings/github_custom.yaml", + "src/specfact_backlog/resources/templates/backlog/field_mappings/github_custom.yaml", + ): + data = yaml.safe_load((module_root / rel).read_text(encoding="utf-8")) + ch = data.get("creation_hierarchy") or {} + assert ch.get("bug") == expected_bug + + +def test_module_package_layout_matches_init_ide_resource_contract() -> None: + """Core discovers resources/prompts and resources/templates/... under the module package root.""" + backlog = REPO_ROOT / "packages" / "specfact-backlog" + assert (backlog / "resources" / "templates" / "backlog" / "field_mappings" / "ado_default.yaml").is_file() + codebase = REPO_ROOT / "packages" / "specfact-codebase" + assert (codebase / "resources" / "prompts" / "specfact.01-import.md").is_file() + + +def test_resource_change_changes_signed_payload_checksum(tmp_path: Path) -> None: + """Bundled resource files participate in the module integrity payload (resource-aware integrity).""" + sign_script = load_module_from_path("sign_modules_payload", SIGN_SCRIPT) + module_payload = vars(sign_script)["_module_payload"] + + module_dir = tmp_path / "packages" / "specfact-example" + (module_dir / "resources" / "prompts").mkdir(parents=True) + (module_dir / "resources" / "prompts" / "specfact.example.md").write_text("v1\n", encoding="utf-8") + manifest = module_dir / "module-package.yaml" + manifest.write_text( + yaml.safe_dump({"name": "nold-ai/specfact-example", "version": "0.1.0"}, sort_keys=False), + encoding="utf-8", + ) + + first = hashlib.sha256(module_payload(module_dir, payload_from_filesystem=True)).hexdigest() + (module_dir / "resources" / "prompts" / "specfact.example.md").write_text("v2\n", encoding="utf-8") + second = hashlib.sha256(module_payload(module_dir, payload_from_filesystem=True)).hexdigest() + + assert first != second + + +def test_version_bump_enforcement_detects_unchanged_version(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None: + """Resource-only publish attempts must bump module version (enforced against base ref in CI).""" + verify_script = load_module_from_path( + "verify_modules_signature_vb", + REPO_ROOT / "scripts" / "verify-modules-signature.py", + ) + manifest = tmp_path / "packages" / "specfact-example" / "module-package.yaml" + manifest.parent.mkdir(parents=True) + manifest.write_text( + yaml.safe_dump({"name": "nold-ai/specfact-example", "version": "0.1.0"}, sort_keys=False), + encoding="utf-8", + ) + + monkeypatch.setattr(verify_script, "_changed_manifests_from_git", lambda _base: [manifest]) + monkeypatch.setattr(verify_script, "_read_manifest_version_from_git", lambda _ref, _path: "0.1.0") + + failures = verify_script._verify_version_bumps("origin/dev") # pylint: disable=protected-access + assert failures and "not incremented" in failures[0]