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

package/dist/graph/graph-reuse-lookup.js

@@ -0,0 +1,41 @@
+/**
+ * The reuse engine's graph questions, answered from one snapshot — shared by
+ * `shrk reuse` and `shrk reuse coverage`, so both resolve every curated entry
+ * (its declaration, import line and whether that import compiles) through the
+ * same lookups, via the inspector's `resolveCuratedReuse`.
+ */
+export function graphReuseLookup(api) {
+    return {
+        declarationsOf: (name) => api
+            .findSymbol(name, { exact: true, limit: 1000 })
+            .filter((n) => typeof n.path === 'string')
+            .map((n) => {
+            const declKind = n.data?.['declKind'];
+            return {
+                path: n.path,
+                symbolId: n.id,
+                isExported: n.data?.['isExported'] === true,
+                ...(typeof n.line === 'number' ? { line: n.line } : {}),
+                ...(typeof declKind === 'string' ? { declKind } : {}),
+            };
+        }),
+        consumerCount: (symbolId) => api.referenceSitesOf(symbolId).length,
+        specifierExport: (specifier, symbol) => {
+            // The file consumers' imports of this specifier resolved to (aliases and
+            // subpaths included) — then the SAME ESM export walk the surface runs.
+            const file = api.fileForSpecifier(specifier);
+            if (!file?.path)
+                return undefined;
+            const hit = api.moduleExports(file.path).exports.find((e) => e.name === symbol);
+            if (hit === undefined)
+                return null;
+            return {
+                symbolId: hit.symbolId,
+                declaredIn: hit.declaredIn,
+                declKind: hit.declKind,
+                ...(hit.line !== undefined ? { line: hit.line } : {}),
+                ...(hit.isDefault === true ? { isDefault: true } : {}),
+            };
+        },
+    };
+}

package/dist/graph/index-behind-hint.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A "the index is N files behind" qualifier for a not-found / empty result, so
+ * an agent doesn't read a bare "not-found" as "this symbol doesn't exist / is
+ * safe to create" when the truth is "it's in a file the index hasn't seen yet."
+ *
+ * Runs the full freshness walk (`detectGraphFreshness`, the one freshness
+ * authority) — only call it on the rare miss path. Shared by the code-graph
+ * query verbs and `shrk reuse`.
+ */
+export declare function indexBehindHint(cwd: string): string | null;
+//# sourceMappingURL=index-behind-hint.d.ts.map

package/dist/graph/index-behind-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-behind-hint.d.ts","sourceRoot":"","sources":["../../src/graph/index-behind-hint.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc1D"}

package/dist/graph/index-behind-hint.js

@@ -0,0 +1,27 @@
+import { detectGraphFreshness } from '@shrkcrft/graph';
+/**
+ * A "the index is N files behind" qualifier for a not-found / empty result, so
+ * an agent doesn't read a bare "not-found" as "this symbol doesn't exist / is
+ * safe to create" when the truth is "it's in a file the index hasn't seen yet."
+ *
+ * Runs the full freshness walk (`detectGraphFreshness`, the one freshness
+ * authority) — only call it on the rare miss path. Shared by the code-graph
+ * query verbs and `shrk reuse`.
+ */
+export function indexBehindHint(cwd) {
+    const f = detectGraphFreshness(cwd);
+    if (!f.hasIndex)
+        return null;
+    const behind = f.modified.length + f.added.length + f.deleted.length;
+    const pkgs = f.packagesChanged;
+    if (behind === 0 && pkgs.length === 0)
+        return null;
+    const files = `${behind} file(s) (${f.modified.length} modified, ${f.added.length} new, ${f.deleted.length} deleted)`;
+    if (pkgs.length === 0) {
+        return `Index is ${behind} file(s) behind (${f.modified.length} modified, ${f.added.length} new, ${f.deleted.length} deleted) — run \`shrk graph index --changed\` and retry.`;
+    }
+    // A package.json entry edit changes what a bare import resolves to; only a
+    // full index re-resolves the imports of unchanged files.
+    const shown = pkgs.slice(0, 3).join(', ') + (pkgs.length > 3 ? `, +${pkgs.length - 3} more` : '');
+    return `Index is behind: ${behind > 0 ? `${files} and ` : ''}${pkgs.length} workspace package(s) changed (${shown}) — run \`shrk graph index\` and retry.`;
+}

package/dist/knowledge/knowledge-stale-gate-flags.d.ts

