canary-test-cli 6.4.0 → 6.5.0

package/dist/engine/guardian/cli.js

@@ -18,9 +18,10 @@
  *     `.exitOverride()` turns commander's own usage errors into throws too, so a
  *     test never terminates the process.
  *
- * Command surface (kebab-case names, matching the shipping Typer CLI):
+ * Command surface (kebab-case names; the first seven match the shipping Typer
+ * CLI, the last two are TS-native additions for #490):
  *   analyze | validate-coverage | harden-gate | pr-check | author-plan |
- *   mark-authored | watch.
+ *   mark-authored | watch | collect-adjudications | precision.
  *
  * Python->TS nuances honored:
  *   - `json.dumps(obj, indent=2)` -> `ensureAscii(JSON.stringify(obj, null, 2))`
@@ -49,11 +50,13 @@ 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 { emitAnalysis } from './analysis-emit.js';
-import { resolveCoverage, validateCoverageJson } from './coverage.js';
+import { gateOutcome } from '../core/gate-result.js';
+import { resolveCoverage, validateCoverageJson, } from './coverage.js';
 import { buildApiDelta, writeApiDelta } from './delta-emitter.js';
 import { extractApiDiff } from './diff-extractor.js';
-import { HardGateBlocked, RestBranchProtectionClient, applyHardGate, renderPlaybook, } from './hard-gate.js';
+import { HardGateAbstained, HardGateBlocked, RestBranchProtectionClient, applyHardGate, renderPlaybook, } from './hard-gate.js';
 import { mapImpact } from './impact-mapper.js';
 import { applySuppressions, buildFindings, buildWeakTestFindings, computeExitCode, effectiveGraphDepth, filterHeuristicNoise, filterSkipped, filterTestUnits, findReexportOnly, loadGuardianConfig, render, scopeDiff, } from './pr-check.js';
 import { RestGitHubClient, degradationAnnotation, upsertStickyComment, } from './pr-comment.js';
@@ -139,6 +142,7 @@ export function defaultDeps() {
             };
         },
         buildCommentClient: (repo, prNumber) => new RestGitHubClient(repo, prNumber, process.env['GITHUB_TOKEN'] ?? ''),
+        buildReactionsClient: (repo, prNumber) => new RestReactionsClient(repo, prNumber, process.env['GITHUB_TOKEN'] ?? ''),
         buildBranchProtectionClient: (repo, token) => new RestBranchProtectionClient(repo, token),
         makeAgentTier: () => new InSessionAgentTier(),
         sleep: (secs) => new Promise((resolve) => setTimeout(resolve, secs * 1000)),
