Harden module command reliability gates

.github/pull_request_template.md

@@ -35,8 +35,9 @@ Paste command output snippets or link workflow runs.
 - [ ] `hatch run lint`
 - [ ] `hatch run yaml-lint`
 - [ ] `hatch run check-bundle-imports`
-- [ ] `hatch run contract-test`
-- [ ] `hatch run smart-test` (or `hatch run test`)
+- [ ] `hatch run contract-test-contracts`
+- [ ] `hatch run smart-test-check`
+- [ ] `hatch run test`
 
 ### Signature + version integrity (required)
 

.github/workflows/docs-review.yml

@@ -9,10 +9,14 @@ on:
       - "**/*.md"
       - "**/*.mdc"
       - "docs/**"
-      - "packages/*/resources/prompts/**"
+      - "packages/*/resources/**"
       - "requirements-docs-ci.txt"
       - "scripts/check-docs-commands.py"
       - "scripts/check-prompt-commands.py"
+      - "scripts/check-command-contract.py"
+      - "scripts/generate-command-overview.py"
+      - "docs/reference/commands.generated.*"
+      - "llms.txt"
       - "scripts/docs_site_validation.py"
       - "tests/unit/test_check_docs_commands_script.py"
       - "tests/unit/test_check_prompt_commands_script.py"
@@ -25,10 +29,14 @@ on:
       - "**/*.md"
       - "**/*.mdc"
       - "docs/**"
-      - "packages/*/resources/prompts/**"
+      - "packages/*/resources/**"
       - "requirements-docs-ci.txt"
       - "scripts/check-docs-commands.py"
       - "scripts/check-prompt-commands.py"
+      - "scripts/check-command-contract.py"
+      - "scripts/generate-command-overview.py"
+      - "docs/reference/commands.generated.*"
+      - "llms.txt"
       - "scripts/docs_site_validation.py"
       - "tests/unit/test_check_docs_commands_script.py"
       - "tests/unit/test_check_prompt_commands_script.py"
@@ -50,6 +58,37 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Resolve paired core command sources ref
+        id: core-ref
+        shell: bash
+        env:
+          CANDIDATE_REF: ${{ github.head_ref || github.ref_name }}
+          FALLBACK_REF: ${{ github.base_ref || github.ref_name }}
+        run: |
+          candidate="${CANDIDATE_REF}"
+          if [ -n "$candidate" ] && git ls-remote --exit-code --heads https://github.com/nold-ai/specfact-cli.git "$candidate" >/dev/null 2>&1; then
+            echo "ref=$candidate" >> "$GITHUB_OUTPUT"
+          else
+            fallback="${FALLBACK_REF:-dev}"
+            case "$fallback" in
+              main|dev) ;;
+              *) fallback="dev" ;;
+            esac
+            echo "ref=$fallback" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout paired core command sources
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          repository: nold-ai/specfact-cli
+          path: specfact-cli
+          ref: ${{ steps.core-ref.outputs.ref }}
+          persist-credentials: false
+
+      - name: Export paired core source path
+        run: echo "SPECFACT_CLI_REPO=${GITHUB_WORKSPACE}/specfact-cli" >> "$GITHUB_ENV"
 
       - name: Set up Python 3.12
         uses: actions/setup-python@v5
@@ -60,6 +99,7 @@ jobs:
       - name: Install docs review dependencies
         run: |
           python -m pip install --upgrade pip
+          python -m pip install hatch
           python -m pip install -r requirements-docs-ci.txt
 
       - name: Run docs review suite
@@ -81,6 +121,11 @@ jobs:
           mkdir -p logs/docs-review
           PROMPT_COMMAND_LOG="logs/docs-review/prompt-command-validation_$(date -u +%Y%m%d_%H%M%S).log"
           python scripts/check-prompt-commands.py 2>&1 | tee "$PROMPT_COMMAND_LOG"
+
+      - name: Validate generated command overview
+        run: |
+          hatch run check-command-overview
+          hatch run check-command-contract
           exit "${PIPESTATUS[0]:-$?}"
 
       - name: Upload docs review logs

.github/workflows/pr-orchestrator.yml

