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

package/dist/commands/reuse.command.js

@@ -20,33 +20,87 @@ 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?$/;
+/**
+ * Rank ALL primitives by the matcher's own score (descending; ties broken by
+ * symbol name so the order is deterministic), then return the top-`k` as scored
+ * did-you-mean suggestions. Pure — no graph, no IO — so it is directly
+ * unit-testable. When every candidate scores 0 (a nonsense intent that shares no
+ * term) the result is the alphabetically-first `k` primitives, each with
+ * `score: 0`; the caller states "no candidate shares any term" in that case
+ * rather than dumping the whole catalog.
+ */
+export function rankReuseSuggestions(primitives, tokens, k) {
+    const cap = Math.max(1, Math.floor(k));
+    return primitives
+        .map((p) => ({ p, detail: scorePrimitive(p, tokens) }))
+        .sort((a, b) => b.detail.score - a.detail.score || a.p.symbol.localeCompare(b.p.symbol))
+        .slice(0, cap)
+        .map(({ p, detail }) => ({
+        symbol: p.symbol,
+        score: detail.score,
+        confidence: tokens.length === 0 ? 0 : detail.matched.length / tokens.length,
+        matched: detail.matched,
+        roles: p.roles,
+    }));
+}
 export const reuseCommand = {
     name: 'reuse',
     description: 'Intent → the canonical primitive to reuse. Matches your intent against configured reusePrimitives[], then resolves the symbol in the code graph to its declaration, public import path, sibling exports, and real consumer files to copy. Deterministic; no AI.',
-    usage: 'shrk reuse "<what I want to build>" [--limit N] [--json]',
+    usage: 'shrk reuse "<what I want to build>" [--limit N] [--all] [--json]',
+    booleanFlags: new Set(['json', 'all']),
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');
-        const limit = flagNumber(args, 'limit') ?? 3;
+        const wantAll = flagBool(args, 'all');
+        // `--limit N` caps both the confident results (historic default 3) and the
+        // did-you-mean suggestion list. When omitted, suggestions default to 5 (a
+        // couple more than results — the point of a did-you-mean is a short menu).
+        const limitFlag = flagNumber(args, 'limit');
+        const limit = limitFlag ?? 3;
+        const suggestK = limitFlag ?? 5;
         const intent = args.positional.join(' ').trim();
         if (!intent) {
-            process.stderr.write('Usage: shrk reuse "<what I want to build>" [--limit N] [--json]\n');
+            process.stderr.write('Usage: shrk reuse "<what I want to build>" [--limit N] [--all] [--json]\n');
             return 2;
         }
         const loaded = await resolveProjectConfig(cwd);
@@ -82,28 +136,104 @@ 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;
+        // Zero keyword overlap: nothing matched at all. Rather than dump the entire
+        // declared catalog (dozens of lines an agent must re-read), rank ALL
+        // candidates and surface the nearest top-K by name — every score is 0 here,
+        // so this is an alphabetized short menu, stated as such. The full catalog is
+        // available only behind an explicit `--all`.
+        if (scored.length === 0) {
+            const suggestions = rankReuseSuggestions(primitives, tokens, suggestK);
+            const roles = [...new Set(primitives.flatMap((p) => p.roles))].sort();
+            if (wantJson) {
+                process.stdout.write(asJson({
+                    schema: 'sharkcraft.reuse/v1',
+                    intent,
+                    confident: false,
+                    results: [],
+                    suggestions,
+                    ...(wantAll ? { availableRoles: roles } : {}),
+                    ...planeJson,
+                }) + '\n');
+                return 0;
+            }
+            process.stdout.write(header(`Reuse: "${intent}"`));
+            if (wantAll) {
+                process.stdout.write('  No primitive matched — no candidate shares any term — showing full catalog:\n');
+                for (const r of roles.slice(0, 40))
+                    process.stdout.write(`    • ${r}\n`);
+            }
+            else {
+                process.stdout.write('  No strong match — no candidate shares any term with the intent.\n' +
+                    '  Nearest primitives (pass --all for the full catalog):\n');
+                for (const s of suggestions) {
+                    process.stdout.write(`    • ${s.symbol}  (score ${s.score}; roles: ${s.roles.join(', ') || '—'})\n`);
+                }
+            }
+            writePlaneNotes();
+            return 0;
+        }
+        // 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) {
+            // Rank the weakly-overlapping candidates (score > 0) and cap at K — never
+            // the whole catalog. `suggestions` and the legacy `didYouMean` alias carry
+            // the same scored rows; `--all` additionally dumps every declared role.
+            const suggestions = scored.slice(0, Math.max(1, suggestK)).map((x) => ({
+                symbol: x.p.symbol,
+                score: x.detail.score,
+                confidence: confidenceOf(x.detail.matched.length),
+                matched: x.detail.matched,
+                roles: x.p.roles,
+            }));
             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');
+                process.stdout.write(asJson({
+                    schema: 'sharkcraft.reuse/v1',
+                    intent,
+                    confident: false,
+                    results: [],
+                    suggestions,
+                    didYouMean: suggestions,
+                    ...(wantAll ? { availableRoles: roles } : {}),
+                    ...planeJson,
+                }) + '\n');
                 return 0;
             }
             process.stdout.write(header(`Reuse: "${intent}"`));
