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

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

@@ -0,0 +1,22 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk spike <slug>` — turn a saved smart-context plan into starter
+ * files for the recommended MVP.
+ *
+ * Reads `.sharkcraft/smart-context/<slug>.plan.json` (written by
+ * smart-context when --save + focused/ai-plan succeeded), grabs
+ * `firstSpike.proposedFiles[]`, and writes a placeholder file at each
+ * proposed path that does not already exist. The placeholders carry a
+ * short header derived from `purpose` plus the plan's
+ * `schemaOutline` when present, so the human opening the file knows
+ * why it exists and what shape to fill in.
+ *
+ * Safety:
+ *   - Never overwrites an existing file.
+ *   - Refuses to write outside the workspace.
+ *   - `--dry-run` prints what would happen.
+ *   - `--force` is intentionally absent — a re-spike should mean
+ *     "delete then rerun" so the user gets a fresh prompt about it.
+ */
+export declare const spikeCommand: ICommandHandler;
+//# sourceMappingURL=spike.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spike.command.d.ts","sourceRoot":"","sources":["../../src/commands/spike.command.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAuBhC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,YAAY,EAAE,eAsI1B,CAAC"}

package/dist/commands/spike.command.js

@@ -0,0 +1,235 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { flagBool, resolveCwd, } from "../command-registry.js";
+import { asJson, header, kv } from "../output/format-output.js";
+const SMART_CONTEXT_DIR = nodePath.join('.sharkcraft', 'smart-context');
+/**
+ * `shrk spike <slug>` — turn a saved smart-context plan into starter
+ * files for the recommended MVP.
+ *
+ * Reads `.sharkcraft/smart-context/<slug>.plan.json` (written by
+ * smart-context when --save + focused/ai-plan succeeded), grabs
+ * `firstSpike.proposedFiles[]`, and writes a placeholder file at each
+ * proposed path that does not already exist. The placeholders carry a
+ * short header derived from `purpose` plus the plan's
+ * `schemaOutline` when present, so the human opening the file knows
+ * why it exists and what shape to fill in.
+ *
+ * Safety:
+ *   - Never overwrites an existing file.
+ *   - Refuses to write outside the workspace.
+ *   - `--dry-run` prints what would happen.
+ *   - `--force` is intentionally absent — a re-spike should mean
+ *     "delete then rerun" so the user gets a fresh prompt about it.
+ */
+export const spikeCommand = {
+    name: 'spike',
+    description: 'Scaffold starter files for a saved smart-context plan\'s recommended MVP. Reads .sharkcraft/smart-context/<slug>.plan.json.',
+    usage: 'shrk spike <slug> [--dry-run] [--json]',
+    async run(args) {
+        const slug = args.positional[0]?.trim();
+        if (!slug) {
+            process.stderr.write('Usage: shrk spike <slug> [--dry-run] [--json]\n');
+            process.stderr.write('       (slug comes from `shrk smart-context list`)\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const json = flagBool(args, 'json');
+        const dryRun = flagBool(args, 'dry-run');
+        const planPath = resolvePlanPath(cwd, slug);
+        if (!planPath) {
+            process.stderr.write(`No structured plan found for slug "${slug}". Looked under .sharkcraft/smart-context/.\n` +
+                `Tip: run smart-context with --save and a structured-output mode (--ai-plan or --focused --plan) first.\n`);
+            return 1;
+        }
+        let plan;
+        try {
+            plan = JSON.parse(readFileSync(planPath, 'utf8'));
+        }
+        catch (e) {
+            process.stderr.write(`Failed to parse ${planPath}: ${e.message}\n`);
+            return 1;
+        }
+        const proposed = plan.firstSpike?.proposedFiles ?? [];
+        if (proposed.length === 0) {
+            process.stderr.write(`Plan at ${planPath} has no firstSpike.proposedFiles[]. Re-run smart-context with --focused --plan (architecture tasks fill this in).\n`);
+            return 1;
+        }
+        const items = [];
+        for (const entry of proposed) {
+            const raw = entry?.path?.trim();
+            if (!raw || raw.length === 0)
+                continue;
+            // Refuse placeholder-y paths like `.../<timestamp>.json`.
+            if (/[<>{}]/.test(raw)) {
+                items.push({ path: raw, absolute: '', action: 'skip-unsafe', reason: 'placeholder syntax' });
+                continue;
+            }
+            const safe = safeJoin(cwd, raw);
+            if (!safe) {
+                items.push({ path: raw, absolute: '', action: 'skip-unsafe', reason: 'escapes workspace' });
+                continue;
+            }
+            if (existsSync(safe)) {
+                items.push({ path: raw, absolute: safe, action: 'skip-exists' });
+                continue;
+            }
+            items.push({ path: raw, absolute: safe, action: 'create' });
+        }
+        const willCreate = items.filter((i) => i.action === 'create');
+        const skipExists = items.filter((i) => i.action === 'skip-exists');
+        const skipUnsafe = items.filter((i) => i.action === 'skip-unsafe');
+        if (!dryRun) {
+            for (const item of willCreate) {
+                const purpose = proposed.find((p) => p.path === item.path)?.purpose ?? '';
+                const body = renderStarter({
+                    path: item.path,
+                    purpose,
+                    plan,
+                });
+                mkdirSync(nodePath.dirname(item.absolute), { recursive: true });
+                writeFileSync(item.absolute, body, 'utf8');
+            }
+        }
+        if (json) {
+            process.stdout.write(asJson({
+                slug,
+                planPath,
+                dryRun,
+                created: willCreate.map((i) => i.path),
+                skippedExisting: skipExists.map((i) => i.path),
+                skippedUnsafe: skipUnsafe.map((i) => ({ path: i.path, reason: i.reason })),
+                proposedCommand: plan.firstSpike?.proposedCommand ?? null,
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`Spike for: ${slug}`));
+        process.stdout.write(kv('plan', planPath) + '\n');
+        if (plan.recommendedMvp?.architectureName) {
+            process.stdout.write(kv('mvp', plan.recommendedMvp.architectureName) + '\n');
+        }
+        process.stdout.write('\n');
+        if (willCreate.length > 0) {
+            process.stdout.write(`Files ${dryRun ? 'that would be created' : 'created'} (${willCreate.length}):\n`);
+            for (const item of willCreate) {
+                const purpose = proposed.find((p) => p.path === item.path)?.purpose ?? '';
+                process.stdout.write(`  + ${item.path}${purpose ? `  — ${purpose}` : ''}\n`);
+            }
+        }
+        else {
+            process.stdout.write('Nothing new to create.\n');
+        }
+        if (skipExists.length > 0) {
+            process.stdout.write(`\nSkipped (already exist):\n`);
+            for (const item of skipExists)
+                process.stdout.write(`  · ${item.path}\n`);
+        }
+        if (skipUnsafe.length > 0) {
+            process.stdout.write(`\nSkipped (unsafe):\n`);
+            for (const item of skipUnsafe) {
+                process.stdout.write(`  ! ${item.path} — ${item.reason ?? 'unsafe'}\n`);
+            }
+        }
+        if (plan.firstSpike?.proposedCommand) {
+            process.stdout.write(`\nNext: run \`${plan.firstSpike.proposedCommand}\`\n`);
+        }
+        if (plan.firstSpike?.successCriteria && plan.firstSpike.successCriteria.length > 0) {
+            process.stdout.write(`\nSuccess criteria:\n`);
+            for (const c of plan.firstSpike.successCriteria)
+                process.stdout.write(`  - ${c}\n`);
+        }
+        return 0;
+    },
+};
+function resolvePlanPath(cwd, slug) {
+    const dir = nodePath.join(cwd, SMART_CONTEXT_DIR);
+    if (!existsSync(dir))
+        return null;
+    // Exact match first.
+    const exact = nodePath.join(dir, `${slug}.plan.json`);
+    if (existsSync(exact))
+        return exact;
+    // Otherwise tolerate <slug>-plan.plan.json and similar suffix patterns.
+    try {
+        for (const name of readdirSync(dir)) {
+            if (!name.endsWith('.plan.json'))
+                continue;
+            const base = name.replace(/\.plan\.json$/, '');
+            if (base === slug || base.startsWith(slug)) {
+                return nodePath.join(dir, name);
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+function safeJoin(cwd, candidate) {
+    const normalised = candidate.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (nodePath.isAbsolute(normalised)) {
+        // Permit only if inside cwd.
+        const resolved = nodePath.resolve(normalised);
+        if (!resolved.startsWith(cwd + nodePath.sep) && resolved !== cwd)
+            return null;
+        return resolved;
+    }
+    const resolved = nodePath.resolve(cwd, normalised);
+    if (!resolved.startsWith(cwd + nodePath.sep))
+        return null;
+    return resolved;
+}
+function renderStarter(input) {
+    const ext = nodePath.extname(input.path).toLowerCase();
+    const commentOpen = pickCommentOpen(ext);
+    const lines = [];
+    const taskOrSummary = input.plan.summary ?? input.plan.task ?? 'smart-context spike';
+    lines.push(`${commentOpen} Spike scaffold: ${input.path}`);
+    if (input.purpose)
+        lines.push(`${commentOpen} Purpose: ${input.purpose}`);
+    lines.push(`${commentOpen} Generated by \`shrk spike\` from a smart-context plan.`);
+    lines.push(`${commentOpen} Plan summary: ${taskOrSummary}`);
+    const mvp = input.plan.recommendedMvp?.architectureName;
+    if (mvp)
+        lines.push(`${commentOpen} MVP: ${mvp}`);
+    lines.push(`${commentOpen} Replace this header with the real implementation.`);
+    if (input.plan.firstSpike?.schemaOutline !== undefined && (ext === '.json' || ext === '.md')) {
+        lines.push('');
+        if (ext === '.json') {
+            const outlined = typeof input.plan.firstSpike.schemaOutline === 'string'
+                ? input.plan.firstSpike.schemaOutline
+                : JSON.stringify(input.plan.firstSpike.schemaOutline, null, 2);
+            lines.push(outlined);
+        }
+        else {
+            lines.push('```json');
+            lines.push(typeof input.plan.firstSpike.schemaOutline === 'string'
+                ? input.plan.firstSpike.schemaOutline
+                : JSON.stringify(input.plan.firstSpike.schemaOutline, null, 2));
+            lines.push('```');
+        }
+    }
+    // For .ts/.tsx files leave a TODO line so the file is syntactically valid.
+    if (ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx') {
+        lines.push('');
+        lines.push('// TODO(spike): implement.');
+        lines.push('export {};');
+    }
+    return lines.join('\n') + '\n';
+}
+function pickCommentOpen(ext) {
+    switch (ext) {
+        case '.json':
+            return '//'; // not technically valid JSON; we replace this body below for .json files
+        case '.md':
+            return '<!--';
+        case '.yml':
+        case '.yaml':
+            return '#';
+        case '.sh':
+            return '#';
+        default:
+            return '//';
+    }
+}
+void statSync;

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

@@ -10,6 +10,7 @@ import { type ICommandHandler } from '../command-registry.js';
  *   - unhide  <command>     reverse hide
  *   - reset                 clear surface.enabled + surface.hidden
  *   - explain <command>     why this command has its current tier
+ *   - profiles [get <id>]   list surface profiles (or show one)
  */
 export declare const surfaceCommand: ICommandHandler;
 //# sourceMappingURL=surface.command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"surface.command.d.ts","sourceRoot":"","sources":["../../src/commands/surface.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiBhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,EAAE,eAmC5B,CAAC"}
+{"version":3,"file":"surface.command.d.ts","sourceRoot":"","sources":["../../src/commands/surface.command.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiBhC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,eAmC5B,CAAC"}

package/dist/commands/surface.command.js

@@ -15,11 +15,12 @@ import { applySurfaceEdit, defaultConfigFile, planSurfaceEdit, } from "../surfac
  *   - unhide  <command>     reverse hide
  *   - reset                 clear surface.enabled + surface.hidden
  *   - explain <command>     why this command has its current tier
+ *   - profiles [get <id>]   list surface profiles (or show one)
  */
 export const surfaceCommand = {
     name: 'surface',
     description: 'Inspect or change the adaptive command surface (core / extended / experimental tiers).',
-    usage: 'shrk surface <list|enable|disable|hide|unhide|reset|explain> [name] [--write] [--json]',
+    usage: 'shrk surface <list|enable|disable|hide|unhide|reset|explain|profiles> [name] [--write] [--json]',
     async run(args) {
         const [verb, ...rest] = args.positional;
         const json = flagBool(args, 'json');
@@ -84,7 +85,7 @@ async function runProfiles(opts) {
         const found = availableProfiles.find((p) => p.id === opts.target);
         if (!found) {
             process.stderr.write(`Unknown profile: ${opts.target}\n`);
-            return 1;
+            return 2;
         }
         if (opts.json) {
             process.stdout.write(asJson(found) + '\n');
@@ -171,10 +172,16 @@ async function runExplain({ cwd, json, target }) {
         process.stderr.write('Usage: shrk surface explain <command>\n');
         return 2;
     }
-    const { context, activeProfile } = await loadSurfaceContext({ cwd });
+    const { context, activeProfile, availableProfiles } = await loadSurfaceContext({ cwd });
     const summary = buildSurfaceSummary(context);
     const view = findCommandInSummary(summary, target);
     if (!view) {
+        // A common mix-up: `surface explain <profile>`. `explain` is for commands;
+        // point the user at the profile-aware verb instead of a bare "unknown".
+        if (availableProfiles.some((p) => p.id === target)) {
+            process.stderr.write(`'${target}' is a surface profile, not a command. Try: shrk surface profiles get ${target}\n`);
+            return 2;
+        }
         process.stderr.write(`Unknown command: ${target}\n`);
         return 2;
     }

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

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

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

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { cliCommandNameSet } from "./command-catalog.js";
 import { analyzeImportGraph, buildAgentBrief, buildContradictionReport, buildGeneratedCodeReport, buildRepositoryKnowledgeModel, buildTaskPacket, buildTaskRiskReport, classifyChangeIntent, detectLanguageProfiles, getChangedFiles, getStatusSummary, inspectSharkcraft, isGitRepo, listConstructs, loadRepositoryMemory, } from '@shrkcrft/inspector';
 import { flagBool, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
@@ -102,7 +103,10 @@ export const validateChangeCommand = {
         }
         // Fallback path through getStatusSummary not necessary — getChangedFiles already covers it.
         void getStatusSummary;
-        const contradictions = buildContradictionReport({ inspection });
+        const contradictions = buildContradictionReport({
+            inspection,
+            cliCommandNames: cliCommandNameSet(),
+        });
         const generated = buildGeneratedCodeReport({ inspection });
         const generatedPaths = new Set(generated.generatedFiles.map((f) => f.path));
         const boundaryHits = changed.filter((f) => looksLikeBoundaryViolation(f));
@@ -399,22 +403,6 @@ async function collectLikelyFilesV2(input) {
             }
         }
     }
-    // Boost files that sit on registered plugin-lifecycle profile barrels.
-    try {
-        const { listPluginLifecycleProfiles } = await import('@shrkcrft/inspector');
-        const profiles = await listPluginLifecycleProfiles(inspection);
-        for (const entry of profiles) {
-            for (const b of entry.profile.barrels ?? []) {
-                for (const f of [...scoreByPath.keys()]) {
-                    if (f.includes(b.path))
-                        bump(f, 3, `lifecycle profile barrel: ${b.id}`);
-                }
-            }
-        }
-    }
-    catch {
-        // Profile registry unavailable — skip the boost.
-    }
     // 10) Tests — files that look like they test the matched files.
     const tests = [];
     for (const f of [...scoreByPath.keys()]) {

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,eA8PzB,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;AA2DhC,eAAO,MAAM,WAAW,EAAE,eAoQzB,CAAC"}

package/dist/commands/task.command.js

@@ -58,8 +58,8 @@ function minimalTaskPacket(p) {
 }
 export const taskCommand = {
     name: 'task',
-    description: 'Build an AI-ready task packet: relevant context, action hints, recommended pipeline, templates, paths, verification commands. Pass `--next` to skip the packet and survey the workspace for the highest-leverage next action.',
-    usage: 'shrk [--cwd <dir>] task "<task>" [--max-tokens 4000] [--scope x,y] [--explain-ranking] [--json] [--compact]   OR   shrk task --next [--json]',
+    description: 'Build an AI-ready task packet: relevant context, action hints, recommended pipeline, templates, paths, verification commands. Defaults to a compact packet (top-5 rules / top-3 templates / 5 hints per field) to keep agent token cost low. Pass `--full` to get the unrestricted packet, or `--next` to skip the packet and survey the workspace for the highest-leverage next action.',
+    usage: 'shrk [--cwd <dir>] task "<task>" [--max-tokens 4000] [--scope x,y] [--explain-ranking] [--full] [--json]   OR   shrk task --next [--json]',
     async run(args) {
         const positional = args.positional;
         // `--next` short-circuits the packet build. Survey doctor / lint /
@@ -142,10 +142,16 @@ export const taskCommand = {
         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');
         const packet = buildTaskPacket(inspection, task, {
             maxTokens,
             ...(scope.length ? { scope } : {}),
             explainRanking,
+            compact,
         });
         // Uncertainty summary always computed; coverage gaps when requested.
         const uncertainty = buildUncertaintySummary(packet);

package/dist/commands/template-quality.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-quality.command.d.ts","sourceRoot":"","sources":["../../src/commands/template-quality.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,oBAAoB,EAAE,eAkClC,CAAC;AAqDF,eAAO,MAAM,oBAAoB,EAAE,eAmBlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAuBtC,CAAC"}
+{"version":3,"file":"template-quality.command.d.ts","sourceRoot":"","sources":["../../src/commands/template-quality.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC,eAAO,MAAM,oBAAoB,EAAE,eAsDlC,CAAC;AA4EF,eAAO,MAAM,oBAAoB,EAAE,eAmBlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAuBtC,CAAC"}

package/dist/commands/template-quality.command.js

@@ -3,18 +3,32 @@ import * as nodePath from 'node:path';
 import { inspectSharkcraft, lintTemplates, testTemplates, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+import { enrichWithLlmRecommendations, renderRecommendationsMarkdown, } from '@shrkcrft/ai';
 export const templatesLintCommand = {
     name: 'lint',
-    description: 'Lint registered templates (titles, vars, target safety, placeholders). --fix-preview emits a TODO patch per finding under .sharkcraft/fixes/templates-lint/ (preview only — never mutates source).',
-    usage: 'shrk templates lint [<id>] [--fix-preview] [--json]',
+    description: 'Lint registered templates (titles, vars, target safety, placeholders). --fix-preview emits a TODO patch per finding under .sharkcraft/fixes/templates-lint/ (preview only — never mutates source). --llm-recommendations layers concrete next-steps onto the deterministic findings when a local LLM is reachable.',
+    usage: 'shrk templates lint [<id>] [--fix-preview] [--json] [--llm-recommendations] [--provider auto|ollama|llamacpp]',
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
         const ids = args.positional.length > 0 ? args.positional : undefined;
         const report = lintTemplates(inspection, ids);
         const fixPreview = flagBool(args, 'fix-preview');
+        const wantLlm = flagBool(args, 'llm-recommendations');
+        const llmEnvelope = wantLlm
+            ? await enrichWithLlmRecommendations({
+                surface: 'templates-lint',
+                deterministicSummary: summariseLintResults(report.results),
+                providerKind: flagString(args, 'provider') ?? undefined,
+                ask: 'For each non-passing template, suggest ONE concrete edit in sharkcraft/templates.ts: name the field (description, variables[i].examples, related[i], etc.) and the literal value or removal. Skip templates with only `info`-level issues unless a clear improvement exists.',
+                maxTokens: 1024,
+            })
+            : null;
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(report) + '\n');
+            process.stdout.write(asJson({
+                ...report,
+                ...(llmEnvelope ? { llmRecommendations: llmEnvelope } : {}),
+            }) + '\n');
             if (fixPreview)
                 writeFixPreviewPatches(cwd, report.results);
             return report.summary.errors > 0 ? 1 : 0;
@@ -35,9 +49,31 @@ export const templatesLintCommand = {
                 process.stdout.write('\nNo fix-preview patches needed.\n');
             }
         }
+        if (llmEnvelope) {
+            process.stdout.write('\n');
+            process.stdout.write(renderRecommendationsMarkdown(llmEnvelope));
+        }
         return report.summary.errors > 0 ? 1 : 0;
     },
 };
+function summariseLintResults(results) {
+    const lines = [];
+    for (const r of results) {
+        lines.push(`## ${r.passed ? 'OK' : 'FAIL'} ${r.templateId}`);
+        if (r.issues.length === 0) {
+            lines.push('(no issues)');
+        }
+        else {
+            for (const i of r.issues) {
+                lines.push(`- ${i.severity} \`${i.code}\` — ${i.message}`);
+            }
+        }
+        lines.push('');
+    }
+    if (lines.length === 0)
+        lines.push('(no templates registered)');
+    return lines.join('\n');
+}
 /** Write a per-template TODO patch under `.sharkcraft/fixes/templates-lint/`. */
 function writeFixPreviewPatches(cwd, results) {
     const dir = nodePath.join(cwd, '.sharkcraft', 'fixes', 'templates-lint');

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

@@ -1 +1 @@
-{"version":3,"file":"templates.command.d.ts","sourceRoot":"","sources":["../../src/commands/templates.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,oBAAoB,EAAE,eA6DlC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmBlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA+CjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAgBpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiDrC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAWnC,CAAC;AAyKF,eAAO,MAAM,2BAA2B,EAAE,eA+BzC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAOnC,CAAC;AA2GF,eAAO,MAAM,wBAAwB,EAAE,eA+FtC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAKjC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAyCpC,CAAC;AAwHF,eAAO,MAAM,sBAAsB,EAAE,eAiKpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAkEpC,CAAC"}
+{"version":3,"file":"templates.command.d.ts","sourceRoot":"","sources":["../../src/commands/templates.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAUhC,eAAO,MAAM,oBAAoB,EAAE,eA6DlC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmBlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA+CjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAgBpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiDrC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAWnC,CAAC;AAgNF,eAAO,MAAM,2BAA2B,EAAE,eA+BzC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAOnC,CAAC;AA2GF,eAAO,MAAM,wBAAwB,EAAE,eA+FtC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAKjC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAyCpC,CAAC;AAwHF,eAAO,MAAM,sBAAsB,EAAE,eAiKpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAkEpC,CAAC"}

package/dist/commands/templates.command.js

@@ -9,6 +9,7 @@ import { flagBool, flagList, flagString, flagVars, resolveCwd, } from "../comman
 import { asJson, header, kv } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
 import { renderFailureHints, templateDriftHints } from "../output/failure-hints.js";
+import { enrichWithLlmRecommendations, renderRecommendationsMarkdown, } from '@shrkcrft/ai';
 export const templatesVarsCommand = {
     name: 'vars',
     description: 'Show the variables a template accepts (required/optional/defaults/examples).',
@@ -209,8 +210,8 @@ export const templatesPreviewCommand = {
 };
 export const templatesDriftCommand = {
     name: 'drift',
-    description: 'Verify every registered template against the workspace. Severity controls and `--watch [--once] [--debounce N]` supported. Read-only.',
-    usage: 'shrk templates drift [--template <id>] [--pack <packId>] [--var key=value ...] [--min-severity error|warning|info] [--hide <code>[,<code>...]] [--strict] [--ci] [--format text|markdown|html|json] [--report] [--output <path>] [--json] [--watch [--once] [--debounce N]]',
+    description: 'Verify every registered template against the workspace. Severity controls and `--watch [--once] [--debounce N]` supported. `--llm-recommendations` layers a local-LLM-derived list of concrete next-steps on top of the deterministic findings (no-op when no provider reachable). Read-only.',
+    usage: 'shrk templates drift [--template <id>] [--pack <packId>] [--var key=value ...] [--min-severity error|warning|info] [--hide <code>[,<code>...]] [--strict] [--ci] [--format text|markdown|html|json] [--report] [--output <path>] [--json] [--llm-recommendations] [--provider auto|ollama|llamacpp] [--watch [--once] [--debounce N]]',
     async run(args) {
         const watchExit = await maybeRunInWatchMode(args, templatesDriftImpl);
         if (watchExit !== null)
@@ -272,6 +273,16 @@ async function templatesDriftImpl(args) {
         else
             filteredFail++;
     }
+    const wantLlmRecs = flagBool(args, 'llm-recommendations');
+    const llmEnvelope = wantLlmRecs
+        ? await enrichWithLlmRecommendations({
+            surface: 'templates-drift',
+            deterministicSummary: summariseDriftEntries(filteredEntries),
+            providerKind: flagString(args, 'provider') ?? undefined,
+            ask: 'For each FAIL or WARN entry, propose ONE concrete fix the maintainer can apply — name the specific field in `sharkcraft/templates.ts` (or a peer file) to edit. Skip PASS entries unless something is genuinely worth nudging.',
+            maxTokens: 1024,
+        })
+        : null;
     const ciPayload = {
         ...report,
         entries: filteredEntries,
@@ -284,6 +295,7 @@ async function templatesDriftImpl(args) {
             minSeverity: minSeverityRaw || 'info',
             hideCodes: [...hideCodes],
         },
+        ...(llmEnvelope ? { llmRecommendations: llmEnvelope } : {}),
     };
     const exitNonZero = ci
         ? filteredFail > 0 || (strict && filteredWarn > 0)
@@ -330,8 +342,31 @@ async function templatesDriftImpl(args) {
     if (exitNonZero) {
         process.stdout.write(renderFailureHints(templateDriftHints()));
     }
+    if (llmEnvelope) {
+        process.stdout.write('\n');
+        process.stdout.write(renderRecommendationsMarkdown(llmEnvelope));
+    }
     return exitNonZero ? 1 : 0;
 }
+function summariseDriftEntries(entries) {
+    const lines = [];
+    for (const e of entries) {
+        const tag = e.status === TemplateDriftStatus.Pass ? 'PASS' : e.status === TemplateDriftStatus.Warn ? 'WARN' : 'FAIL';
+        lines.push(`## [${tag}] ${e.templateId}${e.templateName ? ` — ${e.templateName}` : ''}`);
+        if (e.issues.length === 0) {
+            lines.push('(no issues)');
+        }
+        else {
+            for (const i of e.issues) {
+                lines.push(`- ${i.severity} \`${i.code}\` — ${i.message}${i.suggestedFix ? ` (suggested: ${i.suggestedFix})` : ''}`);
+            }
+        }
+        lines.push('');
+    }
+    if (lines.length === 0)
+        lines.push('(no templates in this drift report)');
+    return lines.join('\n');
+}
 function renderDriftMarkdown(p) {
     const out = [];
     out.push('# Template drift');

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

@@ -1 +1 @@
-{"version":3,"file":"tests.command.d.ts","sourceRoot":"","sources":["../../src/commands/tests.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiChC,eAAO,MAAM,kBAAkB,EAAE,eAyBhC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAajC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAgBjC,CAAC"}
+{"version":3,"file":"tests.command.d.ts","sourceRoot":"","sources":["../../src/commands/tests.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAwChC,eAAO,MAAM,kBAAkB,EAAE,eAyBhC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAajC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAgBjC,CAAC"}

package/dist/commands/tests.command.js

@@ -1,13 +1,24 @@
 import { existsSync, readFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { analyzeTestImpact, inspectSharkcraft, readFeatureBundle, suggestTestPathFor, } from '@shrkcrft/inspector';
+import { analyzeTestImpact, getChangedFiles, inspectSharkcraft, readFeatureBundle, suggestTestPathFor, } from '@shrkcrft/inspector';
 import { flagBool, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
 function collectFiles(cwd, args) {
     const files = flagList(args, 'files');
     const planFile = flagString(args, 'plan');
     const bundleId = flagString(args, 'bundle');
+    const since = flagString(args, 'since');
+    const staged = flagBool(args, 'staged');
     const out = [...files];
+    // `--since <ref>` / `--staged`: collect changed files straight from git so
+    // the agent's reflex `shrk tests impact --since main` works the same way as
+    // `shrk impact --since` (was --files-only, forcing a manual diff).
+    if (since)
+        for (const f of getChangedFiles(cwd, { since }))
+            out.push(f);
+    if (staged)
+        for (const f of getChangedFiles(cwd, { staged: true }))
+            out.push(f);
     if (planFile) {
         const path = nodePath.isAbsolute(planFile) ? planFile : nodePath.join(cwd, planFile);
         if (existsSync(path)) {
@@ -38,7 +49,7 @@ function collectFiles(cwd, args) {
 export const testsImpactCommand = {
     name: 'impact',
     description: 'Test impact analysis for changed files / plan / bundle.',
-    usage: 'shrk tests impact [--files a,b] [--plan <plan>] [--bundle <id>] "<task>"',
+    usage: 'shrk tests impact [--files a,b] [--since <ref>] [--staged] [--plan <plan>] [--bundle <id>] "<task>"',
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });

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

@@ -0,0 +1,26 @@
+import { type ICommandHandler } from '../command-registry.js';
+/**
+ * `shrk watch "<task>"` — emit a fresh task-focused context bundle on
+ * stdout JSONL each time the workspace changes.
+ *
+ * Designed to run in a terminal *next to* Claude Code so the agent has
+ * a continuously-refreshed "feed" of the most relevant code for the
+ * current task — no extra LLM calls, just BGE-ranked deltas.
+ *
+ * Surfaces:
+ *   - stdout: one JSON line per packet, NDJSON-style.
+ *   - filesystem: same packet appended to
+ *     `.sharkcraft/feed/<slug>.jsonl` so other tools (or the user)
+ *     can tail it from elsewhere.
+ *
+ * Cost: every emission is O(BGE-search + re-rank) — typically
+ * 100–300 ms for ~10 candidate files. We never call a generative LLM.
+ */
+export declare const watchCommand: ICommandHandler;
+/** `shrk watch list` — show all active and stale watch manifests. */
+export declare const watchListCommand: ICommandHandler;
+/** `shrk watch stop <slug>` — SIGTERM the matching watcher. */
+export declare const watchStopCommand: ICommandHandler;
+/** `shrk watch prune` — remove stale manifests. */
+export declare const watchPruneCommand: ICommandHandler;
+//# sourceMappingURL=watch.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"watch.command.d.ts","sourceRoot":"","sources":["../../src/commands/watch.command.ts"],"names":[],"mappings":"AAwBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2ChC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,EAAE,eAkL1B,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,EAAE,eAwD9B,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,EAAE,eA4C9B,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,EAAE,eA8B/B,CAAC"}