Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# Change Validation

- Date: 2026-03-24
- Date: 2026-03-26
- 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.
- The change scope has been extended to cover the missing backlog slash-prompt inventory and explicit installed-module IDE discovery verification.
- Proposal, design, tasks, delta specs, and the resource ownership audit now all require `specfact-backlog` prompt packaging in addition to backlog field-mapping seed packaging.
- Validation was re-run after the scope extension and the change remains strict-valid.
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,20 @@ Date: 2026-03-25
| `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
### Backlog prompt inventory requiring restoration into the backlog bundle

- 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.
Observed from archived ownership and prompt-migration work in the sibling `specfact-cli` repository:

- `specfact.backlog-add.md`
- `specfact.backlog-daily.md`
- `specfact.backlog-refine.md`
- `specfact.sync-backlog.md`

Audit result:

- These prompts are backlog-bundle-owned slash-command resources and must be restored into `packages/specfact-backlog/resources/prompts/`.
- Their absence from the current live `specfact-cli/resources/prompts` tree does not remove the ownership requirement; it only means the canonical text must be recovered from history/change artifacts before packaging.
- Packaging coverage for backlog is incomplete until both the prompt inventory and the workspace-template seed set are present in published `specfact-backlog` artifacts.

### Backlog workspace-template seeds still living in `specfact-cli`

Expand Down Expand Up @@ -71,4 +81,5 @@ These are already package-owned and are not migration inputs from the core resou
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.
4. Backlog prompt migration must restore the full slash-prompt inventory into the backlog bundle root so installed-module prompt discovery can surface `nold-ai/specfact-backlog`.
5. 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.
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,40 @@
## Failing-first (design)

- Added `tests/unit/test_bundle_resource_payloads.py` asserting stable `packages/<bundle>/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.
- 2026-03-26: `python3 -m pytest tests/unit/test_bundle_resource_payloads.py -q` — failed as expected after extending coverage to backlog prompts.
- Missing source payload: `packages/specfact-backlog/resources/prompts/specfact.backlog-add.md`
- Missing module-root discovery path: `packages/specfact-backlog/resources/prompts/specfact.backlog-refine.md`
- Missing artifact payload entries under `specfact-backlog/resources/prompts/`

## Passing (implementation)

- 2026-03-25: `python -m pytest tests/unit/test_bundle_resource_payloads.py` — 9 passed.
- 2026-03-26: `python3 -m pytest tests/unit/test_bundle_resource_payloads.py -q` — 13 passed.
- `packages/specfact-backlog/resources/prompts/` now ships the restored backlog prompt inventory: `specfact.backlog-add.md`, `specfact.backlog-daily.md`, `specfact.backlog-refine.md`, and `specfact.sync-backlog.md`.
- `packages/specfact-backlog/resources/prompts/shared/cli-enforcement.md` now ships with the backlog prompt payload so restored relative links resolve after export.
- `packages/specfact-backlog/module-package.yaml` was bumped to `0.41.15` and re-signed after the prompt payload changed.
- 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.

## Artifact verification (task 4.6)

- 2026-03-26: built a workflow-shaped backlog artifact at `/tmp/specfact-backlog-0.41.15.tar.gz` using the same inclusion/exclusion rules as `.github/workflows/publish-modules.yml`.
- Verified the archive contains:
- `specfact-backlog/resources/prompts/specfact.backlog-add.md`
- `specfact-backlog/resources/prompts/specfact.backlog-daily.md`
- `specfact-backlog/resources/prompts/specfact.backlog-refine.md`
- `specfact-backlog/resources/prompts/specfact.sync-backlog.md`
- `specfact-backlog/resources/prompts/shared/cli-enforcement.md`

## Cross-repo prompt discovery/export verification (task 4.7)

