@shrkcrft/cli 0.1.0-alpha.22 → 0.1.0-alpha.24

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

@@ -1,11 +1,12 @@
-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, inspectSharkcraft, renderOverviewText, } from '@shrkcrft/inspector';
+import { buildProjectOverview, buildTaskPacket, contextTuningBoostFor, inspectSharkcraft, renderOverviewText, } from '@shrkcrft/inspector';
 import { flagBool, flagList, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
 import { DeclarationKind, PLAN_CACHE_SCHEMA, PlanCache, SemanticIndex, TaskType, buildFocusedContext, classifyTask, encodeEmbedding, getDefaultSourceRoots, listIndexableFiles, parseTaskTypeOverride, pruneDeletedHits, renderFocusedContextForPrompt, } from '@shrkcrft/embeddings';
 import { SmartContextDetailedPlanSchema, SmartContextExpansionRequestSchema, } from "../schemas/json-schemas.js";
@@ -150,6 +151,42 @@ export const smartContextCommand = {
                 }
             }
             const enh = enhanced.value.enhancement;
+            // Deterministic-always contract (CLAUDE.md): when the enhancement
+            // pipeline fully degrades — every stage failed (or none ran), so the
+            // pipeline's finalOutput is just the echoed system message (preamble +
+            // "## Repository context" + the assembled deterministic seed) — fall
+            // back to the clean deterministic seed instead of leaking the raw
+            // internal prompt to stdout. This mirrors the single-shot
+            // provider-failure fallback below: clean renderSeed(seed) content,
+            // finishReason 'deterministic-fallback', no LLM/system-prompt wrapper.
+            const systemMsg = messages.find((m) => m.role === AiMessageRole.System);
+            const originalContext = (systemMsg?.content ?? '').trim();
+            const fullyDegraded = (enh.stages.length > 0 && enh.stages.every((s) => s.degraded)) ||
+                (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');
+                }
+                const fallbackEnvelope = buildEnvelope({
+                    task,
+                    seed,
+                    ai: {
+                        content: renderSeed(seed),
+                        model: 'deterministic',
+                        finishReason: 'deterministic-fallback',
+                        usage: null,
+                        providerId: 'deterministic',
+                    },
+                    mode: opts.mode,
+                });
+                if (opts.save) {
+                    const saved = saveEnvelope(cwd, fallbackEnvelope);
+                    writeSavedNotice(saved, opts.json, fallbackEnvelope);
+                    return 0;
+                }
+                writeEnvelope(fallbackEnvelope, opts.json, opts.debug);
+                return 0;
+            }
             if (!opts.json && !enh.deterministicFallback) {
                 if (enh.budgetExhausted) {
                     process.stderr.write(`[smart-context] budget reached before all ${enh.plannedPasses} passes finished — output is the best so far. Try a smaller --model or raise --budget.\n`);
@@ -179,6 +216,9 @@ export const smartContextCommand = {
             messages,
             maxTokens: opts.maxTokens,
             model: opts.model,
+            // Bound the single shot so a hung local model degrades to the
+            // deterministic seed below instead of hanging the command.
+            timeoutMs: perCallTimeoutMs(opts.budgetMs),
         });
         if (!aiResult.ok) {
             // Deterministic-always contract (CLAUDE.md): a provider failure must
@@ -293,6 +333,9 @@ export const smartContextPlanAheadCommand = {
                 messages,
                 maxTokens: opts.maxTokens,
                 model: opts.model,
+                // Bound each task's call so one hung model can't stall the queue;
+                // a timeout is reported as that task's error and the loop continues.
+                timeoutMs: perCallTimeoutMs(opts.budgetMs),
             });
             if (!aiResult.ok) {
                 results.push({ task, status: 'error', error: aiResult.error.message, slug: slug(task) });
@@ -1418,6 +1461,7 @@ async function buildSmartContextSeed(input) {
         task,
         maxTokens: options.seedTokens,
         projectOverview: overviewText,
+        boostFor: contextTuningBoostFor(inspection, task),
     });
     const graphGrounding = buildInitialGraphGrounding(cwd, task);
     const semantic = await tryLoadSemanticHits(cwd, task, 10, options);
@@ -2139,45 +2183,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.
@@ -2693,6 +2713,23 @@ function truncateLine(text, max) {
 const PER_STAGE_TIMEOUT_MS = 90_000;
 const FAST_ENHANCE_BUDGET_MS = 150_000;
 const PLUS_ENHANCE_BUDGET_MS = 360_000;
+/**
+ * Per-call wall-clock bounds for the paths that DON'T run through
+ * `runEnhancementPipeline` (single-shot brief, plan-ahead, and the two
+ * `--ai-plan` stages). Without these, `--budget` only constrained the
+ * enhancement pipeline, so a hung local model could still hang those modes.
+ *
+ *  - `SINGLE_CALL_DEFAULT_BUDGET_MS` — the cap applied when no `--budget` is
+ *    given (mirrors the fast-enhance ceiling).
+ *  - `PER_CALL_TIMEOUT_CAP_MS` — an absolute ceiling, so even a generous
+ *    `--budget` can't let a single call run unbounded.
+ */
+const SINGLE_CALL_DEFAULT_BUDGET_MS = 150_000;
+const PER_CALL_TIMEOUT_CAP_MS = 360_000;
+/** Derive a per-call timeout (ms) from the optional `--budget` (budgetMs). */
+function perCallTimeoutMs(budgetMs) {
+    return Math.min(budgetMs ?? SINGLE_CALL_DEFAULT_BUDGET_MS, PER_CALL_TIMEOUT_CAP_MS);
+}
 async function runEnhancementPipeline(input) {
     const provider = input.provider;
     const systemMsg = input.messages.find((m) => m.role === AiMessageRole.System);
@@ -2830,6 +2867,7 @@ async function callProvider(input) {
         ...(input.model ? { model: input.model } : {}),
         ...(input.responseFormat ? { responseFormat: input.responseFormat } : {}),
         ...(input.onTokenStream ? { onTokenStream: input.onTokenStream } : {}),
+        ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
     });
     if (!res.ok || !res.value)
         return { ok: false, error: res.error };
@@ -2927,10 +2965,23 @@ function writeDryRun(messages, mode, provider) {
     }
 }
 function displayProviderName(explicit) {
-    if (explicit)
-        return explicit;
+    // Mirror provider-resolver.ts `normaliseKind` so the --dry-run header names
+    // the provider that will ACTUALLY run, not a stale 'auto'. An explicit
+    // `auto` is a local-first request that AI_PROVIDER never overrides; with no
+    // --provider, AI_PROVIDER (including a hosted claude/gemini) decides what
+    // runs, so the header must say so truthfully.
+    if (explicit !== undefined) {
+        const e = explicit.trim().toLowerCase();
+        if (e === 'auto')
+            return 'auto';
+        if (e === 'claude' || e === 'gemini' || e === 'ollama' || e === 'llamacpp')
+            return e;
+    }
     const envProvider = (process.env.AI_PROVIDER ?? '').trim().toLowerCase();
-    if (envProvider === 'ollama' || envProvider === 'llamacpp') {
+    if (envProvider === 'ollama' ||
+        envProvider === 'llamacpp' ||
+        envProvider === 'claude' ||
+        envProvider === 'gemini') {
         return envProvider;
     }
     return 'auto';
@@ -3212,6 +3263,11 @@ async function buildAiPlanEnvelope(input) {
         }
         progressMarker(`preflight ok — host=${preflight.value.host} models=${preflight.value.models.length}`, input.options);
     }
+    // Split the (optional) --budget across the two stages so a hung local
+    // model can't hang the ai-plan path the way it previously could. Each
+    // call is independently bounded; a TIMEOUT surfaces as a call-failure and
+    // is handled exactly like any other provider failure below.
+    const aiPlanStageTimeoutMs = Math.min(Math.floor((input.options.budgetMs ?? SINGLE_CALL_DEFAULT_BUDGET_MS) / 2), PER_CALL_TIMEOUT_CAP_MS);
     progressMarker(`stage 1 calling ${selection.provider.id}${input.options.model ? `:${input.options.model}` : ''}…`, input.options);
     const stage1Messages = buildStage1Messages(input.seed, grounding, cacheLookup.reference);
     logPromptToStderr('stage1', stage1Messages, input.options);
@@ -3229,6 +3285,7 @@ async function buildAiPlanEnvelope(input) {
         repromptInstruction: STAGE1_REPROMPT,
         stageLabel: 'stage 1',
         options: input.options,
+        timeoutMs: aiPlanStageTimeoutMs,
     });
     let stage1Request;
     let stage1Retried = false;
@@ -3275,6 +3332,7 @@ async function buildAiPlanEnvelope(input) {
         repromptInstruction: STAGE2_REPROMPT,
         stageLabel: 'stage 2',
         options: input.options,
+        timeoutMs: aiPlanStageTimeoutMs,
     });
     const conversationTurns = [];
     if (stage1Call) {
@@ -3424,6 +3482,7 @@ async function callProviderWithRetry(input) {
         maxTokens: input.maxTokens,
         ...(input.model ? { model: input.model } : {}),
         ...(input.responseFormat ? { responseFormat: input.responseFormat } : {}),
+        ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
     });
     if (!first.ok)
         return { kind: 'call-failed', error: first.error };
