Harden CLI command reliability gates

.github/ISSUE_TEMPLATE/augmentation_metadata.md

@@ -42,7 +42,7 @@ specfact <command> --option value
 **Example:**
 
 ```bash
-specfact import from-code ./legacy-project --exclude "tests/**" --confidence 0.7
+specfact code import --repo ./legacy-project legacy-project --exclude-tests --confidence 0.7
 ```
 
 ## Alternative Solutions

.github/ISSUE_TEMPLATE/bug_report.md

@@ -23,7 +23,7 @@ specfact <command> --options
 **Example:**
 
 ```bash
-specfact import from-code ./my-legacy-project --confidence 0.8
+specfact code import --repo ./my-legacy-project legacy-project --confidence 0.8
 ```
 
 ## Expected Behavior

.github/pull_request_template.md

@@ -36,7 +36,7 @@ Please check all that apply:
 - [ ] **Contract validation**: `hatch run contract-test-contracts` ✅
 - [ ] **Contract exploration**: `hatch run contract-test-exploration` ✅
 - [ ] **Scenario tests**: `hatch run contract-test-scenarios` ✅
-- [ ] **Full test suite**: `hatch run contract-test-full` ✅
+- [ ] **Full test suite**: `hatch run smart-test-full` ✅
 
 ### Test Quality
 

.github/workflows/docs-review.yml

@@ -8,7 +8,10 @@ on:
     paths:
       - "**/*.md"
       - "**/*.mdc"
+      - ".github/**"
       - "docs/**"
+      - "resources/**"
+      - "src/specfact_cli/resources/**"
       - "docs/.doc-frontmatter-enforced"
       - "tests/unit/docs/**"
       - "tests/unit/scripts/test_doc_frontmatter/**"
@@ -17,6 +20,10 @@ on:
       - "tests/helpers/doc_frontmatter_fixtures.py"
       - "tests/helpers/doc_frontmatter_types.py"
       - "scripts/check-docs-commands.py"
+      - "scripts/check-command-contract.py"
+      - "scripts/generate-command-overview.py"
+      - "docs/reference/commands.generated.*"
+      - "llms.txt"
       - "scripts/check-cross-site-links.py"
       - "scripts/check_doc_frontmatter.py"
       - "scripts/validate_agent_rule_applies_when.py"
@@ -29,7 +36,10 @@ on:
     paths:
       - "**/*.md"
       - "**/*.mdc"
+      - ".github/**"
       - "docs/**"
+      - "resources/**"
+      - "src/specfact_cli/resources/**"
       - "docs/.doc-frontmatter-enforced"
       - "tests/unit/docs/**"
       - "tests/unit/scripts/test_doc_frontmatter/**"
@@ -38,6 +48,10 @@ on:
       - "tests/helpers/doc_frontmatter_fixtures.py"
       - "tests/helpers/doc_frontmatter_types.py"
       - "scripts/check-docs-commands.py"
+      - "scripts/check-command-contract.py"
+      - "scripts/generate-command-overview.py"
+      - "docs/reference/commands.generated.*"
+      - "llms.txt"
       - "scripts/check-cross-site-links.py"
       - "scripts/check_doc_frontmatter.py"
       - "scripts/validate_agent_rule_applies_when.py"
@@ -60,6 +74,29 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Resolve module command sources ref
+        id: modules-ref
+        shell: bash
+        env:
+          CANDIDATE_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          candidate="${CANDIDATE_REF}"
+          if [ -n "$candidate" ] && git ls-remote --exit-code --heads https://github.com/nold-ai/specfact-cli-modules.git "$candidate" >/dev/null 2>&1; then
+            echo "ref=$candidate" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout module command sources
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          repository: nold-ai/specfact-cli-modules
+          path: specfact-cli-modules
+          ref: ${{ steps.modules-ref.outputs.ref }}
+          persist-credentials: false
+
+      - name: Export module command source path
+        run: echo "SPECFACT_MODULES_REPO=${GITHUB_WORKSPACE}/specfact-cli-modules" >> "$GITHUB_ENV"
 
       - name: Set up Python 3.12
         uses: actions/setup-python@v5
@@ -78,6 +115,12 @@ jobs:
       - name: Validate docs command examples
         run: hatch run check-docs-commands
 
