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

package/dist/commands/changelog-data.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Machine-readable command-SURFACE delta, shipped inside the binary so
+ * `shrk changelog` is authoritative for the exact build in use and works
+ * offline. This is NOT the full human CHANGELOG.md — it records only the delta
+ * an agent needs to re-orient after an upgrade: which verbs/flags were added,
+ * which changed behavior, which were removed. Keep it in sync with CHANGELOG.md
+ * when a release lands; the version keys must match `SHARKCRAFT_VERSION`.
+ *
+ * Ordered oldest → newest; the renderer sorts as needed.
+ */
+/** One version's command-surface delta. */
+export interface IReleaseSurfaceDelta {
+    /** Exact release version, e.g. `0.1.0-alpha.24`. */
+    readonly version: string;
+    /** One-line headline for the release. */
+    readonly title: string;
+    /** New verbs / flags this version introduced. */
+    readonly added: readonly string[];
+    /** Verbs / flags whose behavior or defaults changed. */
+    readonly changed: readonly string[];
+    /** Verbs / flags removed or renamed away. */
+    readonly removed: readonly string[];
+}
+export declare const RELEASE_SURFACE_DELTAS: readonly IReleaseSurfaceDelta[];
+//# sourceMappingURL=changelog-data.d.ts.map

package/dist/commands/changelog-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog-data.d.ts","sourceRoot":"","sources":["../../src/commands/changelog-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,oBAAoB,EA2DjE,CAAC"}

package/dist/commands/changelog-data.js

