@boyingliu01/xp-gate 0.18.2 → 0.18.3

package/adapters/gate-9.sh

@@ -102,3 +102,4 @@ console.log('  ['+severity+'] '+ruleId);console.log('  '+path+':'+line+' → '+m
   fi
 fi
 record_gate_audit "gate-9" "sast-security" "$GATE_9_STATUS" "0" "$GATE_9_START"
+

package/bin/xp-gate.js

@@ -28,6 +28,46 @@ function handleUIReview() {
   }
 }
 
+async function runAlignmentCheck(subargs) {
+  const specIdx = subargs.indexOf('--spec');
+  const specPath = specIdx >= 0 ? subargs[specIdx + 1] : path.join(process.cwd(), 'specification.yaml');
+
+  const testsIdx = subargs.indexOf('--tests');
+  const testDirs = testsIdx >= 0 ? [subargs[testsIdx + 1]] : undefined;
+
+  const outputIdx = subargs.indexOf('--output');
+  const outputPath = outputIdx >= 0 ? subargs[outputIdx + 1] : undefined;
+
+  const jsonMode = subargs.includes('--json');
+
+  // Load TS module via tsx
+  const { execSync } = require('child_process');
+  const alignmentPath = path.join(__dirname, '..', 'lib', 'test-alignment.ts');
+
+  try {
+    execSync(`npx tsx -e "
+      import { runFullAlignment } from '${alignmentPath}';
+      const report = runFullAlignment({
+        specPath: '${specPath}',
+        testDirs: ${JSON.stringify(testDirs || null)},
+        headCommit: require('child_process').execSync('git rev-parse HEAD 2>/dev/null || echo unknown').toString().trim(),
+        outputPath: ${outputPath ? `'${outputPath}'` : 'undefined'},
+      });
+      if (${jsonMode}) {
+        console.log(JSON.stringify(report, null, 2));
+      } else {
+        console.log('Status:', report.alignment_status);
+        console.log('Score:', report.score);
+        console.log('Misaligned:', report.misaligned_tests.length);
+      }
+      process.exit(report.alignment_status === 'PASS' ? 0 : 1);
+    "`, { stdio: 'inherit' });
+  } catch (err) {
+    return 1;
+  }
+  return 0;
+}
+
 const COMMANDS = {
   'init': {
     description: 'Initialize xp-gate (use --global for all projects)',
@@ -131,6 +171,11 @@ const COMMANDS = {
     run: subargs => arch(subargs).then(code => process.exit(code)),
     usage: 'xp-gate arch [--config <path>]'
   },
+  'check-alignment': {
+    description: 'Run test-specification alignment check (deterministic, no LLM)',
+    run: subargs => runAlignmentCheck(subargs).then(code => process.exit(code)),
+    usage: 'xp-gate check-alignment [--spec <path>] [--tests <dir>] [--json] [--output <path>]'
+  },
   'upgrade': {
     description: 'Check for xp-gate updates (--preview for JSON, --apply to upgrade)',
     run: subargs => upgrade(subargs).then(code => process.exit(code)),

package/hooks/pre-commit

@@ -1,10 +1,10 @@
 #!/bin/bash
-# OpenCode Quality Gates - Pre-Commit Hook - Refactored 6-Type-Based Gates
+# OpenCode Quality Gates - Pre-Commit Hook - 12 numbered gates (Gate 0–11)
 # 
-# DESIGN PRINCIPLE: Zero tolerance - tool unavailable = BLOCK (per CODE-OF-CONDUCT.md)
-# Each gate requires its tools to be installed; missing tools block the commit.
+# DESIGN PRINCIPLE: Tool unavailable = SKIP (graceful degradation), tool available + check fails = BLOCK
+# Missing tools do NOT block the commit — the gate degrades to SKIP. Block fires only when
+# the tool exists AND the check fails. This prevents broken toolchains from blocking work.
 #
-# Converts 9 sequential gates into 6 type-based comprehensive gates
 # Sourced from adapter-common.sh and language-specific adapters
 
 # Source the common adapter functions — 3-tier resolution:
@@ -1328,7 +1328,9 @@ source "$GATE_DIR/gate-4.sh"
 # v0.14.3+ (Issue #312): Skip test run when no code files changed.
 # Code files = src/**/*.ts, plugins/**/*.ts, *.ts, *.tsx, etc. (language-aware).
 # VERSION, CHANGELOG, docs, config-only changes → SKIP test run entirely.
-# Gate 5a (new file pairing) and Gate 5b (mock density) still run — they're lightweight.
+  # Gate 5a (new file pairing), 5b (mock density), and 5c (semantic annotation)
+  # are lightweight and still run even when no code files changed.
+  # Gate 5a (new file pairing) and Gate 5b (mock density) still run — they're lightweight.
 # ============================================================================
  2>&1 echo ""
  2>&1 echo "→ Gate 5: Tests & coverage..."
@@ -1640,6 +1642,82 @@ else
     done
   fi
 
+  # ============================================================================
+  # Gate 5c: Semantic Annotation Check (v0.19.0+)
+  # Validates @test REQ-XXX annotations against specification.yaml.
+  #
+  # Strategy: Reads pre-compiled req-ids.json (produced by xp-gate check-alignment).
+  # If req-ids.json is absent or stale, degrades to SKIP.
+  # If present: greps staged tests for @test REQ-XXX, cross-references against
+  # the pre-compiled REQ ID list. BLOCKs if any REQ ID doesn't exist in spec.
+  # If any REQ in spec has no annotated test, emits visible [FAIL] message
+  # (exit 0, appears in hook summary) — full alignment check runs at CLI time.
+  # ============================================================================
+  REQ_IDS_FILE=".sprint-state/phase-outputs/req-ids.json"
+  if [ -f "$REQ_IDS_FILE" ] && command -v jq >/dev/null 2>&1; then
+    # Check staleness: req-ids.json must be newer than specification.yaml
+    SPEC_FILE="specification.yaml"
+    REQ_IDS_STALE=false
+    if [ -f "$SPEC_FILE" ]; then
+      if [ "$REQ_IDS_FILE" -ot "$SPEC_FILE" ]; then
+        REQ_IDS_STALE=true
+      fi
+    fi
+
+    if [ "$REQ_IDS_STALE" = true ]; then
+      echo "⚠️  Gate 5c: req-ids.json is stale (specification.yaml updated since last check-alignment)"
+      echo "   Run 'xp-gate check-alignment' to regenerate before next commit."
+    else
+      CHANGED_TEST_FILES_ANNOTATED=$(echo "$CHANGED_FILES" | grep -E '\.(test|spec)\.(ts|tsx|js|jsx)$' || true)
+      if [ -n "$CHANGED_TEST_FILES_ANNOTATED" ]; then
+        echo "  → Checking @test REQ-XXX annotations..."
+        ANNOTATION_ERRORS=0
+        for tf in $CHANGED_TEST_FILES_ANNOTATED; do
+          if [ -f "$tf" ]; then
+            # Extract @test REQ-XXX annotations from staged test file (word-bounded)
+            ANNOTATED_REQS=$(grep -oE '@test\s+REQ-[A-Z0-9-]+' "$tf" 2>/dev/null | sed 's/@test\s*//' | sort -u || true)
+            for req_id in $ANNOTATED_REQS; do
+              # Cross-reference against pre-compiled REQ ID list
+              FOUND=$(jq -r --arg rid "$req_id" '.[] | select(. == $rid)' "$REQ_IDS_FILE" 2>/dev/null || true)
+              if [ -z "$FOUND" ]; then
+                echo "❌ Gate 5c: $tf — @test $req_id: REQ ID not found in specification.yaml"
+                ANNOTATION_ERRORS=$((ANNOTATION_ERRORS + 1))
+              fi
+            done
+          fi
+        done
+
+        if [ "$ANNOTATION_ERRORS" -gt 0 ]; then
+          echo ""
+          echo "❌ $ANNOTATION_ERRORS test annotation(s) reference non-existent REQ IDs — commit BLOCKED"
+          echo "   Fix: Verify REQ IDs against specification.yaml, or run 'xp-gate check-alignment'"
+          exit 1
+        fi
+
+        # Check reverse: any REQ in spec with no annotated test → visible FAIL (non-blocking)
+        ALL_SPEC_REQS=$(jq -r '.[]' "$REQ_IDS_FILE" 2>/dev/null)
+        ANNOTATED_ALL=""
+        for tf in $(echo "$CHANGED_FILES" | grep -E '\.(test|spec)\.(ts|tsx|js|jsx)$' || true); do
+          if [ -f "$tf" ]; then
+            ANNOTATED_ALL="$ANNOTATED_ALL $(grep -oE '@test\s+REQ-[A-Z0-9-]+' "$tf" 2>/dev/null | sed 's/@test\s*//' || true)"
+          fi
+        done
+        UNTESTED_COUNT=0
+        for spec_req in $ALL_SPEC_REQS; do
+          if ! echo "$ANNOTATED_ALL" | grep -qF "$spec_req"; then
+            UNTESTED_COUNT=$((UNTESTED_COUNT + 1))
+          fi
+        done
+        if [ "$UNTESTED_COUNT" -gt 0 ]; then
+          echo "⚠️  [FAIL] Gate 5c: $UNTESTED_COUNT REQ(s) in specification.yaml have no annotated tests"
+          echo "   This is non-blocking. Run 'xp-gate check-alignment' for full alignment report."
+        fi
+
+        echo "  ✅ @test annotation check complete."
+      fi
+    fi
+  fi
+
   # ============================================================================
   # v0.14.3+ (Issue #312): Early skip when no code files changed.
   # If the commit only touches VERSION, CHANGELOG, docs, config, .gitignore,
@@ -2439,13 +2517,13 @@ generate_quality_report() {
   local TIMESTAMP
   local BRANCH
   local PASSED_COUNT=0
-  local TOTAL_GATES=11
+  local TOTAL_GATES=12
 
   COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
   BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
   TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
-  for gate in 1 2 3 4 5 6 7 8 9 10 11; do
+  for gate in 1 2 3 4 5 6 7 8 9 10 11 12; do
     local status_var="GATE_${gate}_STATUS"
     if [ "${!status_var}" = "PASS" ]; then
       PASSED_COUNT=$((PASSED_COUNT + 1))
@@ -2558,6 +2636,11 @@ generate_quality_report() {
       "name": "Sprint Flow Enforcement",
       "status": "${GATE_11_STATUS:-PASS}",
       "tool": "sprint-gate.sh"
+    },
+    "gate12_file_hygiene": {
+      "name": "File Hygiene Check",
+      "status": "${GATE_12_STATUS:-WARN}",
+      "tool": "gate-12-file-hygiene.sh"
     }
   }
 }
@@ -2583,8 +2666,8 @@ ENDJSON
   GATES_JSON="${GATES_JSON}\"gate8\":{\"status\":\"${GATE_8_STATUS:-PASS}\",\"name\":\"Secret Scanning\"},"
   GATES_JSON="${GATES_JSON}\"gate9\":{\"status\":\"${GATE_9_STATUS:-PASS}\",\"name\":\"Build Integrity\"},"
   GATES_JSON="${GATES_JSON}\"gate10\":{\"status\":\"${GATE_10_STATUS:-PASS}\",\"name\":\"SAST Security\"},"
-  GATES_JSON="${GATES_JSON}\"gate11\":{\"status\":\"${GATE_11_STATUS:-PASS}\",\"name\":\"Sprint Flow\"}}"
-  GATES_JSON="${GATES_JSON}}"
+  GATES_JSON="${GATES_JSON}\"gate11\":{\"status\":\"${GATE_11_STATUS:-PASS}\",\"name\":\"Sprint Flow\"},"
+  GATES_JSON="${GATES_JSON}\"gate12\":{\"status\":\"${GATE_12_STATUS:-WARN}\",\"name\":\"File Hygiene\"}}"
 
   echo "{\"timestamp\":\"$TIMESTAMP\",\"commit\":\"$COMMIT_HASH\",\"branch\":\"$BRANCH\",\"score\":$SCORE,\"passed\":$PASSED_COUNT,\"total\":$TOTAL_GATES,\"gates\":$GATES_JSON,\"coverage\":\"$COV_PCT\",\"complexityWarnings\":${CC_WARNINGS:-0},\"principleWarnings\":${WARNING_COUNT:-0},\"boyScoutBlocked\":${BS_BLOCKED}}" >> "$HISTORY_FILE"
 
@@ -2605,6 +2688,7 @@ ENDJSON
   printf "  %-45s %s\n" "Gate 9: Build Integrity" "${GATE_9_STATUS:-PASS}"
   printf "  %-45s %s\n" "Gate 10: SAST Security" "${GATE_10_STATUS:-PASS}"
   printf "  %-45s %s\n" "Gate 11: Sprint Flow" "${GATE_11_STATUS:-PASS}"
+  printf "  %-45s %s\n" "Gate 12: File Hygiene" "${GATE_12_STATUS:-WARN}"
   echo ""
   echo "  Overall Score: $SCORE/10 | $PASSED_COUNT/$TOTAL_GATES gates passed"
   echo "  Branch status: $REPORT_FILE"
@@ -2612,8 +2696,23 @@ ENDJSON
   echo "  History saved: $HISTORY_FILE"
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo ""
+  # AI-friendly common footer: tells LLM agents how to fix issues instead of bypassing
+  echo "  ── AI AGENT DIRECTIVE ──"
+  echo "  If any gate FAILED above:"
+  echo "    - Each error includes a file path and rule identifier"
+  echo "    - Fix each issue, then re-run: git commit"
+  echo "    - Do NOT use --no-verify — bypassed commits block sprint progression"
+  echo "  ─────────────────────────"
+  echo ""
 }
 
+# Post-commit bypass marker: write a sentinel file in .git/ directory
+# that the post-commit hook checks to detect --no-verify bypasses
+_wp_marker="$(git rev-parse --git-dir 2>/dev/null)/xp-gate-precommit-marker"
+if [ -n "$_wp_marker" ] && [ "$_wp_marker" != "/xp-gate-precommit-marker" ]; then
+  echo "$(date +%s)" > "$_wp_marker"
+fi
+
 generate_quality_report
 
 exit 0