@boyingliu01/xp-gate 0.35.10 → 0.35.11

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"
@@ -578,6 +602,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 +672,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 +689,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 +5138,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-30T21:19:13.693Z",
   "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 })),

package/lib/slo.js

@@ -0,0 +1,150 @@
+/**
+ * @test REQ-609 SLO 指标必须区分"达标"与"没有数据"
+ * @intent 指南 §15 要求首构 ≥90%、终构 ≥98%、首测 ≥85%、Flaky ≤0.5%、
+ *         CI 无效触发 ≤20%、文件丢失 = 0。
+ *
+ *         这个模块的**全部价值**在于三态判定，而不是六行数字：
+ *
+ *           PASS   有数据，且在目标内
+ *           MISS   有数据，但在目标外          <- 唯一需要行动的
+ *           UNKNOWN 数据不足，无从判断         <- 不是通过，也不是失败
+ *
+ *         为什么 UNKNOWN 必须独立存在：把"没有数据"折叠进 PASS 就是 #554 那一类
+ *         缺陷（门禁没跑却报通过）；折叠进 MISS 则会让每一个新仓库一开始就六项
+ *         全红，于是所有人都学会忽略这个面板——面板一旦被忽略，它就和不存在一样。
+ *
+ *         "文件丢失 = 0"尤其危险：它的目标值是 0，而没有数据时最自然的算法
+ *         恰好也产出 0。所以这一项的 UNKNOWN 判定必须先于数值比较，而不是
+ *         比较完之后再补一句注释。
+ *
+ *         每个 SLO 都带 `source`：没有指明数据来源的指标无法被核实，
+ *         也就无法被信任。
+ */
+'use strict';
+
+/** 六项 SLO 及其目标。方向决定比较运算符，避免手写每个分支。 */
+const SLO_DEFINITIONS = [
+  {
+    id: 'first_build_pass',
+    label: 'First-build pass rate',
+    target: 90,
+    unit: '%',
+    direction: 'min',
+    source: '.xp-gate/audit.jsonl + pre-commit reports',
+    describe: 'first attempt of each gate run passes without a retry',
+  },
+  {
+    id: 'final_build_pass',
+    label: 'Final-build pass rate',
+    target: 98,
+    unit: '%',
+    direction: 'min',
+    source: '.xp-gate/audit.jsonl (last attempt per gate per commit)',
+    describe: 'the attempt that actually lands passes',
+  },
+  {
+    id: 'first_test_pass',
+    label: 'First-test pass rate',
+    target: 85,
+    unit: '%',
+    direction: 'min',
+    source: '.xp-gate/audit.jsonl (Gate 5 first attempt)',
+    describe: 'test suite passes on its first run in a commit',
+  },
+  {
+    id: 'flaky_rate',
+    label: 'Flaky rate',
+    target: 0.5,
+    unit: '%',
+    direction: 'max',
+    source: '.xp-gate/audit.jsonl re-run records',
+    describe: 'a test that failed then passed on re-run without a code change',
+  },
+  {
+    id: 'ci_wasted_trigger',
+    label: 'CI wasted trigger rate',
+    target: 20,
+    unit: '%',
+    direction: 'max',
+    source: '.github workflow runs vs gate journal',
+    describe: 'a CI run triggered by a commit that the gates had already rejected',
+  },
+  {
+    id: 'file_loss',
+    label: 'File loss events',
+    target: 0,
+    unit: '',
+    direction: 'max',
+    source: 'vitest-worktree-guard + git status snapshots',
+    describe: 'tracked files disappearing during a run',
+  },
+];
+
+const STATES = { PASS: 'PASS', MISS: 'MISS', UNKNOWN: 'UNKNOWN' };
+
+/**
+ * Evaluate one SLO sample.
+ *
+ * `value === null` / `undefined` means "no measurement", which is a different
+ * claim from `value === 0`. Keeping them distinct is the whole point of this module.
+ */
+function evaluateSlo(id, value, opts = {}) {
+  const def = SLO_DEFINITIONS.find((d) => d.id === id);
+  if (!def) throw new Error(`unknown SLO id: ${id}`);
+
+  if (value === null || value === undefined || Number.isNaN(value)) {
+    return {
+      ...def,
+      value: null,
+      state: STATES.UNKNOWN,
+      reason: opts.reason || 'no measurement available in the reporting window',
+    };
+  }
+
+  // File loss is the trap: its target is 0, and a naive max-direction comparison
+  // (`0 <= 0`) reports PASS for a window that observed nothing. Requiring an
+  // explicit sample count makes "we looked and saw none" different from "we did
+  // not look".
+  const samples = opts.samples;
+  if (def.id === 'file_loss' && (samples === undefined || samples === null || samples <= 0)) {
+    return {
+      ...def,
+      value: null,
+      state: STATES.UNKNOWN,
+      reason: 'no guard runs in the window -- absence of guards is not absence of loss',
+    };
+  }
+
+  const pass = def.direction === 'min' ? value >= def.target : value <= def.target;
+  return {
+    ...def,
+    value,
+    sampleCount: samples,
+    state: pass ? STATES.PASS : STATES.MISS,
+    reason: pass ? '' : `${value}${def.unit} vs target ${def.direction === 'min' ? '>=' : '<='} ${def.target}${def.unit}`,
+  };
+}
+
+/** Evaluate a whole batch of measurements (`{ id: value | {value,samples} }`). */
+function evaluateAll(measurements = {}) {
+  return SLO_DEFINITIONS.map((def) => {
+    const raw = measurements[def.id];
+    if (raw && typeof raw === 'object') return evaluateSlo(def.id, raw.value, raw);
+    return evaluateSlo(def.id, raw);
+  });
+}
+
+/** Count rows per state -- what a dashboard badge and a retro line both need. */
+function summariseStates(rows) {
+  const out = { PASS: 0, MISS: 0, UNKNOWN: 0, total: rows.length };
+  for (const r of rows) out[r.state] += 1;
+  return out;
+}
+
+module.exports = {
+  SLO_DEFINITIONS,
+  STATES,
+  evaluateSlo,
+  evaluateAll,
+  summariseStates,
+};

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.35.10",
+  "version": "0.35.11",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "bin/xp-gate.js"

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.35.10",
+  "version": "0.35.11",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/claude-code/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/claude-code/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/claude-code/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/dsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/dsh-plugin-xp-gate",
-  "version": "0.35.10",
+  "version": "0.35.11",
   "description": "XP-Gate deterministic quality gates + AI workflow skills as a DeepSeek Harness (DSH) native plugin: gate-check / gate-principles / gate-arch tools + 12 SKILL.md skills",
   "type": "module",
   "main": "./lib/index.js",

