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

package/dist/commands/compress.command.js

@@ -38,6 +38,31 @@ function resolveContentType(raw) {
 // legitimately have nothing to compress). Above it, a silent `−0%` re-emit is
 // the opposite of the tool's purpose — nudge the user toward `--type`.
 const PASSTHROUGH_HINT_MIN_BYTES = 128;
+/**
+ * The no-win / passthrough test, shared by the `--json` envelope and the human
+ * text banner: a Passthrough strategy or a non-positive saving means the engine
+ * declined to compress and `compressed` is the verbatim original. Keeping it in
+ * one place is what makes the two output paths agree on fidelity.
+ */
+function isNoWin(result) {
+    return result.strategy === ECompressionStrategy.Passthrough || result.savings.saved <= 0;
+}
+/**
+ * The fidelity label for the human text path, mirroring the `fidelity` field
+ * the `--json` envelope surfaces: `passthrough` for a no-win re-emit, `lossy`
+ * for a reduction that drops detail (markdown line-omission or the code
+ * outline), and `lossless` otherwise. Same classification as `--json` — the
+ * text path just names the no-win case explicitly instead of via a separate
+ * `passthrough` boolean, so an agent reading stderr sees the fidelity at a
+ * glance.
+ */
+function textFidelity(result) {
+    if (isNoWin(result))
+        return 'passthrough';
+    if (result.strategy === ECompressionStrategy.Code || result.lossy)
+        return 'lossy';
+    return 'lossless';
+}
 function readInput(args) {
     const positional = args.positional[0];
     const useStdin = flagBool(args, 'stdin') || positional === undefined || positional === '-';
@@ -60,7 +85,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 +143,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,
@@ -126,7 +158,7 @@ export const compressCommand = {
             // VERBATIM original as `compressed`. Echoing it back inside the JSON
             // envelope (plus scaffold) costs more tokens than the input. Signal
             // passthrough and omit the duplicated content — the caller still has it.
-            const noWin = result.strategy === ECompressionStrategy.Passthrough || result.savings.saved <= 0;
+            const noWin = isNoWin(result);
             const payload = noWin
                 ? { ...base, passthrough: true, inputBytes: Buffer.byteLength(content, 'utf8') }
                 : { ...base, compressed: result.compressed };
@@ -136,6 +168,18 @@ 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 parity with `--json`: print the same classification the JSON
+        // envelope carries as a one-line banner so an agent reading only stderr can
+        // see the output was lossy — and see the no-win `passthrough` case named
+        // explicitly rather than inferred from a bare `−0%` ratio.
+        process.stderr.write(`fidelity: ${textFidelity(result)}\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/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":"AAcA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eAwNzB,CAAC"}

package/dist/commands/gate.command.js

@@ -1,4 +1,5 @@
 import { QualityGateReportStore, renderGateReportMarkdown, runQualityGates, } from '@shrkcrft/quality-gates';
+import { ArchReportStore, runArchCheck } from '@shrkcrft/architecture-guard';
 import { inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
@@ -19,7 +20,7 @@ import { asJson, header, kv } from "../output/format-output.js";
 export const gateCommand = {
     name: 'gate',
     description: 'Aggregator: runs the code-intelligence quality gates (graph freshness, architecture, impact-since-ref) and reports a single pass/fail.',
-    usage: 'shrk gate [--since <gitref>] [--changed-only] [--staged] [--files a,b,c] [--fail-on critical,high] [--arch-all] [--disable arch,impact,policy,knowledge-symbol,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         (the arch gate is baseline-relative once a baseline is frozen — fails only on NEW errors; with no baseline it warns on errors rather than going perpetually red — --arch-all fails on total, --strict escalates the warn)\n         (--changed-only / --staged / --files / --since scope the wiring + policy + knowledge-symbol gates to the changeset; they also drive the impact gate — --since diffs the gitref, the others analyze the changed-file set)\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]',
+    usage: 'shrk gate [--since <gitref>] [--changed-only] [--staged] [--files a,b,c] [--fail-on critical,high] [--arch-all] [--disable arch,impact,policy,knowledge-symbol,api-diff] [--api-baseline <path>] [--no-fail-on-breaking] [--strict] [--no-persist] [--json] [--markdown] [--output <path>]\n         (the arch gate is change-scoped once a baseline is frozen — a NEW error blocks only when the working diff vs HEAD touched its origin file; drift in untouched files is informational — --arch-all fails on total, --strict escalates the warn)\n         (--changed-only / --staged / --files / --since scope the wiring + policy + knowledge-symbol gates to the changeset; they also drive the impact gate — --since diffs the gitref, the others analyze the changed-file set)\n         shrk gate scaffold-ci [--provider github|generic] [--force] [--json]\n         shrk gate scaffold-hook [--provider husky|raw] [--force] [--json]\n         shrk gate baseline --refreeze [--json]  (operational reset: re-freeze the arch baseline to the current state — NOT the change-scoped gate)',
     async run(args) {
         if (args.positional[0] === 'scaffold-ci') {
             const sliced = { ...args, positional: args.positional.slice(1) };
@@ -29,6 +30,10 @@ export const gateCommand = {
             const sliced = { ...args, positional: args.positional.slice(1) };
             return runGateScaffoldHook(sliced);
         }
+        if (args.positional[0] === 'baseline') {
+            const sliced = { ...args, positional: args.positional.slice(1) };
+            return runGateBaseline(sliced);
+        }
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');
         const wantMarkdown = flagBool(args, 'markdown');
@@ -101,6 +106,17 @@ export const gateCommand = {
         const scopeOpts = wantChangedScope
             ? { changedOnly: true, changedFiles: changedFiles ?? [] }
             : {};
+        // §3.1 — the architecture gate's "NEW" is ALWAYS change-scoped: a NEW error
+        // means one introduced by the working change (diff vs HEAD), never drift
+        // against a frozen (possibly months-old) baseline in a file the change never
+        // touched. When an explicit scope flag is passed we reuse its resolution;
+        // otherwise we default to the worktree diff vs HEAD — empty in a clean tree,
+        // so pre-existing baseline drift stays informational and can't red the gate
+        // on its own. `--arch-all` (baselineRelative:false) ignores this and fails
+        // on total errors, keeping a clean-tree CI demand expressible.
+        const archChangedFiles = wantChangedScope
+            ? changedFiles ?? []
+            : resolveChangedFiles({ projectRoot: cwd, includeWorktree: true }).files;
         // Knowledge symbol-ref integrity needs the loaded knowledge entries. The
         // inspection is async, so we build it here and inject it; the gate stays
         // synchronous and resolves the code graph itself. Best-effort — a failed
@@ -116,7 +132,10 @@ export const gateCommand = {
         }
         const report = runQualityGates({
             projectRoot: cwd,
-            ...(archAll ? { arch: { baselineRelative: false } } : {}),
+            arch: {
+                ...(archAll ? { baselineRelative: false } : {}),
+                changedFiles: archChangedFiles,
+            },
             wiring: {
                 ...(configError
                     ? { configError }
@@ -143,7 +162,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.
@@ -395,3 +419,39 @@ async function runGateScaffoldCi(args) {
     process.stdout.write(`Scaffolded ${provider} CI runner → ${target}\n`);
     return 0;
 }
+/**
+ * `shrk gate baseline --refreeze` — deliberate operational reset that re-freezes
+ * the architecture baseline to the CURRENT state, absorbing accumulated drift so
+ * the informational "baseline drift" line resets to zero.
+ *
+ * This is an operational complement, NOT the gate itself: the gate's blocking
+ * verdict is change-scoped (a NEW error blocks only when the working diff touched
+ * its origin file), so a stale baseline never reds the gate on its own. Refreeze
+ * is only for tidying the informational drift line. It mirrors `shrk arch
+ * baseline write`.
+ */
+async function runGateBaseline(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const refreeze = flagBool(args, 'refreeze');
+    if (!refreeze) {
+        process.stderr.write('Usage: shrk gate baseline --refreeze [--json]\n' +
+            '  Re-freeze the architecture baseline to the current state (operational reset,\n' +
+            '  not the change-scoped gate). Equivalent to `shrk arch baseline write`.\n');
+        return 2;
+    }
+    const report = runArchCheck({ projectRoot: cwd });
+    if (report.diagnostics.some((d) => d.includes('code-graph store missing'))) {
+        process.stderr.write('Cannot refreeze — graph index missing. Run `shrk graph index` first.\n');
+        return 2;
+    }
+    const store = new ArchReportStore(cwd);
+    const snap = store.writeBaseline(report);
+    if (wantJson) {
+        process.stdout.write(asJson({ ok: true, wrote: store.baselinePath, baseline: snap }) + '\n');
+        return 0;
+    }
+    process.stdout.write(`Architecture baseline re-frozen → ${store.baselinePath}\n`);
+    process.stdout.write(kv('violations', `${snap.countsBySeverity.error} error, ${snap.countsBySeverity.warning} warning`) + '\n');
+    return 0;
+}

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;
     },
 };

package/dist/commands/graph-code-subverbs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAiE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAgLxH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkEtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2F1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+FtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwEtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2MvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiGvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}
+{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAiE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAgLxH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkFtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2F1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+FtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwEtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA2MvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+HtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgEpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiGvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}

package/dist/commands/graph-code-subverbs.js

@@ -285,7 +285,14 @@ export async function runGraphCycles(args) {
     const api = loadGuarded(() => GraphQueryApi.fromStore(cwd), wantJson);
     if (!api)
         return 1;
-    const allCycles = api.cycles();
+    // Type-only import edges (`import type`, `export type … from`) are erased at
+    // emit time, so they cannot cause a runtime cycle — excluded by default.
+    // `--include-type-edges` opts back in for auditing. The type-only-loop delta
+    // is reported as a non-blocking bucket.
+    const includeTypeEdges = flagBool(args, 'include-type-edges');
+    const allCycles = api.cycles({ includeTypeEdges });
+    const runtimeCycles = includeTypeEdges ? api.cycles() : allCycles;
+    const typeOnlyLoopCount = Math.max(0, api.cycles({ includeTypeEdges: true }).length - runtimeCycles.length);
     const filtered = allCycles.filter((c) => c.size >= minSize);
     const limited = filtered.slice(0, limit);
     if (wantJson) {
@@ -293,6 +300,8 @@ export async function runGraphCycles(args) {
             ok: true,
             total: filtered.length,
             truncated: filtered.length > limit,
+            includeTypeEdges,
+            typeOnlyLoopCount,
             cycles: limited.map((c) => ({
                 size: c.size,
                 paths: c.paths ?? c.nodeIds.map((id) => id.replace(/^file:/, '')),
@@ -302,8 +311,11 @@ export async function runGraphCycles(args) {
     }
     process.stdout.write(header('Graph cycles'));
     process.stdout.write(kv('total', String(filtered.length)) + '\n');
+    if (!includeTypeEdges && typeOnlyLoopCount > 0) {
+        process.stdout.write(kv('type-only loops', `${typeOnlyLoopCount} (excluded — compile-time only; --include-type-edges to audit)`) + '\n');
+    }
     if (filtered.length === 0) {
-        process.stdout.write('\nNo cycles in the file-import graph. ✓\n');
+        process.stdout.write(`\nNo ${includeTypeEdges ? '' : 'runtime '}cycles in the file-import graph. ✓\n`);
         return 0;
     }
     process.stdout.write(kv('shown', `${limited.length}/${filtered.length}`) + '\n');

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

@@ -1 +1 @@
-{"version":3,"file":"graph.command.d.ts","sourceRoot":"","sources":["../../src/commands/graph.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4BhC,eAAO,MAAM,YAAY,EAAE,eAuN1B,CAAC"}
+{"version":3,"file":"graph.command.d.ts","sourceRoot":"","sources":["../../src/commands/graph.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqFhC,eAAO,MAAM,YAAY,EAAE,eAqO1B,CAAC"}