-            process.stdout.write('  No primitive matched. Available roles:\n');
-            for (const r of roles.slice(0, 40))
-                process.stdout.write(`    • ${r}\n`);
+            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 suggestions) {
+                process.stdout.write(`    • ${s.symbol}  (score ${s.score}, ${Math.round(s.confidence * 100)}% of intent; matched: ${s.matched.join(', ') || '—'})\n`);
+            }
+            if (wantAll) {
+                process.stdout.write('  Full catalog (all declared roles):\n');
+                for (const r of roles.slice(0, 40))
+                    process.stdout.write(`    • ${r}\n`);
+            }
             writePlaneNotes();
             return 0;
         }
-        const results = ranked.map(({ p, score }) => {
-            const r = { symbol: p.symbol, score, roles: p.roles, siblings: [], consumers: [] };
+        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 +271,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 +305,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 +324,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/exit-codes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The canonical exit-code contract for every gate / verify / check verb.
+ *
+ * alpha.24 and alpha.25 made the STDOUT verdicts honest ("not verified",
+ * "degraded", "0 rules evaluated", "this is not a pass") but left the exit
+ * code returning `0` over those same unverified paths. An agent almost never
+ * parses the banner — it chains `shrk <cmd> && <next>` on the *exit code*, so a
+ * `0` over a "not verified" result marches straight past the gate. This module
+ * is the single source of truth so a chained gate can finally tell apart
+ * "passed", "failed", and "never ran".
+ *
+ *   0  VerifiedPass  — checks ran over a NON-EMPTY scope and passed. Never
+ *                      returned when zero units were evaluated.
+ *   1  Failure       — checks ran and found violations.
+ *   2  NotVerified   — indeterminate: empty evaluation scope, degraded
+ *                      fallback, short-circuit, timeout, or "refused to run".
+ *                      Distinct from both pass and fail so a chain can branch
+ *                      on it (`|| handle-indeterminate`). This is also the
+ *                      code the CLI already uses for usage errors — both mean
+ *                      "did not produce a verified result".
+ *
+ * The `gen --typecheck` pre-write gate already refuses-to-nonzero rather than
+ * emit an unverified artifact; this generalizes that instinct across the gate
+ * surface, adding the third code so "unverified" is distinguishable from
+ * "broken".
+ */
+export declare enum ExitCode {
+    VerifiedPass = 0,
+    Failure = 1,
+    NotVerified = 2
+}
+/**
+ * Promote a NotVerified (`2`) exit into a Failure-class nonzero (`1`) when the
+ * caller opted into `--strict`. This is the one switch an agent flips to make a
+ * hard CI gate treat "unverified" as a failure. Any other code passes through
+ * unchanged (a real pass stays `0`, a real failure stays `1`). Applied globally
+ * in {@link runCli} after the handler returns, so every gate/verify verb honors
+ * `--strict` uniformly without threading the flag through each call site.
+ */
+export declare function promoteForStrict(code: number, strict: boolean): number;
+/**
+ * True when the argv carries a global `--strict` (bare or `--strict=<level>`).
+ * `--strict` is also an established per-command flag (e.g. `check --strict`,
+ * `doctor --strict=warnings`) whose local meaning is preserved — this global
+ * layer only adds the NotVerified→Failure promotion on top, and only affects a
+ * command that actually returned `2`.
+ */
+export declare function argvHasStrict(argv: readonly string[]): boolean;
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,oBAAY,QAAQ;IAClB,YAAY,IAAI;IAChB,OAAO,IAAI;IACX,WAAW,IAAI;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAGtE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM9D"}

package/dist/exit-codes.js

@@ -0,0 +1,61 @@
+/**
+ * The canonical exit-code contract for every gate / verify / check verb.
+ *
+ * alpha.24 and alpha.25 made the STDOUT verdicts honest ("not verified",
+ * "degraded", "0 rules evaluated", "this is not a pass") but left the exit
+ * code returning `0` over those same unverified paths. An agent almost never
+ * parses the banner — it chains `shrk <cmd> && <next>` on the *exit code*, so a
+ * `0` over a "not verified" result marches straight past the gate. This module
+ * is the single source of truth so a chained gate can finally tell apart
+ * "passed", "failed", and "never ran".
+ *
+ *   0  VerifiedPass  — checks ran over a NON-EMPTY scope and passed. Never
+ *                      returned when zero units were evaluated.
+ *   1  Failure       — checks ran and found violations.
+ *   2  NotVerified   — indeterminate: empty evaluation scope, degraded
+ *                      fallback, short-circuit, timeout, or "refused to run".
+ *                      Distinct from both pass and fail so a chain can branch
+ *                      on it (`|| handle-indeterminate`). This is also the
+ *                      code the CLI already uses for usage errors — both mean
+ *                      "did not produce a verified result".
+ *
+ * The `gen --typecheck` pre-write gate already refuses-to-nonzero rather than
+ * emit an unverified artifact; this generalizes that instinct across the gate
+ * surface, adding the third code so "unverified" is distinguishable from
+ * "broken".
+ */
+export var ExitCode;
+(function (ExitCode) {
+    ExitCode[ExitCode["VerifiedPass"] = 0] = "VerifiedPass";
+    ExitCode[ExitCode["Failure"] = 1] = "Failure";
+    ExitCode[ExitCode["NotVerified"] = 2] = "NotVerified";
+})(ExitCode || (ExitCode = {}));
+/**
+ * Promote a NotVerified (`2`) exit into a Failure-class nonzero (`1`) when the
+ * caller opted into `--strict`. This is the one switch an agent flips to make a
+ * hard CI gate treat "unverified" as a failure. Any other code passes through
+ * unchanged (a real pass stays `0`, a real failure stays `1`). Applied globally
+ * in {@link runCli} after the handler returns, so every gate/verify verb honors
+ * `--strict` uniformly without threading the flag through each call site.
+ */
+export function promoteForStrict(code, strict) {
+    if (strict && code === ExitCode.NotVerified)
+        return ExitCode.Failure;
+    return code;
+}
+/**
+ * True when the argv carries a global `--strict` (bare or `--strict=<level>`).
+ * `--strict` is also an established per-command flag (e.g. `check --strict`,
+ * `doctor --strict=warnings`) whose local meaning is preserved — this global
+ * layer only adds the NotVerified→Failure promotion on top, and only affects a
+ * command that actually returned `2`.
+ */
+export function argvHasStrict(argv) {
+    for (const t of argv) {
+        if (t === '--')
+            break;
+        if (t === '--strict' || t.startsWith('--strict='))
+            return true;
+    }
+    return false;
+}

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;AA8X/B,wBAAgB,aAAa,IAAI,eAAe,CAiY/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiCrE;AAqID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}

package/dist/main.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { loadDotenv } from "./env/load-dotenv.js";
 import { CommandRegistry, extractGlobalCompress, extractGlobalCwd, parseArgs, } from "./command-registry.js";
+import { argvHasStrict, promoteForStrict } from "./exit-codes.js";
 import { runCommandWithCompression } from "./output/output-compression.js";
 import { initCommand } from "./commands/init.command.js";
 import { inspectCommand } from "./commands/inspect.command.js";
@@ -73,6 +74,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 +251,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);
@@ -507,9 +510,15 @@ export function buildRegistry() {
 export async function runCli(argv) {
     const usageStart = performance.now();
     const { cwd: probeCwd, rest: probeArgv } = extractGlobalCwd(argv);
+    // Global `--strict` promotes a NotVerified (`2`) verdict to a Failure-class
+    // nonzero across every gate/verify verb — one switch to make an "unverified"
+    // result fail a hard CI gate. A real pass (`0`) or failure (`1`) is untouched,
+    // and each command's own `--strict` semantics (e.g. `check --strict`) still
+    // apply beneath this (a25 §1.1).
+    const strict = argvHasStrict(argv);
     let exitCode = 0;
     try {
-        exitCode = await runCliInner(argv);
+        exitCode = promoteForStrict(await runCliInner(argv), strict);
         return exitCode;
     }
     finally {
@@ -921,6 +930,22 @@ if (isMain ||
     // test). Commands that re-exec themselves in an isolated child gate on this
     // so unit tests calling `run()` in-process never spawn a subprocess.
     process.env.SHRK_CLI = '1';
+    // Global broken-pipe containment. When a downstream reader closes early
+    // (`shrk registry <name> list | head`, `… | grep`), Node raises `write EPIPE`
+    // on stdout from the async write/flush path — with no `error` listener that
+    // becomes an uncaught exception and a nonzero exit, forging a false failure on
+    // a happy-path query whose data was fine (a25 §2.2). Swallowing EPIPE here (a
+    // no-op listener) turns it back into a benign early-close: the command keeps
+    // its REAL exit code, and nothing is written to the dead pipe. Registered once
+    // at startup so every verb that streams a list is covered.
+    const swallowPipeError = (err) => {
+        if (err && err.code === 'EPIPE')
+            return;
+        // Any other stdio error (ENOSPC, …) is unrecoverable mid-write; there is
+        // nothing safe to print, so contain it rather than crash the shutdown path.
+    };
+    process.stdout.on('error', swallowPipeError);
+    process.stderr.on('error', swallowPipeError);
     loadDotenv(process.cwd());
     const argv = process.argv.slice(2);
     const cleanShutdown = async (code) => {

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