@@ -0,0 +1,3 @@
+/** Moved to `@shrkcrft/inspector` with the gate itself; re-exported so CLI imports stay unchanged. */
+export type { IKnowledgeStaleGateFlags } from '@shrkcrft/inspector';
+//# sourceMappingURL=knowledge-stale-gate-flags.d.ts.map

package/dist/knowledge/knowledge-stale-gate-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-stale-gate-flags.d.ts","sourceRoot":"","sources":["../../src/knowledge/knowledge-stale-gate-flags.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,YAAY,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/knowledge/knowledge-stale-gate-flags.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge/knowledge-stale-gate-input.d.ts

@@ -0,0 +1,3 @@
+/** Moved to `@shrkcrft/inspector` with the gate itself; re-exported so CLI imports stay unchanged. */
+export type { IKnowledgeStaleGateInput } from '@shrkcrft/inspector';
+//# sourceMappingURL=knowledge-stale-gate-input.d.ts.map

package/dist/knowledge/knowledge-stale-gate-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-stale-gate-input.d.ts","sourceRoot":"","sources":["../../src/knowledge/knowledge-stale-gate-input.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,YAAY,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/knowledge/knowledge-stale-gate-input.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge/knowledge-stale-gate-result.d.ts

@@ -0,0 +1,3 @@
+/** Moved to `@shrkcrft/inspector` with the gate itself; re-exported so CLI imports stay unchanged. */
+export type { IKnowledgeStaleGate } from '@shrkcrft/inspector';
+//# sourceMappingURL=knowledge-stale-gate-result.d.ts.map

package/dist/knowledge/knowledge-stale-gate-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-stale-gate-result.d.ts","sourceRoot":"","sources":["../../src/knowledge/knowledge-stale-gate-result.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/knowledge/knowledge-stale-gate-result.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge/knowledge-stale-gate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * THE knowledge stale-check verdict now lives in `@shrkcrft/inspector`
+ * (`knowledge-stale-gate.ts`), so `buildQualityReport` — MCP
+ * `get_quality_report`, the dashboard, the report site — settles the SAME gate
+ * as `shrk knowledge stale-check` and `shrk quality` (round 11 review: the MCP
+ * report had no knowledge gate at all). Re-exported here so every CLI import
+ * stays unchanged; there is no second implementation.
+ */
+export { evaluateKnowledgeStaleGate, formatPct, KNOWLEDGE_FAIL_ON_CATEGORIES, knowledgeStaleGateInput, knowledgeStaleWindowProblem, parseMinReferenced, settleKnowledgeStaleGate, } from '@shrkcrft/inspector';
+//# sourceMappingURL=knowledge-stale-gate.d.ts.map

package/dist/knowledge/knowledge-stale-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-stale-gate.d.ts","sourceRoot":"","sources":["../../src/knowledge/knowledge-stale-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,0BAA0B,EAC1B,SAAS,EACT,4BAA4B,EAC5B,uBAAuB,EACvB,2BAA2B,EAC3B,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC"}

package/dist/knowledge/knowledge-stale-gate.js

@@ -0,0 +1,9 @@
+/**
+ * THE knowledge stale-check verdict now lives in `@shrkcrft/inspector`
+ * (`knowledge-stale-gate.ts`), so `buildQualityReport` — MCP
+ * `get_quality_report`, the dashboard, the report site — settles the SAME gate
+ * as `shrk knowledge stale-check` and `shrk quality` (round 11 review: the MCP
+ * report had no knowledge gate at all). Re-exported here so every CLI import
+ * stays unchanged; there is no second implementation.
+ */
+export { evaluateKnowledgeStaleGate, formatPct, KNOWLEDGE_FAIL_ON_CATEGORIES, knowledgeStaleGateInput, knowledgeStaleWindowProblem, parseMinReferenced, settleKnowledgeStaleGate, } from '@shrkcrft/inspector';

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAMhB,MAAM,uBAAuB,CAAC;AA0Z/B,wBAAgB,aAAa,IAAI,eAAe,CAqZ/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgDrE;AAwID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAsb/B,wBAAgB,aAAa,IAAI,eAAe,CA4Z/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8DrE;AA+OD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}

package/dist/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { loadDotenv } from "./env/load-dotenv.js";
-import { CommandRegistry, extractGlobalCompress, extractGlobalCwd, extractGlobalExitTrailer, parseArgs, } from "./command-registry.js";
-import { argvHasExitTrailer, argvHasNoHints, argvHasStrict, emitPipeExitSignal, promoteForStrict, } from "./exit-codes.js";
+import { CommandRegistry, extractGlobalCwd, parseArgs, } from "./command-registry.js";
+import { argvHasExitTrailer, argvHasNoHints, argvHasStrict, emitPipeExitSignal, promoteForStrict, VERDICT_PATH_TOKENS, } from "./exit-codes.js";
 import { runCommandWithCompression } from "./output/output-compression.js";
 import { initCommand } from "./commands/init.command.js";
 import { inspectCommand } from "./commands/inspect.command.js";