@@ -0,0 +1,70 @@
+/**
+ * Machine-readable command-SURFACE delta, shipped inside the binary so
+ * `shrk changelog` is authoritative for the exact build in use and works
+ * offline. This is NOT the full human CHANGELOG.md — it records only the delta
+ * an agent needs to re-orient after an upgrade: which verbs/flags were added,
+ * which changed behavior, which were removed. Keep it in sync with CHANGELOG.md
+ * when a release lands; the version keys must match `SHARKCRAFT_VERSION`.
+ *
+ * Ordered oldest → newest; the renderer sorts as needed.
+ */
+export const RELEASE_SURFACE_DELTAS = [
+    {
+        version: '0.1.0-alpha.23',
+        title: 'Correctness, gate trust, security & pack-distributable invariants',
+        added: [
+            '`shrk registry <name> list | exists <id> | where <id>` — declarable registry inventory (pack-distributable).',
+            '`shrk policy run --changed-only` / `--since` — finding-diff-scoped policy runs.',
+            '`shrk search tuning explain` — why a query ranked the way it did.',
+        ],
+        changed: [
+            '`graph context`/`search`/`callers`/`impact` report a true `total` + `truncated` instead of a silent per-file cap.',
+            'Incremental reindex no longer drops inbound edges; renamed barrel re-exports (`export { X as Y }`) now resolve.',
+        ],
+        removed: [],
+    },
+    {
+        version: '0.1.0-alpha.24',
+        title: 'Runtime wiring, write-safety & the author loop',
+        added: [
+            '`shrk wiring chain | unprovided | orphans` — the registration/DI graph beside the import graph.',
+            '`shrk wiring test <candidate>` / `shrk check wiring --explain <ruleId>` — declared vs registered set, no config write.',
+            '`shrk trace "<literal>"` — generalize registry tracing to any cross-layer string contract.',
+            '`shrk check orphans [--since <ref>] [--staged]` — first-class diff-robust reverse-closure.',
+            '`shrk finish` (a.k.a. `review --run`) — one changed-only "safe to finish?" verdict.',
+            '`--limit N` (`--limit 0` = all) on graph read commands (default 50).',
+        ],
+        changed: [
+            '`shrk impact --deleted` no longer ENOBUFS — the git diff is streamed via a shared `runGitLines`.',
+            'Pack-health scores quality (resolved cross-refs, runnable verification), not mere presence.',
+            '`compress --type code` is a real strategy (was markdown-only).',
+        ],
+        removed: [],
+    },
+    {
+        version: '0.1.0-alpha.25',
+        title: 'Earned & change-attributable verdicts',
+        added: [
+            '`shrk changelog [--since <version>] [--all] [--json]` — the command-surface delta of the running build.',
+            '`shrk registry <name> exists <id> --fail-if-taken | --fail-if-missing` — guard-mode exit codes for pre-author checks.',
+            '`shrk registry <name> exists <id> --resolve` — map a synonym to the canonical id (registry `aliases`) before the test.',
+            '`shrk check registry-lifecycle --changed-only` — diff-scoped lifecycle check that terminates in seconds.',
+            '`shrk gen --typecheck` — compile the emitted file set against the detected tsconfig as a PRE-WRITE gate (a template bug fails at generation and REFUSES the write; nothing lands on disk).',
+            '`shrk gen --print` — inspect the rendered file bodies in one step (alias of `--show-content`).',
+            '`shrk graph cycles --include-type-edges` — opt back into counting type-only import edges.',
+            '`shrk context` / `shrk task --summary` (`--brief`) — the terse orientation view (now opt-in).',
+        ],
+        changed: [
+            '`shrk check wiring --changed-only` never renders a green verdict over 0 evaluated rules; reports `M of N (K skipped)`.',
+            '`shrk check registry-lifecycle` no longer hangs — bounded scan + wall-clock budget + partial-result flush; skip-dirs are configurable via `registryLifecycle.skipDirs`.',
+            'Cycle detection excludes type-only import edges by default (clears phantom architecture reds).',
+            '`shrk gate` is change-scoped by default — reds only on change-introduced findings; baseline debt is a non-blocking bucket.',
+            '`shrk context` / `shrk task` render the FULL body by default (parity with why/reuse/knowledge get).',
+            '`shrk reuse` applies a confidence floor (weak keyword collisions → did-you-mean, score exposed) and shows the consumer total.',
+            '`compress --type code` labels its lossy fidelity (banner + JSON `fidelity`).',
+            '`changes summary` attributes areas from the declared layer/area taxonomy instead of bucketing to `unknown`.',
+            '`smart-context "<task>"` accepts `--task`, and fails loud (banner) when the local model is degraded instead of returning a stale guide dump.',
+        ],
+        removed: [],
+    },
+];

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.command.d.ts","sourceRoot":"","sources":["../../src/commands/changelog.command.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4ChC,eAAO,MAAM,gBAAgB,EAAE,eA4D9B,CAAC"}

package/dist/commands/changelog.command.js