+      - name: Validate generated command overview
+        run: hatch run check-command-overview
+
+      - name: Validate generated command contract
+        run: hatch run check-command-contract
+
       - name: Cross-site links (warn-only; live site may lag deploys)
         continue-on-error: true
         run: hatch run check-cross-site-links --warn-only

.github/workflows/pr-orchestrator.yml

@@ -217,13 +217,28 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Resolve module bundles ref
+        id: modules-ref
+        if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
+        shell: bash
+        env:
+          CANDIDATE_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          candidate="${CANDIDATE_REF}"
+          if [ -n "$candidate" ] && git ls-remote --exit-code --heads https://github.com/nold-ai/specfact-cli-modules.git "$candidate" >/dev/null 2>&1; then
+            echo "ref=$candidate" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=dev" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Checkout module bundles repo
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
         with:
           repository: nold-ai/specfact-cli-modules
           path: specfact-cli-modules
-          ref: ${{ (github.ref == 'refs/heads/main' || github.head_ref == 'main') && 'main' || 'dev' }}
+          ref: ${{ steps.modules-ref.outputs.ref }}
+          persist-credentials: false
 
       - name: Export module bundles path
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
@@ -242,7 +257,7 @@ jobs:
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
         run: |
           python -m pip install --upgrade pip
-          pip install "hatch" "virtualenv<21" coverage "coverage[toml]" pytest pytest-cov pytest-mock pytest-asyncio pytest-xdist pytest-timeout
+          pip install "hatch" "virtualenv<21" pipx uv coverage "coverage[toml]" pytest pytest-cov pytest-mock pytest-asyncio pytest-xdist pytest-timeout
           pip install -e ".[dev]"
 
       - name: Verify version strings are synchronized
@@ -310,7 +325,7 @@ jobs:
         if: needs.changes.outputs.skip_tests_dev_to_main != 'true'
         shell: bash
         run: |
-          python scripts/runtime_discovery_smoke.py --launcher direct --launcher pip-editable --launcher uvx
+          python scripts/runtime_discovery_smoke.py --launcher direct --launcher hatch-source --launcher pip-editable --launcher pipx --launcher uv-run --launcher uvx
 
       - name: Set run_unit_coverage (or skip for dev→main)
         id: detect-unit
@@ -373,12 +388,26 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v4
+      - name: Resolve module bundles ref
+        id: modules-ref
+        shell: bash
+        env:
+          CANDIDATE_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          candidate="${CANDIDATE_REF}"
+          if [ -n "$candidate" ] && git ls-remote --exit-code --heads https://github.com/nold-ai/specfact-cli-modules.git "$candidate" >/dev/null 2>&1; then
+            echo "ref=$candidate" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=dev" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Checkout module bundles repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
         with:
           repository: nold-ai/specfact-cli-modules
           path: specfact-cli-modules
-          ref: ${{ (github.ref == 'refs/heads/main' || github.head_ref == 'main') && 'main' || 'dev' }}
+          ref: ${{ steps.modules-ref.outputs.ref }}
+          persist-credentials: false
       - name: Export module bundles path
         run: echo "SPECFACT_MODULES_REPO=${GITHUB_WORKSPACE}/specfact-cli-modules" >> "$GITHUB_ENV"
       - name: Set up Python 3.11
@@ -428,12 +457,26 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v4
+      - name: Resolve module bundles ref
+        id: modules-ref
+        shell: bash
+        env:
+          CANDIDATE_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          candidate="${CANDIDATE_REF}"
+          if [ -n "$candidate" ] && git ls-remote --exit-code --heads https://github.com/nold-ai/specfact-cli-modules.git "$candidate" >/dev/null 2>&1; then
+            echo "ref=$candidate" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=dev" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Checkout module bundles repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
         with:
           repository: nold-ai/specfact-cli-modules
           path: specfact-cli-modules
-          ref: ${{ (github.ref == 'refs/heads/main' || github.head_ref == 'main') && 'main' || 'dev' }}
+          ref: ${{ steps.modules-ref.outputs.ref }}
+          persist-credentials: false
       - name: Export module bundles path
         run: echo "SPECFACT_MODULES_REPO=${GITHUB_WORKSPACE}/specfact-cli-modules" >> "$GITHUB_ENV"
       - name: Set up Python 3.12
