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

package/dist/commands/reuse.command.js

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

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

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

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

@@ -52,11 +52,13 @@ export const smartContextCommand = {
     name: 'smart-context',
     booleanFlags: SMART_CONTEXT_BOOLEAN_FLAGS,
     description: 'Build deterministic context and ask an AI provider to synthesise an enriched brief (default), structured plan (--plan), or two-stage development plan (--ai-plan).',
-    usage: 'shrk smart-context "<task>" [--plus] [--budget <seconds>] [--plan] [--ai-plan] [--save] [--provider auto|ollama|llamacpp] [--enhance|--no-enhance] [--enhance-passes N] [--instructions <path>] [--no-instructions] [--model <id>] [--max-tokens N] [--stage1-max-tokens N] [--seed-tokens N] [--expansion-tokens N] [--expansion-limit N] [--log-prompt] [--save-conversation[=<path>]] [--dry-run] [--debug] [--json]',
+    usage: 'shrk smart-context "<task>" | --task "<task>" [--plus] [--budget <seconds>] [--plan] [--ai-plan] [--save] [--provider auto|ollama|llamacpp] [--enhance|--no-enhance] [--enhance-passes N] [--instructions <path>] [--no-instructions] [--model <id>] [--max-tokens N] [--stage1-max-tokens N] [--seed-tokens N] [--expansion-tokens N] [--expansion-limit N] [--log-prompt] [--save-conversation[=<path>]] [--dry-run] [--debug] [--json]',
     async run(args) {
-        const task = args.positional.join(' ').trim();
+        // Accept the documented `--task` form as well as the positional form, so the
+        // CLI surface matches the docs (which advertise `--task` broadly).
+        const task = (args.positional.join(' ').trim() || flagString(args, 'task') || '').trim();
         if (!task) {
-            process.stderr.write('Usage: shrk smart-context "<task>" [--plan] [--ai-plan] [--save]\n');
+            process.stderr.write('Usage: shrk smart-context "<task>" [--task "<task>"] [--plan] [--ai-plan] [--save]\n');
             return 2;
         }
         // Isolate the LLM / native-runtime work in a child process. On macOS the
@@ -165,7 +167,7 @@ export const smartContextCommand = {
                 (originalContext.length > 0 && enhanced.value.content.trim() === originalContext);
             if (fullyDegraded) {
                 if (!opts.json) {
-                    process.stderr.write('[smart-context] enhancement fully degraded — returning deterministic context only.\n');
+                    process.stderr.write(degradedRetrievalBanner(seed, 'enhancement fully degraded') + '\n');
                 }
                 const fallbackEnvelope = buildEnvelope({
                     task,
@@ -226,7 +228,7 @@ export const smartContextCommand = {
             // exit 1. The agent that asked for fast grounding still gets usable
             // rules / paths / templates / candidate files. The error is advisory on
             // stderr (never stdout, so --json stays valid).
-            process.stderr.write('[smart-context] provider unavailable — returning deterministic context only.\n');
+            process.stderr.write(degradedRetrievalBanner(seed, 'provider unavailable') + '\n');
             const fallbackEnvelope = buildEnvelope({
                 task,
                 seed,
@@ -1452,6 +1454,19 @@ export function renderIndexFreshnessWarning(f) {
         `(${f.stale} changed, ${f.missing} deleted, ${f.untracked} new).${pruned} ` +
         'Verify the file suggestions above before editing — run `shrk smart-context --refresh` to rebuild.');
 }
+/**
+ * Loud one-liner for the degraded / provider-unavailable path. The returned
+ * content is the deterministic seed (rules/paths/templates/candidate files), NOT
+ * task-scoped semantic retrieval — so say so, and how far the index is behind,
+ * so a caller never trusts a stale generic dump as if it were curated retrieval.
+ */
+function degradedRetrievalBanner(seed, cause) {
+    const behind = seed.indexFreshness?.behind ?? 0;
+    const behindClause = behind > 0 ? `, semantic index ${behind} file(s) behind the working tree` : '';
+    return (`[smart-context] semantic retrieval unavailable (${cause})${behindClause} — ` +
+        'falling back to the deterministic seed (rules/paths/templates/candidate files), NOT task-scoped retrieval. ' +
+        'Run `shrk smart-context --refresh` to rebuild the index.');
+}
 async function buildSmartContextSeed(input) {
     const { cwd, task, inspection, options } = input;
     const overview = buildProjectOverview(inspection.workspace, inspection.config?.projectName);

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

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

package/dist/commands/task.command.js

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

package/dist/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;AA4X/B,wBAAgB,aAAa,IAAI,eAAe,CAgY/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"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AA6X/B,wBAAgB,aAAa,IAAI,eAAe,CAiY/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

@@ -73,6 +73,7 @@ import { movePlanCommand } from "./commands/move-plan.command.js";
 import { watchCommand, watchListCommand, watchPruneCommand, watchStopCommand } from "./commands/watch.command.js";
 import { mcpCommand } from "./commands/mcp.command.js";
 import { versionCommand } from "./commands/version.command.js";
+import { changelogCommand } from "./commands/changelog.command.js";
 import { makeHelpCommand } from "./commands/help.command.js";
 import { qualityCommand } from "./commands/quality.command.js";
 import { ciCommand } from "./commands/ci.command.js";
@@ -249,6 +250,7 @@ export function buildRegistry() {
     registry.registerSubcommand('watch', watchPruneCommand);
     registry.register(mcpCommand);
     registry.register(versionCommand);
+    registry.register(changelogCommand);
     registry.register(qualityCommand);
     registry.register(ciCommand);
     registry.register(eslintCommand);

package/dist/validation/typecheck-emitted.d.ts

@@ -0,0 +1,36 @@
+/** A file the generator would emit, with its rendered (in-memory) contents. */
+export interface IEmittedFile {
+    /** Absolute path the file would land at. */
+    absPath: string;
+    /** Rendered body (never written to disk by the typecheck). */
+    contents: string;
+}
+/** A single typecheck error located in an emitted file. */
+export interface IEmittedTypecheckError {
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+}
+export interface IEmittedTypecheckResult {
+    /** False when there were no TS/TSX files to check (e.g. a docs-only template). */
+    ran: boolean;
+    errors: readonly IEmittedTypecheckError[];
+    /** Human note (why it didn't run, or which tsconfig it used). */
+    note?: string;
+}
+/**
+ * Typecheck a set of EMITTED (not-yet-written) files against the project's
+ * detected tsconfig, without touching disk. Builds a `ts.Program` whose root
+ * names are the emitted files, over a compiler host that overlays the rendered
+ * bodies for those paths and reads everything else (imports, lib) from disk — so
+ * a scaffold that references a real project symbol resolves, and a template bug
+ * (bad syntax, a dangling import, a type mismatch) surfaces BEFORE apply instead
+ * of at the human's next build.
+ *
+ * Only diagnostics located IN the emitted files are reported; pre-existing
+ * errors elsewhere in the project are ignored (this is a generation gate, not a
+ * whole-repo typecheck).
+ */
+export declare function typecheckEmittedFiles(projectRoot: string, files: readonly IEmittedFile[]): IEmittedTypecheckResult;
+//# sourceMappingURL=typecheck-emitted.d.ts.map

package/dist/validation/typecheck-emitted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typecheck-emitted.d.ts","sourceRoot":"","sources":["../../src/validation/typecheck-emitted.ts"],"names":[],"mappings":"AAIA,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2DAA2D;AAC3D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC1C,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,uBAAuB,CAmFzB"}

package/dist/validation/typecheck-emitted.js

@@ -0,0 +1,109 @@
+import * as ts from 'typescript';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+const TSCONFIG_NAMES = ['tsconfig.json', 'tsconfig.base.json'];
+function findTsconfig(projectRoot) {
+    for (const name of TSCONFIG_NAMES) {
+        const p = resolve(projectRoot, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Typecheck a set of EMITTED (not-yet-written) files against the project's
+ * detected tsconfig, without touching disk. Builds a `ts.Program` whose root
+ * names are the emitted files, over a compiler host that overlays the rendered
+ * bodies for those paths and reads everything else (imports, lib) from disk — so
+ * a scaffold that references a real project symbol resolves, and a template bug
+ * (bad syntax, a dangling import, a type mismatch) surfaces BEFORE apply instead
+ * of at the human's next build.
+ *
+ * Only diagnostics located IN the emitted files are reported; pre-existing
+ * errors elsewhere in the project are ignored (this is a generation gate, not a
+ * whole-repo typecheck).
+ */
+export function typecheckEmittedFiles(projectRoot, files) {
+    const tsFiles = files.filter((f) => /\.tsx?$/.test(f.absPath));
+    if (tsFiles.length === 0) {
+        return { ran: false, errors: [], note: 'no TS/TSX files in the emit set' };
+    }
+    let options = {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        strict: true,
+        esModuleInterop: true,
+    };
+    const tsconfigPath = findTsconfig(projectRoot);
+    if (tsconfigPath) {
+        const read = ts.readConfigFile(tsconfigPath, (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return undefined;
+            }
+        });
+        if (!read.error) {
+            const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(tsconfigPath));
+            options = parsed.options;
+        }
+    }
+    // Force a non-emitting, lib-skipping check regardless of the project's config.
+    options.noEmit = true;
+    options.skipLibCheck = true;
+    options.incremental = false;
+    delete options.composite;
+    delete options.outDir;
+    delete options.declaration;
+    const overlay = new Map(tsFiles.map((f) => [resolve(f.absPath), f.contents]));
+    const host = ts.createCompilerHost(options, true);
+    const origGetSourceFile = host.getSourceFile.bind(host);
+    const origReadFile = host.readFile.bind(host);
+    const origFileExists = host.fileExists.bind(host);
+    host.readFile = (fileName) => {
+        const k = resolve(fileName);
+        return overlay.has(k) ? overlay.get(k) : origReadFile(fileName);
+    };
+    host.fileExists = (fileName) => overlay.has(resolve(fileName)) || origFileExists(fileName);
+    host.getSourceFile = (fileName, languageVersionOrOptions, onError, shouldCreate) => {
+        const k = resolve(fileName);
+        const body = overlay.get(k);
+        if (body !== undefined) {
+            return ts.createSourceFile(fileName, body, languageVersionOrOptions, true);
+        }
+        return origGetSourceFile(fileName, languageVersionOrOptions, onError, shouldCreate);
+    };
+    const rootNames = tsFiles.map((f) => resolve(f.absPath));
+    const program = ts.createProgram({ rootNames, options, host });
+    const errors = [];
+    for (const rn of rootNames) {
+        const sf = program.getSourceFile(rn);
+        if (!sf)
+            continue;
+        const diags = [...program.getSyntacticDiagnostics(sf), ...program.getSemanticDiagnostics(sf)];
+        for (const d of diags) {
+            if (d.category !== ts.DiagnosticCategory.Error)
+                continue;
+            let line = 0;
+            let column = 0;
+            if (d.file && typeof d.start === 'number') {
+                const lc = d.file.getLineAndCharacterOfPosition(d.start);
+                line = lc.line + 1;
+                column = lc.character + 1;
+            }
+            errors.push({
+                file: resolve(d.file?.fileName ?? rn),
+                line,
+                column,
+                message: ts.flattenDiagnosticMessageText(d.messageText, '\n'),
+            });
+        }
+    }
+    return {
+        ran: true,
+        errors,
+        ...(tsconfigPath ? { note: `checked against ${tsconfigPath}` } : { note: 'no tsconfig found — used defaults' }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/cli",
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.25",
   "description": "SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -47,38 +47,38 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.24",
-    "@shrkcrft/compress": "^0.1.0-alpha.24",
-    "@shrkcrft/config": "^0.1.0-alpha.24",
-    "@shrkcrft/workspace": "^0.1.0-alpha.24",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.24",
-    "@shrkcrft/context": "^0.1.0-alpha.24",
-    "@shrkcrft/rules": "^0.1.0-alpha.24",
-    "@shrkcrft/paths": "^0.1.0-alpha.24",
-    "@shrkcrft/templates": "^0.1.0-alpha.24",
-    "@shrkcrft/plugin-api": "^0.1.0-alpha.24",
-    "@shrkcrft/dashboard": "^0.1.0-alpha.24",
-    "@shrkcrft/dashboard-api": "^0.1.0-alpha.24",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.24",
-    "@shrkcrft/presets": "^0.1.0-alpha.24",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.24",
-    "@shrkcrft/graph": "^0.1.0-alpha.24",
-    "@shrkcrft/rule-graph": "^0.1.0-alpha.24",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.24",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.24",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.24",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.24",
-    "@shrkcrft/framework-scanners": "^0.1.0-alpha.24",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.24",
-    "@shrkcrft/quality-gates": "^0.1.0-alpha.24",
-    "@shrkcrft/migrate": "^0.1.0-alpha.24",
-    "@shrkcrft/generator": "^0.1.0-alpha.24",
-    "@shrkcrft/importer": "^0.1.0-alpha.24",
-    "@shrkcrft/inspector": "^0.1.0-alpha.24",
-    "@shrkcrft/ai": "^0.1.0-alpha.24",
-    "@shrkcrft/embeddings": "^0.1.0-alpha.24",
-    "@shrkcrft/shared": "^0.1.0-alpha.24",
-    "@shrkcrft/mcp-server": "^0.1.0-alpha.24",
+    "@shrkcrft/core": "^0.1.0-alpha.25",
+    "@shrkcrft/compress": "^0.1.0-alpha.25",
+    "@shrkcrft/config": "^0.1.0-alpha.25",
+    "@shrkcrft/workspace": "^0.1.0-alpha.25",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.25",
+    "@shrkcrft/context": "^0.1.0-alpha.25",
+    "@shrkcrft/rules": "^0.1.0-alpha.25",
+    "@shrkcrft/paths": "^0.1.0-alpha.25",
+    "@shrkcrft/templates": "^0.1.0-alpha.25",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.25",
+    "@shrkcrft/dashboard": "^0.1.0-alpha.25",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.25",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.25",
+    "@shrkcrft/presets": "^0.1.0-alpha.25",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.25",
+    "@shrkcrft/graph": "^0.1.0-alpha.25",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.25",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.25",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.25",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.25",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.25",
+    "@shrkcrft/framework-scanners": "^0.1.0-alpha.25",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.25",
+    "@shrkcrft/quality-gates": "^0.1.0-alpha.25",
+    "@shrkcrft/migrate": "^0.1.0-alpha.25",
+    "@shrkcrft/generator": "^0.1.0-alpha.25",
+    "@shrkcrft/importer": "^0.1.0-alpha.25",
+    "@shrkcrft/inspector": "^0.1.0-alpha.25",
+    "@shrkcrft/ai": "^0.1.0-alpha.25",
+    "@shrkcrft/embeddings": "^0.1.0-alpha.25",
+    "@shrkcrft/shared": "^0.1.0-alpha.25",
+    "@shrkcrft/mcp-server": "^0.1.0-alpha.25",
     "@huggingface/transformers": "^3.7.5"
   },
   "publishConfig": {