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

package/dist/commands/diagnostics.command.js

@@ -1,7 +1,9 @@
-import { readFileSync } from 'node:fs';
-import { buildDiagnosticByCode, getDiagnosticEntry, listDiagnostics, renderDiagnosticText, suggestDiagnostic, } from '@shrkcrft/inspector';
-import { flagBool, flagString, flagList, } from "../command-registry.js";
+import { listDiagnostics } from '@shrkcrft/inspector';
+import { flagBool } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+// `diagnostics get` / `diagnostics suggest` were pruned from the surface (r48);
+// their handlers lingered here unregistered, still printing usage for commands
+// that exit 2. `list` is the one registered verb.
 export const diagnosticsListCommand = {
     name: 'list',
     description: 'List known SharkCraft failure diagnostics. Read-only.',
@@ -20,78 +22,3 @@ export const diagnosticsListCommand = {
         return 0;
     },
 };
-export const diagnosticsGetCommand = {
-    name: 'get',
-    description: 'Look up a SharkCraft failure diagnostic by code. Read-only.',
-    usage: 'shrk diagnostics get <code> [--ctx key=value ...] [--json]',
-    async run(args) {
-        const code = args.positional[0];
-        if (!code) {
-            process.stderr.write('Usage: shrk diagnostics get <code> [--ctx key=value ...]\n');
-            return 2;
-        }
-        const entry = getDiagnosticEntry(code);
-        if (!entry) {
-            process.stderr.write(`Unknown diagnostic code "${code}". Try \`shrk diagnostics list\`.\n`);
-            return 2;
-        }
-        const ctx = {};
-        for (const raw of flagList(args, 'ctx')) {
-            const i = raw.indexOf('=');
-            if (i < 0)
-                continue;
-            const key = raw.slice(0, i).trim();
-            const value = raw.slice(i + 1);
-            ctx[key] = value;
-        }
-        const diagnostic = buildDiagnosticByCode(entry.code, ctx);
-        if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(diagnostic) + '\n');
-            return 0;
-        }
-        process.stdout.write(renderDiagnosticText(diagnostic));
-        return 0;
-    },
-};
-export const diagnosticsSuggestCommand = {
-    name: 'suggest',
-    description: 'Suggest the most likely diagnostic for a stderr blob. Read-only.',
-    usage: 'shrk diagnostics suggest "<error text>" | --from-file <file> [--json]',
-    async run(args) {
-        const fromFile = flagString(args, 'from-file');
-        let input = args.positional.join(' ').trim();
-        if (fromFile) {
-            try {
-                input = readFileSync(fromFile, 'utf8');
-            }
-            catch (err) {
-                process.stderr.write(`Failed to read --from-file: ${err instanceof Error ? err.message : String(err)}\n`);
-                return 1;
-            }
-        }
-        if (!input) {
-            process.stderr.write('Usage: shrk diagnostics suggest "<error text>" or --from-file <file>\n');
-            return 2;
-        }
-        const r = suggestDiagnostic(input);
-        if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(r) + '\n');
-            return 0;
-        }
-        if (!r.topSuggestion) {
-            process.stdout.write('No matching diagnostic found.\n');
-            return 1;
-        }
-        process.stdout.write(`Top suggestion: ${r.topSuggestion.code} (${r.topSuggestion.confidence})\n`);
-        process.stdout.write(`  title: ${r.topSuggestion.title}\n`);
-        process.stdout.write(`  next:  ${r.topSuggestion.nextCommand}\n`);
-        if (r.topSuggestion.docsLink)
-            process.stdout.write(`  docs:  ${r.topSuggestion.docsLink}\n`);
-        if (r.candidates.length > 1) {
-            process.stdout.write('Other candidates:\n');
-            for (const c of r.candidates.slice(1))
-                process.stdout.write(`  ${c.code} (${c.confidence})\n`);
-        }
-        return 0;
-    },
-};

package/dist/commands/diff-check.command.d.ts

