@shrkcrft/cli 0.1.0-alpha.19 → 0.1.0-alpha.20

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

@@ -15,7 +15,7 @@ import { asJson, header, kv } from "../output/format-output.js";
 export const apiDiffCommand = {
     name: 'api-diff',
     description: 'Compare the current public API surface to a saved baseline. Reports added / removed / kind-changed / moved symbols, with breaking-change severity.',
-    usage: 'shrk api-diff capture --output <path> [--packages a,b] [--with-signatures] | shrk api-diff <baseline.json> [--packages a,b] [--with-signatures] [--json] [--fail-on-breaking]',
+    usage: 'shrk api-diff capture --output <path> [--packages @scope/a,@scope/b] [--with-signatures] | shrk api-diff <baseline.json> [--packages @scope/a,@scope/b] [--with-signatures] [--json] [--fail-on-breaking]   (--packages takes EXACT workspace package names, comma-separated or repeated)',
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');
@@ -96,6 +96,7 @@ async function runDiff(args, cwd, wantJson, baselinePath) {
 function readSurfaceFromCwd(cwd, args) {
     const packages = flagList(args, 'packages');
     const withSignatures = flagBool(args, 'with-signatures');
+    let surface;
     if (withSignatures) {
         const result = extractApiSurfaceWithProgram({
             projectRoot: cwd,
@@ -104,13 +105,40 @@ function readSurfaceFromCwd(cwd, args) {
         for (const d of result.diagnostics.slice(0, 5)) {
             process.stderr.write(`! ${d}\n`);
         }
-        return result.surface;
+        surface = result.surface;
     }
-    const store = new GraphStore(cwd);
-    if (!store.exists()) {
-        process.stderr.write("Code-graph store missing. Run 'shrk graph index' first.\n");
+    else {
+        const store = new GraphStore(cwd);
+        if (!store.exists()) {
+            process.stderr.write("Code-graph store missing. Run 'shrk graph index' first.\n");
+            return undefined;
+        }
+        const snap = store.loadSnapshot();
+        surface = extractApiSurface(snap, {
+            ...(packages.length > 0 ? { packageFilter: packages } : {}),
+        });
+    }
+    return applyPackageFilterGuard(surface, packages);
+}
+/**
+ * A `--packages` filter that resolves to no known workspace package is a quiet
+ * footgun: the extractor silently returns a 0-symbol surface (exit 0) that is
+ * indistinguishable from a package that genuinely exports nothing. When EVERY
+ * requested filter is unknown, abort loudly; when only some are, warn and keep
+ * the partial result.
+ */
+function applyPackageFilterGuard(surface, packages) {
+    const unmatched = surface.unmatchedFilters ?? [];
+    if (packages.length === 0 || unmatched.length === 0)
+        return surface;
+    const matched = Object.keys(surface.countsByPackage).filter((k) => k !== '<no-package>');
+    if (unmatched.length === packages.length) {
+        process.stderr.write(`--packages matched no known workspace package: ${unmatched.join(', ')}\n` +
+            '  Pass exact package names (npm "name", e.g. @shrkcrft/core), comma-separated or repeated.\n');
         return undefined;
     }
-    const snap = store.loadSnapshot();
-    return extractApiSurface(snap, { ...(packages.length > 0 ? { packageFilter: packages } : {}) });
+    process.stderr.write(`! --packages: ignoring unknown package(s): ${unmatched.join(', ')}` +
+        (matched.length > 0 ? ` (matched: ${matched.join(', ')})` : '') +
+        '\n');
+    return surface;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"codemod.command.d.ts","sourceRoot":"","sources":["../../src/commands/codemod.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoDhC,eAAO,MAAM,cAAc,EAAE,eAoE5B,CAAC"}
+{"version":3,"file":"codemod.command.d.ts","sourceRoot":"","sources":["../../src/commands/codemod.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAuEhC,eAAO,MAAM,cAAc,EAAE,eAsE5B,CAAC"}

package/dist/commands/codemod.command.js

@@ -8,23 +8,41 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { affectedFromCheckReport, buildCodemodAssistReport, inspectSharkcraft, parseCustomCheckReportFromFile, renderCodemodAssistMarkdown, } from '@shrkcrft/inspector';
-import { flagBool, flagString, flagList, resolveCwd, } from "../command-registry.js";
+import { formatRuleCompact } from '@shrkcrft/rules';
+import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
 async function loadRule(args) {
     const ruleId = flagString(args, 'rule');
     if (!ruleId) {
-        process.stderr.write('Missing --rule <ruleId>\n');
+        process.stderr.write('Missing --rule <ruleId>. Run `shrk codemod list` to see available rule ids.\n');
         return null;
     }
     const cwd = resolveCwd(args);
     const inspection = await inspectSharkcraft({ cwd });
     const rule = inspection.ruleService.get(ruleId);
     if (!rule) {
-        process.stderr.write(`No rule with id "${ruleId}".\n`);
+        process.stderr.write(`No rule with id "${ruleId}". Run \`shrk codemod list\` to see available rule ids.\n`);
         return null;
     }
     return { rule, cwd };
 }
+/** `shrk codemod list` — enumerate the rule ids codemod-assist accepts. */
+async function listRules(args) {
+    const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
+    let rules = inspection.ruleService.list();
+    const top = flagNumber(args, 'top');
+    if (top !== undefined && top > 0) {
+        rules = [...rules].sort((a, b) => a.id.localeCompare(b.id)).slice(0, top);
+    }
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson(rules.map((r) => ({ id: r.id, type: r.type, priority: r.priority, title: r.title }))) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Codemod rules (${rules.length})`));
+    for (const r of rules)
+        process.stdout.write(formatRuleCompact(r) + '\n');
+    return 0;
+}
 async function gatherAffected(args) {
     const fromReport = flagString(args, 'from-report');
     const out = [];
@@ -57,14 +75,17 @@ function writeAssistOutputs(cwd, ruleId, markdown, scriptTemplate) {
 export const codemodCommand = {
     name: 'codemod',
     description: 'Codemod-assist (NOT a codemod engine). Inventory + risk grouping + checklist + project-script template. Never rewrites source.',
-    usage: 'shrk codemod <inventory|plan|checklist> --rule <ruleId> [--from-report <path>] [--targets a,b,c] [--write-preview] [--json]',
+    usage: 'shrk codemod <list|inventory|plan|checklist> --rule <ruleId> [--from-report <path>] [--targets a,b,c] [--write-preview] [--json]',
     async run(args) {
         const sub = args.positional[0] ?? 'plan';
-        if (!['inventory', 'plan', 'checklist'].includes(sub)) {
-            process.stderr.write('Usage: shrk codemod <inventory|plan|checklist> --rule <ruleId>\n');
+        if (!['list', 'inventory', 'plan', 'checklist'].includes(sub)) {
+            process.stderr.write('Usage: shrk codemod <list|inventory|plan|checklist> --rule <ruleId>\n');
             return 2;
         }
         const inner = { ...args, positional: args.positional.slice(1) };
+        // `list` enumerates rule ids and needs no --rule.
+        if (sub === 'list')
+            return listRules(inner);
         const loaded = await loadRule(inner);
         if (!loaded)
             return 1;

package/dist/commands/command-catalog.d.ts

@@ -266,4 +266,12 @@ export interface ICommandSafetyMatrixRow {
 }
 export declare function buildCommandSafetyMatrix(): readonly ICommandSafetyMatrixRow[];
 export declare function renderCommandSafetyMatrixMarkdown(rows: readonly ICommandSafetyMatrixRow[]): string;
+/**
+ * The set of TOP-LEVEL command verbs in the catalogue (the first token of each
+ * entry's `command`). The single source of truth for "is `shrk <verb>` a real
+ * command" checks — e.g. the contradictions doc-vs-CLI scan, which lives in the
+ * inspector layer and so receives this set by injection rather than importing
+ * the CLI.
+ */
+export declare function cliCommandNameSet(): Set<string>;
 //# sourceMappingURL=command-catalog.d.ts.map

package/dist/commands/command-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}

package/dist/commands/command-catalog.js

@@ -3572,3 +3572,24 @@ export function renderCommandSafetyMatrixMarkdown(rows) {
     }
     return lines.join('\n') + '\n';
 }
+/**
+ * The set of TOP-LEVEL command verbs in the catalogue (the first token of each
+ * entry's `command`). The single source of truth for "is `shrk <verb>` a real
+ * command" checks — e.g. the contradictions doc-vs-CLI scan, which lives in the
+ * inspector layer and so receives this set by injection rather than importing
+ * the CLI.
+ */
+export function cliCommandNameSet() {
+    const out = new Set();
+    for (const entry of COMMAND_CATALOG) {
+        const top = entry.command.split(/\s+/)[0];
+        if (top)
+            out.add(top);
+        for (const alias of entry.aliases) {
+            const aliasTop = alias.split(/\s+/)[0];
+            if (aliasTop)
+                out.add(aliasTop);
+        }
+    }
+    return out;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2BhC,eAAO,MAAM,eAAe,EAAE,eAgF7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}
+{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,eAAe,EAAE,eA8F7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}

package/dist/commands/compress.command.js

@@ -5,6 +5,10 @@ import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-regist
 import { asJson } from "../output/format-output.js";
 import { ccrDir, openCcrStore } from "../output/ccr-store-config.js";
 const CONTENT_TYPES = new Set(Object.values(EContentType));
+// Below this size a passthrough no-op isn't worth a warning (tiny snippets
+// legitimately have nothing to compress). Above it, a silent `−0%` re-emit is
+// the opposite of the tool's purpose — nudge the user toward `--type`.
+const PASSTHROUGH_HINT_MIN_BYTES = 128;
 function readInput(args) {
     const positional = args.positional[0];
     const useStdin = flagBool(args, 'stdin') || positional === undefined || positional === '-';
@@ -97,6 +101,16 @@ export const compressCommand = {
         process.stdout.write(result.compressed + '\n');
         const cached = result.ccrKey ? ` · original cached as ${result.ccrKey} (shrk expand ${result.ccrKey})` : '';
         process.stderr.write(`${result.strategy}: ~${result.savings.before} → ~${result.savings.after} tokens (−${pct}%, est.)${cached}\n`);
+        // Token-economy guard: when auto-detect declines to compress a non-trivial
+        // input, a silent `−0%` re-emit looks like success. Nudge toward `--type`
+        // (stdout stays the verbatim blob; exit code unchanged).
+        const inputBytes = Buffer.byteLength(content, 'utf8');
+        if (result.strategy === ECompressionStrategy.Passthrough &&
+            inputBytes >= PASSTHROUGH_HINT_MIN_BYTES &&
+            !flagBool(args, 'lossless')) {
+            process.stderr.write(`hint: nothing was compressed — auto-detect classified this as ${result.contentType} and found no win. ` +
+                'Try `--type <content-type>` to force a strategy (json, git-diff, search-results, build-log, source-code, markdown).\n');
+        }
         return 0;
     },
 };

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

@@ -1 +1 @@
-{"version":3,"file":"constructs.command.d.ts","sourceRoot":"","sources":["../../src/commands/constructs.command.ts"],"names":[],"mappings":"AA6BA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAahC,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAoDlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA8DpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAoErC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAmCtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAwBpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAiClC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA4BrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA8BrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0DpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0LpC,CAAC"}
+{"version":3,"file":"constructs.command.d.ts","sourceRoot":"","sources":["../../src/commands/constructs.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiGhC,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAoDlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAwFpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAoErC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAmCtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAwBpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAiClC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA4BrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA8BrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0DpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0LpC,CAAC"}

package/dist/commands/constructs.command.js

@@ -1,6 +1,7 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { AdoptionCheckpointStatus, buildConstructAdoptionDiff, buildConstructAdoptionPlan, buildSearchIndex, ConstructAdoptionCategory, evaluateAdoptionCheckpoint, hashDiffBody, inferConstructs, InferredConstructConfidence, inspectSharkcraft, loadConstructs, loadPlaybooks, readAdoptionCheckpoint, readConstructAdoptionStatus, recordAdoptionCheckpoint, renderConstructAdoptionDiff, renderConstructAdoptionMarkdown, renderConstructDraftsModule, searchIndex, SearchKind, traceConstruct, writeConstructAdoption, } from '@shrkcrft/inspector';
+import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
 import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
 async function loadAll(args) {
@@ -9,6 +10,64 @@ async function loadAll(args) {
     const constructs = await loadConstructs(inspection);
     return { constructs, inspection };
 }
+const GLOB_MAGIC = /[*?[\]{}]/;
+function globToRegExp(glob) {
+    // Compile a minimal file glob (`**`, `*`, `?`) to an anchored RegExp. Mark the
+    // wildcards with control-char placeholders BEFORE regex-escaping the rest, so
+    // the escape pass and the wildcard expansion can never clobber each other (an
+    // earlier space-sentinel version was corrupted by editor whitespace handling).
+    const DSTAR_SLASH = '\u0000';
+    const DSTAR = '\u0001';
+    const STAR = '\u0002';
+    const QMARK = '\u0003';
+    const marked = glob
+        .replace(/\*\*\//g, DSTAR_SLASH)
+        .replace(/\*\*/g, DSTAR)
+        .replace(/\*/g, STAR)
+        .replace(/\?/g, QMARK);
+    const pattern = marked
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replaceAll(DSTAR_SLASH, '(?:.*/)?')
+        .replaceAll(DSTAR, '.*')
+        .replaceAll(STAR, '[^/]*')
+        .replaceAll(QMARK, '[^/]');
+    return new RegExp(`^${pattern}$`);
+}
+function enrichTraceWithGraph(declaredFiles, declaredNames, cwd) {
+    if (!new GraphStore(cwd).exists()) {
+        return { graphState: 'missing', resolvedFiles: [], unresolvedGlobs: [], undeclaredSymbols: [] };
+    }
+    const api = GraphQueryApi.fromStore(cwd);
+    const allPaths = [...api.allFiles()].map((n) => n.path).filter((p) => !!p);
+    const resolved = new Set();
+    const unresolvedGlobs = [];
+    for (const entry of declaredFiles) {
+        if (GLOB_MAGIC.test(entry)) {
+            const re = globToRegExp(entry);
+            const matches = allPaths.filter((p) => re.test(p));
+            if (matches.length === 0)
+                unresolvedGlobs.push(entry);
+            for (const m of matches)
+                resolved.add(m);
+        }
+        else if (api.findFile(entry)) {
+            resolved.add(entry);
+        }
+    }
+    const undeclared = new Set();
+    for (const path of resolved) {
+        for (const sym of api.symbolsIn(`file:${path}`)) {
+            if (sym.label && !declaredNames.has(sym.label))
+                undeclared.add(sym.label);
+        }
+    }
+    return {
+        graphState: 'fresh',
+        resolvedFiles: [...resolved].sort(),
+        unresolvedGlobs,
+        undeclaredSymbols: [...undeclared].sort(),
+    };
+}
 export const constructsListCommand = {
     name: 'list',
     description: 'List registered constructs.',
@@ -91,7 +150,7 @@ export const constructsGetCommand = {
 };
 export const constructsTraceCommand = {
     name: 'trace',
-    description: 'Trace all files / publicApi / events / tokens belonging to a construct. --deep adds related / test pointers when present.',
+    description: 'Trace a construct\'s declared files / publicApi / events / tokens, verified against the code graph (expands file globs, flags globs that match nothing, lists undeclared symbols defined in those files). --deep adds related / test pointers.',
     usage: 'shrk constructs trace <id> [--deep] [--json]',
     async run(args) {
         const id = args.positional[0];
@@ -107,6 +166,10 @@ export const constructsTraceCommand = {
         }
         const trace = traceConstruct(c);
         const deep = flagBool(args, 'deep');
+        // Verify the hand-declared inventory against the code graph (additive — does
+        // not change the declared files/tokens the other subverbs rely on).
+        const declaredNames = new Set([...trace.publicApi, ...trace.tokens, ...trace.events]);
+        const graph = enrichTraceWithGraph(trace.files, declaredNames, resolveCwd(args));
         const relatedAll = [
             ...(c.relatedKnowledge ?? []),
             ...(c.relatedRules ?? []),
@@ -122,7 +185,7 @@ export const constructsTraceCommand = {
             }
             : undefined;
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson({ ...trace, ...(deepBlock ? { deep: deepBlock } : {}) }) + '\n');
+            process.stdout.write(asJson({ ...trace, graph, ...(deepBlock ? { deep: deepBlock } : {}) }) + '\n');
             return 0;
         }
         process.stdout.write(header(`Trace: ${id}`));
@@ -145,6 +208,26 @@ export const constructsTraceCommand = {
             for (const w of trace.warnings)
                 process.stdout.write(`  ! ${w}\n`);
         }
+        // Graph-verified view: this is the part that makes the declared inventory
+        // trustworthy rather than a hand-typed partial map.
+        if (graph.graphState === 'missing') {
+            process.stdout.write('\n(declared inventory only — run `shrk graph index` for a graph-verified inventory)\n');
+        }
+        else {
+            if (graph.unresolvedGlobs.length > 0) {
+                process.stdout.write('Unresolved file globs (matched 0 files in the graph):\n');
+                for (const g of graph.unresolvedGlobs)
+                    process.stdout.write(`  ! ${g}\n`);
+            }
+            if (graph.undeclaredSymbols.length > 0) {
+                process.stdout.write(`Graph found ${graph.undeclaredSymbols.length} symbol(s) defined in these files but NOT declared on the construct:\n`);
+                for (const s of graph.undeclaredSymbols.slice(0, 30))
+                    process.stdout.write(`  + ${s}\n`);
+                if (graph.undeclaredSymbols.length > 30) {
+                    process.stdout.write(`  … (${graph.undeclaredSymbols.length - 30} more)\n`);
+                }
+            }
+        }
         if (deepBlock) {
             process.stdout.write('\nDeep:\n');
             if (deepBlock.related.length > 0)

package/dist/commands/contract-gate.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/contract-gate.command.ts"],"names":[],"mappings":"AAYA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAWhC,eAAO,MAAM,oBAAoB,EAAE,eAqDlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA6EpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eA6DnC,CAAC"}
+{"version":3,"file":"contract-gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/contract-gate.command.ts"],"names":[],"mappings":"AAYA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAWhC,eAAO,MAAM,oBAAoB,EAAE,eAqDlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA6EpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAiEnC,CAAC"}

package/dist/commands/contract-gate.command.js

@@ -148,7 +148,11 @@ export const contractStatusCommand = {
     async run(args) {
         const contractFile = args.positional[0];
         if (!contractFile) {
-            process.stderr.write('Usage: shrk contract status <contract.json>\n');
+            // `contract status` inspects a SAVED contract file — it is not a zero-arg
+            // project-health command. Point at the canonical task form so the verb
+            // doesn't read as a broken status command.
+            process.stderr.write('Usage: shrk contract status <contract.json>   (inspect a saved contract file)\n');
+            process.stderr.write('To build/inspect a contract for a task, run:  shrk contract "<task>"\n');
             return 2;
         }
         const cwd = resolveCwd(args);

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

@@ -1 +1 @@
-{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eA2FzB,CAAC"}
+{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eA+FzB,CAAC"}

package/dist/commands/gate.command.js

@@ -18,7 +18,7 @@ import { asJson, header, kv } from "../output/format-output.js";
 export const gateCommand = {
     name: 'gate',
     description: 'Aggregator: runs the code-intelligence quality gates (graph freshness, architecture, impact-since-ref) and reports a single pass/fail.',
-    usage: 'shrk gate [--since <gitref>] [--fail-on critical,high] [--disable arch,impact,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]',
+    usage: 'shrk gate [--since <gitref>] [--fail-on critical,high] [--arch-all] [--disable arch,impact,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         (the arch gate is baseline-relative by default once a baseline is frozen — fails only on NEW errors; --arch-all fails on total)\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]',
     async run(args) {
         if (args.positional[0] === 'scaffold-ci') {
             const sliced = { ...args, positional: args.positional.slice(1) };
@@ -42,8 +42,12 @@ export const gateCommand = {
             ? failOnRaw.split(',').map((s) => s.trim()).filter(Boolean)
             : undefined;
         const disable = disableRaw ? disableRaw.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+        // --arch-all: fail on TOTAL architecture errors (ignore the frozen baseline).
+        // By default the arch gate is baseline-relative — it fails only on NEW errors.
+        const archAll = flagBool(args, 'arch-all');
         const report = runQualityGates({
             projectRoot: cwd,
+            ...(archAll ? { arch: { baselineRelative: false } } : {}),
             impact: {
                 ...(sinceRef ? { sinceRef } : {}),
                 ...(failOn ? { failOn } : {}),

package/dist/commands/graph-code-subverbs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAiI3F,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+DtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwF1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmFtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgMvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAuHtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA0EvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}
+{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAiI3F,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+DtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwF1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmFtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgMvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+EvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}

package/dist/commands/graph-code-subverbs.js

@@ -878,6 +878,11 @@ export async function runGraphImpact(args) {
     for (const d of liveDirect.slice(0, 30)) {
         process.stdout.write(`  ${d.path ?? d.id}\n`);
     }
+    // No silent caps: when the reverse closure hit the limit, say so explicitly so
+    // the reader knows the blast radius is larger than what's shown.
+    if (closure.truncated) {
+        process.stdout.write(`\n  ⓘ Showing ${liveDirect.length + liveTransitive.length} of ${payload.totalReached} dependents (capped at --limit ${limit}); raise --limit to see the full blast radius.\n`);
+    }
     if (fresh.field) {
         process.stdout.write(`\n  ⚠ ${fresh.modified.length} dependent file(s) changed, ${fresh.deleted.length} deleted since indexing — run \`shrk graph index --changed\`.\n`);
     }
@@ -980,7 +985,11 @@ export async function runGraphCallers(args) {
     const ambiguityNote = alsoNamed > 0
         ? `${alsoNamed + 1} symbols named "${sym.label}"; showing callers of the one at ${sym.path ?? sym.id}${sym.line ? ':' + sym.line : ''}. Pass a symbol: id to disambiguate.`
         : undefined;
-    const note = [ambiguityNote, langNote].filter(Boolean).join(' ');
+    // `total` is distinct caller FILES: at index time the graph collapses many
+    // call/reference sites in one file to a single edge. Say so, otherwise `total`
+    // reads as a raw invocation count and under-reports.
+    const dedupNote = 'total counts distinct caller files — multiple sites within one file collapse to a single entry.';
+    const note = [ambiguityNote, langNote, dedupNote].filter(Boolean).join(' ');
     const payload = {
         schema: 'sharkcraft.graph-callers/v1',
         symbol: nodeSummary(sym),

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

@@ -1 +1 @@
-{"version":3,"file":"ingest.command.d.ts","sourceRoot":"","sources":["../../src/commands/ingest.command.ts"],"names":[],"mappings":"AAyCA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC;AAmZF,eAAO,MAAM,qBAAqB,EAAE,eAenC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eA8B9B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAkC9B,CAAC"}
+{"version":3,"file":"ingest.command.d.ts","sourceRoot":"","sources":["../../src/commands/ingest.command.ts"],"names":[],"mappings":"AA0CA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC;AAmZF,eAAO,MAAM,qBAAqB,EAAE,eAkBnC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eA8B9B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAkC9B,CAAC"}

package/dist/commands/ingest.command.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { cliCommandNameSet } from "./command-catalog.js";
 import { applyIngestPlan, buildContradictionReport, buildGeneratedCodeReport, buildIngestAdoptionPlan, buildIngestApplyPlan, buildRepositoryKnowledgeModel, buildStabilityMap, inspectSharkcraft, IngestAdoptionStatus, IngestDepth, IngestSection, loadIngestApplyPlan, renderContradictionReportHtml, renderContradictionReportJson, renderContradictionReportMarkdown, renderContradictionReportText, renderGeneratedCodeReportJson, renderGeneratedCodeReportMarkdown, renderGeneratedCodeReportText, renderIngestAdoptionPatch, renderIngestAdoptionPlanMarkdown, renderIngestApplyReviewMarkdown, renderRepositoryKnowledgeModelHtml, renderRepositoryKnowledgeModelJson, renderRepositoryKnowledgeModelMarkdown, renderRepositoryKnowledgeModelText, renderStabilityMapJson, renderStabilityMapMarkdown, renderStabilityMapText, saveIngestApplyPlan, signIngestApplyPlan, writeIngestAdoption, writeIngestDrafts, } from '@shrkcrft/inspector';
 import { flagBool, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
@@ -442,7 +443,10 @@ export const contradictionsCommand = {
         const cwd = resolveCwd(args);
         const format = parseFormat(flagString(args, 'format'));
         const inspection = await inspectSharkcraft({ cwd });
-        const report = buildContradictionReport({ inspection });
+        const report = buildContradictionReport({
+            inspection,
+            cliCommandNames: cliCommandNameSet(),
+        });
         if (format === 'json')
             process.stdout.write(renderContradictionReportJson(report) + '\n');
         else if (format === 'markdown')

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

@@ -1 +1 @@
-{"version":3,"file":"knowledge.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoFhC,eAAO,MAAM,oBAAoB,EAAE,eA2ClC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAqCpC,CAAC;AAoBF,eAAO,MAAM,0BAA0B,EAAE,eAWxC,CAAC;AA8NF,eAAO,MAAM,sBAAsB,EAAE,eAQpC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8CxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuBrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,eA8B1C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8BxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eAkC1C,CAAC"}
+{"version":3,"file":"knowledge.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge.command.ts"],"names":[],"mappings":"AAkBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoFhC,eAAO,MAAM,oBAAoB,EAAE,eA8ClC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAqCpC,CAAC;AAoBF,eAAO,MAAM,0BAA0B,EAAE,eAWxC,CAAC;AA8NF,eAAO,MAAM,sBAAsB,EAAE,eAQpC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8CxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuBrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,eA8B1C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8BxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eAkC1C,CAAC"}

package/dist/commands/knowledge.command.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join as nodePathJoin, resolve as nodePathResolve } from 'node:path';
 import { buildAnchorUpdatePlan, buildKnowledgeStaleReport, buildRenameFilePlan, buildRenameSymbolPlan, inspectSharkcraft, ReferenceCheckOutcome, resolveChangedFiles, } from '@shrkcrft/inspector';
-import { formatEntryCompact, formatEntryFull, searchKnowledge } from '@shrkcrft/knowledge';
+import { formatEntryCompact, formatEntryFull, projectKnowledgeEntryForJson, searchKnowledge, } from '@shrkcrft/knowledge';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
@@ -84,7 +84,10 @@ export const knowledgeListCommand = {
                     tags: e.tags,
                     appliesWhen: e.appliesWhen,
                 }))
-                : entries.map((e) => ({ ...e }));
+                : // Project the declared IKnowledgeEntry fields by direct access rather
+                    // than spreading (`{ ...e }`), which copies only own-enumerable props
+                    // and would strip pack entries whose fields are getters/non-enumerable.
+                    entries.map(projectKnowledgeEntryForJson);
             process.stdout.write(asJson(payload) + '\n');
             return 0;
         }

package/dist/commands/plan-context.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/plan-context.command.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA2DhC,CAAC"}
+{"version":3,"file":"plan-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/plan-context.command.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAsEhC,CAAC"}

package/dist/commands/plan-context.command.js

@@ -11,7 +11,7 @@ import { asJson, header, kv } from "../output/format-output.js";
  */
 export const planContextCommand = {
     name: 'plan-context',
-    description: 'Produce a deterministic, token-budgeted context pack (`sharkcraft.context-pack/v1`) for an AI agent: ranked files, applicable rules, likely tests, surfaced risks, do-not-touch zones.',
+    description: 'Produce a deterministic, token-budgeted context pack (`sharkcraft.context-pack/v1`) for an AI agent: ranked files, likely tests, and (shallow) surfaced risks / do-not-touch zones. Rules/paths/templates require the rule-graph bridge (`shrk rule-graph index`); the pack reports per-field `coverage` so empty sections are distinguishable from not-computed ones.',
     usage: 'shrk plan-context "<task>" [--budget N] [--max-files N] [--hint-file <path>] [--hint-package <prefix>] [--json]',
     async run(args) {
         const cwd = resolveCwd(args);
@@ -40,11 +40,19 @@ export const planContextCommand = {
         process.stdout.write(header(`Context pack: ${task}`));
         process.stdout.write(kv('intent', pack.intent) + '\n');
         process.stdout.write(kv('files', String(pack.files.length)) + '\n');
-        process.stdout.write(kv('rules', String(pack.rules.length)) + '\n');
-        process.stdout.write(kv('paths', String(pack.paths.length)) + '\n');
-        process.stdout.write(kv('templates', String(pack.templates.length)) + '\n');
+        // Distinguish "computed, none apply" from "not computed". When the bridge
+        // is missing, rules/paths/templates are omitted, not empty — say so rather
+        // than printing a misleading `0`.
+        if (pack.coverage.rulesComputed) {
+            process.stdout.write(kv('rules', String(pack.rules.length)) + '\n');
+            process.stdout.write(kv('paths', String(pack.paths.length)) + '\n');
+            process.stdout.write(kv('templates', String(pack.templates.length)) + '\n');
+        }
+        else {
+            process.stdout.write(kv('rules/paths/templates', 'not computed (run `shrk rule-graph index`)') + '\n');
+        }
         process.stdout.write(kv('tests', String(pack.tests.length)) + '\n');
-        process.stdout.write(kv('risks', String(pack.risks.length)) + '\n');
+        process.stdout.write(kv('risks', pack.coverage.risksComputed ? String(pack.risks.length) : 'not computed') + '\n');
         process.stdout.write(kv('budget', `${pack.budget.used}/${pack.budget.requested} tokens` + (pack.budget.truncated ? ' (truncated)' : '')) + '\n');
         if (pack.files.length > 0) {
             process.stdout.write('\nTop files:\n');

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

@@ -1 +1 @@
-{"version":3,"file":"recommend.command.d.ts","sourceRoot":"","sources":["../../src/commands/recommend.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,gBAAgB,EAAE,eA+M9B,CAAC;AAgHF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAY3D;AAcD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcxD"}
+{"version":3,"file":"recommend.command.d.ts","sourceRoot":"","sources":["../../src/commands/recommend.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,gBAAgB,EAAE,eAkP9B,CAAC;AA0HF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAY3D;AAcD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcxD"}

package/dist/commands/recommend.command.js

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { buildUniversalSearch, entrypointBanner, explainTaskRouting, inspectSharkcraft, recommendCommands, renderUncertaintyReportText, } from '@shrkcrft/inspector';
+import { buildUniversalSearch, entrypointBanner, explainTaskRouting, inspectSharkcraft, rankAll, recommendCommands, renderUncertaintyReportText, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson } from "../output/format-output.js";
 import { loadSurfaceContext } from "../surface/load-surface-context.js";
@@ -65,6 +65,10 @@ export const recommendCommand = {
         const machineJson = flagBool(args, 'json') || flagBool(args, 'machine-json');
         let routingMatches = [];
         let searchReport = null;
+        // Reconcile with `brief`/`task`: those route through the SAME shared ranker
+        // (`rankAll`). Consult it here so `recommend` never claims a "coverage gap"
+        // for a task the rest of the engine confidently matches to a template/pipeline.
+        let ranking = null;
         if (query.length > 0) {
             try {
                 routingMatches = await explainTaskRouting(inspection, query);
@@ -78,7 +82,17 @@ export const recommendCommand = {
             catch {
                 searchReport = null;
             }
+            try {
+                ranking = rankAll(inspection, query);
+            }
+            catch {
+                ranking = null;
+            }
         }
+        const topTemplate = ranking?.templates[0];
+        const topPipeline = ranking?.pipelines[0];
+        const engineHasMatch = (topTemplate?.score ?? 0) >= TEMPLATE_MATCH_THRESHOLD ||
+            (topPipeline?.score ?? 0) >= PIPELINE_MATCH_THRESHOLD;
         // R1 — promote a strongly-matched task-routing hint's recommends.commands
         // into the HEADLINE for create/build intents. Routing hints are scored by
         // explainTaskRouting but were previously only shown under --verbose, so the
@@ -115,6 +129,12 @@ export const recommendCommand = {
                 routingMatches,
                 search: searchReport,
                 gated,
+                rankerMatch: ranking
+                    ? {
+                        topTemplate: topTemplate ? { id: topTemplate.item.id, score: topTemplate.score } : null,
+                        topPipeline: topPipeline ? { id: topPipeline.item.id, score: topPipeline.score } : null,
+                    }
+                    : null,
             }) + '\n');
             return 0;
         }
@@ -158,16 +178,29 @@ export const recommendCommand = {
                 }
             }
         }
-        // Coverage gap — explicit if recommendations look thin and no routing hint fired.
-        if (report.recommendations.length <= 1 &&
-            routingMatches.length === 0 &&
-            query.length > 0) {
+        // Coverage gap — explicit if recommendations look thin AND no routing hint
+        // fired AND the shared ranker (the engine `brief`/`task` use) also found no
+        // template/pipeline. The last clause stops `recommend` from contradicting
+        // `task`/`brief`, which would confidently route the same task.
+        const thinResult = report.recommendations.length <= 1 && routingMatches.length === 0 && query.length > 0;
+        if (thinResult && !engineHasMatch) {
             process.stdout.write(`\n⚠ Coverage gap — no recipe, no routing hint, and no helper/template matched "${query}".\n` +
                 `  Suggest:\n` +
                 `    shrk coverage scaffolds --task "${query}"\n` +
                 `    shrk feedback actions\n` +
                 `    (or contribute a pack template / helper / routing hint)\n`);
         }
+        else if (thinResult && engineHasMatch && !actionsOnly) {
+            // The recipe/routing surface was thin, but the shared ranker DID match —
+            // surface that concrete next step instead of a misleading gap.
+            process.stdout.write('\nEngine match (shared ranker — same as `shrk task` / `shrk brief`):\n');
+            if (topTemplate && topTemplate.score >= TEMPLATE_MATCH_THRESHOLD) {
+                process.stdout.write(`  $ shrk gen ${topTemplate.item.id} <name> --dry-run  [writes-source] — template "${topTemplate.item.name}" matched (score ${topTemplate.score}).\n`);
+            }
+            if (topPipeline && topPipeline.score >= PIPELINE_MATCH_THRESHOLD) {
+                process.stdout.write(`  Pipeline: ${topPipeline.item.id} — run \`shrk task "${query}"\` for the full packet.\n`);
+            }
+        }
         if (gated.length > 0 && !actionsOnly) {
             process.stdout.write(`\nGated (experimental, not enabled in this repo):\n`);
             for (const g of gated.slice(0, 3)) {
@@ -287,6 +320,15 @@ const PLANNING_VERBS = new Set([
  * keyword/regex hits — a real match, not a single weak keyword.
  */
 const ROUTING_HINT_PROMOTE_THRESHOLD = 3;
+/**
+ * Minimum `rankAll` score for a template / pipeline to count as a real engine
+ * match — used only to suppress a false "coverage gap" verdict (and surface the
+ * match) when the recipe/routing surface is thin but the shared ranker, which
+ * `brief`/`task` also use, found project coverage. Conservative: a single weak
+ * token hit scores below this.
+ */
+const TEMPLATE_MATCH_THRESHOLD = 3;
+const PIPELINE_MATCH_THRESHOLD = 3;
 const CREATE_BUILD_VERBS = new Set([
     'create', 'build', 'add', 'generate', 'scaffold', 'implement', 'make', 'new', 'introduce', 'write',
 ]);

package/dist/commands/task-context.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/task-context.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAahC,eAAO,MAAM,qBAAqB,EAAE,eAyEnC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAmEnC,CAAC;AAIF,eAAO,MAAM,mBAAmB,EAAE,eA2DjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAoBlC,CAAC"}
+{"version":3,"file":"task-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/task-context.command.ts"],"names":[],"mappings":"AAuBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAahC,eAAO,MAAM,qBAAqB,EAAE,eAyEnC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAsEnC,CAAC;AAIF,eAAO,MAAM,mBAAmB,EAAE,eA2DjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAoBlC,CAAC"}

package/dist/commands/task-context.command.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { cliCommandNameSet } from "./command-catalog.js";
 import { analyzeImportGraph, buildAgentBrief, buildContradictionReport, buildGeneratedCodeReport, buildRepositoryKnowledgeModel, buildTaskPacket, buildTaskRiskReport, classifyChangeIntent, detectLanguageProfiles, getChangedFiles, getStatusSummary, inspectSharkcraft, isGitRepo, listConstructs, loadRepositoryMemory, } from '@shrkcrft/inspector';
 import { flagBool, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
@@ -102,7 +103,10 @@ export const validateChangeCommand = {
         }
         // Fallback path through getStatusSummary not necessary — getChangedFiles already covers it.
         void getStatusSummary;
-        const contradictions = buildContradictionReport({ inspection });
+        const contradictions = buildContradictionReport({
+            inspection,
+            cliCommandNames: cliCommandNameSet(),
+        });
         const generated = buildGeneratedCodeReport({ inspection });
         const generatedPaths = new Set(generated.generatedFiles.map((f) => f.path));
         const boundaryHits = changed.filter((f) => looksLikeBoundaryViolation(f));

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,EAKhB,MAAM,uBAAuB,CAAC;AAwX/B,wBAAgB,aAAa,IAAI,eAAe,CA4X/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAsHD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA4CxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAwX/B,wBAAgB,aAAa,IAAI,eAAe,CA4X/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAsHD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}

package/dist/main.js

@@ -644,7 +644,15 @@ async function runCliInner(argv) {
  * Exported for tests.
  */
 export function looksLikeFreeFormTask(tokens) {
-    const clean = tokens.filter((t) => t.length > 0 && !t.startsWith('-'));
+    // Flatten on internal whitespace so the canonical *quoted* form
+    // (`shrk "refactor the auth module"`) — which the shell delivers as ONE argv
+    // element — is counted by word, exactly like the unquoted multi-token form.
+    // Without this, the documented quoted form was a single token (length 1) and
+    // fell through to the did-you-mean matcher instead of routing to `recommend`.
+    const clean = tokens
+        .filter((t) => t.length > 0 && !t.startsWith('-'))
+        .flatMap((t) => t.trim().split(/\s+/))
+        .filter((w) => w.length > 0);
     if (clean.length < 2)
         return false;
     // 3+ tokens is almost always a sentence, not a command — `shrk` only has

package/dist/surface/profiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/surface/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uEAAuE;IACvE,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAgID,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAOrD,CAAC;AAEH,gEAAgE;AAChE,wBAAgB,aAAa,CAC3B,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAQ9B;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CACxB,EAAE,EAAE,MAAM,EACV,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,eAAe,GAAG,SAAS,CAE7B"}
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/surface/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uEAAuE;IACvE,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAmLD,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAOrD,CAAC;AAEH,gEAAgE;AAChE,wBAAgB,aAAa,CAC3B,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAQ9B;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CACxB,EAAE,EAAE,MAAM,EACV,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,eAAe,GAAG,SAAS,CAE7B"}

package/dist/surface/profiles.js

@@ -10,6 +10,7 @@
  * Profiles are PURE DATA — no logic, no AI. Adding a profile is just
  * adding an entry here (or in a pack manifest).
  */
+import { COMMAND_CATALOG } from "../commands/command-catalog.js";
 /**
  * `developer` profile. Default for monorepo / app-with-libs shapes.
  * Hides nothing — pack authors / power users see the full extended
@@ -108,20 +109,64 @@ const CI_PROFILE = {
     ],
 };
 /**
- * `agent` profile. Optimized for MCP / agent use. Hides interactive
- * verbs; keeps JSON / read-only verbs visible.
+ * Generic machinery categories that are noise for an inline coding agent:
+ * CI / release gates, pack maintenance & signing, bundle replay, provenance,
+ * report generation, schema / governance / ingestion / lifecycle / polyglot /
+ * integration tooling. Commands stay fully CALLABLE — the agent profile just
+ * filters them from the agent-facing listing.
+ */
+const AGENT_HIDDEN_CATEGORIES = new Set([
+    'release',
+    'ci',
+    'bundles',
+    'bundle',
+    'packs',
+    'pack-author',
+    'provenance',
+    'reports',
+    'schemas',
+    'governance',
+    'ingestion',
+    'lifecycle',
+    'export',
+    'polyglot',
+    'integrations',
+]);
+/** Read-only discovery verbs kept visible even though their category is hidden,
+ *  so an agent can still inspect packs. */
+const AGENT_KEEP_VISIBLE = new Set(['packs list', 'packs doctor']);
+/** Interactive / write-source verbs hidden from the agent surface. */
+const AGENT_INTERACTIVE_HIDDEN = [
+    'dev',
+    'dev start',
+    'dev status',
+    'dev report',
+    'orchestrate',
+    'ask',
+];
+/**
+ * Derive the hidden command list from machinery categories MECHANICALLY from the
+ * catalogue, so it never drifts as commands are added/removed.
+ */
+function deriveHiddenByCategory(hiddenCats, keep) {
+    return COMMAND_CATALOG.filter((e) => hiddenCats.has(e.category) && !keep.has(e.command))
+        .map((e) => e.command)
+        .sort();
+}
+/**
+ * `agent` profile. Optimized for inline coding-agent / MCP use. Hides
+ * interactive verbs AND CI/release/pack-maintenance machinery; favors JSON-pipe
+ * read surfaces. Every hidden command remains callable (hide != disable).
  */
 const AGENT_PROFILE = {
     id: 'agent',
-    description: 'Agent / MCP-friendly default. Hides interactive verbs; favors JSON-pipe surfaces.',
+    description: 'Agent / MCP-friendly default. Hides interactive verbs + CI/release/pack-maintenance machinery from the listing (commands stay callable); favors JSON-pipe read surfaces.',
     source: 'builtin',
     hidden: [
-        'dev',
-        'dev start',
-        'dev status',
-        'dev report',
-        'orchestrate',
-        'ask',
+        ...new Set([
+            ...AGENT_INTERACTIVE_HIDDEN,
+            ...deriveHiddenByCategory(AGENT_HIDDEN_CATEGORIES, AGENT_KEEP_VISIBLE),
+        ]),
     ],
 };
 /** Catalog of built-in profiles. */

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@shrkcrft/cli",
-  "version": "0.1.0-alpha.19",
+  "version": "0.1.0-alpha.20",
   "description": "SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.",
   "license": "MIT",
   "author": "SharkCraft contributors",
   "type": "module",
   "main": "./dist/index.js",
-  "types": "./dist/index.d.d.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -47,38 +47,38 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.19",
-    "@shrkcrft/compress": "^0.1.0-alpha.19",
-    "@shrkcrft/config": "^0.1.0-alpha.19",
-    "@shrkcrft/workspace": "^0.1.0-alpha.19",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.19",
-    "@shrkcrft/context": "^0.1.0-alpha.19",
-    "@shrkcrft/rules": "^0.1.0-alpha.19",
-    "@shrkcrft/paths": "^0.1.0-alpha.19",
-    "@shrkcrft/templates": "^0.1.0-alpha.19",
-    "@shrkcrft/plugin-api": "^0.1.0-alpha.19",
-    "@shrkcrft/dashboard": "^0.1.0-alpha.19",
-    "@shrkcrft/dashboard-api": "^0.1.0-alpha.19",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.19",
-    "@shrkcrft/presets": "^0.1.0-alpha.19",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.19",
-    "@shrkcrft/graph": "^0.1.0-alpha.19",
-    "@shrkcrft/rule-graph": "^0.1.0-alpha.19",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.19",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.19",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.19",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.19",
-    "@shrkcrft/framework-scanners": "^0.1.0-alpha.19",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.19",
-    "@shrkcrft/quality-gates": "^0.1.0-alpha.19",
-    "@shrkcrft/migrate": "^0.1.0-alpha.19",
-    "@shrkcrft/generator": "^0.1.0-alpha.19",
-    "@shrkcrft/importer": "^0.1.0-alpha.19",
-    "@shrkcrft/inspector": "^0.1.0-alpha.19",
-    "@shrkcrft/ai": "^0.1.0-alpha.19",
-    "@shrkcrft/embeddings": "^0.1.0-alpha.19",
-    "@shrkcrft/shared": "^0.1.0-alpha.19",
-    "@shrkcrft/mcp-server": "^0.1.0-alpha.19",
+    "@shrkcrft/core": "^0.1.0-alpha.20",
+    "@shrkcrft/compress": "^0.1.0-alpha.20",
+    "@shrkcrft/config": "^0.1.0-alpha.20",
+    "@shrkcrft/workspace": "^0.1.0-alpha.20",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.20",
+    "@shrkcrft/context": "^0.1.0-alpha.20",
+    "@shrkcrft/rules": "^0.1.0-alpha.20",
+    "@shrkcrft/paths": "^0.1.0-alpha.20",
+    "@shrkcrft/templates": "^0.1.0-alpha.20",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.20",
+    "@shrkcrft/dashboard": "^0.1.0-alpha.20",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.20",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.20",
+    "@shrkcrft/presets": "^0.1.0-alpha.20",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.20",
+    "@shrkcrft/graph": "^0.1.0-alpha.20",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.20",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.20",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.20",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.20",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.20",
+    "@shrkcrft/framework-scanners": "^0.1.0-alpha.20",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.20",
+    "@shrkcrft/quality-gates": "^0.1.0-alpha.20",
+    "@shrkcrft/migrate": "^0.1.0-alpha.20",
+    "@shrkcrft/generator": "^0.1.0-alpha.20",
+    "@shrkcrft/importer": "^0.1.0-alpha.20",
+    "@shrkcrft/inspector": "^0.1.0-alpha.20",
+    "@shrkcrft/ai": "^0.1.0-alpha.20",
+    "@shrkcrft/embeddings": "^0.1.0-alpha.20",
+    "@shrkcrft/shared": "^0.1.0-alpha.20",
+    "@shrkcrft/mcp-server": "^0.1.0-alpha.20",
     "@huggingface/transformers": "^3.7.5"
   },
   "publishConfig": {