canary-test-cli 6.0.0 → 6.2.0

package/dist/engine/analysis/reachability.js

@@ -0,0 +1,305 @@
+/**
+ * Reachability sweep — the generic crawl primitive from #452.
+ *
+ * Enumerate every link on a surface and assert it resolves. Cheap, broad, and
+ * high-yield: it catches dangling routes and 404s that targeted tests never
+ * look for, because a targeted test asserts what a page *does*, not that the
+ * things it points at still exist.
+ *
+ * This module owns the deterministic half — normalization, scoping, and
+ * classification. **Fetching is injected** ({@link LinkProbe}), so the logic is
+ * unit-testable with no network and a caller can supply whatever transport it
+ * already has (plain `fetch`, an authenticated client, a browser page).
+ *
+ * ## The load-bearing distinction: dead vs. slow
+ *
+ * The reason this is not simply "fetch and check the status": **a dead link and
+ * a slow link must never be confusable.** A 404 is a defect the sweep is
+ * entitled to assert on. A timeout, DNS failure, or refused connection is
+ * *inconclusive* — the link may be perfectly fine while the network, a cold
+ * container, or a rate limiter is not.
+ *
+ * Conflating them is how a broad sweep turns into a flaky test that teams learn
+ * to ignore, which costs more than the check was ever worth. So the two are
+ * structurally different outcomes ({@link ReachabilityStatus.Broken} vs
+ * {@link ReachabilityStatus.Unreachable}) with different {@link isDefect}
+ * verdicts, and only the first is ever asserted on.
+ *
+ * The same principle decides the other ambiguous cases:
+ *   - **5xx** — the target exists and is unwell. A server problem, not a
+ *     dangling reference; blaming the link sends someone to fix the wrong
+ *     thing.
+ *   - **401/403** — auth-walled, not missing. The link is fine; the sweep just
+ *     is not logged in.
+ *
+ * Only an unambiguous "this target does not exist" (4xx that is not auth)
+ * counts as a defect.
+ */
+/** How a probed link resolved. Only {@link Broken} is asserted on. */
+export var ReachabilityStatus;
+(function (ReachabilityStatus) {
+    /** Resolved (2xx/3xx), or exists but is auth-walled (401/403). */
+    ReachabilityStatus["Ok"] = "ok";
+    /** The target does not exist (4xx other than auth). The one real defect. */
+    ReachabilityStatus["Broken"] = "broken";
+    /** The target exists but errored (5xx) — a server problem, not a bad link. */
+    ReachabilityStatus["ServerError"] = "server-error";
+    /** No verdict possible: timeout, DNS failure, refused connection. */
+    ReachabilityStatus["Unreachable"] = "unreachable";
+    /** Off-site and not allowlisted, so deliberately not probed. */
+    ReachabilityStatus["SkippedExternal"] = "skipped-external";
+})(ReachabilityStatus || (ReachabilityStatus = {}));
+// Schemes that are not fetchable resources. A `mailto:`/`tel:` is a valid link
+// and probing it is meaningless; `javascript:` is a control, not a destination.
+const NON_FETCHABLE_SCHEMES = new Set([
+    'mailto:',
+    'tel:',
+    'javascript:',
+    'data:',
+    'blob:',
+    'sms:',
+    'file:',
+]);
+/** Auth-walled: the target exists, the sweep just cannot see it. */
+const AUTH_STATUSES = new Set([401, 403]);
+/**
+ * Resolve `href` against `base` into an absolute, fragment-free URL.
+ *
+ * Returns `null` for anything that is not a fetchable destination: an empty or
+ * fragment-only href (it points at the current page), a non-fetchable scheme,
+ * or an href malformed enough that `URL` rejects it.
+ *
+ * The fragment is dropped deliberately — `/p#a` and `/p#b` are the same
+ * request, and keeping them apart would probe the same page repeatedly and
+ * report one dangling route as several.
+ */
+export function normalizeLink(href, base) {
+    const trimmed = href.trim();
+    // Empty, or a pure fragment: this is the current page, not a destination.
+    if (!trimmed || trimmed.startsWith('#'))
+        return null;
+    let url;
+    try {
+        url = new URL(trimmed, base);
+    }
+    catch {
+        return null;
+    }
+    if (NON_FETCHABLE_SCHEMES.has(url.protocol))
+        return null;
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null;
+    url.hash = '';
+    return { url: url.href, host: url.hostname };
+}
+/** True iff `host` is `allowed` or a subdomain of it (never a lookalike). */
+function hostMatches(host, allowed) {
+    const h = host.toLowerCase();
+    const a = allowed.toLowerCase();
+    // The leading dot is what stops `nottrusted.example` matching
+    // `trusted.example` — a bare `endsWith` would wrongly accept it.
+    return h === a || h.endsWith(`.${a}`);
+}
+/** True iff `link` is in scope: same host as the base, or allowlisted. */
+function inScope(link, baseHost, allowExternal) {
+    if (hostMatches(link.host, baseHost))
+        return true;
+    return allowExternal.some((allowed) => hostMatches(link.host, allowed));
+}
+/** Map an HTTP status to a verdict. See the module docstring for the rationale. */
+function classifyStatus(status) {
+    if (status >= 200 && status < 400)
+        return ReachabilityStatus.Ok;
+    // Auth-walled is not dangling: the target exists.
+    if (AUTH_STATUSES.has(status))
+        return ReachabilityStatus.Ok;
+    if (status >= 400 && status < 500)
+        return ReachabilityStatus.Broken;
+    if (status >= 500)
+        return ReachabilityStatus.ServerError;
+    // 1xx as a final status is nonsensical; refuse to guess.
+    return ReachabilityStatus.Unreachable;
+}
+/**
+ * True iff `status` is a finding worth failing a sweep on.
+ *
+ * Only {@link ReachabilityStatus.Broken}. `Unreachable` is inconclusive,
+ * `ServerError` belongs to whoever owns the server, and a skipped link was
+ * never claimed to be checked. Asserting on any of those would make the sweep
+ * fail for reasons the author of the link cannot fix.
+ */
+export function isDefect(status) {
+    return status === ReachabilityStatus.Broken;
+}
+/**
+ * Sweep `hrefs`, probing each unique in-scope URL exactly once.
+ *
+ * Results are sorted by URL so a sweep produces a stable, diffable report
+ * regardless of the order links appeared on the page.
+ */
+export function sweepLinks(hrefs, options) {
+    const { base, probe, allowExternal = [] } = options;
+    const baseHost = new URL(base).hostname;
+    // Dedup by normalized URL: a nav link repeated on every page is one check,
+    // and one dangling route should be reported once, not once per referrer.
+    const unique = new Map();
+    for (const href of hrefs) {
+        const link = normalizeLink(href, base);
+        if (link !== null && !unique.has(link.url))
+            unique.set(link.url, link);
+    }
+    const results = [];
+    for (const { link, scoped } of planSweep(hrefs, base, allowExternal)) {
+        results.push(scoped ? resolveOutcome(link, probe(link.url)) : skippedResult(link));
+    }
+    return { results, summary: summarize(results) };
+}
+/**
+ * Normalize, dedup, sort, and scope `hrefs` — everything the sync and async
+ * drivers must agree on. Shared so the two can never drift apart on which
+ * links get probed or in what order.
+ *
+ * Dedup by normalized URL: a nav link repeated on every page is one check, and
+ * one dangling route should be reported once, not once per referrer. Sorted by
+ * URL so a sweep produces a stable, diffable report regardless of the order
+ * links appeared on the page.
+ */
+function planSweep(hrefs, base, allowExternal) {
+    const baseHost = new URL(base).hostname;
+    const unique = new Map();
+    for (const href of hrefs) {
+        const link = normalizeLink(href, base);
+        if (link !== null && !unique.has(link.url))
+            unique.set(link.url, link);
+    }
+    return [...unique.values()]
+        .sort((a, b) => a.url.localeCompare(b.url))
+        .map((link) => ({
+        link,
+        scoped: inScope(link, baseHost, [...allowExternal]),
+    }));
+}
+function skippedResult(link) {
+    return {
+        url: link.url,
+        status: ReachabilityStatus.SkippedExternal,
+        httpStatus: null,
+        detail: 'off-site and not allowlisted',
+    };
+}
+/** Turn a probe outcome into a verdict, keeping dead and slow apart. */
+function resolveOutcome(link, outcome) {
+    if (outcome.kind === 'failed') {
+        return {
+            url: link.url,
+            status: ReachabilityStatus.Unreachable,
+            httpStatus: null,
+            // The reason is carried verbatim: an inconclusive result is only
+            // actionable if the reader can see WHY no verdict was reached.
+            detail: `no response (${outcome.reason})`,
+        };
+    }
+    return {
+        url: link.url,
+        status: classifyStatus(outcome.status),
+        httpStatus: outcome.status,
+        detail: `HTTP ${outcome.status}`,
+    };
+}
+/**
+ * {@link sweepLinks} over an async transport — the shape real network use takes.
+ *
+ * Probes sequentially on purpose. A sweep enumerates *every* link on a surface,
+ * so firing them concurrently at one host is indistinguishable from a small
+ * load test and invites the rate limiting that would then be misreported as
+ * `unreachable`. A slow, correct sweep beats a fast, self-poisoning one.
+ */
+export async function sweepLinksAsync(hrefs, options) {
+    const { base, probe, allowExternal = [] } = options;
+    const results = [];
+    for (const { link, scoped } of planSweep(hrefs, base, allowExternal)) {
+        results.push(scoped
+            ? resolveOutcome(link, await probe(link.url))
+            : skippedResult(link));
+    }
+    return { results, summary: summarize(results) };
+}
+/**
+ * A `fetch`-backed {@link AsyncLinkProbe} that keeps dead and slow apart.
+ *
+ * Any outcome where the server answered — including a 404 — is a `status`. Any
+ * outcome where no response arrived (timeout, DNS failure, refused connection)
+ * is a `failed`, carrying its reason. Callers should use this rather than
+ * hand-rolling a probe: deciding what counts as "no response" IS the guarantee
+ * this module exists to provide, and re-implementing it per caller is how the
+ * distinction gets quietly lost.
+ *
+ * Uses `HEAD`, falling back to `GET` when a server rejects `HEAD` outright
+ * (405/501) — some servers do, and treating that as a broken link would be a
+ * false positive.
+ */
+export function createHttpProbe(options = {}) {
+    const { timeoutMs = 10_000, fetchImpl = fetch } = options;
+    return async (url) => {
+        const attempt = async (method) => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const res = await fetchImpl(url, {
+                    method,
+                    redirect: 'follow',
+                    signal: controller.signal,
+                });
+                return { kind: 'status', status: res.status };
+            }
+            catch (err) {
+                const reason = controller.signal.aborted
+                    ? `timeout after ${timeoutMs}ms`
+                    : err instanceof Error
+                        ? err.message
+                        : String(err);
+                return { kind: 'failed', reason };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        const head = await attempt('HEAD');
+        if (head.kind === 'status' &&
+            (head.status === 405 || head.status === 501)) {
+            return attempt('GET');
+        }
+        return head;
+    };
+}
+function summarize(results) {
+    const summary = {
+        total: results.length,
+        ok: 0,
+        broken: 0,
+        unreachable: 0,
+        skipped: 0,
+        defects: 0,
+    };
+    for (const r of results) {
+        switch (r.status) {
+            case ReachabilityStatus.Broken:
+                summary.broken += 1;
+                break;
+            case ReachabilityStatus.Unreachable:
+                summary.unreachable += 1;
+                break;
+            case ReachabilityStatus.SkippedExternal:
+                summary.skipped += 1;
+                break;
+            // A 5xx is counted with `ok` for the accounting identity (it is not a
+            // link defect); it stays distinguishable via each result's own status.
+            default:
+                summary.ok += 1;
+        }
+        if (isDefect(r.status))
+            summary.defects += 1;
+    }
+    return summary;
+}
+//# sourceMappingURL=reachability.js.map