@@ -8,7 +8,8 @@
  *      import-hygiene check to only the files the agent touched in the
  *      current git diff.
  *   4. The output is a single agent-friendly JSON envelope with a
- *      verdict (ok / warnings / errors) and a one-line next action.
+ *      verdict (ok / warnings / errors / not-verified) and a one-line next
+ *      action.
  *
  * Why a new command instead of "just run `shrk check boundaries
  * --changed-only` and `shrk check imports --changed-only`":
@@ -21,9 +22,10 @@
  *   - Concrete `nextAction` line — the agent knows exactly what to do
  *     next (declare done, fix N things, or re-run after a manual fix).
  *
- * This is a pure composer — all real logic stays in
- * `@shrkcrft/inspector` and `@shrkcrft/boundaries`. We just stitch
- * their outputs together with consistent scoping.
+ * Round 11: the boundary half goes through THE boundary orchestrator (a rule
+ * edit escalates to the whole tree; a change no rule governs is NOT a pass),
+ * and the verdict is settled by the shared gate envelope — an empty diff, or a
+ * diff nothing examined, is `not-verified` (2), never "Diff passes the gate".
  */
 import { type ICommandHandler } from '../command-registry.js';
 export declare const diffCheckCommand: ICommandHandler;

package/dist/commands/diff-check.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff-check.command.d.ts","sourceRoot":"","sources":["../../src/commands/diff-check.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6GhC,eAAO,MAAM,gBAAgB,EAAE,eAkI9B,CAAC"}
+{"version":3,"file":"diff-check.command.d.ts","sourceRoot":"","sources":["../../src/commands/diff-check.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAcH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6EhC,eAAO,MAAM,gBAAgB,EAAE,eAiP9B,CAAC"}

package/dist/commands/diff-check.command.js

@@ -8,7 +8,8 @@
  *      import-hygiene check to only the files the agent touched in the
  *      current git diff.
  *   4. The output is a single agent-friendly JSON envelope with a
- *      verdict (ok / warnings / errors) and a one-line next action.
+ *      verdict (ok / warnings / errors / not-verified) and a one-line next
+ *      action.
  *
  * Why a new command instead of "just run `shrk check boundaries
  * --changed-only` and `shrk check imports --changed-only`":
@@ -21,14 +22,19 @@
  *   - Concrete `nextAction` line — the agent knows exactly what to do
  *     next (declare done, fix N things, or re-run after a manual fix).
  *
- * This is a pure composer — all real logic stays in
- * `@shrkcrft/inspector` and `@shrkcrft/boundaries`. We just stitch
- * their outputs together with consistent scoping.
+ * Round 11: the boundary half goes through THE boundary orchestrator (a rule
+ * edit escalates to the whole tree; a change no rule governs is NOT a pass),
+ * and the verdict is settled by the shared gate envelope — an empty diff, or a
+ * diff nothing examined, is `not-verified` (2), never "Diff passes the gate".
  */
-import { buildImportHygieneReport, filterViolationsToChangedScope, inspectSharkcraft, resolveChangedFiles, } from '@shrkcrft/inspector';
-import { evaluateBoundaries, loadTsconfigPaths, scanImports, } from '@shrkcrft/boundaries';
+import { boundaryRulesEvaluated, buildImportHygieneReport, describeBoundaryConfiguration, importHygieneCoverage, importHygieneSubjects, inspectSharkcraft, resolveChangedFiles, runBoundaryCheck, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, bullet, header, kv } from "../output/format-output.js";
+import { ExitCode } from "../exit-codes.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
+import { ALLOW_EMPTY_FLAG, allowEmptyValve } from "../gates/allow-empty.js";
+import { verdictLine } from "../gates/verdict-line.js";
+import { ruleSetCoverage } from "../finish/run-finish.js";
 const SCHEMA = 'sharkcraft.diff-check/v1';
 function resolveScope(args, cwd) {
     const staged = flagBool(args, 'staged');
@@ -55,53 +61,14 @@ function resolveScope(args, cwd) {
         options: { projectRoot: cwd, includeWorktree: true },
     };
 }
-function deriveVerdict(env) {
-    const bErr = env.boundaries.counts.error;
-    const bWarn = env.boundaries.counts.warning;
-    const iErr = env.imports.verdict === 'errors' ? (env.imports.counts.error ?? env.imports.findings.length) : 0;
-    const iWarn = env.imports.verdict === 'warnings' ? (env.imports.counts.warning ?? env.imports.findings.length) : 0;
-    if (env.scope.fileCount === 0) {
-        return {
-            verdict: 'ok',
-            summary: 'No files changed in the current diff scope.',
-            nextAction: 'Nothing to check. If you expected changes, verify your `--staged` / `--since <ref>` flag or save your edits first.',
-        };
-    }
-    if (bErr > 0 || iErr > 0) {
-        const parts = [];
-        if (bErr > 0)
-            parts.push(`${bErr} boundary violation${bErr === 1 ? '' : 's'}`);
-        if (iErr > 0)
-            parts.push(`${iErr} import-hygiene error${iErr === 1 ? '' : 's'}`);
-        return {
-            verdict: 'errors',
-            summary: `Diff fails the gate: ${parts.join(', ')}.`,
-            nextAction: 'Fix every error in `boundaries.violations` and `imports.findings` (look at each entry\'s `suggestedFix` line), then re-run `shrk diff-check`.',
-        };
-    }
-    if (bWarn > 0 || iWarn > 0) {
-        const parts = [];
-        if (bWarn > 0)
-            parts.push(`${bWarn} boundary warning${bWarn === 1 ? '' : 's'}`);
-        if (iWarn > 0)
-            parts.push(`${iWarn} import-hygiene warning${iWarn === 1 ? '' : 's'}`);
-        return {
-            verdict: 'warnings',
-            summary: `Diff passes the gate with ${parts.join(', ')}.`,
-            nextAction: 'Safe to declare done. Review warnings if the diff touches a sensitive area; otherwise these are non-blocking.',
-        };
-    }
-    return {
-        verdict: 'ok',
-        summary: `Diff passes the gate (${env.scope.fileCount} file${env.scope.fileCount === 1 ? '' : 's'}, 0 violations).`,
-        nextAction: 'Safe to declare done.',
-    };
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? '' : 's'}`;
 }
 export const diffCheckCommand = {
     name: 'diff-check',
-    description: 'Self-check the current git diff against this project\'s boundary + import-hygiene rules. Single-call composite of `shrk check boundaries --changed-only` + `shrk check imports --changed-only`, with one verdict and one nextAction line. Designed for AI agents to run after editing — pass --json for the structured envelope.',
-    usage: 'shrk [--cwd <dir>] diff-check [files... | --files a.ts,b.ts | --staged | --since <ref>] [--json]',
-    booleanFlags: new Set(['json', 'staged']),
+    description: 'Self-check the current git diff against this project\'s boundary + import-hygiene rules. Single-call composite of `shrk check boundaries --changed-only` (rule edits escalate to the whole tree) + `shrk check imports --changed-only`, with one verdict and one nextAction line. An empty diff, or one nothing examined, is not-verified (exit 2). Designed for AI agents to run after editing — pass --json for the structured envelope.',
+    usage: 'shrk [--cwd <dir>] diff-check [files... | --files a.ts,b.ts | --staged | --since <ref>] [--allow-empty] [--json]',
+    booleanFlags: new Set(['json', 'staged', ALLOW_EMPTY_FLAG]),
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');
@@ -109,44 +76,78 @@ export const diffCheckCommand = {
         // 1. Resolve the changed file set once. Both engines re-use it.
         const changed = resolveChangedFiles(scopeOptions);
         const changedFiles = changed.files;
-        // 2. Boundary engine — only if rules exist.
         const inspection = await inspectSharkcraft({ cwd });
-        const rules = inspection.boundaryRegistry.list();
+        const rows = [];
+        // 2. Boundary engine — THE orchestrator, escalation included.
         let boundaryBlock = {
             ran: false,
             rulesEvaluated: 0,
             counts: { error: 0, warning: 0, info: 0 },
             violations: [],
         };
-        if (rules.length > 0 && changedFiles.length > 0) {
-            const scan = scanImports({ projectRoot: cwd });
-            const tsconfigPaths = loadTsconfigPaths(cwd);
-            const evalResult = evaluateBoundaries(scan, rules, {
-                ...(tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {}),
-            });
-            const filtered = filterViolationsToChangedScope(evalResult.violations, scopeOptions);
-            boundaryBlock = {
-                ran: true,
-                rulesEvaluated: evalResult.rulesEvaluated,
-                counts: {
-                    error: filtered.includedViolations.filter((v) => v.severity === 'error').length,
-                    warning: filtered.includedViolations.filter((v) => v.severity === 'warning').length,
-                    info: filtered.includedViolations.filter((v) => v.severity === 'info').length,
-                },
-                violations: filtered.includedViolations,
-            };
+        const loadIssues = inspection.boundaryLoadIssues ?? [];
+        if (inspection.boundaryRegistry.size() === 0 && loadIssues.length === 0) {
+            boundaryBlock.reason =
+                describeBoundaryConfiguration(inspection).diagnostics[0] ?? 'no boundary rules configured';
         }
-        else if (rules.length > 0 && changedFiles.length === 0) {
-            boundaryBlock = { ...boundaryBlock, ran: true, rulesEvaluated: rules.length };
+        else if (changedFiles.length === 0 && loadIssues.length === 0) {
+            boundaryBlock.reason = 'no changed files in the diff scope';
         }
-        // 3. Import-hygiene engine — always runs, but scoped to changed files.
+        else {
+            const r = runBoundaryCheck(inspection, { changed: { mode: changed.mode, files: changedFiles } });
+            if (r.selectedRuleIds.length === 0 && r.loadIssues.length === 0) {
+                boundaryBlock.reason = 'no changed source file is governed by a boundary rule';
+            }
+            else {
+                const { coverage } = ruleSetCoverage('boundary rules', r.rules.map((x) => ({ ruleId: x.ruleId, coverage: x.coverage })), 'passed over part of their scope or checked nothing');
+                const escalated = r.changed?.escalatedRuleIds ?? [];
+                boundaryBlock = {
+                    ran: true,
+                    rulesEvaluated: boundaryRulesEvaluated(r),
+                    counts: r.counts,
+                    violations: r.violations,
+                    ...(escalated.length > 0
+                        ? {
+                            escalation: {
+                                ruleIds: escalated,
+                                files: [...new Set(r.changed?.escalation.reasons.map((x) => x.file) ?? [])],
+                            },
+                        }
+                        : {}),
+                    ...(r.loadIssues.length > 0
+                        ? { loadIssues: r.loadIssues }
+                        : {}),
+                    ...(r.staleExceptions.length > 0
+                        ? { staleExceptions: r.staleExceptions }
+                        : {}),
+                    coverage,
+                };
+                rows.push({
+                    id: 'boundaries',
+                    type: 'diff',
+                    status: r.proposedExit === ExitCode.Failure ? 'failed' : 'passed',
+                    severity: 'error',
+                    counts: { errors: r.counts.error, warnings: r.counts.warning, rules: r.selectedRuleIds.length },
+                    violations: r.violations.map((v) => ({ id: v.importSpecifier, file: v.file, line: v.line, message: v.message })),
+                    coverage,
+                });
+            }
+        }
+        // 3. Import-hygiene engine — over the changed sources it actually reads.
         let importsBlock = {
             ran: false,
             verdict: 'skipped',
             counts: {},
             findings: [],
         };
-        if (changedFiles.length > 0) {
+        const hygieneFiles = changedFiles.length > 0 ? importHygieneSubjects(cwd, changedFiles) : [];
+        if (changedFiles.length === 0) {
+            importsBlock.reason = 'no changed files in the diff scope';
+        }
+        else if (hygieneFiles.length === 0) {
+            importsBlock.reason = 'no changed .ts/.tsx source for import hygiene to read';
+        }
+        else {
             const report = buildImportHygieneReport(cwd, { files: changedFiles });
             importsBlock = {
                 ran: true,
@@ -154,61 +155,147 @@ export const diffCheckCommand = {
                 counts: report.counts ?? {},
                 findings: report.findings,
             };
+            rows.push({
+                id: 'imports',
+                type: 'diff',
+                status: report.verdict === 'errors' ? 'failed' : 'passed',
+                severity: 'error',
+                counts: { findings: report.findings.length },
+                violations: report.findings
+                    .filter((f) => f.severity === 'error')
+                    .map((f) => ({ id: f.kind, file: f.file, line: f.line })),
+                // THE hygiene coverage fold — an unreadable changed source is unexamined.
+                coverage: importHygieneCoverage(report, 'changed source files'),
+            });
+        }
+        // 4. Settle the verdict through the shared envelope.
+        const runCoverage = {
+            unit: 'sub-checks',
+            expected: rows.length,
+            examined: rows.length,
+            ...(rows.length === 0
+                ? {
+                    reason: changedFiles.length === 0
+                        ? 'no changed files in the diff scope'
+                        : 'nothing in the diff is governed by a boundary rule or read by import hygiene',
+                }
+                : {}),
+            ...allowEmptyValve(args, rows.length),
+        };
+        const proposed = rows.some((r) => r.status === 'failed') ? ExitCode.Failure : ExitCode.VerifiedPass;
+        const env = buildGateEnvelope('diff-check', proposed, rows, runCoverage);
+        const exit = env.exit;
+        const bErr = boundaryBlock.counts.error;
+        const bWarn = boundaryBlock.counts.warning;
+        const bErrored = (boundaryBlock.loadIssues?.length ?? 0) + (boundaryBlock.staleExceptions?.length ?? 0);
+        const iErr = importsBlock.verdict === 'errors' ? (importsBlock.counts.error ?? importsBlock.findings.length) : 0;
+        const iWarn = importsBlock.verdict === 'warnings' ? (importsBlock.counts.warning ?? importsBlock.findings.length) : 0;
+        let verdict;
+        let summary;
+        let nextAction;
+        if (exit === ExitCode.Failure) {
+            const parts = [];
+            if (bErr > 0)
+                parts.push(plural(bErr, 'boundary violation'));
+            if (bErrored > 0)
+                parts.push(plural(bErrored, 'errored boundary rule / stale exception'));
+            if (iErr > 0)
+                parts.push(plural(iErr, 'import-hygiene error'));
+            verdict = 'errors';
+            summary = `Diff fails the gate: ${parts.join(', ') || 'see the failing check'}.`;
+            nextAction =
+                'Fix every error in `boundaries.violations` and `imports.findings` (look at each entry\'s `suggestedFix` line), then re-run `shrk diff-check`.';
+        }
+        else if (exit !== ExitCode.VerifiedPass) {
+            verdict = 'not-verified';
+            summary =
+                rows.length === 0
+                    ? changedFiles.length === 0
+                        ? 'No files changed in the current diff scope — nothing was checked (this is not a pass).'
+                        : 'Nothing in the diff is governed by a boundary rule or read by import hygiene — nothing was checked (this is not a pass).'
+                    : `Not verified: ${env.shortfalls.slice(0, 3).join('; ')} — this is NOT a pass.`;
+            nextAction =
+                rows.length === 0
+                    ? `Nothing was verified. If you expected changes, check your \`--staged\` / \`--since <ref>\` flag or save your edits first; pass --${ALLOW_EMPTY_FLAG} to accept an empty diff explicitly.`
+                    : 'Part of the scope was never examined — fix the rule scope named above, then re-run `shrk diff-check`.';
+        }
+        else if (rows.length === 0) {
+            verdict = 'ok';
+            summary = 'Nothing to check — the empty diff was accepted explicitly.';
+            nextAction = 'Nothing was gated.';
+        }
+        else if (bWarn > 0 || iWarn > 0) {
+            const parts = [];
+            if (bWarn > 0)
+                parts.push(plural(bWarn, 'boundary warning'));
+            if (iWarn > 0)
+                parts.push(plural(iWarn, 'import-hygiene warning'));
+            verdict = 'warnings';
+            summary = `Diff passes the gate with ${parts.join(', ')}.`;
+            nextAction =
+                'Safe to declare done. Review warnings if the diff touches a sensitive area; otherwise these are non-blocking.';
+        }
+        else {
+            verdict = 'ok';
+            summary = `Diff passes the gate (${plural(changedFiles.length, 'file')}, 0 violations).`;
+            nextAction = 'Safe to declare done.';
         }
-        // 4. Build envelope + derive verdict.
-        const partial = {
+        const envelope = {
             schema: SCHEMA,
             generatedAt: new Date().toISOString(),
-            scope: {
-                mode,
-                files: changedFiles,
-                fileCount: changedFiles.length,
-            },
+            scope: { mode, files: changedFiles, fileCount: changedFiles.length },
             boundaries: boundaryBlock,
             imports: importsBlock,
+            verdict,
+            summary,
+            nextAction,
+            exitCode: exit,
+            gate: env,
         };
-        const { verdict, summary, nextAction } = deriveVerdict(partial);
-        const envelope = { ...partial, verdict, summary, nextAction };
         // 5. Render.
         if (wantJson) {
             process.stdout.write(asJson(envelope) + '\n');
-            return verdict === 'errors' ? 1 : 0;
+            return exit;
         }
         process.stdout.write(header('Diff check'));
-        process.stdout.write(kv('scope', `${envelope.scope.mode} (${envelope.scope.fileCount} file${envelope.scope.fileCount === 1 ? '' : 's'})`) + '\n');
-        process.stdout.write(kv('boundaries', envelope.boundaries.ran
-            ? `${envelope.boundaries.counts.error} errors, ${envelope.boundaries.counts.warning} warnings`
-            : '(no rules configured or no scoped files)') + '\n');
-        process.stdout.write(kv('imports', envelope.imports.ran
-            ? `verdict=${envelope.imports.verdict} (${envelope.imports.findings.length} finding${envelope.imports.findings.length === 1 ? '' : 's'})`
-            : '(no scoped files)') + '\n');
-        process.stdout.write(kv('verdict', envelope.verdict) + '\n');
-        process.stdout.write('\n');
-        process.stdout.write(envelope.summary + '\n');
-        if (envelope.boundaries.violations.length > 0) {
+        process.stdout.write(kv('scope', `${envelope.scope.mode} (${plural(envelope.scope.fileCount, 'file')})`) + '\n');
+        process.stdout.write(kv('boundaries', boundaryBlock.ran
+            ? `${bErr} errors, ${bWarn} warnings${boundaryBlock.escalation ? ` — ${boundaryBlock.escalation.ruleIds.length} rule(s) escalated (${boundaryBlock.escalation.files.join(', ')} changed)` : ''}`
+            : `(not run — ${boundaryBlock.reason ?? 'nothing to check'})`) + '\n');
+        process.stdout.write(kv('imports', importsBlock.ran
+            ? `verdict=${importsBlock.verdict} (${plural(importsBlock.findings.length, 'finding')})`
+            : `(not run — ${importsBlock.reason ?? 'nothing to check'})`) + '\n');
+        process.stdout.write(kv('verdict', `${envelope.verdict} (exit ${exit})`) + '\n');
+        if (exit === ExitCode.Failure)
+            process.stdout.write(`\n${summary}\n`);
+        if (boundaryBlock.violations.length > 0) {
             process.stdout.write('\nBoundary violations:\n');
-            for (const v of envelope.boundaries.violations.slice(0, 10)) {
+            for (const v of boundaryBlock.violations.slice(0, 10)) {
                 const file = String(v.file ?? '');
                 const rule = String(v.ruleId ?? '');
                 const fix = v.suggestedFix ? ` — ${String(v.suggestedFix)}` : '';
                 process.stdout.write(bullet(`${rule} in ${file}${fix}`) + '\n');
             }
-            if (envelope.boundaries.violations.length > 10) {
-                process.stdout.write(`  … and ${envelope.boundaries.violations.length - 10} more (pass --json for full list).\n`);
+            if (boundaryBlock.violations.length > 10) {
+                process.stdout.write(`  … and ${boundaryBlock.violations.length - 10} more (pass --json for full list).\n`);
             }
         }
-        if (envelope.imports.findings.length > 0) {
+        if (importsBlock.findings.length > 0) {
             process.stdout.write('\nImport findings:\n');
-            for (const f of envelope.imports.findings.slice(0, 10)) {
+            for (const f of importsBlock.findings.slice(0, 10)) {
                 const file = String(f.path ?? f.file ?? '');
                 const kind = String(f.kind ?? '');
                 process.stdout.write(bullet(`${kind} in ${file}`) + '\n');
             }
-            if (envelope.imports.findings.length > 10) {
-                process.stdout.write(`  … and ${envelope.imports.findings.length - 10} more (pass --json for full list).\n`);
+            if (importsBlock.findings.length > 10) {
+                process.stdout.write(`  … and ${importsBlock.findings.length - 10} more (pass --json for full list).\n`);
             }
         }
-        process.stdout.write(`\nNext: ${envelope.nextAction}\n`);
-        return verdict === 'errors' ? 1 : 0;
+        // The final line comes from the SETTLED verdict — the clean sentence only at 0.
+        const line = verdictLine(env, `${summary} ✓`, exit === ExitCode.NotVerified ? summary : undefined);
+        if (line)
+            process.stdout.write(`\n${line}\n`);
+        process.stdout.write(`\nNext: ${nextAction}\n`);
+        return exit;
     },
 };

package/dist/commands/docs-references.command.d.ts

@@ -1,4 +1,17 @@
+import { type IDocReferenceResult } from '@shrkcrft/inspector';
 import { type ICommandHandler } from '../command-registry.js';
+import type { IVerdictCoverage } from '@shrkcrft/core';
+/**
+ * What one doc-reference rule examined — shared by `docs references check` and
+ * the aggregate (`gates check`, `quality`), so both report the same scope.
+ *
+ * The unit is the id-shaped tokens the rule matched. Tokens it did NOT check
+ * were skipped by the rule's own config — an `exempt` id, an in-file
+ * `exemptMarker`, the `requireContext` gate — which is a deliberate narrowing,
+ * so it is accepted by that config and printed as such rather than silently
+ * shrinking the denominator.
+ */
+export declare function docReferenceCoverage(r: IDocReferenceResult): IVerdictCoverage;
 export declare const docsReferencesCheckCommand: ICommandHandler;
 export declare const docsReferencesExplainCommand: ICommandHandler;
 export declare const docsReferencesListCommand: ICommandHandler;

package/dist/commands/docs-references.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-references.command.d.ts","sourceRoot":"","sources":["../../src/commands/docs-references.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAsGhC,eAAO,MAAM,0BAA0B,EAAE,eAuIxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eA4D1C,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,eAyBvC,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,EAAE,eAkBnC,CAAC"}
+{"version":3,"file":"docs-references.command.d.ts","sourceRoot":"","sources":["../../src/commands/docs-references.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAIL,KAAK,mBAAmB,EAEzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAahC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,mBAAmB,GAAG,gBAAgB,CAQ7E;AAqLD,eAAO,MAAM,0BAA0B,EAAE,eA4LxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eAiF1C,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,eAoCvC,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,EAAE,eA2CnC,CAAC"}