@shrkcrft/cli 0.1.0-alpha.28 → 0.1.0-alpha.30

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

@@ -1,6 +1,38 @@
+import { type IGeneratedArtifactRule } from '@shrkcrft/core';
+import { type IGeneratedTreeDiff, type IProvenanceFinding } from '@shrkcrft/boundaries';
 import { type ICommandHandler } from '../command-registry.js';
+/**
+ * One rule's outcome. Exported so `shrk gates check` aggregates the SAME
+ * evaluation the per-plane verb runs, rather than a second implementation that
+ * could drift from it.
+ */
+export interface IGeneratedOutcome {
+    readonly rule: IGeneratedArtifactRule;
+    readonly status: 'passed' | 'failed' | 'skipped' | 'error';
+    readonly committedCount: number;
+    readonly treeDiff?: IGeneratedTreeDiff;
+    readonly provenance: readonly IProvenanceFinding[];
+    readonly error?: string;
+    readonly skipReason?: string;
+    /** True when the drift half was deliberately not run (`--headers-only` / no `regen`). */
+    readonly driftChecked: boolean;
+    /** Files excluded from every check by `handMaintained`. */
+    readonly handMaintained: readonly string[];
+    /** Per-writer drift results, for a multi-writer rule. */
+    readonly writers: readonly IWriterOutcome[];
+}
+/** One writer's slice result inside a multi-writer rule. */
+interface IWriterOutcome {
+    readonly label: string;
+    readonly committedCount: number;
+    readonly differences: number;
+    readonly error?: string;
+}
+export declare function evaluateGeneratedRule(cwd: string, rule: IGeneratedArtifactRule, excludeDirs: readonly string[], headersOnly: boolean): IGeneratedOutcome;
+export declare function generatedHintFor(rule: IGeneratedArtifactRule): string;
 export declare const generatedListCommand: ICommandHandler;
 export declare const generatedCheckCommand: ICommandHandler;
 export declare const generatedUpdateCommand: ICommandHandler;
 export declare const generatedExplainCommand: ICommandHandler;
+export {};
 //# sourceMappingURL=generated.command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"generated.command.d.ts","sourceRoot":"","sources":["../../src/commands/generated.command.ts"],"names":[],"mappings":"AA+BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAwShC,eAAO,MAAM,oBAAoB,EAAE,eA2ClC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAuFnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAmDpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiErC,CAAC"}
+{"version":3,"file":"generated.command.d.ts","sourceRoot":"","sources":["../../src/commands/generated.command.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0LhC;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IAC3D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAED,4DAA4D;AAC5D,UAAU,cAAc;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,sBAAsB,EAC5B,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,WAAW,EAAE,OAAO,GACnB,iBAAiB,CAqFnB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAOrE;AAwED,eAAO,MAAM,oBAAoB,EAAE,eA4DlC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAgInC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAgEpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAyGrC,CAAC"}

package/dist/commands/generated.command.js

@@ -20,11 +20,13 @@ import { spawnSync } from 'node:child_process';
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
 import * as nodeOs from 'node:os';
 import * as nodePath from 'node:path';
+import { failsWhenEmpty } from '@shrkcrft/core';
 import { checkProvenanceHeaders, compareGeneratedTrees, scanGeneratedFiles, } from '@shrkcrft/boundaries';
 import { resolveProjectConfig } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { ExitCode } from "../exit-codes.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
 const SCHEMA = 'sharkcraft.generated-drift/v1';
 const DEFAULT_TIMEOUT_MS = 120_000;
 /** Cap on the temp tree read — a runaway regen must not be read into memory whole. */
@@ -125,16 +127,23 @@ function alignToCommitted(temp, committed) {
     }
     return out;
 }