package/plugins/dsh/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/dsh/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/dsh/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/opencode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/opencode-plugin",
-  "version": "0.35.10",
+  "version": "0.35.11",
   "type": "module",
   "main": "index.ts",
   "description": "XP-Gate quality gates + AI workflow skills + Sprint Flow TUI sidebar for OpenCode",

package/plugins/opencode/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/opencode/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/opencode/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/plugins/qoder/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.35.10",
+  "version": "0.35.11",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Qoder. Includes 12 pre-commit gates (Gate 0-11), 8 pre-push gates, Sprint Flow (6 phases), and Delphi multi-expert review (>=90% consensus).",
   "author": {

package/plugins/qoder/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/plugins/qoder/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/plugins/qoder/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.

package/skills/delphi-review/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/DELPHI-REVIEW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Delphi Consensus Review — multi-round anonymous expert review (≥90% threshold, exactly 3 experts with distinct executable model IDs). Supports design, requirements, and code-walkthrough modes.

package/skills/sprint-flow/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/SPRINT-FLOW KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 **6-phase** development pipeline (v2.0 compact redesign, Issue #290): PREP → DESIGN → BUILD → VERIFY → SHIP → CLOSE. Phase 3/6 BUILD default build mode is **ralph-loop** (REQ-level iteration, 40-67% token savings vs parallel). HARD-GATE between DESIGN (2/6) and BUILD (3/6): design must pass Delphi review (≥90% consensus) before any coding.

package/skills/test-specification-alignment/AGENTS.md

@@ -1,9 +1,9 @@
 # SKILLS/TEST-SPECIFICATION-ALIGNMENT KNOWLEDGE BASE
 
 **Generated:** 2026-10-30
-**Commit:** 6c9bcb78
+**Commit:** c5c05324
 **Branch:** main
-**Version:** 0.35.10.0
+**Version:** 0.35.11.0
 
 ## OVERVIEW
 Test-Specification Alignment Engine — two-stage validation ensuring tests accurately reflect requirements and design specs.