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

package/dist/commands/search-structural.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-structural.command.d.ts","sourceRoot":"","sources":["../../src/commands/search-structural.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAkErC,CAAC"}
+{"version":3,"file":"search-structural.command.d.ts","sourceRoot":"","sources":["../../src/commands/search-structural.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAkErC,CAAC"}

package/dist/commands/search-structural.command.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { applyRewritePlan, PatternRegistryStore, planRewrite, runSearch, signRewritePlan, STARTER_PATTERNS, verifySignedRewritePlan, } from '@shrkcrft/structural-search';
-import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { flagBool, flagPositiveInt, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 /**
  * `shrk search structural` — declarative AST pattern matching with
@@ -49,7 +49,7 @@ export const searchStructuralCommand = {
             process.stderr.write(`Pattern parse error: ${e.message}\n`);
             return 2;
         }
-        const limit = Number(flagString(args, 'limit') ?? '200');
+        const limit = flagPositiveInt(args, 'limit', 200);
         // Rewrite path?
         const recipeInline = flagString(args, 'rewrite');
         const recipeFile = flagString(args, 'rewrite-file');

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

@@ -1 +1 @@
-{"version":3,"file":"search.command.d.ts","sourceRoot":"","sources":["../../src/commands/search.command.ts"],"names":[],"mappings":"AAgBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0BhC,eAAO,MAAM,aAAa,EAAE,eAuG3B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA+FrC,CAAC;AAwEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,eASzC,CAAC"}
+{"version":3,"file":"search.command.d.ts","sourceRoot":"","sources":["../../src/commands/search.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkChC,eAAO,MAAM,aAAa,EAAE,eAsH3B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA+FrC,CAAC;AAwEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,eASzC,CAAC"}

package/dist/commands/search.command.js

@@ -1,8 +1,15 @@
-import { buildSearchIndex, entrypointBanner, explainSearchTuning, inspectSharkcraft, loadConstructs, loadPlaybooks, loadSearchTuning, renderSearchText, renderTuningExplainHtml, renderTuningExplainMarkdown, searchIndex, SearchKind, SearchSource, } from '@shrkcrft/inspector';
+import { buildSearchIndex, entrypointBanner, explainSearchTuning, inspectSharkcraft, loadConstructs, loadPlaybooks, loadSearchTuning, renderSearchText, renderTuningExplainHtml, renderTuningExplainMarkdown, searchIndex, SearchKind, SearchResultKind, SearchSource, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson } from "../output/format-output.js";
 const VALID_KINDS = new Set(Object.values(SearchKind));
 const VALID_SOURCES = new Set(Object.values(SearchSource));
+// Universal-search (v2) filter vocabularies. `--kind` is one of the
+// `SearchResultKind` enum values; `--source` is the local/pack origin the
+// engine actually filters hits by (`makeHit` only ever emits these two). Both
+// are validated up front so a typo'd value rejects loudly instead of silently
+// filtering every hit out and returning an empty result with exit 0.
+const VALID_RESULT_KINDS = Object.values(SearchResultKind);
+const VALID_RESULT_SOURCES = ['local', 'pack'];
 function parseKinds(args) {
     const list = flagList(args, 'type').concat(flagList(args, 'kind'));
     if (list.length === 0)
@@ -48,6 +55,17 @@ export const searchCommand = {
             const { buildUniversalSearch, renderUniversalSearchText, renderUniversalSearchMarkdown, } = await import('@shrkcrft/inspector');
             const kindFilter = flagString(args, 'kind');
             const sourceFilter = flagString(args, 'source');
+            // Validate the filter vocabularies BEFORE building opts — universal-search
+            // silently drops every non-matching hit, so an unknown `--kind`/`--source`
+            // would otherwise return an empty result with exit 0.
+            if (kindFilter && !VALID_RESULT_KINDS.includes(kindFilter)) {
+                process.stderr.write(`Unknown --kind ${kindFilter}. Valid: ${VALID_RESULT_KINDS.join(', ')}\n`);
+                return 2;
+            }
+            if (sourceFilter && !VALID_RESULT_SOURCES.includes(sourceFilter)) {
+                process.stderr.write(`Unknown --source ${sourceFilter}. Valid: ${VALID_RESULT_SOURCES.join(', ')}\n`);
+                return 2;
+            }
             const limit = flagNumber(args, 'limit');
             const opts = {};
             if (kindFilter)

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

@@ -1 +1 @@
-{"version":3,"file":"simulate.command.d.ts","sourceRoot":"","sources":["../../src/commands/simulate.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,eAAe,EAAE,eAmD7B,CAAC"}
+{"version":3,"file":"simulate.command.d.ts","sourceRoot":"","sources":["../../src/commands/simulate.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,eAAe,EAAE,eAyD7B,CAAC"}

package/dist/commands/simulate.command.js

@@ -3,10 +3,11 @@ import * as nodePath from 'node:path';
 import { inspectSharkcraft, OrchestrationMode, renderWorkflowSimulationText, simulateWorkflow, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson } from "../output/format-output.js";
+const VALID_SIMULATION_MODES = ['conservative', 'balanced', 'aggressive'];
 export const simulateCommand = {
     name: 'simulate',
     description: 'Predict what a workflow would do without executing anything. Read-only. Optionally takes a playbook or pipeline id.',
-    usage: 'shrk simulate "<task>" [--playbook <id>] [--pipeline <id>] [--bundle] [--mode conservative|balanced|aggressive] [--json] [--output <file>]',
+    usage: 'shrk simulate "<task>" [--playbook <id>] [--pipeline <id>] [--mode conservative|balanced|aggressive] [--json] [--output <file>]',
     async run(args) {
         const task = args.positional.join(' ').trim();
         if (!task) {
@@ -18,6 +19,10 @@ export const simulateCommand = {
         const playbookId = flagString(args, 'playbook');
         const pipelineId = flagString(args, 'pipeline');
         const modeRaw = (flagString(args, 'mode') ?? '').toLowerCase();
+        // Warn on a typo'd --mode rather than silently treating it as balanced.
+        if (modeRaw && !VALID_SIMULATION_MODES.includes(modeRaw)) {
+            process.stderr.write(`Unknown --mode ${modeRaw}. Valid: ${VALID_SIMULATION_MODES.join(', ')} (defaulting to balanced).\n`);
+        }
         const mode = modeRaw === 'conservative'
             ? OrchestrationMode.Conservative
             : modeRaw === 'aggressive'

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":"AAyBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAmFhC,eAAO,MAAM,mBAAmB,EAAE,eAuNjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAmF1C,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":"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"}

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

@@ -5,7 +5,7 @@ import * as os from 'node:os';
 import { AiMessageRole, buildPromptMessages, EnhancementPipeline, EnhancementStageKind, OllamaProvider, buildDefaultEnhancementStages, buildFastEnhancementStages, selectAiProvider, } from '@shrkcrft/ai';
 import { buildContext } from '@shrkcrft/context';
 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 +150,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 +215,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 +332,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 +1460,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);
@@ -2693,6 +2736,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 +2890,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 +2988,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 +3286,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 +3308,7 @@ async function buildAiPlanEnvelope(input) {
         repromptInstruction: STAGE1_REPROMPT,
         stageLabel: 'stage 1',
         options: input.options,
+        timeoutMs: aiPlanStageTimeoutMs,
     });
     let stage1Request;
     let stage1Retried = false;
@@ -3275,6 +3355,7 @@ async function buildAiPlanEnvelope(input) {
         repromptInstruction: STAGE2_REPROMPT,
         stageLabel: 'stage 2',
         options: input.options,
+        timeoutMs: aiPlanStageTimeoutMs,
     });
     const conversationTurns = [];
     if (stage1Call) {
@@ -3424,6 +3505,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 +3531,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":"AAcA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,YAAY,EAAE,eAqH1B,CAAC"}

package/dist/commands/trace.command.js

@@ -6,7 +6,7 @@
  * 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 { flagBool, flagList, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header } 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)}]`;
@@ -58,10 +58,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/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAwX/B,wBAAgB,aAAa,IAAI,eAAe,CA4X/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAsHD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AA0X/B,wBAAgB,aAAa,IAAI,eAAe,CA8X/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BrE;AAqID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}

package/dist/main.js

@@ -32,6 +32,8 @@ import { archCommand } from "./commands/arch.command.js";
 import { frameworkCommand } from "./commands/framework.command.js";
 import { apiDiffCommand } from "./commands/api-diff.command.js";
 import { gateCommand } from "./commands/gate.command.js";
+import { policyLintCommand } from "./commands/policy-lint.command.js";
+import { reuseCommand } from "./commands/reuse.command.js";
 import { migrateCommand } from "./commands/migrate.command.js";
 import { coverageCommand } from "./commands/coverage.command.js";
 import { statsCommand } from "./commands/stats.command.js";
@@ -198,6 +200,8 @@ export function buildRegistry() {
     registry.register(frameworkCommand);
     registry.register(apiDiffCommand);
     registry.register(gateCommand);
+    registry.register(policyLintCommand);
+    registry.register(reuseCommand);
     registry.register(migrateCommand);
     registry.register(coverageCommand);
     registry.register(statsCommand);
@@ -597,7 +601,21 @@ async function runCliInner(argv) {
     // (`shrk doctor`, `shrk packs list`, `shrk pack author status`). The
     // resolver stops when it hits a flag or a token that isn't a child of the
     // current node, returning the deepest handler + the leftover tokens.
-    const { handler, matchedPath, rest: leftover, node } = registry.resolve(cleanArgv);
+    let { handler, matchedPath, rest: leftover, node } = registry.resolve(cleanArgv);
+    // A multi-word command passed as a SINGLE quoted token (`shrk "graph status"`)
+    // arrives as one argv element with internal whitespace. The trie has no atomic
+    // `graph status` node, so the first descent misses (handler undefined) — yet
+    // did-you-mean would still list `graph status` as the #1 closest match, a
+    // self-contradiction. Re-split the lone token on whitespace and retry so the
+    // quoted form behaves identically to the unquoted `shrk graph status`.
+    // Genuinely unknown tokens leave `handler` undefined and fall through to the
+    // existing unknown-command path unchanged.
+    if (!handler && cleanArgv.length === 1 && /\s/.test(cleanArgv[0])) {
+        const retry = registry.resolve(cleanArgv[0].trim().split(/\s+/));
+        if (retry.handler) {
+            ({ handler, matchedPath, rest: leftover, node } = retry);
+        }
+    }
     // `--help` / `-h` immediately after a (sub)group → render help for that
     // path. This works at any depth.
     if (leftover[0] === '--help' || leftover[0] === '-h') {

package/dist/status/freshness.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Source-mtime freshness — a small shared CLI helper.
+ *
+ * Several `… status` commands (`framework status`, `context status`) need to
+ * answer the same question: "is this stored artefact stale relative to the
+ * source tree it was built from?" They all walk the workspace for the newest
+ * source-file mtime and compare it to a stored build timestamp. This module
+ * is the single home for that walk so the commands stay byte-identical.
+ *
+ * NOTE: this is deliberately CLI-local and distinct from
+ * `@shrkcrft/graph`'s `detectGraphFreshness` — that one models the graph
+ * store's own freshness and graph sits BELOW cli in the layer order, so it
+ * cannot be reused here.
+ */
+export declare const FRESHNESS_SKIP_DIRS: Set<string>;
+export declare const FRESHNESS_SOURCE_EXTS: Set<string>;
+export interface IStatusFreshness {
+    state: 'fresh' | 'stale' | 'unknown';
+    lastBuiltAt: string | null;
+    lastChangedAt: string | null;
+    behindMs: number;
+}
+/** Newest source-file mtime (ms) under `root`, ignoring build/output dirs. 0
+ *  when nothing matched. */
+export declare function newestSourceMtimeMs(root: string): number;
+/** Compare a stored build timestamp to the newest source mtime in `scope`.
+ *  `stale` when a source file is newer than the build; `unknown` when the
+ *  build timestamp can't be parsed. */
+export declare function computeMtimeFreshness(scope: string, builtAtIso: string | undefined | null): IStatusFreshness;
+//# sourceMappingURL=freshness.d.ts.map

package/dist/status/freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../../src/status/freshness.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,mBAAmB,aAG9B,CAAC;AACH,eAAO,MAAM,qBAAqB,aAGhC,CAAC;AAEH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;4BAC4B;AAC5B,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA8BxD;AAED;;uCAEuC;AACvC,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,gBAAgB,CAc5G"}