@boyingliu01/xp-gate 0.24.0 → 0.26.0

package/hooks/pre-commit

@@ -230,6 +230,16 @@ source "${AUDIT_SCRIPT_DIR}/lib/sprint-gate-report.sh"
 # unit-testable without executing this hook.
 source "${AUDIT_SCRIPT_DIR}/lib/coverage-total.sh"
 
+# Issue #399: Python smart test selection — strategy decision + related-test
+# lookup, kept in a library so the truth table and the path conventions are
+# unit-testable without executing this hook.
+source "${AUDIT_SCRIPT_DIR}/lib/python-test-selection.sh"
+
+# Issue #534: incremental Python type-check for the pre-commit python branch —
+# staged-only mypy (fast) that complements python.sh's CI-aligned full pass.
+# Kept in a library so the exit-code capture and scope handling are unit-testable.
+source "${AUDIT_SCRIPT_DIR}/lib/python-incremental-typecheck.sh"
+
 # Read max_duration_ms from .xp-gate-config.json (default 7200000 = 2 hours)
 _MAX_DURATION_MS=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('${PROJECT_ROOT_FOR_AUDIT}/.xp-gate-config.json','utf8'));console.log((c.audit&&c.audit.max_duration_ms)||7200000);}catch(e){console.log(7200000);}" 2>/dev/null || echo "7200000")
 
@@ -1303,24 +1313,38 @@ else
       fi
     fi
     
-    # Optional: Type checking with mypy
+    # Optional: Type checking with mypy — INCREMENTAL (fast, staged-only).
+    #
+    # Responsibility boundary (#534):
+    #   * This branch (python case) runs mypy ONLY over the staged .py/.pyi
+    #     files via python_typecheck_incremental — seconds, not a full inference
+    #     pass. Uses --follow-imports=silent so a change to A.py that references
+    #     an unchanged B.py does NOT surface B's pre-existing diagnostics; only
+    #     caller-level signature errors still block. Its exit code is captured
+    #     directly (temp file), which is deterministic and does not depend on
+    #     set -o pipefail (the old `... | head | tail; rc=$?` worked only under
+    #     pipefail and could drop mypy's status when the pattern is copied into
+    #     a non-pipefail context).
+    #   * The FULL mypy pass lives OUTSIDE this hook: run_static_analysis()
+    #     (githooks/adapters/python.sh) is reachable via the adapter CLI and the
+    #     general adapter route, and CI installs mypy (quality-gates.yml) for
+    #     typed projects. NOTE: the pre-commit python case is fully inline and
+    #     never routes to run_static_analysis — so the incremental blind spot
+    #     (cross-module signature break on an unchanged file) is the accepted
+    #     trade-off here, backstopped by full mypy wherever that surface runs.
+    #     Both paths coexist: this one is the fast pre-commit pass.
     if command -v mypy &> /dev/null; then
+      # Collect staged .py/.pyi via the helper (whitespace-safe, bash-3
+      # compatible — macOS default bash is 3.2, so avoid mapfile).
       MYPY_ARGS=()
       while IFS= read -r staged_file; do
-        case "$staged_file" in
-          *.py|*.pyi) MYPY_ARGS+=("$staged_file") ;;
-        esac
-      done <<< "$CHANGED_FILES"
-      if [ "${#MYPY_ARGS[@]}" -eq 0 ]; then
-        MYPY_EXIT=0
-      else
-        echo "Running mypy type checking (optional)..."
-        mypy --ignore-missing-imports "${MYPY_ARGS[@]}" 2>&1 | head -20 | tail -10
-        MYPY_EXIT=$?
-      fi
+        MYPY_ARGS+=("$staged_file")
+      done < <(python_staged_py_files)
+      python_typecheck_incremental "${MYPY_ARGS[@]}"
+      MYPY_EXIT=$?
       if [ "$MYPY_EXIT" -ne 0 ]; then
         echo ""
-        echo "❌ BLOCKED - MYPI TYPE ERRORS detected"
+        echo "❌ BLOCKED - MYPY TYPE ERRORS detected"
         echo "Fix the type errors above before committing."
         exit 1
       fi
