@boyingliu01/xp-gate 0.34.1 → 0.35.1

package/bin/xp-gate.js

@@ -350,6 +350,14 @@ const COMMANDS = {
     },
     usage: 'xp-gate retro [--days N] [--all] [--json] [--sprint <id>]'
   },
+  'rework': {
+    description: 'Report rework: first-pass rate, rounds before landing, top blocking reasons (#651)',
+    run: subargs => {
+      const { main } = require('../lib/rework.js');
+      process.exit(main(subargs));
+    },
+    usage: 'xp-gate rework [--top N] [--dir <path>] [--json]'
+  },
   'crap': {
     description: 'Rank functions by CRAP score (complexity x weak coverage) — advisory, never blocks (#404)',
     run: subargs => {

package/gate-3.sh

@@ -461,6 +461,52 @@ else
           GATE_3_DETAIL="mode=ratchet verifier=MISSING"
           exit 1
         fi
+        RATCHET_LIB="$GATE_DIR/lib/ccn-ratchet.sh"
+        [ -f "$RATCHET_LIB" ] || RATCHET_LIB="$(git rev-parse --show-toplevel 2>/dev/null)/githooks/lib/ccn-ratchet.sh"
+        # #617: grade exactly the population the baseline was written from.
+        #
+        # The comment below has always said so, but only as a comment: a repo whose
+        # baseline came from a narrower scan (a Java-only ccn-report, say) had its
+        # vendored minified JS graded anyway, and --csv-verified then disagreed with
+        # lizard on single-line code and fail-closed with "could not be
+        # span-verified". That BLOCK has no repair: the file has no baseline entry
+        # to ratchet, so there is nothing the user could add to clear it.
+        #
+        # The population filter runs BEFORE verification on purpose. Domain
+        # restriction is decidable from the path alone, so asking the expensive
+        # span re-derivation about a file that will not be graded anyway only
+        # manufactures failures for code the ratchet never claims to cover.
+        if [ -f "$RATCHET_LIB" ]; then
+          # shellcheck source=/dev/null
+          . "$RATCHET_LIB" 2>/dev/null || true
+          if declare -F ccn_file_in_population >/dev/null 2>&1; then
+            _cc_pop_kept=""
+            _cc_pop_skipped=""
+            while IFS= read -r _cc_row; do
+              [ -n "$_cc_row" ] || continue
+              _cc_row_path=$(printf '%s' "$_cc_row" | awk -F, '{print $1}')
+              if ccn_file_in_population ".ccn-baseline.json" "$_cc_row_path"; then
+                _cc_pop_kept="${_cc_pop_kept}${_cc_row}
+"
+              else
+                _cc_pop_skipped="${_cc_pop_skipped}${_cc_row_path}
+"
+              fi
+            done <<CC_POP_EOF
+$CC_CSV
+CC_POP_EOF
+            CC_CSV=$(printf '%s' "$_cc_pop_kept")
+            if [ -n "$_cc_pop_skipped" ]; then
+              _cc_pop_skip_n=$(printf '%s' "$_cc_pop_skipped" | grep -c . || true)
+              echo "ℹ️  Gate 3: ${_cc_pop_skip_n:-0} file(s) outside the baseline population — not graded, not ratcheted:"
+              printf '%s' "$_cc_pop_skipped" | sed 's/^/     /' | sed -n '1,5p'
+              if [ "${_cc_pop_skip_n:-0}" -gt 5 ]; then
+                echo "     ... and $((_cc_pop_skip_n - 5)) more"
+              fi
+              echo "     (declare or widen the population in .ccn-baseline.json to grade them)"
+            fi
+          fi
+        fi
         if [ -f "$CC_REPORT" ] && command -v node >/dev/null 2>&1; then
           _cc_verify_failed=0
           CC_CSV_VERIFIED=$(printf '%s\n' "$CC_CSV" | node "$CC_REPORT" --csv-verified batch --root "$(git rev-parse --show-toplevel 2>/dev/null)") || _cc_verify_failed=1
@@ -471,8 +517,6 @@ else
           fi
           CC_CSV="$CC_CSV_VERIFIED"
         fi
-        RATCHET_LIB="$GATE_DIR/lib/ccn-ratchet.sh"
-        [ -f "$RATCHET_LIB" ] || RATCHET_LIB="$(git rev-parse --show-toplevel 2>/dev/null)/githooks/lib/ccn-ratchet.sh"
         # Fail closed when the ratchet library is missing. Sourcing a nonexistent
         # file only prints "No such file or directory" and leaves
         # evaluate_ccn_ratchet undefined; the verdict then came back empty, every

package/gate-4.sh

@@ -172,9 +172,26 @@ else
         rm -f "$PRINCIPLES_STDERR"
 
         if [ "$PRINCIPLES_EXIT" -ge 2 ]; then
-          echo "⚠️  Warning: Principles checker execution failed"
-          echo "⏭️  SKIPPED - Principles check (execution issue)"
-          GATE_4_STATUS="SKIP"
+          # #661: exit>=2 means the checker did not RUN (crash, module not found,
+          # bad invocation). This used to record SKIP, and pre-commit treats SKIP
+          # as non-blocking, so a tool failure was absorbed into the green light --
+          # the reproduction printed a module-not-found stack trace and then
+          # "✅ PASSED - Principles checker (no errors found)".
+          #
+          # The distinction the gate must keep:
+          #   - tool NOT INSTALLED  -> SKIP is honest; nothing is being claimed.
+          #   - tool PRESENT, CRASH -> WARN. Not a pass (nothing was checked) and
+          #     not a silent skip (the user must know their code went unaudited).
+          #
+          # WARN rather than FAIL on purpose: the commit itself is not necessarily
+          # bad, the TOOL is broken, and blocking every commit until node/tsx is
+          # repaired would blame the change for an environment fault. What must
+          # never happen is the green light.
+          echo "⚠️  Principles checker did not run (exit ${PRINCIPLES_EXIT}) — this code is NOT verified."
+          echo "     Gate 4 cannot claim a pass for a check that never executed."
+          echo "     Fix the checker invocation above (or run 'npx xp-gate check principles .')."
+          echo "⏭️  WARN - Principles check (checker execution error)"
+          GATE_4_STATUS="WARN"
           # Consumed by the sourcing parent, not here (see #548).
           # shellcheck disable=SC2034
           GATE_4_REASON="checker_execution_error"

package/hooks/gate-3.sh

@@ -461,6 +461,52 @@ else
           GATE_3_DETAIL="mode=ratchet verifier=MISSING"
           exit 1
         fi
+        RATCHET_LIB="$GATE_DIR/lib/ccn-ratchet.sh"
+        [ -f "$RATCHET_LIB" ] || RATCHET_LIB="$(git rev-parse --show-toplevel 2>/dev/null)/githooks/lib/ccn-ratchet.sh"
+        # #617: grade exactly the population the baseline was written from.
+        #
+        # The comment below has always said so, but only as a comment: a repo whose
+        # baseline came from a narrower scan (a Java-only ccn-report, say) had its
+        # vendored minified JS graded anyway, and --csv-verified then disagreed with
+        # lizard on single-line code and fail-closed with "could not be
+        # span-verified". That BLOCK has no repair: the file has no baseline entry
+        # to ratchet, so there is nothing the user could add to clear it.
+        #
+        # The population filter runs BEFORE verification on purpose. Domain
+        # restriction is decidable from the path alone, so asking the expensive
+        # span re-derivation about a file that will not be graded anyway only
+        # manufactures failures for code the ratchet never claims to cover.
+        if [ -f "$RATCHET_LIB" ]; then
+          # shellcheck source=/dev/null
+          . "$RATCHET_LIB" 2>/dev/null || true
+          if declare -F ccn_file_in_population >/dev/null 2>&1; then
+            _cc_pop_kept=""
+            _cc_pop_skipped=""
+            while IFS= read -r _cc_row; do
+              [ -n "$_cc_row" ] || continue
+              _cc_row_path=$(printf '%s' "$_cc_row" | awk -F, '{print $1}')
+              if ccn_file_in_population ".ccn-baseline.json" "$_cc_row_path"; then
+                _cc_pop_kept="${_cc_pop_kept}${_cc_row}
+"
+              else
+                _cc_pop_skipped="${_cc_pop_skipped}${_cc_row_path}
+"
+              fi
+            done <<CC_POP_EOF
+$CC_CSV
+CC_POP_EOF
+            CC_CSV=$(printf '%s' "$_cc_pop_kept")
+            if [ -n "$_cc_pop_skipped" ]; then
+              _cc_pop_skip_n=$(printf '%s' "$_cc_pop_skipped" | grep -c . || true)
+              echo "ℹ️  Gate 3: ${_cc_pop_skip_n:-0} file(s) outside the baseline population — not graded, not ratcheted:"
+              printf '%s' "$_cc_pop_skipped" | sed 's/^/     /' | sed -n '1,5p'
+              if [ "${_cc_pop_skip_n:-0}" -gt 5 ]; then
+                echo "     ... and $((_cc_pop_skip_n - 5)) more"
+              fi
+              echo "     (declare or widen the population in .ccn-baseline.json to grade them)"
+            fi
+          fi
+        fi
         if [ -f "$CC_REPORT" ] && command -v node >/dev/null 2>&1; then
           _cc_verify_failed=0
           CC_CSV_VERIFIED=$(printf '%s\n' "$CC_CSV" | node "$CC_REPORT" --csv-verified batch --root "$(git rev-parse --show-toplevel 2>/dev/null)") || _cc_verify_failed=1
@@ -471,8 +517,6 @@ else
           fi
           CC_CSV="$CC_CSV_VERIFIED"
         fi
-        RATCHET_LIB="$GATE_DIR/lib/ccn-ratchet.sh"
-        [ -f "$RATCHET_LIB" ] || RATCHET_LIB="$(git rev-parse --show-toplevel 2>/dev/null)/githooks/lib/ccn-ratchet.sh"
         # Fail closed when the ratchet library is missing. Sourcing a nonexistent
         # file only prints "No such file or directory" and leaves
         # evaluate_ccn_ratchet undefined; the verdict then came back empty, every

package/hooks/gate-4.sh

@@ -172,9 +172,26 @@ else
         rm -f "$PRINCIPLES_STDERR"
 
         if [ "$PRINCIPLES_EXIT" -ge 2 ]; then
-          echo "⚠️  Warning: Principles checker execution failed"
-          echo "⏭️  SKIPPED - Principles check (execution issue)"
-          GATE_4_STATUS="SKIP"
+          # #661: exit>=2 means the checker did not RUN (crash, module not found,
+          # bad invocation). This used to record SKIP, and pre-commit treats SKIP
+          # as non-blocking, so a tool failure was absorbed into the green light --
+          # the reproduction printed a module-not-found stack trace and then
+          # "✅ PASSED - Principles checker (no errors found)".
+          #
+          # The distinction the gate must keep:
+          #   - tool NOT INSTALLED  -> SKIP is honest; nothing is being claimed.
+          #   - tool PRESENT, CRASH -> WARN. Not a pass (nothing was checked) and
+          #     not a silent skip (the user must know their code went unaudited).
+          #
+          # WARN rather than FAIL on purpose: the commit itself is not necessarily
+          # bad, the TOOL is broken, and blocking every commit until node/tsx is
+          # repaired would blame the change for an environment fault. What must
+          # never happen is the green light.
+          echo "⚠️  Principles checker did not run (exit ${PRINCIPLES_EXIT}) — this code is NOT verified."
+          echo "     Gate 4 cannot claim a pass for a check that never executed."
+          echo "     Fix the checker invocation above (or run 'npx xp-gate check principles .')."
+          echo "⏭️  WARN - Principles check (checker execution error)"
+          GATE_4_STATUS="WARN"
           # Consumed by the sourcing parent, not here (see #548).
           # shellcheck disable=SC2034
           GATE_4_REASON="checker_execution_error"

package/hooks/lib/ccn-ratchet.sh

@@ -11,6 +11,23 @@
 # improves we say so and suggest refreshing the baseline, because a stale
 # ceiling invites nobody to finish the job.
 #
+# ── Population (#617) ───────────────────────────────────────────────────────
+# A ratchet is only meaningful over the population it was recorded from. Gate 3
+# grades every extension it recognises; a repo whose baseline came from a
+# narrower scan then reports pre-existing code as "new", which is a false BLOCK
+# no repair can clear — the file has no baseline entry to fix.
+#
+# The baseline may therefore DECLARE its population:
+#
+#   { "population": { "roots": ["src/main/java"], "extensions": [".java"] },
+#     "entries": { "src/main/java/A.java::f": 4 } }
+#
+# A baseline without that key is LEGACY and is treated as unrestricted, which is
+# exactly the historical behaviour: every baseline already in the field has the
+# flat `{ "path::fn": ccn }` shape, and refusing to load it would break every
+# install on upgrade. Absent metadata must never be read as an empty population
+# -- that would silently grade nothing at all, the opposite failure.
+#
 # Key = "<relative/path>::<functionName>". Rename or move = new key = treated
 # as a new function. That is deliberate: fuzzy matching would hide debt moves.
 # `node scripts/ccn-report.cjs --write-baseline` regenerates the file after a
@@ -41,6 +58,98 @@
 # every row is read as a single field).
 CSV_FS=$'\x1f'
 
+# ---------------------------------------------------------------------------
+# #617: baseline population.
+#
+# Prints the declared population as `<root>|<ext>|<ext>...` on one line, or
+# NOTHING when the baseline carries no `population` key (legacy => unrestricted).
+# Printing nothing is deliberate: "no declaration" and "empty population" are
+# opposite meanings, and a caller that cannot tell them apart would either grade
+# everything (wrong for a Java-only repo) or nothing (catastrophic -- the ratchet
+# would report a clean run while comparing zero functions).
+# ---------------------------------------------------------------------------
+ccn_baseline_population() {
+  local _bl="${1:-.ccn-baseline.json}"
+  [ -f "$_bl" ] || return 0
+  command -v node >/dev/null 2>&1 || return 0
+  node -e '
+    const fs = require("fs");
+    let data;
+    try { data = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); }
+    catch { process.exit(0); }
+    // Legacy shape: a flat map of "path::fn" -> ccn. No declaration.
+    if (!data || typeof data !== "object" || !data.population) process.exit(0);
+    const pop = data.population || {};
+    const roots = Array.isArray(pop.roots) ? pop.roots : [];
+    const exts = Array.isArray(pop.extensions) ? pop.extensions : [];
+    // A declared-but-empty population is not a legitimate declaration: it would
+    // excuse every file. Treat it as no declaration so the gate keeps grading.
+    if (roots.length === 0 && exts.length === 0) process.exit(0);
+    // One line: "<roots csv>|<exts csv>". Callers split on the single pipe.
+    process.stdout.write(roots.join(",") + "|" + exts.join(","));
+  ' "$_bl" 2>/dev/null
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# #617: is this file inside the baseline's declared population?
+#
+# Returns 0 when the file may be graded, 1 when it is outside the population.
+# A legacy baseline (no declaration) permits everything, preserving the
+# behaviour every existing install already relies on.
+#
+# Both axes are ANDed only when both are declared; a baseline declaring just
+# roots (or just extensions) narrows on that axis alone.
+# ---------------------------------------------------------------------------
+ccn_file_in_population() {
+  local _bl="${1:-.ccn-baseline.json}"
+  local _file="${2:-}"
+  [ -n "$_file" ] || return 1
+
+  local _pop
+  _pop=$(ccn_baseline_population "$_bl")
+  # No declaration => unrestricted (legacy baseline).
+  [ -n "$_pop" ] || return 0
+
+  local _roots="${_pop%%|*}"
+  local _exts="${_pop#*|}"
+  # Normalise separators so a Windows path and a POSIX path compare the same way.
+  # sed, not `tr '\' '/'`: a lone backslash is a portability trap in tr's SET
+  # argument (GNU tr warns "unescaped backslash at end of string" and MSYS tr
+  # behaviour differs), while the sed regex below is unambiguous everywhere.
+  _norm=$(printf '%s' "$_file" | sed 's|\\|/|g')
+
+  if [ -n "$_roots" ]; then
+    local _hit=0 _r
+    local _oldifs="$IFS"
+    IFS=','
+    for _r in $_roots; do
+      IFS="$_oldifs"
+      case "$_norm" in
+        "$_r"|"$_r"/*) _hit=1; break ;;
+      esac
+    done
+    IFS="$_oldifs"
+    [ "$_hit" -eq 1 ] || return 1
+  fi
+
+  if [ -n "$_exts" ]; then
+    local _match=0 _e
+    local _oldifs2="$IFS"
+    IFS=','
+    for _e in $_exts; do
+      IFS="$_oldifs2"
+      case "$_norm" in
+        *"$_e") _match=1; break ;;
+      esac
+    done
+    IFS="$_oldifs2"
+    [ "$_match" -eq 1 ] || return 1
+  fi
+
+  return 0
+}
+
 csv_to_unit_separated() {
   awk '
     function emit(line,   cur, i, ch, q, nf) {

package/hooks/pre-commit

@@ -627,6 +627,98 @@ record_gate_audit() {
   disown 2>/dev/null || true
 }
 
+# ── #651: journal a blocking exit ──────────────────────────────────────────
+#
+# Failure was invisible in this repo's own history: audit.jsonl had 8,258 records
+# and essentially zero gate FAILs, because pre-commit has ~76 `exit 1` blocking
+# paths and record_gate_audit() is only reached AFTER a gate settles. The moment a
+# gate FAILs and exits, the record that would have said so is never written — so
+# `xp-gate retro` and `sprint-status --rework-check` computed rework over a
+# denominator with no failures in it, and rework trended to zero by construction.
+#
+# The trap catches the failure on its way OUT rather than adding a record call to
+# all 76 branches, which would rot the first time someone adds branch 77.
+_BLOCKING_RECORDED=""
+_record_blocking_exit() {
+  local rc=$?
+  # 0 = success, nothing to journal.
+  [ "$rc" -eq 0 ] && return 0
+  # One record per run. Without the latch, a gate that already recorded and then
+  # exited non-zero would be counted twice, halving the reported first-pass rate.
+  [ -n "$_BLOCKING_RECORDED" ] && return 0
+  _BLOCKING_RECORDED="1"
+
+  # Identify the gate that was running. Status vars are NO*-gradeable: any of
+  # FAIL/BLOCK means this gate is the reason. Latest failing gate wins, which is
+  # the one that actually called exit.
+  local _bg_id="" _bg_name="" _bg_status="" _bg_detail=""
+  local _i _st_var _st
+  for _i in 0 1 2 3 4 5 6 7 8 9 10 11 12 13; do
+    _st_var="GATE_${_i}_STATUS"
+    _st="${!_st_var:-}"
+    case "$_st" in
+      FAIL|BLOCK)
+        # Latest failing gate wins: it is the one that actually called exit.
+        _bg_id="$_i"
+        _bg_status="$_st"
+        ;;
+    esac
+  done
+  local _bg_detail_var="GATE_${_bg_id}_DETAIL"
+  _bg_detail="${!_bg_detail_var:-}"
+
+  # Gate names for the journal. Deliberately short: this runs during shutdown.
+  case "$_bg_id" in
+    0)  _bg_name="Version Consistency" ;;
+    1)  _bg_name="Code Quality" ;;
+    2)  _bg_name="Duplicate Code" ;;
+    3)  _bg_name="Cyclomatic Complexity" ;;
+    4)  _bg_name="Principles" ;;
+    5)  _bg_name="Tests + Coverage" ;;
+    6)  _bg_name="Architecture + Boy Scout" ;;
+    7)  _bg_name="IaC Security" ;;
+    8)  _bg_name="Secret Scanning" ;;
+    9)  _bg_name="Build Integrity" ;;
+    10) _bg_name="SAST Security" ;;
+    11) _bg_name="Sprint Flow" ;;
+    12) _bg_name="File Hygiene" ;;
+    13) _bg_name="Compiler Strictness" ;;
+    *)  _bg_name="unknown" ;;
+  esac
+  [ -n "$_bg_id" ] || _bg_id="unknown"
+
+  # The reason must reach the journal or "top-N failing rules" cannot exist.
+  # Prefer the gate's own detail (it carries the rule/threshold), else the status.
+  local _bg_reason="${_bg_detail:-gate_exit_${rc}}"
+
+  local _bg_start_var="GATE_${_bg_id}_START"
+  local _bg_start="${!_bg_start_var:-}"
+  local _bg_dur="null"
+  if [ -n "$_bg_start" ]; then
+    local _bg_end
+    _bg_end=$(now_ms 2>/dev/null || echo "")
+    if [ -n "$_bg_end" ]; then
+      _bg_dur=$((_bg_end - _bg_start))
+      [ "$_bg_dur" -ge 0 ] 2>/dev/null || _bg_dur="null"
+    fi
+  fi
+
+  # Fire-and-forget, and never let journaling change the exit code.
+  {
+    run_tsx "${PROJECT_ROOT_FOR_AUDIT}/src/npm-package/lib/gate-audit.ts" record \
+      --gate-id "$_bg_id" \
+      --gate-name "$_bg_name" \
+      --passed false \
+      --issues-found 1 \
+      --duration-ms "$_bg_dur" \
+      --trigger commit \
+      --failure-reason "$_bg_reason" \
+      2>/dev/null
+  } >/dev/null 2>&1 || true
+  return 0
+}
+trap _record_blocking_exit EXIT
+
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo "   QUALITY GATES - PRE-COMMIT CHECK"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

package/lib/__tests__/doctor-timeout-partial.test.js

@@ -0,0 +1,79 @@
+/**
+ * @test REQ-629
+ * @intent `xp-gate doctor` is non-deterministic on Windows. Against an identical,
+ *         freshly-installed, fully healthy installation it printed
+ *         "All checks passed" on one run and "Timed out after 10s — some checks
+ *         incomplete" on the next two. The timeout is a deliberate safety net
+ *         (#348, "43s on Windows"); the defect is what happens when it fires.
+ *
+ *         `Promise.race` discarded the entire `diagnoseAsync()` result and
+ *         substituted a single placeholder check, so everything that had already
+ *         finished was thrown away. Consequence: doctor can report LESS
+ *         information the LONGER it runs — the opposite of what a diagnostic
+ *         should do — and a WARN from the timeout made the skills section vanish
+ *         entirely, so tooling that scrapes `Skill:.*Up to date` read 0/12.
+ *
+ *         The fix: reach a verdict at the deadline (never hang — #348 stays fixed)
+ *         but keep whatever finished. A diagnostic that says "these 9 checks
+ *         passed, 2 did not report in time" is strictly more useful than one that
+ *         says "timed out".
+ *
+ *         The tests below pin the merge semantics directly rather than waiting on
+ *         a real 10s timer: the behaviour that matters is "partial results are
+ *         preserved and reported as partial", not the clock.
+ * @covers AC-670-43, AC-670-44, AC-670-45
+ */
+'use strict';
+
+// describe/it/expect are vitest globals in this repo's config; requiring them from
+// 'vitest' fails because this file is CommonJS. (Hooks are not needed here.)
+
+/** A completed check, shaped like diagnoseAsync()'s output. */
+function check(name, status) {
+  return { name, status, detail: `${name} detail` };
+}
+
+describe('doctor keeps completed checks when the global timeout fires (#629)', () => {
+  it('AC-670-43: completed checks are merged with the timeout notice, not replaced', () => {
+    const { mergeTimedOutDiagnosis } = require('../doctor');
+    expect(typeof mergeTimedOutDiagnosis).toBe('function');
+
+    const completed = {
+      checks: [check('Hooks', 'PASS'), check('Adapters', 'PASS'), check('Skills', 'WARN')],
+      issues: 1,
+    };
+    const merged = mergeTimedOutDiagnosis(completed, ['Gate env', 'OpenCode TUI']);
+
+    // Nothing that finished may be dropped -- that is the whole defect.
+    for (const name of ['Hooks', 'Adapters', 'Skills']) {
+      expect(merged.checks.map((c) => c.name)).toContain(name);
+    }
+    // The deadline itself is still reported, and still not a pass.
+    const notice = merged.checks.find((c) => c.name === 'Diagnosis');
+    expect(notice).toBeDefined();
+    expect(notice.status).toBe('WARN');
+    // Named individually, so the reader knows which surface is unknown.
+    expect(notice.detail).toContain('Gate env');
+    expect(notice.detail).toContain('OpenCode TUI');
+    expect(merged.timedOut).toBe(true);
+    // A partial run is never clean.
+    expect(merged.issues).toBeGreaterThanOrEqual(1);
+  });
+
+  it('AC-670-44: an empty partial result still yields the honest timeout notice', () => {
+    const { mergeTimedOutDiagnosis } = require('../doctor');
+    const merged = mergeTimedOutDiagnosis({ checks: [], issues: 0 }, ['Gate env']);
+    expect(merged.checks).toHaveLength(1);
+    expect(merged.checks[0].name).toBe('Diagnosis');
+    expect(merged.timedOut).toBe(true);
+  });
+
+  it('AC-670-45: nothing that already reported is ever lost, and a real issue count survives', () => {
+    const { mergeTimedOutDiagnosis } = require('../doctor');
+    const completed = { checks: [check('Hooks', 'FAIL'), check('Templates', 'PASS')], issues: 4 };
+    const merged = mergeTimedOutDiagnosis(completed, []);
+    // Pre-existing issues are not reset by the timeout.
+    expect(merged.issues).toBeGreaterThanOrEqual(4);
+    expect(merged.checks.map((c) => c.name)).toEqual(expect.arrayContaining(['Hooks', 'Templates']));
+  });
+});

package/lib/__tests__/rework.test.js

@@ -0,0 +1,127 @@
+/**
+ * @test REQ-651 rework
+ * @intent #651 asks for a command that turns the gate journal into the three
+ *        numbers rework management actually needs:
+ *
+ *          1. first-pass rate     -- how often a round clears the gates on try 1
+ *          2. rework round stats  -- median / mean / worst rounds per landing
+ *          3. top-N failing rules -- which rule_id blocks most often
+ *
+ *        Without (3) the only thing you can do is "try harder". With it, the
+ *        answer to "why is development slow" becomes a ranked list.
+ *
+ *        Two data hazards decide the design:
+ *
+ *        - Before #651 the journal contained NO failures, so every derived rate
+ *          was 100% by construction. A command that reports "first-pass rate: 100%"
+ *          from an empty failure set is worse than no command: it manufactures
+ *          confidence. So an input with zero FAIL records must report that the
+ *          figure is NOT MEASURABLE, not that it is perfect.
+ *
+ *        - ~401 historical records carry epoch-sized `duration_ms` (flagged
+ *          `duration_anomaly`). Any duration aggregate must exclude them rather
+ *          than average them in -- one of them once produced "average 430 million
+ *          seconds".
+ *
+ *        These tests exercise the pure aggregation function, so the numbers are
+ *        pinned independently of file layout.
+ * @covers AC-670-59, AC-670-60, AC-670-61, AC-670-62
+ */
+'use strict';
+
+const { computeReworkStats } = require('../rework');
+
+/** One journal record, defaulting to a pass. */
+function rec(overrides) {
+  return {
+    timestamp: '2026-10-30T10:00:00.000Z',
+    gate_id: '1',
+    gate_name: 'Code Quality',
+    passed: true,
+    issues_found: 0,
+    duration_ms: 1000,
+    trigger: 'commit',
+    ...overrides,
+  };
+}
+
+describe('computeReworkStats (#651)', () => {
+  it('AC-670-59: reports an unmeasurable first-pass rate when the journal has no failures', () => {
+    // This is exactly the pre-#651 journal: thousands of passes, zero fails.
+    const entries = Array.from({ length: 50 }, () => rec());
+    const stats = computeReworkStats(entries);
+    // A rate derived from an empty failure set is not 100% -- it is unknown.
+    expect(stats.firstPassRate).toBeNull();
+    expect(stats.measurable).toBe(false);
+    expect(stats.reason).toMatch(/no failure/i);
+  });
+
+  it('AC-670-60: counts failing rules and ranks them, so the worst rule is actionable', () => {
+    const entries = [
+      rec({ passed: false, failure_reason: 'long-function' }),
+      rec({ passed: false, failure_reason: 'long-function' }),
+      rec({ passed: false, failure_reason: 'long-function' }),
+      rec({ passed: false, failure_reason: 'tests_failed' }),
+      rec(),
+      rec(),
+    ];
+    const stats = computeReworkStats(entries);
+    expect(stats.measurable).toBe(true);
+    expect(stats.topFailures[0]).toEqual({ reason: 'long-function', count: 3 });
+    expect(stats.topFailures[1]).toEqual({ reason: 'tests_failed', count: 1 });
+    // 4 failures out of 6 attempts -> 33% first-pass.
+    expect(stats.firstPassRate).toBeCloseTo(33.3, 1);
+  });
+
+  it('AC-670-61: excludes anomaly-flagged durations instead of averaging them in', () => {
+    // A real epoch-sized value from the corpus; averaging it in produced
+    // "average 430 million seconds" on gate-1.
+    const entries = [
+      rec({ duration_ms: 1000 }),
+      rec({ duration_ms: 3000 }),
+      rec({ duration_ms: 1784536915891, duration_anomaly: true }),
+    ];
+    const stats = computeReworkStats(entries);
+    expect(stats.duration).not.toBeNull();
+    // Median over the two sane values (1000, 3000) is 2000, not ~5.9e11.
+    expect(stats.duration.medianMs).toBe(2000);
+    expect(stats.duration.samples).toBe(2);
+    expect(stats.duration.excludedAnomalies).toBe(1);
+  });
+
+  it('AC-670-62: a failure with no reason is bucketed, never silently dropped', () => {
+    const entries = [
+      rec({ passed: false }),                              // no failure_reason
+      rec({ passed: false, failure_reason: '' }),          // empty
+      rec({ passed: false, failure_reason: 'short-circuit' }),
+    ];
+    const stats = computeReworkStats(entries);
+    // Dropping unlabelled failures would understate the failure count and push
+    // the first-pass rate UP -- the optimistic direction is the dangerous one.
+    expect(stats.failures).toBe(3);
+    const unattributed = stats.topFailures.find((f) => /unattributed|unknown/i.test(f.reason));
+    expect(unattributed, 'unlabelled failures must appear in the ranking').toBeDefined();
+    expect(unattributed.count).toBe(2);
+  });
+});
+
+describe('rework duration sampling (#651)', () => {
+  it('AC-670-61: an UNFLAGGED epoch-sized duration is still excluded', () => {
+    // Measured on the real journal: 391 records carry duration_anomaly, but 6
+    // more epoch-sized values do not. Trusting the flag alone left the mean at
+    // 1.3e9 ms -- the "average 430 million seconds" artifact returning through
+    // the back door. Plausibility must be checked independently of the flag.
+    const entries = [
+      rec({ duration_ms: 2000 }),
+      rec({ duration_ms: 4000 }),
+      rec({ duration_ms: 1785001784992 }), // no duration_anomaly flag
+    ];
+    const stats = computeReworkStats(entries);
+    expect(stats.duration).not.toBeNull();
+    expect(stats.duration.medianMs).toBe(3000);
+    expect(stats.duration.samples).toBe(2);
+    // Excluded count covers BOTH flagged and implausible, or the sample size
+    // looks closer to the record count than it really is.
+    expect(stats.duration.excludedAnomalies).toBe(1);
+  });
+});