nold-ai · djm81 · Apr 2, 2026 · Apr 2, 2026 · Apr 2, 2026 · Apr 2, 2026
diff --git a/docs/adapters/azuredevops.md b/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
 

diff --git a/docs/bundles/code-review/overview.md b/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

diff --git a/docs/guides/agile-scrum-workflows.md b/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
diff --git a/docs/reference/README.md b/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

diff --git a/docs/reference/architecture.md b/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/)
diff --git a/docs/reference/schema-versioning.md b/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)
diff --git a/openspec/CHANGE_ORDER.md b/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) | — |
diff --git a/openspec/changes/module-bundle-deps-auto-install/.openspec.yaml b/openspec/changes/module-bundle-deps-auto-install/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-02
diff --git a/openspec/changes/module-bundle-deps-auto-install/TDD_EVIDENCE.md b/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.
diff --git a/openspec/changes/module-bundle-deps-auto-install/design.md b/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.
diff --git a/openspec/changes/module-bundle-deps-auto-install/proposal.md b/openspec/changes/module-bundle-deps-auto-install/proposal.md
@@ -0,0 +1,40 @@
+# Change: Declare peer bundle dependencies for auto-install
+
+## Why
+
+Several official bundles share a top-level command group (for example `specfact code …`) but only declare `commands: [code]` in the manifest. Installing a single bundle (such as `nold-ai/specfact-code-review`) therefore does not pull in sibling bundles that register the rest of that group’s commands. Users hit missing subcommands until they manually install `nold-ai/specfact-codebase`. Other bundles already declare `bundle_dependencies` (codebase, spec, govern depend on project); code-review is inconsistent and should declare the peer bundle(s) needed for a complete `code` group experience.
+
+## What Changes
+
+- Set `bundle_dependencies` on `nold-ai/specfact-code-review` to include `nold-ai/specfact-codebase` so the CLI can auto-install the codebase bundle (and its existing dependency on project) when users install code review.
+- Align `registry/index.json` metadata for `nold-ai/specfact-code-review` with the updated manifest (`bundle_dependencies` field).
+- Bump `specfact-code-review` semver (patch or minor per scope of manifest-only vs. user-visible install behavior) and refresh integrity checksums/signatures per publish workflow.
+- Add or extend tests that assert manifest and registry rows stay consistent for declared bundle dependencies.
+- Optionally document the dependency in bundle overview or install docs if user-facing guidance should mention the relationship.
+
+## Capabilities
+
+### New Capabilities
+
+- `module-bundle-dependencies`: Official module manifests and registry entries declare `bundle_dependencies` so SpecFact CLI can install required peer bundles for full command-group coverage; code-review lists codebase as a dependency.
+
+### Modified Capabilities
+
+- (none) — no existing `openspec/specs/` requirement files change; this change introduces a new capability spec.
+
+## Impact
+
+- `packages/specfact-code-review/module-package.yaml` — `bundle_dependencies` populated.
+- `registry/index.json` — matching `bundle_dependencies` for the code-review module entry.
+- **Compatibility** — `bundle_dependencies` auto-install is implemented in specfact-cli; when bumping this bundle, **review `core_compatibility`** in both `packages/specfact-code-review/module-package.yaml` and the corresponding `registry/index.json` row so they stay aligned and reflect the **minimum specfact-cli** that supports `_extract_bundle_dependencies` / `_install_bundle_dependencies_for_module` (e.g. raise the lower bound to `>=0.44.0` if needed).
+- Published artifact tarball and signatures after version bump; `.github/workflows/publish-modules.yml` path unchanged except normal publish flow.
+- `tests/` — assertions for registry/manifest parity if not already covered.
+- Potential docs: `docs/bundles/code-review/overview.md` or reference pages if we surface the dependency to users.
+
+## Source Tracking
+
+<!-- source_repo: nold-ai/specfact-cli-modules -->
+- **GitHub Issue**: #135
+- **Issue URL**: https://github.com/nold-ai/specfact-cli-modules/issues/135
+- **Last Synced Status**: synced
+- **Sanitized**: true
diff --git a/...hanges/module-bundle-deps-auto-install/specs/module-bundle-dependencies/spec.md b/...hanges/module-bundle-deps-auto-install/specs/module-bundle-dependencies/spec.md
@@ -0,0 +1,34 @@
+# module-bundle-dependencies Specification
+
+## Purpose
+
+Define how official module packages declare peer bundle dependencies so SpecFact CLI and the registry expose a consistent install graph for shared command groups (for example `code`).
+
+## ADDED Requirements
+
+### Requirement: Code-review module declares codebase peer dependency
+
+The `nold-ai/specfact-code-review` module SHALL list `nold-ai/specfact-codebase` in `bundle_dependencies` inside `packages/specfact-code-review/module-package.yaml` so that installing code review can resolve the peer bundle required for the full `code` command group.
+
+#### Scenario: Manifest names the codebase bundle
+
+- **WHEN** a maintainer reads `packages/specfact-code-review/module-package.yaml`
+- **THEN** the `bundle_dependencies` sequence includes `nold-ai/specfact-codebase`
+
+### Requirement: Registry mirrors manifest bundle dependencies for code-review
+
+The `registry/index.json` entry for `nold-ai/specfact-code-review` SHALL list the same `bundle_dependencies` values as the published `module-package.yaml` for that module version.
+
+#### Scenario: Registry matches manifest after publish
+
+- **WHEN** the code-review module version is published and the registry row is updated
+- **THEN** the `bundle_dependencies` array for `nold-ai/specfact-code-review` equals the manifest’s `bundle_dependencies` for that version
+
+### Requirement: Dependency declarations stay acyclic
+
+Official module `bundle_dependencies` SHALL NOT introduce a dependency cycle between official nold-ai bundles.
+
+#### Scenario: Code-review dependency does not create a cycle
+
+- **WHEN** code-review declares a dependency on codebase
+- **THEN** no official bundle manifest transitively depends back on `nold-ai/specfact-code-review` in a way that forms a cycle
diff --git a/openspec/changes/module-bundle-deps-auto-install/tasks.md b/openspec/changes/module-bundle-deps-auto-install/tasks.md
@@ -0,0 +1,25 @@
+## 1. Branch and baseline
+
+- [x] 1.1 Create branch `feature/module-bundle-deps-auto-install` from `origin/dev` (use a dedicated worktree if preferred).
+
+## 2. Tests first (TDD)
+
+- [x] 2.1 Add or extend tests that fail until `bundle_dependencies` for `nold-ai/specfact-code-review` in `module-package.yaml` matches `registry/index.json` (and cover acyclic dependency expectation if applicable).
+
+## 3. Implementation
+
+- [x] 3.1 Update `packages/specfact-code-review/module-package.yaml`: set `bundle_dependencies` to include `nold-ai/specfact-codebase`; bump semver per design.
+- [x] 3.2 Update `registry/index.json` for `nold-ai/specfact-code-review` so `bundle_dependencies` matches the manifest; refresh checksums, download_url, and version fields per publish/sign workflow when artifacts are produced.
+- [x] 3.3 Run signing / `verify-modules-signature` flow so integrity fields in the manifest stay valid after edits. (Checksum OK via `--payload-from-filesystem`; **Ed25519 signature** must be applied with the org private key before merge — see `TDD_EVIDENCE.md`.)
+- [x] 3.4 Optionally update user-facing docs (for example code-review bundle overview) to mention that installing code review pulls the codebase bundle for the full `code` command group.
+
+## 4. Evidence and quality gates
+
+- [x] 4.1 Record failing/passing test notes in `openspec/changes/module-bundle-deps-auto-install/TDD_EVIDENCE.md`.
+- [x] 4.2 Run full quality gate sequence from AGENTS.md (`format`, `type-check`, `lint`, `yaml-lint`, `verify-modules-signature`, `contract-test`, `smart-test`, `test`). (Full suite run; `verify-modules-signature` without `--require-signature` passes; **with** `--require-signature` pending until signing step above.)
+- [ ] 4.3 Ensure `.specfact/code-review.json` is present and fresh relative to edits under `packages/`, `registry/`, `tests/`, and this change folder (excluding evidence-only `TDD_EVIDENCE.md` updates). Run `hatch run specfact code review run --json --out .specfact/code-review.json` with `--scope changed` while iterating and `--scope full` before the final PR; remediate all findings. **Blocked here:** `specfact code review` requires workflow bundles (`Command 'code' is not installed`); run after `specfact module install` / profile init locally.
+- [x] 4.4 Open PR to `dev` and link GitHub issue below. — PR [#136](https://github.com/nold-ai/specfact-cli-modules/pull/136) (issue [#135](https://github.com/nold-ai/specfact-cli-modules/issues/135)).
+
+## 5. Source tracking
+
+- [x] 5.1 Keep `proposal.md` Source Tracking in sync with the GitHub issue number and URL after issue creation.