@shrkcrft/cli 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/commands/commands.command.js

@@ -1,7 +1,7 @@
-import { flagBool, flagString, } from "../command-registry.js";
+import { flagBool, flagString } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
-import { COMMAND_CATALOG, CommandLifecycle, CommandSurface, R46_OVERLAY, SafetyLevel, buildCommandSafetyMatrix, commandLifecycle, commandSurface, commandTaskRole, defaultShowInHelp, renderCommandSafetyMatrixMarkdown, } from "./command-catalog.js";
-import { buildCommandTaxonomy, buildPrimaryCommandsReport, renderCommandTaxonomyMarkdown, renderCommandTaxonomyText, renderPrimaryCommandsText, } from '@shrkcrft/inspector';
+import { buildCommandSafetyMatrix, COMMAND_CATALOG, CommandLifecycle, commandLifecycle, CommandSurface, commandSurface, commandTaskRole, defaultShowInHelp, R46_OVERLAY, renderCommandSafetyMatrixMarkdown, SafetyLevel } from "./command-catalog.js";
+import { buildCommandTaxonomy, buildPrimaryCommandsReport, renderCommandTaxonomyMarkdown, renderCommandTaxonomyText, renderPrimaryCommandsText } from '@shrkcrft/inspector';
 export function makeCommandsCommand(registry) {
     return {
         name: 'commands',
@@ -589,7 +589,7 @@ export function buildCommandsUxReport() {
     // issue is clearly structural (none of these currently rise to error).
     for (const e of COMMAND_CATALOG) {
         const surface = commandSurface(e);
-        // (a) primary commands should declare an audience (so adopters can see
+        // (a) primary commands should declare an audience (so consumers can see
         // who the command is for at a glance).
         if (surface === CommandSurface.Primary && (!e.intendedAudience || e.intendedAudience.length === 0)) {
             issues.push({

package/dist/commands/completion.command.d.ts

@@ -0,0 +1,10 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk completion <bash|zsh|fish>` — print a sourcable completion
+ * script. The list of verbs is generated from the registered
+ * `COMMAND_CATALOG` so completion can't drift from the runtime
+ * surface. Subverbs for the high-traffic groups (graph, arch,
+ * impact, gate, context, search-structural) are hand-curated.
+ */
+export declare const completionCommand: ICommandHandler;
+//# sourceMappingURL=completion.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"completion.command.d.ts","sourceRoot":"","sources":["../../src/commands/completion.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,eAqC/B,CAAC"}

package/dist/commands/completion.command.js

@@ -0,0 +1,121 @@
+import { flagBool, flagString, } from "../command-registry.js";
+import { asJson } from "../output/format-output.js";
+import { COMMAND_CATALOG } from "./command-catalog.js";
+/**
+ * `shrk completion <bash|zsh|fish>` — print a sourcable completion
+ * script. The list of verbs is generated from the registered
+ * `COMMAND_CATALOG` so completion can't drift from the runtime
+ * surface. Subverbs for the high-traffic groups (graph, arch,
+ * impact, gate, context, search-structural) are hand-curated.
+ */
+export const completionCommand = {
+    name: 'completion',
+    description: 'Print a sourcable shell-completion script for the `shrk` CLI. Pipe into your shell rc: `shrk completion bash >> ~/.bashrc`.',
+    usage: 'shrk completion <bash|zsh|fish> [--json]',
+    async run(args) {
+        const shell = (args.positional[0] ?? flagString(args, 'shell') ?? 'bash').toLowerCase();
+        const wantJson = flagBool(args, 'json');
+        const verbs = collectTopLevelVerbs();
+        if (wantJson) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.cli-completion/v1',
+                shell,
+                verbs,
+                subverbs: SUBVERBS,
+            }) + '\n');
+            return 0;
+        }
+        switch (shell) {
+            case 'bash':
+                process.stdout.write(renderBash(verbs));
+                return 0;
+            case 'zsh':
+                process.stdout.write(renderZsh(verbs));
+                return 0;
+            case 'fish':
+                process.stdout.write(renderFish(verbs));
+                return 0;
+            default:
+                process.stderr.write(`Unknown shell "${shell}". Use bash | zsh | fish.\n`);
+                return 2;
+        }
+    },
+};
+/**
+ * Subverbs the high-traffic verbs accept. Hand-curated because the
+ * runtime catalog represents them as a single CLI surface; we don't
+ * want to parse the dispatch chain at completion time.
+ */
+const SUBVERBS = Object.freeze({
+    graph: ['index', 'status', 'search', 'context', 'impact', 'callers', 'cycles', 'unresolved', 'deps', 'why', 'export'],
+    arch: ['check', 'baseline'],
+    impact: ['tests', 'graph', 'baseline'],
+    gate: ['scaffold-ci', 'scaffold-hook'],
+    context: ['build', 'refresh', 'status', 'benchmark'],
+    'search-structural': ['registry'],
+    doctor: ['suppress', 'suppressions', 'acknowledge', 'acknowledgements', 'watch'],
+});
+function collectTopLevelVerbs() {
+    const set = new Set();
+    for (const e of COMMAND_CATALOG) {
+        // `command` may carry an argument hint like 'fix preview' — keep
+        // only the first token so completion works at the top level.
+        const head = e.command.split(/\s+/)[0];
+        if (head.length > 0)
+            set.add(head);
+    }
+    return [...set].sort();
+}
+function renderBash(verbs) {
+    const verbList = verbs.join(' ');
+    const subverbCases = Object.entries(SUBVERBS)
+        .map(([verb, subs]) => `      ${verb}) COMPREPLY=($(compgen -W "${subs.join(' ')}" -- "$cur")); return 0;;`)
+        .join('\n');
+    return `# shrk bash completion. Source from ~/.bashrc:
+#   eval "$(shrk completion bash)"
+_shrk_complete() {
+  local cur prev words cword
+  _init_completion || return
+  if [ "$cword" -eq 1 ]; then
+    COMPREPLY=($(compgen -W "${verbList}" -- "$cur"))
+    return 0
+  fi
+  case "\${words[1]}" in
+${subverbCases}
+  esac
+  COMPREPLY=()
+}
+complete -F _shrk_complete shrk
+`;
+}
+function renderZsh(verbs) {
+    const verbList = verbs.join(' ');
+    const subverbCases = Object.entries(SUBVERBS)
+        .map(([verb, subs]) => `    ${verb}) compadd -- ${subs.join(' ')};;`)
+        .join('\n');
+    return `# shrk zsh completion. Source from ~/.zshrc:
+#   eval "$(shrk completion zsh)"
+_shrk() {
+  if [[ \${#words} -eq 2 ]]; then
+    compadd -- ${verbList}
+    return
+  fi
+  case "\${words[2]}" in
+${subverbCases}
+  esac
+}
+compdef _shrk shrk
+`;
+}
+function renderFish(verbs) {
+    const lines = [
+        '# shrk fish completion. Source from ~/.config/fish/completions/shrk.fish:',
+        '#   shrk completion fish > ~/.config/fish/completions/shrk.fish',
+        'complete -e -c shrk',
+        `complete -c shrk -n '__fish_use_subcommand' -a '${verbs.join(' ')}'`,
+    ];
+    for (const [verb, subs] of Object.entries(SUBVERBS)) {
+        lines.push(`complete -c shrk -n '__fish_seen_subcommand_from ${verb}' -a '${subs.join(' ')}'`);
+    }
+    return lines.join('\n') + '\n';
+}

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

@@ -0,0 +1,8 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const compressCommand: ICommandHandler;
+/**
+ * `shrk expand` — the retrieve half of CCR. Print the full original that
+ * `shrk compress` cached for a `<<ccr:KEY>>` key.
+ */
+export declare const expandCommand: ICommandHandler;
+//# sourceMappingURL=compress.command.d.ts.map

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

@@ -0,0 +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;AAgChC,eAAO,MAAM,eAAe,EAAE,eA8F7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}

package/dist/commands/compress.command.js

@@ -0,0 +1,147 @@
+import { readFileSync } from 'node:fs';
+import { Buffer } from 'node:buffer';
+import { compressContent, ECompressionStrategy, EContentType, } from '@shrkcrft/compress';
+import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
+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 === '-';
+    if (useStdin)
+        return readFileSync(0, 'utf8');
+    return readFileSync(positional, 'utf8');
+}
+/**
+ * `shrk compress` — deterministically compress a blob (file or stdin) before
+ * it re-enters an agent prompt. Same information, fewer tokens. Lossy passes
+ * cache the original under `.sharkcraft/ccr/` so `shrk expand <key>` can get
+ * it back. The compressed text goes to stdout (pipeable); the savings summary
+ * goes to stderr unless `--json` is set.
+ */
+const COMPRESS_BOOLEAN_FLAGS = new Set([
+    'stdin',
+    'lossless',
+    'no-cache',
+    'json',
+]);
+export const compressCommand = {
+    name: 'compress',
+    description: 'Compress a blob (file or stdin) deterministically to cut tokens — JSON→table, logs/search/diffs→signal. Reversible via `shrk expand`.',
+    usage: 'shrk [--cwd <dir>] compress [<file>|-] [--stdin] [--type <content-type>] [--query <text>] [--max <n>] [--lossless] [--no-cache] [--json]',
+    booleanFlags: COMPRESS_BOOLEAN_FLAGS,
+    run(args) {
+        const cwd = resolveCwd(args);
+        let content;
+        try {
+            content = readInput(args);
+        }
+        catch (e) {
+            process.stderr.write(`compress: cannot read input — ${e.message}\n`);
+            return 1;
+        }
+        if (content.length === 0) {
+            process.stderr.write('compress: empty input.\n');
+            return 1;
+        }
+        const opts = {};
+        if (!flagBool(args, 'no-cache'))
+            opts.store = openCcrStore(cwd);
+        const query = flagString(args, 'query');
+        if (query)
+            opts.query = query;
+        const max = flagNumber(args, 'max');
+        if (max !== undefined && max > 0)
+            opts.maxItems = Math.floor(max);
+        if (flagBool(args, 'lossless'))
+            opts.lossless = true;
+        const type = flagString(args, 'type');
+        if (type && CONTENT_TYPES.has(type))
+            opts.contentType = type;
+        const result = compressContent(content, opts);
+        const pct = Math.round(result.savings.ratio * 100);
+        // A lossy result with no cached original (i.e. --no-cache) can't be undone
+        // by `shrk expand`. Warn so the dropped detail isn't lost silently.
+        if (result.lossy && !result.ccrKey) {
+            process.stderr.write('warning: compressed lossily but the original was NOT cached (--no-cache) — ' +
+                'detail is unrecoverable; omit --no-cache to keep it retrievable via `shrk expand`.\n');
+        }
+        const queryApplied = query !== undefined && query.length > 0;
+        if (flagBool(args, 'json')) {
+            // tokens are a deterministic ESTIMATE (chars/divisor heuristic), not a
+            // real BPE count — flagged so callers don't treat savedRatio as exact.
+            const base = {
+                contentType: result.contentType,
+                strategy: result.strategy,
+                lossy: result.lossy,
+                tokensBefore: result.savings.before,
+                tokensAfter: result.savings.after,
+                tokensSaved: result.savings.saved,
+                savedRatio: result.savings.ratio,
+                tokensAreEstimated: true,
+                queryApplied,
+                ccrKey: result.ccrKey ?? null,
+                note: result.note,
+            };
+            // Net-loss guard: on a passthrough/no-win blob the engine returns the
+            // VERBATIM original as `compressed`. Echoing it back inside the JSON
+            // envelope (plus scaffold) costs more tokens than the input. Signal
+            // passthrough and omit the duplicated content — the caller still has it.
+            const noWin = result.strategy === ECompressionStrategy.Passthrough || result.savings.saved <= 0;
+            const payload = noWin
+                ? { ...base, passthrough: true, inputBytes: Buffer.byteLength(content, 'utf8') }
+                : { ...base, compressed: result.compressed };
+            process.stdout.write(asJson(payload) + '\n');
+            return 0;
+        }
+        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;
+    },
+};
+/**
+ * `shrk expand` — the retrieve half of CCR. Print the full original that
+ * `shrk compress` cached for a `<<ccr:KEY>>` key.
+ */
+export const expandCommand = {
+    name: 'expand',
+    description: 'Retrieve the full original a `shrk compress` run cached, by its `<<ccr:KEY>>` key.',
+    usage: 'shrk [--cwd <dir>] expand <key> [--json]',
+    run(args) {
+        const cwd = resolveCwd(args);
+        const key = (args.positional[0] ?? '').trim();
+        if (key.length === 0) {
+            process.stderr.write('expand: a CCR key is required (e.g. `shrk expand a1b2c3d4e5f60718`).\n');
+            return 1;
+        }
+        const store = openCcrStore(cwd);
+        const entry = store.get(key);
+        if (!entry) {
+            process.stderr.write(`expand: no cached original for key "${key}" under ${ccrDir(cwd)}.\n`);
+            return 1;
+        }
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson({ key: entry.key, bytes: entry.bytes, content: entry.content }) + '\n');
+            return 0;
+        }
+        // Write the cached original VERBATIM — appending a newline broke byte-for-byte
+        // round-trip (`compress … ; expand` must reproduce the input exactly).
+        process.stdout.write(entry.content);
+        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,eAmFrC,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/sandbox/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 ?? []),
@@ -118,11 +181,11 @@ export const constructsTraceCommand = {
             ? {
                 related: relatedAll,
                 tags: c.tags ?? [],
-                registryHints: c.tags?.filter((t) => /(registry|composer|defaults|sandbox|demo|barrel)/i.test(t)) ?? [],
+                registryHints: c.tags?.filter((t) => /(registry|barrel)/i.test(t)) ?? [],
             }
             : 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)
@@ -175,28 +258,11 @@ export const constructsImpactCommand = {
         }
         const trace = traceConstruct(c);
         /**
-         * Registry touch-points are inferred from the active plugin
-         * lifecycle profile (key-table + barrels). The engine no longer
-         * hardcodes project-specific paths.
+         * Registry touch-points are not inferred — pack-contributed
+         * touch-point hints can be added in the future via the convention
+         * registry.
          */
         const registryTouchPoints = [];
-        try {
-            const { listPluginLifecycleProfiles } = await import('@shrkcrft/inspector');
-            const profiles = await listPluginLifecycleProfiles(inspection);
-            for (const entry of profiles) {
-                const p = entry.profile;
-                if (c.tags?.some((t) => /plugin-key|key-table/i.test(t)) && p.keyTable) {
-                    registryTouchPoints.push(p.keyTable.path);
-                }
-                if (c.tags?.some((t) => /barrel|public-api/i.test(t)) && p.barrels) {
-                    for (const b of p.barrels)
-                        registryTouchPoints.push(b.path);
-                }
-            }
-        }
-        catch {
-            // Best-effort enrichment; absence of profiles just means no touch-points.
-        }
         const verificationCommands = [
             'shrk check boundaries --changed-only',
             'shrk doctor',

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

@@ -1 +1 @@
-{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AASA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,cAAc,EAAE,eA6H5B,CAAC"}
+{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,cAAc,EAAE,eAyI5B,CAAC"}

package/dist/commands/context.command.js

@@ -1,12 +1,38 @@
 import { entrypointBanner, inspectSharkcraft } from '@shrkcrft/inspector';
 import { buildContext } from '@shrkcrft/context';
+import { loadIntentBenchmark, runIntentBenchmark, STARTER_INTENT_BENCHMARK, writeBenchmarkRun, } from '@shrkcrft/context-planner';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
 import { buildUniversalSearch, explainTaskRouting, recommendCommands, renderOverviewText, buildProjectOverview, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+/**
+ * Minimal JSON shape for agent / skill consumption — the context-side mirror
+ * of `shrk task --compact`. Drops the heavy `body` and `request` echo and
+ * carries the section map + structured action hints (so the agent reads
+ * forbiddenActions / verificationCommands / preferredFlow directly instead of
+ * regexing the markdown body). The schema marker is distinct so consumers can
+ * tell the shapes apart at a glance.
+ */
+function minimalContext(task, result, commands) {
+    return {
+        schema: 'sharkcraft.context/v1-compact',
+        task,
+        tokens: { used: result.totalTokens, max: result.maxTokens },
+        sections: result.sections.map((s) => ({
+            title: s.title,
+            tokens: s.tokens,
+            ...(s.truncated ? { truncated: true } : {}),
+        })),
+        omittedSections: result.omittedSections,
+        actionHints: result.actionHints,
+        topCommands: (commands?.recommendations ?? []).slice(0, 5).map((r) => r.command),
+    };
+}
 export const contextCommand = {
     name: 'context',
     description: 'Build relevant AI-ready context for a task (token-budgeted). Subcommands: build / refresh / status.',
-    usage: 'shrk context [build|refresh|status] --task "<task>" [--max-tokens 3000] [--framework x] [--area y] [--json]',
+    usage: 'shrk context [build|refresh|status] --task "<task>" [--max-tokens 3000] [--framework x] [--area y] [--json] [--compact] [--full]',
     async run(args) {
         // Dispatch subcommands (build / refresh / status) based on first positional.
         const sub = args.positional[0];
@@ -19,6 +45,10 @@ export const contextCommand = {
                 return contextRefreshCommand.run(sliced);
             return contextStatusCommand.run(sliced);
         }
+        if (sub === 'benchmark') {
+            const sliced = { ...args, positional: args.positional.slice(1) };
+            return runContextBenchmark(sliced);
+        }
         const task = flagString(args, 'task');
         if (!task) {
             process.stderr.write('Missing --task\n');
@@ -72,6 +102,14 @@ export const contextCommand = {
             // ignore — fall back to legacy context only.
         }
         if (flagBool(args, 'json') || flagBool(args, 'machine-json')) {
+            // `--compact` emits a minimal, structured agent shape (no long body /
+            // request echo) — the context-side mirror of `shrk task --compact`.
+            // Carries the load-bearing action hints as structured data so the agent
+            // never has to parse the markdown body. Full shape stays the default.
+            if (flagBool(args, 'compact')) {
+                process.stdout.write(asJson(minimalContext(task, result, commandRecommendations)) + '\n');
+                return 0;
+            }
             process.stdout.write(asJson({
                 ...result,
                 commands: commandRecommendations,
@@ -118,3 +156,85 @@ export const contextCommand = {
         return 0;
     },
 };
+async function runContextBenchmark(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    // `shrk context benchmark seed` writes a starter fixture to
+    // sharkcraft/intent-benchmark.json. Useful first step for adopting
+    // the surface — fixture is opinionated but small and easy to prune.
+    if (args.positional[0] === 'seed') {
+        return runContextBenchmarkSeed(cwd, args);
+    }
+    const noPersist = flagBool(args, 'no-persist');
+    const benchmark = loadIntentBenchmark(cwd);
+    if (!benchmark) {
+        const msg = `No benchmark at sharkcraft/intent-benchmark.json. Create one with schema "sharkcraft.intent-benchmark/v1" and a "cases" array of { task, expected } entries.\n`;
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: 'benchmark-missing' }) + '\n');
+            return 1;
+        }
+        process.stderr.write(msg);
+        return 1;
+    }
+    const run = runIntentBenchmark(benchmark);
+    if (!noPersist) {
+        try {
+            writeBenchmarkRun(cwd, run);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    if (wantJson) {
+        process.stdout.write(asJson(run) + '\n');
+        return run.failed === 0 ? 0 : 1;
+    }
+    process.stdout.write(header('Intent classifier benchmark'));
+    process.stdout.write(`  total       ${run.total}\n`);
+    process.stdout.write(`  passed      ${run.passed}\n`);
+    process.stdout.write(`  failed      ${run.failed}\n`);
+    process.stdout.write(`  accuracy    ${Math.round(run.accuracy * 1000) / 10}%\n`);
+    const failures = run.cases.filter((c) => !c.passed);
+    if (failures.length > 0) {
+        process.stdout.write('\nFailures:\n');
+        for (const c of failures.slice(0, 20)) {
+            process.stdout.write(`  ✗ task="${truncateTask(c.task)}"  expected=${c.expected}  actual=${c.actual}\n`);
+        }
+        if (failures.length > 20) {
+            process.stdout.write(`  … (${failures.length - 20} more)\n`);
+        }
+    }
+    return run.failed === 0 ? 0 : 1;
+}
+function truncateTask(s) {
+    if (s.length <= 60)
+        return s;
+    return s.slice(0, 57) + '…';
+}
+function runContextBenchmarkSeed(cwd, args) {
+    const wantJson = flagBool(args, 'json');
+    const force = flagBool(args, 'force');
+    const target = nodePath.join(cwd, 'sharkcraft', 'intent-benchmark.json');
+    if (existsSync(target) && !force) {
+        const msg = `${target} already exists. Use --force to overwrite.\n`;
+        if (wantJson) {
+            process.stdout.write(asJson({ ok: false, error: 'exists', path: target }) + '\n');
+            return 1;
+        }
+        process.stderr.write(msg);
+        return 1;
+    }
+    mkdirSync(nodePath.dirname(target), { recursive: true });
+    writeFileSync(target, JSON.stringify(STARTER_INTENT_BENCHMARK, null, 2), 'utf8');
+    if (wantJson) {
+        process.stdout.write(asJson({
+            ok: true,
+            wrote: target,
+            cases: STARTER_INTENT_BENCHMARK.cases.length,
+        }) + '\n');
+        return 0;
+    }
+    process.stdout.write(`Seeded ${STARTER_INTENT_BENCHMARK.cases.length} starter intent case(s) → ${target}\n`);
+    process.stdout.write('Run `shrk context benchmark` to record accuracy.\n');
+    return 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"}