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

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;AA6Z/B,wBAAgB,aAAa,IAAI,eAAe,CAwZ/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 { gatesCheckCommand, gatesCommand, gatesCoverageCommand, gatesExplainCommand, gatesListCommand, gatesTryCommand, } 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";
@@ -148,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() {
@@ -232,8 +242,12 @@ export function buildRegistry() {
     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);
@@ -543,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),
             });
@@ -604,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 &&
@@ -655,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
@@ -668,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.
@@ -707,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".
  *
@@ -788,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;
@@ -842,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)
@@ -881,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);
@@ -962,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"}

package/dist/output/failure-hints.js

@@ -41,8 +41,10 @@ export function fuzzyImpactAmbiguousHints() {
 }
 export function agentTestMissingExpectedHints() {
     return [
-        { label: 'explain a missing id', command: 'shrk why <id> --for-task "<task>"' },
-        { label: 'explain why not', command: 'shrk why-not <id> --for-task "<task>"' },
+        // `why <id> --for-task` / `why-not` are gone (`why` explains a FILE now);
+        // the ranking trace for a task lives on `task` and `search`.
+        { label: 'see how each id ranked for the task (or why it was left out)', command: 'shrk task "<task>" --explain-ranking' },
+        { label: 'see what the ranker matched for the query', command: 'shrk search "<task>" --explain' },
     ];
 }
 export function ciReportEmptyHints() {
@@ -87,25 +89,25 @@ export function errorFooterFor(kind, context) {
             return {
                 next: `shrk recommend "${task}"`,
                 why: 'Free-form input routes to the canonical human entrypoint — `shrk recommend` ranks commands for a query without writes.',
-                more: ['shrk commands', 'shrk commands suggest "<partial>"', 'shrk start-here'],
+                more: ['shrk commands', 'shrk commands search "<partial>"', 'shrk start-here'],
             };
         case 'ambiguous-command':
             return {
-                next: 'shrk commands suggest "<partial>"',
+                next: 'shrk commands search "<partial>"',
                 why: 'Multiple commands matched the input — narrow it down or pick the canonical entrypoint.',
-                more: ['shrk commands explain <cmd>', 'shrk commands overlaps'],
+                more: ['shrk help <cmd>', 'shrk commands overlaps'],
             };
         case 'apply-rejected':
             return {
                 next: 'shrk plan review <plan.json>',
                 why: 'The apply gate refused the plan — review the safety report before retrying.',
-                more: ['shrk plan verify <plan.json>', 'shrk safety audit --deep'],
+                more: ['shrk plan simulate <plan.json>', 'shrk safety audit --deep'],
             };
         case 'signature-mismatch':
             return {
-                next: 'shrk plan verify <plan.json>',
-                why: 'The plan signature does not match the source content — re-sign or regenerate before retrying.',
-                more: ['shrk plan sign <plan.json>', 'shrk gen <template> --save-plan <plan.json>'],
+                next: 'shrk plan review <plan.json>',
+                why: 'The plan signature does not match the source content — regenerate the plan (which re-signs it) before retrying.',
+                more: ['shrk gen <template> --save-plan <plan.json>'],
             };
         case 'contract-gate-blocked':
             return {

package/dist/output/rejected-entries-note.d.ts

@@ -0,0 +1,57 @@
+/**
+ * THE list-verb note (round 12, 12.1 — and, since the round-12 review (A-4),
+ * the files that failed to load).
+ *
+ * A contributed entry its loader refused used to vanish: the `list` verb
+ * printed the survivors and exited 0, and nothing said an entry was dropped.
+ * A contribution FILE that failed to import dropped every entry it declares
+ * just as silently — `conventions list` even pointed at that very file as the
+ * place to contribute. Every list verb now prints, after its list, one line
+ * per file:
+ *
+ *   ⚠ sharkcraft/conventions.ts failed to load (boom) — nothing in it is listed → shrk conventions doctor
+ *   ⚠ 2 entries rejected from node_modules/@r12/pack/conventions.ts: 'conv.b' (default[8]) — severity: …; 'conv.j' (default[9]) — … → shrk conventions doctor
+ *
+ * with the wording of THE formatter (`formatEntryRejection`), from THE channel
+ * (`collectKindOutcomes`). A list verb is not a verdict: its exit stays 0.
+ * Under `--json` the stdout array is untouched (a parser never breaks) and the
+ * note goes to stderr, one line per failed file plus one for the rejections.
+ */
+import { type ContributionKind, type IContributionEntryRejection, type IContributionLoadFailure, type IKindOutcomes, type inspectSharkcraft } from '@shrkcrft/inspector';
+type IInspection = Awaited<ReturnType<typeof inspectSharkcraft>>;
+/** The note lines (text, stdout) — `''` when nothing was rejected. */
+export declare function rejectedEntriesNote(rejections: readonly IContributionEntryRejection[], projectRoot: string, next?: string): string;
+/** The one-line `--json` stderr form — `''` when nothing was rejected. */
+export declare function rejectedEntriesStderrNote(rejections: readonly IContributionEntryRejection[], projectRoot: string, next?: string): string;
+/** One line per contribution file that failed to load (text, stdout) — `''` when every file loaded. */
+export declare function loadFailuresNote(failures: readonly IContributionLoadFailure[], projectRoot: string, next?: string): string;
+/** The `--json` stderr form, one line per failed file — `''` when every file loaded. */
+export declare function loadFailuresStderrNote(failures: readonly IContributionLoadFailure[], projectRoot: string, next?: string): string;
+/**
+ * What `kinds`' loaders reported — refused entries and files that never
+ * loaded — narrowed to `--source`. `loadFailures: false` for a verb that
+ * already reports its own load failures (knowledge list's partial-list WARN,
+ * helper list's broken-file line), so no failure is said twice.
+ */
+export declare function collectListVerbNote(inspection: IInspection, kinds: readonly ContributionKind[], options?: {
+    readonly source?: string;
+    readonly loadFailures?: boolean;
+}): Promise<IKindOutcomes>;
+/** Write a collected note: text after the list on stdout, or stderr lines under `--json`. */
+export declare function writeListVerbNote(outcomes: IKindOutcomes, projectRoot: string, options?: {
+    readonly json?: boolean;
+    readonly next?: string;
+}): void;
+/**
+ * Collect `kinds`' outcomes (THE channel, running only the loaders those
+ * kinds need) and write the note: text after the list on stdout, or stderr
+ * lines under `--json`. Returns the rejections it reported.
+ */
+export declare function writeRejectedEntriesNote(inspection: IInspection, kinds: readonly ContributionKind[], options?: {
+    readonly json?: boolean;
+    readonly source?: string;
+    readonly next?: string;
+    readonly loadFailures?: boolean;
+}): Promise<readonly IContributionEntryRejection[]>;
+export {};
+//# sourceMappingURL=rejected-entries-note.d.ts.map

package/dist/output/rejected-entries-note.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rejected-entries-note.d.ts","sourceRoot":"","sources":["../../src/output/rejected-entries-note.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAE7B,KAAK,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC;AAUjE,sEAAsE;AACtE,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,2BAA2B,EAAE,EAClD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAaR;AAED,0EAA0E;AAC1E,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,SAAS,2BAA2B,EAAE,EAClD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAIR;AAED,uGAAuG;AACvG,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,wBAAwB,EAAE,EAC7C,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAUR;AAED,wFAAwF;AACxF,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,EAC7C,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAUR;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,WAAW,EACvB,KAAK,EAAE,SAAS,gBAAgB,EAAE,EAClC,OAAO,GAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAC1E,OAAO,CAAC,aAAa,CAAC,CAMxB;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,aAAa,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAChE,IAAI,CAaN;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,WAAW,EACvB,KAAK,EAAE,SAAS,gBAAgB,EAAE,EAClC,OAAO,GAAE;IACP,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CAC5B,GACL,OAAO,CAAC,SAAS,2BAA2B,EAAE,CAAC,CAIjD"}