- Added `test_core_prompt_discovery_finds_installed_backlog_bundle` in `tests/unit/test_bundle_resource_payloads.py`.
- The test copies `packages/specfact-backlog/` into a temporary install-like module root, patches installed `specfact_cli.utils.ide_setup._module_discovery_roots(...)`, and verifies:
- `discover_prompt_sources_catalog(...)` includes `nold-ai/specfact-backlog`
- the discovered prompt set includes the restored backlog prompt filenames
- installed core export writes IDE prompt files for the backlog source segment and matches `expected_ide_prompt_export_paths(...)`

## packaging-02 path contract (task 4.2)

- **Module install layout**: `.specfact/modules/<bundle>/resources/prompts`, `.specfact/modules/<bundle>/resources/templates/backlog/field_mappings` (module root = directory containing `module-package.yaml`).
Expand Down
26 changes: 23 additions & 3 deletions openspec/changes/packaging-01-bundle-resource-payloads/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ 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
- backlog slash prompts also belong to the backlog bundle, but the active modules-side packaging change only enforced prompt payloads for codebase/project/spec/govern while backlog was reduced to field-mapping templates
- 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

Expand All @@ -18,8 +19,10 @@ The audit result is explicit: the official bundle package directories in `specfa
- 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
- package the restored backlog slash-prompt inventory under the backlog bundle root so `specfact init ide` can rediscover it from installed modules
- 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
- prove that the packaged backlog prompt layout is sufficient for the current core prompt-catalog logic without additional core discovery changes

**Non-Goals:**

Expand All @@ -39,6 +42,15 @@ Each official bundle should carry a `resources/` subtree inside its package dire

This keeps installation, packaging, signature, and ownership boundaries aligned.

For backlog specifically, the authoritative prompt payload must live at the module root under:

- `packages/specfact-backlog/resources/prompts/specfact.backlog-add.md`
- `packages/specfact-backlog/resources/prompts/specfact.backlog-daily.md`
- `packages/specfact-backlog/resources/prompts/specfact.backlog-refine.md`
- `packages/specfact-backlog/resources/prompts/specfact.sync-backlog.md`

This is the path the current core prompt discovery contract already scans in installed module roots. Mirroring under `src/specfact_backlog/resources/...` is optional unless a runtime helper later requires package-local resource lookup, but it is not sufficient by itself for `specfact init ide`.

### 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.
Expand All @@ -47,19 +59,27 @@ The modules repo already computes integrity hashes from full module payloads. Th

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.

For verification, this change must be testable against the current `specfact_cli.utils.ide_setup.discover_prompt_sources_catalog(...)` behavior. If a bundle packages prompt files somewhere else, the change is incomplete even if the tarball technically contains markdown files.

### 4. Recover backlog prompt sources from historical canonical content

The current `specfact-cli` tree no longer contains the backlog prompt files in `resources/prompts/`, so the implementation cannot copy from the live core working tree. The prompt payload must instead be restored from the last valid prompt content preserved in `specfact-cli` history and archived change artifacts, then imported into the backlog bundle as the new canonical packaged source.

## 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.
- `[Backlog prompts are reconstructed from stale or partial source text]` -> verify restored filenames and semantics against archived `specfact-cli` change artifacts before publishing.

## 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.
2. Rebase the packaging worktree to `origin/dev` and restore backlog prompt templates from historical canonical sources into the backlog bundle root.
3. Move prompt templates, prompt companion assets, and backlog field mapping templates into the owning bundle packages.
4. Add tests for package-resource presence, published artifact contents, installed-module discovery, and integrity/version-bump enforcement.
5. Update docs/manifests as needed, re-sign the backlog bundle after version bump, and sync dependency notes back to the core packaging change.

## Open Questions

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,12 @@ Bundle-owned prompt templates and other workflow resources still live in the cor

- 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`.
- Explicitly restore the backlog slash-prompt inventory in `specfact-backlog`, including `specfact.backlog-add.md`, `specfact.backlog-daily.md`, `specfact.backlog-refine.md`, and `specfact.sync-backlog.md`, so installed-module prompt discovery can surface backlog workflows again.
- 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.
- Add cross-repo verification requirements that prove `specfact init ide` can discover backlog prompt resources from an installed `nold-ai/specfact-backlog` module root after the bundle is published/installed.
- 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`).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,12 @@ Each official bundle package SHALL include the prompt templates and other non-co
#### 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
- **AND** the ownership mapping covers the codebase, project, spec, govern, and backlog bundles for the currently supported prompt set

#### Scenario: Backlog bundle ships the restored slash-prompt inventory
- **WHEN** the backlog bundle package is inspected from source or from an installed artifact
- **THEN** `resources/prompts/` contains `specfact.backlog-add.md`, `specfact.backlog-daily.md`, `specfact.backlog-refine.md`, and `specfact.sync-backlog.md`
- **AND** those prompt files are treated as canonical bundle-owned sources rather than historical leftovers

#### Scenario: Prompt companion resources ship with prompt payloads
- **WHEN** an exported prompt template references a companion file by relative path, such as `./shared/cli-enforcement.md`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,12 @@ Bundled resources SHALL live at stable paths inside the bundle package so that t
- **WHEN** the core CLI inspects an installed official bundle package
- **THEN** the bundle contains a stable prompt resource path that can be discovered without scanning the core CLI repository

#### Scenario: Installed backlog bundle contributes prompt source catalog entries

- **WHEN** `nold-ai/specfact-backlog` is installed under an effective module root with the packaged backlog prompt files
- **THEN** core prompt-source discovery includes `nold-ai/specfact-backlog` as a prompt source
- **AND** `specfact init ide` can export the backlog prompt filenames from that installed module root

#### Scenario: Core resolves prompt companion resources with exported prompts
- **WHEN** the core CLI exports a prompt that depends on a companion file such as `shared/cli-enforcement.md`
- **THEN** the companion resource is discoverable from the same installed bundle root
Expand Down
10 changes: 10 additions & 0 deletions openspec/changes/packaging-01-bundle-resource-payloads/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,20 @@
- [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`.
- [x] 2.7 Add failing tests that assert `specfact-backlog` packages the backlog slash-prompt inventory at `resources/prompts/` with the expected filenames.
- [x] 2.8 Add failing artifact-content checks that confirm published `specfact-backlog-*.tar.gz` archives contain `resources/prompts/...` entries, not only field-mapping templates.
- [x] 2.9 Add or update a cross-repo verification slice that proves core prompt discovery includes `nold-ai/specfact-backlog` when an installed module root contains backlog prompt resources.

