@shrkcrft/cli 0.1.0-alpha.23 → 0.1.0-alpha.25

package/dist/commands/reuse.command.js

@@ -20,20 +20,44 @@ function tokenize(s) {
 function scorePrimitive(p, tokens) {
     // Substring match (so intent "debounce" matches symbol `useDebounce`); the
     // 3-char minimum above keeps it from over-matching on tiny fragments.
+    const symbolLower = p.symbol.toLowerCase();
     const hay = [p.symbol, ...(p.roles ?? []), ...(p.keywords ?? []), p.description ?? '']
         .join(' ')
         .toLowerCase();
     let s = 0;
-    for (const t of tokens)
-        if (hay.includes(t))
+    const matched = [];
+    let symbolHit = false;
+    for (const t of tokens) {
+        if (hay.includes(t)) {
             s += 1;
+            matched.push(t);
+            if (symbolLower.includes(t))
+                symbolHit = true;
+        }
+    }
     // A role the intent mentions is a strong signal; re-weight role hits.
     for (const role of p.roles ?? []) {
         const rl = role.toLowerCase();
         if (rl.length >= 3 && tokens.some((t) => rl.includes(t)))
             s += 0.5;
     }
-    return s;
+    return { score: s, matched, symbolHit };
+}
+/**
+ * Confidence floor: a keyword collision is not a match. A hit is only "confident"
+ * when it matched the symbol name itself, OR matched ≥2 distinct query tokens, OR
+ * the query was a single token and that token hit. A single generic keyword hit on
+ * a multi-token intent (the "nearest collision on an unrelated entry" failure mode)
+ * is a weak match — surfaced as a did-you-mean, never as a confident answer.
+ */
+function isConfidentMatch(detail, queryTokenCount) {
+    if (detail.matched.length === 0)
+        return false;
+    if (detail.symbolHit)
+        return true;
+    if (detail.matched.length >= 2)
+        return true;
+    return queryTokenCount <= 1;
 }
 const INDEX_RE = /(^|\/)index\.[cm]?[jt]sx?$/;
 export const reuseCommand = {
@@ -82,14 +106,17 @@ export const reuseCommand = {
             return 0;
         }
         const tokens = tokenize(intent);
-        const ranked = primitives
-            .map((p) => ({ p, score: scorePrimitive(p, tokens) }))
-            .filter((x) => x.score > 0)
-            .sort((a, b) => b.score - a.score || a.p.symbol.localeCompare(b.p.symbol))
-            .slice(0, Math.max(1, limit));
+        const confidenceOf = (matched) => tokens.length === 0 ? 0 : matched / tokens.length;
+        const scored = primitives
+            .map((p) => ({ p, detail: scorePrimitive(p, tokens) }))
+            .filter((x) => x.detail.score > 0)
+            .sort((a, b) => b.detail.score - a.detail.score || a.p.symbol.localeCompare(b.p.symbol));
+        const confident = scored.filter((x) => isConfidentMatch(x.detail, tokens.length));
+        const ranked = confident.slice(0, Math.max(1, limit));
         const store = new GraphStore(cwd);
         const api = store.exists() ? GraphQueryApi.fromStore(cwd) : null;
-        if (ranked.length === 0) {
+        // Zero keyword overlap: nothing matched at all → surface available roles.
+        if (scored.length === 0) {
             const roles = [...new Set(primitives.flatMap((p) => p.roles))].sort();
             if (wantJson) {
                 process.stdout.write(asJson({ schema: 'sharkcraft.reuse/v1', intent, results: [], availableRoles: roles, ...planeJson }) + '\n');
@@ -102,8 +129,41 @@ export const reuseCommand = {
             writePlaneNotes();
             return 0;
         }
-        const results = ranked.map(({ p, score }) => {
-            const r = { symbol: p.symbol, score, roles: p.roles, siblings: [], consumers: [] };
+        // Weak overlap only (a single generic keyword collision on an unrelated
+        // entry): below the confidence floor. A miss must look like a miss — never
+        // return the nearest collision as a confident answer. Offer did-you-mean.
+        if (ranked.length === 0) {
+            const didYouMean = scored.slice(0, 5).map((x) => ({
+                symbol: x.p.symbol,
+                score: x.detail.score,
+                confidence: confidenceOf(x.detail.matched.length),
+                matched: x.detail.matched,
+                roles: x.p.roles,
+            }));
+            if (wantJson) {
+                process.stdout.write(asJson({ schema: 'sharkcraft.reuse/v1', intent, confident: false, results: [], didYouMean, ...planeJson }) + '\n');
+                return 0;
+            }
+            process.stdout.write(header(`Reuse: "${intent}"`));
+            process.stdout.write('  No confident match — the intent only weakly overlaps existing primitives.\n' +
+                '  Did you mean (weak, verify before reusing):\n');
+            for (const s of didYouMean) {
+                process.stdout.write(`    • ${s.symbol}  (score ${s.score}, ${Math.round(s.confidence * 100)}% of intent; matched: ${s.matched.join(', ') || '—'})\n`);
+            }
+            writePlaneNotes();
+            return 0;
+        }
+        const results = ranked.map(({ p, detail }) => {
+            const score = detail.score;
+            const r = {
+                symbol: p.symbol,
+                score,
+                confidence: confidenceOf(detail.matched.length),
+                matched: detail.matched,
+                roles: p.roles,
+                siblings: [],
+                consumers: [],
+            };
             if (p.description)
                 r.description = p.description;
             if (p.importPath)
@@ -141,8 +201,9 @@ export const reuseCommand = {
                             }
                         }
                     }
-                    r.consumers = api
-                        .referenceSitesOf(sym.id)
+                    const sites = api.referenceSitesOf(sym.id);
+                    r.consumerTotal = sites.length;
+                    r.consumers = sites
                         .slice(0, 5)
                         .map((s) => ({ path: s.node.path ?? s.node.id, ...(s.line ? { line: s.line } : {}) }));
                     const alts = pool.slice(1).map((c) => c.path).filter((x) => !!x);
@@ -174,6 +235,7 @@ export const reuseCommand = {
             process.stdout.write(`\n${i}. ${r.symbol}\n`);
             if (r.description)
                 process.stdout.write(`   ${r.description}\n`);
+            process.stdout.write(`   match: score ${r.score} (${Math.round(r.confidence * 100)}% of intent; matched: ${r.matched.join(', ') || '—'})\n`);
             if (r.notFound) {
                 process.stdout.write('   ⚠ symbol not found in the code graph — verify reusePrimitives[].symbol (typo/rename?) or run `shrk graph index`\n');
             }
@@ -192,7 +254,11 @@ export const reuseCommand = {
             if (r.siblings.length > 0)
                 process.stdout.write(`   sibling exports: ${r.siblings.join(', ')}\n`);
             if (r.consumers.length > 0) {
-                process.stdout.write('   consumers to copy:\n');
+                const total = r.consumerTotal ?? r.consumers.length;
+                const label = total > r.consumers.length
+                    ? `   consumers to copy (${total} total, showing ${r.consumers.length}):\n`
+                    : `   consumers to copy (${total} total):\n`;
+                process.stdout.write(label);
                 for (const c of r.consumers)
                     process.stdout.write(`     - ${c.path}${c.line ? ':' + c.line : ''}\n`);
             }

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

@@ -1 +1 @@
-{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AA0BA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAmFhC,eAAO,MAAM,mBAAmB,EAAE,eAmQjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAsF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAmH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAoH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAyPF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAuHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC;AAqJF,UAAU,eAAe;IACvB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAWzF"}
+{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AA2BA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAmFhC,eAAO,MAAM,mBAAmB,EAAE,eAiQjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAsF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAmH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAoH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAyPF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAuHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC;AAqJF,UAAU,eAAe;IACvB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAWzF"}

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

@@ -1,9 +1,10 @@
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import * as os from 'node:os';
 import { AiMessageRole, buildPromptMessages, EnhancementPipeline, EnhancementStageKind, OllamaProvider, buildDefaultEnhancementStages, buildFastEnhancementStages, selectAiProvider, } from '@shrkcrft/ai';
 import { buildContext } from '@shrkcrft/context';
+import { runGitLines } from '@shrkcrft/shared';
 import { EdgeKind, GraphQueryApi, GraphStore, NodeKind } from '@shrkcrft/graph';
 import { buildProjectOverview, buildTaskPacket, contextTuningBoostFor, inspectSharkcraft, renderOverviewText, } from '@shrkcrft/inspector';
 import { flagBool, flagList, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
@@ -51,11 +52,13 @@ export const smartContextCommand = {
     name: 'smart-context',
     booleanFlags: SMART_CONTEXT_BOOLEAN_FLAGS,
     description: 'Build deterministic context and ask an AI provider to synthesise an enriched brief (default), structured plan (--plan), or two-stage development plan (--ai-plan).',
-    usage: 'shrk smart-context "<task>" [--plus] [--budget <seconds>] [--plan] [--ai-plan] [--save] [--provider auto|ollama|llamacpp] [--enhance|--no-enhance] [--enhance-passes N] [--instructions <path>] [--no-instructions] [--model <id>] [--max-tokens N] [--stage1-max-tokens N] [--seed-tokens N] [--expansion-tokens N] [--expansion-limit N] [--log-prompt] [--save-conversation[=<path>]] [--dry-run] [--debug] [--json]',
+    usage: 'shrk smart-context "<task>" | --task "<task>" [--plus] [--budget <seconds>] [--plan] [--ai-plan] [--save] [--provider auto|ollama|llamacpp] [--enhance|--no-enhance] [--enhance-passes N] [--instructions <path>] [--no-instructions] [--model <id>] [--max-tokens N] [--stage1-max-tokens N] [--seed-tokens N] [--expansion-tokens N] [--expansion-limit N] [--log-prompt] [--save-conversation[=<path>]] [--dry-run] [--debug] [--json]',
     async run(args) {
-        const task = args.positional.join(' ').trim();
+        // Accept the documented `--task` form as well as the positional form, so the
+        // CLI surface matches the docs (which advertise `--task` broadly).
+        const task = (args.positional.join(' ').trim() || flagString(args, 'task') || '').trim();
         if (!task) {
-            process.stderr.write('Usage: shrk smart-context "<task>" [--plan] [--ai-plan] [--save]\n');
+            process.stderr.write('Usage: shrk smart-context "<task>" [--task "<task>"] [--plan] [--ai-plan] [--save]\n');
             return 2;
         }
         // Isolate the LLM / native-runtime work in a child process. On macOS the
@@ -164,7 +167,7 @@ export const smartContextCommand = {
                 (originalContext.length > 0 && enhanced.value.content.trim() === originalContext);
             if (fullyDegraded) {
                 if (!opts.json) {
-                    process.stderr.write('[smart-context] enhancement fully degraded — returning deterministic context only.\n');
+                    process.stderr.write(degradedRetrievalBanner(seed, 'enhancement fully degraded') + '\n');
                 }
                 const fallbackEnvelope = buildEnvelope({
                     task,
@@ -225,7 +228,7 @@ export const smartContextCommand = {
             // exit 1. The agent that asked for fast grounding still gets usable
             // rules / paths / templates / candidate files. The error is advisory on
             // stderr (never stdout, so --json stays valid).
-            process.stderr.write('[smart-context] provider unavailable — returning deterministic context only.\n');
+            process.stderr.write(degradedRetrievalBanner(seed, 'provider unavailable') + '\n');
             const fallbackEnvelope = buildEnvelope({
                 task,
                 seed,
@@ -1451,6 +1454,19 @@ export function renderIndexFreshnessWarning(f) {
         `(${f.stale} changed, ${f.missing} deleted, ${f.untracked} new).${pruned} ` +
         'Verify the file suggestions above before editing — run `shrk smart-context --refresh` to rebuild.');
 }
+/**
+ * Loud one-liner for the degraded / provider-unavailable path. The returned
+ * content is the deterministic seed (rules/paths/templates/candidate files), NOT
+ * task-scoped semantic retrieval — so say so, and how far the index is behind,
+ * so a caller never trusts a stale generic dump as if it were curated retrieval.
+ */
+function degradedRetrievalBanner(seed, cause) {
+    const behind = seed.indexFreshness?.behind ?? 0;
+    const behindClause = behind > 0 ? `, semantic index ${behind} file(s) behind the working tree` : '';
+    return (`[smart-context] semantic retrieval unavailable (${cause})${behindClause} — ` +
+        'falling back to the deterministic seed (rules/paths/templates/candidate files), NOT task-scoped retrieval. ' +
+        'Run `shrk smart-context --refresh` to rebuild the index.');
+}
 async function buildSmartContextSeed(input) {
     const { cwd, task, inspection, options } = input;
     const overview = buildProjectOverview(inspection.workspace, inspection.config?.projectName);
@@ -2182,45 +2198,21 @@ function isSemanticAutomationDisabled() {
  * ripples through. Empty array on git failure or no-graph.
  */
 function collectChangedPathsWithNeighbors(cwd, gitRef) {
-    // Use `node:child_process` spawnSync (works under both Bun and Node)
-    // instead of `Bun.spawnSync` so the CLI runs cleanly on a pure-Node
-    // runtime after `npm i -g @shrkcrft/cli`. The compat-node preflight
-    // gate flags `Bun.*` direct usages as publish blockers.
-    let changed;
-    try {
-        const out = spawnSync('git', ['-C', cwd, 'diff', '--name-only', `${gitRef}...HEAD`], {
-            encoding: 'utf8',
-        });
-        if (out.status !== 0)
-            return [];
-        changed = (out.stdout ?? '')
-            .split('\n')
-            .map((s) => s.trim())
-            .filter((s) => s.length > 0);
-    }
-    catch {
-        return [];
-    }
-    if (changed.length === 0)
+    // `runGitLines` is shell-free + high-maxBuffer, so a large changeset can't
+    // ENOBUFS-crash the feedback bundle. (It also keeps the CLI on
+    // `node:child_process` rather than `Bun.*`, which the compat-node preflight
+    // gate flags as a publish blocker.)
+    const committed = runGitLines(cwd, ['diff', '--name-only', `${gitRef}...HEAD`]);
+    if (!committed.ok || committed.lines.length === 0)
         return [];
+    const changed = [...committed.lines];
     // Also include uncommitted changes — agent feedback should reflect
     // the *current* working tree, not just committed deltas.
-    try {
-        const out = spawnSync('git', ['-C', cwd, 'diff', '--name-only', 'HEAD'], {
-            encoding: 'utf8',
-        });
-        if (out.status === 0) {
-            const uncommitted = (out.stdout ?? '')
-                .split('\n')
-                .map((s) => s.trim())
-                .filter((s) => s.length > 0);
-            for (const p of uncommitted)
-                if (!changed.includes(p))
-                    changed.push(p);
-        }
-    }
-    catch {
-        // ignore
+    const uncommitted = runGitLines(cwd, ['diff', '--name-only', 'HEAD']);
+    if (uncommitted.ok) {
+        for (const p of uncommitted.lines)
+            if (!changed.includes(p))
+                changed.push(p);
     }
     const set = new Set(changed);
     // One-hop graph expansion if the graph is fresh.

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

@@ -1 +1 @@
-{"version":3,"file":"task.command.d.ts","sourceRoot":"","sources":["../../src/commands/task.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2DhC,eAAO,MAAM,WAAW,EAAE,eAoQzB,CAAC"}
+{"version":3,"file":"task.command.d.ts","sourceRoot":"","sources":["../../src/commands/task.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkEhC,eAAO,MAAM,WAAW,EAAE,eAgRzB,CAAC"}

package/dist/commands/task.command.js

@@ -3,6 +3,12 @@ import { SpecStatus } from '@shrkcrft/generator';
 import { flagBool, flagNumber, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { buildTaskNextReport } from "../task-next/task-next-ranker.js";
+/**
+ * Budget for the DEFAULT full human-text packet when no explicit `--max-tokens`
+ * is set — large enough to hold every planned context section so orientation
+ * isn't silently thinner than the sibling verbs. JSON/terse callers keep 3500.
+ */
+const WIDE_TASK_BUDGET = 100_000;
 function compactTaskPacket(p) {
     return {
         task: p.task,
@@ -139,14 +145,26 @@ export const taskCommand = {
             return 2;
         }
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
-        const maxTokens = flagNumber(args, 'max-tokens') ?? 3500;
         const scope = flagList(args, 'scope');
         const explainRanking = flagBool(args, 'explain-ranking') || flagBool(args, 'json');
-        // `--full` (or `--verbose`, which already affects text rendering) opts
-        // out of the compact packet — pass it when an agent genuinely needs
-        // the full ranking + uncapped action-hint aggregates. Default is the
-        // tight packet (5 rules / 3 templates / 5 hints per field).
-        const compact = !flagBool(args, 'full') && !flagBool(args, 'verbose');
+        // Orientation renders the full packet by default now (parity with why /
+        // reuse / knowledge get / `shrk context`) so the agent's first read isn't
+        // thinner than every adjacent command. `--summary`/`--brief` (or
+        // `--commands-first`/`--actions-only`) opts back into the terse view.
+        const wantsJson = flagBool(args, 'json');
+        const terse = flagBool(args, 'summary') ||
+            flagBool(args, 'brief') ||
+            flagBool(args, 'commands-first') ||
+            flagBool(args, 'actions-only');
+        // Compact packet (5 rules / 3 templates / 5 hints per field) still backs the
+        // default JSON shape and the terse text view; the full text view is uncapped.
+        const compact = wantsJson
+            ? !flagBool(args, 'full') && !flagBool(args, 'verbose')
+            : terse;
+        // Auto-widen the context budget for the default full human view so no rich
+        // section is dropped purely to fit a tight budget; JSON/terse keep 3500.
+        const wideView = !wantsJson && !terse;
+        const maxTokens = flagNumber(args, 'max-tokens') ?? (wideView ? WIDE_TASK_BUDGET : 3500);
         const packet = buildTaskPacket(inspection, task, {
             maxTokens,
             ...(scope.length ? { scope } : {}),
@@ -185,14 +203,13 @@ export const taskCommand = {
         process.stdout.write(kv('detected profiles', packet.detectedProfiles.join(', ') || '(none)') + '\n');
         process.stdout.write(kv('context tokens', `${packet.context.totalTokens} / ${packet.context.maxTokens}`) + '\n');
         process.stdout.write(kv('total token est.', String(packet.tokenEstimate)) + '\n');
-        // Commands-first summary at the top so the agent sees the action
-        // path before the long context body. `--commands-first` collapses the
-        // output to just commands + uncertainty.
-        // Text mode defaults to commands-first; pass `--verbose` or
-        // `--full` to print the full packet. JSON output is unchanged.
+        // Commands-first summary at the top so the agent sees the action path
+        // before the long context body. The full packet then prints by default;
+        // `--commands-first`/`--actions-only`/`--summary` collapse to just the
+        // commands + uncertainty footer.
         const commandsFirst = flagBool(args, 'commands-first');
         const actionsOnly = flagBool(args, 'actions-only');
-        const verbose = flagBool(args, 'verbose') || flagBool(args, 'full');
+        const summaryOnly = flagBool(args, 'summary') || flagBool(args, 'brief');
         if (packet.recommendedCliCommands.length > 0) {
             process.stdout.write('\nTop commands (command-first):\n');
             for (const c of packet.recommendedCliCommands.slice(0, 5)) {
@@ -203,11 +220,11 @@ export const taskCommand = {
             process.stdout.write('\nSuggested generation:\n');
             process.stdout.write(`  $ ${packet.suggestedGen.dryRunCommand}\n`);
         }
-        if (commandsFirst || actionsOnly || !verbose) {
-            if (!verbose && !commandsFirst && !actionsOnly) {
-                process.stdout.write('\n(text mode is summary-only — pass --verbose for the full packet, --json for machine output.)\n');
+        if (commandsFirst || actionsOnly || summaryOnly) {
+            if (summaryOnly && !commandsFirst && !actionsOnly) {
+                process.stdout.write('\n(summary mode — omit --summary for the full packet, --json for machine output.)\n');
             }
-            // Render uncertainty and stop — caller asked for action-only output.
+            // Render uncertainty and stop — caller asked for terse output.
             process.stdout.write('\n' + renderUncertaintyText(uncertainty) + '\n');
             return 0;
         }

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

@@ -1 +1 @@
-{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,YAAY,EAAE,eAqH1B,CAAC"}
+{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6EhC,eAAO,MAAM,YAAY,EAAE,eAwH1B,CAAC"}

package/dist/commands/trace.command.js

@@ -6,16 +6,86 @@
  * shared query resolver and prints structured trace output.
  */
 import { findSymbolInProject, inspectSharkcraft, QueryMatchKind, resolveQuery, } from '@shrkcrft/inspector';
+import { traceLiteral, TraceRole, } from '@shrkcrft/boundaries';
 import { flagBool, flagList, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
-import { asJson, header } from "../output/format-output.js";
+import { asJson, header, kv } from "../output/format-output.js";
 function describeMatch(m) {
     return `${m.kind.padEnd(12)} ${m.id}${m.label && m.label !== m.id ? ` — ${m.label}` : ''} [${m.score.toFixed(0)}]`;
 }
+const LITERAL_SITE_CAP = 30;
+const TRACE_ROLE_ORDER = [
+    TraceRole.Declare,
+    TraceRole.Register,
+    TraceRole.Consume,
+    TraceRole.Reference,
+];
+function renderTraceLiteral(report, limit) {
+    process.stdout.write(header(`Trace literal: "${report.literal}"`));
+    process.stdout.write(kv('found', `${report.total} site(s) across ${report.files} file(s)`) + '\n');
+    if (report.aliases.length > 0) {
+        process.stdout.write(kv('const aliases', report.aliases.join(', ')) + '\n');
+    }
+    if (report.total === 0) {
+        process.stdout.write('\nNo occurrences of that exact string literal in scope.\n');
+        return;
+    }
+    // Mirror `shrk registry <name> where`'s `<role>  file:line` line idiom so the
+    // two surfaces read the same — `trace literal` is the same scanner + classifier
+    // without a pre-declared registry, just with two extra roles (`registered`,
+    // `reference`). The raw source line stays in `--json` (`text`); the human view
+    // is classification-first (direction), not a grep-style text dump.
+    process.stdout.write('\n');
+    for (const role of TRACE_ROLE_ORDER) {
+        const sites = report.byRole[role];
+        for (const s of sites.slice(0, limit)) {
+            const alias = s.viaAlias ? ` [via ${s.viaAlias}]` : '';
+            process.stdout.write(`  ${role.padEnd(10)} ${s.file}:${s.line}${alias}\n`);
+        }
+        if (sites.length > limit) {
+            process.stdout.write(`  ${role.padEnd(10)} … (${sites.length - limit} more — pass --json)\n`);
+        }
+    }
+}
+/**
+ * `shrk trace literal "<string>"`: trace an EXACT string literal across the
+ * codebase, classified by direction (declare → register → consume), resolving
+ * `const X = "lit"` aliases too. Generalizes `registry … where` to any
+ * cross-fence string contract (a kind slug, permission id, route key) with no
+ * pre-declared registry — the chain grep can't give (direction + role + layer).
+ */
+function runTraceLiteral(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    // `trace literal "<lit>"` → the literal is positional[1] (quoted by the user
+    // so an internal space stays one token); join the rest defensively.
+    const literal = args.positional.slice(1).join(' ');
+    if (literal === '') {
+        process.stderr.write('Usage: shrk trace literal "<string>" [--glob <g1,g2>] [--no-aliases] [--limit N] [--json]\n');
+        return 2;
+    }
+    const globs = flagList(args, 'glob');
+    const report = traceLiteral(cwd, literal, {
+        ...(globs.length > 0 ? { globs } : {}),
+        resolveAliases: !flagBool(args, 'no-aliases'),
+    });
+    if (wantJson) {
+        process.stdout.write(asJson(report) + '\n');
+        return 0;
+    }
+    const limitRaw = flagNumber(args, 'limit');
+    const limit = limitRaw !== undefined && limitRaw > 0 ? Math.floor(limitRaw) : LITERAL_SITE_CAP;
+    renderTraceLiteral(report, limit);
+    return 0;
+}
 export const traceCommand = {
     name: 'trace',
-    description: 'Fuzzy trace — accept any free-form query (file path, construct id, symbol, plugin key, helper id, template id, knowledge id, command). Read-only.',
-    usage: 'shrk trace <query> [--limit <n>] [--kind file|construct|knowledge|template|helper|playbook|policy|command] [--deep] [--json]',
+    description: 'Fuzzy trace — accept any free-form query (file path, construct id, symbol, plugin key, helper id, template id, knowledge id, command). `trace literal "<string>"` traces an exact string literal\'s declare→register→consume chain across layers (alias-resolved). Read-only.',
+    usage: 'shrk trace <query> | shrk trace literal "<string>" [--glob <g>] [--no-aliases] [--limit <n>] [--kind ...] [--deep] [--json]',
+    booleanFlags: new Set(['json', 'deep', 'no-aliases']),
     async run(args) {
+        // `trace literal "<lit>"` — cross-fence string-contract tracer (3.3).
+        if (args.positional[0] === 'literal')
+            return runTraceLiteral(args);
         // Direct symbol trace via --symbol <Name>
         const symbol = flagString(args, 'symbol');
         if (symbol) {

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

@@ -0,0 +1,12 @@
+import { type IWiringExplain } from '@shrkcrft/boundaries';
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * Render an {@link IWiringExplain} to stdout. Shared by `wiring explain`,
+ * `wiring test`, and `check wiring --explain` so all three speak the same
+ * dialect. JSON emits the full payload; text mirrors `search tuning explain`
+ * (header → loaded sets → per-site detail → the set-difference → verdict).
+ * Always returns 0 — explain is informational, the verdict is in the output.
+ */
+export declare function renderWiringExplain(report: IWiringExplain, wantJson: boolean): number;
+export declare const wiringCommand: ICommandHandler;
+//# sourceMappingURL=wiring.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wiring.command.d.ts","sourceRoot":"","sources":["../../src/commands/wiring.command.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAwB,KAAK,eAAe,EAAmB,MAAM,wBAAwB,CAAC;AAKrG;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAsDrF;AA+TD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}