chore(release): v0.40.0

.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,57 @@ 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
+
+- Category command groups and first-run bundle selection (OpenSpec change `module-migration-01-categorize-and-group`, issue [#315](https://github.com/nold-ai/specfact-cli/issues/315)): `specfact` now organizes workflow commands under `project`, `backlog`, `code`, `spec`, and `govern`, with profile-driven and explicit bundle selection during `specfact init`.
+- 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.
+- Modules-repo quality parity baseline (OpenSpec change `module-migration-05-modules-repo-quality`, issue [#334](https://github.com/nold-ai/specfact-cli/issues/334)): the extracted bundle repo now carries mirrored quality gates, test layout, import-boundary checks, docs baseline, and CI orchestration so it can serve as the canonical home for official bundles.
+- Backlog bundle auth command group (OpenSpec change `backlog-auth-01-backlog-auth-commands`, issue [#340](https://github.com/nold-ai/specfact-cli/issues/340)): `specfact backlog auth` now provides `azure-devops`, `github`, `status`, and `clear` using core `specfact_cli.utils.auth_tokens` storage.
+- 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`.
+- Core-slimming verification gate: `scripts/verify-bundle-published.py` plus `hatch run verify-removal-gate` for signed-bundle publication checks before source deletion.
+- Core-slimming integration and E2E coverage: `tests/integration/test_core_slimming.py` and `tests/e2e/test_core_slimming_e2e.py`.
+- GitHub change-export helper: `scripts/export-change-to-github.py` and hatch alias `hatch run export-change-github -- ...` for `sync bridge` exports with optional in-place issue updates.
+
+### Changed
+
+- Core package slimming and mandatory bundle-first runtime (OpenSpec change `module-migration-03-core-slimming`, issue [#317](https://github.com/nold-ai/specfact-cli/issues/317)): the default install now stays lean, core keeps only permanent runtime/lifecycle commands, and `specfact init` requires an explicit profile or bundle selection before non-core workflows are available.
+- 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.
+- Full docs alignment audit for the lean-core plus modules-repo architecture (OpenSpec change `docs-01-core-modules-docs-alignment`, issue [#348](https://github.com/nold-ai/specfact-cli/issues/348)): README, docs landing pages, reference pages, tutorials, and publishing/signing guidance were reviewed and corrected so command examples use grouped command paths, bundle ownership is attributed to `specfact-cli-modules`, and temporary-in-core module docs are explicitly marked for future migration.
+- Core help/registry behavior now mounts category groups only for installed bundles, preventing non-installed groups from appearing at top level.
+- Marketplace package loader now resolves namespaced command entrypoints (`src/<package>/<command>/app.py`) for installed modules.
+- Installed bundle detection now infers `specfact-*` bundle IDs from namespaced module names when manifest `bundle` metadata is absent.
+- Core/module ownership boundaries were tightened after extraction (OpenSpec change `module-migration-06-core-decoupling-cleanup`, issue [#338](https://github.com/nold-ai/specfact-cli/issues/338)): residual non-core helpers, models, and import paths were reviewed and reduced so core focuses on bootstrap, lifecycle, trust, and shared runtime responsibilities.
+- Post-migration test ownership was clarified (OpenSpec change `module-migration-07-test-migration-cleanup`, issue [#339](https://github.com/nold-ai/specfact-cli/issues/339)): extracted-module behavior tests are being moved to `specfact-cli-modules`, while `specfact-cli` retains only core runtime and compatibility coverage.
+
+### Removed
+
+- **BREAKING**: Removed flat root command shims (OpenSpec change `module-migration-04-remove-flat-shims`, issue [#330](https://github.com/nold-ai/specfact-cli/issues/330)). Use grouped commands only, for example `specfact code validate` instead of `specfact validate`.
+
+### 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.
+
+### Fixed
+
+- Grouped command registration now preserves duplicate-command extension merging correctly, and first-run detection now treats project-scoped installed bundles as satisfying bundle availability checks in the new modular layout.
+- Azure DevOps backlog creation now validates required mapped custom fields and constrained picklist values before submit (OpenSpec change `backlog-core-07-ado-required-custom-fields-and-picklists`, issue [#337](https://github.com/nold-ai/specfact-cli/issues/337)).
+- `specfact backlog map-fields --non-interactive` now auto-discovers required ADO custom fields and picklist/list-backed allowed values, persists them into `.specfact/backlog-config.yaml`, and fails with guidance only when deterministic auto-mapping cannot resolve the field setup.
+- Azure DevOps description and acceptance-criteria text fields now default to Markdown rendering, with HTML-like input normalized to Markdown before create/write calls so add-time validation and downstream prompts operate on one text format.
+- Residual post-migration test and fixture failures were reduced by updating legacy test assumptions around removed flat commands, extracted-module import paths, and signing/script fixtures to match the decoupled modules architecture.
+
+### Migration
+
+- Continue using `0.40.0` in this branch; migration-03 closeout updates are tracked under this same release line (no new version section added yet).
+
 ---
 
 ## [0.39.0] - 2026-02-28

README.md

@@ -34,8 +34,12 @@ pip install -U specfact-cli
 ### Bootstrap and IDE Setup
 
 ```bash
-# Bootstrap module registry and local config (~/.specfact)
-specfact init
+# First run: install workflow bundles (required)
+specfact init --profile solo-developer
+
+# Other first-run options
+specfact init --install backlog,codebase
+specfact init --install all
 
 # First-run bundle selection (examples)
 specfact init --profile solo-developer
@@ -59,6 +63,14 @@ specfact code validate sidecar init my-project /path/to/repo
 specfact code validate sidecar run my-project /path/to/repo
 ```
 
+### Migration Note (Flat Commands Removed)
+
+As of `0.40.0`, flat root commands are removed. Use grouped commands:
+
+- `specfact validate ...` -> `specfact code validate ...`
+- `specfact plan ...` -> `specfact project plan ...`
+- `specfact policy ...` -> `specfact backlog policy ...`
+
 ### Backlog Bridge (60 seconds)
 
 SpecFact's USP is closing the drift gap between **backlog -> specs -> code**.
@@ -73,7 +85,7 @@ specfact backlog daily ado --ado-org <org> --ado-project "<project>" --state any
 specfact backlog refine ado --ado-org <org> --ado-project "<project>" --id <work-item-id> --preview
 
 # 3) Keep backlog + spec intent aligned (avoid silent drift)
-specfact policy validate --group-by-item
+specfact backlog policy validate --group-by-item
 ```
 
 For GitHub, replace adapter/org/project with:
@@ -141,18 +153,18 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 Recommended command entrypoints:
 - `specfact backlog ceremony standup ...`
 - `specfact backlog ceremony refinement ...`
-- `specfact policy validate ...`
-- `specfact policy suggest ...`
+- `specfact backlog policy validate ...`
+- `specfact backlog policy suggest ...`
 
 What the Policy Engine does in practice:
 - Turns team agreements (DoR, DoD, flow checks) into executable checks against your real backlog data.
 - Shows exactly what is missing per item (for example missing acceptance criteria or definition of done).
 - Generates patch-ready suggestions so teams can fix policy gaps quickly without guessing.
 
 Start with:
-- `specfact policy init --template scrum`
-- `specfact policy validate --group-by-item`
-- `specfact policy suggest --group-by-item --limit 5`
+- `specfact backlog policy init --template scrum`
+- `specfact backlog policy validate --group-by-item`
+- `specfact backlog policy suggest --group-by-item --limit 5`
 
 **Try it now**
 
@@ -163,13 +175,12 @@ Start with:
 
 ## Modules and Capabilities
 
-**Core modules**
+**Core runtime**
 
-- **Analyze**: Extract specs and plans from existing code.
-- **Validate**: Enforce contracts, run reproducible checks, and block regressions.
-- **Report**: CI/CD summaries and evidence outputs.
+- **Permanent commands**: `init`, `module`, `upgrade`
+- **Core responsibilities**: lifecycle, registry, trust, contracts, orchestration, shared runtime utilities
 
-**Agile DevOps modules**
+**Marketplace-installed bundles**
 
 - **Backlog**: Refinement, dependency analysis, sprint summaries, risk rollups.
 - **Ceremony**: Standup, refinement, and planning entry points.
@@ -188,6 +199,41 @@ 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`.
+Bundle-specific docs are still temporarily hosted in this docs set while the long-term
+bundle docs home is prepared in the modules repository docs site:
+`https://nold-ai.github.io/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
+```
+
+If startup warns that bundled modules are missing or outdated, run:
+
+```bash
+specfact module init --scope project
+specfact module init
+```
+
+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`
+
+Use this repo's docs for the current CLI/runtime release branch. Module-specific guides
+will move to `specfact-cli-modules` so future bundle-only changes do not require ongoing
+docs maintenance in long-lived `specfact-cli` release branches.
+
 ---
 
 ## Where SpecFact Fits

docs/README.md

@@ -22,18 +22,18 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 Recommended command entrypoints:
 - `specfact backlog ceremony standup ...`
 - `specfact backlog ceremony refinement ...`
-- `specfact policy validate ...`
-- `specfact policy suggest ...`
+- `specfact backlog policy validate ...`
+- `specfact backlog policy suggest ...`
 
 What the Policy Engine does in practice:
 - Converts team working agreements (DoR, DoD, flow/PI readiness) into deterministic checks.
 - Flags exact policy gaps per backlog item with actionable evidence pointers.
 - Produces patch-ready suggestions so teams can remediate quickly.
 
 Start with:
-- `specfact policy init --template scrum`
-- `specfact policy validate --group-by-item`
-- `specfact policy suggest --group-by-item --limit 5`
+- `specfact backlog policy init --template scrum`
+- `specfact backlog policy validate --group-by-item`
+- `specfact backlog policy suggest --group-by-item --limit 5`
 
 **Try it now**
 
@@ -55,13 +55,12 @@ Start with:
 
 ## Modules and Capabilities
 
-**Core modules**
+**Core runtime**
 
-- **Analyze**: Extract specs and plans from existing code.
-- **Validate**: Enforce contracts, run reproducible checks, and block regressions.
-- **Report**: CI/CD summaries and evidence outputs.
+- **Permanent commands**: `init`, `module`, `upgrade`
+- **Core responsibilities**: lifecycle, registry, trust, contracts, orchestration, shared runtime utilities
 
-**Agile DevOps modules**
+**Marketplace-installed bundles**
 
 - **Backlog**: Refinement, dependency analysis, sprint summaries, risk rollups.
 - **Ceremony**: Standup, refinement, and planning entry points.
@@ -85,12 +84,16 @@ SpecFact CLI uses a lifecycle-managed module system:
 
 This is the baseline for marketplace-driven module lifecycle and future community module distribution.
 
+Module-specific guides are still temporarily hosted in this docs set while the long-term
+bundle docs home is prepared in `nold-ai/specfact-cli-modules`.
+
 ### Why the Module System Is the Foundation
 
 This architecture intentionally separates the CLI core from feature modules:
 
 - Core provides lifecycle, registry, contracts, and orchestration.
-- Modules provide feature-specific command logic and integrations.
+- Official workflow bundles are authored and released from `nold-ai/specfact-cli-modules`.
+- This docs set still hosts bundle-specific guidance temporarily for the `0.40.x` release line.
 - Compatibility shims preserve legacy import paths during migration windows.
 
 Practical outcomes: