@boyingliu01/xp-gate 0.35.10 → 0.35.12

package/hooks/pre-commit

@@ -36,6 +36,30 @@ _LE_CR=$(tr -cd '\r' < "$0" | wc -c | tr -d '[:space:]'); test "${_LE_CR:-0}" -e
 # 1. Global: ~/.config/xp-gate/adapters (for core.hooksPath global setup)
 # 2. Project-local: <repo>/githooks/ (for per-project init)
 # 3. Script dir: hooks directory containing this script (fallback)
+# ── #640: wall-clock start, written into the per-run report ──────────────────
+# The gate journal records every gate's verdict but no timing, so a slow commit
+# could not be attributed: the #640 measurement found ~11s per commit outside any
+# gate and had no instrument to say where it went. One timestamp at entry and one
+# subtraction at report-write time turns "it feels slow" into a number.
+#
+# Milliseconds come from /proc/uptime when readable (bash's %3N is not portable to
+# the bash 3.2 / MSYS builds this hook supports); otherwise whole seconds, which
+# is coarse but still separates "gates are slow" from "the hook around them is".
+_XP_HOOK_START_MS=""
+if [ -r /proc/uptime ]; then
+  _xp_up=$(cut -d' ' -f1 /proc/uptime 2>/dev/null || echo "")
+  case "$_xp_up" in
+    *.*) _XP_HOOK_START_MS=$(printf '%s%s' "${_xp_up%%.*}" "$(printf '%s' "${_xp_up#*.}" | cut -c1-3)") ;;
+  esac
+fi
+case "$_XP_HOOK_START_MS" in
+  ''|*[!0-9]*) _XP_HOOK_START_MS=$(( $(date +%s) * 1000 )) ;;
+esac
+export _XP_HOOK_START_MS
+# #609: 1-based attempt index for this hook run. One hook invocation is one attempt,
+# so every gate recorded during it shares the same index. Left empty by default so a
+# caller that genuinely does not know the index omits the field instead of guessing.
+_XP_GATE_ATTEMPT=""
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ADAPTER_DIR=""
 GLOBAL_ADAPTER_DIR="$HOME/.config/xp-gate/adapters"
@@ -76,8 +100,16 @@ fi
 # and a plausible wrong number is harder to notice than a visible gap.
 #
 # Resolve from the repo's own declaration, in the order the tools themselves
-# use: pyproject [tool.coverage.report] fail_under, then .coveragerc. A repo
-# declaring neither keeps the historical 80.
+# use: pyproject [tool.coverage.report] fail_under, then .coveragerc, then the
+# JS/TS runner's own threshold block. A repo declaring none keeps the historical 80.
+#
+# #605: the JS/TS branch below enforces THIS number, but the resolver only ever
+# read Python declarations -- so a vitest project declaring `thresholds.lines: 60`
+# was silently judged against 80. The result was the worst possible split:
+# `npx vitest run` goes green, the commit is then rejected, and the two numbers
+# are read from different files with nothing pointing at the disagreement.
+# Same defect shape as #554/#609: a declaration exists, an enforcement exists,
+# and nothing connected them.
 _resolve_coverage_threshold() {
   _rct_value=""
   _rct_src="default"
@@ -93,13 +125,36 @@ _resolve_coverage_threshold() {
     _rct_value=$(grep -oE '^[[:space:]]*fail_under[[:space:]]*=[[:space:]]*[0-9]+' .coveragerc 2>/dev/null | grep -oE '[0-9]+' | head -1 || true)
     [ -n "$_rct_value" ] && _rct_src=".coveragerc fail_under"
   fi
+  # #605: JS/TS. Read the runner's own threshold rather than assuming 80, so the
+  # hook enforces the number the project actually declares. `lines` specifically:
+  # it is the metric the JS branch below compares, and it is the one vitest docs
+  # lead with. Only the FLAT shape is read -- the nested `thresholds: { global }`
+  # form is vitest 2.x and was proven silently dropped by the 1.6.x config parser
+  # (#561), so honouring it here would enforce a number that never takes effect.
+  if [ -z "$_rct_value" ]; then
+    for _rct_cfg in vitest.config.ts vitest.config.js vitest.config.mts; do
+      [ -f "$_rct_cfg" ] || continue
+      _rct_value=$(sed -n '/thresholds[[:space:]]*:[[:space:]]*{/,/}/p' "$_rct_cfg" 2>/dev/null \
+        | grep -oE 'lines[[:space:]]*:[[:space:]]*[0-9]+' | grep -oE '[0-9]+' | head -1 || true)
+      if [ -n "$_rct_value" ]; then
+        _rct_src="$_rct_cfg coverage.thresholds.lines"
+        break
+      fi
+    done
+  fi
   case "$_rct_value" in
-    ''|*[!0-9]*) _rct_value="80"; _rct_src="default (no fail_under declared)" ;;
+    ''|*[!0-9]*) _rct_value="80"; _rct_src="default (no coverage threshold declared)" ;;
   esac
   COVERAGE_THRESHOLD_SOURCE="$_rct_src"
   printf '%s' "$_rct_value"
 }