-/** Run `regen` into a fresh temp dir and read the result back. Always cleans up. */
-function runRegen(cwd, rule, committed) {
+/**
+ * Run ONE regen command into a fresh temp dir and read the result back, keyed
+ * onto the committed paths it corresponds to. Always cleans up.
+ *
+ * `committed` is the slice this command OWNS, not the whole tree — that is what
+ * keeps a multi-writer tree honest: each command's output is aligned against
+ * (and later diffed against) only its own files, so writer A's output can never
+ * be reported as writer B's stale committed file.
+ */
+function runOneRegen(cwd, command, committed, timeoutMs) {
     const tmp = mkdtempSync(nodePath.join(nodeOs.tmpdir(), 'shrk-generated-'));
     try {
-        const command = rule.regen.split('{TMP}').join(tmp);
-        const child = spawnSync(command, {
+        const child = spawnSync(command.split('{TMP}').join(tmp), {
             cwd,
             shell: true,
             encoding: 'utf8',
-            timeout: rule.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            timeout: timeoutMs,
             maxBuffer: 16 * 1024 * 1024,
         });
         if (child.error)
@@ -153,21 +162,48 @@ function runRegen(cwd, rule, committed) {
         rmSync(tmp, { recursive: true, force: true });
     }
 }
-function evaluateRule(cwd, rule, excludeDirs, headersOnly) {
+/**
+ * The regen units for a rule: one per `sources[]` writer, or a single unit for
+ * the classic `regen` form. A rule declaring neither yields none (header-only).
+ */
+function regenUnitsOf(rule, scan) {
+    const fallback = rule.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (scan.slices.length > 0) {
+        return scan.slices.map((slice) => ({
+            label: slice.label,
+            command: slice.regen,
+            committed: slice.files,
+            timeoutMs: slice.timeoutMs ?? fallback,
+        }));
+    }
+    if (rule.regen === undefined)
+        return [];
+    // Single-writer: the checkable set, so a hand-maintained bless inside the
+    // glob is not compared against output no generator produces.
+    return [{ label: rule.id, command: rule.regen, committed: scan.checkable, timeoutMs: fallback }];
+}
+export function evaluateGeneratedRule(cwd, rule, excludeDirs, headersOnly) {
     const scan = scanGeneratedFiles(cwd, rule, excludeDirs);
     const severity = rule.severity ?? 'error';
     if (scan.generated.size === 0) {
-        const failed = rule.failOnEmpty === true;
+        const failed = failsWhenEmpty(rule);
         return {
             rule,
             status: failed ? 'failed' : 'skipped',
             committedCount: 0,
             provenance: [],
             driftChecked: false,
+            handMaintained: [],
+            writers: [],
             skipReason: `0 files matched generatedGlob (${rule.generatedGlob.join(', ')})`,
         };
     }
-    const headers = checkProvenanceHeaders(rule, scan.generated, scan.outside);
+    // Headers + byte checks run over the CHECKABLE set — a hand-maintained bless
+    // is excluded from both, which is the whole point of declaring it.
+    const headers = checkProvenanceHeaders(rule, scan.checkable, scan.outside, {
+        unclassified: scan.unclassified,
+        staleHandMaintained: scan.staleHandMaintained,
+    });
     if (headers.error) {
         return {
             rule,
@@ -175,21 +211,39 @@ function evaluateRule(cwd, rule, excludeDirs, headersOnly) {
             committedCount: scan.generated.size,
             provenance: [],
             driftChecked: false,
+            handMaintained: scan.handMaintained,
+            writers: [],
             error: headers.error,
         };
     }
-    let treeDiff;
-    let error;
-    const wantDrift = !headersOnly && rule.regen !== undefined;
-    if (wantDrift) {
-        const regen = runRegen(cwd, rule, scan.generated);
-        if (regen.error)
-            error = regen.error;
-        else
-            treeDiff = compareGeneratedTrees(scan.generated, regen.files, rule.compare ?? 'bytes');
+    const units = headersOnly ? [] : regenUnitsOf(rule, scan);
+    const differences = [];
+    const writers = [];
+    const errors = [];
+    let committedCompared = 0;
+    let regeneratedCount = 0;
+    for (const unit of units) {
+        const regen = runOneRegen(cwd, unit.command, unit.committed, unit.timeoutMs);
+        if (regen.error) {
+            errors.push(units.length > 1 ? `${unit.label}: ${regen.error}` : regen.error);
+            writers.push({ label: unit.label, committedCount: unit.committed.size, differences: 0, error: regen.error });
+            continue;
+        }
+        const diff = compareGeneratedTrees(unit.committed, regen.files, rule.compare ?? 'bytes');
+        differences.push(...diff.differences);
+        committedCompared += diff.committedCount;
+        regeneratedCount += diff.regeneratedCount;
+        writers.push({ label: unit.label, committedCount: unit.committed.size, differences: diff.differences.length });
     }
+    const ranAnyWriter = units.length > 0 && errors.length < units.length;
+    const treeDiff = ranAnyWriter
+        ? { differences, committedCount: committedCompared, regeneratedCount }
+        : undefined;
+    const error = errors.length > 0 ? errors.join(' · ') : undefined;
     const hardFindings = headers.findings.filter((f) => f.severity === 'error');
-    const drifted = (treeDiff?.differences.length ?? 0) > 0;
+    const drifted = differences.length > 0;
+    // A writer that failed to RUN proved nothing, so the rule is in error even if
+    // its siblings were clean — a partial regen must never read as a full pass.
     const status = error !== undefined
         ? 'error'
         : drifted || (hardFindings.length > 0 && severity === 'error')
@@ -202,12 +256,14 @@ function evaluateRule(cwd, rule, excludeDirs, headersOnly) {
         ...(treeDiff ? { treeDiff } : {}),
         provenance: headers.findings,
         ...(error ? { error } : {}),
-        driftChecked: wantDrift && error === undefined,
+        driftChecked: units.length > 0 && errors.length === 0,
+        handMaintained: scan.handMaintained,
+        writers: writers.length > 1 ? writers : [],
     };
 }
-function hintFor(rule) {
+export function generatedHintFor(rule) {
     return (rule.hint ??
-        (rule.regen
+        (rule.regen || rule.sources
             ? `regenerate with \`shrk generated update --id ${rule.id}\` and commit the result`
             : 'add the provenance header to the generated file, or move it out of the generated glob'));
 }
@@ -219,11 +275,13 @@ function outcomeJson(o) {
         severity: o.rule.severity ?? 'error',
         committedCount: o.committedCount,
         driftChecked: o.driftChecked,
+        handMaintained: o.handMaintained,
+        ...(o.writers.length > 0 ? { writers: o.writers } : {}),
         ...(o.treeDiff ? { differences: o.treeDiff.differences, regeneratedCount: o.treeDiff.regeneratedCount } : {}),
         provenance: o.provenance,
         ...(o.error ? { error: o.error } : {}),
         ...(o.skipReason ? { skipReason: o.skipReason } : {}),
-        hint: hintFor(o.rule),
+        hint: generatedHintFor(o.rule),
     };
 }
 async function prepare(args) {
@@ -235,7 +293,7 @@ async function prepare(args) {
             process.stdout.write(asJson({ schema: SCHEMA, error: loaded.message }) + '\n');
         else
             process.stderr.write(`Could not load config: ${loaded.message}\n  Run \`shrk doctor\` for details.\n`);
-        return { ok: false, code: ExitCode.NotVerified };
+        return { ok: false, code: ExitCode.UsageError };
     }
     const id = flagString(args, 'id');
     let rules = loaded.value.rules;
@@ -245,7 +303,7 @@ async function prepare(args) {
         const unknown = wanted.filter((w) => !known.has(w));
         if (unknown.length > 0) {
             process.stderr.write(`Unknown generated-artifact id(s): ${unknown.join(', ')}. Declared: ${[...known].join(', ') || '(none)'}\n`);
-            return { ok: false, code: ExitCode.NotVerified };
+            return { ok: false, code: ExitCode.UsageError };
         }
         rules = rules.filter((r) => wanted.includes(r.id));
     }
@@ -289,6 +347,9 @@ export const generatedListCommand = {
                     description: r.description ?? null,
                     generatedGlob: r.generatedGlob,
                     regen: r.regen ?? null,
+                    sources: r.sources ?? null,
+                    handMaintained: r.handMaintained ?? null,
+                    handMaintainedMarker: r.handMaintainedMarker ?? null,
                     compare: r.compare ?? 'bytes',
                     provenanceHeader: r.provenanceHeader ?? null,
                     failOnEmpty: r.failOnEmpty === true,
@@ -301,7 +362,22 @@ export const generatedListCommand = {
         for (const r of prep.all) {
             process.stdout.write(`  • ${r.id}\n`);
             process.stdout.write(`      glob   ${r.generatedGlob.join(', ')}\n`);
-            process.stdout.write(`      regen  ${r.regen ?? '(header-only — never spawns)'}\n`);
+            if (r.sources && r.sources.length > 0) {
+                process.stdout.write(`      regen  ${r.sources.length} writer(s):\n`);
+                r.sources.forEach((src, i) => {
+                    process.stdout.write(`               [${src.id ?? i}] ${src.regen}\n`);
+                    process.stdout.write(`                    owns ${src.glob.join(', ')}\n`);
+                });
+            }
+            else {
+                process.stdout.write(`      regen  ${r.regen ?? '(header-only — never spawns)'}\n`);
+            }
+            if (r.handMaintained && r.handMaintained.length > 0) {
+                process.stdout.write(`      hand   ${r.handMaintained.join(', ')}  (exempt from header + byte checks)\n`);
+            }
+            if (r.handMaintainedMarker) {
+                process.stdout.write(`      marker /${r.handMaintainedMarker}/  (in-file bless)\n`);
+            }
             if (r.provenanceHeader) {
                 process.stdout.write(`      header /${r.provenanceHeader.mustMatch}/${r.provenanceHeader.forbidOutside ? '  + mislabel check' : ''}\n`);
             }
@@ -326,12 +402,13 @@ export const generatedCheckCommand = {
         const headersOnly = flagBool(args, 'headers-only');
         if (prep.rules.length === 0)
             return writeNoRules(json);
-        const outcomes = prep.rules.map((r) => evaluateRule(prep.cwd, r, prep.excludeDirs, headersOnly));
+        const outcomes = prep.rules.map((r) => evaluateGeneratedRule(prep.cwd, r, prep.excludeDirs, headersOnly));
         const failed = outcomes.filter((o) => o.status === 'failed' || (o.status === 'error' && (o.rule.severity ?? 'error') === 'error'));
         const evaluated = outcomes.filter((o) => o.status !== 'skipped').length;
+        const skippedCount = outcomes.length - evaluated;
         const exit = failed.length > 0
             ? ExitCode.Failure
-            : evaluated === 0
+            : evaluated === 0 || skippedCount > 0
                 ? ExitCode.NotVerified
                 : ExitCode.VerifiedPass;
         if (json) {
@@ -343,6 +420,33 @@ export const generatedCheckCommand = {
                 skipped: outcomes.filter((o) => o.status === 'skipped').length,
                 verdict: failed.length > 0 ? 'errors' : evaluated === 0 ? 'not-verified' : 'pass',
                 diagnostics: prep.planeDiagnostics,
+                gate: buildGateEnvelope('generated check', exit, outcomes.map((o) => ({
+                    id: o.rule.id,
+                    type: 'generated',
+                    status: o.status,
+                    severity: o.rule.severity ?? 'error',
+                    counts: {
+                        files: o.committedCount,
+                        differences: o.treeDiff?.differences.length ?? 0,
+                        provenance: o.provenance.length,
+                    },
+                    violations: [
+                        ...(o.treeDiff?.differences ?? []).map((d) => ({
+                            id: d.file,
+                            file: d.file,
+                            message: d.kind,
+                            hint: generatedHintFor(o.rule),
+                        })),
+                        ...o.provenance.map((f) => ({
+                            id: f.file,
+                            file: f.file,
+                            message: f.message,
+                            hint: generatedHintFor(o.rule),
+                        })),
+                    ],
+                    ...(o.skipReason ? { skipReason: o.skipReason } : {}),
+                    ...(o.error ? { error: o.error } : {}),
+                }))),
             }) + '\n');
             return exit;
         }
@@ -361,11 +465,18 @@ export const generatedCheckCommand = {
             }
             const diffs = o.treeDiff?.differences ?? [];
             if (o.status === 'passed') {
-                process.stdout.write(`  ✓ ${o.rule.id}  (${o.committedCount} files` +
+                const exempt = o.handMaintained.length > 0 ? `, ${o.handMaintained.length} hand-maintained` : '';
+                process.stdout.write(`  ✓ ${o.rule.id}  (${o.committedCount} files${exempt}` +
                     `${o.driftChecked ? ', byte-identical to a fresh regen' : ', headers only'})\n`);
+                for (const w of o.writers) {
+                    process.stdout.write(`      · ${w.label}: ${w.committedCount} file(s) verified\n`);
+                }
             }
             else {
                 process.stdout.write(`  ✗ ${o.rule.id}  ${diffs.length} file(s) differ from a fresh regen\n`);
+                for (const w of o.writers) {
+                    process.stdout.write(`      · ${w.label}: ${w.error ? `ERROR — ${w.error}` : `${w.differences} of ${w.committedCount} differ`}\n`);
+                }
                 for (const d of diffs.slice(0, 25)) {
                     const label = d.kind === 'content'
                         ? 'hand-edited (or source changed)'
@@ -384,7 +495,7 @@ export const generatedCheckCommand = {
                 process.stdout.write(`      … (${o.provenance.length - 25} more header finding(s))\n`);
             }
             if (o.status === 'failed')
-                process.stdout.write(`      → ${hintFor(o.rule)}\n`);
+                process.stdout.write(`      → ${generatedHintFor(o.rule)}\n`);
         }
         for (const d of prep.planeDiagnostics)
             process.stdout.write(`  ! ${d}\n`);
@@ -411,29 +522,41 @@ export const generatedUpdateCommand = {
             return writeNoRules(json);
         const results = [];
         for (const rule of prep.rules) {
-            if (!rule.regen) {
+            // A multi-writer rule blesses by running EVERY writer — regenerating one
+            // slice and calling the artifact updated is how a mixed tree drifts.
+            const commands = rule.sources && rule.sources.length > 0
+                ? rule.sources.map((src, i) => ({
+                    label: `${rule.id}/${src.id ?? i}`,
+                    command: src.regen,
+                    timeoutMs: src.timeoutMs ?? rule.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                }))
+                : rule.regen
+                    ? [{ label: rule.id, command: rule.regen, timeoutMs: rule.timeoutMs ?? DEFAULT_TIMEOUT_MS }]
+                    : [];
+            if (commands.length === 0) {
                 results.push({ id: rule.id, ran: false, error: 'header-only rule — nothing to regenerate' });
                 continue;
             }
-            // `{TMP}` is the CHECK contract; `update` writes in place, so it is
-            // substituted with the project root and the regen writes its real output.
-            const command = rule.regen.split('{TMP}').join(prep.cwd);
-            const child = spawnSync(command, {
-                cwd: prep.cwd,
-                shell: true,
-                encoding: 'utf8',
-                timeout: rule.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-                maxBuffer: 16 * 1024 * 1024,
-                stdio: json ? 'pipe' : 'inherit',
-            });
-            if (child.error) {
-                results.push({ id: rule.id, ran: false, error: child.error.message });
-            }
-            else if (child.status !== 0) {
-                results.push({ id: rule.id, ran: true, error: `exited ${child.status ?? 'null'}` });
-            }
-            else {
-                results.push({ id: rule.id, ran: true });
+            for (const { label, command, timeoutMs } of commands) {
+                // `{TMP}` is the CHECK contract; `update` writes in place, so it is
+                // substituted with the project root and the regen writes its real output.
+                const child = spawnSync(command.split('{TMP}').join(prep.cwd), {
+                    cwd: prep.cwd,
+                    shell: true,
+                    encoding: 'utf8',
+                    timeout: timeoutMs,
+                    maxBuffer: 16 * 1024 * 1024,
+                    stdio: json ? 'pipe' : 'inherit',
+                });
+                if (child.error) {
+                    results.push({ id: label, ran: false, error: child.error.message });
+                }
+                else if (child.status !== 0) {
+                    results.push({ id: label, ran: true, error: `exited ${child.status ?? 'null'}` });
+                }
+                else {
+                    results.push({ id: label, ran: true });
+                }
             }
         }
         const failed = results.filter((r) => r.error !== undefined);
@@ -460,7 +583,7 @@ export const generatedExplainCommand = {
         const id = flagString(args, 'id') ?? args.positional[0];
         if (!id) {
             process.stderr.write('Usage: shrk generated explain --id <id>\n');
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         }
         const prep = await prepare(args);
         if (!prep.ok)
@@ -468,16 +591,27 @@ export const generatedExplainCommand = {
         const rule = prep.all.find((r) => r.id === id);
         if (!rule) {
             process.stderr.write(`No generated-artifact rule "${id}". Declared: ${prep.all.map((r) => r.id).join(', ') || '(none)'}\n`);
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         }
         // explain never spawns — the point is to show what the rule SEES.
         const scan = scanGeneratedFiles(prep.cwd, rule, prep.excludeDirs);
-        const outcome = evaluateRule(prep.cwd, rule, prep.excludeDirs, true);
+        const outcome = evaluateGeneratedRule(prep.cwd, rule, prep.excludeDirs, true);
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 schema: 'sharkcraft.generated-explain/v1',
                 ...outcomeJson(outcome),
                 files: [...scan.generated.keys()],
+                checkable: [...scan.checkable.keys()],
+                handMaintained: scan.handMaintained,
+                markedHandMaintained: scan.markedHandMaintained,
+                staleHandMaintained: scan.staleHandMaintained,
+                unclassified: scan.unclassified,
+                slices: scan.slices.map((sl) => ({
+                    label: sl.label,
+                    regen: sl.regen,
+                    glob: sl.glob,
+                    files: [...sl.files.keys()],
+                })),
                 outsideScanned: scan.outside.size,
                 outsideGlobs: scan.outsideGlobs,
                 regen: rule.regen ?? null,
@@ -489,7 +623,34 @@ export const generatedExplainCommand = {
             process.stdout.write(`  ${rule.description}\n`);
         process.stdout.write(kv('glob', rule.generatedGlob.join(', ')) + '\n');
         process.stdout.write(kv('files matched', String(scan.generated.size)) + '\n');
-        process.stdout.write(kv('regen', rule.regen ?? '(header-only)') + '\n');
+        if (scan.slices.length > 0) {
+            process.stdout.write(kv('writers', String(scan.slices.length)) + '\n');
+            for (const sl of scan.slices) {
+                process.stdout.write(`      [${sl.label}] ${sl.files.size} file(s) — ${sl.regen}\n`);
+                process.stdout.write(`            owns ${sl.glob.join(', ')}\n`);
+            }
+        }
+        else {
+            process.stdout.write(kv('regen', rule.regen ?? '(header-only)') + '\n');
+        }
+        if (scan.handMaintained.length > 0) {
+            process.stdout.write(kv('hand-maintained', `${scan.handMaintained.length} file(s) — exempt from header + byte checks`) + '\n');
+            const marked = new Set(scan.markedHandMaintained);
+            // Say WHICH mechanism blessed each file: a config entry and an in-file
+            // marker are reviewed in different places, so "why is this exempt?" has
+            // two different answers and the reader needs to know which one applies.
+            for (const f of scan.handMaintained.slice(0, 20)) {
+                process.stdout.write(`      ${f}${marked.has(f) ? '  (in-file marker)' : '  (handMaintained[])'}\n`);
+            }
+        }
+        if (scan.unclassified.length > 0) {
+            process.stdout.write(kv('unclassified', `${scan.unclassified.length} file(s) — owned by no writer, not blessed`) + '\n');
+            for (const f of scan.unclassified.slice(0, 20))
+                process.stdout.write(`      ${f}\n`);
+        }
+        for (const pattern of scan.staleHandMaintained) {
+            process.stdout.write(`  ! handMaintained "${pattern}" matches no file — stale bless\n`);
+        }
         process.stdout.write(kv('compare', rule.compare ?? 'bytes') + '\n');
         if (rule.provenanceHeader) {
             process.stdout.write(kv('header', `/${rule.provenanceHeader.mustMatch}/`) + '\n');

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,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"}
+{"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,CAmGtE;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

@@ -594,7 +594,11 @@ export async function runGraphStatus(args) {
     }
     process.stdout.write(header('Graph status'));
     process.stdout.write(kv('schema', payload.schema) + '\n');
-    process.stdout.write(kv('files', String(payload.fileCount)) + '\n');
+    // "files indexed", not "files": this is the size of the STORED snapshot, and
+    // it deliberately does not move when a new file appears on disk — that shows
+    // up on the `drift` line below. Reading it as a live count is how an added
+    // file looks invisible to the index.
+    process.stdout.write(kv('files indexed', String(payload.fileCount)) + '\n');
     process.stdout.write(kv('nodes', String(payload.nodeCount)) + '\n');
     process.stdout.write(kv('edges', String(payload.edgeCount)) + '\n');
     process.stdout.write(kv('packages', String(payload.workspacePackages.length)) + '\n');

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;AAqF9D;;;;;;;;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;EAqJpF"}
+{"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;AA4H9D;;;;;;;;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;EA2KpF"}

package/dist/commands/help.command.js

@@ -1,5 +1,45 @@
 import { header } from "../output/format-output.js";
 import { COMMAND_CATALOG, defaultShowInHelp, listExplainFamily } from "./command-catalog.js";
+/**
+ * Every multi-token command path the catalog documents. These are real,
+ * callable verbs that the command trie never sees, because their parent
+ * dispatches them from a positional argument rather than registering them.
+ */
+function catalogHelpPaths() {
+    const paths = new Set();
+    for (const entry of COMMAND_CATALOG) {
+        // Strip the flag/argument tail a few catalog entries carry in `command`.
+        const clean = entry.command.split(/\s+--/)[0].trim();
+        if (clean.length > 0)
+            paths.add(clean);
+    }
+    return paths;
+}
+/**
+ * Render help for a command path the trie could not resolve but the catalog
+ * documents, plus its sibling verbs under the same parent so the family is
+ * discoverable from any one member.
+ */
+function renderCatalogHelp(tokens) {
+    const want = tokens.join(' ');
+    const entry = COMMAND_CATALOG.find((e) => e.command.split(/\s+--/)[0].trim() === want);
+    if (!entry)
+        return undefined;
+    let out = `${want} — ${entry.description}\n`;
+    const extra = EXTRA_HELP_LINES[want];
+    if (extra)
+        out += extra.join('\n') + '\n';
+    const parent = tokens.slice(0, -1).join(' ');
+    if (parent.length > 0) {
+        const siblings = [...catalogHelpPaths()]
+            .filter((p) => p !== want && p.startsWith(parent + ' ') && !p.slice(parent.length + 1).includes(' '))
+            .sort();
+        if (siblings.length > 0) {
+            out += `\nSiblings: ${siblings.join(', ')}\n`;
+        }
+    }
+    return out;
+}
 /** First sentence of a catalog description, for the compact explain-family list. */
 function firstSentence(description) {
     const dot = description.indexOf('. ');
@@ -156,8 +196,17 @@ export function makeHelpCommand(registry) {
                     // that exits 0. Error out honestly instead, with a did-you-mean when
                     // a real topic is a near-typo of the request.
                     const attempt = tokens.join(' ');
+                    // The trie matched nothing, but the CATALOG may still document this
+                    // path — a documented verb whose parent isn't a registered command
+                    // is still real and callable.
+                    const viaCatalog = renderCatalogHelp(tokens);
+                    if (viaCatalog !== undefined) {
+                        process.stdout.write(viaCatalog);
+                        return 0;
+                    }
                     process.stderr.write(`no such help topic: '${attempt}'\n`);
-                    const suggestion = nearestHelpTopic(attempt, realHelpTopics(registry));
+                    const suggestion = nearestHelpTopic(attempt, realHelpTopics(registry)) ??
+                        nearestHelpTopic(attempt, catalogHelpPaths());
                     if (suggestion)
                         process.stderr.write(`Did you mean: ${suggestion}?\n`);
                     return 1;
@@ -199,7 +248,20 @@ export function makeHelpCommand(registry) {
                     }
                     return 0;
                 }
-                process.stderr.write(`Unknown command: ${tokens.join(' ')}\n`);
+                // The trie could not resolve the full path, but the CATALOG may still
+                // document it. Verbs like `check wiring` are dispatched from inside
+                // their parent's handler on a positional, so they are real, callable
+                // and documented — yet never trie nodes. Falling through to "Unknown
+                // command" made an entire documented surface look non-existent.
+                const catalogHelp = renderCatalogHelp(tokens);
+                if (catalogHelp !== undefined) {
+                    process.stdout.write(catalogHelp);
+                    return 0;
+                }
+                process.stderr.write(`no such help topic: '${tokens.join(' ')}'\n`);
+                const near = nearestHelpTopic(tokens.join(' '), catalogHelpPaths());
+                if (near)
+                    process.stderr.write(`Did you mean: shrk help ${near}?\n`);
                 return 1;
             }
             if (!wantsFull) {

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":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,qBAAqB,EAAG,8BAAuC,CAAC;AAE7E,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,cAAc,CAqBhB;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CA0CtF;AAGD,eAAO,MAAM,wBAAwB,EAAE,eA8BtC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAmN/B,CAAC"}
+{"version":3,"file":"policy-lint.command.d.ts","sourceRoot":"","sources":["../../src/commands/policy-lint.command.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAEL,KAAK,cAAc,EAEnB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC,eAAO,MAAM,qBAAqB,EAAG,8BAAuC,CAAC;AAE7E,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,cAAc,CAqBhB;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CA0CtF;AAGD,eAAO,MAAM,wBAAwB,EAAE,eA8BtC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAoQ/B,CAAC"}