Merge pull request #138 from nold-ai/dev

Release: bundle_dependencies, pip_dependencies, and manifest validation (dev → main)

Author: djm81

docs/adapters/azuredevops.md

@@ -187,7 +187,7 @@ adapter = AdoAdapter(
 
 ### Error diagnostics (PATCH failures)
 
-When a work item PATCH fails (e.g. HTTP 400 during backlog refine or status update), the CLI shows the ADO error message and a hint in the console. With `--debug`, the log includes the ADO response snippet and the JSON Patch paths attempted so you can identify the failing field. See [Debug Logging – Examining ADO API Errors](../reference/debug-logging.md#examining-ado-api-errors) and [Troubleshooting – Backlog refine or work item PATCH fails (400/422)](../guides/troubleshooting.md#backlog-refine-or-work-item-patch-fails-400422).
+When a work item PATCH fails (e.g. HTTP 400 during backlog refine or status update), the CLI shows the ADO error message and a hint in the console. With `--debug`, the log includes the ADO response snippet and the JSON Patch paths attempted so you can identify the failing field. See [Debug Logging – Examining ADO API Errors](https://docs.specfact.io/core-cli/debug-logging/#examining-ado-api-errors) and [Troubleshooting – Backlog refine or work item PATCH fails (400/422)](../guides/troubleshooting.md#backlog-refine-or-work-item-patch-fails-400422).
 
 ## Usage Examples
 

docs/bundles/code-review/overview.md

@@ -16,7 +16,7 @@ Use it together with the [Codebase](../codebase/overview/) bundle (`import`, `an
 
 ## Prerequisites
 
-- `specfact module install nold-ai/specfact-code-review`
+- `specfact module install nold-ai/specfact-code-review` — the manifest `bundle_dependencies` list includes **`nold-ai/specfact-codebase`**, so SpecFact CLI **will automatically install** the Codebase bundle alongside this one for the full shared **`specfact code`** command surface (import, analyze, drift, and related commands live there).
 - Optional tool installs (Ruff, Radon, Semgrep, Pyright, etc.) as described in command help
 
 ## `specfact code review` — nested commands

docs/guides/agile-scrum-workflows.md

@@ -1046,5 +1046,5 @@ If template rendering fails:
 ## Related Documentation
 
 - [Command Reference - Project Commands](../reference/commands.md#project---project-bundle-management) - Complete command documentation including `project merge` and `project resolve-conflict`
-- [Project Bundle Structure](../reference/directory-structure.md) - Project bundle organization
+- [Project Bundle Structure](https://docs.specfact.io/reference/directory-structure/) - Project bundle organization (core CLI docs)
 - See [Project Commands](../reference/commands.md#project---project-bundle-management) for template customization options

docs/reference/README.md

@@ -19,12 +19,12 @@ Complete technical reference for the official modules site and bundle-owned work
 - **[Command Syntax Policy](command-syntax-policy.md)** - Source-of-truth argument syntax conventions for docs
 - **[Authentication](authentication.md)** - Device code auth flows and token storage
 - **[Architecture](architecture.md)** - Technical design, module structure, and internals
-- **[Debug Logging](debug-logging.md)** - Where and what is logged when using `--debug`
+- **[Debug Logging](https://docs.specfact.io/core-cli/debug-logging/)** - Where and what is logged when using `--debug` (core CLI docs)
 - **[Operational Modes](modes.md)** - CI/CD vs CoPilot modes
 - **[Specmatic API](specmatic.md)** - Specmatic integration API reference (functions, classes, integration points)
 - **[Telemetry](telemetry.md)** - Opt-in analytics and privacy guarantees
-- **[Feature Keys](feature-keys.md)** - Key normalization and formats
-- **[Directory Structure](directory-structure.md)** - Project structure and organization
+- **[Feature Keys](https://docs.specfact.io/reference/feature-keys/)** - Key normalization and formats (core CLI docs)
+- **[Directory Structure](https://docs.specfact.io/reference/directory-structure/)** - Project structure and organization (core CLI docs)
 - **[Schema Versioning](schema-versioning.md)** - Bundle schema versions and backward compatibility (v1.0, v1.1)
 - **[Module Security](module-security.md)** - Marketplace/module integrity and publisher metadata
 - **[Module Categories](module-categories.md)** - Category grouping model, canonical module assignments, bundles, and first-run profiles

docs/reference/architecture.md

@@ -161,6 +161,6 @@ Formal ADR pages are not yet published on the modules docs site. The current arc
 
 ## Related Docs
 
-- [Directory Structure](directory-structure.md)
+- [Directory Structure](https://docs.specfact.io/reference/directory-structure/) (core CLI docs)
 - [Module Development Guide](/authoring/module-development/)
 - [Adapter Development Guide](/authoring/adapter-development/)

docs/reference/schema-versioning.md

@@ -178,4 +178,4 @@ schema_metadata:
 
 - [Architecture - Change Tracking Models](../reference/architecture.md#change-tracking-models-v11-schema) - Technical details
 - [Architecture - Bridge Adapter Interface](../reference/architecture.md#bridge-adapter-interface) - Adapter implementation guide
-- [Directory Structure](directory-structure.md) - Bundle file organization
+- [Directory Structure](https://docs.specfact.io/reference/directory-structure/) - Bundle file organization (core CLI docs)

openspec/CHANGE_ORDER.md

@@ -72,3 +72,9 @@ Adds bidirectional conversion between spec-kit feature folders and OpenSpec chan
 | speckit | 03 | speckit-03-change-proposal-bridge | [#116](https://github.com/nold-ai/specfact-cli-modules/issues/116) | specfact-cli/speckit-02-v04-adapter-alignment ([specfact-cli#453](https://github.com/nold-ai/specfact-cli/issues/453)) |
 
 **Cross-repo dependency**: Requires `speckit-02-v04-adapter-alignment` in `nold-ai/specfact-cli` to be implemented first (provides `ToolCapabilities.extension_commands` consumed by `SpecKitBacklogSync`).
+
+### Module bundle peer dependencies
+
+| Module | Order | Change folder | GitHub # | Blocked by |
+|--------|-------|---------------|----------|------------|
+| peer-deps | 01 | module-bundle-deps-auto-install | [#135](https://github.com/nold-ai/specfact-cli-modules/issues/135) | — |

openspec/changes/module-bundle-deps-auto-install/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-02

openspec/changes/module-bundle-deps-auto-install/TDD_EVIDENCE.md

@@ -0,0 +1,49 @@
+# TDD evidence — module-bundle-deps-auto-install
+
+## Tests
+
+- Added `tests/unit/test_registry_manifest_bundle_dependencies.py`:
+  - `test_registry_bundle_dependencies_match_manifests` — every registry module with a local `module-package.yaml` must have matching `bundle_dependencies`.
+  - `test_official_bundle_dependency_graph_is_acyclic` — no cycles among `nold-ai/*` edges in `registry/index.json`.
+- Ran: `.venv/bin/pytest tests/unit/test_registry_manifest_bundle_dependencies.py` — **pass** (2 tests).
+- Ran: `.venv/bin/pytest tests/unit/docs/test_bundle_overview_cli_examples.py` — **pass** (after overview doc update).
+
+## Implementation
+
+- `packages/specfact-code-review/module-package.yaml`: `bundle_dependencies` includes `nold-ai/specfact-codebase`; version **0.46.0** (minor bump per design).
+- `registry/index.json` + `registry/modules/specfact-code-review-0.46.0.tar.gz` (+ `.sha256`) aligned with publish workflow layout.
+- `docs/bundles/code-review/overview.md`: prerequisites note peer dependency / auto-install behavior.
+
+## Signing (required before CI merge)
+
+Manifest integrity was generated with **`hatch run sign-modules -- --allow-unsigned`** (checksum only) because the local signing key is encrypted and no passphrase was available in this environment.
+
+**Before opening the PR or merging**, sign with the org private key so CI passes `verify-modules-signature --require-signature`:
+
+```bash
+hatch run sign-modules -- \
+  --key-file "${SPECFACT_MODULE_PRIVATE_SIGN_KEY_FILE:-$HOME/.specfact/sign-keys/module-signing-private.pem}" \
+  packages/specfact-code-review/module-package.yaml \
+  --payload-from-filesystem
+```
+
+Then re-run:
+
+```bash
+hatch run verify-modules-signature -- --require-signature --payload-from-filesystem
+```
+
+If the manifest checksum changes after signing, rebuild the registry tarball and refresh `registry/index.json` checksum for `specfact-code-review-0.46.0.tar.gz` (same Python step as publish workflow) or re-run the publish automation.
+
+## Quality gates (2026-04-02, worktree)
+
+- `hatch run format` — pass  
+- `hatch run yaml-lint` — pass  
+- `hatch run type-check` (scoped + full lint path) — pass via `hatch run lint`  
+- `hatch run lint` — pass  
+- `python scripts/verify-modules-signature.py --payload-from-filesystem` — pass (all 6 manifests)  
+- `python scripts/verify-modules-signature.py --require-signature --payload-from-filesystem` — **fails until manifest is signed** (expected until signing step above)  
+- `hatch run contract-test` — pass  
+- `hatch run smart-test` — pass  
+- `hatch run test` — pass  
+- `hatch run specfact code review run --json --out .specfact/code-review.json --scope changed` — not run (SpecFact CLI: `Command 'code' is not installed`); complete before PR per `tasks.md` 4.3.

openspec/changes/module-bundle-deps-auto-install/design.md

@@ -0,0 +1,42 @@
+## Context
+
+Official bundles ship `module-package.yaml` with `commands` and optional `bundle_dependencies`. The registry copies `bundle_dependencies` into `registry/index.json` during publish (`publish-modules.yml`). `nold-ai/specfact-codebase` already depends on `nold-ai/specfact-project`; `nold-ai/specfact-code-review` shares the `code` command group but lists no peer dependencies, so installs can omit the codebase bundle until users discover missing `code` subcommands manually.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Declare `bundle_dependencies` for code-review so manifest and registry advertise the need for the codebase bundle (and, transitively via codebase, project).
+- Keep manifest and registry `bundle_dependencies` fields aligned after version bump and publish.
+- Add automated checks or tests that prevent drift between YAML manifest and JSON registry for this metadata where practical.
+
+**Non-Goals:**
+
+- Changing SpecFact CLI marketplace installer logic in this repo (core lives in `specfact-cli`); transitive `bundle_dependencies` behavior is confirmed in core (see “Resolved” below).
+- Re-evaluating every bundle’s full dependency graph beyond the known code-review gap (optional follow-up audits).
+
+## Decisions
+
+1. **Dependency list for code-review** — Add a single entry `nold-ai/specfact-codebase`. Rationale: codebase already depends on project; duplicating project on code-review would be redundant unless CLI only installs direct deps. If CLI resolves transitive `bundle_dependencies`, one entry is sufficient. If not, extend to also list `nold-ai/specfact-project` after verifying core behavior.
+2. **Semver** — Treat as **minor** if users perceive new auto-install behavior; **patch** if manifest/registry alignment only. Default to minor when `bundle_dependencies` changes user-facing install resolution.
+3. **Verification** — Prefer extending existing registry/manifest tests or `verify-modules-signature` expectations over one-off scripts.
+
+## Risks / Trade-offs
+
+- **Circular dependency** — Code-review must not create a cycle. Codebase does not depend on code-review → safe.
+- **Larger install footprint** — Users installing only code-review will pull more bundles; acceptable per goal of “full command group.”
+- **Core vs modules** — If CLI ignores `bundle_dependencies`, this change still documents intent; follow-up in specfact-cli.
+
+## Migration Plan
+
+1. Implement on a feature branch from `dev`; bump `specfact-code-review` version; update manifest + registry.
+2. Run publish/sign verification locally; publish via normal workflow.
+3. No data migration for end users beyond reinstalling or updating modules.
+
+## Resolved: transitive `bundle_dependencies` installs
+
+**Confirmed.** Marketplace installs recurse through `bundle_dependencies`: `_install_bundle_dependencies_for_module` in `specfact-cli` (`src/specfact_cli/registry/module_installer.py`) calls `install_module()` for each missing peer before placing the requested module, so transitive peers (e.g. codebase → project) are installed in order.
+
+**Spec evidence:** `specfact-cli` `openspec/specs/official-bundle-tier/spec.md` — requirement **“Module installer auto-installs bundle dependencies for official-tier bundles”** (installer SHALL automatically install listed dependencies when an official bundle declares `bundle_dependencies`).
+
+**This change’s delta spec:** `openspec/changes/module-bundle-deps-auto-install/specs/module-bundle-dependencies/spec.md` — manifest/registry parity and acyclicity for declared peers.