## 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.
- [x] 3.5 Rebase the implementation worktree `feature/packaging-01-bundle-resource-payloads` onto `origin/dev` before editing payload files or tests.
- [x] 3.6 Restore the canonical backlog prompt sources into `packages/specfact-backlog/resources/prompts/` from the last valid backlog prompt content in `specfact-cli` history/change artifacts.
- [x] 3.7 If any restored backlog prompt uses relative companion assets, package those companions under the same backlog prompt root and verify the references remain valid after export.
- [x] 3.8 Bump `packages/specfact-backlog/module-package.yaml` version and refresh integrity metadata because prompt resources are part of the signed module payload.

## 4. Validation

Expand All @@ -29,3 +36,6 @@
- [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`.
- [x] 4.6 Rebuild or inspect the published backlog artifact and verify it contains `resources/prompts/specfact.backlog-add.md`, `specfact.backlog-daily.md`, `specfact.backlog-refine.md`, and `specfact.sync-backlog.md`.
- [x] 4.7 Verify in `specfact-cli` that installed-module prompt discovery surfaces `nold-ai/specfact-backlog` from an installed module root and that `specfact init ide` can export the restored backlog prompts.
- [x] 4.8 Record both modules-repo and cross-repo verification evidence in `TDD_EVIDENCE.md`.
Loading
Loading