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

package/dist/commands/docs-references.command.js

@@ -1,26 +1,62 @@
-/**
- * `shrk docs references {check,explain,list}` — the prose-reference linter.
- *
- *   shrk docs references check [--id X] [--json]     # unresolved id → finding
- *   shrk docs references explain --id X              # every token + where it resolved
- *   shrk docs references list                        # the declared rules
- *
- * shrk validates the STRUCTURED `references[]` on knowledge entries. The same
- * ids written as prose — a README, an architecture doc, an agent skill file
- * saying `shrk gen nge.foo` — had no gate at all, and markdown has no build
- * behind it. This points the existing reference resolver at that surface.
- *
- * Read-only: it scans documents and consults registries. Nothing is written and
- * nothing is spawned.
- */
-import * as nodePath from 'node:path';
-import { checkDocReferences, inspectSharkcraft, warmReferenceRegistries, resolveProjectConfig, } from '@shrkcrft/inspector';
+import { formatEmptyRuleAdvice } from '@shrkcrft/core';
+import { planeScanExcludeDirs, readScopeCoverage } from '@shrkcrft/boundaries';
+import { warmCliReferenceRegistries } from "../surface/cli-command-resolver.js";
+import { checkDocReferences, inspectSharkcraft, resolveProjectConfig, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { ExitCode } from "../exit-codes.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { buildGateEnvelope } from "../gates/gate-envelope.js";
+import { verdictLine } from "../gates/verdict-line.js";
+import { acceptedEmptyNote } from "../gates/accepted-empty-note.js";
+import { emptyRuleAdviceLines } from "../gates/empty-rule-advice-lines.js";
+import { qualifyCleanForUnits } from "../gates/qualify-clean-for-units.js";
+import { unitStateNotes } from "../gates/unit-state-notes.js";
+import { planeVerdictForExit } from "../gates/plane-verdict.js";
+import { seamRejectedRules } from "../gates/seam-rejected-rules.js";
 const SCHEMA = 'sharkcraft.doc-references/v1';
-async function prepare(args) {
+/**
+ * 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 function docReferenceCoverage(r) {
+    // An intended-empty rule (round 13: every `files` inclusion glob marked
+    // `expectEmpty`, no document matched) is covered by its acceptance — the
+    // settle's own record, printed at exit 0.
+    if (r.emptyCoverage !== undefined)
+        return r.emptyCoverage;
+    // A document the reader could not read (over the read cap) folds in through
+    // the one rule every plane uses: `examined N of M files`, named.
+    return readScopeCoverage(planeDocReferenceCoverage(r), r.readScope);
+}
+function planeDocReferenceCoverage(r) {
+    if (r.error !== undefined) {
+        return { unit: 'references', expected: 0, examined: 0, reason: 'the rule could not run' };
+    }
+    const expected = r.tokensChecked + r.tokensSkipped;
+    return {
+        unit: 'references',
+        expected,
+        examined: r.tokensChecked,
+        ...(r.skipReason !== undefined
+            ? { reason: r.skipReason }
+            : r.tokensSkipped > 0
+                ? { reason: "skipped by the rule's own exempt / exemptMarker / requireContext config" }
+                : {}),
+        ...(r.tokensSkipped > 0 && r.tokensChecked > 0
+            ? { acceptedBy: 'the rule config (exempt / exemptMarker / requireContext)' }
+            : {}),
+    };
+}
+async function prepare(args, 
+/** `rejectedKnown`: the verdict verb may select a rejected rule by `--id` (its errored row). */
+opts = {}) {
     const cwd = resolveCwd(args);
     const json = flagBool(args, 'json');
     const loaded = await resolveProjectConfig(cwd);
@@ -33,18 +69,28 @@ async function prepare(args) {
         return { ok: false, code: ExitCode.UsageError };
     }
     const all = loaded.value.config.docReferences ?? [];
-    const rel = nodePath.relative(cwd, loaded.value.sharkcraftDir).split(nodePath.sep).join('/');
+    // A pack doc-reference rule the merge seam REJECTED is a configured rule
+    // that never ran — an ERRORED row on this verb exactly as on `gates check`
+    // (round 13, P3 review). It was one `! … invalid docReference element … —
+    // skipped` line under a ✓ at exit 0 (or "No doc-reference rules declared"
+    // at 2 when it was the only rule) while `gates check` exited 1 on the tree.
+    const rejectedAll = seamRejectedRules(loaded.value, ['doc-reference']);
     let rules = all;
+    let rejected = rejectedAll;
     const id = flagString(args, 'id');
     if (id) {
         const wanted = id.split(',').map((s) => s.trim()).filter(Boolean);
-        const known = new Set(all.map((r) => r.id));
+        const known = new Set([
+            ...all.map((r) => r.id),
+            ...(opts.rejectedKnown === true ? rejectedAll.map((r) => r.id) : []),
+        ]);
         const unknown = wanted.filter((w) => !known.has(w));
         if (unknown.length > 0) {
             process.stderr.write(`Unknown doc-reference rule id(s): ${unknown.join(', ')}. Declared: ${[...known].join(', ') || '(none)'}\n`);
             return { ok: false, code: ExitCode.UsageError };
         }
         rules = all.filter((r) => wanted.includes(r.id));
+        rejected = rejectedAll.filter((r) => wanted.includes(r.id));
     }
     return {
         ok: true,
@@ -52,7 +98,9 @@ async function prepare(args) {
             cwd,
             rules,
             all,
-            excludeDirs: rel && !rel.startsWith('..') ? [rel] : [],
+            rejected,
+            // THE plane scan scope — the same authority `gates check` reads.
+            excludeDirs: planeScanExcludeDirs(cwd, loaded.value.sharkcraftDir),
             planeDiagnostics: loaded.value.planeDiagnostics,
         },
     };
@@ -69,19 +117,50 @@ async function inspectionFor(cwd) {
     // resolver is sync. Warming here is what makes a correct pack playbook cited
     // in prose actually resolve.
     const inspection = await inspectSharkcraft({ cwd });
-    await warmReferenceRegistries(inspection);
+    // WITH the command resolver: a `resolvesAs: ['command']` rule resolves
+    // against the live command index (without it, `command` is unverifiable
+    // and the rule refuses loudly).
+    await warmCliReferenceRegistries(inspection);
     return inspection;
 }
-function writeNoRules(json) {
+/**
+ * The "no rules declared" landing. A VERDICT verb passes its name so its JSON
+ * still carries the settled `gate` envelope — nothing declared is `2`.
+ */
+function writeNoRules(json, verb) {
+    // A VERDICT verb settles first and renders second, in text AND JSON: nothing
+    // declared proposes 0 and the run coverage (expected 0) settles it to 2. The
+    // exit comes from the envelope — never a hard-coded code — so text, JSON and
+    // gate.exit cannot disagree. List / explain subverbs stay informational.
+    const gate = verb !== undefined
+        ? buildGateEnvelope(verb, ExitCode.VerifiedPass, [], {
+            unit: 'doc-reference rules',
+            expected: 0,
+            examined: 0,
+            reason: 'no docReferences[] declared',
+        })
+        : undefined;
+    const exit = gate?.exit ?? ExitCode.NotVerified;
     if (json) {
-        process.stdout.write(asJson({ schema: SCHEMA, results: [], evaluated: 0, verdict: 'not-verified' }) + '\n');
-        return ExitCode.NotVerified;
+        process.stdout.write(asJson({
+            schema: SCHEMA,
+            results: [],
+            evaluated: 0,
+            verdict: gate ? planeVerdictForExit(gate.exit) : 'not-verified',
+            ...(gate ? { exitCode: gate.exit, gate } : {}),
+        }) + '\n');
+        return exit;
     }
     process.stdout.write(header('Doc references'));
     process.stdout.write('  No doc-reference rules declared. Add `docReferences[]` to sharkcraft.config.ts to\n' +
         '  catch ids cited in prose (READMEs, docs, agent skill files) that no longer resolve\n' +
         '  (see docs/doc-references.md).\n');
-    return ExitCode.NotVerified;
+    if (gate) {
+        const line = verdictLine(gate, 'Nothing declared — accepted.');
+        if (line)
+            process.stdout.write(`\n${line}\n`);
+    }
+    return exit;
 }
 function resultJson(r) {
     return {
@@ -97,20 +176,36 @@ function resultJson(r) {
         ...(r.error ? { error: r.error } : {}),
     };
 }
+/**
+ * The round-12 list-verb rejection note (K10): one line per pack doc-reference
+ * rule the merge seam REJECTED — the rows `baseline list` / `gates list` print.
+ */
+function writeRejectedDocRules(rejected) {
+    if (rejected.length === 0)
+        return;
+    process.stdout.write(`\n  rejected at the pack-plane merge seam — never checked (${rejected.length}):\n`);
+    for (const r of rejected)
+        process.stdout.write(`  ✗ ${r.id}  REJECTED — ${r.error ?? 'failed validation'}\n`);
+    process.stdout.write('  `shrk packs contributions` names every rejected entry.\n');
+}
 export const docsReferencesCheckCommand = {
     name: 'check',
     description: 'Scan configured docs for id-shaped tokens and assert each resolves to a registered id. Catches a README or skill file citing a template that no longer exists.',
     usage: 'shrk docs references check [--id <ids>] [--json]',
     booleanFlags: new Set(['json']),
     async run(args) {
-        const prep = await prepare(args);
+        const prep = await prepare(args, { rejectedKnown: true });
         if (!prep.ok)
             return prep.code;
         const json = flagBool(args, 'json');
-        if (prep.value.rules.length === 0)
-            return writeNoRules(json);
-        const inspection = await inspectionFor(prep.value.cwd);
-        const results = prep.value.rules.map((r) => checkDocReferences(prep.value.cwd, r, inspection, prep.value.excludeDirs));
+        const rejected = prep.value.rejected;
+        if (prep.value.rules.length === 0 && rejected.length === 0)
+            return writeNoRules(json, 'docs references check');
+        // The resolver's inspection is paid for only when a rule will run.
+        const inspection = prep.value.rules.length > 0 ? await inspectionFor(prep.value.cwd) : undefined;
+        const results = inspection
+            ? prep.value.rules.map((r) => checkDocReferences(prep.value.cwd, r, inspection, prep.value.excludeDirs))
+            : [];
         // A rule that ERRORED proved nothing — it never got as far as checking an
         // id. So it is not `evaluated`, whatever its severity: a warning-severity
         // rule that could not run must not leave the banner saying "not blocking"
@@ -121,41 +216,74 @@ export const docsReferencesCheckCommand = {
         const blocking = [...failed, ...errored].filter((r) => r.severity === 'error');
         const evaluated = results.filter((r) => r.status !== 'skipped' && r.status !== 'error').length;
         const skipped = results.length - evaluated;
-        const exit = blocking.length > 0
+        // A rejected pack rule is a configured rule that never ran: 1, as on
+        // `gates check` (its ERRORED row, `failed validation — NOT evaluated`).
+        const proposed = blocking.length > 0 || rejected.length > 0
             ? ExitCode.Failure
             : evaluated === 0 || skipped > 0
                 ? ExitCode.NotVerified
                 : ExitCode.VerifiedPass;
+        // Settle first, render second: the envelope is built for text AND JSON, so
+        // both return the same settled exit and the ✓ line is printed only from it.
+        const unexamined = [
+            ...results.filter((r) => r.status === 'skipped' || r.status === 'error').map((r) => r.ruleId),
+            ...rejected.map((r) => r.id),
+        ];
+        const env = buildGateEnvelope('docs references check', proposed, [...results.map((r) => ({
+                id: r.ruleId,
+                type: 'doc-reference',
+                status: r.status,
+                severity: r.severity,
+                counts: { files: r.filesScanned, tokens: r.tokensChecked, skipped: r.tokensSkipped },
+                violations: r.findings.map((f) => ({
+                    id: f.token,
+                    file: f.file,
+                    line: f.line,
+                    message: f.message,
+                    ...(f.didYouMean.length > 0 ? { hint: `did you mean: ${f.didYouMean.join(', ')}` } : {}),
+                })),
+                ...(r.skipReason ? { skipReason: r.skipReason } : {}),
+                ...(r.error ? { error: r.error } : {}),
+                coverage: docReferenceCoverage(r),
+                // The rule's `expectEmpty` acceptance and unit lines (round 13),
+                // folded into the envelope's one settle — the accepted line comes from it.
+                ...(r.unitAcceptance !== undefined ? { unitAcceptance: r.unitAcceptance } : {}),
+                ...(r.units !== undefined ? { units: r.units } : {}),
+            })), ...rejected], {
+            unit: 'doc-reference rules',
+            expected: results.length + rejected.length,
+            examined: results.length + rejected.length - unexamined.length,
+            ...(unexamined.length > 0 ? { unexamined, reason: 'checked nothing or could not run' } : {}),
+        });
+        const exit = env.exit;
         if (json) {
             process.stdout.write(asJson({
                 schema: SCHEMA,
                 results: results.map(resultJson),
                 evaluated,
                 skipped,
-                verdict: blocking.length > 0 ? 'errors' : evaluated === 0 ? 'not-verified' : 'pass',
+                verdict: exit === ExitCode.Failure ? 'errors' : exit === ExitCode.VerifiedPass ? 'pass' : 'not-verified',
+                rejected: rejected.map((r) => ({ id: r.id, error: r.error ?? null })),
                 diagnostics: prep.value.planeDiagnostics,
                 exitCode: exit,
-                gate: buildGateEnvelope('docs references check', exit, results.map((r) => ({
-                    id: r.ruleId,
-                    type: 'doc-reference',
-                    status: r.status,
-                    severity: r.severity,
-                    counts: { files: r.filesScanned, tokens: r.tokensChecked, skipped: r.tokensSkipped },
-                    violations: r.findings.map((f) => ({
-                        id: f.token,
-                        file: f.file,
-                        line: f.line,
-                        message: f.message,
-                        ...(f.didYouMean.length > 0 ? { hint: `did you mean: ${f.didYouMean.join(', ')}` } : {}),
-                    })),
-                    ...(r.skipReason ? { skipReason: r.skipReason } : {}),
-                    ...(r.error ? { error: r.error } : {}),
-                }))),
+                gate: env,
             }) + '\n');
             return exit;
         }
         process.stdout.write(header('Doc references'));
-        process.stdout.write(kv('evaluated', `${evaluated} of ${prep.value.rules.length}`) + '\n');
+        // Round 13 (K6): the printed count is the envelope's (`gate.evaluated`), which
+        // never counts a rule accepted as intended-empty — it is named apart. The
+        // local `evaluated` keeps counting it for the "nothing ran" proposal above.
+        process.stdout.write(kv('evaluated', `${env.evaluated} of ${prep.value.rules.length + rejected.length}${acceptedEmptyNote(env.acceptedEmpty)}`) +
+            '\n');
+        // THE shared unit-state block (round 13, K2): a dead `files` glob of a rule
+        // that still matched, and a LOCAL expectEmpty marker whose target appeared,
+        // withhold the ✓ (exit unchanged); a pack marker is INFO.
+        const unitNotes = unitStateNotes(results.map((r) => ({
+            id: r.ruleId,
+            ...(r.unitLiveness !== undefined ? { unitLiveness: r.unitLiveness } : {}),
+            reportedEmpty: r.status === 'skipped' || r.skipReason !== undefined,
+        })));
         for (const r of results) {
             if (r.status === 'skipped') {
                 process.stdout.write(`  – ${r.ruleId}  SKIPPED — ${r.skipReason}\n`);
@@ -166,7 +294,12 @@ export const docsReferencesCheckCommand = {
                 continue;
             }
             if (r.status === 'passed') {
-                process.stdout.write(`  ✓ ${r.ruleId}  (${r.tokensChecked} reference(s) across ${r.filesScanned} doc(s) all resolve)\n`);
+                // Rendered from the SETTLED rule: a pass over part of its scope is
+                // `partial`, never a ✓ (the keystone emitter pattern, step 5).
+                const settledRule = env.rules.find((x) => x.id === r.ruleId);
+                process.stdout.write(settledRule?.status === 'partial'
+                    ? `  ~ ${r.ruleId}  PARTIAL — ${settledRule.shortfall ?? 'part of its scope was not examined'}\n`
+                    : `  ✓ ${r.ruleId}  (${r.tokensChecked} reference(s) across ${r.filesScanned} doc(s) all resolve)\n`);
                 continue;
             }
             // A rule that CHECKED nothing failed for a different reason than one with
@@ -175,8 +308,8 @@ export const docsReferencesCheckCommand = {
             // bad id when the real problem is a moved directory.
             if (r.skipReason) {
                 process.stdout.write(`  ✗ ${r.ruleId}  FAILED — ${r.skipReason}\n`);
-                process.stdout.write('      Nothing was checked, so nothing was enforced. Fix the glob, or set\n' +
-                    '      `failOnEmpty: false` if this rule may legitimately cover no docs.\n');
+                process.stdout.write('      Nothing was checked, so nothing was enforced.\n' +
+                    `      → ${formatEmptyRuleAdvice({ fails: true })}\n`);
                 continue;
             }
             process.stdout.write(`  ✗ ${r.ruleId}  ${r.findings.length} unresolved reference(s) of ${r.tokensChecked} checked\n`);
@@ -193,25 +326,33 @@ export const docsReferencesCheckCommand = {
             if (hint)
                 process.stdout.write(`      → ${hint}\n`);
         }
+        for (const r of rejected)
+            process.stdout.write(`  ✗ ${r.id}  REJECTED — ${r.error ?? 'failed validation'}\n`);
         for (const d of prep.value.planeDiagnostics)
             process.stdout.write(`  ! ${d}\n`);
+        // THE empty-rule advice (round 13, K8) for a rule that matched nothing and
+        // does not fail on it: only a FAILING empty rule was advised (inline,
+        // above), so a soft skip was never told how to make it fail or to mark a
+        // planned unit.
+        for (const a of emptyRuleAdviceLines(results.filter((r) => r.status === 'skipped').map(() => ({ fails: false })))) {
+            process.stdout.write(`  ${a}.\n`);
+        }
+        process.stdout.write(unitNotes.text);
         // A warning-severity rule reports without blocking, but the banner must
         // still say it FIRED. "Every id resolves ✓" printed under a list of
         // unresolved ids is the kind of half-truth that trains people to stop
         // reading the output.
         const warned = failed.filter((r) => r.severity !== 'error');
-        if (exit === ExitCode.VerifiedPass && warned.length > 0) {
-            const count = warned.reduce((n, r) => n + r.findings.length, 0);
-            process.stdout.write(`\n${count} unresolved reference(s) reported by ${warned.length} warning rule(s) — not blocking.\n`);
-        }
-        else if (exit === ExitCode.VerifiedPass) {
-            process.stdout.write('\nEvery id cited in prose resolves. ✓\n');
-        }
-        else if (exit === ExitCode.NotVerified) {
-            process.stdout.write(errored.length > 0
-                ? `\n${errored.length} rule(s) could not run — nothing was proved. This is NOT a pass.\n`
-                : '\nNothing was checked — this is NOT a pass.\n');
-        }
+        const warnedCount = warned.reduce((n, r) => n + r.findings.length, 0);
+        const line = verdictLine(env, warned.length > 0
+            ? `${warnedCount} unresolved reference(s) reported by ${warned.length} warning rule(s) — not blocking.`
+            : qualifyCleanForUnits('Every id cited in prose resolves. ✓', unitNotes), proposed === ExitCode.NotVerified
+            ? errored.length > 0
+                ? `${errored.length} rule(s) could not run — nothing was proved. This is NOT a pass.`
+                : 'Nothing was checked — this is NOT a pass.'
+            : undefined);
+        if (line)
+            process.stdout.write(`\n${line}\n`);
         return exit;
     },
 };
@@ -228,12 +369,32 @@ export const docsReferencesExplainCommand = {
         }
         const forwarded = { ...args, flags: new Map(args.flags) };
         forwarded.flags.set('id', id);
-        const prep = await prepare(forwarded);
+        // A rejected pack rule's id is a DECLARED one (K10): `explain` names its
+        // rejection — it called the id unknown (a usage error, 3).
+        const prep = await prepare(forwarded, { rejectedKnown: true });
         if (!prep.ok)
             return prep.code;
         const rule = prep.value.rules[0];
-        if (!rule)
-            return writeNoRules(flagBool(args, 'json'));
+        if (!rule) {
+            const rejectedRule = prep.value.rejected[0];
+            if (rejectedRule === undefined)
+                return writeNoRules(flagBool(args, 'json'));
+            if (flagBool(args, 'json')) {
+                process.stdout.write(asJson({
+                    schema: 'sharkcraft.doc-references-explain/v1',
+                    id: rejectedRule.id,
+                    rejected: true,
+                    error: rejectedRule.error ?? null,
+                }) + '\n');
+            }
+            else {
+                process.stdout.write(header(`Doc references: ${rejectedRule.id}`));
+                writeRejectedDocRules([rejectedRule]);
+            }
+            // A rule that never loaded cannot be explained: a failure, as every
+            // registry verb answers a rejected pack registry.
+            return ExitCode.Failure;
+        }
         const inspection = await inspectionFor(prep.value.cwd);
         const result = checkDocReferences(prep.value.cwd, rule, inspection, prep.value.excludeDirs);
         if (flagBool(args, 'json')) {
@@ -282,10 +443,18 @@ export const docsReferencesListCommand = {
         if (!prep.ok)
             return prep.code;
         const json = flagBool(args, 'json');
-        if (prep.value.all.length === 0)
+        // Round 13 (K10): a pack doc-reference rule the merge seam REJECTED is a
+        // declared rule that never runs — listed, as `baseline list` / `gates
+        // list` list theirs (it was absent from `list` and unknown to `explain`).
+        const rejected = prep.value.rejected;
+        if (prep.value.all.length === 0 && rejected.length === 0)
             return writeNoRules(json);
         if (json) {
-            process.stdout.write(asJson({ schema: SCHEMA, rules: prep.value.all }) + '\n');
+            process.stdout.write(asJson({
+                schema: SCHEMA,
+                rules: prep.value.all,
+                rejected: rejected.map((r) => ({ id: r.id, error: r.error ?? null })),
+            }) + '\n');
             return ExitCode.VerifiedPass;
         }
         process.stdout.write(header(`Doc-reference rules (${prep.value.all.length})`));
@@ -298,6 +467,7 @@ export const docsReferencesListCommand = {
             if (r.description)
                 process.stdout.write(`      ${r.description}\n`);
         }
+        writeRejectedDocRules(rejected);
         return ExitCode.VerifiedPass;
     },
 };
@@ -306,6 +476,32 @@ export const docsReferencesCommand = {
     name: 'references',
     description: 'Prose-reference linter: assert every id cited in free text (READMEs, docs, agent skill files) still resolves to a registered id.',
     usage: 'shrk docs references check | explain --id <id> | list',
+    // Declared (round 11 review): the dispatcher guard refuses any other token
+    // with the closest subverb, `help` and the index see the three verbs, and
+    // the declared walk reaches the verdict path — so a bad flag on `docs
+    // references check` is a usage error of `docs references check` (3), never
+    // one of `docs references` (2).
+    positionals: PositionalMode.None,
+    subverbs: [
+        {
+            name: docsReferencesCheckCommand.name,
+            description: docsReferencesCheckCommand.description,
+            usage: docsReferencesCheckCommand.usage,
+            positionals: PositionalMode.None,
+        },
+        {
+            name: docsReferencesExplainCommand.name,
+            description: docsReferencesExplainCommand.description,
+            usage: docsReferencesExplainCommand.usage,
+            positionals: PositionalMode.Free,
+        },
+        {
+            name: docsReferencesListCommand.name,
+            description: docsReferencesListCommand.description,
+            usage: docsReferencesListCommand.usage,
+            positionals: PositionalMode.None,
+        },
+    ],
     booleanFlags: new Set(['json']),
     async run(args) {
         const sub = args.positional[0];
@@ -316,8 +512,9 @@ export const docsReferencesCommand = {
             return docsReferencesExplainCommand.run(rest);
         if (sub === 'list')
             return docsReferencesListCommand.run(rest);
-        process.stderr.write((sub ? `Unknown subcommand "${sub}". ` : '') +
-            'Usage: shrk docs references check | explain --id <id> | list\n');
+        // Only a bare `shrk docs references` lands here: the guard refused any
+        // other token before this body ran.
+        process.stderr.write('Usage: shrk docs references check | explain --id <id> | list\n');
         return ExitCode.UsageError;
     },
 };

package/dist/commands/doctor.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.command.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6PhC,eAAO,MAAM,aAAa,EAAE,eAW3B,CAAC;AA2fF,eAAO,MAAM,qBAAqB,EAAE,eAmCnC,CAAC;AAuDF,eAAO,MAAM,yBAAyB,EAAE,eAavC,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eA2CtC,CAAC;AAgCF,eAAO,MAAM,6BAA6B,EAAE,eAa3C,CAAC"}
+{"version":3,"file":"doctor.command.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.command.ts"],"names":[],"mappings":"AAwBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAmShC,eAAO,MAAM,aAAa,EAAE,eAc3B,CAAC;AA4gBF,eAAO,MAAM,qBAAqB,EAAE,eAmCnC,CAAC;AAuDF,eAAO,MAAM,yBAAyB,EAAE,eAavC,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eA2CtC,CAAC;AAgCF,eAAO,MAAM,6BAA6B,EAAE,eAa3C,CAAC"}

package/dist/commands/doctor.command.js

@@ -1,15 +1,18 @@
 import { detectGraphFreshness } from '@shrkcrft/graph';
-import { buildAcknowledgement, buildAiReadinessReport, buildSuppressionEntry, doctorSuppressionsFile, DoctorSeverity, filterDoctorResult, inspectSharkcraft, loadDoctorSuppressions, renderAcknowledgementsText, runDoctor, saveDoctorSuppressions, summarizeAcknowledgements, } from '@shrkcrft/inspector';
+import { buildAcknowledgement, buildAiReadinessReport, buildSuppressionEntry, detectUnregisteredExports, doctorSuppressionsFile, DoctorSeverity, filterDoctorResult, inspectSharkcraft, loadDoctorSuppressions, renderAcknowledgementsText, doctorVerdict, runDoctor, saveDoctorSuppressions, summarizeAcknowledgements, } from '@shrkcrft/inspector';
 import { detectProjectShape } from '@shrkcrft/workspace';
 import { loadSurfaceContext } from "../surface/load-surface-context.js";
 import { buildSurfaceSummary } from "../surface/surface-summary.js";
 import { renderShapeLine } from "../surface/shape-defaults.js";
 import { existsSync } from 'node:fs';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { PositionalMode } from "../dispatch/positional-mode.js";
 import { SemanticIndex, listIndexableFiles } from '@shrkcrft/embeddings';
 import { asJson, header, kv } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
 import { doctorHints, renderFailureHints } from "../output/failure-hints.js";
+import { settleVerdict } from "../gates/settle-verdict.js";
+import { verdictLine } from "../gates/verdict-line.js";
 import { foldDoctorChecks, renderFoldedSummary, DoctorState, } from "../doctor/doctor-tags.js";
 import { enrichWithLlmRecommendations, renderRecommendationsMarkdown, } from '@shrkcrft/ai';
 const SEVERITY_LABEL = {
@@ -158,6 +161,39 @@ function augmentWithSemanticIndexCheck(result, cwd) {
         summary.errors = (summary.errors ?? 0) + 1;
     return { ...result, checks, summary };
 }
+/**
+ * "Unregistered entry exports" (round 11 §3.1): an entry a group module exports
+ * that the aggregator registering it never lists is silently invisible. Added
+ * only when something is found (an error → exit 1); a clean repo sees no new
+ * line. The check lives in the inspector (`detectUnregisteredExports`) and is
+ * async (it imports the group modules), so it is appended here.
+ */
+async function augmentWithUnregisteredExports(result, inspection) {
+    let found = [];
+    try {
+        found = await detectUnregisteredExports(inspection);
+    }
+    catch {
+        return result;
+    }
+    if (found.length === 0)
+        return result;
+    const shown = found.slice(0, 10).map((u) => `${u.group}${u.line > 0 ? `:${u.line}` : ''} — ${u.message}`);
+    const more = found.length > shown.length ? ` (+${found.length - shown.length} more)` : '';
+    const check = {
+        id: 'unregistered-entry-exports',
+        title: 'Unregistered entry exports',
+        severity: DoctorSeverity.Error,
+        category: 'unregistered-entry-exports',
+        code: 'unregistered-export',
+        message: `${found.length} exported entr${found.length === 1 ? 'y is' : 'ies are'} never registered, so no lookup can see ${found.length === 1 ? 'it' : 'them'}: ${shown.join('; ')}${more}`,
+        fix: "Add each export to its aggregator's array, or re-export the group module with `export * from './<group>'`.",
+    };
+    const summary = { ...result.summary, errors: (result.summary.errors ?? 0) + 1 };
+    // An error check is a failed doctor: `passed` is what the exit code, the
+    // JSON `ready` and the Verdict line all read, so it must flip with it.
+    return { ...result, passed: false, checks: [...result.checks, check], summary };
+}
 function renderSemanticIndexCheck(report) {
     if (!report.hasIndex) {
         return {
@@ -215,6 +251,9 @@ function renderSemanticIndexCheck(report) {
 }
 export const doctorCommand = {
     name: 'doctor',
+    // Mixed-mode: suppress / suppressions / acknowledge / acknowledgements are
+    // trie children; a bare token reaching this handler used to run the doctor.
+    positionals: PositionalMode.None,
     description: 'Validate the local SharkCraft setup (config, knowledge, templates, project). `--focus errors|warnings-new|info`, `--hide <category,...>`, `--quiet-known` filter the headline view using `sharkcraft/doctor.suppressions.json`. `--watch`/`--once`/`--debounce` for live mode. `--explain-quality` shows the per-warning "why this matters" line so warnings stop being permanent yellow noise. `--blockers` shows only must-fix findings (errors + warning-category in {config-invalid, pack-signature-invalid, plan-signature-divergent, asset-load-failed}); exit code is non-zero iff a blocker remains. `--llm-recommendations` layers a local-LLM-derived list of concrete next-steps onto the deterministic output (no-op when no provider is reachable). Subcommands: `suppress`, `suppressions list|check`, `watch`.',
     usage: 'shrk [--cwd <dir>] doctor [--no-config] [--json] [--strict[=errors|warnings|all]] [--blockers] [--show-advisory] [--min-score <0-100>] [--focus errors,warnings-new,info] [--hide action-hint-quality,...] [--quiet-known] [--explain-quality] [--llm-recommendations] [--provider auto|ollama|llamacpp] [--watch [--once] [--debounce N]]',
     async run(args) {
@@ -237,7 +276,7 @@ async function doctorCommandImpl(args) {
         inspectOpts.loaderTimeoutMs = loaderTimeout;
     }
     const inspection = await inspectSharkcraft(inspectOpts);
-    const result = augmentWithSemanticIndexCheck(runDoctor(inspection, { graphDivergence: detectGraphFreshness(cwd) }), cwd);
+    const result = await augmentWithUnregisteredExports(augmentWithSemanticIndexCheck(runDoctor(inspection, { graphDivergence: detectGraphFreshness(cwd) }), cwd), inspection);
     const report = buildAiReadinessReport(inspection);
     if (debug) {
         process.stderr.write(`[debug] inspection elapsed ${inspection.inspectionElapsedMs}ms cache=${inspection.cacheEnabled ? 'on' : 'off'} loaders=${inspection.loaderDiagnostics.length}\n`);
@@ -331,7 +370,7 @@ async function doctorCommandImpl(args) {
     // When --blockers is set, the exit code reflects ONLY the
     // remaining blocker set. This is the agent-friendly contract: 0 means
     // "nothing must-fix", 1 means "at least one blocker remains".
-    const overallExitCode = noConfigLenient
+    const proposedExitCode = noConfigLenient
         ? 0
         : blockersOnly
             ? blockerCount > 0
@@ -340,6 +379,13 @@ async function doctorCommandImpl(args) {
             : (result.passed && !strictEval.failed && !minScoreFailed && !ackExpired)
                 ? 0
                 : 1;
+    // A scope the doctor could not verify (a compiled pack build with no build
+    // record, never compared with its source) settles a clean run to NOT
+    // VERIFIED (2), as `packs doctor` does. It never reads "Ready ✓". The
+    // advisory `--no-config` run and the filtered `--blockers` view keep
+    // their own contracts.
+    const doctorSettled = noConfigLenient || blockersOnly ? undefined : settleVerdict(proposedExitCode, result.coverage ?? []);
+    const overallExitCode = doctorSettled?.exit ?? proposedExitCode;
     if (flagBool(args, 'json')) {
         // Also compute the folded view for machine consumers so JSON
         // callers see source/state tags + folded counts.
@@ -367,7 +413,9 @@ async function doctorCommandImpl(args) {
         }
         process.stdout.write(asJson({
             targetRoot: inspection.projectRoot,
-            ready: result.passed && inspection.knowledgeEntries.length > 0,
+            // THE doctor settlement (`doctorVerdict`), shared with `shrk check`,
+            // the dashboard and MCP: never ready over an unverified scope.
+            ready: doctorVerdict(result).ready && inspection.knowledgeEntries.length > 0,
             strict: strictMode,
             strictCountedWarnings: strictEval.countedWarnings,
             strictExcludedWarnings: strictEval.excludedWarnings,
@@ -375,6 +423,7 @@ async function doctorCommandImpl(args) {
             strictFailed: strictEval.failed,
             minScoreFailed,
             exitCode: overallExitCode,
+            ...(doctorSettled && doctorSettled.shortfalls.length > 0 ? { shortfalls: doctorSettled.shortfalls } : {}),
             // Blockers preset state. Shape stays stable when --blockers is off.
             blockers: blockersOnly
                 ? {
@@ -542,6 +591,11 @@ async function doctorCommandImpl(args) {
     if (noConfigLenient) {
         process.stdout.write('\nVerdict: --no-config mode — repo has no sharkcraft/ yet (advisory). Detection works regardless.\n');
     }
+    else if (doctorSettled?.verdict === 'not-verified') {
+        const line = verdictLine(doctorSettled, '', 'Verdict: NOT VERIFIED — part of the setup could not be checked.');
+        if (line)
+            process.stdout.write(`\n${line}\n`);
+    }
     else if (result.passed && hasContent) {
         process.stdout.write('\nVerdict: Ready for AI-agent use. ✓\n');
     }

package/dist/commands/drift.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drift.command.d.ts","sourceRoot":"","sources":["../../src/commands/drift.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,YAAY,EAAE,eA4E1B,CAAC"}
+{"version":3,"file":"drift.command.d.ts","sourceRoot":"","sources":["../../src/commands/drift.command.ts"],"names":[],"mappings":"AAWA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,YAAY,EAAE,eAuF1B,CAAC"}