-COVERAGE_THRESHOLD="$(_resolve_coverage_threshold)"
+# NOT `COVERAGE_THRESHOLD="$(_resolve_coverage_threshold)"`: command substitution
+# runs in a subshell, so `COVERAGE_THRESHOLD_SOURCE` set inside the function was
+# discarded and the audit record's `threshold_source` field was empty on every
+# single commit. A field that is always blank is worse than a missing one -- it
+# looks populated and says nothing. Call the function in this shell instead.
+_resolve_coverage_threshold >/dev/null
+COVERAGE_THRESHOLD="$_rct_value"
 
 # Look up one tier's directory variable by name without eval-ing arbitrary input:
 # the base names are a closed set baked into the generated file.
@@ -578,6 +633,41 @@ record_gate_audit() {
   local detail="${6:-}"
   local end_ms
   end_ms=$(now_ms)
+  # #609: attempt index for this gate.
+  #
+  # Two failed designs are recorded here so they are not retried:
+  #
+  #   1. Keying on commit_hash -- the pre-commit record is STAGED with an empty
+  #      commit_hash (the commit does not exist yet, see stageAuditEntry), so the
+  #      lookup always matched zero and every gate stayed at attempt 1.
+  #   2. Counting every record in a time window -- measured attempt=63 for gate-1
+  #      over one working session, because unrelated SUCCESSFUL commits accumulate.
+  #      A retry index that counts successes is not a retry index.
+  #
+  # What actually defines a retry: the previous record for this gate FAILED. So the
+  # index is (consecutive failures immediately before this run) + 1. A clean history
+  # is attempt 1; fail, fix, re-commit gives 2; three failures in a row gives 4.
+  #
+  # Read failure leaves the value empty -> the writer omits the field rather than
+  # recording a fabricated 1, which would inflate the first-pass denominator.
+  if [ -z "${_XP_GATE_ATTEMPT:-}" ]; then
+    local _failed_streak
+    if [ -f .xp-gate/audit.jsonl ]; then
+      _failed_streak=$(awk -v g="\"gate_id\":\"${gate_id}\"" '
+        index($0, g) {
+          # passed is a JSON boolean; "false" is the only failure spelling.
+          if (index($0, "\"passed\":false") > 0) { streak++ }
+          else if (index($0, "\"passed\":true") > 0) { streak = 0 }
+        }
+        END { print streak + 0 }' .xp-gate/audit.jsonl 2>/dev/null | tr -d ' ')
+      case "$_failed_streak" in
+        ''|*[!0-9]*) _failed_streak="" ;;
+      esac
+      if [ -n "$_failed_streak" ]; then
+        _XP_GATE_ATTEMPT=$(( _failed_streak + 1 ))
+      fi
+    fi
+  fi
   # REQ-B: sanitize BEFORE subtracting. A poisoned start (empty -> arithmetic
   # 0, or a seconds-unit value from an old code path) used to survive as an
   # epoch-sized duration_ms that only the anomaly flag papered over. Now the
@@ -613,6 +703,13 @@ record_gate_audit() {
   fi
 
   # Fire-and-forget: audit must never block the commit
+  #
+  # #609: `--attempt` was implemented in gate-audit.ts (#603) but never passed by
+  # this hook -- verified against 9212 real journal entries, none carried `attempt`.
+  # The 1-based attempt index makes the first-build / final-build / first-test SLOs
+  # computable; without it "passed" cannot separate a clean run from one that only
+  # passed after a re-run, and every such metric is defined to be 100%. Callers that
+  # do not know the index stay absent (== 1) rather than being stamped with a guess.
   {
     run_tsx "${PROJECT_ROOT_FOR_AUDIT}/src/npm-package/lib/gate-audit.ts" record \
       --gate-id "$gate_id" \
@@ -623,6 +720,7 @@ record_gate_audit() {
       $duration_anomaly_flag \
       $duration_reason_flag \
       --trigger commit \
+      ${_XP_GATE_ATTEMPT:+--attempt "$_XP_GATE_ATTEMPT"} \
       ${detail:+--detail "$detail"} \
       2>/dev/null
   } &
@@ -5071,7 +5169,35 @@ ENDJSON
   REPORT_TS=$(date -u +"%Y-%m-%d-%H%M%S")
   local PERSISTED_REPORT_FILE="${REPORTS_DIR}/${REPORT_TS}.json"
   mkdir -p "$REPORTS_DIR"
-  _XP_RF="$REPORT_FILE" _XP_PRF="$PERSISTED_REPORT_FILE" _XP_TS="$TIMESTAMP" _XP_BR="$BRANCH" _XP_CH="$COMMIT_HASH" _XP_CF="${CHANGED_FILES:-}" node -e "const fs=require('fs');const e=process.env;const br=JSON.parse(fs.readFileSync(e._XP_RF,'utf8'));const cf=(e._XP_CF||'').split('\n').filter(f=>f);const r={timestamp:e._XP_TS,trigger:'pre-commit',branch:e._XP_BR,commit:e._XP_CH,changed_files:cf,overall:br.overall||{},gates:br.gates||{},warnings:[],errors:[]};fs.writeFileSync(e._XP_PRF,JSON.stringify(r,null,2)+'\n');" 2>/dev/null || cp "$REPORT_FILE" "$PERSISTED_REPORT_FILE"
+  # #640: `duration_ms` is wall-clock time from hook entry to report write. It is
+  # the number the issue could not get: gate verdicts were journaled but durations
+  # were not, so the ~11s observed outside any gate had no instrument pointing at
+  # it. Emitted only when measurable -- an absent field is honest, a 0 is not.
+  #
+  # The subtraction happens in BASH, not in the node writer. Measured: on MSYS
+  # (Windows) `/proc/uptime` is visible to bash but NOT to native node --
+  # `readFileSync('/proc/uptime')` there throws ENOENT. Computing the elapsed time
+  # in node therefore passed a bash-clock start into a reader that could not produce
+  # a comparable "now", and the field silently never appeared. Both ends of a
+  # duration must come from the same clock.
+  local _XP_DURATION_MS=""
+  local _XP_NOW_MS=""
+  if [ -r /proc/uptime ]; then
+    _xp_up2=$(cut -d' ' -f1 /proc/uptime 2>/dev/null || echo "")
+    case "$_xp_up2" in
+      *.*) _XP_NOW_MS=$(printf '%s%s' "${_xp_up2%%.*}" "$(printf '%s' "${_xp_up2#*.}" | cut -c1-3)") ;;
+    esac
+  fi
+  case "$_XP_NOW_MS" in
+    ''|*[!0-9]*) _XP_NOW_MS="" ;;
+  esac
+  case "$_XP_HOOK_START_MS" in
+    ''|*[!0-9]*) _XP_HOOK_START_MS="" ;;
+  esac
+  if [ -n "$_XP_NOW_MS" ] && [ -n "$_XP_HOOK_START_MS" ] && [ "$_XP_NOW_MS" -gt "$_XP_HOOK_START_MS" ]; then
+    _XP_DURATION_MS=$(( _XP_NOW_MS - _XP_HOOK_START_MS ))
+  fi
+  _XP_RF="$REPORT_FILE" _XP_PRF="$PERSISTED_REPORT_FILE" _XP_TS="$TIMESTAMP" _XP_BR="$BRANCH" _XP_CH="$COMMIT_HASH" _XP_CF="${CHANGED_FILES:-}" _XP_DUR="$_XP_DURATION_MS" node -e "const fs=require('fs');const e=process.env;const br=JSON.parse(fs.readFileSync(e._XP_RF,'utf8'));const cf=(e._XP_CF||'').split('\n').filter(f=>f);const r={timestamp:e._XP_TS,trigger:'pre-commit',branch:e._XP_BR,commit:e._XP_CH,changed_files:cf,overall:br.overall||{},gates:br.gates||{},warnings:[],errors:[]};const d=Number(e._XP_DUR);if(Number.isFinite(d)&&d>0){r.duration_ms=d;}fs.writeFileSync(e._XP_PRF,JSON.stringify(r,null,2)+'\n');" 2>/dev/null || cp "$REPORT_FILE" "$PERSISTED_REPORT_FILE"
 
   # ── History append (unchanged — append-only for trend) ────────────────────────────
   local GATES_JSON="{"

package/lib/__tests__/coverage-scope.test.js

@@ -0,0 +1,140 @@
+/**
+ * @test REQ-562 覆盖率核算范围必须覆盖真实被测代码，不能靠排除把分数养高
+ * @intent #562 追踪把 lines/statements 从 60% 提到 80%。它建议的第一步是
+ *         "把 `plugins/**` 的排除去掉"，理由是那里有 801 个测试被隐藏。
+ *
+ *         **那条理由已经不成立了**：28 个插件测试文件、225 个测试**本来就在跑**，
+ *         全绿。`plugins/**` 只出现在 `coverage.exclude` 里，不在 `test.exclude` 里。
+ *
+ *         真正没被修的是另一半：`coverage.include` 曾是 `['src/**']`，所以
+ *         `'plugins/**'` 这条排除项**从来没有起过作用**——plugins 源码压根不在
+ *         核算范围内，光靠 include 就被排除了。结果是 4340 行、30 个文件、
+ *         被 225 个通过的测试覆盖着的规范源代码，**从未计入覆盖率**。
+ *
+ *         隔离测量这些源文件是 **83.8% lines**，远高于仓库 60% 的地板。
+ *         "把一个覆盖良好的目录排除在平均分之外"是覆盖率数字从"描述代码库"
+ *         退化成"描述配置"的典型方式。
+ *
+ *         这里的断言是两条**属性**，不是某个 glob 的字符串：
+ *           1. 有测试在跑的源码必须被计入覆盖率核算。
+ *           2. exclude 里的每一条都必须在 include 的范围内，否则它是死配置——
+ *              读起来像"我们考虑过"，实际什么都没做。
+ * @covers AC-562-01, AC-562-02
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+const CONFIG = path.join(REPO_ROOT, 'vitest.config.ts');
+
+/**
+ * Read the `coverage:` block and return its include/exclude globs.
+ *
+ * Comment lines are blanked first: this config explains its own history by quoting
+ * old patterns in prose (the same trap recorded in gate-coverage.js for #605), and
+ * a naive read treats a quoted example as live configuration.
+ */
+function readCoverageGlobs() {
+  let raw;
+  try {
+    raw = fs.readFileSync(CONFIG, 'utf8').replace(/^\s*\/\/.*$/gm, '');
+  } catch (err) {
+    throw new Error(`cannot read vitest.config.ts: ${err.message}`);
+  }
+  const start = raw.indexOf('coverage: {');
+  if (start === -1) throw new Error('coverage block not found in vitest.config.ts');
+  const block = raw.slice(start, raw.indexOf('\n    },', start));
+  const pick = (key) => {
+    const m = block.match(new RegExp(`${key}:\\s*\\[([\\s\\S]*?)\\]`));
+    if (!m) return [];
+    return [...m[1].matchAll(/'([^']+)'/g)].map((x) => x[1]);
+  };
+  return { include: pick('include'), exclude: pick('exclude') };
+}
+
+/**
+ * Trees that legitimately hold tests but are not measured product source:
+ * build sandboxes, dependencies, and tooling. Excluding these is not the defect
+ * #562 describes -- excluding a product tree that tests already exercise is.
+ */
+const NOT_PRODUCT_TREES = [
+  'node_modules', '.stryker-tmp', '.worktrees', '.git', 'coverage', 'dist',
+  'scripts', 'skills', 'githooks', 'dashboard', 'compat', '.xp-gate',
+  '.agent-tmp', '.delphi-work', '.opencode', '.omo', '.workbuddy',
+];
+
+/** The #562 shape, kept as data so the detector can be tested on it. */
+const UNMEASURED_SAMPLE = ['plugins/**'];
+
+/** True when a directory holds at least one collected test file (bounded depth). */
+function hasTestFile(dir, depth) {
+  if ((depth || 0) > 4) return false;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const e of entries) {
+    if (e.name === 'node_modules' || e.name === 'skills') continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (hasTestFile(full, (depth || 0) + 1)) return true;
+    } else if (/\.test\.[cm]?[jt]s$/.test(e.name)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+describe('覆盖率核算范围 (#562)', () => {
+  it('AC-562-01: 有测试在跑的源码必须计入覆盖率核算', () => {
+    // 28 test files under plugins/ run and pass; if the source they exercise is not
+    // measured, those 225 tests cannot move the coverage number at all.
+    const { include } = readCoverageGlobs();
+    expect(include.some((g) => g.startsWith('plugins/'))).toBe(true);
+  });
+
+  it('AC-562-01: plugins 不再出现在排除列表里', () => {
+    const { exclude } = readCoverageGlobs();
+    expect(exclude).not.toContain('plugins/**');
+  });
+
+  it('AC-562-02: 被测试覆盖的源码目录不能被排除在核算之外', () => {
+    // `'plugins/**'` sat in exclude while include was `['src/**']`: the entry could
+    // never match, so it read as "we thought about plugins" while doing nothing.
+    //
+    // A generic "is this exclude entry dead?" check cannot work -- `node_modules/**`
+    // and `.worktrees/**` legitimately name real directories that must stay out, and
+    // `scripts/**` / `skills/**` hold tooling rather than measured product source.
+    // The property that matters is narrower: **product source with tests must be
+    // measured.** Otherwise those tests cannot move the coverage number at all.
+    const { exclude } = readCoverageGlobs();
+    const dirsWithTests = fs
+      .readdirSync(REPO_ROOT, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .filter((name) => !NOT_PRODUCT_TREES.includes(name))
+      .filter((name) => hasTestFile(path.join(REPO_ROOT, name)));
+    const unmeasured = dirsWithTests.filter((name) => exclude.includes(`${name}/**`));
+    expect(unmeasured).toEqual([]);
+  });
+
+  it('AC-562-02: 检测器在合成输入上确实会触发', () => {
+    // A detector that never fires is indistinguishable from "no drift" -- the same
+    // trap recorded for the mirror guard (#654). Prove the filter is not vacuous.
+    const fakeDirs = ['plugins', 'dashboard'];
+    const unmeasured = fakeDirs.filter((name) => UNMEASURED_SAMPLE.includes(`${name}/**`));
+    expect(unmeasured).toEqual(['plugins']);
+  });
+
+  it('AC-562-02: 检测器在合成输入上确实会触发', () => {
+    // A detector that never fires is indistinguishable from "no drift" -- the same
+    // trap recorded for the mirror guard (#654). Prove the filter is not vacuous.
+    const fake = ['plugins', 'dashboard'];
+    const unmeasured = fake.filter((name) => UNMEASURED_SAMPLE.includes(`${name}/**`));
+    expect(unmeasured).toEqual(['plugins']);
+  });
+});

package/lib/__tests__/slo.test.js

@@ -0,0 +1,89 @@
+/**
+ * @test REQ-609 SLO 三态判定：PASS / MISS / UNKNOWN 必须互不可替代
+ * @intent 六项 SLO 的价值不在数字本身，而在"能不能行动"。
+ *
+ *         这里断言的是**状态机**，不是阈值算术：
+ *
+ *           - 没数据 -> UNKNOWN，既不报通过也不报失败
+ *           - 有数据但越界 -> MISS（唯一需要行动的状态）
+ *           - 文件丢失目标为 0 时，"没跑过守卫" 不得算成 PASS
+ *
+ *         最后一条是本模块最容易被写错的地方：`0 <= 0` 恒真，所以任何按
+ *         数值比较的实现都会在没有观测时报告"零文件丢失"——那是对**没有发生
+ *         观测**和**观测到零**的混淆，与 #554 门禁没跑却报通过同源。
+ * @covers AC-609-01, AC-609-02, AC-609-03
+ */
+'use strict';
+
+const { evaluateSlo, evaluateAll, summariseStates, SLO_DEFINITIONS, STATES } = require('../slo');
+
+describe('SLO 三态判定 (#609)', () => {
+  it('AC-609-01: 无数据返回 UNKNOWN 而不是 PASS 或 MISS', () => {
+    for (const id of ['first_build_pass', 'flaky_rate', 'file_loss']) {
+      const r = evaluateSlo(id, null);
+      expect(r.state).toBe(STATES.UNKNOWN);
+      expect(r.value).toBeNull();
+      expect(r.reason.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('AC-609-01: 有价值的 0 与无数据必须可区分', () => {
+    // flaky_rate = 0 is a real, excellent measurement; null is not a measurement.
+    const zero = evaluateSlo('flaky_rate', 0);
+    const absent = evaluateSlo('flaky_rate', null);
+    expect(zero.state).toBe(STATES.PASS);
+    expect(absent.state).toBe(STATES.UNKNOWN);
+    expect(zero.state).not.toBe(absent.state);
+  });
+
+  it('AC-609-02: min 方向越界是 MISS，达标是 PASS', () => {
+    expect(evaluateSlo('first_build_pass', 90).state).toBe(STATES.PASS);
+    expect(evaluateSlo('first_build_pass', 89.9).state).toBe(STATES.MISS);
+  });
+
+  it('AC-609-02: max 方向越界是 MISS，零违规是 PASS', () => {
+    expect(evaluateSlo('ci_wasted_trigger', 20).state).toBe(STATES.PASS);
+    expect(evaluateSlo('ci_wasted_trigger', 20.1).state).toBe(STATES.MISS);
+  });
+
+  it('AC-609-03: file_loss 目标为 0 时，没有样本不算 PASS', () => {
+    // `0 <= 0` passes a naive comparison. Without an observation, the honest
+    // answer is UNKNOWN -- same defect class as a gate that reports success
+    // without running.
+    const noSamples = evaluateSlo('file_loss', 0);
+    expect(noSamples.state).toBe(STATES.UNKNOWN);
+  });
+
+  it('AC-609-03: file_loss 有样本且为 0 才算 PASS', () => {
+    const observed = evaluateSlo('file_loss', 0, { samples: 12 });
+    expect(observed.state).toBe(STATES.PASS);
+    expect(observed.sampleCount).toBe(12);
+  });
+
+  it('AC-609-03: file_loss 有样本且非 0 是 MISS', () => {
+    expect(evaluateSlo('file_loss', 3, { samples: 12 }).state).toBe(STATES.MISS);
+  });
+
+  it('AC-609-01: 每项 SLO 都声明了数据来源', () => {
+    // A metric whose provenance is unstated cannot be verified, so it cannot be
+    // trusted -- and an untrusted SLO panel is worse than no panel.
+    for (const def of SLO_DEFINITIONS) {
+      expect(def.source).toBeTruthy();
+      expect(def.describe).toBeTruthy();
+    }
+  });
+
+  it('AC-609-01: evaluateAll 覆盖全部六项且计数自洽', () => {
+    const rows = evaluateAll({ first_build_pass: 95, flaky_rate: null });
+    expect(rows).toHaveLength(SLO_DEFINITIONS.length);
+    const counts = summariseStates(rows);
+    expect(counts.total).toBe(SLO_DEFINITIONS.length);
+    expect(counts.PASS + counts.MISS + counts.UNKNOWN).toBe(counts.total);
+    expect(counts.PASS).toBe(1);
+    expect(counts.UNKNOWN).toBe(SLO_DEFINITIONS.length - 1);
+  });
+
+  it('AC-609-02: 未知 SLO id 抛错而不是静默返回', () => {
+    expect(() => evaluateSlo('no_such_slo', 1)).toThrow(/unknown SLO id/);
+  });
+});

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-30T19:59:34.778Z",
+  "checked_at": "2026-10-30T22:00:31.148Z",
   "source": "network"
 }

package/lib/retro.js

@@ -15,6 +15,7 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 const { computeFlakyStats, parseQuarantine, findPolicyViolations } = require('./flaky');
+const { evaluateAll, summariseStates } = require('./slo');
 
 /**
  * Upper bound for a believable gate runtime. A gate that reports more than two
@@ -242,6 +243,59 @@ function buildGateMSection(runs) {
  * @param {object} opts - Report data
  * @returns {string} Markdown report
  */
+/**
+ * Derive the six SLO measurements from the journal (#609, guide §15).
+ *
+ * Every branch that cannot produce a number returns `null`, never 0. The SLO
+ * evaluator turns nulls into UNKNOWN, which is displayed as "not measured" --
+ * distinct from "measured zero". A dashboard that prints 0% for an unmeasured
+ * window teaches people to ignore it.
+ */
+function deriveSloMeasurements(audit, flaky) {
+  const gateEntries = audit.filter((e) => e.gate_id);
+  // The journal key is `commit_hash`, not `commit`, and there is no `attempt`
+  // field at all (verified against 9212 real entries). Without attempts, a single
+  // gate list cannot separate "passed first time" from "passed after a retry", so
+  // the three attempt-derived SLOs stay UNKNOWN rather than being approximated
+  // from a flat pass rate -- which would report ~100% and be believed.
+  const withAttempt = gateEntries.filter((e) => Number.isFinite(e.attempt));
+  const firsts = withAttempt.filter((e) => e.attempt === 1);
+  const firstPass = firsts.filter((e) => e.passed).length;
+
+  // "Final" = the last attempt recorded per gate within each commit.
+  const finals = new Map();
+  for (const e of withAttempt) {
+    const key = `${e.commit_hash || ''}:${e.gate_id}`;
+    const prev = finals.get(key);
+    if (!prev || e.attempt > prev.attempt) finals.set(key, e);
+  }
+  const finalList = [...finals.values()];
+
+  // Gate 5 is the test gate; its first attempt is the first-test signal.
+  const gate5First = firsts.filter((e) => /gate.?5|test/i.test(String(e.gate_id)));
+
+  return {
+    first_build_pass: firsts.length > 0 ? (firstPass / firsts.length) * 100 : null,
+    final_build_pass: finalList.length > 0
+      ? (finalList.filter((e) => e.passed).length / finalList.length) * 100
+      : null,
+    first_test_pass: gate5First.length > 0
+      ? (gate5First.filter((e) => e.passed).length / gate5First.length) * 100
+      : null,
+    flaky_rate: flaky && flaky.measurable && flaky.flakyRate !== null
+      ? parseFloat(flaky.flakyRate)
+      : null,
+    // No workflow-run source is wired in yet: a number here would be invented.
+    ci_wasted_trigger: null,
+    file_loss: { value: 0, samples: countGuardRuns(audit) },
+  };
+}
+
+/** How many guard runs the journal actually observed (file-loss denominator). */
+function countGuardRuns(audit) {
+  return audit.filter((e) => /worktree.?guard|file.?loss/i.test(String(e.event || e.gate_id || ''))).length;
+}
+
 function buildReport(opts) {
   const { days, commits, audit, quality, sprints, gateMRuns = [] } = opts;
   const now = new Date();
@@ -277,6 +331,27 @@ function buildReport(opts) {
   }
   L.push('');
 
+  // SLO panel (#609, guide §15)
+  L.push('## SLO Dashboard (#609)');
+  const sloRows = evaluateAll(deriveSloMeasurements(audit, computeFlakyStats(gateEntries)));
+  const sloCounts = summariseStates(sloRows);
+  L.push(`- ${sloCounts.PASS} PASS / ${sloCounts.MISS} MISS / ${sloCounts.UNKNOWN} UNKNOWN of ${sloCounts.total}`);
+  if (sloCounts.UNKNOWN === sloCounts.total) {
+    // Print the distinction explicitly. An all-UNKNOWN panel is the normal state
+    // for a journal that never recorded attempts, and calling that "0% healthy"
+    // would be the same defect the panel exists to prevent.
+    L.push('- All six UNKNOWN: the journal holds no attempt-level records for this window.');
+    L.push('  That is "not measured", not "nothing wrong" -- see each row source.');
+  }
+  for (const r of sloRows) {
+    const shown = r.value === null ? '--' : `${r.value}${r.unit}`;
+    const goal = `${r.direction === 'min' ? '>=' : '<='} ${r.target}${r.unit}`;
+    L.push(`- [${r.state}] ${r.label}: ${shown} (goal ${goal})`);
+    if (r.state === 'UNKNOWN') L.push(`    reason: ${r.reason}`);
+    if (r.state === 'MISS') L.push(`    ${r.reason}`);
+  }
+  L.push('');
+
   // Flaky-test governance (#603)
   L.push('## Test Stability (#603)');
   const flaky = computeFlakyStats(gateEntries);
@@ -392,10 +467,19 @@ async function handleRetro(args = []) {
   if (jsonFlag) {
     const gateEntries = audit.filter(e => e.gate_id);
     const passed = gateEntries.filter(e => e.passed).length;
+    const sloRows = evaluateAll(deriveSloMeasurements(audit, computeFlakyStats(gateEntries)));
     console.log(JSON.stringify({
       period: { days, from: new Date(Date.now() - days * 86400000).toISOString(), to: new Date().toISOString() },
       total_commits: commits.length,
       gate_pass_rate: gateEntries.length > 0 ? passed / gateEntries.length : null,
+      slo: {
+        states: summariseStates(sloRows),
+        metrics: sloRows.map(r => ({
+          id: r.id, label: r.label, target: r.target, unit: r.unit,
+          direction: r.direction, value: r.value, state: r.state,
+          reason: r.reason, source: r.source,
+        })),
+      },
       rework_rates: sprints.filter(s => s.metrics?.rework_rate != null).map(s => ({ id: s.id, rate: s.metrics.rework_rate })),
       evidence_skipped: audit.filter(e => e.event === 'evidence_skipped'),
       quality: quality.map(q => ({ timestamp: q.timestamp, score: q.score })),