@@ -463,8 +506,11 @@ jobs:
         run: |
           echo "🔍 Validating runtime contracts..."
           REPRO_LOG="logs/repro/repro_$(date -u +%Y%m%d_%H%M%S).log"
-          echo "Running contract-first validation with required CrossHair... (log: $REPRO_LOG)"
-          hatch run contract-test 2>&1 | tee "$REPRO_LOG"
+          echo "Running scoped contract-first validation with required CrossHair... (log: $REPRO_LOG)"
+          {
+            hatch run contract-test-contracts
+            hatch run contract-test-exploration-fast
+          } 2>&1 | tee "$REPRO_LOG"
           exit "${PIPESTATUS[0]:-$?}"
       - name: Upload repro logs
         if: always()
@@ -490,6 +536,28 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v4
+      - name: Resolve module command sources ref
+        id: modules-ref
+        shell: bash
+        env:
+          CANDIDATE_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          candidate="${CANDIDATE_REF}"
+          if [ -n "$candidate" ] && git ls-remote --exit-code --heads https://github.com/nold-ai/specfact-cli-modules.git "$candidate" >/dev/null 2>&1; then
+            echo "ref=$candidate" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout module command sources
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          repository: nold-ai/specfact-cli-modules
+          path: specfact-cli-modules
+          ref: ${{ steps.modules-ref.outputs.ref }}
+          persist-credentials: false
+      - name: Export module command source 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:
@@ -500,11 +568,16 @@ jobs:
       - name: Install CLI
         run: |
           echo "Installing SpecFact CLI..."
+          python -m pip install --upgrade pip
+          python -m pip install "hatch" "virtualenv<21"
           pip install -e .
       - name: Validate CLI commands
         run: |
           echo "🔍 Validating CLI commands..."
           specfact --help
+          hatch run check-command-overview
+          hatch run check-command-contract
+          hatch run check-docs-commands
           echo "✅ CLI validation complete"
 
   quality-gates:

.github/workflows/specfact.yml

@@ -47,6 +47,32 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Resolve module bundles ref
+        id: modules-ref
+        shell: bash
+        env:
+          CANDIDATE_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          candidate="${CANDIDATE_REF}"
+          if [ -n "$candidate" ] && git ls-remote --exit-code --heads https://github.com/nold-ai/specfact-cli-modules.git "$candidate" >/dev/null 2>&1; then
+            echo "ref=$candidate" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=dev" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout module bundles repo
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          repository: nold-ai/specfact-cli-modules
+          path: specfact-cli-modules
+          ref: ${{ steps.modules-ref.outputs.ref }}
+          persist-credentials: false
+
+      - name: Export module bundles path
+        run: |
+          echo "SPECFACT_MODULES_REPO=${GITHUB_WORKSPACE}/specfact-cli-modules" >> "$GITHUB_ENV"
+          echo "SPECFACT_MODULES_ROOTS=${GITHUB_WORKSPACE}/specfact-cli-modules/packages" >> "$GITHUB_ENV"
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -83,8 +109,17 @@ jobs:
         id: repro
         continue-on-error: true
         run: |
-          specfact repro --verbose --crosshair-required --budget ${{ steps.validation.outputs.budget }} || true
-          echo "exit_code=$?" >> "$GITHUB_OUTPUT"
+          budget='${{ steps.validation.outputs.budget }}'
+          if ! [[ "$budget" =~ ^[0-9]+$ ]]; then
+            echo "Invalid budget: $budget" >&2
+            echo "exit_code=2" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          set +e
+          specfact code repro --verbose --crosshair-required --budget "$budget"
+          rc=$?
+          set -e
+          echo "exit_code=$rc" >> "$GITHUB_OUTPUT"
 
       - name: Find latest repro report
         id: report

.markdownlint.json

@@ -1,8 +1,17 @@
 {
   "default": true,
+  "MD024": {
+    "siblings_only": true
+  },
+  "MD025": {
+    "front_matter_title": ""
+  },
+  "MD029": false,
   "MD013": false,
   "MD033": false,
+  "MD036": false,
+  "MD040": true,
+  "MD051": false,
   "MD041": false,
   "MD060": false
 }
-