@@ -1337,16 +1361,32 @@ else
     echo "ℹ️  golangci-lint not available — skipping Go linting"
     echo "⏭️  SKIPPED - Code quality (golangci-lint not available)"
   else
-    echo "Running golangci-lint (comprehensive static analysis)..."
-    golangci-lint run 2>&1 | head -30
-    GOLANGCI_EXIT=$?
-    if [ "$GOLANGCI_EXIT" -ne 0 ]; then
-      echo ""
-      echo "❌ BLOCKED - GOLANGCI-LINT ERRORS detected"
-      echo "Fix the lint errors above before committing."
-      exit 1
+    # #534: run golangci-lint over ONLY the staged .go files (incremental),
+    # not the whole repo. `golangci-lint run` with no args scans every package
+    # and dominates pre-commit time on large Go repos. golangci-lint accepts
+    # explicit file targets. No staged .go files -> SKIP (nothing to lint).
+    GO_FILES=$(echo "$CHANGED_FILES" | grep '\.go$' || true)
+    if [ -z "$GO_FILES" ]; then
+      echo "✅ PASSED - No staged Go files to lint."
+    else
+      echo "Running golangci-lint (incremental, staged .go)..."
+      # #534: capture golangci-lint's REAL exit code via a temp file, not a
+      # pipe stage's (`... | head -30; rc=$?` would take head's status; it only
+      # works because of set -o pipefail, which is fragile and inconsistent with
+      # the python incremental helper's temp-file pattern).
+      GO_TMP=$(mktemp)
+      golangci-lint run $GO_FILES > "$GO_TMP" 2>&1
+      GOLANGCI_EXIT=$?
+      head -30 "$GO_TMP"
+      rm -f "$GO_TMP"
+      if [ "$GOLANGCI_EXIT" -ne 0 ]; then
+        echo ""
+        echo "❌ BLOCKED - GOLANGCI-LINT ERRORS detected"
+        echo "Fix the lint errors above before committing."
+        exit 1
+      fi
+      echo "✅ PASSED - golangci-lint."
     fi
-    echo "✅ PASSED - golangci-lint."
   fi
     ;;
     
@@ -2294,6 +2334,13 @@ else
   else
   echo "Running coverage check..."
 
+  # Major-2 (Delphi): COV_EXIT aggregates coverage-run failures across ALL
+  # languages in Stage 1. It starts at 0 and each language branch ORs its own
+  # result in (`COV_EXIT=$((COV_EXIT || $?))`), so a later language's success
+  # can never mask an earlier language's subset-run failure. Previously every
+  # branch overwrote COV_EXIT and the last language's status won.
+  COV_EXIT=0
+
   for CURRENT_LANG in $PROJECT_LANGS; do
   ADAPTER_FILE=$(resolve_adapter_path "$CURRENT_LANG")
   if [ "${CURRENT_LANG}" != "unknown" ] && [ -n "$ADAPTER_FILE" ]; then
@@ -2307,13 +2354,13 @@ else
           # If no tests were run (TESTS_SKIPPED=true), skip coverage check entirely.
           if [ "${TESTS_SKIPPED:-false}" = "true" ]; then
             echo "ℹ️  Test run was skipped — skipping coverage check."
-            COV_EXIT=0
+            COV_EXIT=$((COV_EXIT || 0))
           elif [ -f "coverage/coverage-summary.json" ]; then
             echo "TypeScript coverage collected during test run."
-            COV_EXIT=0
+            COV_EXIT=$((COV_EXIT || 0))
           else
             echo "ℹ️  No coverage data produced — test run was skipped (no TS changes)."
-            COV_EXIT=0
+            COV_EXIT=$((COV_EXIT || 0))
           fi
           ;;
         "python")
@@ -2334,12 +2381,89 @@ else
             fi
             [ -z "$PY_COV_SOURCE" ] && PY_COV_SOURCE="--cov=."
             [ -z "$PY_COV_FAIL_UNDER" ] && PY_COV_FAIL_UNDER=80