@@ -37,9 +37,10 @@ import { gateCommand } from "./commands/gate.command.js";
 import { policyLintCommand, policyLintExplainCommand } from "./commands/policy-lint.command.js";
 import { baselineCheckCommand, baselineCommand, baselineDiffCommand, baselineExplainCommand, baselineListCommand, baselineUpdateCommand, } from "./commands/baseline.command.js";
 import { generatedCheckCommand, generatedExplainCommand, generatedListCommand, generatedUpdateCommand, } from "./commands/generated.command.js";
-import { gatesCommand, gatesCoverageCommand, gatesExplainCommand, gatesListCommand, } from "./commands/gates.command.js";
+import { gatesCheckCommand, gatesCommand, gatesCoverageCommand, gatesExplainCommand, gatesListCommand, gatesScaffoldSelfTestCommand, gatesTryCommand, } from "./commands/gates.command.js";
 import { wiringCommand } from "./commands/wiring.command.js";
 import { reuseCommand } from "./commands/reuse.command.js";
+import { reuseCoverageCommand } from "./commands/reuse-coverage.command.js";
 import { migrateCommand } from "./commands/migrate.command.js";
 import { coverageCommand } from "./commands/coverage.command.js";
 import { statsCommand } from "./commands/stats.command.js";
@@ -106,6 +107,7 @@ import { briefCommand } from "./commands/brief.command.js";
 import { releaseCommand, installSmokeCommand } from "./commands/release.command.js";
 import { startHereCommand } from "./commands/start-here.command.js";
 import { docsCheckCommand, examplesCheckCommand } from "./commands/docs.command.js";
+import { docsReferencesCommand } from "./commands/docs-references.command.js";
 import { selfAuditCommand } from "./commands/self.command.js";
 import { diagnosticsListCommand } from "./commands/diagnostics.command.js";
 import { architectureMapCommand } from "./commands/architecture.command.js";
@@ -147,8 +149,17 @@ import { errorFooterFor, renderErrorFooter } from "./output/failure-hints.js";
 import { renderAbout } from "./surface/about.js";
 import { renderNoArgsLanding } from "./surface/no-args-landing.js";
 import { loadSurfaceContext } from "./surface/load-surface-context.js";
+import { warnStaleCompiledPacks } from "./packs/stale-build-warning.js";
 import { buildSurfaceSummary, findCommandInSummary } from "./surface/surface-summary.js";
