@shrkcrft/cli 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/finish/run-finish.js

@@ -1,15 +1,52 @@
-import { buildImportHygieneReport, filterViolationsToChangedScope, gitShowFile, inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
-import { existsSync } from 'node:fs';
-import * as nodePath from 'node:path';
-import { buildRegistrationGraph, evaluateBoundaries, loadTsconfigPaths, providedTokensFromEntries, registrationTouchesChanged, registrationUnprovided, runPolicyLint, runWiring, scanImports, } from '@shrkcrft/boundaries';
+import { boundaryRuleSourceFiles, buildImportHygieneReport, describeBoundaryConfiguration, gitShowFile, importHygieneCoverage, importHygieneSubjects, inspectSharkcraft, isProjectConfigAbsent, resolveChangedFiles, resolveProjectConfig, runBoundaryCheck, } from '@shrkcrft/inspector';
+import { coverageShortfall, settleRuleStatus, } from '@shrkcrft/core';
+import { buildRegistrationGraph, measureIdiomRoleCoverage, planeScanExcludeDirs, providedTokensFromEntries, registrationTouchesChanged, registrationUnprovidedVerdict, runPolicyLint, runWiring, unreadDirectoryContains, } from '@shrkcrft/boundaries';
 import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
+import { deletedOrphanCoverage } from "../diff/deleted-orphan-coverage.js";
 import { ExitCode } from "../exit-codes.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
+import { seamRejectedRules } from "../gates/seam-rejected-rules.js";
+import { unitStateNotes } from "../gates/unit-state-notes.js";
+import { DEAD_SELECTOR_CAUSES } from '@shrkcrft/core';
 export const FINISH_SCHEMA = 'sharkcraft.finish/v1';
 /** Files in the boundary/import/wiring domain — a change outside it evaluates nothing there. */
 const CODE_FILE = /\.(?:m|c)?[jt]sx?$/;
 function codeFilesOf(files) {
     return files.filter((f) => CODE_FILE.test(f));
 }
+/**
+ * A sub-gate's REPORTED status, settled against its coverage — the ONE place
+ * finish derives `partial`, through core's one rule (`settleRuleStatus`: a
+ * `passed` whose coverage has a shortfall is `partial`). Finish's sub-gates say
+ * `pass`, so the status is spoken in the envelope's vocabulary for the call.
+ * The fold, the text renderer and --json all read the settled gate; none
+ * re-derives it. (The gate envelope re-derives the same word through the same
+ * core function when a `partial` gate is handed to it as `passed`.)
+ */
+function settleFinishGate(g) {
+    const { shortfall: _producerShortfall, ...rest } = g;
+    // Every record the sub-gate settled — `coverage`, then `extraCoverage` —
+    // so a gap in any of them is `partial` and named (round 13 review).
+    const records = [...(g.coverage !== undefined ? [g.coverage] : []), ...(g.extraCoverage ?? [])];
+    // Over several records a gap names its subject (the idiom), or two dead
+    // roles would read as the same sentence twice.
+    const labelled = records.length > 1;
+    const gaps = records.flatMap((c) => {
+        const s = coverageShortfall(c);
+        if (s === undefined)
+            return [];
+        return [{ record: c, shortfall: labelled && c.subject !== undefined ? `${c.subject}: ${s}` : s }];
+    });
+    const first = gaps[0];
+    if (first === undefined)
+        return rest;
+    const settled = settleRuleStatus(g.status === 'pass' ? 'passed' : g.status, first.record);
+    return {
+        ...rest,
+        ...(settled === 'partial' ? { status: 'partial' } : {}),
+        shortfall: gaps.map((x) => x.shortfall).join('; '),
+    };
+}
 /** The base ref the unprovided gate diffs against to spot removed providers. */
 function baseRefFor(input) {
     if (input.mode === 'files')
@@ -43,49 +80,30 @@ export async function runFinishGates(input) {
     const { cwd } = input;
     const changed = resolveChangedFiles(input.scope);
     const changedFiles = changed.files;
-    // The boundary/import/wiring engines only reason about code files. A change to
-    // non-code files (docs, JSON, config) evaluates NOTHING in those gates, so they
-    // must SKIP, not trivially pass — otherwise a markdown-only change paints green
-    // ("evaluated nothing" must read as not-verified, never a `0`).
-    const codeChanged = codeFilesOf(changedFiles);
     const gates = [];
-    // ── boundaries (changed-only) ────────────────────────────────────────
+    // ── boundaries (changed-only, with rule escalation) ──────────────────
     const inspection = await inspectSharkcraft({ cwd });
-    const boundaryRules = inspection.boundaryRegistry.list();
-    if (boundaryRules.length === 0) {
-        gates.push(skip('boundaries', 'no boundary rules configured'));
-    }
-    else if (codeChanged.length === 0) {
-        gates.push(skip('boundaries', 'no code files in changed scope'));
-    }
-    else {
-        const scan = scanImports({ projectRoot: cwd });
-        const tsconfigPaths = loadTsconfigPaths(cwd);
-        const evalResult = evaluateBoundaries(scan, boundaryRules, {
-            ...(tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {}),
-        });
-        const filtered = filterViolationsToChangedScope(evalResult.violations, input.scope);
-        const errors = filtered.includedViolations.filter((v) => v.severity === 'error');
-        const warnings = filtered.includedViolations.filter((v) => v.severity === 'warning');
-        gates.push({
-            name: 'boundaries',
-            status: errors.length > 0 ? 'fail' : 'pass',
-            detail: `${errors.length} error(s), ${warnings.length} warning(s) across ${changedFiles.length} changed file(s)`,
-            errors: errors.length,
-            warnings: warnings.length,
-            items: [...errors, ...warnings].map((v) => ({
-                file: v.file,
-                line: v.line,
-                message: `[${v.severity}] ${v.ruleId}: ${v.message}`,
-            })),
-        });
-    }
+    gates.push(boundariesGate(inspection, { mode: changed.mode, files: changedFiles }));
+    // The boundary/import engines only reason about code files, and a file that
+    // DEFINES rules (a boundaryFiles entry, the config) is a rule source, not a
+    // subject: a changed rule file escalates its rules above; it is never
+    // "scanned" as if it were the change under review. A change to non-code files
+    // evaluates NOTHING here, so these gates SKIP rather than trivially pass.
+    const ruleSources = new Set(boundaryRuleSourceFiles(inspection));
+    const codeChanged = codeFilesOf(changedFiles).filter((f) => !ruleSources.has(f));
     // ── import hygiene (changed-only) ────────────────────────────────────
+    // Hygiene reads existing .ts/.tsx sources only (THE subject list the engine
+    // itself scans): a deleted file, a .js edit or a test fixture put nothing in
+    // front of it, and a pass over nothing is not a pass.
+    const hygieneFiles = importHygieneSubjects(cwd, codeChanged);
     if (codeChanged.length === 0) {
         gates.push(skip('imports', 'no code files in changed scope'));
     }
+    else if (hygieneFiles.length === 0) {
+        gates.push(skip('imports', `no existing .ts/.tsx source in the changed scope (${codeChanged.length} changed code file(s))`));
+    }
     else {
-        const report = buildImportHygieneReport(cwd, { files: codeChanged });
+        const report = buildImportHygieneReport(cwd, { files: hygieneFiles });
         const errors = report.counts?.['error'] ?? (report.verdict === 'errors' ? report.findings.length : 0);
         const warnings = report.counts?.['warning'] ?? (report.verdict === 'warnings' ? report.findings.length : 0);
         // Only the findings that actually DRIVE the verdict become "failing items".
@@ -97,9 +115,12 @@ export async function runFinishGates(input) {
         gates.push({
             name: 'imports',
             status: report.verdict === 'errors' ? 'fail' : 'pass',
-            detail: `verdict=${report.verdict} (${driving.length} of ${report.findings.length} finding(s) drive it)`,
+            detail: `verdict=${report.verdict} (${driving.length} of ${report.findings.length} finding(s) drive it) across ${hygieneFiles.length} changed source file(s)`,
             errors,
             warnings,
+            // THE hygiene coverage fold: an unreadable changed source was never
+            // checked, so a clean result over it settles this sub-gate `partial` (2).
+            coverage: importHygieneCoverage(report, 'changed source files'),
             items: driving.map((f) => ({
                 file: f.file,
                 line: f.line,
@@ -114,7 +135,9 @@ export async function runFinishGates(input) {
         // A MALFORMED config in a real sharkcraft project is a fail (the wiring/
         // policy gates can't be trusted). The mere ABSENCE of a sharkcraft/ folder
         // is not — those gates simply don't apply, so skip them without failing.
-        const isSharkcraftProject = existsSync(nodePath.join(cwd, 'sharkcraft'));
+        // THE "no config at all" answer (`isProjectConfigAbsent`: the loader found
+        // no sharkcraft/ folder) — the quality report's plane row reads it too.
+        const isSharkcraftProject = !isProjectConfigAbsent(loaded.error);
         if (isSharkcraftProject)
             configError = loaded.error.message;
         const detail = isSharkcraftProject
@@ -125,7 +148,17 @@ export async function runFinishGates(input) {
         gates.push(skip('policy', detail));
     }
     else {
-        gates.push(wiringGate(cwd, loaded.value.config.wiringRules ?? [], changedFiles), unprovidedGate(cwd, loaded.value.config.registrationGraph ?? [], changedFiles, baseRefFor(input)), policyGate(cwd, loaded.value.config.policyRules ?? [], changedFiles));
+        // Every plane sub-gate walks THE plane scan scope (`planeScanExcludeDirs`),
+        // the same tree its verb (`check wiring`, `wiring unprovided`,
+        // `policy-lint`) walks for the same rule.
+        const excludeDirs = planeScanExcludeDirs(cwd, loaded.value.sharkcraftDir);
+        // A pack rule the merge seam rejected never runs, whatever changed: its
+        // sub-gate FAILS naming it, as `gates check` fails the same errored row
+        // (round 12 review, R12-X1) — never a "Safe to finish" over a rule that
+        // was silently dropped.
+        const rejected = seamRejectedRules(loaded.value, ['wiring', 'registration', 'policy']);
+        const rejectedOn = (plane) => rejected.filter((r) => r.type === plane);
+        gates.push(withSeamRejections(wiringGate(cwd, loaded.value.config.wiringRules ?? [], changedFiles, excludeDirs), rejectedOn('wiring')), withSeamRejections(unprovidedGate(cwd, loaded.value.config.registrationGraph ?? [], changedFiles, excludeDirs, baseRefFor(input)), rejectedOn('registration')), withSeamRejections(policyGate(cwd, loaded.value.config.policyRules ?? [], changedFiles, excludeDirs), rejectedOn('policy')));
     }
     // ── deleted-orphans (write-safety) ───────────────────────────────────
     gates.push(await orphansGate(input));
@@ -133,46 +166,106 @@ export async function runFinishGates(input) {
     gates.push(await archGate(cwd, changedFiles));
     // ── impact summary (informational, best-effort) ──────────────────────
     const impact = await impactSummary(cwd, changedFiles);
-    // ── fold into one honest 0/1/2 verdict ───────────────────────────────
-    // Only NON-advisory ("deciding") gates decide the verdict. A deciding fail (or
-    // a config that could not load) is `1`. Otherwise, if NO deciding gate actually
-    // evaluated anything (all skipped), the run verified nothing → `2` (never a
-    // green `0`). Only when at least one deciding gate ran over a real scope and
-    // none failed is it a true `0`.
-    const deciding = gates.filter((g) => !g.advisory);
+    // ── settle each sub-gate's reported status, once ─────────────────────
+    // A `pass` whose coverage has a shortfall is `partial` — derived HERE, so the
+    // text renderer and --json show the same word and the fold below reads it.
+    const settledGates = gates.map(settleFinishGate);
+    // ── fold into one honest 0/1/2 verdict — through the shared envelope ──
+    // Only NON-advisory ("deciding") gates decide the verdict, and only the ones
+    // that evaluated something become rows: a skipped sub-gate is narrowing (its
+    // domain had nothing in the changeset), not a gap. The envelope settles the
+    // proposal on every row's coverage and on the run's — so a partial gate is 2,
+    // and a run where NO deciding gate evaluated anything (run coverage expected
+    // 0) is 2 unless `--allow-empty` accepted it. A deciding fail (or a config
+    // that could not load) is 1.
+    const deciding = settledGates.filter((g) => !g.advisory);
+    const evaluatedDeciding = deciding.filter((g) => g.status !== 'skipped');
     const failed = deciding.filter((g) => g.status === 'fail');
-    const anyEvaluated = deciding.some((g) => g.status === 'pass');
-    const warnings = gates.reduce((n, g) => n + g.warnings, 0);
-    let verdict;
-    let exit;
-    if (failed.length > 0 || configError) {
-        verdict = 'fail';
-        exit = ExitCode.Failure;
-    }
-    else if (!anyEvaluated) {
-        verdict = 'not-verified';
-        exit = ExitCode.NotVerified;
-    }
-    else {
-        verdict = 'pass';
-        exit = ExitCode.VerifiedPass;
+    const rows = evaluatedDeciding.flatMap((g) => [
+        {
+            id: g.name,
+            type: 'finish',
+            // A settled `partial` is handed over as `passed` with its coverage: the
+            // builder re-derives `partial` through the same core `settleRuleStatus`.
+            status: g.status === 'fail' ? 'failed' : 'passed',
+            severity: 'error',
+            counts: { errors: g.errors, warnings: g.warnings },
+            violations: g.items.slice(0, 50).map((i) => ({
+                id: i.message,
+                ...(i.file ? { file: i.file } : {}),
+                ...(i.line !== undefined ? { line: i.line } : {}),
+            })),
+            coverage: g.coverage ?? { unit: `${g.name} sub-gate runs`, expected: 1, examined: 1 },
+        },
+        // A sub-gate's further records (round 13 review: the unprovided sub-gate's
+        // other idioms' role records and acceptances) — each its own row, so the
+        // one settle names every gap and prints every acceptance.
+        ...(g.extraCoverage ?? []).map((c, i) => ({
+            id: `${g.name}: ${c.subject ?? `record ${i + 2}`}${c.acceptedBy !== undefined ? ' (accepted)' : ''}`,
+            type: 'finish',
+            status: 'passed',
+            severity: 'error',
+            counts: {},
+            violations: [],
+            coverage: c,
+        })),
+    ]);
+    if (configError) {
+        rows.push({
+            id: 'config',
+            type: 'finish',
+            status: 'error',
+            severity: 'error',
+            counts: {},
+            violations: [],
+            error: `sharkcraft.config.ts did not load: ${configError}`,
+            coverage: { unit: 'config files', expected: 1, examined: 0, reason: 'failed to load' },
+        });
     }
-    const skipped = gates.filter((g) => g.status === 'skipped').map((g) => g.name);
-    const advisoryWarned = gates.filter((g) => g.advisory && g.warnings > 0).map((g) => g.name);
+    const runCoverage = {
+        unit: 'deciding sub-gates',
+        expected: evaluatedDeciding.length,
+        examined: evaluatedDeciding.length,
+        ...(evaluatedDeciding.length === 0
+            ? {
+                reason: changedFiles.length === 0
+                    ? 'nothing changed'
+                    : 'no deciding gate had anything in the changed scope to evaluate',
+            }
+            : {}),
+        ...(input.emptyValve ? input.emptyValve(evaluatedDeciding.length) : {}),
+    };
+    const proposed = failed.length > 0 || configError ? ExitCode.Failure : ExitCode.VerifiedPass;
+    const gate = buildGateEnvelope('finish', proposed, rows, runCoverage);
+    const exit = gate.exit;
+    const verdict = gate.verdict === 'pass' ? 'pass' : gate.verdict === 'fail' ? 'fail' : 'not-verified';
+    const anyEvaluated = evaluatedDeciding.length > 0;
+    const warnings = settledGates.reduce((n, g) => n + g.warnings, 0);
+    const skipped = settledGates.filter((g) => g.status === 'skipped').map((g) => g.name);
+    const advisoryWarned = settledGates.filter((g) => g.advisory && g.warnings > 0).map((g) => g.name);
+    const gateShortfalls = gate.shortfalls;
     const summary = verdict === 'fail'
         ? `Not safe to finish: ${configError ? 'config failed to load; ' : ''}${failed.map((g) => `${g.name} (${g.errors} error(s))`).join(', ') || 'see gates'}.`
-        : verdict === 'not-verified'
-            ? `Not verified: no gate evaluated the changed scope${changedFiles.length === 0 ? ' (nothing changed)' : ' (nothing in it is gate-relevant)'} — this is NOT a pass. Re-run over a scope with code changes, or gate explicitly.`
-            : `Safe to finish: every applicable gate passed${warnings > 0 ? ` (${warnings} non-blocking warning(s)${advisoryWarned.length > 0 ? ` — see ${advisoryWarned.join(', ')}` : ''})` : ''}${skipped.length > 0 ? `; skipped: ${skipped.join(', ')}` : ''}.`;
+        : verdict === 'not-verified' && anyEvaluated
+            ? `Not verified: ${gateShortfalls.slice(0, 3).join('; ')}${gateShortfalls.length > 3 ? `; … (+${gateShortfalls.length - 3} more)` : ''} — this is NOT a pass.`
+            : verdict === 'not-verified'
+                ? `Not verified: no gate evaluated the changed scope${changedFiles.length === 0 ? ' (nothing changed)' : ' (nothing in it is gate-relevant)'} — this is NOT a pass. Re-run over a scope with code changes, or gate explicitly.`
+                : !anyEvaluated
+                    ? 'Nothing to finish: no deciding gate had anything to evaluate — accepted explicitly.'
+                    : `Safe to finish: every applicable gate passed${warnings > 0 ? ` (${warnings} non-blocking warning(s)${advisoryWarned.length > 0 ? ` — see ${advisoryWarned.join(', ')}` : ''})` : ''}${skipped.length > 0 ? `; skipped: ${skipped.join(', ')}` : ''}.`;
     const nextAction = verdict === 'fail'
         ? 'Fix every failing gate item (each carries file:line), then re-run `shrk finish`.'
         : verdict === 'not-verified'
-            ? 'Nothing was verified — do not treat this as done.'
-            : 'Safe to declare done.';
+            ? anyEvaluated
+                ? 'Part of the changed scope was not verified (see "Not verified" above) — do not treat this as done.'
+                : 'Nothing was verified — do not treat this as done.'
+            : anyEvaluated
+                ? 'Safe to declare done.'
+                : 'Nothing was gated — the empty changeset was accepted with --allow-empty.';
     return {
         schema: FINISH_SCHEMA,
         scope: { mode: input.mode, files: changedFiles, fileCount: changedFiles.length },
-        gates,
+        gates: settledGates,
         impact,
         verdict,
         exit,
@@ -180,6 +273,7 @@ export async function runFinishGates(input) {
         ...(configError ? { configError } : {}),
         summary,
         nextAction,
+        gate,
     };
 }
 function skip(name, detail) {
@@ -189,12 +283,199 @@ function skip(name, detail) {
 function advisorySkip(name, detail) {
     return { name, status: 'skipped', detail, errors: 0, warnings: 0, items: [], advisory: true };
 }
-function wiringGate(cwd, rules, changedFiles) {
+/**
+ * A plane sub-gate with the pack rules the merge seam REJECTED folded in: each
+ * is a failing item (it never ran), so the sub-gate fails — skipped or not —
+ * exactly as `gates check` fails the same errored rows (round 12 review,
+ * R12-X1). Unchanged when there are none.
+ */
+function withSeamRejections(gate, rejected) {
+    if (rejected.length === 0)
+        return gate;
+    const note = `${rejected.length} pack rule(s) rejected at the pack-plane merge seam — NOT evaluated`;
+    return {
+        ...gate,
+        status: 'fail',
+        detail: gate.status === 'skipped' ? note : `${gate.detail}, ${note}`,
+        errors: gate.errors + rejected.length,
+        items: [
+            ...gate.items,
+            ...rejected.map((r) => ({ message: `rejected pack rule ${r.id}: ${r.error ?? 'failed validation'}` })),
+        ],
+    };
+}
+/**
+ * One sub-gate's coverage over the rules its changeset SELECTED, folded from
+ * each rule's ENGINE coverage through core's `coverageShortfall` — the rule
+ * `check wiring --changed-only` / `policy-lint --changed-only` / `check
+ * boundaries --changed-only` settle their exit on — so a rule that passed over
+ * part of its scope, or examined nothing at all, is unexamined here exactly as
+ * those verbs count it. Returns the record and the ` — NOT VERIFIED: <rule>:
+ * <shortfall>` detail suffix. `diff-check` folds its boundaries row with it too.
+ */
+export function ruleSetCoverage(unit, rules, reason) {
+    const ruleShortfalls = rules.flatMap((r) => {
+        const s = coverageShortfall(r.coverage);
+        return s === undefined ? [] : [{ id: r.ruleId, shortfall: s }];
+    });
+    const coverage = {
+        unit,
+        expected: rules.length,
+        examined: rules.length - ruleShortfalls.length,
+        ...(ruleShortfalls.length > 0
+            ? {
+                unexamined: ruleShortfalls.slice(0, 20).map((r) => r.id),
+                unexaminedTotal: ruleShortfalls.length,
+                reason,
+            }
+            : {}),
+    };
+    const first = ruleShortfalls[0];
+    const notVerified = first
+        ? ` — NOT VERIFIED: ${first.id}: ${first.shortfall}${ruleShortfalls.length > 1 ? ` (+${ruleShortfalls.length - 1} more)` : ''}`
+        : '';
+    return { coverage, notVerified };
+}
+/** A rule that matched nothing under `failOnEmpty`, as a sub-gate item. */
+function emptyFailureItem(s) {
+    return { message: `[${s.severity}] ${s.ruleId}: matched nothing (failOnEmpty) — ${s.reason}` };
+}
+/**
+ * The boundaries sub-gate — through THE boundary orchestrator, the call `check
+ * boundaries --changed-only`, `diff-check` and the MCP tools make (round 11).
+ *
+ * It closes the two greens closing#d reproduced:
+ *   - a rule EDIT (the changeset touches a rule source, the config or
+ *     tsconfig) escalates those rules to a whole-tree evaluation: the
+ *     violations the edit created in untouched files are this changeset's,
+ *     never "legacy";
+ *   - a change no rule GOVERNS evaluated nothing, so the gate SKIPS — it used to
+ *     report `pass` from an error count of zero over files no rule looks at.
+ * Otherwise it carries the selected rules' coverage, so a rule whose scope glob
+ * went dead settles it `partial`.
+ */
+function boundariesGate(inspection, changed) {
+    const loadIssues = inspection.boundaryLoadIssues ?? [];
+    if (inspection.boundaryRegistry.size() === 0 && loadIssues.length === 0) {
+        const why = describeBoundaryConfiguration(inspection).diagnostics[0];
+        return skip('boundaries', `no boundary rules configured${why ? ` — ${why}` : ''}`);
+    }
+    if (changed.files.length === 0 && loadIssues.length === 0) {
+        return skip('boundaries', 'nothing in the changed scope');
+    }
+    const r = runBoundaryCheck(inspection, { changed });
+    if (r.selectedRuleIds.length === 0 && r.loadIssues.length === 0) {
+        return skip('boundaries', `no changed source file is governed by a boundary rule (${changed.files.length} changed file(s))`);
+    }
+    const errors = r.violations.filter((v) => v.severity === 'error');
+    const warnings = r.violations.filter((v) => v.severity === 'warning');
+    const failedOnEmpty = r.rules.filter((x) => x.failedOnEmpty === true);
+    const escalated = r.changed?.escalatedRuleIds ?? [];
+    const governed = r.changed?.governedFiles.length ?? 0;
+    const { coverage, notVerified } = ruleSetCoverage('boundary rules', r.rules.map((x) => ({ ruleId: x.ruleId, coverage: x.coverage })), 'passed over part of their scope or checked nothing');
+    const detailParts = [
+        `${errors.length} error(s), ${warnings.length} warning(s) across ${governed} governed changed file(s)`,
+    ];
+    if (escalated.length > 0) {
+        const why = [...new Set(r.changed?.escalation.reasons.map((x) => x.file) ?? [])].join(', ');
+        detailParts.push(`${escalated.length} rule(s) escalated (${why} changed) — evaluated repo-wide`);
+    }
+    if (r.loadIssues.length > 0)
+        detailParts.push(`${r.loadIssues.length} errored rule(s)`);
+    if (r.staleExceptions.length > 0)
+        detailParts.push(`${r.staleExceptions.length} stale exception(s)`);
+    if (failedOnEmpty.length > 0)
+        detailParts.push(`${failedOnEmpty.length} matched nothing (failOnEmpty)`);
+    // Round 13 (lane B): dead selector units and went-live expectEmpty markers
+    // are ADVISORY on finish — named in the detail and listed in `notes`, never
+    // items (items are the envelope's violations) and never a failure: finish
+    // runs without --fail-on-dead-units. It used to report `pass` in silence
+    // while `check boundaries` withheld its ✓ over the same tree.
+    // A PACK marker that went live is INFO (round 13 review) — `check
+    // boundaries` prints it in its own INFO block; it never counts as advisory.
+    const advisory = [
+        ...r.deadUnits.map((d) => `[advisory] dead selector unit [${d.unit}] ${d.ruleId}: ${d.selector} — ${d.reason}`),
+        ...r.wentLive.map((u) => `${u.packageName !== undefined ? '[info]' : '[advisory]'} [${u.unit}] ${u.ruleId}: ${u.selector} — ${u.reason}`),
+    ];
+    const localWentLive = r.wentLive.filter((u) => u.packageName === undefined).length;
+    const packWentLive = r.wentLive.length - localWentLive;
+    // Each rule's expectEmpty acceptance (settle record B) — its own envelope row
+    // through `extraCoverage`, so finish's ONE settle prints every acceptance at
+    // exit 0 (round 13 review: they were dropped in silence — the sub-gate's
+    // single `coverage` is the rule-set fold, which cannot carry them).
+    const acceptances = r.rules.flatMap((x) => x.detail.unitAcceptance !== undefined
+        ? [{ ...x.detail.unitAcceptance, subject: x.detail.unitAcceptance.subject ?? x.ruleId }]
+        : []);
+    if (r.deadUnits.length > 0)
+        detailParts.push(`${r.deadUnits.length} dead selector unit(s) (advisory)`);
+    if (localWentLive > 0)
+        detailParts.push(`${localWentLive} expectEmpty marker(s) went live (advisory)`);
+    if (packWentLive > 0)
+        detailParts.push(`${packWentLive} pack expectEmpty marker(s) went live (INFO)`);
+    if (r.intendedEmpty.length > 0)
+        detailParts.push(`${r.intendedEmpty.length} expectEmpty unit(s) intended empty`);
+    return {
+        name: 'boundaries',
+        // The orchestrator's proposal is THE boundary verdict: 1 = something failed.
+        status: r.proposedExit === ExitCode.Failure ? 'fail' : 'pass',
+        detail: `${detailParts.join('; ')}${notVerified}`,
+        errors: errors.length + r.loadIssues.length + r.staleExceptions.length + failedOnEmpty.length,
+        warnings: warnings.length,
+        coverage,
+        ...(acceptances.length > 0 ? { extraCoverage: acceptances } : {}),
+        ...(advisory.length > 0 ? { notes: advisory } : {}),
+        items: [
+            ...[...errors, ...warnings].map((v) => ({
+                file: v.file,
+                line: v.line,
+                message: `[${v.severity}] ${v.ruleId}: ${v.message}`,
+            })),
+            ...r.loadIssues.map((i) => ({
+                file: i.file,
+                message: `[error] ${i.ruleId ?? i.kind}: ${i.issues.join('; ')} — NOT evaluated`,
+            })),
+            ...r.staleExceptions.map((s) => ({ file: s.file, message: `[error] ${s.ruleId}: ${s.message}` })),
+            ...failedOnEmpty.map((x) => emptyFailureItem({ ruleId: x.ruleId, reason: x.skipReason ?? 'no governed file', severity: x.severity })),
+        ],
+    };
+}
+/**
+ * A plane sub-gate's per-rule expectEmpty acceptances and unit notes (round 13
+ * review): the acceptances ride beside the rule-set fold as `extraCoverage`
+ * (one envelope row each, as the boundaries sub-gate does), so finish's ONE
+ * settle prints every one at exit 0 — `check wiring` / `policy-lint` printed
+ * them while finish dropped them in silence. A dead glob of a rule that still
+ * matched and a LOCAL marker whose target appeared are ADVISORY notes; a pack
+ * marker is `[info]` — worded by THE shared unit-state renderer. Never a
+ * failure: finish runs without --fail-on-dead-units.
+ */
+function planeUnitFields(rules, emptyIds) {
+    const extra = rules.flatMap((r) => r.unitAcceptance !== undefined ? [{ ...r.unitAcceptance, subject: r.unitAcceptance.subject ?? r.ruleId }] : []);
+    const n = unitStateNotes(rules.map((r) => ({
+        id: r.ruleId,
+        ...(r.unitLiveness !== undefined ? { unitLiveness: r.unitLiveness } : {}),
+        reportedEmpty: emptyIds.has(r.ruleId),
+    })));
+    const notes = [
+        ...n.deadLines.map((l) => `[advisory] dead selector unit ${l} — ${DEAD_SELECTOR_CAUSES}`),
+        ...n.localWentLiveLines.map((l) => `[advisory] ${l}`),
+        ...n.packWentLiveLines.map((l) => `[info] ${l}`),
+    ];
+    return { ...(extra.length > 0 ? { extraCoverage: extra } : {}), ...(notes.length > 0 ? { notes } : {}) };
+}
+function wiringGate(cwd, rules, changedFiles, excludeDirs) {
     if (rules.length === 0)
         return skip('wiring', 'no wiring rules configured');
-    const report = runWiring(cwd, rules, { changedOnly: true, changedFiles });
-    if (report.evaluated === 0) {
-        return skip('wiring', `${report.rules.length} rule(s) configured but none matched the changed scope`);
+    const report = runWiring(cwd, rules, { changedOnly: true, changedFiles, excludeDirs });
+    // Skip ONLY when the changeset selected no rule (no rule's footprint
+    // intersects it) — deliberate narrowing. A SELECTED rule that examined
+    // nothing (its source globs matched no files) is not narrowing: it falls
+    // through, carries its coverage, and settles this sub-gate `partial` (2) or
+    // `fail` (1, an error-severity failOnEmpty rule) — exactly where `check
+    // wiring --changed-only` reads 2 / 1. (Skipping on `evaluated === 0` read
+    // "Safe to finish", exit 0, over a rule that had checked nothing.)
+    if (report.rules.length === 0) {
+        return skip('wiring', `${rules.length} rule(s) configured, none in the changed scope`);
     }
     const errors = report.violations.filter((v) => v.severity === 'error');
     const warnings = report.violations.filter((v) => v.severity === 'warning');
@@ -202,12 +483,23 @@ function wiringGate(cwd, rules, changedFiles) {
     // rule-level error but NO violation — it must FAIL the gate, never read as a
     // silent green ("loud, never silent green").
     const diag = report.diagnostics;
+    // A rule that matched nothing under failOnEmpty carries no violation either:
+    // it is counted and listed so a failing sub-gate names what failed.
+    const emptyFailed = report.skipped.filter((s) => s.failed);
+    // Round 11: what this sub-gate examined — every selected rule's engine
+    // coverage through core's shortfall rule, so a rule that passed over part of
+    // its scope (a subset rule whose declared selector never produced some
+    // registered tokens) or checked nothing keeps this sub-gate from counting as
+    // a pass (the settle step reports it `partial` and the composite is 2).
+    const { coverage, notVerified } = ruleSetCoverage('wiring rules', report.rules, 'passed over part of their scope or checked nothing');
     return {
+        ...planeUnitFields(report.rules, new Set(report.skipped.map((s) => s.ruleId))),
         name: 'wiring',
         status: report.verdict === 'errors' || diag.length > 0 ? 'fail' : 'pass',
-        detail: `${report.evaluated}/${report.rules.length} rule(s) evaluated — ${errors.length} error(s), ${warnings.length} warning(s)${diag.length > 0 ? `, ${diag.length} misconfigured` : ''}`,
-        errors: errors.length + diag.length,
-        warnings: warnings.length,
+        detail: `${report.evaluated}/${report.rules.length} rule(s) evaluated — ${errors.length} error(s), ${warnings.length} warning(s)${diag.length > 0 ? `, ${diag.length} misconfigured` : ''}${emptyFailed.length > 0 ? `, ${emptyFailed.length} matched nothing (failOnEmpty)` : ''}${notVerified}`,
+        errors: errors.length + diag.length + emptyFailed.filter((s) => s.severity === 'error').length,
+        warnings: warnings.length + emptyFailed.filter((s) => s.severity === 'warning').length,
+        coverage,
         items: [
             ...report.violations.map((v) => ({
                 file: v.file,
@@ -215,25 +507,40 @@ function wiringGate(cwd, rules, changedFiles) {
                 message: `[${v.severity}] ${v.ruleId}: "${v.token}" ${v.direction === 'registered-missing' ? 'registered but not declared' : 'declared but not registered'}`,
             })),
             ...diag.map((d) => ({ message: `misconfigured rule: ${d}` })),
+            ...emptyFailed.map(emptyFailureItem),
         ],
     };
 }
-function policyGate(cwd, rules, changedFiles) {
+function policyGate(cwd, rules, changedFiles, excludeDirs) {
     if (rules.length === 0)
         return skip('policy', 'no policy rules configured');
-    const report = runPolicyLint(cwd, rules, { changedOnly: true, changedFiles });
-    if (report.evaluated === 0) {
-        return skip('policy', `${report.rules.length} rule(s) configured but none matched the changed scope`);
+    // The SharkCraft asset dir holds the rule definitions themselves (which can
+    // self-match): pruned through THE plane scan scope, exactly as `policy-lint`.
+    const report = runPolicyLint(cwd, rules, { changedOnly: true, changedFiles, excludeDirs });
+    // Same shape as the wiring sub-gate: skip ONLY when no rule is in the
+    // changed scope. The engine already narrows a rule out when the change put
+    // no content in front of it (only deleted files, or files with nothing on its
+    // surface), so a rule still SELECTED here that scanned nothing left real
+    // scope unexamined: it settles this sub-gate `partial` (2), or `fail` (1)
+    // under failOnEmpty — exactly where `policy-lint --changed-only` reads 2 / 1.
+    if (report.rules.length === 0) {
+        return skip('policy', `${rules.length} rule(s) configured, none with content in the changed scope`);
     }
     const errors = report.findings.filter((f) => f.severity === 'error');
     const warnings = report.findings.filter((f) => f.severity === 'warning');
     const diag = report.diagnostics;
+    // `policy-lint` fails on ANY failOnEmpty skip (its proposed exit is 1), so
+    // this sub-gate fails on one too, and counts it as an error.
+    const emptyFailed = report.skipped.filter((s) => s.failed);
+    const { coverage, notVerified } = ruleSetCoverage('policy rules', report.rules, 'examined only part of their scope, scanned nothing, or could not run');
     return {
+        ...planeUnitFields(report.rules, new Set(report.skipped.map((s) => s.ruleId))),
         name: 'policy',
-        status: report.verdict === 'errors' || diag.length > 0 ? 'fail' : 'pass',
-        detail: `${report.evaluated}/${report.rules.length} rule(s) evaluated — ${errors.length} error(s), ${warnings.length} warning(s)${diag.length > 0 ? `, ${diag.length} misconfigured` : ''}`,
-        errors: errors.length + diag.length,
+        status: report.verdict === 'errors' || diag.length > 0 || emptyFailed.length > 0 ? 'fail' : 'pass',
+        detail: `${report.evaluated}/${report.rules.length} rule(s) evaluated — ${errors.length} error(s), ${warnings.length} warning(s)${diag.length > 0 ? `, ${diag.length} misconfigured` : ''}${emptyFailed.length > 0 ? `, ${emptyFailed.length} matched nothing (failOnEmpty)` : ''}${notVerified}`,
+        errors: errors.length + diag.length + emptyFailed.length,
         warnings: warnings.length,
+        coverage,
         items: [
             ...report.findings.map((f) => ({
                 file: f.file,
@@ -241,6 +548,7 @@ function policyGate(cwd, rules, changedFiles) {
                 message: `[${f.severity}] ${f.ruleId}: ${f.message ?? ''}`.trim(),
             })),
             ...diag.map((d) => ({ message: `misconfigured rule: ${d}` })),
+            ...emptyFailed.map(emptyFailureItem),
         ],
     };
 }
@@ -252,10 +560,10 @@ function policyGate(cwd, rules, changedFiles) {
  * fails) when no idioms are configured or the change touched no wiring — so a
  * repo that never modeled its DI is not penalized.
  */
-function unprovidedGate(cwd, idioms, changedFiles, baseRef) {
+function unprovidedGate(cwd, idioms, changedFiles, excludeDirs, baseRef) {
     if (idioms.length === 0)
         return skip('unprovided', 'no registration idioms configured');
-    const graph = buildRegistrationGraph(cwd, idioms);
+    const graph = buildRegistrationGraph(cwd, idioms, { excludeDirs });
     const diag = graph.diagnostics;
     // Two ways THIS change can leave a token unprovided:
     //  (1) a declared/injected site added in a changed file with no provider —
@@ -263,32 +571,65 @@ function unprovidedGate(cwd, idioms, changedFiles, baseRef) {
     //  (2) the last PROVIDER removed from a changed file — which leaves NO site in
     //      the changed file, so (1) structurally can't see it. Recover it by
     //      diffing the base content of the changed files (providerRegressions).
-    const scoped = registrationUnprovided(graph, changedFiles);
     const regressions = baseRef ? providerRegressions(cwd, idioms, graph, changedFiles, baseRef) : [];
-    const byToken = new Map();
-    for (const u of [...scoped, ...regressions])
-        if (!byToken.has(u.token))
-            byToken.set(u.token, u);
-    const unprovided = [...byToken.values()].sort((a, b) => a.token.localeCompare(b.token));
+    // Settled against what the graph READ, through the one boundaries helper
+    // `wiring unprovided` and MCP `get_wiring_graph` use. A file an idiom
+    // matched that the reader could not read (over the read cap) holds sites the
+    // graph never saw: a token whose provider could sit there is `unproven` —
+    // not a failure, and never a pass (its coverage names the token and file).
+    // Round 13 (P4): and against what every idiom's ROLES examined, from THE
+    // role authority `gates check` reads — a declared role that matched no file
+    // printed `✓ unprovided pass` here while `gates check` said NOT VERIFIED.
+    const verdict = registrationUnprovidedVerdict(graph, idioms, measureIdiomRoleCoverage(cwd, idioms, excludeDirs), changedFiles, regressions);
+    const unprovided = verdict.findings;
+    const candidates = unprovided.length + verdict.unproven.length;
+    // A CHANGED unread file is scope this change put in front of the gate, so it
+    // keeps the gate from skipping — so does a changed file beneath a directory
+    // the reader could not list.
+    const unreadChanged = (graph.readScope?.unread ?? []).filter((u) => changedFiles.includes(u.path) || changedFiles.some((f) => unreadDirectoryContains(u, f)));
     // Skip (evaluated nothing) only when the change touched no registration site
     // AND removed no provider AND has no misconfigured idiom — never a silent pass.
-    if (!registrationTouchesChanged(graph, changedFiles) && unprovided.length === 0 && diag.length === 0) {
+    if (!registrationTouchesChanged(graph, changedFiles) &&
+        candidates === 0 &&
+        diag.length === 0 &&
+        unreadChanged.length === 0) {
         return skip('unprovided', 'no registration sites in the changed scope');
     }
+    // The most specific record: the demoted tokens (their reason names the
+    // unread file), else the first record with a gap — the unread idiom files,
+    // or an idiom role that examined nothing (round 13, P4) — else an
+    // expectEmpty acceptance (printed at 0), else the first. A full record
+    // picked over a gap would settle `pass` over a dead role.
+    const coverage = verdict.coverage.find((c) => c.subject === 'unprovided') ??
+        verdict.coverage.find((c) => coverageShortfall(c) !== undefined) ??
+        verdict.coverage.find((c) => c.acceptedBy !== undefined) ??
+        verdict.coverage[0];
+    // Every OTHER record rides beside it (round 13 review) — one per idiom: a
+    // second idiom's acceptance or dead role is never dropped.
+    const extraCoverage = verdict.coverage.filter((c) => c !== coverage);
+    const siteOf = (u) => {
+        const site = u.declared[0] ?? u.consumed[0];
+        return site ? { file: site.file, line: site.line } : {};
+    };
     return {
         name: 'unprovided',
         status: unprovided.length > 0 || diag.length > 0 ? 'fail' : 'pass',
-        detail: `${unprovided.length} unprovided token(s) attributable to the change${diag.length > 0 ? `, ${diag.length} misconfigured idiom(s)` : ''}`,
+        detail: `${unprovided.length} unprovided token(s) attributable to the change` +
+            `${verdict.unproven.length > 0 ? `, ${verdict.unproven.length} not verified (a provider may sit in an unread file)` : ''}` +
+            `${diag.length > 0 ? `, ${diag.length} misconfigured idiom(s)` : ''}`,
         errors: unprovided.length + diag.length,
         warnings: 0,
+        ...(coverage ? { coverage } : {}),
+        ...(extraCoverage.length > 0 ? { extraCoverage } : {}),
         items: [
-            ...unprovided.map((u) => {
-                const site = u.declared[0] ?? u.consumed[0];
-                return {
-                    ...(site ? { file: site.file, line: site.line } : {}),
-                    message: `"${u.token}" declared/injected but never provided (silent at runtime)`,
-                };
-            }),
+            ...unprovided.map((u) => ({
+                ...siteOf(u),
+                message: `"${u.token}" declared/injected but never provided (silent at runtime)`,
+            })),
+            ...verdict.unproven.map((u) => ({
+                ...siteOf(u),
+                message: `"${u.token}" has no provider among the files read — NOT VERIFIED (a provider may sit in an unread file)`,
+            })),
             ...diag.map((d) => ({ message: `misconfigured idiom: ${d}` })),
         ],
     };
@@ -376,6 +717,13 @@ async function orphansGate(input) {
     }
     if (scan.deleted.length === 0)
         return skip('orphans', `nothing deleted (vs ${scan.ref})`);
+    // What the orphan query examined — the ONE authority `check orphans` settles
+    // on: deleted files the index knows, over an index current for every
+    // surviving importer. A delete of nothing the graph indexes (a README, a
+    // `dist/*.js`) evaluates nothing here, so the sub-gate skips.
+    const coverage = deletedOrphanCoverage(scan);
+    if (coverage.expected === 0)
+        return skip('orphans', coverage.reason ?? 'no deleted code files');
     const orphans = scan.report?.orphans ?? [];
     return {
         name: 'orphans',
@@ -383,6 +731,7 @@ async function orphansGate(input) {
         detail: `${scan.deleted.length} deleted file(s) (vs ${scan.ref}) — ${orphans.length} surviving importer(s)`,
         errors: orphans.length,
         warnings: 0,
+        coverage,
         items: orphans.map((o) => ({
             file: o.path ?? o.id,
             ...(typeof o.line === 'number' ? { line: o.line } : {}),