@@ -3449,6 +3508,7 @@ async function callProviderWithRetry(input) {
         maxTokens: input.maxTokens,
         ...(input.model ? { model: input.model } : {}),
         ...(input.responseFormat ? { responseFormat: input.responseFormat } : {}),
+        ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
     });
     if (!second.ok) {
         return {

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

@@ -1 +1 @@
-{"version":3,"file":"spec.command.d.ts","sourceRoot":"","sources":["../../src/commands/spec.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA0CH,OAAO,EASL,gBAAgB,EAIjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AACpE,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAY1E,eAAO,MAAM,iBAAiB,EAAE,eA2K/B,CAAC;AAcF,eAAO,MAAM,iBAAiB,EAAE,eAiE/B,CAAC;AAqBF,eAAO,MAAM,eAAe,EAAE,eAmC7B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eA8B7B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eA2C7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAoE/B,CAAC;AASF,eAAO,MAAM,oBAAoB,EAAE,eAsRlC,CAAC;AAyDF,eAAO,MAAM,iBAAiB,EAAE,eAsL/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eA4B/B,CAAC;AAkBF,OAAO,EAAE,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"spec.command.d.ts","sourceRoot":"","sources":["../../src/commands/spec.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA0CH,OAAO,EAUL,gBAAgB,EAMjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AACpE,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAY1E,eAAO,MAAM,iBAAiB,EAAE,eA2K/B,CAAC;AAcF,eAAO,MAAM,iBAAiB,EAAE,eAiE/B,CAAC;AAqBF,eAAO,MAAM,eAAe,EAAE,eAmC7B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eA8B7B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eA2C7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAoE/B,CAAC;AASF,eAAO,MAAM,oBAAoB,EAAE,eAsRlC,CAAC;AAyDF,eAAO,MAAM,iBAAiB,EAAE,eAqP/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eA4B/B,CAAC;AAkBF,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/commands/spec.command.js

@@ -17,7 +17,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { appendSpecEvent, buildSavedPlan, buildSpecId, canonicalJson, deriveSpecJson, FileChangeType, generate, listSpecIds, loadSpec, OverwriteStrategy, persistSpecArtifacts, PLAN_SECRET_ENV, readSpecEvents, renderSpecMd, savePlanToFile, signPlan, specDir, specMdPath, specPlanPath, specVerificationPath, splitSpecMd, SPEC_SCHEMA_V1, SpecStatus, validateSpecStructural, verifyPlan, writeSpecJson, writeSpecMd, } from '@shrkcrft/generator';
-import { AssetProvenanceOperation, AssetProvenanceSource, buildSpecList, buildSpecReview, buildTaskPacket, inspectSharkcraft, recordProvenance, SPEC_LIST_SCHEMA, } from '@shrkcrft/inspector';
+import { AssetProvenanceOperation, AssetProvenanceSource, buildSpecList, buildSpecReview, buildTaskPacket, inspectSharkcraft, mapChecklistToEvidence, recordProvenance, SPEC_LIST_SCHEMA, } from '@shrkcrft/inspector';
 import { flagBool, flagList, flagString, resolveCwd, } from "../command-registry.js";
 import { collectChangedPaths } from "../diff/collect-changed-paths.js";
 import { asJson, header } from "../output/format-output.js";
@@ -778,8 +778,8 @@ function shortHash(text) {
 }
 export const specVerifyCommand = {
     name: 'verify',
-    description: 'Run the spec\'s trusted verification commands, check acceptance-criteria coverage, run diff-aware boundary + drift checks. Returns sharkcraft.spec-verification/v1.',
-    usage: 'shrk spec verify <id> [--since <ref>] [--strict] [--skip-verification-commands] [--json] [--write]',
+    description: 'Run the spec\'s trusted verification commands, check acceptance-criteria coverage, run diff-aware boundary + drift checks. Pass --coverage to map each acceptance criterion to backing changeset evidence and flag UNMET (claimed-but-zero-footprint) criteria. Returns sharkcraft.spec-verification/v1.',
+    usage: 'shrk spec verify <id> [--since <ref>] [--coverage] [--strict] [--skip-verification-commands] [--json] [--write]',
     async run(args) {
         const ref = args.positional[0];
         if (!ref) {
@@ -886,18 +886,51 @@ export const specVerifyCommand = {
                 planIntegrity = 'invalid-signature';
             }
         }
-        const acceptanceResults = spec.acceptanceCriteria.map((ac) => ({
-            id: ac.id,
-            status: ac.verifiedBy.includes('manual')
-                ? 'manual'
-                : commandFailed
-                    ? 'fail'
-                    : 'pass',
-            evidence: [],
-        }));
+        // --coverage: map each acceptance criterion to backing changeset
+        // evidence (new exported symbol / registration / route / companion
+        // file / test). UNMET = a claimed criterion with zero footprint.
+        const wantCoverage = flagBool(args, 'coverage');
+        let coverage = null;
+        if (wantCoverage) {
+            const fileContents = {};
+            if (changed.isAvailable) {
+                for (const rel of changed.changed) {
+                    const abs = nodePath.join(cwd, rel);
+                    if (existsSync(abs)) {
+                        try {
+                            fileContents[rel] = readFileSync(abs, 'utf8');
+                        }
+                        catch {
+                            fileContents[rel] = '';
+                        }
+                    }
+                }
+            }
+            coverage = mapChecklistToEvidence({
+                criteria: spec.acceptanceCriteria.map((ac) => ({ id: ac.id, text: ac.text })),
+                changedFiles: changed.changed,
+                fileContents,
+            });
+        }
+        const coverageById = new Map((coverage?.criteria ?? []).map((c) => [c.id, c]));
+        const acceptanceResults = spec.acceptanceCriteria.map((ac) => {
+            const cov = coverageById.get(ac.id);
+            return {
+                id: ac.id,
+                status: ac.verifiedBy.includes('manual')
+                    ? 'manual'
+                    : commandFailed
+                        ? 'fail'
+                        : 'pass',
+                evidence: cov?.evidence ?? [],
+                ...(wantCoverage ? { covered: cov?.covered ?? false } : {}),
+            };
+        });
         const verdict = commandFailed
             ? 'fail'
-            : scopeDrift.length > 0 || planIntegrity === 'missing-signature'
+            : scopeDrift.length > 0 ||
+                planIntegrity === 'missing-signature' ||
+                (coverage !== null && coverage.unmetCount > 0)
                 ? 'warn'
                 : 'pass';
         const report = {
@@ -911,6 +944,17 @@ export const specVerifyCommand = {
             boundaries: { since: changed.ref, violations: [] },
             scopeDrift: { outsideScope: scopeDrift },
             planIntegrity: { status: planIntegrity },
+            ...(coverage !== null
+                ? {
+                    coverage: {
+                        checked: true,
+                        total: coverage.criteria.length,
+                        covered: coverage.coveredCount,
+                        unmet: coverage.unmetCount,
+                        changesetAvailable: changed.isAvailable,
+                    },
+                }
+                : {}),
         };
         if (flagBool(args, 'write') || flagBool(args, 'apply')) {
             writeFileSync(specVerificationPath(cwd, spec.id), JSON.stringify(report, null, 2) + '\n', 'utf8');
@@ -935,6 +979,22 @@ export const specVerifyCommand = {
             }
             process.stdout.write(`  scope drift: ${scopeDrift.length}\n`);
             process.stdout.write(`  plan integrity: ${planIntegrity}\n`);
+            if (coverage !== null) {
+                process.stdout.write(`  coverage: ${coverage.coveredCount}/${coverage.criteria.length} covered, ${coverage.unmetCount} UNMET\n`);
+                if (!changed.isAvailable) {
+                    process.stdout.write('    (no changeset available — pass --since <ref> for evidence)\n');
+                }
+                for (const c of coverage.criteria) {
+                    if (c.covered) {
+                        const ev = c.evidence[0];
+                        const note = ev ? ` (${ev.kind}: ${ev.detail})` : '';
+                        process.stdout.write(`    [ok]   ${c.id}${note}\n`);
+                    }
+                    else {
+                        process.stdout.write(`    UNMET  ${c.id} — ${c.text.slice(0, 60)}\n`);
+                    }
+                }
+            }
         }
         if (verdict === 'fail')
             return 1;

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":"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"}
+{"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;AAchC,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,eA8ClC,CAAC"}

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

@@ -4,6 +4,7 @@ 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";
+import { computeMtimeFreshness } from "../status/freshness.js";
 const CONTEXT_BASE = nodePath.join('.sharkcraft', 'context');
 function slug(s) {
     return s
@@ -244,11 +245,34 @@ export const contextStatusCommand = {
         }
         const { readFileSync } = await import('node:fs');
         const body = readFileSync(file, 'utf8');
+        let status;
+        try {
+            status = JSON.parse(body);
+        }
+        catch {
+            status = {};
+        }
+        // Honest freshness: the saved context is stale once a source file changed
+        // after it was built. Adds `state` + a warn line in both shapes.
+        const fresh = computeMtimeFreshness(cwd, status.lastBuilt);
         if (flagBool(args, 'json')) {
-            process.stdout.write(body + '\n');
+            process.stdout.write(asJson({
+                ...status,
+                state: fresh.state,
+                lastBuiltAt: fresh.lastBuiltAt,
+                lastChangedAt: fresh.lastChangedAt,
+                behindMs: fresh.behindMs,
+                ...(fresh.state === 'stale' ? { nextCommand: 'shrk context refresh' } : {}),
+            }) + '\n');
             return 0;
         }
-        process.stdout.write(body + '\n');
+        process.stdout.write(header('Context status'));
+        process.stdout.write(kv('last task', status.lastTask ?? '-') + '\n');
+        process.stdout.write(kv('last built', status.lastBuilt ?? '-') + '\n');
+        process.stdout.write(kv('state', fresh.state) + '\n');
+        if (fresh.state === 'stale') {
+            process.stdout.write(`! stale — files changed since this context was built${fresh.lastChangedAt ? ` (last change ${fresh.lastChangedAt})` : ''}; re-run \`shrk context refresh\`\n`);
+        }
         return 0;
     },
 };

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

@@ -1 +1 @@
-{"version":3,"file":"test.command.d.ts","sourceRoot":"","sources":["../../src/commands/test.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6QhC,eAAO,MAAM,WAAW,EAAE,eA4BzB,CAAC"}
+{"version":3,"file":"test.command.d.ts","sourceRoot":"","sources":["../../src/commands/test.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiShC,eAAO,MAAM,WAAW,EAAE,eA4BzB,CAAC"}

package/dist/commands/test.command.js

@@ -3,6 +3,7 @@ import * as nodePath from 'node:path';
 import { buildTaskPacket, inspectSharkcraft, loadAgentContractTests, loadContextTests, runAgentContractTest, runContextTest, } from '@shrkcrft/inspector';
 import { flagBool, flagList, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { agentTestMissingExpectedHints, renderFailureHints } from "../output/failure-hints.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
 async function runContextTests(args) {
     const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
@@ -114,6 +115,22 @@ async function runAgentTests(args) {
         }
     }
     process.stdout.write(`\nSummary: ${results.length - failed.length}/${results.length} passed.\n`);
+    // Surface explain/why hints when a failure lists an expected construct the
+    // packet didn't include — that's the case the `shrk why`/`why-not` family
+    // is built to diagnose.
+    const anyMissingExpected = failed.some((r) => (r.missingTemplates ?? []).length > 0 ||
+        (r.missingRules ?? []).length > 0 ||
+        (r.missingForbiddenActions ?? []).length > 0 ||
+        (r.missingVerificationCommands ?? []).length > 0 ||
+        (r.missingHelpers ?? []).length > 0 ||
+        (r.missingPlaybooks ?? []).length > 0 ||
+        (r.missingPolicies ?? []).length > 0 ||
+        (r.missingConstructs ?? []).length > 0 ||
+        (r.missingCommands ?? []).length > 0 ||
+        (r.missingKnowledge ?? []).length > 0);
+    if (anyMissingExpected) {
+        process.stdout.write(renderFailureHints(agentTestMissingExpectedHints()));
+    }
     return failed.length > 0 ? 1 : 0;
 }
 async function generateContextTest(args) {

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,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,YAAY,EAAE,eAsG1B,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 { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
-import { asJson, header } from "../output/format-output.js";
+import { traceLiteral, TraceRole, } from '@shrkcrft/boundaries';
+import { flagBool, flagList, flagNumber, flagString, resolveCwd, } from "../command-registry.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) {
@@ -58,10 +128,23 @@ export const traceCommand = {
             process.stderr.write('Usage: shrk trace <query> | shrk trace --symbol <Name>\n');
             return 2;
         }
+        // `--kind` restricts the result set to specific match kinds — the engine
+        // (resolveQuery) filters by them. Validate up front so an unknown kind
+        // fails fast with the valid list, instead of being silently ignored (which
+        // returned a wrong-kind best match, e.g. a knowledge hit for
+        // `--kind template`).
+        const kinds = flagList(args, 'kind');
+        const validKinds = new Set(Object.values(QueryMatchKind));
+        const unknownKind = kinds.find((k) => !validKinds.has(k));
+        if (unknownKind) {
+            process.stderr.write(`trace: unknown --kind "${unknownKind}". Valid kinds: ${[...validKinds].sort().join(', ')}.\n`);
+            return 2;
+        }
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         const limit = flagNumber(args, 'limit');
         const resolution = resolveQuery(inspection, query, {
+            ...(kinds.length > 0 ? { kinds: kinds } : {}),
             ...(typeof limit === 'number' ? { limit } : {}),
         });
         if (flagBool(args, 'json')) {

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"}