@@ -125,6 +125,39 @@ jobs:
       - name: Checkout
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Resolve paired core CLI ref
+        id: core-ref
+        if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
+        shell: bash
+        env:
+          CANDIDATE_REF: ${{ github.head_ref || github.ref_name }}
+          FALLBACK_REF: ${{ github.base_ref || github.ref_name }}
+        run: |
+          candidate="${CANDIDATE_REF}"
+          if [ -n "$candidate" ] && git ls-remote --exit-code --heads https://github.com/nold-ai/specfact-cli.git "$candidate" >/dev/null 2>&1; then
+            echo "ref=$candidate" >> "$GITHUB_OUTPUT"
+          else
+            fallback="${FALLBACK_REF:-dev}"
+            case "$fallback" in
+              main|dev) ;;
+              *) fallback="dev" ;;
+            esac
+            echo "ref=$fallback" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout paired core CLI
+        if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          repository: nold-ai/specfact-cli
+          path: specfact-cli
+          ref: ${{ steps.core-ref.outputs.ref }}
+          persist-credentials: false
+      - name: Export paired core CLI path
+        if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
+        run: echo "SPECFACT_CLI_REPO=${GITHUB_WORKSPACE}/specfact-cli" >> "$GITHUB_ENV"
       - name: Setup Python
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
         uses: actions/setup-python@v5
@@ -140,7 +173,17 @@ jobs:
         run: hatch env create
       - name: Install specfact-cli dependency
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
-        run: hatch run pip install "specfact-cli==0.46.2"
+        run: hatch run pip install -e ./specfact-cli
+      - name: Runtime discovery smoke across package managers
+        if: needs.changes.outputs.skip_tests_dev_to_main != 'true' && matrix.python-version == '3.12'
+        run: |
+          python -m pip install pipx uv "virtualenv<21"
+          hatch run python specfact-cli/scripts/runtime_discovery_smoke.py --modules-repo "${GITHUB_WORKSPACE}" --launcher direct --launcher hatch-source --launcher pip-editable --launcher pipx --launcher uv-run --launcher uvx
+      - name: Validate generated command overview
+        if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
+        run: |
+          hatch run check-command-overview
+          hatch run check-command-contract
       - name: Format
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
         run: hatch run format
@@ -158,10 +201,10 @@ jobs:
         run: hatch run check-bundle-imports
       - name: Contract Test
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
-        run: hatch run contract-test
-      - name: Smart Test
+        run: hatch run contract-test-contracts
+      - name: Smart Test Configuration
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
-        run: hatch run smart-test
-      - name: Test
+        run: hatch run smart-test-check
+      - name: Full Test Suite
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
         run: hatch run test

README.md

@@ -2,6 +2,11 @@
 
 Central module registry for SpecFact CLI. This repository hosts official **nold-ai** bundles and their documentation.
 
+## Command Overview
+
+- [Generated module command overview for humans](docs/reference/commands.generated.md)
+- [AI-agent module command overview](llms.txt)
+
 ## Highlight: AI-shaped bloat detection
 
 The Code Review bundle now surfaces `ai_bloat` findings: advisory, score-neutral signals tuned for the bloated shapes AI-assisted code commonly produces, such as identity `try/except`, one-call wrappers, passthrough lambdas, redundant intermediates, and long linear functions. A dry run on this change's affected package sources found 144 advisory candidates and applied 0 automatic rewrites; use `specfact code review run --json --out .specfact/code-review.json`, then run `/specfact.08-simplify` in your AI IDE to review each simplification with per-change confirmation. See the [AI bloat quickstart](./docs/quickstart-ai-bloat.md).

docs/adapters/azuredevops.md

@@ -67,7 +67,7 @@ The adapter automatically derives work item type from your project's process tem
 You can override with `--ado-work-item-type`:
 
 ```bash
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --ado-work-item-type "Bug" \
@@ -437,7 +437,7 @@ This handles cases where:
 
 ```bash
 # Export OpenSpec change proposals to Azure DevOps work items
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --repo /path/to/openspec-repo
@@ -447,7 +447,7 @@ specfact sync bridge --adapter ado --mode export-only \
 
 ```bash
 # Import work items AND export proposals
-specfact sync bridge --adapter ado --bidirectional \
+specfact project sync bridge --adapter ado --bidirectional \
   --ado-org your-org \
   --ado-project your-project \
   --repo /path/to/openspec-repo
@@ -457,7 +457,7 @@ specfact sync bridge --adapter ado --bidirectional \
 
 ```bash
 # Import specific work items into bundle
-specfact sync bridge --adapter ado --mode bidirectional \
+specfact project sync bridge --adapter ado --mode bidirectional \
   --ado-org your-org \
   --ado-project your-project \
   --bundle main \