@@ -523,6 +527,16 @@ function analyzeCmd(commit, opts, deps) {
     const coverageRows = opts.coverage ? loadCoverage(opts.coverage) : [];
     const gaps = mapImpact(diff, coverageRows);
     const summary = buildSummary(gaps, sha, opts.suite);
+    // #508 advisory abstention (D3): a diff with zero endpoints analyzed
+    // nothing. gateOutcome is the only decision point -- no local === 0.
+    const endpointCount = diff.added.length + diff.removed.length + diff.changed.length;
+    const outcome = gateOutcome({ checked: endpointCount, findings: gaps }, 'advisory', { noun: 'endpoint(s)' });
+    if (outcome.abstained) {
+        deps.out(outcome.summaryLine);
+        deps.out('guardian: the spec diff contains zero endpoints, so there was no ' +
+            'impact to analyze. Pass --spec-before/--spec-after pointing at ' +
+            'specs that actually differ.');
+    }
     if (opts.json) {
         deps.out(ensureAscii(JSON.stringify({
             commit: sha,
@@ -530,6 +544,8 @@ function analyzeCmd(commit, opts, deps) {
             added: diff.added.length,
             removed: diff.removed.length,
             changed: diff.changed.length,
+            checked: endpointCount,
+            abstained: outcome.abstained,
             gaps: gaps.map((g) => ({
                 path: g.path,
                 method: g.method,
@@ -547,6 +563,17 @@ function analyzeCmd(commit, opts, deps) {
     }
 }
 const MAX_COVERAGE_BYTES = 25 * 1024 * 1024;
+/** The validator's denominator: entries in the `files` map (#508). */
+function coverageEntryCount(data) {
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        return 0;
+    }
+    const files = data['files'];
+    if (typeof files !== 'object' || files === null || Array.isArray(files)) {
+        return 0;
+    }
+    return Object.keys(files).length;
+}
 function validateCoverageCmd(path, opts, deps) {
     let text;
     try {
@@ -577,6 +604,7 @@ function validateCoverageCmd(path, opts, deps) {
     const errors = problems.filter((p) => p.severity === 'error');
     const warnings = problems.filter((p) => p.severity === 'warning');
     const valid = errors.length === 0;
+    const outcome = gateOutcome({ checked: coverageEntryCount(data), findings: problems }, 'advisory', { noun: 'file entrie(s)' });
     if (opts.json) {
         // Plain stdout, NOT colored -- producer-controlled keys must not be
         // interpreted as markup, and the payload must stay valid JSON.
@@ -587,6 +615,8 @@ function validateCoverageCmd(path, opts, deps) {
                 location: pr.location,
                 message: pr.message,
             })),
+            checked: coverageEntryCount(data),
+            abstained: outcome.abstained,
         }, null, 2)));
     }
     else {
@@ -597,7 +627,15 @@ function validateCoverageCmd(path, opts, deps) {
             deps.out(`${pc.yellow('warning')} ${pr.location}: ${pr.message}`);
         }
         if (valid && warnings.length === 0) {
-            deps.out(pc.green(pc.bold(`${CHECK} ${path} is a valid coverage-json document.`)));
+            if (outcome.abstained) {
+                deps.out(outcome.summaryLine);
+                deps.out(`guardian: ${path} carries zero file entries ${EM_DASH} nothing ` +
+                    'was validated. Check that the producer wrote a non-empty ' +
+                    "'files' map.");
+            }
+            else {
+                deps.out(pc.green(pc.bold(`${CHECK} ${path} is a valid coverage-json document.`)));
+            }
         }
         else if (valid) {
             deps.out(`${pc.green(`${CHECK} valid`)} with ${warnings.length} warning(s) ${EM_DASH} coverage is usable but degraded.`);
@@ -610,6 +648,20 @@ function validateCoverageCmd(path, opts, deps) {
         throw new CliExit(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) {
@@ -617,6 +669,8 @@ async function hardenGateCmd(opts, deps) {
         throw new CliExit(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);
     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 ' +
@@ -637,6 +691,15 @@ async function hardenGateCmd(opts, deps) {
         plan = await applyHardGate(client, repo, opts.branch, opts.check, opts.force ?? false);
     }
     catch (exc) {
+        if (exc instanceof HardGateAbstained) {
+            const outcome = gateOutcome({ checked: 0, findings: [] }, 'gate', {
+                noun: 'check context(s)',
+            });
+            deps.out(outcome.summaryLine);
+            deps.out(`${pc.red(pc.bold(`${CROSS} ${exc.reason}`))}\n`);
+            deps.out(exc.playbook);
+            throw new CliExit(outcome.exitCode); // 3, never 1
+        }
         if (exc instanceof HardGateBlocked) {
             deps.out(`${pc.red(pc.bold(`${CROSS} ${exc.reason}`))}\n`);
             deps.out(exc.playbook);
@@ -657,6 +720,67 @@ async function hardenGateCmd(opts, deps) {
         'canary.guardian.pr.gate = "hard" in harness.config.json ' +
         '(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.
+ */
+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.`);
+        throw new CliExit(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 CliExit(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);
+}
 // --- pr-check -----------------------------------------------------------------
 /**
  * Upsert the Phase-2 sticky PR comment (behavior-preserving extraction). When no
@@ -679,8 +803,96 @@ async function postStickyComment(findings, resolution, deps) {
     }
 }
 /** The gate's no-op line, shared by the pre- and post-filter exits. */
-function nothingToVerify(skippedCount) {
-    return `guardian: nothing to verify (${skippedCount} path(s) skipped).`;
+// 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, noisePaths = []) {
+    return [
+        ...skipped.map((u) => ({ name: u.path, reason: 'skipGlobs' })),
+        ...testUnits.map((u) => ({ name: u.path, reason: 'test path' })),
+        ...barrelUnits.map((u) => ({
+            name: u.path,
+            reason: 're-export barrel',
+        })),
+        ...noisePaths.map((p) => ({
+            name: p,
+            reason: 'heuristic-ineligible',
+        })),
+    ];
+}
+// Remediation is required copy (#508): say WHY the denominator
+// collapsed and the first fix step. The #456 class, now loud.
+const PR_CHECK_ABSTAIN_REMEDIATION = [
+    'guardian: the diff contained no findings-eligible units, so NO ' +
+        'coverage was verified. This is not a pass (exit 3, abstained).',
+    'If you expected verification: in CI, checkout with fetch-depth: 0 ' +
+        'or pass --diff <base>...HEAD; locally, confirm the diff is ' +
+        'non-empty and skipGlobs/heuristicExclude are not filtering ' +
+        'every path.',
+];
+/** Exit 3 with the structural abstention line + remediation (#508). */
+function abstainPrCheck(skipped, format, deps) {
+    const outcome = gateOutcome({ checked: 0, findings: [], skipped }, 'gate', {
+        noun: 'unit(s)',
+    });
+    deps.out(outcome.summaryLine);
+    for (const line of PR_CHECK_ABSTAIN_REMEDIATION)
+        deps.out(line);
+    if (format === 'json') {
+        deps.out(ensureAscii(JSON.stringify({ findings: [], tier: 0, checked: 0, abstained: true }, null, 2)));
+    }
+    throw new CliExit(outcome.exitCode); // EXIT_ABSTAINED
+}
+/** Resolve the analyses-channel dir (test override, else repo-root default). */
+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);
@@ -695,6 +907,12 @@ async function prCheckCmd(opts, deps) {
         throw new CliExit(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);
@@ -715,8 +933,7 @@ async function prCheckCmd(opts, deps) {
         : [];
     const preFilterSkipped = skipped.length + testUnits.length + barrelUnits.length;
     if (kept.length === 0 && weakFindings.length === 0) {
-        deps.out(nothingToVerify(preFilterSkipped));
-        throw new CliExit(0);
+        abstainPrCheck(prCheckSkipEntries(skipped, testUnits, barrelUnits), opts.format, deps);
     }
     const results = resolveCoverage(kept, {
         coveragePath: opts.coverage ?? null,
@@ -736,8 +953,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) {
-        deps.out(nothingToVerify(preFilterSkipped + noiseResults.length));
-        throw new CliExit(0);
+        abstainPrCheck(prCheckSkipEntries(skipped, testUnits, barrelUnits, noiseResults.map((r) => r.unit.path)), opts.format, deps);
     }
     // SC-5 (PR half): resolve the requested tier against actual capability. No
     // agent runtime exists (default NoAgentProbe), so any `pr.tier > 0` drops to
@@ -755,9 +971,7 @@ async function prCheckCmd(opts, deps) {
         // SC-10 producer half: write ONE record to the analyses channel. On an
         // unavailable channel `emitAnalysis` returns a LOUD notice and we fall back
         // to the sticky comment -- the record is never silently dropped.
-        const analysesDir = opts.analysesDir
-            ? opts.analysesDir
-            : join(gitToplevel(deps), '.harness', 'analyses');
+        const analysesDir = resolveAnalysesDir(opts.analysesDir, deps);
         const res = emitAnalysis(findings, {
             analysesDir,
             ref: resolveAnalysisRef(deps),
@@ -765,6 +979,8 @@ async function prCheckCmd(opts, deps) {
             effective_tier: resolution.effective,
             degraded_notice: resolution.degraded_notice,
             exit_code: exitCode,
+            checked: scoredResults.length,
+            abstained: false, // an abstained run exits before emit (see plan)
         });
         if (res.action === 'emitted') {
             deps.out(`guardian: wrote analysis record ${RIGHT_ARROW} ${res.path}`);
@@ -786,7 +1002,7 @@ async function prCheckCmd(opts, deps) {
     }
     else if (!opts.emitAnalysis && !opts.postComment) {
         // Local, non-posting default: render to stdout in `--format`.
-        deps.out(render(findings, opts.format, resolution.effective, resolution.degraded_notice));
+        deps.out(render(findings, opts.format, resolution.effective, resolution.degraded_notice, { checked: scoredResults.length, abstained: false }));
     }
     throw new CliExit(exitCode);
 }
@@ -822,6 +1038,33 @@ function intentDict(intent) {
         skip_reason: intent.skip_reason,
     };
 }
+/**
+ * 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.
+ */
+function authorPlanOutcome(checked, results, deps) {
+    const outcome = gateOutcome({ checked, findings: [...results] }, 'advisory', {
+        noun: 'gap(s)',
+    });
+    if (outcome.abstained) {
+        deps.err(`${outcome.summaryLine} guardian author-plan scoped zero coverage ` +
+            'gaps, so "nothing to author" here means nothing was EXAMINED, not ' +
+            'that everything is covered. Confirm the diff is non-empty and that ' +
+            'skipGlobs is not filtering every path.');
+    }
+    return outcome;
+}
 function authorPlanCmd(opts, deps) {
     const [config, warning] = loadGuardianConfig(opts.config);
     if (warning !== null) {
@@ -845,6 +1088,7 @@ function authorPlanCmd(opts, deps) {
     });
     const results = deps.makeAgentTier().author_tests(gaps, ctx);
     const decision = decideBlock(results);
+    const outcome = authorPlanOutcome(gaps.length, results, deps);
     const payload = {
         intents: results.map(intentDict),
         block: {
@@ -852,6 +1096,8 @@ function authorPlanCmd(opts, deps) {
             message: decision.message,
             authored_count: decision.authored_count,
         },
+        checked: gaps.length,
+        abstained: outcome.abstained,
     };
     deps.out(ensureAscii(JSON.stringify(payload, null, 2)));
 }
@@ -942,9 +1188,30 @@ 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).')
+        .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())
+        .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);
+    });
     program
         .command('pr-check')
         .description('Tier 0 deterministic PR guardian: scope, resolve, gate.')

package/dist/engine/guardian/hard-gate.js

@@ -56,6 +56,19 @@ export class HardGateBlocked extends Error {
         this.playbook = playbook;
     }
 }
+/**
+ * The verification population was EMPTY (#508): no check has ever
+ * reported on the branch, so the context could not be verified against
+ * anything. A subclass of {@link HardGateBlocked} so pre-#508 catch
+ * sites keep working; the CLI maps it to EXIT_ABSTAINED (3), distinct
+ * from real blockers (1).
+ */
+export class HardGateAbstained extends HardGateBlocked {
+    constructor(reason, playbook) {
+        super(reason, playbook);
+        this.name = 'HardGateAbstained';
+    }
+}
 /**
  * Decide the change without touching the network (PURE).
  *
@@ -190,11 +203,11 @@ export async function applyHardGate(client, repo, branch, checkContext, force =
             observed = [];
         }
         if (observed.length === 0) {
-            throw blocked(`could not confirm any check has reported on ${repo}@${branch}, ` +
+            throw new HardGateAbstained(`could not confirm any check has reported on ${repo}@${branch}, ` +
                 `so cannot verify '${checkContext}' is a real context; ` +
                 'requiring an unreported check would block every merge. ' +
                 'Open a PR so the guardian check runs at least once, or pass ' +
-                '--force to register it anyway.');
+                '--force to register it anyway.', playbook);
         }
         if (!observed.includes(checkContext)) {
             const sorted = [...observed].sort();

package/dist/engine/guardian/pr-check.js

@@ -729,18 +729,7 @@ function findingDict(finding) {
         suppression_reason: finding.suppression_reason,
     };
 }
-/**
- * Render findings as a sticky PR `comment`, `json`, or plain `text`.
- *
- * - `comment`: leads with the sticky marker `<!-- canary-pr-guardian -->`, a
- *   fidelity-labeled summary line, then severity-ranked findings (each showing
- *   path/unit, severity, fidelity, evidence). Suppressed findings are rendered
- *   but visually marked `suppressed`. Footer states `tier 0` and appends
- *   `degradedNotice` when present.
- * - `json`: `{"findings": [...], "tier": <n>}` — stable schema.
- * - `text`: plain, markdown-free, for local/CLI output.
- */
-export function render(findings, fmt, tier = 0, degradedNotice = null) {
+export function render(findings, fmt, tier = 0, degradedNotice = null, gateMeta = null) {
     const ordered = [...findings].sort((a, b) => severitySortKey(a.severity) - severitySortKey(b.severity));
     if (fmt === 'json') {
         const payload = {
@@ -749,6 +738,10 @@ export function render(findings, fmt, tier = 0, degradedNotice = null) {
         };
         if (degradedNotice)
             payload['degraded_notice'] = degradedNotice;
+        if (gateMeta !== null) {
+            payload['checked'] = gateMeta.checked;
+            payload['abstained'] = gateMeta.abstained;
+        }
         return ensureAscii(JSON.stringify(payload, null, 2));
     }
     const active = ordered.filter((f) => !f.suppressed);

package/dist/engine/history/cli.js

@@ -25,6 +25,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { Command, Option } from 'commander';
 import pc from 'picocolors';
 import { CliExit, jsonIndent2, normalizeUsageExit } from '../cli-common.js';
+import { gateOutcome } from '../core/gate-result.js';
 import { makeRunId } from './schema.js';
 import { makeStore as realMakeStore } from './store.js';
 import { pyFloat } from '../util/round.js';
@@ -32,6 +33,34 @@ const EM_DASH = '\u{2014}';
 const GEQ = '\u{2265}';
 const MDASH_CELL = '\u{2014}'; // rich `r.get("area") or <em-dash>`
 const DEFAULT_HISTORY_FILE = 'test-results/reports/history-v2.jsonl';
+/**
+ * The denominator guard for the history reports (#508 Wave 4a).
+ *
+ * `countRuns` is OPTIONAL on `AsyncHistoryStore`: a backend that cannot report
+ * how many runs it holds (today, the remote Supabase store) keeps
+ * benefit-of-the-doubt and never abstains. An UNKNOWN denominator is not a zero
+ * one -- inventing an abstention would be its own dishonesty, the same reason
+ * #527 renders `precision: null` rather than 0.
+ *
+ * Advisory (D3): exit stays 0. Returns true when the caller should stop.
+ */
+async function abstainOnEmptyHistory(store, deps, json, what) {
+    if (store.countRuns === undefined)
+        return false; // unknown, not zero
+    if ((await store.countRuns()) > 0)
+        return false;
+    const outcome = gateOutcome({ checked: 0, findings: [] }, 'advisory');
+    const notice = `${outcome.summaryLine} No runs recorded, so ${what} is unknown rather ` +
+        `than clean. Record runs first (\`canary history push\`), then re-run.`;
+    if (json) {
+        deps.out(jsonIndent2([]));
+        deps.err(notice);
+    }
+    else {
+        deps.out(notice);
+    }
+    return true;
+}
 /** Every field of the Python `RunRecord` dataclass (the push/migrate filter). */
 const RUN_FIELDS = [
     'run_id',
@@ -124,6 +153,9 @@ async function pushCmd(historyFile, opts, deps) {
 }
 async function flakyCmd(opts, deps) {
     const store = deps.makeStore(opts.dbUrl);
+    if (await abstainOnEmptyHistory(store, deps, opts.json === true, 'flake rate')) {
+        return;
+    }
     const results = await store.queryFlaky(opts.window, opts.suite ?? null, opts.minRate);
     if (opts.json) {
         deps.out(jsonIndent2(results));
@@ -148,6 +180,14 @@ async function flakyCmd(opts, deps) {
 }
 async function timelineCmd(testName, opts, deps) {
     const store = deps.makeStore(opts.dbUrl);
+    // #508 (review-round gap): `No history found for: <test>` rendered
+    // IDENTICALLY whether the test genuinely has no runs in a populated store (a
+    // real answer) or the store is empty and nothing was examined at all (an
+    // absent one). Same runs-vs-rows distinction Wave 4a built `countRuns()` for;
+    // `timeline` was missed because #515's audit table never listed it.
+    if (await abstainOnEmptyHistory(store, deps, opts.json === true, `the timeline for ${testName}`)) {
+        return;
+    }
     const rows = await store.queryTimeline(testName);
     if (opts.json) {
         deps.out(jsonIndent2(rows));
@@ -171,6 +211,24 @@ async function timelineCmd(testName, opts, deps) {
 async function summaryCmd(suite, opts, deps) {
     const store = deps.makeStore(opts.dbUrl);
     const result = await store.querySummary(suite, opts.runs);
+    // #508: a summary over zero runs used to print `avg pass rate: 0.0%` -- a
+    // FABRICATED number, not a measured one, and the most misleading shape in the
+    // whole audit (0% reads as catastrophe, not as absence). The store's own
+    // `total_runs` is the denominator here; no extra probe is needed.
+    if ((result.total_runs ?? 0) === 0) {
+        const outcome = gateOutcome({ checked: 0, findings: [] }, 'advisory');
+        const notice = `${outcome.summaryLine} Suite ${suite} has no recorded runs, so its ` +
+            `pass rate is unknown -- not 0%. Record runs first ` +
+            `(\`canary history push\`), then re-run.`;
+        if (opts.json) {
+            deps.out(jsonIndent2({ ...result, abstained: true }));
+            deps.err(notice);
+        }
+        else {
+            deps.out(notice);
+        }
+        return;
+    }
     if (opts.json) {
         deps.out(jsonIndent2(result));
         return;
@@ -227,6 +285,15 @@ async function migrateCmd(file, opts, deps) {
         await store.pushRun(run, []);
         migrated += 1;
     }
+    // #508: `Migrated 0 runs` in green is a success line over an empty
+    // denominator -- the #504 shape. A file that yielded nothing was not migrated.
+    if (migrated === 0) {
+        const outcome = gateOutcome({ checked: 0, findings: [] }, 'advisory');
+        deps.out(`${outcome.summaryLine} No run in ${file} could be migrated ` +
+            `(skipped ${skipped}). Check that the file is v1 history NDJSON and ` +
+            `that --suite/--repo match it.`);
+        return;
+    }
     deps.out(`${pc.green('Migrated')} ${migrated} runs, skipped ${skipped}`);
 }
 // --- assembly ----------------------------------------------------------------

package/dist/engine/history/ndjson-store.js

@@ -46,6 +46,10 @@ export class NdjsonHistoryStore {
         }
         return records;
     }
+    /** The denominator probe: how many runs this store holds (#508). */
+    countRuns() {
+        return this.readAll().length;
+    }
     /**
      * Append a run + its results as one NDJSON line. Idempotent: a run whose
      * `run_id` is already present is silently skipped (matches Python

package/dist/engine/history/store.js

@@ -30,6 +30,9 @@ export class LocalAsyncAdapter {
     async queryTimeline(testName) {
         return this.inner.queryTimeline(testName);
     }
+    async countRuns() {
+        return this.inner.countRuns();
+    }
     async querySummary(suite, runs) {
         return this.inner.querySummary(suite, runs);
     }