@@ -0,0 +1,100 @@
+import { SHARKCRAFT_VERSION } from '@shrkcrft/shared';
+import { flagBool, flagString, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+import { RELEASE_SURFACE_DELTAS } from "./changelog-data.js";
+/** Parse `X.Y.Z[-alpha.N]` into a comparable tuple. A release outranks its prerelease. */
+function parseVersion(v) {
+    const [coreStr, preStr] = v.replace(/^v/, '').split('-');
+    const parts = (coreStr ?? '').split('.').map((n) => Number(n) || 0);
+    const core = [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+    // No prerelease sorts ABOVE any prerelease of the same core; a prerelease
+    // sorts by its trailing number (alpha.24 < alpha.25).
+    let pre = Number.POSITIVE_INFINITY;
+    if (preStr) {
+        const m = preStr.match(/(\d+)/);
+        pre = m ? Number(m[1]) : 0;
+    }
+    return { core, pre };
+}
+/** -1 / 0 / 1 comparator over version strings. */
+function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    for (let i = 0; i < 3; i += 1) {
+        const d = (pa.core[i] ?? 0) - (pb.core[i] ?? 0);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    if (pa.pre === pb.pre)
+        return 0;
+    return pa.pre < pb.pre ? -1 : 1;
+}
+function renderDeltaText(d) {
+    const lines = [`\n${d.version} — ${d.title}`];
+    const section = (label, items) => {
+        if (items.length === 0)
+            return;
+        lines.push(`  ${label}:`);
+        for (const it of items)
+            lines.push(`    • ${it}`);
+    };
+    section('Added', d.added);
+    section('Changed', d.changed);
+    section('Removed', d.removed);
+    return lines.join('\n') + '\n';
+}
+export const changelogCommand = {
+    name: 'changelog',
+    description: "The shrk command-surface delta of the running build — which verbs/flags were added, changed, or removed. Sourced from an in-binary release-notes asset (offline, authoritative for this exact build). `--since <version>` shows the cumulative delta since a prior version.",
+    usage: 'shrk changelog [--since <version>] [--all] [--json]',
+    booleanFlags: new Set(['all', 'json']),
+    run(args) {
+        const wantJson = flagBool(args, 'json');
+        const since = flagString(args, 'since');
+        const all = flagBool(args, 'all');
+        const current = SHARKCRAFT_VERSION;
+        // Newest-first for display.
+        const sorted = [...RELEASE_SURFACE_DELTAS].sort((a, b) => compareVersions(b.version, a.version));
+        let selected;
+        let scope;
+        if (all) {
+            selected = sorted;
+            scope = 'all recorded versions';
+        }
+        else if (since) {
+            // Cumulative delta: every recorded version strictly newer than `since`.
+            selected = sorted.filter((d) => compareVersions(d.version, since) > 0);
+            scope = `since ${since}`;
+        }
+        else {
+            // Default: the entry matching the running build, else the newest recorded.
+            const exact = sorted.find((d) => compareVersions(d.version, current) === 0);
+            selected = exact ? [exact] : sorted.slice(0, 1);
+            scope = exact ? `running build (${current})` : `latest recorded (running build ${current} has no recorded surface delta)`;
+        }
+        if (wantJson) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.changelog/v1',
+                runningVersion: current,
+                scope,
+                ...(since ? { since } : {}),
+                count: selected.length,
+                versions: selected,
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header(`shrk changelog — ${scope}`));
+        if (selected.length === 0) {
+            process.stdout.write(since
+                ? `  No recorded surface changes since ${since}.\n`
+                : '  No recorded surface changes.\n');
+            return 0;
+        }
+        for (const d of selected)
+            process.stdout.write(renderDeltaText(d));
+        if (!all && !since) {
+            process.stdout.write('\n(pass --since <version> for the cumulative delta, or --all for every recorded version.)\n');
+        }
+        return 0;
+    },
+};

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

@@ -1 +1 @@
-{"version":3,"file":"changes.command.d.ts","sourceRoot":"","sources":["../../src/commands/changes.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA2HhC,eAAO,MAAM,cAAc,EAAE,eAwB5B,CAAC"}
+{"version":3,"file":"changes.command.d.ts","sourceRoot":"","sources":["../../src/commands/changes.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiIhC,eAAO,MAAM,cAAc,EAAE,eAwB5B,CAAC"}

package/dist/commands/changes.command.js

@@ -59,6 +59,10 @@ async function runChangesSummary(args) {
     for (const [area, list] of Object.entries(report.filesByArea)) {
         process.stdout.write(`  ${area.padEnd(20)} (${list.length})\n`);
     }
+    if (report.unknownFiles > 0) {
+        process.stdout.write(`  ! ${report.unknownFiles}/${report.totalFiles} file(s) (${Math.round(report.unknownRate * 100)}%) matched no declared area — ` +
+            'the layer/area taxonomy may be missing globs (classifier diagnostic, not a low-risk signal).\n');
+    }
     if (report.touchedMcpTools.length > 0) {
         process.stdout.write('\nMCP tools touched (verify read-only invariant):\n');
         for (const m of report.touchedMcpTools)

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

@@ -1 +1 @@
-{"version":3,"file":"check.command.d.ts","sourceRoot":"","sources":["../../src/commands/check.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAurBhC,eAAO,MAAM,YAAY,EAAE,eAyE1B,CAAC"}
+{"version":3,"file":"check.command.d.ts","sourceRoot":"","sources":["../../src/commands/check.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAm1BhC,eAAO,MAAM,YAAY,EAAE,eAoG1B,CAAC"}

package/dist/commands/check.command.js

@@ -4,9 +4,11 @@ import * as nodePath from 'node:path';
 import { flagBool, flagNumber, flagString, flagVars, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { maybeRunInWatchMode } from "../output/watch-loop.js";
+import { computeDeletedOrphans } from "../diff/deleted-orphans.js";
+import { renderWiringExplain } from "./wiring.command.js";
 import { validateTemplateVariables } from '@shrkcrft/templates';
 import { FileChangeType, planGeneration } from '@shrkcrft/generator';
-import { evaluateBoundaries, loadTsconfigPaths, runWiring, scanImports, summarizeImports, } from '@shrkcrft/boundaries';
+import { evaluateBoundaries, explainWiring, loadTsconfigPaths, runWiring, scanImports, summarizeImports, } from '@shrkcrft/boundaries';
 function knowledgeGroup(inspection) {
     const dup = inspection.validationIssues.filter((i) => i.code === 'duplicate-id');
     const missing = inspection.validationIssues.filter((i) => i.code !== 'duplicate-id');
@@ -542,6 +544,27 @@ async function checkWiring(args) {
     }
     const rules = loaded.value.config.wiringRules ?? [];
     const planeDiagnostics = loaded.value.planeDiagnostics;
+    // `--explain <ruleId>`: dry-run ONE rule and print the declared + registered
+    // sets it extracts (file:line), the set-difference, and the verdict — the
+    // author-loop view of what the gate sees, without re-running the whole gate.
+    if (args.flags.has('explain')) {
+        const explainId = flagString(args, 'explain');
+        if (!explainId) {
+            process.stderr.write('Usage: shrk check wiring --explain <ruleId> [--json]\n');
+            return 2;
+        }
+        const rule = rules.find((r) => r.id === explainId);
+        if (!rule) {
+            const ids = rules.map((r) => r.id);
+            if (wantJson) {
+                process.stdout.write(asJson({ ok: false, error: 'not-found', ruleId: explainId, available: ids }) + '\n');
+                return 2;
+            }
+            process.stderr.write(`No wiring rule "${explainId}". Configured rules: ${ids.length > 0 ? ids.join(', ') : '(none)'}\n`);
+            return 2;
+        }
+        return renderWiringExplain(explainWiring(cwd, rule), wantJson);
+    }
     if (rules.length === 0) {
         if (wantJson) {
             process.stdout.write(asJson({ schema: 'sharkcraft.wiring/v1', rules: [], violations: [], verdict: 'pass' }) + '\n');
@@ -570,20 +593,42 @@ async function checkWiring(args) {
     const report = planeDiagnostics.length > 0
         ? { ...reportRaw, diagnostics: [...reportRaw.diagnostics, ...planeDiagnostics] }
         : reportRaw;
+    // Truthful evaluation accounting so a subset run never reads as a full green.
+    //   configured      — every wiring rule declared (the honest denominator).
+    //   selected        — rules that survived --changed-only / --only narrowing.
+    //   evaluated        — rules that actually ran a comparison (globs matched >0 files).
+    //   skippedByScope  — configured − selected (dropped by the diff/only narrowing).
+    //   matchedNothing  — selected − evaluated (in scope but matched 0 files).
+    const configured = rules.length;
+    const selected = report.rules.length;
+    const evaluated = report.evaluated;
+    const skippedByScope = Math.max(0, configured - selected);
+    const matchedNothing = Math.max(0, selected - evaluated);
+    const notVerified = Math.max(0, configured - evaluated);
+    const allEvaluated = evaluated === configured;
+    const scopeNote = changedOnly || since ? ' by --changed-only' : '';
+    const parts = [];
+    if (skippedByScope > 0)
+        parts.push(`${skippedByScope} skipped${scopeNote}`);
+    if (matchedNothing > 0)
+        parts.push(`${matchedNothing} matched no files`);
+    const breakdown = parts.length > 0 ? ` (${parts.join(', ')})` : '';
     if (wantJson) {
-        process.stdout.write(asJson(report) + '\n');
+        // Carry the honest counts so a machine consumer can tell "0 evaluated" from
+        // a real green, and see how many rules the scope skipped.
+        process.stdout.write(asJson({ ...report, configured, selected, evaluated, skippedByScope, matchedNothing, notVerified }) + '\n');
         return report.verdict === 'errors' ? 1 : 0;
     }
     process.stdout.write(header('Wiring check'));
     // `evaluated` counts rules that actually ran a comparison (globs matched >0
     // files). When 0 rules evaluated but rules ARE configured, say so loudly —
     // "checked nothing" must never read as the green "every token is wired" pass.
-    if (report.evaluated === 0) {
-        process.stdout.write(`  ! Nothing evaluated — ${report.rules.length} rule(s) configured but none matched files in scope` +
-            (changedOnly || since ? ' (changed-only).\n' : '.\n'));
+    if (evaluated === 0) {
+        process.stdout.write(`  ! 0 rules evaluated — NOT verified. ${configured} rule(s) configured${breakdown}; ` +
+            'none ran a comparison in scope. Wiring was not checked — this is not a pass.\n');
         return 0;
     }
-    process.stdout.write(kv('rules evaluated', `${report.evaluated} of ${report.rules.length}`) + '\n');
+    process.stdout.write(kv('rules evaluated', `${evaluated} of ${configured}${breakdown}`) + '\n');
     const errors = report.violations.filter((v) => v.severity === 'error').length;
     const warnings = report.violations.filter((v) => v.severity === 'warning').length;
     process.stdout.write(kv('violations', `${errors} error(s), ${warnings} warning(s)`) + '\n');
@@ -595,7 +640,16 @@ async function checkWiring(args) {
             process.stdout.write(`  ! ${d}\n`);
     }
     if (report.violations.length === 0 && report.diagnostics.length === 0) {
-        process.stdout.write('\nNo wiring violations — every declared token is registered. ✓\n');
+        if (allEvaluated) {
+            // Every configured rule ran — the earned full green.
+            process.stdout.write('\nNo wiring violations — every declared token is registered. ✓\n');
+        }
+        else {
+            // A subset ran: no violations AMONG WHAT RAN, but not a full green. Never
+            // print the unqualified "every declared token is wired" success sentence.
+            process.stdout.write(`\nNo wiring violations among the ${evaluated} rule(s) evaluated — ` +
+                `${notVerified} of ${configured} NOT verified${breakdown}. Not a full green.\n`);
+        }
         return 0;
     }
     if (report.violations.length === 0) {
@@ -619,12 +673,94 @@ async function checkWiring(args) {
     }
     return report.verdict === 'errors' ? 1 : 0;
 }
+/**
+ * `shrk check orphans [--since <ref>] [--staged]`: first-class, diff-robust
+ * reverse-closure over REMOVED files. Reads the deleted files from the diff
+ * (vs `--since`, or the staged index with `--staged`) and queries the
+ * code-graph snapshot for surviving files that still import them or reference a
+ * symbol they declared — alias-resolved, incl. barrel re-exports. Each survivor
+ * is an error with `file:line`; the type checker misses a deleted barrel
+ * re-export or string-keyed registration, so this is a write-safety guard an
+ * agent can't replicate natively. Generalizes `impact --deleted`; pairs with
+ * the composite `finish` gate.
+ */
+async function checkOrphans(args) {
+    const cwd = resolveCwd(args);
+    const wantJson = flagBool(args, 'json');
+    const since = flagString(args, 'since');
+    const staged = flagBool(args, 'staged');
+    const scan = await computeDeletedOrphans(cwd, {
+        ...(since ? { since } : {}),
+        ...(staged ? { staged: true } : {}),
+    });
+    if (!scan.ok) {
+        if (wantJson) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.deleted-orphans/v1',
+                error: scan.error,
+                reason: scan.reason,
+                orphans: [],
+            }) + '\n');
+            return 2;
+        }
+        process.stdout.write(header('Orphan check'));
+        process.stdout.write(scan.reason === 'diff-unavailable'
+            ? `  ✗ Cannot resolve diff: ${scan.error ?? 'unknown'}\n`
+            : `  ✗ ${scan.error ?? 'orphan check unavailable'}\n`);
+        return 2;
+    }
+    const scopeLabel = staged ? 'staged' : `vs ${scan.ref}`;
+    // Nothing deleted → there is nothing to check. Report a LOUD skip, not a
+    // green "no orphans" — "checked nothing" must never read as "verified clean".
+    if (scan.deleted.length === 0) {
+        if (wantJson) {
+            process.stdout.write(asJson({
+                schema: 'sharkcraft.deleted-orphans/v1',
+                skipped: true,
+                ref: scan.ref,
+                resolvedDeleted: [],
+                unresolvedDeleted: [],
+                orphans: [],
+                diagnostics: [`no deleted files (${scopeLabel}) — nothing to check`],
+            }) + '\n');
+            return 0;
+        }
+        process.stdout.write(header('Orphan check'));
+        process.stdout.write(`  ! Nothing deleted (${scopeLabel}) — orphan check skipped.\n`);
+        return 0;
+    }
+    const report = scan.report;
+    if (wantJson) {
+        process.stdout.write(asJson(report) + '\n');
+        return report.orphans.length > 0 ? 1 : 0;
+    }
+    process.stdout.write(header('Orphan check'));
+    process.stdout.write(kv('deleted files', `${scan.deleted.length} (${scopeLabel})`) + '\n');
+    if (report.orphans.length === 0) {
+        process.stdout.write('\nNo orphaned importers — nothing still references the deleted code. ✓\n');
+        for (const d of report.diagnostics.slice(0, 5))
+            process.stdout.write(`  ! ${d}\n`);
+        return 0;
+    }
+    process.stdout.write(`\n${report.orphans.length} surviving importer(s) still reference deleted code:\n`);
+    for (const o of report.orphans.slice(0, 100)) {
+        const loc = o.path ? `${o.path}${o.line ? `:${o.line}` : ''}` : o.id;
+        const detail = o.via === 'reference' && o.symbol ? `references \`${o.symbol}\`` : 'imports';
+        process.stdout.write(`  ✗ ${loc} ${detail} from deleted ${o.deletedFile}\n`);
+    }
+    if (report.orphans.length > 100) {
+        process.stdout.write(`  … (${report.orphans.length - 100} more)\n`);
+    }
+    for (const d of report.diagnostics.slice(0, 5))
+        process.stdout.write(`  ! ${d}\n`);
+    return 1;
+}
 // Main shrk check + subcommands
 // ────────────────────────────────────────────────────────────────────────
 export const checkCommand = {
     name: 'check',
     description: 'Run SharkCraft-level validation across knowledge / rules / templates / pipelines / packs / action hints / doctor. `check boundaries [--watch [--paths a,b] [--debounce N] [--once]]` re-runs the boundary scan on file changes.',
-    usage: 'shrk [--cwd <dir>] check [packs|pipelines|knowledge|generation|boundaries|imports|wiring] [--strict] [--min-score <0-100>] [--changed-only] [--since <ref>] [--only <ids>] [--json] [--watch [--paths <list>] [--debounce N] [--once]]',
+    usage: 'shrk [--cwd <dir>] check [packs|pipelines|knowledge|generation|boundaries|imports|wiring|orphans] [--strict] [--min-score <0-100>] [--changed-only] [--since <ref>] [--staged] [--only <ids>] [--json] [--watch [--paths <list>] [--debounce N] [--once]]',
     async run(args) {
         const sub = args.positional[0];
         // `check generation <id> <name>` legitimately takes extra positionals;
@@ -647,23 +783,52 @@ export const checkCommand = {
             return checkImports(args);
         if (sub === 'wiring')
             return checkWiring(args);
+        if (sub === 'orphans')
+            return checkOrphans(args);
         if (sub === 'registry-lifecycle') {
             const cwd = resolveCwd(args);
+            const changedOnly = flagBool(args, 'changed-only');
+            const since = flagString(args, 'since');
+            const scope = flagString(args, 'scope');
             const { buildRegistryLifecycleReport, renderRegistryLifecycleReportText } = await import('@shrkcrft/inspector');
-            // The scan is a single synchronous pass with no streamed output; on a
-            // large repo it can run for tens of seconds. Without a heartbeat that
-            // silence reads as a hang, so announce the work first (human path only —
-            // JSON consumers want a clean stdout).
-            if (!flagBool(args, 'json')) {
-                process.stderr.write('⏳ Scanning source + registries for lifecycle coverage (can take a while on large repos)…\n');
+            // `--changed-only` scopes the scan to the diff (tracked + untracked), so it
+            // runs inline in seconds; the full-tree scan is bounded by a wall-clock
+            // budget and flushes partial results on timeout instead of hanging.
+            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 (so a repo that
+            // registers code under tools/ etc. isn't blinded by the default set).
+            let skipDirs;
+            if (files === undefined) {
+                const loaded = await resolveProjectConfig(cwd);
+                if (loaded.ok)
+                    skipDirs = loaded.value.config.registryLifecycle?.skipDirs;
+            }
+            // Only the slow full-tree path needs the heartbeat (JSON keeps stdout clean).
+            if (!flagBool(args, 'json') && files === undefined) {
+                process.stderr.write('⏳ Scanning source + registries for lifecycle coverage (bounded by a wall-clock budget)…\n');
             }
-            const report = buildRegistryLifecycleReport({ projectRoot: cwd });
+            const report = buildRegistryLifecycleReport({
+                projectRoot: cwd,
+                ...(files !== undefined ? { files } : {}),
+                ...(scope ? { scope } : {}),
+                ...(skipDirs ? { skipDirs } : {}),
+            });
+            // Deterministic non-zero on timeout so a wedged scan fails loud, not silent.
+            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;
         }
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const readiness = buildAiReadinessReport(inspection);

package/dist/commands/command-catalog.d.ts

@@ -245,6 +245,17 @@ export declare function commandLifecycle(e: ICommandCatalogEntry): CommandLifecy
  * membership.
  */
 export declare function defaultShowInHelp(e: ICommandCatalogEntry): boolean;
+/**
+ * The "explain / dry-run" command family: entries that show you what a gate,
+ * ranker, or graph *sees* before you act (`search tuning explain`, `wiring
+ * explain`/`wiring test`, `boundaries explain`, `surface explain`, …). Several
+ * carry an Advanced surface, so {@link defaultShowInHelp} hides them despite
+ * being high-value — which is exactly why an agent finds them only by guessing.
+ * `shrk --full-help` lists this family in a dedicated section so they stop
+ * being hidden. Returns callable entries only (retired/deprecated/alias and
+ * R46-pruned are excluded), sorted by command.
+ */
+export declare function listExplainFamily(): readonly ICommandCatalogEntry[];
 /**
  * Short "Use this when…" line derived from `surface`, `taskRole`,
  * `preferredCommand`, `replacedBy`, and `machineOnly`. Empty string when

package/dist/commands/command-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../src/commands/command-catalog.ts"],"names":[],"mappings":"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"}