@@ -469,7 +469,7 @@ specfact sync bridge --adapter ado --mode bidirectional \
 
 ```bash
 # Update existing work item with latest proposal content
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --change-ids add-feature-x \
@@ -481,7 +481,7 @@ specfact sync bridge --adapter ado --mode export-only \
 
 ```bash
 # Detect code changes and add progress comments
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --track-code-changes \
@@ -493,7 +493,7 @@ specfact sync bridge --adapter ado --mode export-only \
 
 ```bash
 # Export from bundle to ADO (uses stored lossless content)
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org your-org \
   --ado-project your-project \
   --bundle main \

docs/adapters/github.md

@@ -337,14 +337,14 @@ To create a GitHub issue from an OpenSpec change and have the issue number/URL w
 
 ```bash
 # Export one or more changes; creates issues and updates proposal.md Source Tracking
-specfact sync bridge --adapter github --mode export-only \
+specfact project sync bridge --adapter github --mode export-only \
   --repo . \
   --repo-owner nold-ai \
   --repo-name specfact-cli \
   --change-ids <change-id>
 
 # Example: export backlog-scrum-05-summarize-markdown-output
-specfact sync bridge --adapter github --mode export-only \
+specfact project sync bridge --adapter github --mode export-only \
   --repo . \
   --repo-owner nold-ai \
   --repo-name specfact-cli \
@@ -365,15 +365,15 @@ When you improve comment logic or branch detection, use `--include-archived` to
 
 ```bash
 # Update all archived proposals with new comment logic
-specfact sync bridge --adapter github --mode export-only \
+specfact project sync bridge --adapter github --mode export-only \
   --repo-owner your-org \
   --repo-name your-repo \
   --include-archived \
   --update-existing \
   --repo /path/to/openspec-repo
 
 # Update specific archived proposal
-specfact sync bridge --adapter github --mode export-only \
+specfact project sync bridge --adapter github --mode export-only \
   --repo-owner your-org \
   --repo-name your-repo \
   --change-ids add-code-change-tracking \

docs/agent-rules/20-repository-context.md

@@ -51,7 +51,7 @@ hatch run contract-test
 hatch run smart-test
 hatch run test
 # manual code review: always include --bug-hunt (CrossHair longer budgets; see bundle docs)
-hatch run specfact code review run --bug-hunt --json --out .specfact/code-review.json
+hatch run specfact code review run --enforcement changed --bug-hunt --json --out .specfact/code-review.json
 ```
 
 ## Architecture

docs/agent-rules/50-quality-gates-and-review.md

@@ -49,7 +49,7 @@ Before running quality gates in a fresh worktree, bootstrap the Hatch environmen
 7. `hatch run contract-test`
 8. `hatch run smart-test`
 9. `hatch run test`
-10. `hatch run specfact code review run --bug-hunt --json --out .specfact/code-review.json` (always pass **`--bug-hunt`** on manual runs so CrossHair uses bug-hunt timeouts; full-repo scope when required: add **`--scope full`**; machine-readable evidence lives at `.specfact/code-review.json` and unresolved findings block merge unless an explicit exception is documented)
+10. `hatch run specfact code review run --enforcement changed --bug-hunt --json --out .specfact/code-review.json` (always pass **`--bug-hunt`** on manual runs so CrossHair uses bug-hunt timeouts; use **`--enforcement full`** when legacy blockers in reviewed files must fail the run; full-repo scope when required: add **`--scope full`**; machine-readable evidence lives at `.specfact/code-review.json` and unresolved changed-line findings block merge unless an explicit exception is documented)
 
 ## Pre-commit order
 
@@ -68,7 +68,7 @@ Run the full pipeline manually with `./scripts/pre-commit-quality-checks.sh` or
 
 ## Clean-code review gate
 
-The repository enforces the clean-code charter through `specfact code review run`. When agents or developers invoke the review manually (outside the pre-commit helper), include **`--bug-hunt`** so the contract runner gives CrossHair the longer bug-hunt budgets documented in the code-review bundle. Zero regressions in `naming`, `kiss`, `yagni`, `dry`, and `solid` are required before merge.
+The repository enforces the clean-code charter through `specfact code review run`. When agents or developers invoke the review manually (outside the pre-commit helper), include **`--enforcement changed --bug-hunt`** so changed-line regressions block and CrossHair gets the longer bug-hunt budgets documented in the code-review bundle. Use **`--enforcement full`** only when the task explicitly requires every legacy blocker in reviewed files to fail the run. Zero regressions in `naming`, `kiss`, `yagni`, `dry`, and `solid` are required before merge.
 
 ## Module signature gate
 