-            pytest $PY_COV_SOURCE --cov-fail-under="$PY_COV_FAIL_UNDER" --tb=short
-            COV_EXIT=$?
+
+            # ── #399: smart test selection, the Python counterpart of #286 ──
+            # Three tiers (lib/python-test-selection.sh holds the pure
+            # decision logic + related-test lookup, unit-tested separately):
+            #   changed-tests / related -> run ONLY those targets, with the
+            #     repo's coverage SOURCE but WITHOUT the global fail_under
+            #     (subset coverage is meaningless globally). The run is marked
+            #     partial so Stage 2 warns instead of falsely blocking.
+            #   full -> unchanged behavior: whole suite + real threshold.
+            #   skip -> nothing test-relevant changed; no pytest at all.
+            PY_CHANGED_TEST_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null \
+              | grep -E '(^|/)test_[^/]*\.py$|_test\.py$' || true)
+            PY_CHANGED_SRC_FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null \
+              | grep -E '\.py$' | grep -vE '(^|/)test_[^/]*\.py$|_test\.py$' || true)
+            PY_CHANGED_ALL=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null || true)
+            # `grep -c '.'` prints its own zero AND exits 1 on an empty list
+            # (#493), so the count is derived with `|| true` + wc -l instead.
+            PY_TEST_COUNT=$(printf '%s\n' "$PY_CHANGED_TEST_FILES" | grep -c '.' || true)
+            PY_SRC_COUNT=$(printf '%s\n' "$PY_CHANGED_SRC_FILES" | grep -c '.' || true)
+            PY_DEPS_CHANGED=0
+            if python_dependency_changed $PY_CHANGED_ALL; then PY_DEPS_CHANGED=1; fi
+            PY_STRATEGY=$(select_python_test_strategy "$PY_TEST_COUNT" "$PY_SRC_COUNT" "$PY_DEPS_CHANGED")
+
+            # xdist parallel args (#516) — empty + warning when unavailable,
+            # never a BLOCK; unquoted expansion is the multi-word arg list.
+            PY_XDIST_ARGS=$(python_xdist_args 2>/dev/null || true)
+
+            if [ "$PY_STRATEGY" = "skip" ]; then
+              echo "ℹ️  Python: no test/source changes — skipping test run (#399)."
+              # Critical-1 (#399): mark the run skipped so Stage 2's
+              # enforce_python_coverage refuses to consume a stale .coverage
+              # left by a prior subset run. Without this flag the gate read the
+              # leftover low-% file and BLOCKED a docs-only commit that changed
+              # no Python. Mirrors the TS branch's TESTS_SKIPPED guard.
+              PY_TEST_SKIPPED=true
+              COV_EXIT=$((COV_EXIT || 0))
+            elif [ "$PY_STRATEGY" = "full" ]; then
+              if [ "$PY_DEPS_CHANGED" = "1" ]; then
+                echo "ℹ️  Python: dependency manifest changed — running FULL suite (#399)."
+              elif [ "$PY_TEST_COUNT" -gt 20 ] 2>/dev/null; then
+                echo "ℹ️  Python: $PY_TEST_COUNT changed test files (>20) — running FULL suite (#399)."
+              fi
+              # shellcheck disable=SC2086
+              pytest $PY_XDIST_ARGS $PY_COV_SOURCE --cov-fail-under="$PY_COV_FAIL_UNDER" --tb=short
+              COV_EXIT=$((COV_EXIT || $?))
+            else
+              # changed-tests | related → resolve the exact targets.
+              PY_TARGETS=""
+              if [ "$PY_STRATEGY" = "changed-tests" ]; then
+                PY_TARGETS="$PY_CHANGED_TEST_FILES"
+              else
+                for _py_src in $PY_CHANGED_SRC_FILES; do
+                  _py_related=$(python_related_tests "$_py_src")
+                  if [ -n "$_py_related" ]; then
+                    PY_TARGETS="${PY_TARGETS}${_py_related}
+"
+                  fi
+                done
+                PY_TARGETS=$(printf '%s\n' "$PY_TARGETS" | grep -v '^$' | sort -u)
+              fi
+
+              if [ -z "$PY_TARGETS" ]; then
+                # related lookup found nothing → tier 3 full run is safest.
+                echo "ℹ️  Python: no related tests found for changed sources — running FULL suite (#399)."
+                # shellcheck disable=SC2086
+                pytest $PY_XDIST_ARGS $PY_COV_SOURCE --cov-fail-under="$PY_COV_FAIL_UNDER" --tb=short
+                COV_EXIT=$((COV_EXIT || $?))
+              else
+                PY_TARGET_COUNT=$(printf '%s\n' "$PY_TARGETS" | grep -c '.' || true)
+                echo "ℹ️  Python: selective run ($PY_STRATEGY) — $PY_TARGET_COUNT target(s):"
+                printf '%s\n' "$PY_TARGETS" | sed 's/^/     /'
+                # Subset run: keep --cov so data is collected, but drop the
+                # global threshold — subset coverage is meaningless globally.
+                PARTIAL_TEST_RUN=true
+                # shellcheck disable=SC2086
+                pytest $PY_XDIST_ARGS $PY_COV_SOURCE --tb=short $PY_TARGETS
+                COV_EXIT=$((COV_EXIT || $?))
+              fi
+            fi
           else
             echo "pytest/coverage not available, running coverage via adapter..."
             run_coverage_output=$(run_coverage 2>&1)
