@boyingliu01/xp-gate 0.35.3 → 0.35.5

package/gates/test-layers.ts

@@ -20,8 +20,23 @@ export interface TestLayerReport {
   layer1: {
     pairedSources: number;
     unpairedSources: string[];
+    /**
+     * Sources the pairing convention does not describe (#642).
+     *
+     * Reported apart from `unpairedSources` because the two call for opposite
+     * responses: an unpaired source needs a test, whereas an out-of-scope source
+     * (a shell script covered by BATS) needs the convention widened. Counting it
+     * as "unpaired" would ask the reader to write a .test.ts for `pre-commit`.
+     */
+    outOfScopeSources: string[];
     pairRate: number;
   };
+  /** Test suites that live outside src/ -- BATS and other shell-level suites (#642). */
+  shellSuites: {
+    total: number;
+    bats: number;
+    files: string[];
+  };
   layer2: {
     integrationFiles: number;
   };
@@ -175,6 +190,8 @@ interface LayerCounts {
   integrationTests: string[];
   e2eTests: string[];
   unpairedSources: string[];
+  outOfScopeSources: string[];
+  shellSuites: string[];
   pairedCount: number;
 }
 
@@ -189,15 +206,24 @@ function appendPairingLines(messages: string[], counts: LayerCounts, totalNeedin
   messages.push('  Layer 1 (Unit Pairing):');
   messages.push(`    Paired:    ${counts.pairedCount}/${totalNeedingTests} (${pairRate}%)`);
 
-  const unpaired = counts.unpairedSources;
-  if (unpaired.length === 0 || unpaired.length > UNPAIRED_DISPLAY_LIMIT) {
-    if (unpaired.length > 0) {
-      messages.push(`    Unpaired:  ${unpaired.length} files (showing first 10)`);
-      unpaired.slice(0, UNPAIRED_DISPLAY_LIMIT).forEach(f => messages.push(`      - ${f}`));
-    }
+  appendUnpairedLines(messages, counts.unpairedSources);
+
+  // Out-of-scope sources get their own line: folding them into the unpaired list
+  // would ask the reader to write a module test for a shell script (#642).
+  if (counts.outOfScopeSources.length > 0) {
+    messages.push(`    Not pair-able (shell/other): ${counts.outOfScopeSources.length}`);
+  }
+}
+
+/** Unpaired list, kept short enough not to bury the summary above it (#620). */
+function appendUnpairedLines(messages: string[], unpaired: string[]): void {
+  if (unpaired.length === 0) return;
+  if (unpaired.length <= UNPAIRED_DISPLAY_LIMIT) {
+    messages.push(`    Unpaired:  ${unpaired.join(', ')}`);
     return;
   }
-  messages.push(`    Unpaired:  ${unpaired.join(', ')}`);
+  messages.push(`    Unpaired:  ${unpaired.length} files (showing first 10)`);
+  unpaired.slice(0, UNPAIRED_DISPLAY_LIMIT).forEach(f => messages.push(`      - ${f}`));
 }
 
 /** Format the console block for one analysis. */
@@ -207,10 +233,14 @@ function buildLayerMessages(counts: LayerCounts, totalNeedingTests: number): str
     '━━━ Test Layer Analytics ━━━',
     '',
     `  Sources:     ${counts.sourceFiles.length} files`,
-    `  Tests:       ${counts.testFiles.length} total`,
+    `  Tests:       ${counts.testFiles.length + counts.shellSuites.length} total`,
     `    Unit:      ${counts.unitTests.length}`,
-    `    Integra:   ${counts.integrationTests.length}`,
+    `    Integra:   ${counts.integrationTests.length + counts.shellSuites.length}`,
     `    E2E:       ${counts.e2eTests.length}`,
+    // Printed separately rather than folded into "Integra": whether a suite is
+    // BATS or a TS integration test is a fact about the repo that the reader is
+    // here to learn, and a shell suite is never counted as a unit test (#642).
+    `    Shell:     ${counts.shellSuites.length}`,
     '',
   ];
 
@@ -236,13 +266,21 @@ function buildLayerMessages(counts: LayerCounts, totalNeedingTests: number): str
 function computePairing(
   sourceFiles: string[],
   allFiles: string[],
-): { unpairedSources: string[]; pairedCount: number } {
+): { unpairedSources: string[]; outOfScopeSources: string[]; pairedCount: number } {
   const allSourceRelative = allFiles.map(f => path.join('src', f));
   const unpairedSources: string[] = [];
+  const outOfScopeSources: string[] = [];
   let pairedCount = 0;
 
   for (const source of sourceFiles) {
     if (isExempt(path.basename(source))) continue;
+    // A source the convention does not describe is not "unpaired" -- nobody was
+    // ever asked to pair it. Reporting it as unpaired would send the reader to
+    // write a module test for a shell script (#642).
+    if (isPairingOutOfScope(source)) {
+      outOfScopeSources.push(source);
+      continue;
+    }
     if (findExpectedTest(path.join('src', source), allSourceRelative)) {
       pairedCount++;
     } else {
@@ -250,7 +288,95 @@ function computePairing(
     }
   }
 
-  return { unpairedSources, pairedCount };
+  return { unpairedSources, outOfScopeSources, pairedCount };
+}
+
+/**
+ * Directories that hold test suites but are not under `src/` (#642).
+ *
+ * `test-layers` used to scan only `<repo>/src`, so this repository's 166 BATS
+ * suites were invisible: the report said "Integration: 0" about a repo whose
+ * hook tests spawn real git, real shell adapters and real processes. A metric
+ * that omits 37% of the suites cannot be used to judge the test strategy.
+ */
+const SHELL_SUITE_DIRS = [
+  'githooks/__tests__',
+  'scripts/__tests__',
+  'tests',
+  'test',
+];
+
+/** A shell-level test suite: BATS or a bare .test.cjs/.test.mjs. */
+function isShellSuite(normalized: string): boolean {
+  return /\.test\.bats$/.test(normalized)
+    || /\.test\.(cjs|mjs)$/.test(normalized)
+    || /\/__tests__\/[^/]+\.bats$/.test(normalized);
+}
+
+/**
+ * Find test suites outside `src/` (#642).
+ *
+ * Bounded to the conventional test directories rather than walking the whole
+ * repo: node_modules and build output would otherwise dominate, and a suite that
+ * is not under one of these roots is not discoverable by the runner either.
+ */
+function listDirNames(abs: string): string[] {
+  try {
+    // Explicit encoding: without it readdirSync may hand back Buffer entries.
+    // The array check covers stubbed/mocked fs implementations too -- a suite
+    // that exercises the "directory missing" path must not crash the scanner.
+    const listing = fs.readdirSync(abs, { encoding: 'utf8' });
+    return Array.isArray(listing) ? listing : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Suites under one shell-test root, as repo-relative forward-slash paths. */
+function suitesInDir(root: string, rel: string): string[] {
+  const prefix = rel.split(path.sep).join('/');
+  return listDirNames(path.join(root, rel))
+    .map(name => `${prefix}/${name}`)
+    .filter(isShellSuite);
+}
+
+export function discoverShellSuites(cwd?: string): string[] {
+  const root = cwd || process.cwd();
+  const found = SHELL_SUITE_DIRS.flatMap(rel => suitesInDir(root, rel));
+  // Sorted so the report is stable across filesystems with differing readdir order.
+  return found.sort();
+}
+
+/**
+ * Files the `.test.ts` pairing convention does not apply to (#642).
+ *
+ * Shell scripts are exercised by BATS suites, not by a neighbouring module
+ * test. Listing them separately keeps the pair rate about the language whose
+ * convention it actually describes.
+ */
+function isPairingOutOfScope(filePath: string): boolean {
+  return /\.(sh|bash|bats)$/.test(filePath) || !/\.(ts|tsx|js|jsx|mjs|cjs|py|go|java|kt)$/.test(filePath);
+}
+
+/** The summary block; shell suites are added to the test total (#642). */
+function buildSummary(counts: LayerCounts, shellOutsideSrc: string[]): TestLayerReport['summary'] {
+  return {
+    totalSources: counts.sourceFiles.length,
+    totalTests: counts.testFiles.length + shellOutsideSrc.length,
+    unitTests: counts.unitTests.length,
+    integrationTests: counts.integrationTests.length,
+    e2eTests: counts.e2eTests.length,
+  };
+}
+
+/**
+ * Shell-level suites that the src/ scan did not already pick up (#642).
+ *
+ * Keeping these out of the count made "Integration: 0" a statement about the
+ * scanner rather than about the repository.
+ */
+function shellSuitesOutside(testFiles: string[], dir: string): string[] {
+  return discoverShellSuites(dir).filter(f => !testFiles.includes(f));
 }
 
 /**
@@ -264,7 +390,8 @@ export function analyzeTestLayers(cwd?: string): TestLayerReport {
   const testFiles = allFiles.filter(f => isTestFile(f));
   const byLayer = (layer: string): string[] => testFiles.filter(f => classifyTestLayer(f) === layer);
 
-  const { unpairedSources, pairedCount } = computePairing(sourceFiles, allFiles);
+  const { unpairedSources, outOfScopeSources, pairedCount } = computePairing(sourceFiles, allFiles);
+  const shellOutsideSrc = shellSuitesOutside(testFiles, dir);
 
   const counts: LayerCounts = {
     sourceFiles,
@@ -273,23 +400,25 @@ export function analyzeTestLayers(cwd?: string): TestLayerReport {
     integrationTests: byLayer('integration'),
     e2eTests: byLayer('e2e'),
     unpairedSources,
+    outOfScopeSources,
+    shellSuites: shellOutsideSrc,
     pairedCount,
   };
-  const totalNeedingTests = sourceFiles.filter(f => !isExempt(path.basename(f))).length;
+  const totalNeedingTests = sourceFiles.filter(f => !isExempt(path.basename(f)) && !isPairingOutOfScope(f)).length;
 
   return {
-    summary: {
-      totalSources: sourceFiles.length,
-      totalTests: testFiles.length,
-      unitTests: counts.unitTests.length,
-      integrationTests: counts.integrationTests.length,
-      e2eTests: counts.e2eTests.length,
-    },
+    summary: buildSummary(counts, shellOutsideSrc),
     layer1: {
       pairedSources: pairedCount,
       unpairedSources,
+      outOfScopeSources,
       pairRate: totalNeedingTests > 0 ? Math.round((pairedCount / totalNeedingTests) * 100) : 100,
     },
+    shellSuites: {
+      total: shellOutsideSrc.length,
+      bats: shellOutsideSrc.filter(f => f.endsWith('.test.bats') || f.endsWith('.bats')).length,
+      files: shellOutsideSrc,
+    },
     layer2: {
       integrationFiles: counts.integrationTests.length,
     },

package/lib/__tests__/flaky.test.js

@@ -0,0 +1,128 @@
+/**
+ * @test REQ-603 Flaky 测试治理：首过率度量、重试上限、隔离台账
+ * @intent 指南 §11「Flaky 测试治理」整章空白：无重试上限、无首过率/重跑率度量、
+ *         无隔离台账与到期机制。`xp-gate retro` 只统计 rework rate 和 gate pass rate，
+ *         回答不了「我们的测试稳不稳」。
+ *
+ *         这个缺口有一个具体的代价：**不稳定的测试会被当成产品缺陷去修**。
+ *         一个失败-run 如果只是抖动，开发者花在"修"它上面的时间全是浪费；
+ *         而如果它是真的，把它当抖动重跑就是漏网。两条路都错在同一个地方——
+ *         我们没有任何数据区分这两者。
+ *
+ *         三个设计决定：
+ *
+ *         1. **重跑成功不计入首过率。** 这是整个度量的立身之本。如果 `passed: true`
+ *            不管是不是重跑得来的都算通过，首过率永远是 100%，度量就没有意义。
+ *            记录必须显式携带 `attempt`，否则"重跑后通过"和"一次通过"在数据上
+ *            无法区分——而这两者正是要区分的全部。
+ *
+ *         2. **重试必须有上限，且默认极小（1 次）。** 无上限重试等于把门禁变成
+ *            "多试几次总会有一次过"，那是退让而不是治理。上限的作用是让抖动
+ *            暴露出来，而不是让它消失。
+ *
+ *         3. **隔离台账必须有到期。** 没有到期的隔离就是永久删除（只是看起来还在）。
+ *            这条和 #608 的 escape valve 同一条教训：没有失效机制的安全阀，
+ *            一年后就成了常态。
+ * @covers AC-603-01, AC-603-02, AC-603-03, AC-603-04
+ */
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { computeFlakyStats, parseQuarantine, findExpiredQuarantine, MAX_RETRIES } = require('../flaky');
+
+function rec(overrides) {
+  return {
+    commit_hash: 'deadbeef',
+    duration_ms: 1000,
+    gate_id: '5',
+    gate_name: 'Tests + Coverage',
+    issues_found: 0,
+    passed: true,
+    repo_path: '/repo',
+    timestamp: '2026-10-30T00:00:00Z',
+    trigger: 'pre-commit',
+    ...overrides,
+  };
+}
+
+describe('flaky 测试治理 (#603)', () => {
+  it('AC-603-01: 重跑后通过不计入首过率', () => {
+    const stats = computeFlakyStats([
+      rec({ passed: true, attempt: 1 }),
+      rec({ passed: false, attempt: 1 }),
+      rec({ passed: true, attempt: 2, previously_failed: true }),
+      rec({ passed: true, attempt: 1 }),
+    ]);
+    // 4 个 gate 运行，其中 3 个是首次尝试（1 过 1 失 1 过 —— 第 4 条也是首次）。
+    // 首过率 = 首过数 / 首次尝试数。重跑成功那一条既不算首过，也不算首次尝试。
+    expect(stats.firstAttempts).toBe(3);
+    expect(stats.firstPasses).toBe(2);
+    expect(stats.firstPassRate).toBeCloseTo(66.7, 1);
+    // 重跑成功被单独计量——这正是需要被看见的那一类。
+    // 分母是全部运行（3 次首次 + 1 次重跑 = 4），所以 1/4 = 25%。
+    expect(stats.flakyRecoveries).toBe(1);
+    expect(stats.flakyRate).toBeCloseTo(25, 1);
+  });
+
+  it('AC-603-02: 没有重跑记录时 flakyRate 为 null 而非 0（不可测量≠零抖动）', () => {
+    // 一个从没记录过重跑的 journal 说明不了"测试很稳"，只能说明"没度量"。
+    // 报 0 会让读者以为已经量过而且是好的——和 #651 的 NOT MEASURABLE 同一条教训。
+    const stats = computeFlakyStats([rec({ passed: true, attempt: 1 })]);
+    expect(stats.flakyRate).toBeNull();
+    expect(stats.measurable).toBe(false);
+    expect(stats.reason).toBeTruthy();
+  });
+
+  it('AC-603-03: 重试上限有硬上限，配置不能无限放大', () => {
+    // 无上限重试等于把门禁变成"多试几次总会有一次过"。
+    expect(MAX_RETRIES).toBeGreaterThan(0);
+    expect(MAX_RETRIES).toBeLessThanOrEqual(5);
+    const { resolveMaxRetries } = require('../flaky');
+    expect(resolveMaxRetries(undefined)).toBe(1);
+    expect(resolveMaxRetries('0')).toBe(0);
+    expect(resolveMaxRetries('99')).toBe(MAX_RETRIES);
+    expect(resolveMaxRetries('-3')).toBe(0);
+  });
+
+  it('AC-603-04: 隔离台账解析出到期项，逾期必须被查出且核心链路不得长期隔离', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'flaky-'));
+    const file = path.join(dir, '.flaky-quarantine.yaml');
+    fs.writeFileSync(file, [
+      'quarantined:',
+      '  - test: "src/a.test.ts > flaky one"',
+      '    owner: alice',
+      '    issue: 601',
+      '    expiry: 2026-01-01',
+      '    reason: "timing-dependent assertion"',
+      '  - test: "src/b.test.ts > ok one"',
+      '    owner: bob',
+      '    issue: 602',
+      '    expiry: 2099-01-01',
+      '    reason: "upstream bug"',
+      '  - test: "src/c.test.ts > critical"',
+      '    owner: carol',
+      '    issue: 603',
+      '    expiry: 2099-01-01',
+      '    reason: "known"',
+      '    critical_path: true',
+      '',
+    ].join('\n'));
+    const entries = parseQuarantine(file);
+    expect(entries).toHaveLength(3);
+    expect(entries[0].owner).toBe('alice');
+
+    const expired = findExpiredQuarantine(entries, new Date('2026-06-01T00:00:00Z'));
+    expect(expired.map((e) => e.owner)).toEqual(['alice']);
+
+    const { findPolicyViolations } = require('../flaky');
+    // A critical-path test may not sit in quarantine past its expiry either --
+    // that is the whole point of marking it critical.
+    const violations = findPolicyViolations(entries, new Date('2026-06-01T00:00:00Z'));
+    const owners = violations.map((v) => v.entry.owner);
+    expect(owners).toContain('alice');
+    expect(owners).toContain('carol');
+    expect(owners).not.toContain('bob');
+  });
+});

package/lib/doctor.js

@@ -26,6 +26,7 @@ const { GATE_CLI_TOOLS, checkCliTool, getToolInstallCmd, checkBash } = require('
 // generated shell projection of this same module.
 const { RESOLUTION_ORDER } = require('./hook-module-resolution.js');
 const { inspectHookFile } = require('./hook-health.js');
+const { parseQuarantine, findPolicyViolations } = require('./flaky.js');
 
 /**
  * Files above this size get a `bash -n` probe in addition to the CRLF scan.
@@ -830,6 +831,48 @@ function diagnoseAuditLedger(ctx = {}) {
   return { checks, issues };
 }
 
+/**
+ * Check the flaky-test quarantine ledger for expired entries (#603).
+ *
+ * This lives in doctor rather than in the gate path on purpose: an expired
+ * quarantine is not a code defect, it is a decision that was never revisited.
+ * Nothing fails, everything keeps running, and a test meant to be fixed within
+ * two weeks quietly stays disabled for a year. That is exactly the class of drift
+ * doctor exists to surface, and exactly the class no gate can block.
+ */
+function diagnoseFlakyQuarantine(ctx = {}) {
+  const checks = [];
+  let issues = 0;
+  const root = ctx.repoRoot || process.cwd();
+  let entries = [];
+  try {
+    entries = parseQuarantine(path.join(root, '.flaky-quarantine.yaml'));
+  } catch {
+    return { checks, issues };
+  }
+  // No ledger is PASS, not SKIP: a project that quarantines nothing is genuinely
+  // in good shape, and SKIP would imply the check had not been performed.
+  if (entries.length === 0) {
+    checks.push({ name: 'Flaky quarantine', status: 'PASS', detail: 'no quarantined tests' });
+    return { checks, issues };
+  }
+  const violations = findPolicyViolations(entries, new Date());
+  if (violations.length === 0) {
+    checks.push({
+      name: 'Flaky quarantine',
+      status: 'PASS',
+      detail: `${entries.length} quarantined test(s), all within expiry`,
+    });
+    return { checks, issues };
+  }
+  issues += violations.length;
+  const detail = violations
+    .map((v) => `${v.rule}: ${v.entry.test} (owner ${v.entry.owner || 'unassigned'}, expiry ${v.entry.expiry || 'none'})`)
+    .join('; ');
+  checks.push({ name: 'Flaky quarantine', status: 'WARN', detail });
+  return { checks, issues };
+}
+
 function diagnoseModuleDrift(ctx = {}) {
   const checks = [];
   let issues = 0;
@@ -3020,6 +3063,19 @@ async function doctor(args) {
     issues += hookDrift.issues + moduleDrift.issues;
   }
 
+  // Flaky-test quarantine expiry (#603). A WARN, not a FAIL: an overdue ledger
+  // breaks nothing at runtime, it only means an intentional gap outlived its
+  // intent -- doctor's business, not a gate's.
+  try {
+    const flaky = diagnoseFlakyQuarantine({ repoRoot: process.cwd() });
+    checks.push(...flaky.checks);
+    issues += flaky.issues;
+  } catch (err) {
+    // Surface the cause: a bare "could not be read" hid the real error and made
+    // this look like a missing file rather than a bug in the check itself.
+    checks.push({ name: 'Flaky quarantine', status: 'SKIP', detail: `ledger check failed: ${err && err.message ? err.message : String(err)}` });
+  }
+
   let langIssues = 0;
   // Upgrade + plugin + language-tool status, kept as one callable because a
   // --format json run still has to execute all of it (#488).

package/lib/flaky.js

@@ -0,0 +1,208 @@
+/**
+ * Flaky-test governance (#603).
+ *
+ * The gap this closes: a flaky test and a genuine failure look identical in the
+ * gate journal, so one of two wrong things happens — the flake gets treated as a
+ * product bug and someone spends a day "fixing" nothing, or the real failure gets
+ * re-run until it passes and slips through. Both are consequences of having no
+ * data that separates the two.
+ *
+ * Three rules, each earned from a specific failure mode:
+ *
+ * 1. A re-run that passes does NOT count as a first pass. If `passed: true` counted
+ *    the same regardless of how it was obtained, first-pass rate would be
+ *    permanently 100% and the metric would measure nothing.
+ * 2. Retries are capped, and the default is tiny. Unlimited retries turn a gate
+ *    into "eventually something passes", which is a concession rather than
+ *    governance.
+ * 3. Quarantine entries expire. An entry with no expiry is a permanent deletion
+ *    that merely still looks present.
+ *
+ * No runtime dependencies: this ships inside the zero-install package.
+ */
+'use strict';
+
+const fs = require('node:fs');
+
+/**
+ * Hard ceiling on retries. Config may lower this but never raise it: the cap
+ * exists so flakiness surfaces rather than being retried away.
+ */
+const MAX_RETRIES = 3;
+
+/** Only schedule YAML is needed, so a tiny parser beats a dependency here. */
+const FIELD_RE = /^\s*-\s+test:\s*(.+?)\s*$/
+const KV_RE = /^\s+([A-Za-z_][\w]*):\s*(.*?)\s*$/
+
+function stripQuotes(value) {
+  if (value.length >= 2) {
+    const first = value[0]
+    const last = value[value.length - 1]
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1)
+    }
+  }
+  return value
+}
+
+/**
+ * Parse `.flaky-quarantine.yaml`.
+ *
+ * Returns `[]` for a missing file: no ledger is not an error, it just means
+ * nothing is quarantined. A malformed entry is skipped rather than throwing —
+ * a broken ledger must not take down `doctor`.
+ *
+ * @param {string} filePath
+ * @returns {Array<object>}
+ */
+function parseQuarantine(filePath) {
+  let text
+  try {
+    text = fs.readFileSync(filePath, 'utf8')
+  } catch {
+    return []
+  }
+  const entries = []
+  let current = null
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+$/, '')
+    if (line === '' || line.startsWith('#')) continue
+    const start = FIELD_RE.exec(line)
+    if (start) {
+      if (current) entries.push(current)
+      current = { test: stripQuotes(start[1]) }
+      continue
+    }
+    if (!current) continue
+    const kv = KV_RE.exec(line)
+    if (!kv) continue
+    const key = kv[1]
+    const value = stripQuotes(kv[2])
+    if (key === 'critical_path') {
+      current.critical_path = value === 'true'
+    } else {
+      current[key] = value
+    }
+  }
+  if (current) entries.push(current)
+  return entries
+}
+
+/** Parse an `YYYY-MM-DD` expiry into a UTC midnight Date, or null. */
+function parseExpiry(value) {
+  if (typeof value !== 'string') return null
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value.trim())
+  if (!m) return null
+  const date = new Date(`${m[1]}-${m[2]}-${m[3]}T00:00:00Z`)
+  return Number.isNaN(date.getTime()) ? null : date
+}
+
+/** Entries whose expiry has passed. An unparseable expiry counts as expired. */
+function findExpiredQuarantine(entries, now) {
+  const at = now || new Date()
+  return entries.filter((entry) => {
+    const expiry = parseExpiry(entry.expiry)
+    // No expiry at all is treated as expired: rule 3 says quarantine without an
+    // end date is a permanent deletion, so it must be reported, not tolerated.
+    if (expiry === null) return true
+    return expiry.getTime() < at.getTime()
+  })
+}
+
+/**
+ * Policy violations across the ledger.
+ *
+ * Two distinct rules are reported separately because they need different
+ * responses: an expired entry is routine bookkeeping, whereas a critical-path
+ * entry is a decision someone has to make — a critical path that has been flaky
+ * for months means the team has stopped trusting its own safety net.
+ */
+function findPolicyViolations(entries, now) {
+  const at = now || new Date()
+  const violations = []
+  for (const entry of findExpiredQuarantine(entries, at)) {
+    violations.push({ rule: 'expired', entry })
+  }
+  for (const entry of entries) {
+    if (entry.critical_path && !violations.some((v) => v.entry === entry)) {
+      violations.push({ rule: 'critical-path-quarantined', entry })
+    }
+  }
+  return violations
+}
+
+/**
+ * Resolve the retry budget from configuration.
+ *
+ * Clamped, not validated-with-an-error: a bad value must not make the gate
+ * unusable, and the direction of clamping always favours surfacing flakiness.
+ */
+function resolveMaxRetries(value) {
+  if (value === undefined || value === null || value === '') return 1
+  const parsed = Number.parseInt(String(value), 10)
+  if (Number.isNaN(parsed)) return 1
+  if (parsed < 0) return 0
+  return Math.min(parsed, MAX_RETRIES)
+}
+
+/** Round to one decimal place without trailing `.0`. */
+function pct(part, whole) {
+  if (whole === 0) return null
+  return Math.round((part / whole) * 1000) / 10
+}
+
+/**
+ * Compute first-pass and flaky statistics from gate-journal entries.
+ *
+ * Records carry `attempt` (1-based). A record with `attempt > 1` is a re-run and
+ * is excluded from the first-attempt denominator — that exclusion IS the metric.
+ */
+function computeFlakyStats(entries) {
+  const rows = Array.isArray(entries) ? entries : []
+  let firstAttempts = 0
+  let firstPasses = 0
+  let flakyRecoveries = 0
+  let reruns = 0
+  let quarantined = 0
+
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') continue
+    if (row.quarantined === true) quarantined += 1
+    const attempt = Number.isFinite(row.attempt) ? row.attempt : 1
+    if (attempt > 1) {
+      reruns += 1
+      if (row.passed === true) flakyRecoveries += 1
+      continue
+    }
+    firstAttempts += 1
+    if (row.passed === true) firstPasses += 1
+  }
+
+  const measurable = reruns > 0
+  return {
+    totalRuns: rows.length,
+    firstAttempts,
+    firstPasses,
+    firstPassRate: pct(firstPasses, firstAttempts),
+    reruns,
+    flakyRecoveries,
+    quarantined,
+    // Without any re-run there is no evidence either way. Reporting 0 here would
+    // claim "measured, and stable" from data that only says "not measured".
+    flakyRate: measurable ? pct(flakyRecoveries, firstAttempts + reruns) : null,
+    measurable,
+    reason: measurable
+      ? null
+      : 'no re-run records in the journal — flakiness is unmeasured, not zero',
+  }
+}
+
+module.exports = {
+  MAX_RETRIES,
+  parseQuarantine,
+  parseExpiry,
+  findExpiredQuarantine,
+  findPolicyViolations,
+  resolveMaxRetries,
+  computeFlakyStats,
+}

package/lib/gate-audit.ts

@@ -47,6 +47,17 @@ export interface GateAuditEntry {
    * one that drives fixes. Only meaningful when passed=false.
    */
   failure_reason?: string;
+  /**
+   * Which attempt this record represents, 1-based (#603).
+   *
+   * Absent means 1 — older records predate re-run tracking. This field is what
+   * makes first-pass rate computable: without it, "passed" cannot distinguish a
+   * clean run from one that only passed after a re-run, and a metric that cannot
+   * tell those apart is always 100%.
+   */
+  attempt?: number;
+  /** True when this row describes a test that is quarantined as flaky (#603). */
+  quarantined?: boolean;
 }
 
 // ── Public API ───────────────────────────────────────────────────────────────
@@ -423,6 +434,10 @@ function runCli(): void {
       ...(opts['detail'] ? { detail: opts['detail'] } : {}),
       // #651: only set when provided, so successful records stay byte-identical.
       ...(opts['failure-reason'] ? { failure_reason: String(opts['failure-reason']).slice(0, 300) } : {}),
+      // #603: only set when provided, so single-attempt records stay byte-identical
+      // to what earlier versions wrote.
+      ...(opts['attempt'] ? { attempt: Number.parseInt(String(opts['attempt']), 10) || 1 } : {}),
+      ...(opts['quarantined'] === 'true' ? { quarantined: true } : {}),
     };
     // Pre-commit (trigger=commit) is staging for a commit that does not exist
     // yet: park it in the pending sidecar so post-commit can stamp the real