package/dist/engine/cli.core.js

@@ -1,9 +1,9 @@
 /**
- * The main `canary` command -- faithful commander port of `agent/cli.py`
- * (`app`), the culmination of the CLI wave. Mounts the already-ported sub-apps
- * (`guardian`, `history`, `analyze`) plus the inline `skills` / `workflow` /
- * `company-knowledge` sub-apps, and the ~15 top-level commands. Additive: the
- * Python `agent.cli:app` stays the shipping entry point until a later cutover.
+ * The main `canary` command -- the commander CLI, culmination of the CLI wave.
+ * Mounts the sub-apps (`guardian`, `history`, `analyze`) plus the inline
+ * `skills` / `workflow` / `company-knowledge` sub-apps, and the ~15 top-level
+ * commands. This is the sole shipping entry point (the Python engine was
+ * retired in the v6 cutover).
  *
  * Conventions follow `guardian/cli.ts` (see `cli-common.ts`): a
  * {@link createCanaryCommand} factory wired to an injectable {@link MainDeps},

package/dist/engine/core/company-knowledge.js

@@ -112,6 +112,12 @@ const _KNOWN_KEYS = new Set([
     'otel_exporter_endpoint',
     'notes',
     'brand',
+    // #459: read by the migrator (`_detectFramework` / overlay `deploy_to`
+    // matching) to decide which overlay skills deploy. It is NOT parsed into a
+    // `CompanyKnowledge` field, but it is emphatically not "ignored" either --
+    // warning that it is told anyone adopting an overlay that the single field
+    // driving their adoption does nothing.
+    'canary_shape',
 ]);
 const _HEX_COLOR_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
 const _BRAND_TEXT_MAX = 200;

package/dist/engine/core/framework-registry.js

@@ -1,20 +1,23 @@
 /**
  * Framework Registry — queries the collection of supported testing frameworks.
  *
- * Faithful TypeScript port of `agent/core/framework_registry.py`. Reads the same
- * `agent/frameworks/registry.json` the Python engine uses. The default path is
- * resolved relative to this file (../../.. → repo root, then agent/frameworks).
+ * Reads the framework catalog from `data/frameworks/registry.json`, resolved
+ * relative to this module. The source-of-truth lives at
+ * `ts/src/data/frameworks/registry.json`; `scripts/copy-data.mjs` mirrors it to
+ * `dist/data/` after `tsc`, and the offset `../data/frameworks/registry.json` is
+ * stable across all three runtimes: vitest (from `src/core/`), the dev CLI (from
+ * `dist/core/`), and the shipped npm bundle (from `dist/engine/core/`).
  */
 import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { def } from '../util/coalesce.js';
 import { scaffoldableFrameworks } from './scaffolder.js';