docs/bundles/backlog/refinement.md

@@ -558,7 +558,7 @@ The most common workflow is to refine backlog items and then sync them to extern
 **Workflow**: `backlog ceremony refinement` → `sync bridge`
 
 1. **Refine Backlog Items**: Use `specfact backlog ceremony refinement` to standardize backlog items with templates
-2. **Sync to External Tools**: Use `specfact sync bridge` to sync refined items back to backlog tools (GitHub, ADO, etc.)
+2. **Sync to External Tools**: Use `specfact project sync bridge` to sync refined items back to backlog tools (GitHub, ADO, etc.)
 
 ```bash
 # Complete command chaining workflow
@@ -570,7 +570,7 @@ specfact backlog ceremony refinement github \
   --state open
 
 # 2. Sync refined items to external tool (same or different adapter)
-specfact sync bridge --adapter github \
+specfact project sync bridge --adapter github \
   --repo-owner my-org --repo-name my-repo \
   --backlog-ids 123,456 \
   --mode export-only
@@ -581,7 +581,7 @@ specfact backlog ceremony refinement github \
   --write \
   --labels feature
 
-specfact sync bridge --adapter ado \
+specfact project sync bridge --adapter ado \
   --ado-org my-org --ado-project my-project \
   --backlog-ids 123,456 \
   --mode export-only
@@ -617,12 +617,12 @@ When syncing backlog items between different adapters (e.g., GitHub ↔ ADO), Sp
 
 ```bash
 # 1. Import closed GitHub issues into bundle (state "closed" is preserved)
-specfact sync bridge --adapter github --mode bidirectional \
+specfact project sync bridge --adapter github --mode bidirectional \
   --repo-owner nold-ai --repo-name specfact-cli \
   --backlog-ids 110,122
 
 # 2. Export to ADO (state is automatically mapped: closed → Closed)
-specfact sync bridge --adapter ado --mode export-only \
+specfact project sync bridge --adapter ado --mode export-only \
   --ado-org dominikusnold --ado-project "SpecFact CLI" \
   --bundle cross-sync-test --change-ids add-ado-backlog-adapter,add-template-driven-backlog-refinement
 
@@ -649,14 +649,14 @@ specfact sync bridge --adapter ado --mode export-only \
 
 Backlog refinement works seamlessly with the [DevOps Adapter Integration](/integrations/devops-adapter-overview/):
 
-1. **Import Backlog Items**: Use `specfact sync bridge` to import backlog items as OpenSpec proposals
+1. **Import Backlog Items**: Use `specfact project sync bridge` to import backlog items as OpenSpec proposals
 2. **Refine Items**: Use `specfact backlog ceremony refinement` to standardize imported items
-3. **Export Refined Items**: Use `specfact sync bridge` to export refined proposals back to backlog tools
+3. **Export Refined Items**: Use `specfact project sync bridge` to export refined proposals back to backlog tools
 
 ```bash
 # Complete workflow
 # 1. Import GitHub issues as OpenSpec proposals
-specfact sync bridge --adapter github --mode bidirectional \
+specfact project sync bridge --adapter github --mode bidirectional \
   --repo-owner my-org --repo-name my-repo \
   --backlog-ids 123,456
 
@@ -665,7 +665,7 @@ specfact backlog ceremony refinement github --bundle my-project --auto-bundle \
   --search "is:open"
 
 # 3. Export refined proposals back to GitHub
-specfact sync bridge --adapter github --mode export-only \
+specfact project sync bridge --adapter github --mode export-only \
   --bundle my-project --change-ids <refined-change-id>
 ```
 
@@ -940,11 +940,11 @@ If adapter search methods are not available:
 # "Note: GitHub issue fetching requires adapter.search_issues() implementation"
 ```
 
-**Workaround**: Use `specfact sync bridge` to import backlog items first, then refine:
+**Workaround**: Use `specfact project sync bridge` to import backlog items first, then refine:
 
 ```bash
 # 1. Import backlog items
-specfact sync bridge --adapter github --mode bidirectional \
+specfact project sync bridge --adapter github --mode bidirectional \
   --backlog-ids 123,456
 
 # 2. Refine imported items from bundle