-            COV_EXIT=$?
+            COV_EXIT=$((COV_EXIT || $?))
             echo "$run_coverage_output" | head -30
           fi
           ;;
@@ -2352,30 +2476,30 @@ else
               exit 1
             fi
             echo "Go coverage: $TOTAL_COVERAGE%"
-            COV_EXIT=0
+            COV_EXIT=$((COV_EXIT || 0))
           fi
           ;;
         "shell")
           shell_cov_output=$(run_coverage 2>&1)
-          COV_EXIT=$?
+          COV_EXIT=$((COV_EXIT || $?))
           echo "$shell_cov_output" | head -10
           echo "ℹ️  Shell coverage not typically measured"
           ;;
         *)
           default_cov_output=$(run_coverage 2>&1)
-          COV_EXIT=$?
+          COV_EXIT=$((COV_EXIT || $?))
           echo "$default_cov_output" | head -30
           ;;
       esac
     else
       # Adapter source failed — warn and let Stage 2 attempt file-based enforcement
       echo "⚠️  Could not source ${CURRENT_LANG} adapter from ${ADAPTER_FILE}, will check coverage files directly..."
-      COV_EXIT=0
+      COV_EXIT=$((COV_EXIT || 0))
     fi
   else
     # No adapter available — warn and let Stage 2 attempt file-based enforcement
     echo "⚠️  No adapter found for ${CURRENT_LANG} (searched: ${ADAPTER_DIR}/, ${ADAPTER_DIR}/adapters/, ${PROJECT_GITHOOKS}/adapters/, ${SCRIPT_DIR}/adapters/) — will check coverage files directly..."
-    COV_EXIT=0
+    COV_EXIT=$((COV_EXIT || 0))
   fi
   done  # end for CURRENT_LANG (Stage 1 coverage)
 

package/lib/__tests__/init-gitleaks-notice.test.js