-/** Default registry path: <repo>/agent/frameworks/registry.json. */
+/** Default registry path: `<module dir>/../data/frameworks/registry.json`. */
 export function defaultRegistryPath() {
     const here = dirname(fileURLToPath(import.meta.url));
-    // here = ts/src/core → repo root is three levels up.
-    return resolve(here, '..', '..', '..', 'agent', 'frameworks', 'registry.json');
+    // here = <core> → sibling data/ dir (src/data in vitest, dist/data at runtime).
+    return resolve(here, '..', 'data', 'frameworks', 'registry.json');
 }
 export class FrameworkRegistry {
     frameworks;

package/dist/engine/guardian/cli.js

@@ -55,7 +55,7 @@ import { buildApiDelta, writeApiDelta } from './delta-emitter.js';
 import { extractApiDiff } from './diff-extractor.js';
 import { HardGateBlocked, RestBranchProtectionClient, applyHardGate, renderPlaybook, } from './hard-gate.js';
 import { mapImpact } from './impact-mapper.js';
-import { applySuppressions, buildFindings, buildWeakTestFindings, computeExitCode, effectiveGraphDepth, filterSkipped, filterTestUnits, findReexportOnly, loadGuardianConfig, render, scopeDiff, } from './pr-check.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';
 import { buildSummary } from './summary-emitter.js';
 import { resolveTier } from './tier.js';
@@ -263,17 +263,146 @@ function authoredSentinelPath(deps, root) {
  *
  * `source === '-'` reads stdin; a path reads that file; `null` runs `git diff`
  * and falls back to `git diff --staged` when the worktree is clean.
+ *
+ * This is the AT-DESK resolution: the working tree is the subject. `pr-check`
+ * uses {@link readPrDiff} instead, which prefers the PR diff in CI (#369).
  */
 function readDiff(source, deps) {
     if (source === '-')
         return deps.readStdin();
     if (source !== null)
         return readFileSync(source, 'utf-8');
+    return readWorktreeDiff(deps);
+}
+/** `git diff`, falling back to `git diff --staged` on a clean worktree. */
+function readWorktreeDiff(deps) {
     const unstaged = deps.runGit(['diff'])?.stdout ?? '';
     if (unstaged.trim())
         return unstaged;
     return deps.runGit(['diff', '--staged'])?.stdout ?? '';
 }
+/** True when the process looks like a CI runner rather than a dev worktree. */
+function isCiContext(env) {
+    return Boolean(env['GITHUB_ACTIONS'] || env['CI']);
+}
+/**
+ * Read `pull_request.base.sha` from the Actions event payload, if present.
+ *
+ * Optional chaining over a narrow interface (rather than an `unknown` +
+ * `typeof` ladder) keeps this at one branch per real failure mode: unreadable
+ * file, unparseable JSON, or a payload without a usable sha.
+ */
+function eventBaseSha(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?.base?.sha;
+    }
+    catch {
+        return null;
+    }
+    return typeof sha === 'string' && sha.trim() ? sha.trim() : null;
+}
+/**
+ * Base-rev candidates for the PR diff, most-preferred first.
+ *
+ * `origin/<ref>` leads because `actions/checkout` fetches the base branch under
+ * the remote namespace and usually does NOT create a local branch for it; the
+ * bare `<ref>` covers checkouts that do. The event payload's `base.sha` is the
+ * last resort — exact, but only present on `pull_request` events.
+ */
+function baseRefCandidates(env) {
+    const candidates = [];
+    const baseRef = env['GITHUB_BASE_REF']?.trim();
+    if (baseRef)
+        candidates.push(`origin/${baseRef}`, baseRef);
+    const sha = eventBaseSha(env);
+    if (sha)
+        candidates.push(sha);
+    return candidates;
+}
+/**
+ * Return the first base candidate that actually resolves to a commit locally.
+ *
+ * A shallow clone (`fetch-depth: 1`, the `actions/checkout` default) will NOT
+ * have the base commit, so every candidate fails `rev-parse` and we return
+ * `null` — the caller then falls back to the worktree diff and warns.
+ */
+function resolveBaseRev(deps) {
+    for (const candidate of baseRefCandidates(deps.env)) {
+        const res = deps.runGit([
+            'rev-parse',
+            '--verify',
+            '--quiet',
+            `${candidate}^{commit}`,
+        ]);
+        if (res !== null && res.code === 0 && res.stdout.trim())
+            return candidate;
+    }
+    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.
+ */
+export function readPrDiff(source, deps) {
+    if (source === '-') {
+        return { text: deps.readStdin(), origin: 'stdin', base: null };
+    }
+    if (source !== null) {
+        return { text: readFileSync(source, 'utf-8'), origin: 'file', base: null };
+    }
+    if (isCiContext(deps.env)) {
+        const base = resolveBaseRev(deps);
+        if (base !== null) {
+            const res = deps.runGit(['diff', `${base}...HEAD`]);
+            if (res !== null && res.code === 0) {
+                return { text: res.stdout, origin: 'ci-base', base };
+            }
+        }
+    }
+    return { text: readWorktreeDiff(deps), origin: 'worktree', base: null };
+}
+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 ' +
+    'ref resolves automatically.';
+/**
+ * Warn LOUDLY when a CI run scoped zero paths off the worktree fallback (#369).
+ *
+ * Fires only for the exact broken shape — `--diff` omitted, CI detected, base
+ * rev unresolvable, and zero changed paths. A diff that DID carry paths which
+ * were then all skipped is a legitimate no-op and stays quiet.
+ *
+ * Deliberately non-blocking: it annotates (`::warning::` + step summary +
+ * stderr) rather than exiting non-zero, so adopting an engine upgrade never
+ * flips a green build red — but a silent green no-op becomes impossible.
+ */
+function warnIfEmptyCiDiff(resolved, unitCount, deps) {
+    if (resolved.origin !== 'worktree')
+        return;
+    if (unitCount > 0)
+        return;
+    if (!isCiContext(deps.env))
+        return;
+    deps.out(degradationAnnotation(EMPTY_CI_DIFF_NOTICE));
+    appendStepSummary(deps.env, EMPTY_CI_DIFF_NOTICE);
+    deps.err(EMPTY_CI_DIFF_NOTICE);
+}
 // --- analyze ------------------------------------------------------------------
 function loadSpec(path, deps) {
     if (!existsSync(path)) {
@@ -494,6 +623,10 @@ async function postStickyComment(findings, resolution, deps) {
         appendStepSummary(deps.env, res.notice);
     }
 }
+/** 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).`;
+}
 async function prCheckCmd(opts, deps) {
     const [config, warning] = loadGuardianConfig(opts.config);
     if (warning !== null) {
@@ -507,8 +640,12 @@ async function prCheckCmd(opts, deps) {
         throw new CliExit(0);
     }
     const effectiveGate = opts.gate ?? config.pr_gate;
-    const diffText = readDiff(opts.diff ?? null, 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);
     // 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.
@@ -521,9 +658,9 @@ async function prCheckCmd(opts, deps) {
     const weakFindings = config.weak_tests
         ? buildWeakTestFindings(testUnits, diffText)
         : [];
+    const preFilterSkipped = skipped.length + testUnits.length + barrelUnits.length;
     if (kept.length === 0 && weakFindings.length === 0) {
-        deps.out(`guardian: nothing to verify ` +
-            `(${skipped.length + testUnits.length + barrelUnits.length} path(s) skipped).`);
+        deps.out(nothingToVerify(preFilterSkipped));
         throw new CliExit(0);
     }
     const results = resolveCoverage(kept, {
@@ -532,10 +669,21 @@ async function prCheckCmd(opts, deps) {
         // (depth 1); soft stays unbounded. An explicit config value wins.
         graphMaxDepth: effectiveGraphDepth(config, effectiveGate),
     });
+    // #413: drop uncovered HEURISTIC verdicts on paths a naming heuristic can
+    // 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);
     const findings = [
-        ...applySuppressions(buildFindings(results)),
+        ...applySuppressions(buildFindings(scoredResults)),
         ...weakFindings,
     ];
+    // #413: if the heuristic filter consumed every scorable unit, report it as a
+    // 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);
+    }
     // SC-5 (PR half): resolve the requested tier against actual capability. No
     // agent runtime exists (default NoAgentProbe), so any `pr.tier > 0` drops to
     // tier 0 with a LOUD degradation notice.
@@ -602,7 +750,10 @@ function buildGaps(diffText, config, coveragePath, graphMaxDepth) {
     if (kept.length === 0)
         return [];
     const results = resolveCoverage(kept, { coveragePath, graphMaxDepth });
-    return applySuppressions(buildFindings(results));
+    // #413: never hand the authoring tier a heuristic FP -- a generated "test" for
+    // a config dotfile is worse noise than the finding was.
+    const [scored] = filterHeuristicNoise(results, config.heuristic_exclude);
+    return applySuppressions(buildFindings(scored));
 }
 /** Serialize a {@link GeneratedTest} intent for the SKILL (JSON-safe). */
 function intentDict(intent) {
@@ -729,11 +880,15 @@ export function createGuardianCommand(depsInit = {}) {
     program
         .command('pr-check')
         .description('Tier 0 deterministic PR guardian: scope, resolve, gate.')
-        .option('--diff <diff>', "Diff file, '-' for stdin, or omit to use `git diff`.")
+        .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).')
         .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')
+        .option('--heuristic-exclude <glob>', 'Glob whose paths never produce a heuristic-tier finding (repeatable). ' +
+        'Replaces canary.guardian.pr.heuristicExclude for this run. ' +
+        'Coverage/graph-verified findings are unaffected.', (value, previous) => [...(previous ?? []), value])
         .option('--post-comment', 'Post/update the sticky PR comment via the GitHub API (CI).')
         .option('--emit-analysis', 'Write the finding record to the .harness/analyses/ channel ' +
         '(harness handoff, #899); falls back LOUDLY to the sticky comment ' +

package/dist/engine/guardian/coverage.js

@@ -682,6 +682,96 @@ const TEST_PATH_RE = /(^|\/)tests?\/|(^|\/)test_[^/]*\.py$|\.test\.[^/]+$|\.spec
 export function isTestPath(path) {
     return TEST_PATH_RE.test(path);
 }
+/**
+ * Extensions that denote hand-authored, executable program source (#413).
+ *
+ * The membership rule is deliberately simple and defensible: **a programming
+ * language belongs; data, config, markup, and style do not.** `.sh` is in (it is
+ * executable logic — bats/shunit2 exist); `.json`, `.yaml`, `.sql`, `.css`, and
+ * `.html` are out (nothing a naming heuristic could meaningfully judge).
+ *
+ * A repo that disagrees at the margins tunes the glob layer
+ * (`canary.guardian.pr.heuristicExclude`) rather than this list.
+ */
+const SOURCE_EXTENSIONS = new Set([
+    // TS/JS + component dialects.
+    '.ts',
+    '.tsx',
+    '.mts',
+    '.cts',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.vue',
+    '.svelte',
+    '.astro',
+    // Python / Ruby / PHP / Perl / Lua.
+    '.py',
+    '.pyi',
+    '.rb',
+    '.php',
+    '.pl',
+    '.pm',
+    '.lua',
+    // JVM + .NET.
+    '.java',
+    '.kt',
+    '.kts',
+    '.scala',
+    '.groovy',
+    '.clj',
+    '.cljs',
+    '.cs',
+    '.fs',
+    '.vb',
+    // Systems.
+    '.go',
+    '.rs',
+    '.c',
+    '.h',
+    '.cc',
+    '.cpp',
+    '.cxx',
+    '.hpp',
+    '.hh',
+    '.m',
+    '.mm',
+    '.swift',
+    // Functional / scientific / other.
+    '.ex',
+    '.exs',
+    '.erl',
+    '.dart',
+    '.r',
+    '.jl',
+    // Shell.
+    '.sh',
+    '.bash',
+    '.zsh',
+    '.ps1',
+    '.psm1',
+]);
+/**
+ * True if `path` looks like hand-authored program source (#413).
+ *
+ * Used to gate the Tier-3 naming heuristic. That heuristic asks "does any test
+ * file reference this file's stem or a top-level symbol?" — for a config
+ * dotfile, a lockfile, or a data blob there are no symbols and no test will
+ * ever name it, so the verdict is structurally always "uncovered": a guaranteed
+ * false positive rather than a signal. An extension-less file (`Makefile`,
+ * `Dockerfile`) and a bare dotfile (`.eslintrc`) are both non-source.
+ */
+export function isSourcePath(path) {
+    const base = basename(path);
+    // `.eslintrc` — `extname` calls this '' already, but a dotfile WITH a real
+    // extension (`.eslintrc.json`) must be judged on that extension, which the
+    // normal path handles.
+    const ext = extname(base).toLowerCase();
+    if (!ext)
+        return false;
+    return SOURCE_EXTENSIONS.has(ext);
+}
 /**
  * Tier 2: derive coverage from the harness knowledge graph (`GRAPH_VERIFIED`).
  *

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

@@ -28,7 +28,7 @@ import { readFileSync } from 'node:fs';
 import { extname, join } from 'node:path';
 import { readJsonWithWarning } from '../core/config-validation.js';
 import { isAssertionFreeTest } from '../core/quality-scorer.js';
-import { Fidelity, isTestPath, } from './coverage.js';
+import { Fidelity, isSourcePath, isTestPath, } from './coverage.js';
 import { Severity, severitySortKey } from './impact-mapper.js';
 const HUNK_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
 // Suppression annotation: `// canary:allow-untested <reason>` or the `#`
@@ -359,6 +359,58 @@ export function filterTestUnits(units) {
     }
     return [kept, testUnits];
 }
+/**
+ * Default glob layer over the {@link isSourcePath} extension floor (#413).
+ *
+ * These paths carry a *source* extension but still have nothing a naming
+ * heuristic could judge: ambient type declarations have no runtime behavior,
+ * and generated clients/stubs are regenerated from a schema rather than
+ * hand-authored. An explicit `heuristicExclude` in config (even `[]`) replaces
+ * this list; the extension floor is NOT config-defeatable.
+ */
+export const DEFAULT_HEURISTIC_EXCLUDE_GLOBS = [
+    '**/*.d.ts',
+    '**/__generated__/**',
+    '**/generated/**',
+    '**/*.generated.*',
+    '**/*_pb2.py',
+    '**/*.pb.go',
+];
+/**
+ * Partition coverage results, dropping heuristic false positives (#413).
+ *
+ * A result is dropped iff ALL of:
+ *
+ *   - its fidelity is `HEURISTIC` (the last-resort naming tier), AND
+ *   - it is **uncovered** (a covered result raises no finding anyway), AND
+ *   - its path is not program source ({@link isSourcePath}) OR it matches an
+ *     `excludeGlobs` entry.
+ *
+ * The narrowness is the point. A `COVERAGE_VERIFIED` or `GRAPH_VERIFIED`
+ * verdict on the very same path rests on real evidence (an lcov row, a graph
+ * edge) and still fires — the suppression is scoped to the tier, never to the
+ * path. Returns `[kept, dropped]`, order-preserving in both.
+ *
+ * Why this matters beyond noise: the soft→hard gate promotion is earned by
+ * reviewer adjudication feeding `precision = TP / (TP + FP)`. A repo that
+ * routinely touches config files accumulated 👎 on findings that could never
+ * have been true, holding it below its promotion bar indefinitely.
+ */
+export function filterHeuristicNoise(results, excludeGlobs) {
+    const kept = [];
+    const dropped = [];
+    for (const result of results) {
+        const ineligible = result.fidelity === Fidelity.Heuristic &&
+            !result.covered &&
+            (!isSourcePath(result.unit.path) ||
+                excludeGlobs.some((glob) => globMatches(result.unit.path, glob)));
+        if (ineligible)
+            dropped.push(result);
+        else
+            kept.push(result);
+    }
+    return [kept, dropped];
+}
 /**
  * A single guardian finding about a changed unit.
  *
@@ -612,6 +664,46 @@ export function computeExitCode(findings, gate) {
     return 0;
 }
 const STICKY_MARKER = '<!-- canary-pr-guardian -->';
+// Severity → status icon for the sticky comment (encodes severity in form, not
+// just text, so the most urgent findings read at a glance).
+//
+// Written as `\u{...}` escapes, not literal glyphs: this file is `.ts`, and the
+// house rule keeps emitted non-ASCII out of non-Markdown source (see the
+// "Output data glyphs" block in `cli.ts`). They are emitted verbatim.
+/**
+ * Character budget for a rendered sticky comment (#457).
+ *
+ * GitHub rejects an issue/PR comment body over **65,536** characters. The post
+ * path reports that as "could not post", so an over-long body means the gate
+ * silently produces nothing on exactly the large PRs that need it most -- the
+ * same silent-green failure #369 was filed for.
+ *
+ * 60,000 leaves ~5.5k of headroom for anything appended outside `render`
+ * (degradation annotations, upsert wrappers) without inviting a body that only
+ * *just* fits and then breaks when a filename grows.
+ *
+ * The cap applies ONLY to the comment. The `--emit-analysis` JSON record is the
+ * authoritative complete set and is never truncated.
+ */
+export const COMMENT_CHAR_BUDGET = 60_000;
+/** The line that accounts for findings the budget could not fit (#457). */
+function overflowNote(omitted) {
+    return (`<sub>${EM_DASH} and ${omitted} more finding(s) omitted to keep this ` +
+        `comment under GitHub's size limit. The full set is in the analysis ` +
+        `record (\`--emit-analysis\`) and the CI logs.</sub>`);
+}
+const EM_DASH = '\u{2014}';
+const RED_CIRCLE = '\u{1F534}';
+const YELLOW_CIRCLE = '\u{1F7E1}';
+const WHITE_CIRCLE = '\u{26AA}';
+const BABY_CHICK = '\u{1F424}';
+const WHITE_CHECK = '\u{2705}';
+const SEVERITY_ICON = {
+    [Severity.CRITICAL]: RED_CIRCLE,
+    [Severity.HIGH]: RED_CIRCLE,
+    [Severity.MEDIUM]: YELLOW_CIRCLE,
+    [Severity.LOW]: WHITE_CIRCLE,
+};
 /**
  * Escape every non-ASCII (>= U+0080) code unit to a `\uXXXX` sequence, matching
  * Python's `json.dumps(..., ensure_ascii=True)` (the library default). `JSON`
@@ -661,33 +753,79 @@ export function render(findings, fmt, tier = 0, degradedNotice = null) {
     }
     const active = ordered.filter((f) => !f.suppressed);
     const suppressed = ordered.filter((f) => f.suppressed);
+    // A finding's file label shows the path once, appending the unit only when
+    // it is a distinct symbol within the file (never `path (path)`).
+    const fileLabel = (f) => f.unit && f.unit !== f.path
+        ? `\`${f.path}\` → \`${f.unit}\``
+        : `\`${f.path}\``;
+    const cell = (s) => s.replace(/\|/g, '\\|');
+    const CONFIDENCE_NOTE = 'Confidence — **coverage-verified**: measured from a real coverage run · ' +
+        '**graph-verified**: inferred from the call graph · **heuristic**: filename ' +
+        `guess (lowest). tier ${tier}: deterministic check, no LLM.`;
+    const footerLine = `<sub>${CONFIDENCE_NOTE}${degradedNotice ? ` ${EM_DASH} ${degradedNotice}` : ''}</sub>`;
     if (fmt === 'comment') {
-        const lines = [STICKY_MARKER, '## Canary PR Guardian'];
-        lines.push(`**${active.length} unaddressed** / ${suppressed.length} suppressed ` +
-            `finding(s) — fidelity-labeled below.`);
-        for (const finding of ordered) {
-            const mark = finding.suppressed ? ' _(suppressed)_' : '';
-            lines.push(`- **${finding.severity}** \`${finding.path}\` ` +
-                `(${finding.unit}) — _${finding.fidelity}_ — ` +
-                `${finding.evidence}${mark}`);
-        }
-        let footer = `_tier ${tier}_`;
-        if (degradedNotice)
-            footer += ` — ${degradedNotice}`;
-        lines.push(footer);
+        const fileCount = new Set(active.map((f) => f.path)).size;
+        const lines = [STICKY_MARKER];
+        if (active.length === 0) {
+            lines.push(`## ${BABY_CHICK} Canary PR Guardian ${EM_DASH} ` +
+                `${WHITE_CHECK} no test-coverage gaps`);
+            if (suppressed.length) {
+                lines.push(`_${suppressed.length} finding(s) suppressed as intentional._`);
+            }
+        }
+        else {
+            const noun = fileCount === 1 ? 'file needs' : 'files need';
+            lines.push(`## ${BABY_CHICK} Canary PR Guardian ${EM_DASH} ` +
+                `${fileCount} ${noun} test coverage`);
+            lines.push('These lines were changed by this PR but no test exercises them. Add or ' +
+                'extend a test that covers them, or reply ' +
+                '`/guardian suppress <file> <reason>` if they are intentionally untested.');
+            lines.push('', '| Sev | File | What is uncovered | Confidence |', '| --- | --- | --- | --- |');
+            // #457: fill rows against a character budget instead of emitting all of
+            // them. `active` is already severity-ordered, so the rows that survive
+            // are the most severe -- a critical finding is never dropped to make room
+            // for a low one.
+            const suppressedNote = suppressed.length
+                ? `\n\n<sub>${suppressed.length} finding(s) suppressed as intentional and not counted above.</sub>`
+                : '';
+            // Reserved so the tail always fits: footer, suppressed note, and a
+            // worst-case overflow line (the real one is shorter).
+            const reserve = footerLine.length +
+                suppressedNote.length +
+                overflowNote(active.length).length +
+                4;
+            let used = lines.join('\n').length;
+            let shown = 0;
+            for (const f of active) {
+                const row = `| ${SEVERITY_ICON[f.severity] ?? ''} ${f.severity} | ${cell(fileLabel(f))} | ${cell(f.evidence)} | ${f.fidelity} |`;
+                if (used + row.length + 1 + reserve > COMMENT_CHAR_BUDGET)
+                    break;
+                lines.push(row);
+                used += row.length + 1;
+                shown += 1;
+            }
+            const omitted = active.length - shown;
+            if (omitted > 0)
+                lines.push('', overflowNote(omitted));
+            if (suppressed.length) {
+                lines.push('', `<sub>${suppressed.length} finding(s) suppressed as intentional and not counted above.</sub>`);
+            }
+        }
+        lines.push('', footerLine);
         return lines.join('\n');
     }
     // fmt == "text" (default fallback): plain, no markdown/HTML.
     const lines = [
-        `Canary PR Guardian — ${active.length} unaddressed, ` +
-            `${suppressed.length} suppressed`,
+        active.length === 0
+            ? 'Canary PR Guardian — no test-coverage gaps'
+            : `Canary PR Guardian — ${new Set(active.map((f) => f.path)).size} file(s) need test coverage`,
     ];
     for (const finding of ordered) {
+        const unit = finding.unit && finding.unit !== finding.path ? ` → ${finding.unit}` : '';
         const mark = finding.suppressed ? ' (suppressed)' : '';
-        lines.push(`[${finding.severity}] ${finding.path} (${finding.unit}) ` +
-            `[${finding.fidelity}] ${finding.evidence}${mark}`);
+        lines.push(`[${finding.severity}] ${finding.path}${unit} — ${finding.evidence} (${finding.fidelity})${mark}`);
     }
-    let footer = `tier ${tier}`;
+    let footer = `tier ${tier}: deterministic check, no LLM`;
     if (degradedNotice)
         footer += ` - ${degradedNotice}`;
     lines.push(footer);
@@ -716,9 +854,30 @@ export const DEFAULT_SKIP_GLOBS = [
     '**/*.snap',
     // Generated slash-command artifacts and harness state — regenerated from a
     // tracked source (skill.yaml / graph scans), never hand-authored, so a
-    // covering test makes no sense.
+    // covering test makes no sense. `**/.harness/**` also catches harness state
+    // nested under a subproject (e.g. `services/neo/.harness/…`), which the
+    // top-level `.harness/**` misses (#413).
     'agents/commands/**',
     '.harness/**',
+    '**/.harness/**',
+    // Dotfile config/metadata at any depth (.gitignore, .env, .eslintrc,
+    // .neorc*, .dockerignore, .npmrc, …). None carry testable code, so the
+    // heuristic tier's "no test file references this" is a false positive on them
+    // (#413 — observed on `.gitignore` / `.neorc.dev`). Matches only files whose
+    // basename starts with a dot, not source inside a dot-directory.
+    '**/.*',
+    // Build/tooling config files (not authored product logic).
+    '**/*.config.js',
+    '**/*.config.ts',
+    '**/*.config.mjs',
+    '**/*.config.cjs',
+    // Test fixtures / mocks and generated code — noise, not logic under test.
+    '**/fixtures/**',
+    '**/__fixtures__/**',
+    '**/__mocks__/**',
+    '**/testdata/**',
+    '**/generated/**',
+    '**/__generated__/**',
 ];
 /**
  * Parsed `canary.guardian` config block.
@@ -744,6 +903,10 @@ export class GuardianConfig {
     precommit_gate;
     coverage_paths;
     skip_globs;
+    // #413: glob layer suppressing the HEURISTIC tier only (a source path that
+    // still has nothing a naming heuristic can judge). Distinct from
+    // `skip_globs`, which drops a path from the gate entirely at every tier.
+    heuristic_exclude;
     // #320: bound the graph-coverage reverse-BFS. `null` means "gate-derived"
     // (see {@link effectiveGraphDepth} — hard→1 direct edge, soft→unbounded); an
     // explicit int here overrides the gate default on BOTH surfaces.
@@ -758,6 +921,9 @@ export class GuardianConfig {
         this.precommit_gate = init.precommit_gate ?? 'soft';
         this.coverage_paths = init.coverage_paths ?? [];
         this.skip_globs = init.skip_globs ?? [...DEFAULT_SKIP_GLOBS];
+        this.heuristic_exclude = init.heuristic_exclude ?? [
+            ...DEFAULT_HEURISTIC_EXCLUDE_GLOBS,
+        ];
         this.graph_coverage_max_depth = init.graph_coverage_max_depth ?? null;
     }
 }
@@ -927,6 +1093,14 @@ export function loadGuardianConfig(configPath = 'harness.config.json') {
             config.pr_gate = coerceGate(pr['gate'], config.pr_gate, 'pr.gate', warnings);
         }
         config.weak_tests = pyTruthy(pyGet(pr, 'weakTests', config.weak_tests));
+        // #413: same present-vs-absent contract as `skipGlobs` (FIX B) — absent
+        // keeps the built-in default, an explicit list (including `[]`) is honored
+        // verbatim so `heuristicExclude: []` means "no glob layer". The
+        // {@link isSourcePath} extension floor is unaffected either way.
+        const heuristicExclude = pr['heuristicExclude'];
+        if (Array.isArray(heuristicExclude)) {
+            config.heuristic_exclude = heuristicExclude.map((g) => String(g));
+        }
     }
     const precommit = pyGet(block, 'preCommit', {});
     if (isRecord(precommit)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canary-test-cli",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "Canary — AI-powered test automation agent",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,7 @@
   },
   "files": [
     "bin/canary.js",
-    "dist/",
-    "agent/frameworks/registry.json"
+    "dist/"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",