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

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,EAAqD,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AA+J5G,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,CA0MvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HtE;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,CAkGvE;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

@@ -12,7 +12,7 @@ import { FrameworkQueryApi, FrameworkStore } from '@shrkcrft/framework-scanners'
 import { existsSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { compactArrayToColumnar } from '@shrkcrft/compress';
-import { flagBool, flagPositiveInt, flagString, resolveCwd } from "../command-registry.js";
+import { flagBool, flagNumber, flagPositiveInt, flagString, resolveCwd } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
 /**
@@ -67,6 +67,24 @@ const CORRUPT_HINT = 'code graph store is corrupt — run `shrk graph index` to
  * runGraphCallers). Kept in sync with the MCP `get_graph_context` tool.
  */
 const CONTEXT_LIST_CAP = 50;
+/**
+ * Resolve a `--limit N` per-list cap for the graph read commands. Absent → the
+ * command's `fallback` (the historical default — 50 for `context`, 200 for
+ * `callers`/`impact`); `--limit 0` (or any non-positive) → unbounded so a
+ * consumer can pull the full set off a high-fan-in barrel/hub in one call.
+ * Returns `Infinity` for the unbounded case: `arr.slice(0, Infinity)` yields
+ * every row and `len > Infinity` is `false`, so the `<list>Truncated` flag stays
+ * honest (never "truncated" when nothing was dropped). Malformed `--limit abc`
+ * (NaN) degrades to `fallback`, matching `flagPositiveInt`.
+ */
+function resolveListLimit(args, fallback) {
+    const v = flagNumber(args, 'limit');
+    if (v === undefined)
+        return fallback;
+    if (v <= 0)
+        return Number.POSITIVE_INFINITY;
+    return Math.floor(v);
+}
 /**
  * Refresh-by-default: incrementally reindex changed/deleted files BEFORE
  * querying so an agent's just-saved edits are reflected, then print a one-line
@@ -267,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) {
@@ -275,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:/, '')),
@@ -284,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');
@@ -659,10 +689,11 @@ export async function runGraphContext(args) {
     const wantJson = flagBool(args, 'json');
     const target = args.positional[1];
     if (!target) {
-        process.stderr.write('Usage: shrk graph context <fileOrSymbol> [--depth N] [--no-bridge] [--no-framework]\n');
+        process.stderr.write('Usage: shrk graph context <fileOrSymbol> [--depth N] [--limit N|0] [--no-bridge] [--no-framework]\n');
         return 2;
     }
     const depth = Math.min(3, flagPositiveInt(args, 'depth', 1));
+    const cap = resolveListLimit(args, CONTEXT_LIST_CAP);
     const includeBridge = !flagBool(args, 'no-bridge');
     const includeFramework = !flagBool(args, 'no-framework');
     maybeRefresh(args, cwd);
@@ -708,13 +739,13 @@ export async function runGraphContext(args) {
     const importsFromAll = neighbours.out.filter((o) => o.edge.kind === 'imports-file');
     const importedByAll = neighbours.in.filter((i) => i.edge.kind === 'imports-file');
     const importsFromList = importsFromAll
-        .slice(0, CONTEXT_LIST_CAP)
+        .slice(0, cap)
         .map((o) => ('target' in o ? targetSummary(o.target) : { id: 'unknown', resolved: false }));
     const importedByList = importedByAll
-        .slice(0, CONTEXT_LIST_CAP)
+        .slice(0, cap)
         .map((i) => ('source' in i ? sourceSummary(i.source) : { id: 'unknown', resolved: false }));
-    const referencedByList = references.slice(0, CONTEXT_LIST_CAP).map(nodeSummary);
-    const calledByList = callers.slice(0, CONTEXT_LIST_CAP).map(nodeSummary);
+    const referencedByList = references.slice(0, cap).map(nodeSummary);
+    const calledByList = callers.slice(0, cap).map(nodeSummary);
     // Staleness over the anchor + every referenced file: drop dead paths from the
     // usage lists, flag changed ones.
     const ctxPathOf = (x) => x.path;
@@ -733,19 +764,19 @@ export async function runGraphContext(args) {
         depth,
         importsFrom: ctxDropDel(importsFromList),
         totalImportsFrom: importsFromAll.length,
-        importsFromTruncated: importsFromAll.length > CONTEXT_LIST_CAP,
+        importsFromTruncated: importsFromAll.length > cap,
         importedBy: ctxDropDel(importedByList),
         totalImportedBy: importedByAll.length,
-        importedByTruncated: importedByAll.length > CONTEXT_LIST_CAP,
-        symbols: symbols.slice(0, 50).map(nodeSummary),
+        importedByTruncated: importedByAll.length > cap,
+        symbols: symbols.slice(0, cap).map(nodeSummary),
         referencedBy: ctxDropDel(referencedByList),
         totalReferencedBy: references.length,
-        referencedByTruncated: references.length > CONTEXT_LIST_CAP,
+        referencedByTruncated: references.length > cap,
         calledBy: ctxDropDel(calledByList),
         totalCalledBy: callers.length,
-        calledByTruncated: callers.length > CONTEXT_LIST_CAP,
-        ...(subtypes.length > 0 ? { subtypes: subtypes.slice(0, 50).map(nodeSummary) } : {}),
-        ...(supertypes.length > 0 ? { supertypes: supertypes.slice(0, 50).map(nodeSummary) } : {}),
+        calledByTruncated: callers.length > cap,
+        ...(subtypes.length > 0 ? { subtypes: subtypes.slice(0, cap).map(nodeSummary) } : {}),
+        ...(supertypes.length > 0 ? { supertypes: supertypes.slice(0, cap).map(nodeSummary) } : {}),
         ...(fresh.field ?? {}),
         bridge: bridgeFor
             ? {
@@ -860,11 +891,11 @@ export async function runGraphImpact(args) {
     const wantFull = flagBool(args, 'full');
     const target = args.positional[1];
     if (!target) {
-        process.stderr.write('Usage: shrk graph impact <fileOrSymbol> [--max-depth N] [--limit N] [--full]\n');
+        process.stderr.write('Usage: shrk graph impact <fileOrSymbol> [--max-depth N] [--limit N|0] [--full]\n');
         return 2;
     }
     const maxDepth = Math.min(10, flagPositiveInt(args, 'max-depth', 5));
-    const limit = flagPositiveInt(args, 'limit', 200);
+    const limit = resolveListLimit(args, 200);
     maybeRefresh(args, cwd);
     // --full → delegate to the impact-engine for a richer v3 payload.
     if (wantFull) {
@@ -949,7 +980,8 @@ export async function runGraphImpact(args) {
         schema: 'sharkcraft.graph-impact/v1',
         anchor: nodeSummary(anchor),
         maxDepth,
-        limit,
+        // 0 signals "unbounded" (`--limit 0`); JSON can't carry Infinity.
+        limit: Number.isFinite(limit) ? limit : 0,
         truncated: closure.truncated,
         directDependents: liveDirect,
         transitiveDependents: liveTransitive,
@@ -1052,16 +1084,15 @@ export async function runGraphCallers(args) {
     const wantJson = flagBool(args, 'json');
     const target = args.positional[1];
     if (!target) {
-        process.stderr.write('Usage: shrk graph callers <symbol> [--mode call|reference] [--limit N] [--no-refresh]\n');
+        process.stderr.write('Usage: shrk graph callers <symbol> [--mode call|reference] [--limit N|0] [--no-refresh]\n');
         return 2;
     }
     const mode = (flagString(args, 'mode') ?? 'call');
-    // --limit N: cap the returned call sites (default 200). `total` still reports
-    // the true uncapped count, so a truncated result stays honest. Guard against
-    // non-numeric input — `Number('foo')` is NaN and `slice(0, NaN)` would zero
-    // the callers list while `total` kept showing the real count.
-    const parsedLimit = Number.parseInt(flagString(args, 'limit') ?? '200', 10);
-    const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 200;
+    // --limit N: cap the returned call sites (default 200; `--limit 0` = all).
+    // `total` still reports the true uncapped count, so a truncated result stays
+    // honest. resolveListLimit guards non-numeric input (NaN → fallback) so a
+    // fat-fingered `--limit foo` can't zero the list via `slice(0, NaN)`.
+    const limit = resolveListLimit(args, 200);
     maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)

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

@@ -1 +1 @@
-{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAqB9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwC1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EA2HpF"}
+{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AA4B9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwC1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EAwIpF"}

package/dist/commands/help.command.js

@@ -1,5 +1,11 @@
 import { header } from "../output/format-output.js";
-import { COMMAND_CATALOG, defaultShowInHelp } from "./command-catalog.js";
+import { COMMAND_CATALOG, defaultShowInHelp, listExplainFamily } from "./command-catalog.js";
+/** First sentence of a catalog description, for the compact explain-family list. */
+function firstSentence(description) {
+    const dot = description.indexOf('. ');
+    const head = dot > 0 ? description.slice(0, dot + 1) : description;
+    return head.length > 100 ? head.slice(0, 97).trimEnd() + '…' : head;
+}
 const EXTRA_HELP_LINES = Object.freeze({
     graph: [
         '',
@@ -60,7 +66,7 @@ export function renderStartScreen() {
     lines.push('Discover the rest (everything stays callable — this screen shows ~17 of ~70 verbs):');
     lines.push('  $ shrk surface list              — full catalog by tier');
     lines.push('  $ shrk help <command>            — usage for a specific command');
-    lines.push('  $ shrk --full-help               — long, exhaustive help');
+    lines.push('  $ shrk --full-help               — long, exhaustive help (incl. the explain/dry-run family)');
     lines.push('  $ shrk --about                   — what shrk is and is not');
     lines.push('');
     lines.push('Free-form input is fine — `shrk "<task>"` routes to `shrk recommend`.');
@@ -188,6 +194,18 @@ export function makeHelpCommand(registry) {
                     process.stdout.write(`  ${group} ${s.name.padEnd(10)} — ${s.description}\n`);
                 }
             }
+            // Explain / dry-run family — several carry an Advanced surface and are
+            // filtered out of the listings above, so surface them explicitly. These
+            // show you what a gate, ranker, or graph SEES before you act; an agent
+            // would otherwise find them only by guessing (the #4.4 friction).
+            const explainFamily = listExplainFamily();
+            if (explainFamily.length > 0) {
+                process.stdout.write(header('Inspect / explain (dry-run what a gate, ranker, or graph sees)'));
+                for (const e of explainFamily) {
+                    process.stdout.write(`  ${e.command.padEnd(24)} — ${firstSentence(e.description)}\n`);
+                }
+                process.stdout.write('  (also: shrk check wiring --explain <ruleId>)\n');
+            }
             process.stdout.write('\nRun `shrk help <command>` for detailed usage.\n');
             return 0;
         },

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

@@ -1 +1 @@
-{"version":3,"file":"impact.command.d.ts","sourceRoot":"","sources":["../../src/commands/impact.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAibhC,eAAO,MAAM,aAAa,EAAE,eAsW3B,CAAC"}
+{"version":3,"file":"impact.command.d.ts","sourceRoot":"","sources":["../../src/commands/impact.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2ahC,eAAO,MAAM,aAAa,EAAE,eAsW3B,CAAC"}

package/dist/commands/impact.command.js

@@ -4,7 +4,7 @@ import { analyzeImpact, analyzeTestImpact, findSymbolInProject, FuzzyImpactSourc
 import { flagBool, flagNumber, flagString, flagList, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { fuzzyImpactAmbiguousHints, renderFailureHints } from "../output/failure-hints.js";
-import { collectChangedPaths } from "../diff/collect-changed-paths.js";
+import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
 function collectFiles(args, cwd) {
     const diagnostics = [];
     const explicitFiles = flagList(args, 'files');
@@ -297,17 +297,24 @@ async function runDeletedOrphans(args) {
     const cwd = resolveCwd(args);
     const wantJson = flagBool(args, 'json') || flagString(args, 'format') === 'json';
     const sinceRef = flagString(args, 'since');
-    const changed = collectChangedPaths({ cwd, ...(sinceRef ? { ref: sinceRef } : {}) });
-    if (!changed.isAvailable) {
+    const staged = flagBool(args, 'staged');
+    const scan = await computeDeletedOrphans(cwd, {
+        ...(sinceRef ? { since: sinceRef } : {}),
+        ...(staged ? { staged: true } : {}),
+    });
+    if (!scan.ok) {
         if (wantJson) {
-            process.stdout.write(asJson({ ok: false, error: changed.error }) + '\n');
+            process.stdout.write(asJson({ ok: false, error: scan.error }) + '\n');
+        }
+        else if (scan.reason === 'diff-unavailable') {
+            process.stderr.write(`Cannot resolve diff: ${scan.error ?? 'unknown'}\n`);
         }
         else {
-            process.stderr.write(`Cannot resolve diff: ${changed.error ?? 'unknown'}\n`);
+            process.stderr.write(`${scan.error ?? 'orphan check unavailable'}\n`);
         }
         return 2;
     }
-    const deleted = changed.deleted;
+    const deleted = scan.deleted;
     if (deleted.length === 0) {
         if (wantJson) {
             process.stdout.write(asJson({
@@ -315,33 +322,21 @@ async function runDeletedOrphans(args) {
                 resolvedDeleted: [],
                 unresolvedDeleted: [],
                 orphans: [],
-                diagnostics: [`no deleted files in diff vs ${changed.ref}`],
+                diagnostics: [`no deleted files in diff vs ${scan.ref}`],
             }) + '\n');
             return 0;
         }
         process.stdout.write(header('Deleted-symbol orphans'));
-        process.stdout.write(`No deleted files in diff vs ${changed.ref}.\n`);
+        process.stdout.write(`No deleted files in diff vs ${scan.ref}.\n`);
         return 0;
     }
-    const { GraphStore, GraphQueryApi } = await import('@shrkcrft/graph');
-    if (!new GraphStore(cwd).exists()) {
-        const msg = 'code-graph store missing — run `shrk graph index` first.';
-        if (wantJson) {
-            process.stdout.write(asJson({ ok: false, error: msg }) + '\n');
-        }
-        else {
-            process.stderr.write(msg + '\n');
-        }
-        return 2;
-    }
-    const { findDeletedOrphans } = await import('@shrkcrft/impact-engine');
-    const report = findDeletedOrphans(GraphQueryApi.fromStore(cwd), deleted);
+    const report = scan.report;
     if (wantJson) {
         process.stdout.write(asJson(report) + '\n');
         return report.orphans.length > 0 ? 1 : 0;
     }
     process.stdout.write(header('Deleted-symbol orphans'));
-    process.stdout.write(`Deleted files (vs ${changed.ref}): ${deleted.length}\n`);
+    process.stdout.write(`Deleted files (vs ${scan.ref}): ${deleted.length}\n`);
     if (report.orphans.length === 0) {
         process.stdout.write('no orphaned importers\n');
         for (const d of report.diagnostics.slice(0, 5))

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