@@ -0,0 +1,57 @@
+/**
+ * @intent #511: Gate 8 is fail-closed since #499 (missing gitleaks BLOCKS the
+ *         commit). The npm init path never surfaced that fact, so an upgrading
+ *         user met a hard BLOCK with no prior signal. `probeGitleaksNotice`
+ *         prints a migration notice and never installs anything.
+ * @covers probeGitleaksNotice() in lib/init.js
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { probeGitleaksNotice } = require('../init.js');
+
+describe('probeGitleaksNotice (#511)', () => {
+  it('reports present and stays quiet when gitleaks is available', () => {
+    const lines = [];
+    const result = probeGitleaksNotice(
+      () => ({ available: true, version: '8.24.2' }),
+      l => lines.push(l),
+    );
+    expect(result.available).toBe(true);
+    const joined = lines.join('\n');
+    expect(joined).toContain('gitleaks present');
+    expect(joined).toContain('8.24.2');
+    expect(joined).not.toContain('FAIL-CLOSED');
+  });
+
+  it('prints the fail-closed migration notice when gitleaks is missing', () => {
+    const lines = [];
+    const result = probeGitleaksNotice(() => ({ available: false }), l => lines.push(l));
+    expect(result.available).toBe(false);
+    const joined = lines.join('\n');
+    expect(joined).toContain('FAIL-CLOSED');
+    expect(joined).toContain('Gate 8');
+    expect(joined).toContain('install-gitleaks.sh');
+    expect(joined).toContain('brew install gitleaks');
+    expect(joined).toContain('winget install gitleaks');
+  });
+
+  it('probes exactly the gitleaks tool name', () => {
+    const checkTool = vi.fn(() => ({ available: true }));
+    probeGitleaksNotice(checkTool, () => {});
+    expect(checkTool).toHaveBeenCalledWith('gitleaks');
+  });
+
+  it('never installs anything — it is a pure text probe', () => {
+    // The helper must not shell out: no exec/spawn import is exercised here,
+    // and the only observable effect is log lines. A missing tool returns the
+    // notice; the caller decides whether to install.
+    const lines = [];
+    const before = process.env.PATH;
+    probeGitleaksNotice(() => ({ available: false }), l => lines.push(l));
+    expect(process.env.PATH).toBe(before);
+    expect(lines.some(l => /dev\/null|execSync|spawn/.test(l))).toBe(false);
+  });
+});

package/lib/__tests__/issue-519-phase-transition-guard.test.js

@@ -0,0 +1,233 @@
+/**
+ * @intent #519: A real pointer-drift incident (#507) showed that a MISSED
+ *         phase transition is invisible — the state file cannot distinguish
+ *         "never ran" from "not yet advanced". Guards under test:
+ *           (1) sequence guard: `completed` on phase n is refused unless phase
+ *               n-1 is completed/skipped, with `--force` as the explicit escape;
+ *           (2) before/after echo so "command didn't run" and "ran without
+ *               effect" are distinguishable in the output;
+ *           (3) an append-only transition audit log;
+ *           (4) phase_history field normalization (`name` → `phase_name`).
+ * @covers handlePhaseTransition guard/echo, appendTransitionAudit, migrateState
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { handlePhaseTransition } from '../phase-transition.js';
+import { SprintStateManager } from '../sprint-state-manager.js';
+import { migrateState } from '../sprint-state-migrator.js';
+
+function writeState(dir, state) {
+  try {
+    fs.mkdirSync(path.join(dir, '.sprint-state'), { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, '.sprint-state', 'sprint-state.json'),
+      JSON.stringify(state, null, 2),
+    );
+  } catch (err) {
+    throw new Error(`writeState failed for ${dir}: ${err.message}`);
+  }
+}
+
+function baseState(overrides = {}) {
+  return {
+    _schema_version: 1,
+    id: 'sprint-519',
+    task_description: 'test',
+    phase: 2,
+    status: 'in_progress',
+    started_at: '2026-10-14T00:00:00Z',
+    phase_history: [],
+    isolation: { worktree_path: null, branch: null },
+    ...overrides,
+  };
+}
+
+describe('#519 phase-transition sequence guard', () => {
+  let dir;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p519-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('refuses `completed` on phase 3 when phase 2 is not completed/skipped', async () => {
+    writeState(dir, baseState({
+      phase: 3,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'in_progress' }],
+    }));
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    const stderr = errSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    errSpy.mockRestore();
+    expect(code).toBe(1);
+    expect(stderr).toContain('Cannot complete phase 3');
+    expect(stderr).toContain('phase 2');
+    expect(stderr).toContain('phase history');
+  });
+
+  it('refuses the jump and names --force as the override', async () => {
+    writeState(dir, baseState({ phase: 3, phase_history: [] }));
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    await handlePhaseTransition(['5', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    const stderr = errSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    errSpy.mockRestore();
+    expect(stderr).toContain('--force');
+  });
+
+  it('allows `completed` when the previous phase is completed', async () => {
+    writeState(dir, baseState({
+      phase: 2,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'completed' }],
+    }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+
+  it('treats a skipped previous phase as valid', async () => {
+    writeState(dir, baseState({
+      phase: 2,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'skipped' }],
+    }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+
+  it('--force overrides the guard and warns', async () => {
+    writeState(dir, baseState({ phase: 3, phase_history: [] }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'completed', '--dir', dir, '--skip-evidence', 'x', '--force']);
+    const warned = warnSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    outSpy.mockRestore();
+    warnSpy.mockRestore();
+    expect(code).toBe(0);
+    expect(warned).toContain('overridden');
+  });
+
+  it('does not guard phase 1 (no predecessor)', async () => {
+    writeState(dir, baseState({ phase: 1, phase_history: [] }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['1', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+
+  it('does not guard non-completed statuses', async () => {
+    writeState(dir, baseState({ phase: 3, phase_history: [] }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['3', 'in_progress', '--dir', dir]);
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+  });
+});
+
+describe('#519 before/after echo', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p519echo-'));
+  });
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('prints before→after for the top-level phase/status and the entry', async () => {
+    // Phase 1 must be completed for the phase-2 completion to pass the
+    // sequence guard (#519) — otherwise the echo is never reached.
+    writeState(dir, baseState({
+      phase: 2,
+      status: 'in_progress',
+      phase_history: [
+        { phase: 1, name: 'PREP', status: 'completed' },
+        { phase: 2, phase_name: 'DESIGN', status: 'in_progress' },
+      ],
+    }));
+    const outSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const code = await handlePhaseTransition(['2', 'completed', '--dir', dir, '--skip-evidence', 'x']);
+    const output = outSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    outSpy.mockRestore();
+    expect(code).toBe(0);
+    expect(output).toContain('before→after');
+    expect(output).toContain('in_progress → completed');
+  });
+});
+
+describe('#519 transition audit log + field normalization', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p519audit-'));
+  });
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('appends one JSON line per transition with from/to', () => {
+    writeState(dir, baseState({ phase: 2, phase_history: [] }));
+    const manager = new SprintStateManager(dir);
+    manager.transitionPhase(2, 'in_progress');
+    manager.transitionPhase(2, 'completed');
+    const auditFile = path.join(dir, '.sprint-state', 'transition-audit.jsonl');
+    expect(fs.existsSync(auditFile)).toBe(true);
+    const lines = fs.readFileSync(auditFile, 'utf8').trim().split('\n');
+    expect(lines.length).toBe(2);
+    const first = JSON.parse(lines[0]);
+    expect(first.phase).toBe(2);
+    expect(first.phase_name).toBe('DESIGN');
+    expect(first.to_status).toBe('in_progress');
+    expect(first.timestamp).toBeTruthy();
+    const second = JSON.parse(lines[1]);
+    expect(second.to_status).toBe('completed');
+  });
+
+  it('audit is best-effort: a write failure does not break the transition', () => {
+    writeState(dir, baseState({ phase: 2, phase_history: [] }));
+    const manager = new SprintStateManager(dir);
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    // Break the real appendFileSync so appendTransitionAudit's OWN try/catch is
+    // exercised (mocking the method itself would bypass the production guard).
+    const appendSpy = vi.spyOn(fs, 'appendFileSync').mockImplementation(() => {
+      throw new Error('disk full');
+    });
+    expect(() => manager.transitionPhase(2, 'in_progress')).not.toThrow();
+    const warned = warnSpy.mock.calls.map(c => c.join(' ')).join('\n');
+    appendSpy.mockRestore();
+    warnSpy.mockRestore();
+    expect(warned).toContain('transition audit write failed');
+  });
+
+  it('migrateState normalizes legacy `name` into `phase_name`', () => {
+    // A legacy file (no _schema_version) whose phase 1 entry carries `name`
+    // rather than `phase_name` — the exact shape #507 left behind.
+    const legacy = baseState({
+      _schema_version: undefined,
+      phase_history: [{ phase: 1, name: 'PREP', status: 'completed' }],
+    });
+    const migrated = migrateState(legacy, dir);
+    const entry = migrated.phase_history[0];
+    // The canonical field is populated (via the legacy remap and/or the
+    // name→phase_name normalization) and the legacy field is preserved.
+    expect(entry.phase_name).toBeTruthy();
+    expect(entry.name).toBe('PREP');
+  });
+
+  it('migrateState backfills `name` from `phase_name` (both directions)', () => {
+    const legacy = baseState({
+      _schema_version: undefined,
+      phase_history: [{ phase: 2, phase_name: 'DESIGN', status: 'in_progress' }],
+    });
+    const migrated = migrateState(legacy, dir);
+    const entry = migrated.phase_history[0];
+    expect(entry.phase_name).toBeTruthy();
+    // `name` is backfilled so a reader consulting either field agrees.
+    expect(entry.name).toBe(entry.phase_name);
+  });
+});

package/lib/init.js

@@ -271,6 +271,46 @@ function printCliToolStatus() {
   }
 }
 
+/**
+ * Probe for gitleaks and warn when it is missing (#511).
+ *
+ * Gate 8 became fail-closed in #499: a missing gitleaks BLOCKs the commit
+ * outright (it does NOT skip, unlike the tools reported by
+ * printCliToolStatus). The user-facing installers never provisioned it, so an
+ * existing user upgrading into #499 hits a hard BLOCK on their next commit with
+ * no prior signal — this is the missing migration notice.
+ *
+ * Probe-and-prompt only: nothing is installed here (installing is the user's
+ * explicit choice, via the printed command). The fail-closed semantics of
+ * #499 are untouched.
+ *
+ * @param {(name: string) => {available: boolean, version?: string}} checkTool
+ * @param {(line: string) => void} [log]
+ * @returns {{available: boolean}} the probe result, for callers that branch on it
+ */
+function probeGitleaksNotice(checkTool, log = console.log) {
+  const result = checkTool('gitleaks');
+  if (result.available) {
+    log(`✓ gitleaks present${result.version ? `: ${result.version}` : ''}`);
+    return { available: true };
+  }
+
+  log('');
+  log('⚠  gitleaks is NOT installed.');
+  log('   Gate 8 (secret scanning) is FAIL-CLOSED since #499: your next commit');
+  log('   will be BLOCKED until gitleaks is available.');
+  log('');
+  log('   Install it now:');
+  log('     bash scripts/install-gitleaks.sh');
+  log('');
+  log('   Per-OS alternatives:');
+  log('     macOS:    brew install gitleaks');
+  log('     Linux:    https://github.com/gitleaks/gitleaks/releases');
+  log('     Windows:  winget install gitleaks  (or: scoop install gitleaks)');
+  log('');
+  return { available: false };
+}
+
 /**
  * Ask the user for confirmation via stdin.
  * @param {string} question - The yes/no question to display
@@ -352,6 +392,11 @@ async function init(args) {
   console.log('Checking CLI tools...');
   printCliToolStatus();
 
+  // #511: gitleaks is the one tool whose absence BLOCKS rather than SKIPs
+  // (Gate 8 fail-closed, #499) — surface it separately so an upgrading user
+  // has a migration path before the first blocked commit.
+  probeGitleaksNotice(checkCliTool);
+
   console.log('Checking platform dependencies...');
   // Detect platform and check/auto-install dependencies
   const platform = detectPlatform();
@@ -925,4 +970,4 @@ function injectKarpathyPrinciples(projectRoot) {
 // setupGlobal is exported so the global-install wiring (agents deployed to the
 // real HOME) can be audited under a sandboxed HOME, not just asserted to exist
 // — the historical miss was "local deployed, global did not" (#417, #429).
-module.exports = { init, promptBootstrap, installModuleRuntimeDeps, deployQoderDelphiAgents, configureQoderDelphiAgents, readQoderModelId, setupGlobal };
+module.exports = { init, promptBootstrap, installModuleRuntimeDeps, deployQoderDelphiAgents, configureQoderDelphiAgents, readQoderModelId, setupGlobal, probeGitleaksNotice };

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-14T09:00:41.434Z",
+  "checked_at": "2026-10-16T00:33:22.006Z",
   "source": "network"
 }