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

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

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/policy-lint.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy-lint.command.d.ts","sourceRoot":"","sources":["../../src/commands/policy-lint.command.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,iBAAiB,EAAE,eAkJ/B,CAAC"}
+{"version":3,"file":"policy-lint.command.d.ts","sourceRoot":"","sources":["../../src/commands/policy-lint.command.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,iBAAiB,EAAE,eA6L/B,CAAC"}

package/dist/commands/policy-lint.command.js

@@ -1,17 +1,21 @@
 import * as nodePath from 'node:path';
 import { runPolicyLint } from '@shrkcrft/boundaries';
-import { resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
+import { classifyChangedScope, resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 const VALID_SURFACES = new Set(['template', 'style', 'ts']);
 export const policyLintCommand = {
     name: 'policy-lint',
     description: 'Lint template/markup, stylesheet, and AOT-invisible TS surfaces against data-defined policyRules[] (e.g. flag raw markup when a primitive exists). Sees `.html` files AND inline `template:` strings — surfaces tsc/AOT cannot. Deterministic; no AI.',
-    usage: 'shrk [--cwd <dir>] policy-lint [--surface template|style|ts] [--changed-only] [--since <ref>] [--only <ids>] [--json]',
+    usage: 'shrk [--cwd <dir>] policy-lint [--surface template|style|ts] [--changed-only] [--new-only] [--since <ref>] [--only <ids>] [--json]\n         (--changed-only SCANS just the changed files; --new-only scans the whole tree but shows only findings the change introduced, hiding pre-existing baseline debt)',
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');
         const changedOnly = flagBool(args, 'changed-only');
+        // --new-only: scan the WHOLE tree, then show only findings the current change
+        // introduced (baseline debt is bucketed as hidden, not printed) — the
+        // finding-level complement to --changed-only's file-level scoping.
+        const newOnly = flagBool(args, 'new-only');
         const since = flagString(args, 'since');
         const only = flagString(args, 'only');
         const surfaceRaw = flagString(args, 'surface');
@@ -60,11 +64,11 @@ export const policyLintCommand = {
             }
         }
         let changedFiles;
-        if (changedOnly || since) {
+        if (changedOnly || newOnly || since) {
             changedFiles = resolveChangedFiles({
                 projectRoot: cwd,
                 ...(since ? { since } : {}),
-                ...(changedOnly && !since ? { includeWorktree: true } : {}),
+                ...((changedOnly || newOnly) && !since ? { includeWorktree: true } : {}),
             }).files;
         }
         // Don't lint SharkCraft's own asset/config dir by default (its .ts files
@@ -73,17 +77,46 @@ export const policyLintCommand = {
         const excludeDirs = sharkcraftRel && !sharkcraftRel.startsWith('..') ? [sharkcraftRel] : [];
         const reportRaw = runPolicyLint(cwd, rules, {
             ...(surfaces ? { surfaces } : {}),
-            ...(changedOnly || since ? { changedOnly: true, changedFiles: changedFiles ?? [] } : {}),
+            // --changed-only narrows the SCAN; --new-only scans the full tree so it can
+            // still diff findings (it filters after, below).
+            ...((changedOnly || since) && !newOnly ? { changedOnly: true, changedFiles: changedFiles ?? [] } : {}),
             ...(only ? { only: only.split(',').map((s) => s.trim()).filter(Boolean) } : {}),
             ...(excludeDirs.length > 0 ? { excludeDirs } : {}),
         });
         // Surface pack-plane merge notes (missing/invalid pack policy files, dropped
         // collisions) in the same diagnostics array the engine already emits.
-        const report = planeDiagnostics.length > 0
+        let report = planeDiagnostics.length > 0
             ? { ...reportRaw, diagnostics: [...reportRaw.diagnostics, ...planeDiagnostics] }
             : reportRaw;
+        // --new-only: partition the full-tree findings against the changed set and
+        // keep only the ones the current change introduced; pre-existing baseline
+        // debt is bucketed as hidden (reported as a count, never printed as green).
+        let hiddenBaseline = 0;
+        if (newOnly) {
+            const keyOf = (f) => `${f.ruleId}|${f.file}:${f.line}|${f.match}`;
+            const classification = classifyChangedScope({
+                projectRoot: cwd,
+                current: report.findings.map((f) => ({
+                    key: keyOf(f),
+                    file: f.file,
+                    code: f.ruleId,
+                    severity: f.severity,
+                    message: f.message,
+                })),
+                changedFiles: changedFiles ?? [],
+            });
+            const newKeys = new Set(classification.newIssues.map((n) => n.key));
+            const newFindings = report.findings.filter((f) => newKeys.has(keyOf(f)));
+            hiddenBaseline = report.findings.length - newFindings.length;
+            const verdict = newFindings.some((f) => f.severity === 'error')
+                ? 'errors'
+                : newFindings.length > 0
+                    ? report.verdict
+                    : 'pass';
+            report = { ...report, findings: newFindings, verdict };
+        }
         if (wantJson) {
-            process.stdout.write(asJson(report) + '\n');
+            process.stdout.write(asJson({ ...report, ...(newOnly ? { newOnly: true, hiddenBaseline } : {}) }) + '\n');
             return report.verdict === 'errors' ? 1 : 0;
         }
         process.stdout.write(header('Policy lint'));
@@ -99,13 +132,18 @@ export const policyLintCommand = {
         const errors = report.findings.filter((f) => f.severity === 'error').length;
         const warnings = report.findings.filter((f) => f.severity === 'warning').length;
         process.stdout.write(kv('findings', `${errors} error(s), ${warnings} warning(s)`) + '\n');
+        if (newOnly) {
+            process.stdout.write(kv('scope', `new-only (${hiddenBaseline} pre-existing finding(s) hidden — run without --new-only to see all)`) + '\n');
+        }
         if (report.diagnostics.length > 0) {
             process.stdout.write('\nMisconfigured rules:\n');
             for (const d of report.diagnostics)
                 process.stdout.write(`  ! ${d}\n`);
         }
         if (report.findings.length === 0 && report.diagnostics.length === 0) {
-            process.stdout.write('\nNo policy violations on the scanned surfaces. ✓\n');
+            process.stdout.write(newOnly
+                ? `\nNo NEW policy violations from this change${hiddenBaseline > 0 ? ` (${hiddenBaseline} pre-existing hidden)` : ''}. ✓\n`
+                : '\nNo policy violations on the scanned surfaces. ✓\n');
             return 0;
         }
         // Group findings by rule.

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

@@ -1 +1 @@
-{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AAwBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,wBAAwB,EAAE,eAetC,CAAC;AAsGF,eAAO,MAAM,eAAe,EAAE,eAuB7B,CAAC"}
+{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AA4BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,wBAAwB,EAAE,eAsCtC,CAAC;AAsIF,eAAO,MAAM,eAAe,EAAE,eA4B7B,CAAC"}

package/dist/commands/registry.command.js

@@ -4,30 +4,57 @@
  *   shrk registry lifecycle [--json]            # register/remove symmetry
  *   shrk registry <name> list [--json]          # every declared id
  *   shrk registry <name> exists <id> [--json]   # is the id taken? (exit 1 if not)
+ *       [--resolve]                             #   map a synonym → canonical id first
+ *       [--fail-if-taken]                       #   guard: non-zero when taken (free → 0)
+ *       [--fail-if-missing]                     #   guard: non-zero when NOT registered
  *   shrk registry <name> where <id> [--json]    # declaration (+ consumer) sites
  *
  * `<name>` resolves a `registries[]` declaration in sharkcraft.config.ts — one
  * deterministic multi-root scan that answers "is this id taken / where is it"
  * without an agent re-running a fragile grep.
  */
-import { buildRegistryLifecycleReport, renderRegistryLifecycleReportText, resolveProjectConfig, } from '@shrkcrft/inspector';
+import { buildRegistryLifecycleReport, renderRegistryLifecycleReportText, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
 import { scanRegistry, registryExists, registryWhere, } from '@shrkcrft/boundaries';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson } from "../output/format-output.js";
 export const registryLifecycleCommand = {
     name: 'lifecycle',
     description: 'Scan the workspace for register/remove symmetry. Read-only.',
-    usage: 'shrk registry lifecycle [--scope <dir>] [--json]',
+    usage: 'shrk registry lifecycle [--scope <dir>] [--changed-only] [--since <ref>] [--json]',
     async run(args) {
         const cwd = resolveCwd(args);
         const scope = flagString(args, 'scope');
-        const report = buildRegistryLifecycleReport({ projectRoot: cwd, ...(scope ? { scope } : {}) });
+        const changedOnly = flagBool(args, 'changed-only');
+        const since = flagString(args, 'since');
+        let files;
+        if (changedOnly || since) {
+            const changed = resolveChangedFiles({
+                projectRoot: cwd,
+                ...(since ? { since } : {}),
+                ...(changedOnly && !since ? { includeWorktree: true } : {}),
+            });
+            files = changed.files;
+        }
+        // Full-tree walk honors the project's skipDirs override.
+        let skipDirs;
+        if (files === undefined) {
+            const loaded = await resolveProjectConfig(cwd);
+            if (loaded.ok)
+                skipDirs = loaded.value.config.registryLifecycle?.skipDirs;
+        }
+        const report = buildRegistryLifecycleReport({
+            projectRoot: cwd,
+            ...(files !== undefined ? { files } : {}),
+            ...(scope ? { scope } : {}),
+            ...(skipDirs ? { skipDirs } : {}),
+        });
+        const exit = report.timedOut ? 2 : report.missingRemovers.length === 0 ? 0 : 1;
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson(report) + '\n');
-            return report.missingRemovers.length === 0 ? 0 : 1;
+            return exit;
         }
         process.stdout.write(renderRegistryLifecycleReportText(report));
-        return report.missingRemovers.length === 0 ? 0 : 1;
+        return exit;
     },
 };
 async function loadRegistries(cwd) {
@@ -87,15 +114,42 @@ async function runRegistryInventory(args, name) {
     }
     if (action === 'exists') {
         if (!id) {
-            process.stderr.write(`Usage: shrk registry ${name} exists <id>\n`);
+            process.stderr.write(`Usage: shrk registry ${name} exists <id> [--resolve] [--fail-if-taken|--fail-if-missing]\n`);
             return 2;
         }
-        const exists = registryExists(inventory, id);
-        if (json)
-            process.stdout.write(asJson({ name: inventory.name, id, exists }) + '\n');
-        else
-            process.stdout.write(`${exists ? 'yes' : 'no'} — "${id}" is ${exists ? 'declared' : 'NOT declared'} in registry "${inventory.name}".\n`);
-        return exists ? 0 : 1;
+        const failIfTaken = flagBool(args, 'fail-if-taken');
+        const failIfMissing = flagBool(args, 'fail-if-missing');
+        if (failIfTaken && failIfMissing) {
+            process.stderr.write('Pass at most one of --fail-if-taken / --fail-if-missing.\n');
+            return 2;
+        }
+        // `--resolve` maps a human noun to the canonical registered id via the
+        // registry's `aliases` map before the existence test — so a duplicate guard
+        // can't return a false "free" on a synonym of an already-taken slug.
+        const doResolve = flagBool(args, 'resolve');
+        const canonical = doResolve ? (decl.aliases?.[id] ?? id) : id;
+        const resolved = canonical !== id;
+        const exists = registryExists(inventory, canonical);
+        // Exit-code convention:
+        //   --fail-if-taken   → non-zero when the id is already registered (free → 0),
+        //                       so `exists <id> --fail-if-taken && <author>` is a natural guard.
+        //   --fail-if-missing → non-zero when the id is NOT registered (the consume-side check).
+        //   neither           → the historical query convention (taken → 0, free → 1).
+        const code = failIfTaken ? (exists ? 1 : 0) : exists ? 0 : 1;
+        if (json) {
+            process.stdout.write(asJson({
+                name: inventory.name,
+                id,
+                ...(resolved ? { resolvedId: canonical } : {}),
+                exists,
+                exitCode: code,
+            }) + '\n');
+            return code;
+        }
+        if (resolved)
+            process.stdout.write(`resolved "${id}" → "${canonical}" (alias)\n`);
+        process.stdout.write(`${exists ? 'yes' : 'no'} — "${canonical}" is ${exists ? 'declared' : 'NOT declared'} in registry "${inventory.name}".\n`);
+        return code;
     }
     if (action === 'where') {
         if (!id) {
@@ -124,7 +178,11 @@ async function runRegistryInventory(args, name) {
 export const registryCommand = {
     name: 'registry',
     description: 'Registry inspections: lifecycle symmetry + declared-registry inventory. Read-only.',
-    usage: 'shrk registry lifecycle | <name> list | <name> exists <id> | <name> where <id>',
+    usage: 'shrk registry lifecycle | <name> list | <name> exists <id> [--resolve] [--fail-if-taken|--fail-if-missing] | <name> where <id>',
+    // Guard-mode + query flags take no value — declare them so `exists <id>
+    // --fail-if-taken` (flag last) and `exists --resolve <id>` (flag first) both
+    // keep the id as a positional instead of swallowing it.
+    booleanFlags: new Set(['json', 'resolve', 'fail-if-taken', 'fail-if-missing']),
     async run(args) {
         const sub = args.positional[0];
         if (sub === 'lifecycle') {

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

@@ -1 +1 @@
-{"version":3,"file":"reuse.command.d.ts","sourceRoot":"","sources":["../../src/commands/reuse.command.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4DhC,eAAO,MAAM,YAAY,EAAE,eAqK1B,CAAC"}
+{"version":3,"file":"reuse.command.d.ts","sourceRoot":"","sources":["../../src/commands/reuse.command.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2GhC,eAAO,MAAM,YAAY,EAAE,eA0N1B,CAAC"}