-import { makeSurfaceNotEnabledError, renderSurfaceNotEnabledText, SURFACE_NOT_ENABLED_EXIT_CODE, } from "./surface/not-enabled-error.js";
+import { commandIndexFor, setActiveCommandRegistry } from "./surface/command-index.js";
+import { editDistance, typoTolerance } from "./dispatch/closest-match.js";
+import { isPathTransparentGlobal, PATH_TRANSPARENCY, stripPreDispatchGlobals, withoutPathGlobals, } from "./dispatch/global-flags.js";
+import { judgeInvocation } from "./dispatch/judge-invocation.js";
+import { helpTopicFor, wantsHelp } from "./dispatch/help-intercept.js";
+import { beginFlagReadTracking, flagDocumentation, invocationFlagDocumentation, settleUnreadFlags, siblingsDocumenting, tracksFlagReads, } from "./dispatch/unread-flags.js";
+import { isStdoutPipe } from "./output/stdout-is-pipe.js";
+import { walkDeclaredSubverbs } from "./dispatch/walk-declared-subverbs.js";
+import { SURFACE_NOT_ENABLED_EXIT_CODE, surfaceRefusalFor, surfaceRefusalOutput, } from "./surface/not-enabled-error.js";
 import { extractCommandPath, recordUsage, sanitizeFlagNames, } from "./usage/usage-log.js";
 import { loadProjectConfig } from '@shrkcrft/config';
 export function buildRegistry() {
@@ -227,10 +238,16 @@ export function buildRegistry() {
     registry.registerSubcommand('generated', generatedExplainCommand);
     registry.register(gatesCommand);
     registry.registerSubcommand('gates', gatesListCommand);
+    registry.registerSubcommand('gates', gatesCheckCommand);
     registry.registerSubcommand('gates', gatesCoverageCommand);
     registry.registerSubcommand('gates', gatesExplainCommand);
+    registry.registerSubcommand('gates', gatesTryCommand);
+    registry.registerSubcommand('gates', gatesScaffoldSelfTestCommand);
     registry.register(wiringCommand);
     registry.register(reuseCommand);
+    // `shrk reuse coverage` — the trie's greedy descent routes the literal
+    // `coverage` here; any other intent still reaches `reuse` itself.
+    registry.registerSubcommand('reuse', reuseCoverageCommand);
     registry.register(migrateCommand);
     registry.register(coverageCommand);
     registry.register(statsCommand);
@@ -339,6 +356,7 @@ export function buildRegistry() {
     registry.registerSubcommand('memory', memorySnapshotsCommand);
     registry.register(languagesCommand);
     registry.registerSubcommand('docs', docsCheckCommand);
+    registry.registerSubcommand('docs', docsReferencesCommand);
     registry.registerSubcommand('examples', examplesCheckCommand);
     registry.registerSubcommand('self', selfAuditCommand);
     registry.registerSubcommand('install', installSmokeCommand);
@@ -539,21 +557,35 @@ export async function runCli(argv) {
     // and each command's own `--strict` semantics (e.g. `check --strict`) still
     // apply beneath this (a25 §1.1).
     const strict = argvHasStrict(argv);
-    // Derive the command path from an argv with the global --exit-trailer stripped:
-    // otherwise a LEADING `--exit-trailer` makes extractCommandPath break on the '-'
-    // and return "" — zeroing out both the pipe-exit signal and the usage record.
-    const command = extractCommandPath(extractGlobalExitTrailer(probeArgv).rest);
+    // THE registry this run dispatches from — the verdict path below and the
+    // dispatcher read the same one.
+    const registry = buildRegistry();
+    // Derive the command path from the argv the dispatcher reads: THE pre-dispatch
+    // strip (`--cwd`, `--exit-trailer`, `--compress*` — the one runCliInner uses),
+    // then the global `--no-hints` / `--strict` stepped over by the SAME descent.
+    // Otherwise a LEADING stripped global (`--exit-trailer`, `--compress`) makes
+    // extractCommandPath break on the '-' and return "" — zeroing out the pipe
+    // note, `--exit-trailer` and the usage record — while `doctor --strict
+    // warnings` must stay `doctor`.
+    const commandArgv = withoutPathGlobals(stripPreDispatchGlobals(argv).rest, registry);
+    const command = extractCommandPath(commandArgv);
+    // The verdict-verb check reads one token deeper than the usage record, so a
+    // three-token verdict verb (`docs references check`) is told apart from its
+    // informational siblings (`docs references list` / `explain`).
+    const verdictPath = extractCommandPath(commandArgv, VERDICT_PATH_TOKENS);
     let exitCode = 0;
     try {
-        exitCode = promoteForStrict(await runCliInner(argv), strict);
+        exitCode = promoteForStrict(await runCliInner(argv, registry), strict);
         // Keep the honest 0/1/2 verdict readable through a trailing pipe (the shape
         // an agent reaches for first). A no-op for non-gate verbs. Skipped inside the
         // smart-context worker child and the --compress re-run child, whose stdout is
         // a pipe by construction — a spurious "stdout is piped" note there (the user
         // never piped) would be noise, not signal.
         if (!process.env.SHRK_WORKER_EXITCODE_FILE && !process.env.SHRK_COMPRESS_CHILD) {
-            emitPipeExitSignal(command, exitCode, {
-                piped: !process.stdout.isTTY,
+            emitPipeExitSignal(verdictPath, exitCode, {
+                // A PIPE (or socket) to another process — never a plain file redirect,
+                // which is not a TTY either but has no downstream `$?` (round 13).
+                piped: isStdoutPipe(),
                 trailer: argvHasExitTrailer(argv),
                 noHints: argvHasNoHints(argv),
             });
@@ -600,16 +632,21 @@ async function isUsageEnabled(cwd) {
         return true;
     }
 }
-async function runCliInner(argv) {
-    const registry = buildRegistry();
-    // Pre-parse the global --cwd so it can appear anywhere (incl. before the command).
-    const { cwd: globalCwd, rest: cwdCleanArgv } = extractGlobalCwd(argv);
-    // Strip the global --exit-trailer here so no per-command flag-guard sees it;
-    // runCli reads it off the raw argv to decide whether to print the trailer.
-    const { rest: trailerCleanArgv } = extractGlobalExitTrailer(cwdCleanArgv);
-    // Pre-parse the global --compress / --ccr output-compression flags.
-    const { directive: compressDirective, rest: cleanArgv } = extractGlobalCompress(trailerCleanArgv);
-    const [first] = cleanArgv;
+async function runCliInner(argv, registry) {
+    // The ONE command index (surface list, help, the surface gate, the command
+    // resolver injected into the inspector) reads the registry this run
+    // dispatches from — commands never import main.ts to get it.
+    setActiveCommandRegistry(registry);
+    // THE pre-dispatch strip — the one runCli derives the verdict path from: the
+    // global --cwd (anywhere, incl. before the command), --exit-trailer (runCli
+    // reads it off the raw argv to decide whether to print the trailer) and the
+    // --compress / --ccr output-compression flags, so no per-command flag guard
+    // ever sees them.
+    const { cwd: globalCwd, compress: compressDirective, rest: cleanArgv } = stripPreDispatchGlobals(argv);
+    // The global `--strict` / `--no-hints` may LEAD the command
+    // (`shrk --no-hints scaffolds list`): the meta checks below read the first
+    // token that is not one of them, and the trie descent steps over them.
+    const first = cleanArgv.find((t) => !isPathTransparentGlobal(t));
     // `--compress` / `--ccr` on a real command: re-run it and compress its stdout.
     // (Meta verbs like --help/--version and bare invocations are left untouched.)
     if (compressDirective &&
@@ -651,11 +688,16 @@ async function runCliInner(argv) {
         process.stdout.write(renderAbout());
         return 0;
     }
-    // greedy trie descent. Handles 1-, 2-, and 3-level commands uniformly
+    // Greedy trie descent. Handles 1-, 2-, and 3-level commands uniformly
     // (`shrk doctor`, `shrk packs list`, `shrk pack author status`). The
     // resolver stops when it hits a flag or a token that isn't a child of the
-    // current node, returning the deepest handler + the leftover tokens.
-    let { handler, matchedPath, rest: leftover, node } = registry.resolve(cleanArgv);
+    // current node, returning the deepest handler + the leftover tokens. The
+    // global `--strict` / `--no-hints` are transparent to it while they sit
+    // inside the path — hoisted into the leftover instead of ending the descent
+    // at the first token — and past the path a bare `--strict` keeps the value
+    // after it (`doctor --strict warnings`). THE options: PATH_TRANSPARENCY.
+    const descend = (tokens) => registry.resolve(tokens, PATH_TRANSPARENCY);
+    let { handler, matchedPath, rest: leftover, node } = descend(cleanArgv);
     // A multi-word command passed as a SINGLE quoted token (`shrk "graph status"`)
     // arrives as one argv element with internal whitespace. The trie has no atomic
     // `graph status` node, so the first descent misses (handler undefined) — yet
@@ -664,32 +706,82 @@ async function runCliInner(argv) {
     // quoted form behaves identically to the unquoted `shrk graph status`.
     // Genuinely unknown tokens leave `handler` undefined and fall through to the
     // existing unknown-command path unchanged.
-    if (!handler && cleanArgv.length === 1 && /\s/.test(cleanArgv[0])) {
-        const retry = registry.resolve(cleanArgv[0].trim().split(/\s+/));
+    const bareArgv = cleanArgv.filter((t) => !isPathTransparentGlobal(t));
+    if (!handler && bareArgv.length === 1 && /\s/.test(bareArgv[0])) {
+        const retry = descend([
+            ...bareArgv[0].trim().split(/\s+/),
+            ...cleanArgv.filter(isPathTransparentGlobal),
+        ]);
         if (retry.handler) {
             ({ handler, matchedPath, rest: leftover, node } = retry);
         }
     }
-    // `--help` / `-h` immediately after a (sub)group → render help for that
-    // path. This works at any depth.
-    if (leftover[0] === '--help' || leftover[0] === '-h') {
-        return registry.get('help').run(parseArgs([matchedPath.join(' ')], { globalCwd }));
+    // `--help` / `-h` ANYWHERE before `--` — after a subverb, a positional or
+    // another flag, at any depth — prints help for the deepest path the command
+    // index knows, and NOTHING else runs: no guard, no surface gate, no
+    // inspection, no command body. (Only a leading `--help` used to be caught:
+    // `report site --help` wrote twelve HTML files, `graph index --help` built
+    // the store.) Tokens after `--` pass through untouched.
+    if (matchedPath.length > 0 && wantsHelp(leftover)) {
+        const topic = helpTopicFor(commandIndexFor(registry), matchedPath, leftover);
+        return registry.get('help').run(parseArgs([topic.join(' ')], { globalCwd }));
     }
+    const trieChildren = [...node.children.keys()];
     if (handler) {
-        // gate experimental commands. Bootstrap commands and core/extended
-        // tiers pass through; experimental commands return the structured
-        // not-enabled error unless `surface.enabled[]` contains them.
-        const gateReason = await checkSurfaceGate(matchedPath, globalCwd ?? process.cwd());
-        if (gateReason) {
-            const err = makeSurfaceNotEnabledError(gateReason.command, { reason: gateReason.detail });
-            process.stderr.write(renderSurfaceNotEnabledText(err));
+        const parsed = parseArgs(leftover, { globalCwd, booleanFlags: handler.booleanFlags });
+        // THE pre-run judgement (round 11 §5.2, `judgeInvocation` — the function the
+        // command-string resolver calls too): an unknown subcommand, a verb-shaped
+        // token that is neither a subverb nor a file, a flag outside a declared set,
+        // or a flag no documentation of the command names is refused BEFORE
+        // anything runs — cheap, no inspection — instead of a default action that
+        // exits 0 (or a write that happens before the refusal).
+        const rejection = judgeInvocation({
+            registry,
+            handler,
+            matchedPath,
+            trieChildren,
+            parsed,
+            cwd: globalCwd ?? process.cwd(),
+        });
+        if (rejection) {
+            process.stderr.write(rejection.message);
+            return rejection.exitCode;
+        }
+        // The surface gate. Bootstrap commands and core/extended tiers pass
+        // through; an experimental command not in `surface.enabled[]`, a
+        // tool-maintenance command outside SharkCraft's own repository, or a
+        // command `surface.disabled[]` denies returns the structured refusal
+        // (exit 78 — never a check verdict).
+        const refusal = await checkSurfaceGate(handler, matchedPath, parsed.positional, globalCwd ?? process.cwd());
+        if (refusal) {
+            // `--json` / `--format json` get the documented machine form on stdout
+            // (`sharkcraft.surface.not-enabled.v1` + `reasonCode`); otherwise the text
+            // on stderr — `surfaceRefusalOutput`, the one writer.
+            const output = surfaceRefusalOutput(refusal, parsed);
+            if (output.stdout)
+                process.stdout.write(output.stdout);
+            if (output.stderr)
+                process.stderr.write(output.stderr);
             return SURFACE_NOT_ENABLED_EXIT_CODE;
         }
-        return await handler.run(parseArgs(leftover, { globalCwd, booleanFlags: handler.booleanFlags }));
+        return await runWithFlagReadTracking(registry, handler, matchedPath, parsed);
     }
-    // No handler at the deepest match. If we landed on a group node (has
-    // children), show that group's help so the user discovers the verbs.
+    // No handler at the deepest match: a command group. A bare token under it
+    // is an unknown subcommand (`templates lst` → did you mean `templates
+    // list`?), never the group's help at exit 0; a bare group lists its verbs.
     if (matchedPath.length > 0 && node.children.size > 0) {
+        const rejection = judgeInvocation({
+            registry,
+            handler: undefined,
+            matchedPath,
+            trieChildren,
+            parsed: parseArgs(leftover, { globalCwd }),
+            cwd: globalCwd ?? process.cwd(),
+        });
+        if (rejection) {
+            process.stderr.write(rejection.message);
+            return rejection.exitCode;
+        }
         return registry.get('help').run(parseArgs([matchedPath.join(' ')], { globalCwd }));
     }
     // Genuinely unknown — fall back to free-form / did-you-mean.
@@ -703,6 +795,43 @@ async function runCliInner(argv) {
     printDidYouMean(attempted);
     return 2;
 }
+/**
+ * Run `handler`, then judge the flags it never READ — the universal post-run
+ * detector (`dispatch/unread-flags.ts`). An undocumented non-presentation flag
+ * was already refused before the run (`judgeInvocation`), so this backstop
+ * warns about an undocumented presentation flag and catches a flag name
+ * computed at runtime: a `0` over a dropped input becomes `usageExitFor(path)`. Skipped for a
+ * handler that declares `flags` (the pre-run guard already judged them) or
+ * `forwardsArgv` (a child process re-parses the argv). The declared-subverb
+ * walk is taken BEFORE the run — some handlers consume `args.positional`.
+ */
+async function runWithFlagReadTracking(registry, handler, matchedPath, parsed) {
+    const walk = walkDeclaredSubverbs(handler, matchedPath, parsed.positional);
+    if (!tracksFlagReads(handler, walk))
+        return await handler.run(parsed);
+    // Captured BEFORE the run — some handlers consume `args.positional`.
+    const positional = [...parsed.positional];
+    const unread = beginFlagReadTracking(parsed);
+    const exit = await handler.run(parsed);
+    // The flag documentation (which builds the command index) is needed only to
+    // judge an unread flag — the common run reads every flag it was given, so it
+    // pays nothing. settleUnreadFlags returns `exit` untouched for no unread flag.
+    // The INVOCATION's documentation, as the pre-run refusal read it (round 13:
+    // per subverb, never a sibling's).
+    const unreadKeys = unread();
+    if (unreadKeys.length === 0)
+        return exit;
+    const index = commandIndexFor(registry);
+    return settleUnreadFlags({
+        unread: unreadKeys,
+        path: walk.path.join(' '),
+        documentation: invocationFlagDocumentation({ handler, matchedPath, positional, index }),
+        groupDocumentation: flagDocumentation(handler, matchedPath, index),
+        documentedOn: (key) => siblingsDocumenting(key, matchedPath, walk.path, index),
+        exit,
+        argv: parsed.argv,
+    });
+}
 /**
  * Heuristic for "this looks like a task, not a command".
  *
@@ -784,32 +913,44 @@ function printFreeFormTaskHint(task) {
         `  $ shrk commands\n`);
 }
 /**
- * Check whether the resolved command path is gated by the
- * surface tier model. Returns `null` if the command is callable
- * (core/extended), or `{ command, detail }` if it is an experimental
- * command not enabled in the current repo's surface config.
+ * Check whether the invoked command is gated by the surface tier model.
+ * Returns `null` if the command is callable (core/extended), or the
+ * structured refusal (`surfaceRefusalFor`) — an experimental command not
+ * enabled, a tool-maintenance command outside SharkCraft's own repository, or
+ * a command a `surface.disabled` selector denies.
+ *
+ * The view is looked up at the deepest DECLARED path first
+ * (`walkDeclaredSubverbs`: `release readiness` and `commands doctor` are
+ * subverbs one handler dispatches, so the trie path alone — `release` — could
+ * never gate them), then at each shorter prefix down to the top-level token.
  *
  * Failure-soft: any error loading the inspection (fresh repo, no
  * config, etc.) lets the command through. The gate must NEVER false-
  * positive a bootstrap call — the bootstrap set in `tier.ts` plus
  * spine-derived core commands always pass through cleanly.
  */
-async function checkSurfaceGate(matchedPath, cwd) {
-    const candidate = matchedPath.join(' ');
-    if (candidate.length === 0)
+async function checkSurfaceGate(handler, matchedPath, positional, cwd) {
+    if (matchedPath.length === 0)
         return null;
+    const walk = walkDeclaredSubverbs(handler, matchedPath, positional);
+    const candidates = [];
+    for (let n = walk.path.length; n >= 1; n -= 1)
+        candidates.push(walk.path.slice(0, n).join(' '));
     try {
-        const { context } = await loadSurfaceContext({ cwd });
+        const { context, inspection } = await loadSurfaceContext({ cwd });
+        // Startup warning: a pack serving compiled contributions built from an
+        // older source (the one pack-asset freshness authority; content, not age).
+        warnStaleCompiledPacks(inspection);
         const summary = buildSurfaceSummary(context);
-        // Try the full path first; fall back to the top-level token. The
-        // catalog uses both shapes ("doctor" and "plan review").
-        const view = findCommandInSummary(summary, candidate) ??
-            findCommandInSummary(summary, matchedPath[0] ?? '');
-        if (!view)
-            return null;
-        if (view.callable)
+        let view;
+        for (const candidate of candidates) {
+            view = findCommandInSummary(summary, candidate);
+            if (view)
+                break;
+        }
+        if (!view || view.callable)
             return null;
-        return { command: view.command, detail: view.detail };
+        return surfaceRefusalFor(view);
     }
     catch {
         return null;
@@ -838,29 +979,6 @@ function reorderCandidates(attempted, candidates) {
     });
     return ranked;
 }
-/** Edit distance (Levenshtein). Used to gate did-you-mean confidence. */
-function editDistance(a, b) {
-    const m = a.length;
-    const n = b.length;
-    if (m === 0)
-        return n;
-    if (n === 0)
-        return m;
-    const dp = new Array(n + 1);
-    for (let j = 0; j <= n; j += 1)
-        dp[j] = j;
-    for (let i = 1; i <= m; i += 1) {
-        let prev = dp[0];
-        dp[0] = i;
-        for (let j = 1; j <= n; j += 1) {
-            const tmp = dp[j];
-            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-            dp[j] = Math.min(dp[j] + 1, dp[j - 1] + 1, prev + cost);
-            prev = tmp;
-        }
-    }
-    return dp[n];
-}
 /**
  * Suggestion is "confident" when the candidate's top token is close
  * to the attempt in edit-distance terms — `doctorz`→`doctor` (1 edit)
@@ -877,9 +995,9 @@ function isConfidentMatch(attempted, suggestion) {
         return false;
     const lower = attempted.toLowerCase();
     const head = (suggestion.command.split(/\s+/)[0] ?? suggestion.command).toLowerCase();
-    const dist = editDistance(lower, head);
-    const tolerance = Math.max(1, Math.floor(lower.length / 4));
-    return dist <= tolerance;
+    // The ONE typo tolerance (dispatch/closest-match.ts) — shared with help's
+    // topic suggestion and the dispatcher guard's closest subcommand / flag.
+    return editDistance(lower, head) <= typoTolerance(lower);
 }
 function printDidYouMean(attempted) {
     const rawCandidates = suggestDidYouMean(COMMAND_CATALOG, [attempted], 5);
@@ -958,13 +1076,16 @@ async function redirectStderrToTeardownLog() {
 // Bun exposes `import.meta.main`; Node does not. When Node runs the
 // compiled `dist/main.js` directly the path-suffix check (`main.js`)
 // catches it. The npm bin shim points at `shrk` so that suffix also
-// triggers it. Source dev under Bun still runs via `main.ts`.
+// triggers it. Source dev under Bun still runs via `main.ts`. The bin target
+// is the round-13 bootstrap `dist/shrk.js` (source `src/shrk.ts`), which
+// imports this module — its suffixes are recognised the same way.
 const isMain = typeof import.meta !== 'undefined' && import.meta.main === true;
 const entryPath = process.argv[1] ?? '';
 if (isMain ||
     entryPath.endsWith('main.ts') ||
     entryPath.endsWith('main.js') ||
     entryPath.endsWith('shrk') ||
+    entryPath.endsWith('shrk.ts') ||
     entryPath.endsWith('shrk.js') ||
     entryPath.endsWith('shrk.cmd')) {
     // Marks a real CLI invocation (vs. a command handler imported directly by a

package/dist/output/failure-hints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"failure-hints.d.ts","sourceRoot":"","sources":["../../src/output/failure-hints.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAUzE;AAID,wBAAgB,WAAW,IAAI,YAAY,EAAE,CAM5C;AAED,wBAAgB,mBAAmB,IAAI,YAAY,EAAE,CAMpD;AAED,wBAAgB,kBAAkB,IAAI,YAAY,EAAE,CAMnD;AAED,wBAAgB,yBAAyB,IAAI,YAAY,EAAE,CAK1D;AAED,wBAAgB,6BAA6B,IAAI,YAAY,EAAE,CAK9D;AAED,wBAAgB,kBAAkB,IAAI,YAAY,EAAE,CAKnD;AAED,wBAAgB,wBAAwB,IAAI,YAAY,EAAE,CAKzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAiB9D;AAED,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,mBAAmB,GACnB,gBAAgB,GAChB,oBAAoB,GACpB,uBAAuB,GACvB,kBAAkB,GAClB,eAAe,GACf,2BAA2B,GAC3B,sBAAsB,GACtB,+BAA+B,GAC/B,wBAAwB,GACxB,8BAA8B,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,GAAG,SAAS,CA4E3G"}
+{"version":3,"file":"failure-hints.d.ts","sourceRoot":"","sources":["../../src/output/failure-hints.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAUzE;AAID,wBAAgB,WAAW,IAAI,YAAY,EAAE,CAM5C;AAED,wBAAgB,mBAAmB,IAAI,YAAY,EAAE,CAMpD;AAED,wBAAgB,kBAAkB,IAAI,YAAY,EAAE,CAMnD;AAED,wBAAgB,yBAAyB,IAAI,YAAY,EAAE,CAK1D;AAED,wBAAgB,6BAA6B,IAAI,YAAY,EAAE,CAO9D;AAED,wBAAgB,kBAAkB,IAAI,YAAY,EAAE,CAKnD;AAED,wBAAgB,wBAAwB,IAAI,YAAY,EAAE,CAKzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAiB9D;AAED,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,mBAAmB,GACnB,gBAAgB,GAChB,oBAAoB,GACpB,uBAAuB,GACvB,kBAAkB,GAClB,eAAe,GACf,2BAA2B,GAC3B,sBAAsB,GACtB,+BAA+B,GAC/B,wBAAwB,GACxB,8BAA8B,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,GAAG,SAAS,CA4E3G"}