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

package/dist/commands/command-catalog.js

@@ -390,6 +390,14 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'check orphans',
+        description: 'Write-safety guard: after deleting file(s)/export(s), finds surviving files that still import them or reference a symbol they declared — alias-resolved, incl. barrel re-exports the type checker misses. Reverse-closure over the diff vs --since (or --staged) against the code-graph snapshot; each survivor reported with file:line. [--since <ref>] [--staged] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
     entry({
         command: 'policy-lint',
         description: 'Lint template/markup, stylesheet, and AOT-invisible TS surfaces against config-defined policyRules[] — sees `.html` files AND inline `template:` strings that tsc/AOT cannot. Deterministic; no AI. [--surface template|style|ts] [--changed-only] [--only <ids>] [--json]',
@@ -398,6 +406,46 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'wiring explain',
+        description: 'Dry-run ONE configured wiringRule and print the declared set + registered set it extracts (token + file:line), the alias-resolved set-difference, and the verdict — the author-loop view of what `check wiring` sees, without re-running the gate. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'wiring test',
+        description: 'Dry-run an EPHEMERAL candidate wiring rule (a .json file or inline JSON) against the live tree — see the declared/registered sets + diff it would produce before committing it to sharkcraft.config.ts. Never writes config. [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Explain,
+    }),
+    entry({
+        command: 'wiring chain',
+        description: 'Registration/DI graph query: the declared → provided → consumed chain of a token across files/layers, alias-resolved, with file:line at each hop + a verdict (wired / unprovided / orphan). Models runtime wiring imports can\'t see. Idioms from sharkcraft.config.ts registrationGraph[]. [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Inspect,
+    }),
+    entry({
+        command: 'wiring unprovided',
+        description: 'Registration/DI graph query: tokens DECLARED or INJECTED but never PROVIDED — the silent-at-runtime class (typecheck/AOT-green, resolves to undefined at runtime). The write-safety check imports/grep structurally can\'t do. [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Validate,
+    }),
+    entry({
+        command: 'wiring orphans',
+        description: 'Registration/DI graph query: tokens PROVIDED/registered that nothing CONSUMES — a build-clean dead registration (or a sign the consumer was renamed/removed). [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Inspect,
+    }),
     entry({
         command: 'reuse',
         description: 'Intent → the canonical primitive to reuse: matches your intent against config reusePrimitives[] then resolves the symbol through the code graph (transitive star-barrels) to its import path, sibling exports, and real consumer files to copy. Read-only; no AI.',
@@ -415,6 +463,14 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'finish',
+        description: 'Composite "is this changeset safe to finish?" gate: EXECUTES boundaries + import-hygiene + wiring + policy + deleted-orphans changed-only inline, plus an impact summary, and returns ONE pass/fail. The trustworthy "done?" call after editing — superset of diff-check; honors 0-rules→skipped. Read-only. [files… | --staged | --since <ref>] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        taskRole: CommandTaskRole.Validate,
+    }),
     entry({
         command: 'review',
         description: 'PR-review packet — changed files, affected rules, missing tests heuristic.',
@@ -1104,6 +1160,14 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.ReadOnly,
         surface: CommandSurface.Common,
     }),
