feat: module-migration-02 bundle extraction (#332)

* docs: add module-migration-02-bundle-extraction to CHANGE_ORDER.md

* feat: implement module-migration-02 bundle extraction

* fix(ci): checkout module bundles repo for test jobs

* Fix test failures

* fix(modules): load local bundle sources in compatibility aliases

* fix: run worktree policy code in tests/CI and silence reexport deprecation

- Prefer src/<name>/main.py over app.py when SPECFACT_REPO_ROOT is set so
  policy init uses worktree templates.py (SPECFACT_POLICY_TEMPLATES_DIR).
- Policy engine module-package.yaml: version 0.1.5 and re-signed checksum.
- conftest: set SPECFACT_REPO_ROOT, SPECFACT_POLICY_TEMPLATES_DIR; add
  bundle package roots when specfact-cli-modules present.
- Policy engine integration tests: rely on conftest env, clear registry
  and re-register before invoke so loader uses worktree.
- test_reexport_shims: filter deprecation warning for legacy analyze import.

Made-with: Cursor

* fix: defer specfact_backlog import in shims so CI can register bridges

- backlog and policy_engine __init__.py: import specfact_backlog only in
  __getattr__ (cached), not at module load. Allows loading .src.adapters.*
  for bridge registration without requiring specfact_backlog installed.
- Re-sign backlog and policy_engine module-package.yaml after init changes.
- openspec: update module-migration-02 tasks.md.

Made-with: Cursor

* fix: defer bundle import in all module shims to fix CI collection errors

- Apply deferred import (only in __getattr__, cached) to analyze, contract,
  drift, enforce, generate, import_cmd, migrate, patch_mode, plan, project,
  repro, sdd, spec, sync, validate. Matches backlog and policy_engine.
- Prevents ImportError when tests import specfact_cli.modules.<name>.src.*
  without specfact_backlog/specfact_govern/specfact_project/specfact_spec
  installed (e.g. CI). Fixes 78 collection errors.
- Re-sign all affected module-package.yaml manifests.

Made-with: Cursor

* fix(ci): include module shims in hatch cache key so CI uses current code

* feat(modules): registry descriptions, --bump-version for publish, tasks and format fixes

- Add description to registry index entries in publish-module.py (module search)
- Add --bump-version patch|minor|major for bundle re-publish in publish-module.py
- Format fixes in validate-modules-repo-sync.py (SIM108, B007)
- Mark completed tasks in module-migration-02-bundle-extraction tasks.md
- Update test for publish_bundle(bump_version=) signature

Made-with: Cursor

* Add missing migration tasks to the open change to completely isolate modules into specfact-cli-modules repo.

* Add gap analysis and update changes

* Update follow-up changes to avoid ambiguities and overlaps

* docs: complete migration-02 section-18 parity and 17.8 gate evidence

* docs: mark migration-02 import-categorization commit checkpoint done

* Update change constraints and blockers for module migration

* docs: add migration-05 issue #334 and complete task 17.10.4

* Update change constraints and blockers for module migration

---------

Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

Author: djm81

.github/workflows/pr-orchestrator.yml

@@ -118,6 +118,18 @@ jobs:
       - uses: actions/checkout@v4
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
 
+      - name: Checkout module bundles repo
+        if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
+        uses: actions/checkout@v4
+        with:
+          repository: nold-ai/specfact-cli-modules
+          path: specfact-cli-modules
+          ref: ${{ (github.ref == 'refs/heads/main' || github.head_ref == 'main') && 'main' || 'dev' }}
+
+      - name: Export module bundles path
+        if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
+        run: echo "SPECFACT_MODULES_REPO=${GITHUB_WORKSPACE}/specfact-cli-modules" >> "$GITHUB_ENV"
+
       - name: Set up Python 3.12
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
         uses: actions/setup-python@v5
@@ -140,7 +152,7 @@ jobs:
           path: |
             ~/.local/share/hatch
             ~/.cache/uv
-          key: ${{ runner.os }}-hatch-tests-py312-${{ hashFiles('pyproject.toml') }}
+          key: ${{ runner.os }}-hatch-tests-py312-${{ hashFiles('pyproject.toml', 'src/specfact_cli/modules/*/__init__.py') }}
           restore-keys: |
             ${{ runner.os }}-hatch-tests-py312-
             ${{ runner.os }}-hatch-
@@ -214,6 +226,14 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v4
+      - name: Checkout module bundles repo
+        uses: actions/checkout@v4
+        with:
+          repository: nold-ai/specfact-cli-modules
+          path: specfact-cli-modules
+          ref: ${{ (github.ref == 'refs/heads/main' || github.head_ref == 'main') && 'main' || 'dev' }}
+      - name: Export module bundles path
+        run: echo "SPECFACT_MODULES_REPO=${GITHUB_WORKSPACE}/specfact-cli-modules" >> "$GITHUB_ENV"
       - name: Set up Python 3.11
         uses: actions/setup-python@v5
         with:
@@ -231,7 +251,7 @@ jobs:
           path: |
             ~/.local/share/hatch
             ~/.cache/uv
-          key: ${{ runner.os }}-hatch-compat-py311-${{ hashFiles('pyproject.toml') }}
+          key: ${{ runner.os }}-hatch-compat-py311-${{ hashFiles('pyproject.toml', 'src/specfact_cli/modules/*/__init__.py') }}
           restore-keys: |
             ${{ runner.os }}-hatch-compat-py311-
             ${{ runner.os }}-hatch-
@@ -261,6 +281,14 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v4
+      - name: Checkout module bundles repo
+        uses: actions/checkout@v4
+        with:
+          repository: nold-ai/specfact-cli-modules
+          path: specfact-cli-modules
+          ref: ${{ (github.ref == 'refs/heads/main' || github.head_ref == 'main') && 'main' || 'dev' }}
+      - name: Export module bundles path
+        run: echo "SPECFACT_MODULES_REPO=${GITHUB_WORKSPACE}/specfact-cli-modules" >> "$GITHUB_ENV"
       - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
@@ -278,7 +306,7 @@ jobs:
           path: |
             ~/.local/share/hatch
             ~/.cache/uv
-          key: ${{ runner.os }}-hatch-contract-first-py312-${{ hashFiles('pyproject.toml') }}
+          key: ${{ runner.os }}-hatch-contract-first-py312-${{ hashFiles('pyproject.toml', 'src/specfact_cli/modules/*/__init__.py') }}
           restore-keys: |
             ${{ runner.os }}-hatch-contract-first-py312-
             ${{ runner.os }}-hatch-

AGENTS.md

@@ -154,6 +154,13 @@ If remote cleanup is needed:
 git push origin --delete feature/<branch-slug>
 ```
 
+### Developing specfact-cli-modules (IDE dependencies)
+
+Bundle code in **specfact-cli-modules** imports from `specfact_cli` (models, runtime, validators, etc.). That repo uses **Hatch**: a `pyproject.toml` with optional dependency `.[dev]` pulls in `specfact-cli` from a sibling path (`file://../specfact-cli`). When opening the modules repo in Cursor/VS Code:
+
+- In **specfact-cli-modules**: run `hatch env create` (with specfact-cli at `../specfact-cli`, or symlink / edit path in pyproject), then in the IDE select **Python: Select Interpreter** → `.venv` in that repo.
+- See **specfact-cli-modules** `README.md` → "Local development (IDE / Cursor)" for sibling layout and worktree/symlink options.
+
 ### Pre-Commit Checklist
 
 Run all steps in order before committing. Every step must pass with no errors.

CHANGELOG.md

@@ -8,6 +8,28 @@ All notable changes to this project will be documented in this file.
 **Important:** Changes need to be documented below this block as this is the header section. Each section should be separated by a horizontal rule. Newer changelog entries need to be added on top of prior ones to keep the history chronological with most recent changes first.
 
 
+---
+
+## [0.40.0] - 2026-02-28
+
+### Added
+
+- Official marketplace bundle extraction (OpenSpec change `module-migration-02-bundle-extraction`, issue [#316](https://github.com/nold-ai/specfact-cli/issues/316)): five bundle packages (`specfact-project`, `specfact-backlog`, `specfact-codebase`, `specfact-spec`, `specfact-govern`) are now produced in the dedicated `nold-ai/specfact-cli-modules` repository.
+- Official-tier trust model in module validation and display: `official` tier verification path with `nold-ai` publisher allowlist and `[official]` module list badge.
+- Bundle dependency auto-install in module installer: installing `nold-ai/specfact-spec` or `nold-ai/specfact-govern` now auto-installs `nold-ai/specfact-project` when missing.
+- Bundle publishing mode in `scripts/publish-module.py` (`--bundle` and `--modules-repo-dir`) for packaging/signing/index updates against the dedicated modules repository.
+- New marketplace bundles guide: `docs/guides/marketplace.md`.
+
+### Changed
+
+- Module source relocation to bundle namespaces with compatibility shims: legacy `specfact_cli.modules.*` imports now re-export from `specfact_<bundle>.*` namespaces during migration.
+- Official module install output now explicitly confirms verification status (`Verified: official (nold-ai)`).
+- Documentation updates across getting-started, docs landing page, module categories, marketplace guides, layout navigation, and root README to reflect marketplace-distributed official bundles.
+
+### Deprecated
+
+- Legacy flat import paths under `specfact_cli.modules.*` are deprecated in favor of bundle namespaces (`specfact_project.*`, `specfact_backlog.*`, `specfact_codebase.*`, `specfact_spec.*`, `specfact_govern.*`) and are planned for removal in the next major release.
+
 ---
 
 ## [0.39.0] - 2026-02-28

README.md

@@ -188,6 +188,27 @@ For technical architecture details (module lifecycle, registry internals, adapte
 - [Architecture Docs Index](docs/architecture/README.md)
 - [Architecture Implementation Status](docs/architecture/implementation-status.md)
 
+### Official Marketplace Bundles
+
+SpecFact ships official bundle packages via the dedicated marketplace registry repository
+`nold-ai/specfact-cli-modules`.
+
+Install examples:
+
+```bash
+specfact module install nold-ai/specfact-project
+specfact module install nold-ai/specfact-backlog
+specfact module install nold-ai/specfact-codebase
+specfact module install nold-ai/specfact-spec
+specfact module install nold-ai/specfact-govern
+```
+
+Official bundles are verified as `official` tier (`nold-ai` publisher). Some bundles
+auto-install dependencies:
+
+- `nold-ai/specfact-spec` pulls `nold-ai/specfact-project`
+- `nold-ai/specfact-govern` pulls `nold-ai/specfact-project`
+
 ---
 
 ## Where SpecFact Fits

docs/_layouts/default.html

@@ -150,6 +150,7 @@ <h2 class="docs-sidebar-title">
                 <li><a href="{{ '/guides/extending-projectbundle/' | relative_url }}">Extending ProjectBundle</a></li>
                 <li><a href="{{ '/guides/installing-modules/' | relative_url }}">Installing Modules</a></li>
                 <li><a href="{{ '/guides/module-marketplace/' | relative_url }}">Module Marketplace</a></li>
+                <li><a href="{{ '/guides/marketplace/' | relative_url }}">Marketplace Bundles</a></li>
                 <li><a href="{{ '/guides/module-signing-and-key-rotation/' | relative_url }}">Module Signing and Key Rotation</a></li>
                 <li><a href="{{ '/guides/using-module-security-and-extensions/' | relative_url }}">Using Module Security and Extensions</a></li>
                 <li><a href="{{ '/brownfield-engineer/' | relative_url }}">Working With Existing Code</a></li>

docs/getting-started/README.md

@@ -50,6 +50,19 @@ specfact init --profile solo-developer
 specfact init --install backlog,codebase
 ```
 
+Marketplace bundle install examples:
+
+```bash
+specfact module install nold-ai/specfact-codebase
+specfact module install nold-ai/specfact-backlog
+```
+
+Official bundles are published in the `nold-ai/specfact-cli-modules` registry and verified as `official` tier during install.
+Some bundles install dependencies automatically:
+
+- `nold-ai/specfact-spec` -> pulls `nold-ai/specfact-project`
+- `nold-ai/specfact-govern` -> pulls `nold-ai/specfact-project`
+
 ### Modernizing Legacy Code?
 
 **New to brownfield modernization?** See our **[Brownfield Engineer Guide](../guides/brownfield-engineer.md)** for a complete walkthrough of modernizing legacy Python code with SpecFact CLI.

docs/guides/marketplace.md

@@ -0,0 +1,60 @@
+---
+layout: default
+title: Marketplace Bundles
+nav_order: 23
+permalink: /guides/marketplace/
+description: Official SpecFact bundle IDs, trust tiers, and bundle dependency behavior.
+---
+
+# Marketplace Bundles
+
+SpecFact publishes official workflow bundles in the dedicated modules repository:
+
+- Registry repository: <https://github.com/nold-ai/specfact-cli-modules>
+- Registry index: `registry/index.json`
+
+## Official Bundles
+
+Install commands:
+
+```bash
+specfact module install nold-ai/specfact-project
+specfact module install nold-ai/specfact-backlog
+specfact module install nold-ai/specfact-codebase
+specfact module install nold-ai/specfact-spec
+specfact module install nold-ai/specfact-govern
+```
+
+Bundle overview:
+
+- `nold-ai/specfact-project`: project lifecycle commands (`project`, `plan`, `import`, `sync`, `migrate`)
+- `nold-ai/specfact-backlog`: backlog and policy workflows (`backlog`, `policy`)
+- `nold-ai/specfact-codebase`: codebase analysis and validation (`analyze`, `drift`, `validate`, `repro`)
+- `nold-ai/specfact-spec`: API/spec workflows (`contract`, `api`, `sdd`, `generate`)
+- `nold-ai/specfact-govern`: governance and patch workflows (`enforce`, `patch`)
+
+## Trust Tiers
+
+Marketplace modules are validated with tier and publisher metadata:
+
+- `official`: trusted publisher allowlist (`nold-ai`) with official verification output
+- `community`: signed/verified community publisher module
+- unsigned/local-dev: local or unsigned content, intended for development workflows only
+
+When listing modules, official modules display an `[official]` marker.
+When installing an official bundle, output confirms verification (for example `Verified: official (nold-ai)`).
+
+## Bundle Dependencies
+
+Some bundles declare bundle-level dependencies that are auto-installed:
+
+- `nold-ai/specfact-spec` auto-installs `nold-ai/specfact-project`
+- `nold-ai/specfact-govern` auto-installs `nold-ai/specfact-project`
+
+If a dependency bundle is already installed, installer skips it and continues.
+
+## See Also
+
+- [Module Marketplace](module-marketplace.md)
+- [Installing Modules](installing-modules.md)
+- [Module Categories](../reference/module-categories.md)

docs/guides/module-marketplace.md

@@ -9,6 +9,9 @@ description: Registry model, discovery priority, trust semantics, and security c
 
 SpecFact supports centralized marketplace distribution with local multi-source discovery.
 
+For the curated official bundle list and trust/dependency quick reference, see
+[Marketplace Bundles](marketplace.md).
+
 ## Registry Overview
 
 - **Official registry**: <https://github.com/nold-ai/specfact-cli-modules> (index: `registry/index.json`)

docs/index.md

@@ -141,8 +141,17 @@ See [Module Categories](reference/module-categories.md) for full mappings and pr
 
 SpecFact now supports a central marketplace workflow for module installation and lifecycle management.
 
+Official bundles are now marketplace-distributed as `nold-ai/specfact-*` modules:
+
+- `nold-ai/specfact-project`
+- `nold-ai/specfact-backlog`
+- `nold-ai/specfact-codebase`
+- `nold-ai/specfact-spec`
+- `nold-ai/specfact-govern`
+
 - **[Installing Modules](guides/installing-modules.md)** - Install, list, uninstall, and upgrade modules
 - **[Module Marketplace](guides/module-marketplace.md)** - Registry model, security checks, and discovery priority
+- **[Marketplace Bundles](guides/marketplace.md)** - Official bundle ids, trust tiers, and dependency auto-install behavior
 - **[Module Signing and Key Rotation](guides/module-signing-and-key-rotation.md)** - Signing and key management runbook
 
 Module lifecycle note: use `specfact module` (`init`, `install`, `list`, `show`, `search`, `enable`, `disable`, `uninstall`, `upgrade`) for module management.

docs/reference/module-categories.md

@@ -58,6 +58,25 @@ Category command groups:
 - `specfact-spec`: `contract`, `api`, `sdd`, `generate`
 - `specfact-govern`: `enforce`, `patch`
 
+## Bundle Package Layout and Namespaces
+
+Official bundle packages are published from the dedicated modules repository:
+
+- Repository: `nold-ai/specfact-cli-modules`
+- Package roots: `packages/specfact-project/`, `packages/specfact-backlog/`, `packages/specfact-codebase/`, `packages/specfact-spec/`, `packages/specfact-govern/`
+
+Namespace mapping:
+
+- `specfact-project` -> import namespace `specfact_project.*`
+- `specfact-backlog` -> import namespace `specfact_backlog.*`
+- `specfact-codebase` -> import namespace `specfact_codebase.*`
+- `specfact-spec` -> import namespace `specfact_spec.*`
+- `specfact-govern` -> import namespace `specfact_govern.*`
+
+Compatibility note:
+
+- Legacy `specfact_cli.modules.*` import paths remain as re-export shims during migration.
+
 ## First-Run Profiles
 
 `specfact init` supports profile presets and explicit bundle selection: