canary-test-cli 7.1.0 → 8.0.0

package/dist/engine/guardian/cli.js

@@ -19,9 +19,9 @@
  *     test never terminates the process.
  *
  * Command surface (kebab-case names; the first seven match the shipping Typer
- * CLI, the last two are TS-native additions for #490):
+ * CLI, the last is a TS-native addition, derived per ADR 0025):
  *   analyze | validate-coverage | harden-gate | pr-check | author-plan |
- *   mark-authored | watch | collect-adjudications | precision.
+ *   mark-authored | watch | precision.
  *
  * Python->TS nuances honored:
  *   - `json.dumps(obj, indent=2)` -> `ensureAscii(JSON.stringify(obj, null, 2))`
@@ -50,16 +50,18 @@ import { Command, Option } from 'commander';
 import { load as loadYaml } from 'js-yaml';
 import pc from 'picocolors';
 import { AuthoringContext, InSessionAgentProbe, InSessionAgentTier, decideBlock, } from './agent-tier.js';
-import { RestReactionsClient, collectAdjudications, loadAdjudicationRecords, renderPrecision, summarizePrecision, } from './adjudication.js';
+import { deriveReport, renderReport } from './adjudication.js';
+import { GitHubAdjudicationSource, collectEvidence, } from './adjudication-github.js';
 import { emitAnalysis } from './analysis-emit.js';
-import { gateOutcome } from '../core/gate-result.js';
-import { coverageDegradedNotice, resolveCoverage, resolveCoverageWithInput, validateCoverageJson, } from './coverage.js';
+import { EXIT_ABSTAINED, gateOutcome, } from '../core/gate-result.js';
+import { coverageDegradedNotice, coverageDeltaNotice, isSourcePath, resolveCoverage, resolveCoverageDelta, resolveCoverageWithInput, validateCoverageJson, } from './coverage.js';
 import { buildApiDelta, writeApiDelta } from './delta-emitter.js';
 import { extractApiDiff } from './diff-extractor.js';
 import { HardGateAbstained, HardGateBlocked, RestBranchProtectionClient, applyHardGate, renderPlaybook, } from './hard-gate.js';
 import { mapImpact } from './impact-mapper.js';
 import { ensureAscii } from '../util/ensure-ascii.js';
-import { applySuppressions, buildFindings, buildWeakTestFindings, computeExitCode, effectiveGraphDepth, filterHeuristicNoise, filterSkipped, filterTestSupportUnits, filterTestUnits, filterTypeOnlyUnits, findReexportOnly, loadGuardianConfig, renderFindings, scopeDiff, } from './pr-check.js';
+import { MERGE_REF_WARNING, provenanceLine, applySuppressions, buildFindings, buildRegressionFindings, computeExitCode, effectiveGraphDepth, filterHeuristicNoise, filterSkipped, filterTestSupportUnits, filterTestUnits, filterTypeOnlyUnits, findReexportOnly, isCoverageAbstention, loadGuardianConfig, renderFindings, scopeDiff, } from './pr-check.js';
+import { buildWeakTestFindings } from './weak-test.js';
 import { RestGitHubClient, degradationAnnotation, upsertStickyComment, } from './pr-comment.js';
 import { buildSummary } from './summary-emitter.js';
 import { resolveTier } from './tier.js';
@@ -101,6 +103,33 @@ export class WatchInterruptError extends Error {
         this.name = 'WatchInterruptError';
     }
 }
+/** Run `git`; `null` when the binary is missing (Python OSError fail-safe). */
+function spawnGit(args, cwd) {
+    const res = spawnSync('git', args, {
+        encoding: 'utf-8',
+        maxBuffer: Infinity,
+        ...(cwd ? { cwd } : {}),
+    });
+    if (res.error)
+        return null;
+    return { code: res.status ?? 1, stdout: res.stdout ?? '' };
+}
+/** Run `gh` with a 30s timeout; `failed` when it could not be spawned. */
+function spawnGh(args) {
+    const res = spawnSync('gh', args, {
+        encoding: 'utf-8',
+        timeout: 30_000,
+        maxBuffer: Infinity,
+    });
+    if (res.error)
+        return { status: null, stdout: '', stderr: '', failed: true };
+    return {
+        status: res.status,
+        stdout: res.stdout ?? '',
+        stderr: res.stderr ?? '',
+        failed: false,
+    };
+}
 /** Process-backed defaults for production (the `guardianCommand` export). */
 export function defaultDeps() {
     return {
@@ -116,34 +145,10 @@ export function defaultDeps() {
         },
         env: process.env,
         cwd: () => process.cwd(),
-        runGit: (args, cwd) => {
-            const res = spawnSync('git', args, {
-                encoding: 'utf-8',
-                maxBuffer: Infinity,
-                ...(cwd ? { cwd } : {}),
-            });
-            if (res.error)
-                return null; // missing binary -> Python OSError fail-safe
-            return { code: res.status ?? 1, stdout: res.stdout ?? '' };
-        },
-        runGh: (args) => {
-            const res = spawnSync('gh', args, {
-                encoding: 'utf-8',
-                timeout: 30_000,
-                maxBuffer: Infinity,
-            });
-            if (res.error) {
-                return { status: null, stdout: '', stderr: '', failed: true };
-            }
-            return {
-                status: res.status,
-                stdout: res.stdout ?? '',
-                stderr: res.stderr ?? '',
-                failed: false,
-            };
-        },
+        runGit: spawnGit,
+        runGh: spawnGh,
         buildCommentClient: (repo, prNumber) => new RestGitHubClient(repo, prNumber, process.env['GITHUB_TOKEN'] ?? ''),
-        buildReactionsClient: (repo, prNumber) => new RestReactionsClient(repo, prNumber, process.env['GITHUB_TOKEN'] ?? ''),
+        buildAdjudicationSource: (repo, token) => new GitHubAdjudicationSource(repo, token),
         buildBranchProtectionClient: (repo, token) => new RestBranchProtectionClient(repo, token),
         makeAgentTier: () => new InSessionAgentTier(),
         sleep: (secs) => new Promise((resolve) => setTimeout(resolve, secs * 1000)),
@@ -320,20 +325,9 @@ function headSha(deps, root) {
     return res.stdout.trim().toLowerCase() || null;
 }
 /**
- * Is the loop guard live -- i.e. does a sentinel stamped at the CURRENT `HEAD`
- * exist?
- *
- * This is the surviving half of the stage-and-block-once contract (#456). The
- * component that CLEARED the sentinel on the next commit
- * (`hooks/guardian_precommit.py`) was deleted as dead code in #449, which left
- * `author-plan` fail-closed forever: author once in a clone and Tier-2 authoring
- * never ran again. Stamping HEAD makes the guard self-expiring -- once the human
- * reviews and commits the staged tests, `HEAD` moves, the stamp stops matching,
- * and authoring re-enables itself with no manual step and no hook.
- *
- * Every unverifiable state FAILS OPEN (returns `false`, authoring allowed):
- * missing or unreadable sentinel, a malformed/absent `HEAD` header, or a `HEAD`
- * we cannot resolve. Fail-closed here is exactly the bug being fixed.
+ * Is the loop guard live, i.e. is the sentinel stamped at the CURRENT `HEAD`
+ * (#456)? Stamping HEAD makes the guard self-expiring once the staged tests are
+ * committed. Every unverifiable state FAILS OPEN (returns `false`).
  */
 function authoredSentinelActive(deps, root) {
     let body;
@@ -374,6 +368,71 @@ function readWorktreeDiff(deps) {
         return unstaged;
     return deps.runGit(['diff', '--staged'])?.stdout ?? '';
 }
+/**
+ * The PR head sha the CI event declares, if this is a `pull_request` event.
+ *
+ * Distinct from {@link eventBaseSha}: that answers "what are we diffing
+ * against", this answers "what SHOULD the diffed HEAD be". They are compared in
+ * {@link detectMergeRef} (#761).
+ */
+function eventHeadSha(env) {
+    const eventPath = env['GITHUB_EVENT_PATH'];
+    if (!eventPath)
+        return null;
+    let sha;
+    try {
+        const event = JSON.parse(readFileSync(eventPath, 'utf-8'));
+        sha = event?.pull_request?.head?.sha;
+    }
+    catch {
+        return null;
+    }
+    return typeof sha === 'string' && sha.trim() ? sha.trim() : null;
+}
+/** Resolve `HEAD` to a full sha, or null when git cannot answer. */
+function resolveHeadSha(deps) {
+    const res = deps.runGit(['rev-parse', 'HEAD']);
+    if (res === null || res.code !== 0)
+        return null;
+    const sha = res.stdout.trim();
+    return sha || null;
+}
+/**
+ * True when HEAD is a `pull_request` MERGE REF, not the PR head (#761): a diff
+ * to `refs/pull/<n>/merge` sweeps in every commit merged into base since the
+ * base sha (a one-file PR read as 43 files). A comparison against the event's
+ * PR head sha, false whenever either side is unknown.
+ */
+export function detectMergeRef(headSha, deps) {
+    if (deps.env['GITHUB_EVENT_NAME'] !== 'pull_request')
+        return false;
+    const declared = eventHeadSha(deps.env);
+    if (!declared || !headSha)
+        return false;
+    return declared !== headSha;
+}
+/**
+ * The event-declared PR head, when it resolves to a local commit (#883).
+ *
+ * Diffing to it instead of `HEAD` judges the PR's own changes rather than the
+ * merge ref's widened set. Null outside a `pull_request` event or when the sha
+ * was not fetched (a shallow checkout) — the caller then diffs to `HEAD` and
+ * {@link detectMergeRef} still discloses the widening.
+ */
+function resolvePrHead(deps) {
+    if (deps.env['GITHUB_EVENT_NAME'] !== 'pull_request')
+        return null;
+    const sha = eventHeadSha(deps.env);
+    if (!sha)
+        return null;
+    const res = deps.runGit([
+        'rev-parse',
+        '--verify',
+        '--quiet',
+        `${sha}^{commit}`,
+    ]);
+    return res !== null && res.code === 0 ? sha : null;
+}
 /** True when the process looks like a CI runner rather than a dev worktree. */
 function isCiContext(env) {
     return Boolean(env['GITHUB_ACTIONS'] || env['CI']);
@@ -438,19 +497,9 @@ function resolveBaseRev(deps) {
     return null;
 }
 /**
- * Resolve the diff `pr-check` should scope, preferring the PR diff in CI (#369).
- *
- * An explicit `--diff` (stdin or file) always wins and never shells out. With
- * `--diff` omitted:
- *
- *   - **In CI** with a resolvable base rev → `git diff <base>...HEAD`. The
- *     TRIPLE-dot form diffs against the merge base, so commits that land on the
- *     base branch mid-PR never appear as part of this PR's changed surface.
- *   - **Otherwise** → the at-desk working-tree diff ({@link readWorktreeDiff}).
- *
- * The legacy behavior was the working-tree diff unconditionally, which is empty
- * on a clean CI checkout — the gate then scoped zero paths and exited 0, so an
- * adopting repo could not tell a working gate from a broken one.
+ * Resolve the diff `pr-check` should scope (#369). An explicit `--diff` wins;
+ * in CI with a base rev it is `git diff <base>...HEAD` (merge base, so commits
+ * landing on base mid-PR stay out); otherwise the working-tree diff.
  */
 export function readPrDiff(source, deps) {
     if (source === '-') {
@@ -462,14 +511,20 @@ export function readPrDiff(source, deps) {
     if (isCiContext(deps.env)) {
         const base = resolveBaseRev(deps);
         if (base !== null) {
-            const res = deps.runGit(['diff', `${base}...HEAD`]);
+            const head = resolvePrHead(deps);
+            const res = deps.runGit(['diff', `${base}...${head ?? 'HEAD'}`]);
             if (res !== null && res.code === 0) {
-                return { text: res.stdout, origin: 'ci-base', base };
+                return { text: res.stdout, origin: 'ci-base', base, head };
             }
         }
     }
     return { text: readWorktreeDiff(deps), origin: 'worktree', base: null };
 }
+// Built from the shared fragment so the annotation and the rendered provenance
+// line cannot drift into describing the same defect two different ways (#761).
+const MERGE_REF_NOTICE = `guardian: ${MERGE_REF_WARNING} — findings may name files this PR never ` +
+    'touched. Check out with `ref: ${{ github.event.pull_request.head.sha }}`, ' +
+    'or diff to that sha instead of HEAD.';
 const EMPTY_CI_DIFF_NOTICE = 'guardian: 0 changed paths — fell back to a working-tree `git diff`, which ' +
     'is empty on a clean CI checkout, so NOTHING was verified. Pass ' +
     '`--diff <base>...<head>`, or checkout with `fetch-depth: 0` so the PR base ' +
@@ -682,20 +737,6 @@ function validateCoverageCmd(path, opts, deps) {
         throw new CliExitError(1);
     }
 }
-/**
- * Print the precision evidence the promotion contract depends on (#490).
- *
- * The soft→hard promotion is earned by reviewer adjudication feeding
- * `precision = TP / (TP + FP)`; before #490 that contract lived only in a
- * comment with nothing feeding it. This surfaces the measured number — or an
- * honest `unknown` over an empty sample — in the readiness output. Advisory:
- * it informs the operator's decision, it does not block the registration.
- */
-function reportPrecisionEvidence(analysesDir, deps) {
-    const summary = summarizePrecision(loadAdjudicationRecords(analysesDir));
-    const line = renderPrecision(summary);
-    deps.out(summary.precision === null ? pc.yellow(line) : line);
-}
 async function hardenGateCmd(opts, deps) {
     const repo = opts.repo;
     if (!repo) {
@@ -703,8 +744,9 @@ async function hardenGateCmd(opts, deps) {
         throw new CliExitError(2);
     }
     const playbook = renderPlaybook(repo, opts.branch, opts.check);
-    // #490: the readiness evidence the promotion is supposed to rest on.
-    reportPrecisionEvidence(resolveAnalysesDir(opts.analysesDir, deps), deps);
+    // ADR 0025: precision is derived from merged PRs, not stored locally.
+    deps.out(pc.yellow(`guardian precision: not measured here ${EM_DASH} run ` +
+        '`canary guardian precision` (or the weekly Guardian precision workflow).'));
     if (!opts.apply) {
         deps.out(`${pc.bold('Dry run')} ${EM_DASH} would require the '${opts.check}' check on ${repo}@${opts.branch}.`);
         deps.out('On --apply this merges into existing protection (or creates minimal ' +
@@ -755,65 +797,26 @@ async function hardenGateCmd(opts, deps) {
         '(or run pr-check --gate hard).'));
 }
 /**
- * Explicit adjudication sweep for one PR (the scheduled-sweep / at-desk shape;
- * `pr-check` runs the same collection inline on its CI surfaces). Unlike the
- * inline best-effort path this one FAILS LOUDLY (exit 1 on an unavailable
- * channel) — an operator who asked for a collection must know it did not land.
+ * Derive guardian precision from merged PRs on demand (ADR 0025): the sticky's
+ * first vs last revision, the merged diff's suppressions, and nothing stored.
+ * Exits 2 without a repo or token rather than reporting an empty sample.
  */
-async function collectAdjudicationsCmd(opts, deps) {
-    let repo = opts.repo;
-    let prNumber = opts.pr;
-    if (!repo || prNumber === undefined) {
-        const ctx = prContextFromEnv(deps.env);
-        if (ctx !== null) {
-            repo = repo ?? ctx[0];
-            prNumber = prNumber ?? ctx[1];
-        }
-    }
-    if (!repo || prNumber === undefined) {
-        deps.out(`${pc.red(pc.bold(`${CROSS} no PR context`))} ${EM_DASH} pass --repo and --pr, or run in Actions.`);
+async function precisionCmd(opts, deps) {
+    const token = deps.env['GITHUB_TOKEN'];
+    if (!opts.repo || !token) {
+        deps.out(`${pc.red(pc.bold(`${CROSS} precision needs --repo and GITHUB_TOKEN`))} ` +
+            `${EM_DASH} nothing was measured.`);
         throw new CliExitError(2);
     }
-    const client = deps.buildReactionsClient(repo, prNumber);
-    const res = await collectAdjudications(client, {
-        repo,
-        prNumber,
-        analysesDir: resolveAnalysesDir(opts.analysesDir, deps),
-    });
-    if (opts.json) {
-        deps.out(ensureAscii(JSON.stringify({ action: res.action, path: res.path, record: res.record }, null, 2)));
-    }
-    else if (res.action === 'collected' && res.record) {
-        deps.out(pc.green(`${CHECK} adjudication recorded (${res.record.tp} up / ` +
-            `${res.record.fp} down, ${res.record.granularity}-level) ` +
-            `${RIGHT_ARROW} ${res.path}`));
-    }
-    else if (res.action === 'no-comment') {
-        deps.out(`guardian: no sticky comment on ${repo}#${prNumber} ${EM_DASH} nothing to adjudicate.`);
-    }
-    else if (res.action === 'no-reactions') {
-        deps.out(`guardian: sticky comment on ${repo}#${prNumber} has no reviewer ` +
-            `verdicts yet ${EM_DASH} nothing recorded (no reaction is neutral, ` +
-            `not a data point).`);
-    }
-    if (res.action === 'unavailable') {
-        deps.out(pc.red(pc.bold(`${CROSS} ${res.notice ?? 'not persisted'}`)));
-        throw new CliExitError(1);
-    }
-}
-/** Aggregate the persisted adjudications into the promotion evidence (#490). */
-function precisionCmd(opts, deps) {
-    const analysesDir = resolveAnalysesDir(opts.analysesDir, deps);
-    const records = loadAdjudicationRecords(analysesDir);
-    const summary = summarizePrecision(records);
-    if (opts.json) {
-        // `precision: null` is the honest zero-denominator value — consumers must
-        // treat it as unknown, never as 1.0 (#490).
-        deps.out(ensureAscii(JSON.stringify({ ...summary, records: records.length }, null, 2)));
-        return;
-    }
-    const line = renderPrecision(summary);
-    deps.out(summary.precision === null ? pc.yellow(line) : line);
+    const since = new Date(Date.now() - opts.days * 86_400_000)
+        .toISOString()
+        .slice(0, 10);
+    const source = deps.buildAdjudicationSource(opts.repo, token);
+    const { evidence, scanned } = await collectEvidence(source, since);
+    const report = deriveReport(evidence, scanned);
+    deps.out(opts.json
+        ? JSON.stringify({ since, ...report }, null, 2)
+        : `${renderReport(report)}\nwindow: merged since ${since}`);
 }
 // --- pr-check -----------------------------------------------------------------
 /**
@@ -836,11 +839,17 @@ async function postStickyComment(findings, resolution, deps, gateMeta = null) {
         appendStepSummary(deps.env, res.notice);
     }
 }
+/** An abstained run judged nothing, so no agent tier was ever in play. */
+const NO_TIER = {
+    requested: 0,
+    effective: 0,
+    degraded_notice: null,
+};
 /** The gate's no-op line, shared by the pre- and post-filter exits. */
 // D7: every filtered path stays visible as a SkipEntry, never folded
 // into "passed". One entry per path so the rendered count still equals
 // the path count the old `N path(s) skipped` line reported.
-function prCheckSkipEntries(skipped, testUnits, barrelUnits, supportUnits = [], typeOnlyUnits = []) {
+function prCheckSkipEntries(skipped, testUnits, barrelUnits, supportUnits = [], typeOnlyUnits = [], nonSourceUnits = []) {
     return [
         ...skipped.map((u) => ({ name: u.path, reason: 'skipGlobs' })),
         ...testUnits.map((u) => ({ name: u.path, reason: 'test path' })),
@@ -851,6 +860,8 @@ function prCheckSkipEntries(skipped, testUnits, barrelUnits, supportUnits = [],
         // #562: likewise distinct -- adjudication has to be able to measure this
         // class separately, since it is the one that held precision at 13/20.
         ...typeOnlyUnits.map((u) => ({ name: u.path, reason: 'type-only module' })),
+        // #928: config/data files, below the source floor.
+        ...nonSourceUnits.map((u) => ({ name: u.path, reason: 'non-source' })),
         ...barrelUnits.map((u) => ({
             name: u.path,
             reason: 're-export barrel',
@@ -876,21 +887,49 @@ const PR_CHECK_ABSTAIN_REMEDIATION = [
         'non-empty and skipGlobs/heuristicExclude are not filtering ' +
         'every path.',
 ];
-/** Exit 3 with the structural abstention line + remediation (#508). */
-function abstainPrCheck(skipped, format, deps) {
+/**
+ * Exit 3 with the structural abstention line + remediation (#508). Nothing was
+ * eligible (docs, tests, config), so under `--post-comment` it also upserts the
+ * ✅ "nothing to test" sticky and an earlier ⚠️ one cannot linger (#928).
+ */
+async function abstainPrCheck(skipped, opts, deps, provenance = null) {
     const outcome = gateOutcome({ checked: 0, findings: [], skipped }, 'gate', {
         noun: 'unit(s)',
     });
     deps.out(outcome.summaryLine);
+    // #761: state the range, so "correctly abstained" and "wrong diff" differ.
+    if (provenance)
+        deps.out(provenanceLine(provenance));
     for (const line of PR_CHECK_ABSTAIN_REMEDIATION)
         deps.out(line);
-    if (format === 'json') {
+    if (opts.postComment) {
+        const coverage = { requested: null, found: false, parsed: false };
+        await postStickyComment([], NO_TIER, deps, {
+            checked: 0,
+            abstained: false,
+            coverage: {
+                ...coverage,
+                filesInReport: 0,
+                unitsMatched: 0,
+                unitsTotal: 0,
+            },
+            skipped,
+            provenance,
+        });
+    }
+    if (opts.format === 'json') {
         deps.out(ensureAscii(JSON.stringify(
-        // #579: `skipped` carries the denominator the abstention collapsed
-        // to. Without it a consumer sees `abstained: true` and cannot tell
-        // WHAT was dropped or why -- the #508 class one layer down, on the
-        // only surface a machine can read.
-        { findings: [], tier: 0, checked: 0, abstained: true, skipped }, null, 2)));
+        // #579: `skipped` is the denominator the abstention collapsed to.
+        {
+            findings: [],
+            tier: 0,
+            checked: 0,
+            abstained: true,
+            skipped,
+            // #761: `null` when no diff was resolved -- never absent, so a
+            // reader can tell "not applicable" from "this producer is old".
+            provenance,
+        }, null, 2)));
     }
     throw new CliExitError(outcome.exitCode); // EXIT_ABSTAINED
 }
@@ -898,53 +937,6 @@ function abstainPrCheck(skipped, format, deps) {
 function resolveAnalysesDir(override, deps) {
     return override ?? join(gitToplevel(deps), '.harness', 'analyses');
 }
-/**
- * Collect 👍/👎 adjudications off the sticky comment, best-effort (#490).
- *
- * Runs on the NEXT `pr-check` for a PR (the collection loop the #490 sketch
- * chose over a scheduled sweep — the guardian already authenticates against
- * this API and already finds its own comment by marker). Read-only against
- * GitHub, so it works where the fork-degraded poster could not write.
- *
- * NEVER affects the gate: any failure prints a `::warning::` and returns —
- * a broken feedback loop must not turn a coverage gate red.
- */
-async function collectAdjudicationsBestEffort(analysesDirOverride, deps) {
-    const ctx = prContextFromEnv(deps.env);
-    if (ctx === null)
-        return; // no PR context — nothing to collect against
-    if (!deps.env['GITHUB_TOKEN']) {
-        // Every read here needs a token; skipping LOUDLY beats a guaranteed 401.
-        deps.out(degradationAnnotation(`guardian: no GITHUB_TOKEN ${EM_DASH} reviewer adjudications not ` +
-            'collected this run'));
-        return;
-    }
-    // Resolved lazily (shells out to git) only once a collection will happen —
-    // an explicit `--diff` run without PR context must stay subprocess-free.
-    const analysesDir = resolveAnalysesDir(analysesDirOverride, deps);
-    try {
-        const client = deps.buildReactionsClient(ctx[0], ctx[1]);
-        const res = await collectAdjudications(client, {
-            repo: ctx[0],
-            prNumber: ctx[1],
-            analysesDir,
-        });
-        if (res.action === 'collected' && res.record) {
-            deps.out(`guardian: adjudication recorded (${res.record.tp} up / ` +
-                `${res.record.fp} down) ${RIGHT_ARROW} ${res.path}`);
-        }
-        else if (res.action === 'unavailable' && res.notice) {
-            deps.out(degradationAnnotation(res.notice));
-        }
-        // no-comment / no-reactions: nothing to say — absence of a reaction is
-        // neutral, not a data point (#490).
-    }
-    catch (exc) {
-        const message = exc instanceof Error ? exc.message : String(exc);
-        deps.out(degradationAnnotation(`guardian: adjudication collection failed (${message}) ${EM_DASH} ` +
-            'findings and gate unaffected'));
-    }
-}
 async function prCheckCmd(opts, deps) {
     const [config, warning] = loadGuardianConfig(opts.config);
     if (warning !== null) {
@@ -958,18 +950,34 @@ async function prCheckCmd(opts, deps) {
         throw new CliExitError(0);
     }
     const effectiveGate = opts.gate ?? config.pr_gate;
-    // #490: read reviewer 👍/👎 off the PREVIOUS run's sticky comment before this
-    // run touches it. Runs on the posting/emitting (CI) surfaces only, before the
-    // early exits so a docs-only follow-up push still harvests the verdicts.
-    if (opts.postComment || opts.emitAnalysis) {
-        await collectAdjudicationsBestEffort(opts.analysesDir, deps);
-    }
     // #369: in CI an omitted `--diff` resolves the PR diff from the base ref;
     // the working-tree fallback is empty on a clean checkout.
     const resolvedDiff = readPrDiff(opts.diff ?? null, deps);
     const diffText = resolvedDiff.text;
     const units = scopeDiff(diffText);
     warnIfEmptyCiDiff(resolvedDiff, units.length, deps);
+    // #761: capture what the diff was taken between, BEFORE the skip/test/
+    // type-only filters run — `fileCount` is the size of the surface guardian was
+    // handed, which is the number a reviewer can check against their own PR.
+    // Populated even for an explicit `--diff` (where `base` is unknowable): the
+    // merge-ref warning and the file count are exactly what was missing on
+    // the consumer run that surfaced #761, which passed `--diff` from a file.
+    // #883: a diff taken to the PR head is the PR's own, so it is not widened.
+    const headSha = resolvedDiff.head ?? resolveHeadSha(deps);
+    const mergeRef = detectMergeRef(headSha, deps);
+    const provenance = {
+        base: resolvedDiff.base,
+        head: headSha,
+        origin: resolvedDiff.origin,
+        fileCount: units.length,
+        ...(mergeRef ? { mergeRef: true } : {}),
+    };
+    if (mergeRef) {
+        // Loud, because it invalidates every count downstream — but non-blocking:
+        // the caller owns the checkout, so guardian reports and carries on.
+        deps.err(degradationAnnotation(MERGE_REF_NOTICE));
+        appendStepSummary(deps.env, MERGE_REF_NOTICE);
+    }
     // SC-2: drop docs/config-only units matching skipGlobs.
     const [keptSkip, skipped] = filterSkipped(units, config.skip_globs);
     // FIX A: drop test-path units -- a test does not itself need a test.
@@ -985,22 +993,20 @@ async function prCheckCmd(opts, deps) {
     // FIX 2: drop pure re-export/barrel files.
     const reexportPaths = findReexportOnly(diffText);
     const barrelUnits = keptTyped.filter((u) => reexportPaths.has(u.path));
-    const kept = keptTyped.filter((u) => !reexportPaths.has(u.path));
+    const keptBarrel = keptTyped.filter((u) => !reexportPaths.has(u.path));
+    // #928: the heuristic tier's source floor (#413) applies to coverage units
+    // too; a config/data file can never match a coverage report.
+    const nonSourceUnits = keptBarrel.filter((u) => !isSourcePath(u.path));
+    const kept = keptBarrel.filter((u) => isSourcePath(u.path));
     // Advisory weak-test findings for added tests that assert nothing.
     const weakFindings = config.weak_tests
         ? buildWeakTestFindings(testUnits, diffText)
         : [];
-    // #582: build the skip list ONCE, above the abstain exit, so the surviving
-    // (non-abstain) path carries the same denominator the abstain payload has
-    // carried since #579. The heuristic-noise class is not known until the
-    // coverage ladder has run, so it is appended below rather than passed here.
-    //
-    // This supersedes a `preFilterSkipped` count that was computed at this point
-    // and read by nothing — the fossil of an earlier attempt to surface the same
-    // number on this path.
-    const preCoverageSkips = prCheckSkipEntries(skipped, testUnits, barrelUnits, supportUnits, typeOnlyUnits);
+    // #582: build the skip list ONCE, above the abstain exit, so both paths carry
+    // the same denominator; the heuristic-noise class is appended below.
+    const preCoverageSkips = prCheckSkipEntries(skipped, testUnits, barrelUnits, supportUnits, typeOnlyUnits, nonSourceUnits);
     if (kept.length === 0 && weakFindings.length === 0) {
-        abstainPrCheck(preCoverageSkips, opts.format, deps);
+        await abstainPrCheck(preCoverageSkips, opts, deps, provenance);
     }
     const { results, coverage } = resolveCoverageWithInput(kept, {
         coveragePath: opts.coverage ?? null,
@@ -1012,8 +1018,17 @@ async function prCheckCmd(opts, deps) {
     // never judge (non-source, or an excluded glob). Coverage/graph-verified
     // verdicts on the same paths are real evidence and survive.
     const [scoredResults, noiseResults] = filterHeuristicNoise(results, opts.heuristicExclude ?? config.heuristic_exclude);
+    // #606: the second coverage question — did coverage go DOWN on a unit this
+    // PR touches? Run over the same `kept` units the ladder scored, so the two
+    // denominators are the same surface. With no base artifact this returns no
+    // deltas and a state that says so, which the notice below reports loudly.
+    const { deltas, state: coverageDelta } = resolveCoverageDelta(kept, {
+        baseCoveragePath: opts.baseCoverage ?? null,
+        headCoveragePath: opts.coverage ?? null,
+    });
     const findings = [
         ...applySuppressions(buildFindings(scoredResults)),
+        ...buildRegressionFindings(deltas),
         ...weakFindings,
     ];
     // The complete skip list for this run: the pre-coverage filters plus the
@@ -1026,7 +1041,7 @@ async function prCheckCmd(opts, deps) {
     // SKIP rather than rendering an empty "0 unaddressed" report -- an adopter
     // must be able to tell "nothing was judgeable" from "everything passed".
     if (scoredResults.length === 0 && findings.length === 0) {
-        abstainPrCheck(allSkips, opts.format, deps);
+        await abstainPrCheck(allSkips, opts, deps, provenance);
     }
     // SC-5 (PR half): resolve the requested tier against actual capability. No
     // agent runtime exists (default NoAgentProbe), so any `pr.tier > 0` drops to
@@ -1036,27 +1051,49 @@ async function prCheckCmd(opts, deps) {
         deps.out(degradationAnnotation(resolution.degraded_notice));
         appendStepSummary(deps.env, resolution.degraded_notice);
     }
+    // #761: the run judged units but VERIFIED no coverage, and every finding is a
+    // naming guess. That is an abstention on the coverage denominator — a
+    // different test from the findings-eligible one the two `abstainPrCheck`
+    // calls above make, and the one that consumer run needed. It does not exit
+    // through `abstainPrCheck`: those findings are worth showing, so the run keeps
+    // every surface and changes only its headline and its exit code.
+    const coverageAbstained = isCoverageAbstention(coverage, findings);
     // Compute the gate result once, up front: the emitted record carries it and it
     // is the process exit at the end (SC-4 -- emit never changes the exit logic).
-    const exitCode = computeExitCode(findings, effectiveGate);
+    const exitCode = coverageAbstained
+        ? EXIT_ABSTAINED
+        : computeExitCode(findings, effectiveGate);
     // #554: every surface below carries the coverage-input state, so a run that
     // never saw a coverage report cannot present as one that checked and passed.
     const gateMeta = {
         checked: scoredResults.length,
-        abstained: false,
+        abstained: coverageAbstained,
         coverage,
+        // #606: the delta's own denominator, so "no regressions" can never be read
+        // as "compared and clean" on a run that compared nothing.
+        coverageDelta,
+        // #761: the endpoints every count above is scoped by.
+        provenance,
         // #582: `checked` is the numerator of a fraction whose denominator was
         // never printed. This is the rest of it.
         skipped: allSkips,
     };
-    const coverageNotice = coverageDegradedNotice(coverage);
-    if (coverageNotice) {
-        // `--format json` owns stdout: a `::warning::` line there would make the
-        // document unparseable, so the annotation goes to stderr on that path. Both
-        // streams are scanned for workflow commands, so CI still sees it.
-        const machineStdout = !opts.postComment && !opts.emitAnalysis && opts.format === 'json';
-        (machineStdout ? deps.err : deps.out)(degradationAnnotation(coverageNotice));
-        appendStepSummary(deps.env, coverageNotice);
+    // #606: the delta degradation rides the exact same surfaces as the coverage
+    // one — a head-only run is as blind about regressions as a report-less run is
+    // about coverage, and must be as loud.
+    const notices = [
+        coverageDegradedNotice(coverage),
+        coverageDeltaNotice(coverageDelta),
+    ];
+    // `--format json` owns stdout: a `::warning::` line there would make the
+    // document unparseable, so the annotation goes to stderr on that path. Both
+    // streams are scanned for workflow commands, so CI still sees it.
+    const machineStdout = !opts.postComment && !opts.emitAnalysis && opts.format === 'json';
+    for (const notice of notices) {
+        if (!notice)
+            continue;
+        (machineStdout ? deps.err : deps.out)(degradationAnnotation(notice));
+        appendStepSummary(deps.env, notice);
     }
     let commentPosted = false;
     if (opts.emitAnalysis) {
@@ -1072,9 +1109,15 @@ async function prCheckCmd(opts, deps) {
             degraded_notice: resolution.degraded_notice,
             exit_code: exitCode,
             checked: scoredResults.length,
-            abstained: false, // an abstained run exits before emit (see plan)
+            // #761: a coverage abstention DOES reach emit — unlike the
+            // findings-eligible abstention, it keeps its findings, so a machine
+            // consumer must see the flag rather than infer a result from the array.
+            abstained: coverageAbstained,
             coverage,
             skipped: allSkips,
+            // #761: the archived artifact is where an inflated diff gets diagnosed
+            // long after the run, so it carries the endpoints too.
+            provenance,
         });
         if (res.action === 'emitted') {
             deps.out(`guardian: wrote analysis record ${RIGHT_ARROW} ${res.path}`);
@@ -1142,19 +1185,10 @@ function intentDict(intent) {
     };
 }
 /**
- * author-plan's denominator decision (#508, review-round gap).
- *
- * The spec's audit list named `author-plan` next to `pr-check`, but #515
- * deferred it ("guardian internals being reworked in parallel") and Wave 2 only
- * took pr-check. On an EMPTY diff this surface emitted
- * `block: false, authored_count: 0` and exited 0 -- "we examined nothing,
- * therefore do not block", which is the #456 class verbatim.
- *
- * ADVISORY, not a gate: author-plan is an authoring aid whose JSON an agent
- * reads (see `canary-pr-guardian/SKILL.md`); the exit-code contract belongs to
- * `pr-check` and the pre-commit gate. So the exit stays 0 and stdout stays a
- * single parseable object -- `checked`/`abstained` ride the payload additively
- * and the loud line goes to stderr, keeping `--json` consumers byte-compatible.
+ * author-plan's denominator decision (#508): an empty diff must not read as
+ * "examined nothing, so do not block" (#456). ADVISORY, not a gate: exit stays
+ * 0 and stdout one parseable object; `checked`/`abstained` ride the payload and
+ * the loud line goes to stderr.
  */
 function authorPlanOutcome(checked, results, deps) {
     const outcome = gateOutcome({ checked, findings: [...results] }, 'advisory', {
@@ -1291,29 +1325,20 @@ export function createGuardianCommand(depsInit = {}) {
         .addOption(new Option('--check <check>', 'Status-check context to require (the guardian workflow job).').default('guardian'))
         .addOption(new Option('--token <token>', 'Admin token for --apply.').env('GITHUB_TOKEN'))
         .option('--force', 'Skip the check-context-exists verification (risky).')
-        .addOption(new Option('--analyses-dir <dir>', 'Override the analyses dir (tests).').hideHelp())
         .action(async (opts) => {
         await hardenGateCmd(opts, deps);
     });
     program
-        .command('collect-adjudications')
-        .description("Read reviewer thumbs-up/down reactions off the guardian's sticky PR " +
-        'comment and persist the adjudication record (#490).')
+        .command('precision')
+        .description('Derive guardian finding precision (TP / (TP + FP)) from merged PRs, ' +
+        'with its sample size (ADR 0025).')
         .addOption(new Option('--repo <repo>', 'owner/repo.').env('GITHUB_REPOSITORY'))
-        .addOption(new Option('--pr <number>', 'Pull-request number.').argParser((v) => Number.parseInt(v, 10)))
-        .option('--json', 'Emit the collection result as JSON.')
-        .addOption(new Option('--analyses-dir <dir>', 'Override the analyses dir (tests).').hideHelp())
+        .addOption(new Option('--days <n>', 'Merged-PR window in days.')
+        .default(14)
+        .argParser((v) => Number.parseInt(v, 10)))
+        .option('--json', 'Emit the report as JSON (precision null = unknown).')
         .action(async (opts) => {
-        await collectAdjudicationsCmd(opts, deps);
-    });
-    program
-        .command('precision')
-        .description('Report guardian finding precision (TP / (TP + FP)) from collected ' +
-        'adjudications, with its sample size.')
-        .option('--json', 'Emit the summary as JSON (precision null = unknown).')
-        .addOption(new Option('--analyses-dir <dir>', 'Override the analyses dir (tests).').hideHelp())
-        .action((opts) => {
-        precisionCmd(opts, deps);
+        await precisionCmd(opts, deps);
     });
     program
         .command('pr-check')
@@ -1321,6 +1346,9 @@ export function createGuardianCommand(depsInit = {}) {
         .option('--diff <diff>', "Diff file, '-' for stdin, or omit to auto-resolve: the PR diff " +
         '(`<base>...HEAD`) in CI, else the local working-tree `git diff`.')
         .option('--coverage <path>', 'Coverage report path (lcov/json).')
+        .option('--base-coverage <path>', "Coverage report for the PR's BASE ref (#606). Enables coverage-" +
+        'regression findings on touched units. Without it the run degrades ' +
+        'LOUDLY to head-only — it never silently reports no regressions.')
         .addOption(new Option('--format <fmt>', 'comment|json|text').default('comment'))
         .addOption(new Option('--config <path>').default('harness.config.json'))
         .option('--gate <gate>', 'Override config gate: soft|hard')