+    entry({
+        command: 'changelog',
+        description: 'The shrk command-surface delta of the running build (added / changed / removed verbs & flags). `--since <version>` for the cumulative delta; offline, authoritative for this exact build.',
+        category: 'meta',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Common,
+        intendedAudience: [CommandAudience.Human, CommandAudience.Agent],
+    }),
     entry({
         command: 'completion',
         description: 'Print a sourcable shell-completion script for the `shrk` CLI (bash | zsh | fish). Pipe into your shell rc.',
@@ -1658,6 +1722,14 @@ export const COMMAND_CATALOG = Object.freeze([
         safetyLevel: SafetyLevel.ReadOnly,
         mcpAvailable: true,
     }),
+    entry({
+        command: 'trace literal',
+        description: 'Trace an EXACT string literal across the codebase, classified by direction: declare → register → consume sites of a cross-fence contract (kind slug, permission id, route key) the type system can\'t link and grep can\'t classify. Resolves `const X = "lit"` aliases. Generalizes `registry … where` to any literal — no pre-declared registry. [--glob <g>] [--no-aliases] [--limit N] [--json]',
+        category: 'analysis',
+        safetyLevel: SafetyLevel.ReadOnly,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Inspect,
+    }),
     entry({
         command: 'feedback',
         description: 'Feedback ingestion (ingest|summarize|actions|convert-to-backlog). Read-only.',
@@ -3664,6 +3736,7 @@ const PRIMARY_VERBS_ALLOWLIST = new Set([
     'gen',
     'apply',
     'check',
+    'finish',
     'quality',
     'plan',
     'fix',
@@ -3734,6 +3807,32 @@ export function defaultShowInHelp(e) {
     const surface = commandSurface(e);
     return surface === CommandSurface.Primary || surface === CommandSurface.Common;
 }
+/**
+ * The "explain / dry-run" command family: entries that show you what a gate,
+ * ranker, or graph *sees* before you act (`search tuning explain`, `wiring
+ * explain`/`wiring test`, `boundaries explain`, `surface explain`, …). Several
+ * carry an Advanced surface, so {@link defaultShowInHelp} hides them despite
+ * being high-value — which is exactly why an agent finds them only by guessing.
+ * `shrk --full-help` lists this family in a dedicated section so they stop
+ * being hidden. Returns callable entries only (retired/deprecated/alias and
+ * R46-pruned are excluded), sorted by command.
+ */
+export function listExplainFamily() {
+    return COMMAND_CATALOG.filter((e) => {
+        const lc = commandLifecycle(e);
+        if (lc === CommandLifecycle.Deprecated ||
+            lc === CommandLifecycle.Retired ||
+            lc === CommandLifecycle.Alias) {
+            return false;
+        }
+        if (R46_OVERLAY[e.command])
+            return false;
+        const role = commandTaskRole(e);
+        return role === CommandTaskRole.Explain || /(^|\s)explain$/.test(e.command);
+    })
+        .slice()
+        .sort((a, b) => a.command.localeCompare(b.command));
+}
 /**
  * Short "Use this when…" line derived from `surface`, `taskRole`,
  * `preferredCommand`, `replacedBy`, and `machineOnly`. Empty string when

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

@@ -1 +1 @@
-{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqEhC,eAAO,MAAM,eAAe,EAAE,eAoG7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}
+{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqEhC,eAAO,MAAM,eAAe,EAAE,eAqH7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}

package/dist/commands/compress.command.js

@@ -60,7 +60,7 @@ const COMPRESS_BOOLEAN_FLAGS = new Set([
 ]);
 export const compressCommand = {
     name: 'compress',
-    description: 'Compress a blob (file or stdin) deterministically to cut tokens — JSON→table, logs/search/diffs→signal. Reversible via `shrk expand`.',
+    description: 'Compress a blob (file or stdin) deterministically to cut tokens — JSON→table, logs/search/diffs→signal. Reversible via `shrk expand`. NOTE: `--type code` emits a LOSSY outline (function bodies elided) — good for fitting more code into context, NOT for line-accurate reading; use plain Read (or `--lossless`) to inspect a file.',
     usage: 'shrk [--cwd <dir>] compress [<file>|-] [--stdin] [--type <content-type>] [--query <text>] [--max <n>] [--lossless] [--no-cache] [--json]',
     booleanFlags: COMPRESS_BOOLEAN_FLAGS,
     run(args) {
@@ -118,6 +118,13 @@ export const compressCommand = {
                 tokensSaved: result.savings.saved,
                 savedRatio: result.savings.ratio,
                 tokensAreEstimated: true,
+                // Explicit fidelity signal so a caller never mistakes a lossy code
+                // outline for a line-accurate read.
+                fidelity: result.strategy === ECompressionStrategy.Code
+                    ? 'lossy-outline (not line-accurate; use Read or --lossless to inspect)'
+                    : result.lossy
+                        ? 'lossy'
+                        : 'lossless',
                 queryApplied,
                 ccrKey: result.ccrKey ?? null,
                 note: result.note,
@@ -136,6 +143,13 @@ export const compressCommand = {
         process.stdout.write(result.compressed + '\n');
         const cached = result.ccrKey ? ` · original cached as ${result.ccrKey} (shrk expand ${result.ccrKey})` : '';
         process.stderr.write(`${result.strategy}: ~${result.savings.before} → ~${result.savings.after} tokens (−${pct}%, est.)${cached}\n`);
+        // Fidelity banner: the code outline elides function bodies, so it is a
+        // footgun as a cheaper Read. Say so loudly — same failure mode as a lossy
+        // result that doesn't *look* lossy.
+        if (result.strategy === ECompressionStrategy.Code) {
+            process.stderr.write('note: code outline is LOSSY (bodies elided) — for bulk context, not line-accurate reading; ' +
+                'use `Read` or `--lossless` for inspection.\n');
+        }
         // Token-economy guard: when auto-detect declines to compress a non-trivial
         // input, a silent `−0%` re-emit looks like success. Nudge toward `--type`
         // (stdout stays the verbatim blob; exit code unchanged).

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

@@ -1 +1 @@
-{"version":3,"file":"constructs.command.d.ts","sourceRoot":"","sources":["../../src/commands/constructs.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkHhC,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAoDlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAiGpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA0ErC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAmCtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA4BpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAkClC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAkBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA4BrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA8BrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0DpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0LpC,CAAC"}
+{"version":3,"file":"constructs.command.d.ts","sourceRoot":"","sources":["../../src/commands/constructs.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkKhC,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmDlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAgGpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAyErC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAkCtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA2BpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAiClC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAkBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA2BrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA8BrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0DpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0LpC,CAAC"}

package/dist/commands/constructs.command.js

@@ -4,6 +4,48 @@ import { AdoptionCheckpointStatus, buildConstructAdoptionDiff, buildConstructAdo
 import { GraphQueryApi, GraphStore } from '@shrkcrft/graph';
 import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+/**
+ * A construct subverb was handed an id that is NOT a registered construct.
+ * `constructs *` matches a curated construct-registry ID, not a raw code symbol
+ * — so a miss must never read as an existence claim about the symbol. Probe the
+ * code graph and redirect to the tools that actually answer "where does X live /
+ * who calls it" instead of a definitive-sounding "No construct". Returns exit 1.
+ */
+function emitConstructMiss(id, args) {
+    const cwd = resolveCwd(args);
+    const store = new GraphStore(cwd);
+    let isCodeSymbol = false;
+    if (store.exists()) {
+        const api = GraphQueryApi.fromStore(cwd);
+        isCodeSymbol =
+            api.findSymbol(id, { exact: true }).length > 0 ||
+                api.findSymbol(id, { exact: false, limit: 1 }).length > 0;
+    }
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({
+            schema: 'sharkcraft.constructs-miss/v1',
+            id,
+            found: false,
+            reason: 'not-a-construct-id',
+            isCodeSymbol,
+            hint: isCodeSymbol
+                ? `"${id}" is a code symbol, not a construct — try 'shrk graph callers ${id}' or 'shrk graph search ${id}'.`
+                : `"${id}" is not a registered construct ID; list them with 'shrk constructs list', or search code with 'shrk graph search ${id}'.`,
+        }) + '\n');
+        return 1;
+    }
+    if (isCodeSymbol) {
+        process.stderr.write(`"${id}" is not a construct ID — did you mean a code symbol?\n` +
+            `  shrk graph callers ${id}    # who references it (path:line)\n` +
+            `  shrk graph search ${id}     # find its declaration\n`);
+    }
+    else {
+        process.stderr.write(`"${id}" is not a registered construct ID, and no code symbol by that name was found.\n` +
+            `  shrk constructs list        # the curated construct IDs\n` +
+            `  shrk graph search ${id}     # search the code graph\n`);
+    }
+    return 1;
+}
 async function loadAll(args) {
     const cwd = resolveCwd(args);
     const inspection = await inspectSharkcraft({ cwd });
@@ -116,8 +158,7 @@ export const constructsGetCommand = {
         const { constructs } = await loadAll(args);
         const c = constructs.find((x) => x.id === id);
         if (!c) {
-            process.stderr.write(`No construct "${id}"\n`);
-            return 1;
+            return emitConstructMiss(id, args);
         }
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(c) + '\n');
@@ -175,8 +216,7 @@ export const constructsTraceCommand = {
         const { constructs } = await loadAll(args);
         const c = constructs.find((x) => x.id === id);
         if (!c) {
-            process.stderr.write(`No construct "${id}"\n`);
-            return 1;
+            return emitConstructMiss(id, args);
         }
         const trace = traceConstruct(c);
         const deep = flagBool(args, 'deep');
@@ -274,8 +314,7 @@ export const constructsImpactCommand = {
         const { constructs, inspection } = await loadAll(args);
         const c = constructs.find((x) => x.id === id);
         if (!c) {
-            process.stderr.write(`No construct "${id}"\n`);
-            return 1;
+            return emitConstructMiss(id, args);
         }
         const trace = traceConstruct(c);
         /**
@@ -352,8 +391,7 @@ export const constructsRelatedCommand = {
         const { constructs } = await loadAll(args);
         const c = constructs.find((x) => x.id === id);
         if (!c) {
-            process.stderr.write(`No construct "${id}"\n`);
-            return 1;
+            return emitConstructMiss(id, args);
         }
         const related = [
             ...(c.relatedKnowledge ?? []).map((id) => ({ kind: 'knowledge', id })),
@@ -389,8 +427,7 @@ export const constructsFilesCommand = {
         const { constructs } = await loadAll(args);
         const c = constructs.find((x) => x.id === id);
         if (!c) {
-            process.stderr.write(`No construct "${id}"\n`);
-            return 1;
+            return emitConstructMiss(id, args);
         }
         const trace = traceConstruct(c);
         // Emit the graph-resolved files (globs expanded), not the raw declared
@@ -419,8 +456,7 @@ export const constructsApiCommand = {
         const { constructs } = await loadAll(args);
         const c = constructs.find((x) => x.id === id);
         if (!c) {
-            process.stderr.write(`No construct "${id}"\n`);
-            return 1;
+            return emitConstructMiss(id, args);
         }
         const publicApi = c.publicApi ?? [];
         if (flagBool(args, 'json')) {
@@ -493,8 +529,7 @@ export const constructsFacetsCommand = {
         const { constructs } = await loadAll(args);
         const c = constructs.find((x) => x.id === id);
         if (!c) {
-            process.stderr.write(`No construct "${id}"\n`);
-            return 1;
+            return emitConstructMiss(id, args);
         }
         const facets = c.facets ?? {};
         if (flagBool(args, 'json')) {

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

@@ -1 +1 @@
-{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,cAAc,EAAE,eA2I5B,CAAC"}
+{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0ChC,eAAO,MAAM,cAAc,EAAE,eA8I5B,CAAC"}

package/dist/commands/context.command.js

@@ -6,6 +6,15 @@ import * as nodePath from 'node:path';
 import { buildUniversalSearch, explainTaskRouting, recommendCommands, renderOverviewText, buildProjectOverview, } from '@shrkcrft/inspector';
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+/**
+ * Budget used for the DEFAULT full human-text orientation view when the caller
+ * set no explicit `--max-tokens`. Orientation is the cheap-first step an agent
+ * uses to form its initial model of the project — it must not silently drop the
+ * body of the richest sections (architecture, conventions, paths, workflows) the
+ * way a tight budget would. Large enough to hold every planned section; explicit
+ * `--max-tokens` and JSON/`--summary` callers still get the configured budget.
+ */
+const WIDE_CONTEXT_BUDGET = 100_000;
 /**
  * Minimal JSON shape for agent / skill consumption — the context-side mirror
  * of `shrk task --compact`. Drops the heavy `body` and `request` echo and
@@ -65,8 +74,19 @@ export const contextCommand = {
         const noPaths = flagBool(args, 'no-paths');
         const includeDocs = flagBool(args, 'include-docs');
         const includeCommands = flagBool(args, 'include-commands');
+        // Orientation renders the FULL body by default now (parity with why / reuse
+        // / knowledge get). `--summary`/`--brief` opts back into the terse view.
+        const wantsSummary = flagBool(args, 'summary') || flagBool(args, 'brief');
+        const wantsJsonOut = flagBool(args, 'json') || flagBool(args, 'machine-json');
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const overview = buildProjectOverview(inspection.workspace, inspection.config?.projectName);
+        // Auto-widen the budget for the default full human view so no requested
+        // section is dropped purely to fit a tight budget. Explicit `--max-tokens`,
+        // JSON, and summary callers keep the configured budget.
+        const effectiveMaxTokens = maxTokens ??
+            (!wantsJsonOut && !wantsSummary
+                ? WIDE_CONTEXT_BUDGET
+                : (inspection.config?.defaultMaxTokens ?? 3000));
         const contextBoost = contextTuningBoostFor(inspection, task);
         const result = buildContext(inspection.knowledgeEntries, {
             task,
@@ -74,7 +94,7 @@ export const contextCommand = {
             area,
             tags,
             scope,
-            maxTokens: maxTokens ?? inspection.config?.defaultMaxTokens ?? 3000,
+            maxTokens: effectiveMaxTokens,
             includeExamples: !noExamples,
             includeTemplates: !noTemplates,
             includeRules: !noRules,
@@ -84,14 +104,10 @@ export const contextCommand = {
             projectOverview: renderOverviewText(overview),
             ...(contextBoost ? { boostFor: contextBoost } : {}),
         });
-        // Surface top commands prominently before the long context body.
-        // Auto-promote commands-first for action-like tasks (rename / add /
-        // fix / refactor / remove / migrate / explore / wire). Pass --full to
-        // see the long context body anyway.
-        const actionVerbRe = /^(rename|add|fix|refactor|remove|delete|migrate|wire|explore|create|implement|update|introduce|build|extract|move|inline|generate|scaffold)\b/i;
-        const isActionLike = actionVerbRe.test(task.trim());
-        const wantsFull = flagBool(args, 'full');
-        const commandsFirst = flagBool(args, 'commands-first') || (isActionLike && !wantsFull);
+        // Surface top commands prominently before the long context body. The body
+        // itself now prints by default (parity with sibling orientation verbs);
+        // `--commands-first` keeps the terse commands-only view for action tasks.
+        const commandsOnly = flagBool(args, 'commands-first');
         let commandRecommendations = null;
         let routingMatches = [];
         let searchReport = null;
@@ -141,16 +157,12 @@ export const contextCommand = {
                 process.stdout.write(`  • ${m.hint.id}  ${m.hint.title}\n`);
             }
         }
-        // Default human text mode keeps the output short. The long
-        // context body is one flag away via `--full`. JSON / commands-first /
-        // markdown paths are unchanged.
-        if (commandsFirst || !wantsFull) {
-            if (!wantsFull) {
-                process.stdout.write('\n(text mode is summary-only — pass --full for the long context body, --json for machine output.)\n');
-            }
-            else if (isActionLike && !flagBool(args, 'commands-first')) {
-                process.stdout.write('\n(action-like task → commands-first; pass --full to see the long context body.)\n');
-            }
+        // The full context body prints by default now — parity with why / reuse /
+        // knowledge get, so the agent's first read of the project isn't thinner than
+        // every adjacent command. `--summary`/`--brief` (or `--commands-first`) opts
+        // back into the terse view.
+        if (wantsSummary || commandsOnly) {
+            process.stdout.write('\n(summary mode — omit --summary for the full context body, --json for machine output.)\n');
             return 0;
         }
         process.stdout.write('\n');

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

@@ -0,0 +1,3 @@
+import { type ICommandHandler } from '../command-registry.js';
+export declare const finishCommand: ICommandHandler;
+//# sourceMappingURL=finish.command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"finish.command.d.ts","sourceRoot":"","sources":["../../src/commands/finish.command.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA8DhC,eAAO,MAAM,aAAa,EAAE,eAmB3B,CAAC"}

package/dist/commands/finish.command.js

@@ -0,0 +1,70 @@
+import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { asJson, bullet, header, kv } from "../output/format-output.js";
+import { runFinishGates } from "../finish/run-finish.js";
+function resolveScope(args, cwd) {
+    const staged = flagBool(args, 'staged');
+    const since = flagString(args, 'since');
+    const filesRaw = flagString(args, 'files');
+    const files = filesRaw
+        ? filesRaw.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
+        : args.positional.filter((s) => s.length > 0);
+    if (files.length > 0)
+        return { mode: 'files', options: { projectRoot: cwd, files } };
+    if (staged)
+        return { mode: 'staged', options: { projectRoot: cwd, staged: true } };
+    if (since)
+        return { mode: 'since', options: { projectRoot: cwd, since } };
+    return { mode: 'worktree', options: { projectRoot: cwd, includeWorktree: true } };
+}
+const STATUS_GLYPH = {
+    pass: '✓',
+    fail: '✗',
+    skipped: '–',
+};
+function renderText(report) {
+    process.stdout.write(header('Finish — is this changeset safe to complete?'));
+    process.stdout.write(kv('scope', `${report.scope.mode} (${report.scope.fileCount} file${report.scope.fileCount === 1 ? '' : 's'})`) +
+        '\n');
+    for (const g of report.gates) {
+        process.stdout.write(`  ${STATUS_GLYPH[g.status]} ${g.name.padEnd(11)} ${g.status.padEnd(8)} ${g.detail}\n`);
+    }
+    if (report.impact.ran) {
+        process.stdout.write(kv('impact', `risk=${report.impact.risk}, ${report.impact.directDependents} direct / ${report.impact.transitiveDependents} transitive dependents`) +
+            '\n');
+    }
+    else if (report.impact.note) {
+        process.stdout.write(kv('impact', `(skipped — ${report.impact.note})`) + '\n');
+    }
+    process.stdout.write(kv('verdict', report.verdict) + '\n\n');
+    process.stdout.write(report.summary + '\n');
+    const failing = report.gates.filter((g) => g.status === 'fail');
+    for (const g of failing) {
+        process.stdout.write(`\n${g.name} — failing items:\n`);
+        for (const item of g.items.slice(0, 15)) {
+            const loc = item.file ? `${item.file}${item.line ? `:${item.line}` : ''}` : '';
+            process.stdout.write(bullet(`${loc ? loc + ' — ' : ''}${item.message}`) + '\n');
+        }
+        if (g.items.length > 15) {
+            process.stdout.write(`  … and ${g.items.length - 15} more (pass --json for the full list).\n`);
+        }
+    }
+    process.stdout.write(`\nNext: ${report.nextAction}\n`);
+}
+export const finishCommand = {
+    name: 'finish',
+    description: 'Composite "is this changeset safe to finish?" gate: EXECUTES every deterministic changed-only check inline — boundaries + import-hygiene + wiring + policy + deleted-orphans — plus an impact summary, and returns ONE pass/fail. The single trustworthy "done?" call after editing (superset of `diff-check`; honors 0-rules→skipped). Read-only.',
+    usage: 'shrk [--cwd <dir>] finish [files... | --files a.ts,b.ts | --staged | --since <ref>] [--json]',
+    booleanFlags: new Set(['json', 'staged']),
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const wantJson = flagBool(args, 'json');
+        const { mode, options } = resolveScope(args, cwd);
+        const report = await runFinishGates({ cwd, mode, scope: options });
+        if (wantJson) {
+            process.stdout.write(asJson(report) + '\n');
+            return report.verdict === 'fail' ? 1 : 0;
+        }
+        renderText(report);
+        return report.verdict === 'fail' ? 1 : 0;
+    },
+};

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

@@ -1 +1 @@
-{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eAiMzB,CAAC"}
+{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eAsMzB,CAAC"}

package/dist/commands/gate.command.js

@@ -143,7 +143,12 @@ export const gateCommand = {
                 : {}),
             impact: {
                 ...(sinceRef ? { sinceRef } : {}),
-                ...(failOn ? { failOn } : {}),
+                // Blast-radius risk is inherently PRE-EXISTING structure (touching a hub
+                // is risky but not a new failure this change introduced), so the composite
+                // gate treats it as ADVISORY by default — `failOn: []` warns instead of
+                // redding, keeping the verdict change-attributable. `--fail-on critical`
+                // opts into a hard fail; `--strict` escalates the advisory warn.
+                failOn: failOn ?? [],
                 // Scope the impact gate to the changeset too: with `--since` we keep the
                 // gitref diff; with `--changed-only` / `--staged` / `--files` (and no
                 // `--since`) we analyze the resolved changed-file set directly.

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

@@ -1 +1 @@
-{"version":3,"file":"gen.command.d.ts","sourceRoot":"","sources":["../../src/commands/gen.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkBhC,eAAO,MAAM,UAAU,EAAE,eA+JxB,CAAC"}
+{"version":3,"file":"gen.command.d.ts","sourceRoot":"","sources":["../../src/commands/gen.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAuBhC,eAAO,MAAM,UAAU,EAAE,eAsNxB,CAAC"}

package/dist/commands/gen.command.js

@@ -1,8 +1,10 @@
 import { inspectSharkcraft } from '@shrkcrft/inspector';
 import { buildSavedPlan, FileChangeType, generate, OverwriteStrategy, savePlanToFile, signPlan, } from '@shrkcrft/generator';
 import { flagBool, flagString, flagVars, resolveCwd, } from "../command-registry.js";
+import * as nodePath from 'node:path';
 import { asJson, header } from "../output/format-output.js";
 import { printError } from "../output/print-error.js";
+import { typecheckEmittedFiles, } from "../validation/typecheck-emitted.js";
 const CHANGE_LABEL = {
     [FileChangeType.Create]: 'CREATE',
     [FileChangeType.Update]: 'UPDATE',
@@ -19,7 +21,7 @@ const CHANGE_LABEL = {
 export const genCommand = {
     name: 'gen',
     description: 'Generate code from a template. Defaults to dry-run.',
-    usage: 'shrk gen <templateId> [<name>] [--var key=value ...] [--dry-run] [--write] [--force] [--save-plan <file>] [--show-content] [--json]',
+    usage: 'shrk gen <templateId> [<name>] [--var key=value ...] [--dry-run] [--write] [--force] [--save-plan <file>] [--print|--show-content] [--typecheck] [--json]\n         (--typecheck compiles the emitted files against the detected tsconfig BEFORE apply — a template bug fails here, not at the human next build; --print shows the rendered bodies)',
     async run(args) {
         const templateId = args.positional[0];
         const name = args.positional[1];
@@ -40,19 +42,50 @@ export const genCommand = {
             : flagString(args, 'overwrite') ?? OverwriteStrategy.Never;
         const variables = flagVars(args);
         const savePlanPath = flagString(args, 'save-plan');
-        const result = generate(template, {
+        const wantTypecheck = flagBool(args, 'typecheck');
+        const genOpts = {
             templateId: template.id,
             name,
             variables,
             projectRoot: inspection.projectRoot,
             overwriteStrategy: overwrite,
-            write,
-        });
+        };
+        // --typecheck is a PRE-WRITE gate. Render a dry-run FIRST, compile the emitted
+        // (full-file create) TS/TSX against the detected tsconfig in memory, and only
+        // proceed to write if they compile — so an agent driving gen→apply never lands
+        // non-compiling code. On failure the write is refused (nothing touches disk).
+        // Only whole-file creates are checkable standalone (update ops are fragments).
+        let typecheckResult;
+        let effectiveWrite = write;
+        let result;
+        if (wantTypecheck) {
+            const dry = generate(template, { ...genOpts, write: false });
+            if (!dry.ok) {
+                printError(dry.error);
+                return 1;
+            }
+            const emitted = dry.value.plan.changes
+                .filter((c) => c.type === FileChangeType.Create)
+                .map((c) => ({
+                absPath: nodePath.resolve(inspection.projectRoot, c.relativePath),
+                contents: c.contents ?? '',
+            }))
+                .filter((f) => f.contents.length > 0 && /\.tsx?$/.test(f.absPath));
+            typecheckResult = typecheckEmittedFiles(inspection.projectRoot, emitted);
+            // Refuse to write non-compiling output — the whole point of the gate.
+            effectiveWrite = write && typecheckResult.errors.length === 0;
+            result = effectiveWrite ? generate(template, { ...genOpts, write: true }) : dry;
+        }
+        else {
+            result = generate(template, { ...genOpts, write });
+        }
         if (!result.ok) {
             printError(result.error);
             return 1;
         }
         const { plan, summary, written } = result.value;
+        const typecheckFailed = (typecheckResult?.errors.length ?? 0) > 0;
+        const writeRefused = write && typecheckFailed;
         // --save-plan is allowed regardless of write/dry-run, but we refuse to
         // save plans that have conflicts (since `shrk apply` would refuse them too).
         if (savePlanPath) {
@@ -89,10 +122,12 @@ export const genCommand = {
                 summary,
                 written: written.map((w) => w.relativePath),
                 savedPlanPath: savePlanPath ?? null,
+                ...(typecheckResult ? { typecheck: typecheckResult } : {}),
+                ...(writeRefused ? { writeRefused: true } : {}),
             }) + '\n');
-            return plan.hasConflicts ? 1 : 0;
+            return plan.hasConflicts || typecheckFailed ? 1 : 0;
         }
-        process.stdout.write(header(write ? `Generation: ${template.id}` : `Dry-run: ${template.id}`));
+        process.stdout.write(header(effectiveWrite ? `Generation: ${template.id}` : `Dry-run: ${template.id}`));
         if (plan.warnings.length) {
             process.stdout.write('Warnings:\n');
             for (const w of plan.warnings)
@@ -118,7 +153,7 @@ export const genCommand = {
         // agent can review what a template would generate WITHOUT writing to disk
         // (the saved plan stays content-free). The bytes are identical in dry-run
         // and --write; this is purely additive.
-        if (flagBool(args, 'show-content')) {
+        if (flagBool(args, 'show-content') || flagBool(args, 'print')) {
             process.stdout.write('\nVirtual content (not written to disk):\n');
             for (const change of plan.changes) {
                 const body = change.contents ?? '';
@@ -139,10 +174,31 @@ export const genCommand = {
         if (updateLike.length > 0) {
             process.stdout.write(`\nHUMAN REVIEW REQUIRED — ${updateLike.length} update entry/entries modify existing files.\n`);
         }
+        if (typecheckResult) {
+            if (!typecheckResult.ran) {
+                process.stdout.write(`\nTypecheck: skipped — ${typecheckResult.note ?? 'nothing to check'}.\n`);
+            }
+            else if (typecheckResult.errors.length === 0) {
+                process.stdout.write('\nTypecheck: ✓ emitted files compile against the detected tsconfig.\n');
+            }
+            else {
+                process.stdout.write(`\nTypecheck: ✗ ${typecheckResult.errors.length} error(s) in the emitted files — a template bug (NOT applied):\n`);
+                for (const e of typecheckResult.errors.slice(0, 30)) {
+                    const rel = nodePath.relative(inspection.projectRoot, e.file) || e.file;
+                    process.stdout.write(`  ${rel}:${e.line}:${e.column}  ${e.message}\n`);
+                }
+                if (typecheckResult.errors.length > 30) {
+                    process.stdout.write(`  … (${typecheckResult.errors.length - 30} more)\n`);
+                }
+                if (writeRefused) {
+                    process.stdout.write('\nWrite REFUSED — the emitted files do not typecheck (nothing written). Fix the template, then re-run.\n');
+                }
+            }
+        }
         process.stdout.write(`\nSummary: written=${summary.written}, skipped=${summary.skipped}, conflicts=${summary.conflicts}\n`);
-        if (!write && !savePlanPath) {
+        if (!effectiveWrite && !savePlanPath && !writeRefused) {
             process.stdout.write('\nRe-run with --write to apply, or --save-plan <file> + `shrk apply`.\n');
         }
-        return plan.hasConflicts ? 1 : 0;
+        return plan.hasConflicts || typecheckFailed ? 1 : 0;
     },
 };