Merge pull request #106 from nold-ai/dev

release: merge dev to main (bundle resources + OpenSpec updates)

Author: djm81

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/<python_package>/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

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 |

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

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 <command> --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 <command> --help` output
+- **THEN** the command name, arguments, and key options match

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

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
 

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

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

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

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