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

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

@@ -1,4 +1,29 @@
+import type { IBaselineRule } from '@shrkcrft/core';
+import { type IBaselineDiff } from '@shrkcrft/boundaries';
 import { type ICommandHandler } from '../command-registry.js';
+/**
+ * One rule's outcome, shared by check / diff / update — and by `shrk gates
+ * check`, which aggregates every plane. Exported so the aggregate runs the
+ * IDENTICAL evaluation as the per-plane verb: two implementations of "did this
+ * baseline drift?" would eventually disagree, and the one nobody runs would be
+ * the one that is wrong.
+ */
+export interface IBaselineOutcome {
+    readonly rule: IBaselineRule;
+    readonly status: 'passed' | 'failed' | 'skipped' | 'error';
+    readonly diff?: IBaselineDiff;
+    readonly committed?: string;
+    readonly current?: string;
+    readonly committedCount: number;
+    readonly currentCount: number;
+    readonly error?: string;
+    readonly skipReason?: string;
+    /** The recompute produced 0 entries while the baseline has some — likely a broken compute. */
+    readonly emptyCompute?: boolean;
+    /** No committed artifact exists yet — `committed` is absent, not zero. */
+    readonly missingBaseline?: boolean;
+}
+export declare function evaluateBaselineRule(cwd: string, rule: IBaselineRule, excludeDirs: readonly string[], changedFiles: readonly string[] | undefined): IBaselineOutcome;
 export declare const baselineListCommand: ICommandHandler;
 export declare const baselineCheckCommand: ICommandHandler;
 export declare const baselineDiffCommand: ICommandHandler;

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

@@ -1 +1 @@
-{"version":3,"file":"baseline.command.d.ts","sourceRoot":"","sources":["../../src/commands/baseline.command.ts"],"names":[],"mappings":"AA6BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiShC,eAAO,MAAM,mBAAmB,EAAE,eAyCjC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAgFlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA8BjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAwDnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAoDpC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAc7B,CAAC"}
+{"version":3,"file":"baseline.command.d.ts","sourceRoot":"","sources":["../../src/commands/baseline.command.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAuFhC;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAC1C,gBAAgB,CAiHlB;AA4FD,eAAO,MAAM,mBAAmB,EAAE,eAyCjC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAyGlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA8BjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAwDnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAiEpC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAc7B,CAAC"}

package/dist/commands/baseline.command.js

@@ -17,11 +17,13 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { resolveSourceGlobs, failsWhenEmpty } from '@shrkcrft/core';
 import { baselineCount, baselineFails, computeBaselineFromExtractor, diffBaseline, matchesAny, } from '@shrkcrft/boundaries';
 import { resolveChangedFiles, 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.baseline/v1';
 const DEFAULT_TIMEOUT_MS = 60_000;
 async function loadBaselines(cwd) {
@@ -85,7 +87,7 @@ function computeCurrent(cwd, rule, excludeDirs) {
     }
     return { text: String(child.stdout ?? '') };
 }
-function evaluateRule(cwd, rule, excludeDirs, changedFiles) {
+export function evaluateBaselineRule(cwd, rule, excludeDirs, changedFiles) {
     // --changed-only is honest about what it CANNOT scope: a command compute with
     // no `watchFiles` has no file footprint, so it is reported as skipped rather
     // than quietly passing.
@@ -93,7 +95,7 @@ function evaluateRule(cwd, rule, excludeDirs, changedFiles) {
         const globs = rule.watchFiles && rule.watchFiles.length > 0
             ? rule.watchFiles
             : rule.compute.kind === 'extractor'
-                ? (rule.compute.source?.files ?? [])
+                ? (resolveSourceGlobs(rule.compute.source ?? { files: [] }))
                 : undefined;
         if (globs === undefined) {
             return {
@@ -116,12 +118,19 @@ function evaluateRule(cwd, rule, excludeDirs, changedFiles) {
     }
     const abs = nodePath.resolve(cwd, rule.baseline);
     if (!existsSync(abs)) {
+        // No artifact yet. `check` must still fail (nothing to compare against),
+        // but the CURRENT side is knowable and is exactly what the author needs to
+        // see before blessing — so compute it rather than reporting a false `0`.
+        const first = computeCurrent(cwd, rule, excludeDirs);
         return {
             rule,
             status: 'error',
             committedCount: 0,
-            currentCount: 0,
-            error: `committed baseline ${rule.baseline} does not exist — create it with \`shrk baseline update --id ${rule.id}\``,
+            ...(first.error ? {} : { current: first.text }),
+            currentCount: first.error ? 0 : baselineCount(rule, first.text),
+            missingBaseline: true,
+            error: first.error ??
+                `committed baseline ${rule.baseline} does not exist — create it with \`shrk baseline update --id ${rule.id}\``,
         };
     }
     let committed;
@@ -149,9 +158,22 @@ function evaluateRule(cwd, rule, excludeDirs, changedFiles) {
     // the baseline has entries and the recompute has none, that is real drift
     // (everything vanished) and must be reported as such, not swallowed as a skip.
     if (currentCount === 0 && committedCount === 0) {
+        // A fence ASSERTS emptiness, so for it the empty case is the verified pass
+        // rather than "nothing was checked" — otherwise the rule could never be
+        // green and could not gate anything.
+        if (rule.expectEmpty === true) {
+            return {
+                rule,
+                status: 'passed',
+                committed,
+                current: computed.text,
+                committedCount,
+                currentCount,
+            };
+        }
         return {
             rule,
-            status: rule.failOnEmpty ? 'failed' : 'skipped',
+            status: failsWhenEmpty(rule) ? 'failed' : 'skipped',
             committed,
             current: computed.text,
             committedCount,
@@ -190,6 +212,7 @@ function outcomeJson(o) {
         ...(o.error ? { error: o.error } : {}),
         ...(o.skipReason ? { skipReason: o.skipReason } : {}),
         ...(o.emptyCompute ? { emptyCompute: true } : {}),
+        ...(o.missingBaseline ? { missingBaseline: true } : {}),
         hint: hintFor(o.rule),
     };
 }
@@ -216,12 +239,12 @@ async function prepare(args, opts) {
             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 selected = selectRules(loaded.value.rules, flagString(args, 'id') ?? undefined);
     if (!selected.ok) {
         process.stderr.write(selected.message + '\n');
-        return { ok: false, code: ExitCode.NotVerified };
+        return { ok: false, code: ExitCode.UsageError };
     }
     let changedFiles;
     if (opts.changedAware) {
@@ -310,13 +333,15 @@ export const baselineCheckCommand = {
         const json = flagBool(args, 'json');
         if (prep.rules.length === 0)
             return writeNoRules(json);
-        const outcomes = prep.rules.map((r) => evaluateRule(prep.cwd, r, prep.excludeDirs, prep.changedFiles));
+        const outcomes = prep.rules.map((r) => evaluateBaselineRule(prep.cwd, r, prep.excludeDirs, prep.changedFiles));
         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;
         // 0 only when a NON-EMPTY scope was actually compared; 2 when nothing was.
+        // A skipped baseline is "partially verified", never a green 0.
+        const skippedCount = outcomes.filter((o) => o.status === 'skipped').length;
         const exit = failed.length > 0
             ? ExitCode.Failure
-            : evaluated === 0
+            : evaluated === 0 || skippedCount > 0
                 ? ExitCode.NotVerified
                 : ExitCode.VerifiedPass;
         if (json) {
@@ -327,6 +352,19 @@ export const baselineCheckCommand = {
                 skipped: outcomes.filter((o) => o.status === 'skipped').length,
                 verdict: failed.length > 0 ? 'errors' : evaluated === 0 ? 'not-verified' : 'pass',
                 diagnostics: prep.planeDiagnostics,
+                gate: buildGateEnvelope('baseline check', exit, outcomes.map((o) => ({
+                    id: o.rule.id,
+                    type: 'baseline',
+                    status: o.status,
+                    severity: o.rule.severity ?? 'error',
+                    counts: { committed: o.committedCount, current: o.currentCount },
+                    violations: [
+                        ...(o.diff?.added ?? []).map((id) => ({ id, message: 'added', hint: hintFor(o.rule) })),
+                        ...(o.diff?.removed ?? []).map((id) => ({ id, message: 'removed', hint: hintFor(o.rule) })),
+                    ],
+                    ...(o.skipReason ? { skipReason: o.skipReason } : {}),
+                    ...(o.error ? { error: o.error } : {}),
+                }))),
             }) + '\n');
             return exit;
         }
@@ -343,6 +381,10 @@ export const baselineCheckCommand = {
             }
             if (o.status === 'error') {
                 process.stdout.write(`  ! ${o.rule.id}  ${o.error}\n`);
+                if (o.missingBaseline && o.currentCount > 0) {
+                    process.stdout.write(`      the compute currently yields ${o.currentCount} entr${o.currentCount === 1 ? 'y' : 'ies'} — ` +
+                        `run \`shrk baseline update --id ${o.rule.id}\` to bless them.\n`);
+                }
                 continue;
             }
             const added = o.diff?.added.length ?? 0;
@@ -378,7 +420,7 @@ export const baselineDiffCommand = {
         const json = flagBool(args, 'json');
         if (prep.rules.length === 0)
             return writeNoRules(json);
-        const outcomes = prep.rules.map((r) => evaluateRule(prep.cwd, r, prep.excludeDirs, undefined));
+        const outcomes = prep.rules.map((r) => evaluateBaselineRule(prep.cwd, r, prep.excludeDirs, undefined));
         if (json) {
             process.stdout.write(asJson({ schema: SCHEMA, results: outcomes.map(outcomeJson), inspection: true }) + '\n');
             return ExitCode.VerifiedPass;
@@ -414,7 +456,7 @@ export const baselineUpdateCommand = {
                 errors.push({ id: rule.id, error: computed.error });
                 continue;
             }
-            if (computed.text.trim() === '' && rule.failOnEmpty) {
+            if (computed.text.trim() === '' && failsWhenEmpty(rule)) {
                 errors.push({
                     id: rule.id,
                     error: 'refusing to write an EMPTY baseline for a `failOnEmpty` rule — fix the compute first',
@@ -455,7 +497,7 @@ export const baselineExplainCommand = {
         const id = flagString(args, 'id') ?? args.positional[0];
         if (!id) {
             process.stderr.write('Usage: shrk baseline explain --id <id>\n');
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         }
         const prep = await prepare(args, { changedAware: false });
         if (!prep.ok)
@@ -463,9 +505,9 @@ export const baselineExplainCommand = {
         const rule = prep.all.find((r) => r.id === id);
         if (!rule) {
             process.stderr.write(`No baseline "${id}". Declared: ${prep.all.map((r) => r.id).join(', ') || '(none)'}\n`);
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         }
-        const outcome = evaluateRule(prep.cwd, rule, prep.excludeDirs, undefined);
+        const outcome = evaluateBaselineRule(prep.cwd, rule, prep.excludeDirs, undefined);
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 schema: 'sharkcraft.baseline-explain/v1',
@@ -479,12 +521,17 @@ export const baselineExplainCommand = {
         if (rule.description)
             process.stdout.write(`  ${rule.description}\n`);
         process.stdout.write(kv('committed', rule.baseline) + '\n');
-        process.stdout.write(kv('compute', rule.compute.kind === 'command' ? `command · ${rule.compute.run}` : `extractor · ${rule.compute.source?.extract ?? 'sugar'}`) + '\n');
+        process.stdout.write(kv('compute', rule.compute.kind === 'command'
+            ? `command · ${rule.compute.run}`
+            : `extractor · ${rule.compute.source?.extract ?? 'sugar'}` +
+                (rule.compute.source?.$use ? `  (via $use:${rule.compute.source.$use})` : '')) + '\n');
         process.stdout.write(kv('direction', rule.direction ?? 'two-way') + '\n');
         process.stdout.write(kv('canonical', outcome.diff?.canonical ?? rule.compute.canonical ?? 'auto') + '\n');
         if (rule.keyBy)
             process.stdout.write(kv('keyBy', rule.keyBy) + '\n');
-        process.stdout.write(kv('entries', `${outcome.committedCount} committed → ${outcome.currentCount} now`) + '\n');
+        process.stdout.write(kv('entries', outcome.missingBaseline
+            ? `committed (none yet) → ${outcome.currentCount} now`
+            : `${outcome.committedCount} committed → ${outcome.currentCount} now`) + '\n');
         process.stdout.write(kv('status', outcome.status) + '\n');
         if (outcome.error)
             process.stdout.write(`  ! ${outcome.error}\n`);
@@ -506,6 +553,6 @@ export const baselineCommand = {
         const sub = args.positional[0];
         process.stderr.write((sub ? `Unknown subcommand "${sub}". ` : '') +
             'Usage: shrk baseline list | check [--id X] | diff | update | explain --id <id>\n');
-        return ExitCode.NotVerified;
+        return ExitCode.UsageError;
     },
 };

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

@@ -1 +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,EA8HjE,CAAC"}
+{"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,EA4KjE,CAAC"}

package/dist/commands/changelog-data.js

@@ -134,4 +134,50 @@ export const RELEASE_SURFACE_DELTAS = [
         ],
         removed: [],
     },
+    {
+        version: '0.1.0-alpha.30',
+        title: 'The engine taps the import graph, and reads its own prose',
+        added: [
+            '`shrk docs references check|explain|list` — the seventh rule plane (`docReferences[]`): ids cited in free-text PROSE (READMEs, docs, agent skill files) that no longer resolve. Markdown has no build, so these drift with zero signal. `requireContext` (default `backtick`), `exempt[]`, a per-line `<!-- ref-allow: why -->` marker, and a length-scaled `did you mean` keep it low-noise. Reads dot-directories a glob explicitly names, so `.claude/skills/**` works.',
+            '`shrk gates check` — every rule plane in ONE pass with one exit code (the CI / pre-commit primitive); `--changed-only` scopes by rule footprint, `--strict` promotes warning-severity findings to failures.',
+            '`shrk gates try --rule-file <f> [--full]` — dry-run a candidate rule against the tree without adding it to config. Dumps every captured token, so an over-matching `tokenPattern` is visible in one run instead of arriving as noise in CI.',
+            '`import-edges` extractor — the resolved dependency graph as a rule input (`emit: edge|symbol|from`, targetable by `to.module` / `to.modulePattern` / `to.files` / `to.match`). Existing planes now express adoption ledgers, orphan detection, deprecation ratchets and targeted fences. Alias-aware; no persisted index, so no staleness.',
+            '`filenames` extractor + `mode: parity` — companion-file invariants (every `X.ts` has an `X.test.ts`).',
+            'Shared extractors: a top-level `extractors` map plus `{ $use: "<id>" }` on any plane (local fields override). The planes describing one id set can no longer drift apart, and a typo\'d id fails the config load rather than silently matching nothing.',
+            '`generatedArtifacts[]` for MIXED trees: `sources[]` (N writers, each verifying its own sub-glob), `handMaintained[]` (literal filenames only, so the exemption cannot silently widen) and `handMaintainedMarker` for an in-file bless. A file under the tree owned by neither is an `unclassified` finding.',
+            '`expectEmpty: true` on `baselines[]` — a fence that fails the moment the edge set becomes non-empty.',
+            '`shrk check wiring --fix` now adds the missing IMPORT alongside the array member when the specifier is a pure function of the member name AND resolves to the declaring file; otherwise it refuses with `needs-import`.',
+        ],
+        changed: [
+            'FIXED (P1): `--fix --write` could green the wiring gate over a file that no longer compiles. The common registry shape IMPORTS its array members, and appending the token alone left `TS2304: Cannot find name`. It now writes both edits or refuses.',
+            'FIXED (P1): reference resolution ran in THREE modules — the prose linter and both self-config doctors — each from its own sources, agreeing only by coincidence. The self-config doctor reported 17 of shrk\'s own correctly-registered ids as unknown (its hand-written "known ids" union omitted policies, decisions, scaffold patterns and paths). One resolver now answers for every kind, and each kind reads the source its `list` verb reads.',
+            'FIXED (P2): `shrk graph status` judged index freshness by working-tree DIVERGENCE while `shrk code-intel` judged it by wall-clock age — contradictory verdicts on the same index in the same second, with every arch/cycle count derived from it inheriting the staleness unmarked. Divergence is now the single verdict; age is a display detail (`current (indexed 5d ago)` / `STALE — N file(s) changed since index`).',
+            'A finding DERIVED from a stale graph index is reported `NOT VERIFIED` rather than as a count — the loud-skip contract the rule planes already honour, extended to the graph-derived surfaces. An unmeasured verdict is never a pass.',
+            'An ERRORED rule is no longer counted as `evaluated` by `gates check` / `docs references check`, so a warning-severity rule that could not run exits `2` instead of printing "not blocking" above exit `0`.',
+            'A doc-reference rule whose registries are ALL empty refuses loudly instead of reporting every id as unresolved — a gate that confidently flags correct usage is worse than no gate.',
+            '`detectGraphFreshness` no longer throws on a store whose `meta.json` exists but whose remaining parts do not (an interrupted index); it reports "could not measure", which reads as not-verified.',
+            '`shrk graph status` labels its snapshot size `files indexed` — it deliberately does not move when a new file appears on disk; that shows up on the `drift` line.',
+        ],
+        removed: [],
+    },
+    {
+        version: '0.1.0-alpha.29',
+        title: 'The exit code has to agree with the sentence',
+        added: [
+            '`shrk check wiring --fix` — deterministic autofix for the mechanically-unambiguous `declared-but-not-registered` case: append the missing id to its sink array. Dry-run by default, `--write` applies. Refuses ambiguity (N sinks, non-array sink, non-unique file/array, chain rules, parity violations) and lists what it left alone WITH the reason — it never guesses.',
+            '`shrk explain <ruleId>` resolves a rule id across ALL planes and dispatches to the right explainer; a non-rule token still gets the original topic search. The per-plane forms remain.',
+            'A shared `gate` envelope (`sharkcraft.gate/v1`) inside every gate verb\'s `--json`: `verb` / `exit` / normalized per-rule `{id,type,status,severity,counts,violations,skipReason}`. Additive — the per-plane payloads are unchanged. See docs/gate-json.md.',
+            'Global `--no-hints` silences the advisory piped-exit note (the structured `--exit-trailer` channel is unaffected).',
+            'Exit code `3` = usage error (unloadable config / unknown rule id / bad flag value) on the gate verbs, split out of `2` so "the gate proved nothing" and "the gate never started" are distinguishable.',
+        ],
+        changed: [
+            'A SKIPPED rule is no longer masked by a passing sibling. `failOnEmpty` now defaults to TRUE for `error`-severity rules (an error rule matching zero subjects is a bug in the rule, not a pass) and any skip with no failures exits `2`, never `0`. `warning`-severity rules still default to `false`. BEHAVIOUR CHANGE: an error-severity rule that matches nothing now exits `1` — fix the selector or set `failOnEmpty: false`.',
+            '`shrk help <multi-word verb>` resolves catalog-documented paths (`check wiring`, `wiring unprovided`, …) that are dispatched from a parent handler and therefore never appear in the command trie; it also lists sibling verbs. Previously answered "Unknown command".',
+            '`shrk baseline explain` always computes the CURRENT side, so a rule with no committed artifact yet reports `committed (none yet) → N now` instead of a false `0 now`. `baseline check` names what would be blessed.',
+            '`shrk registry` accepts both argument orders — `registry list <name>` now works alongside `registry <name> list`; a verb-first call with an unknown name names the correct grammar.',
+            '`shrk policy-lint` returns `3` (usage) rather than `1` (violations) when the config cannot be loaded, and `2` when it scanned nothing.',
+            'The piped-exit note is emitted at most once per process.',
+        ],
+        removed: [],
+    },
 ];

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;AAw6BhC,eAAO,MAAM,YAAY,EAAE,eA+G1B,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;AA2jChC,eAAO,MAAM,YAAY,EAAE,eA+G1B,CAAC"}

package/dist/commands/check.command.js

@@ -9,7 +9,8 @@ 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, explainWiring, loadTsconfigPaths, runWiring, scanImports, summarizeImports, } from '@shrkcrft/boundaries';
+import { evaluateBoundaries, explainWiring, loadTsconfigPaths, runWiring, scanImports, summarizeImports, planWiringFix, readMatchingFiles, wiringGlobsOf, } from '@shrkcrft/boundaries';
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
 function knowledgeGroup(inspection) {
     const dup = inspection.validationIssues.filter((i) => i.code === 'duplicate-id');
     const missing = inspection.validationIssues.filter((i) => i.code !== 'duplicate-id');
@@ -523,7 +524,8 @@ async function checkBoundariesOnce(args) {
 // ────────────────────────────────────────────────────────────────────────
 // Subcommand: wiring — "declared but not wired" completeness checks
 // ────────────────────────────────────────────────────────────────────────
-const WIRING_CHECK_USAGE = 'shrk check wiring [--changed-only] [--since <ref>] [--base <ref>] [--only <ids>] [--explain <ruleId>] [--json] [--strict]\n' +
+const WIRING_CHECK_USAGE = 'shrk check wiring [--changed-only] [--since <ref>] [--base <ref>] [--only <ids>] [--explain <ruleId>]\n' +
+    '                  [--fix [--write]] [--json] [--strict]\n' +
     '  Cross-file "declared but not wired" completeness gate. Scope flags select rules by\n' +
     '  FOOTPRINT — a rule fires when the diff touches EITHER its declared or its registered\n' +
     '  side (so a registration edited in file B fires a rule declared in file A).\n' +
@@ -531,7 +533,105 @@ const WIRING_CHECK_USAGE = 'shrk check wiring [--changed-only] [--since <ref>] [
     '    --since <ref>    scope the diff to changes since <ref> (--base is a synonym)\n' +
     '    --only <ids>     run only these rule ids (comma-separated)\n' +
     '    --explain <id>   dry-run ONE rule and print the declared/registered sets it extracts\n' +
+    '    --fix            plan the deterministic repair (append the token to its sink array);\n' +
+    '                     dry-run by default, prints every edit AND any import it must add.\n' +
+    '                     Refuses anything ambiguous — see `needs-import` in docs/wiring.md.\n' +
+    '    --write          apply the planned edits (only meaningful with --fix)\n' +
     '  Exit: 0 verified pass · 1 violations · 2 not-verified (0 rules evaluated in scope).';
+/**
+ * The honest exit code for a wiring run.
+ *
+ * The banner already said "Not a full green" when some rules were skipped, but
+ * the code an agent chains on returned `0` — a rule that enforced NOTHING was
+ * masked by its passing siblings. The verdict must match the sentence:
+ *
+ *   `1` violations (or a `failOnEmpty` skip, which the engine folds into the verdict)
+ *   `2` nothing evaluated, OR anything skipped — partially verified is not verified
+ *   `0` only when every configured rule actually ran and passed
+ */
+function wiringExitCode(report, evaluated) {
+    if (report.verdict === 'errors')
+        return ExitCode.Failure;
+    if (evaluated === 0)
+        return ExitCode.NotVerified;
+    if (report.skipped.length > 0)
+        return ExitCode.NotVerified;
+    return ExitCode.VerifiedPass;
+}
+/**
+ * `check wiring --fix` — append a declared-but-unregistered token to its sink
+ * array, but ONLY where the edit is mechanically unambiguous.
+ *
+ * Dry-run by default: it prints the exact diff it would make and writes
+ * nothing. `--write` applies it. Anything the planner will not touch is listed
+ * with the reason, because a gate that silently half-fixes is worse than one
+ * that does nothing — the user must be able to see what was left.
+ */
+function runWiringFix(cwd, rules, report, write, wantJson) {
+    const allEdits = [];
+    const allSkips = [];
+    // Read every file a sink could live in, once.
+    const globs = [...new Set(rules.flatMap((r) => wiringGlobsOf(r)))];
+    const cache = readMatchingFiles(cwd, globs, new Set());
+    const files = [...cache.entries()].map(([path, content]) => ({ path, content }));
+    for (const rule of rules) {
+        const violations = report.violations.filter((v) => v.ruleId === rule.id);
+        if (violations.length === 0)
+            continue;
+        const plan = planWiringFix(rule, violations, files);
+        allEdits.push(...plan.edits);
+        allSkips.push(...plan.skipped);
+    }
+    // One write per file: the planner threads each file's content forward, so the
+    // LAST edit for a path carries every earlier insertion.
+    const finalByFile = new Map();
+    for (const e of allEdits)
+        finalByFile.set(e.file, e.nextContent);
+    let written = 0;
+    if (write) {
+        for (const [rel, content] of finalByFile) {
+            writeFileSync(nodePath.resolve(cwd, rel), content, 'utf8');
+            written += 1;
+        }
+    }
+    if (wantJson) {
+        process.stdout.write(asJson({
+            schema: 'sharkcraft.wiring-fix/v1',
+            applied: write,
+            filesWritten: written,
+            edits: allEdits.map(({ nextContent: _drop, ...rest }) => rest),
+            skipped: allSkips,
+        }) + '\n');
+        return allEdits.length === 0 && allSkips.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
+    }
+    process.stdout.write(header(write ? 'Wiring fix (applied)' : 'Wiring fix (dry run)'));
+    if (allEdits.length === 0 && allSkips.length === 0) {
+        process.stdout.write('  Nothing to fix — no declared-but-unregistered tokens.\n');
+        return ExitCode.VerifiedPass;
+    }
+    for (const e of allEdits) {
+        process.stdout.write(`  ${write ? 'wrote  ' : 'would add'} ${e.token} → ${e.file}:${e.line}\n`);
+        // Show BOTH halves of the edit. An array append whose import is invisible
+        // in the preview is exactly how the reviewer approves a change they have
+        // not actually seen — and the import is the half that decides whether the
+        // result compiles.
+        if (e.importInsert !== undefined) {
+            process.stdout.write(`      + ${e.importInsert}${e.importLine !== undefined ? `   (line ${e.importLine})` : ''}\n`);
+        }
+        process.stdout.write(`      + ${e.insert}${e.importInsert !== undefined ? `   (line ${e.line})` : ''}\n`);
+    }
+    if (allSkips.length > 0) {
+        process.stdout.write(`\n  Left untouched (${allSkips.length}) — not mechanically unambiguous:\n`);
+        for (const sk of allSkips) {
+            process.stdout.write(`    • ${sk.token}  [${sk.reason}] ${sk.detail}\n`);
+        }
+    }
+    process.stdout.write(write
+        ? `\n${written} file(s) written. Re-run \`shrk check wiring\` to confirm, and review the diff.\n`
+        : '\nDry run — nothing written. Re-run with `--write` to apply.\n');
+    // An unfixable violation still means the gate is red.
+    return allSkips.length > 0 ? ExitCode.Failure : ExitCode.VerifiedPass;
+}
 async function checkWiring(args) {
     const cwd = resolveCwd(args);
     // `--help`/`-h` on the subverb documents its own scoping flags instead of
@@ -570,7 +670,7 @@ async function checkWiring(args) {
         const explainId = flagString(args, 'explain');
         if (!explainId) {
             process.stderr.write('Usage: shrk check wiring --explain <ruleId> [--json]\n');
-            return 2;
+            return ExitCode.UsageError;
         }
         const rule = rules.find((r) => r.id === explainId);
         if (!rule) {
@@ -580,7 +680,7 @@ async function checkWiring(args) {
                 return 2;
             }
             process.stderr.write(`No wiring rule "${explainId}". Configured rules: ${ids.length > 0 ? ids.join(', ') : '(none)'}\n`);
-            return 2;
+            return ExitCode.UsageError;
         }
         return renderWiringExplain(explainWiring(cwd, rule), wantJson);
     }
@@ -637,6 +737,10 @@ async function checkWiring(args) {
     // blast radius, not just the rules whose literal files were edited (a25 §3.2).
     const selectedRuleIds = report.rules.map((r) => r.ruleId);
     const scoped = changedOnly || since !== undefined;
+    // ── --fix: deterministic, heavily-guarded autofix ─────────────────────
+    if (flagBool(args, 'fix')) {
+        return runWiringFix(cwd, rules, report, flagBool(args, 'write'), wantJson);
+    }
     if (wantJson) {
         // Carry the honest counts so a machine consumer can tell "0 evaluated" from
         // a real green, and see how many rules the scope skipped + which fired.
@@ -650,15 +754,31 @@ async function checkWiring(args) {
             notVerified,
             selectedRuleIds,
             // Distinguish verified-pass / failure / not-verified for a chained gate.
-            exitCode: evaluated === 0 ? ExitCode.NotVerified : report.verdict === 'errors' ? ExitCode.Failure : ExitCode.VerifiedPass,
+            exitCode: wiringExitCode(report, evaluated),
+            // One shape across every plane — see docs/gate-json.md.
+            gate: buildGateEnvelope('check wiring', wiringExitCode(report, evaluated), report.rules.map((r) => {
+                const skip = report.skipped.find((s) => s.ruleId === r.ruleId);
+                return {
+                    id: r.ruleId,
+                    type: 'wiring',
+                    status: r.status,
+                    severity: r.severity,
+                    counts: { declared: r.declaredCount, registered: r.registeredCount },
+                    violations: r.violations.map((v) => ({
+                        id: v.token,
+                        file: v.file,
+                        line: v.line,
+                        ...(v.message ? { message: v.message } : {}),
+                        ...(v.hint ? { hint: v.hint } : {}),
+                    })),
+                    ...(skip ? { skipReason: skip.reason } : {}),
+                    ...(r.error ? { error: r.error } : {}),
+                };
+            })),
         }) + '\n');
         // `evaluated === 0` = nothing checked in scope → NOT verified (`2`), never a
         // silent `0` an agent's `&& next` would march past (a25 §1.1).
-        return evaluated === 0
-            ? ExitCode.NotVerified
-            : report.verdict === 'errors'
-                ? ExitCode.Failure
-                : ExitCode.VerifiedPass;
+        return wiringExitCode(report, evaluated);
     }
     process.stdout.write(header('Wiring check'));
     // `evaluated` counts rules that actually ran a comparison (globs matched >0
@@ -707,6 +827,11 @@ async function checkWiring(args) {
             continue;
         process.stdout.write(`\n  ! ${r.ruleId}: the registered side extracted 0 ids while ${r.declaredCount} were declared —\n` +
             `    every declared token "fails". Check the registered glob before chasing the tokens.\n`);
+        // When the engine knows WHY the sink came back empty, say it here — the
+        // generic advice above would otherwise send the reader to inspect a glob
+        // that is perfectly fine.
+        if (r.sinkHint)
+            process.stdout.write(`    → ${r.sinkHint}\n`);
     }
     if (report.violations.length === 0 && report.diagnostics.length === 0) {
         // A failOnEmpty skip produces no violation object but IS a failure.
@@ -722,10 +847,10 @@ async function checkWiring(args) {
             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;
+        return wiringExitCode(report, evaluated);
     }
     if (report.violations.length === 0) {
-        return report.verdict === 'errors' ? 1 : 0;
+        return wiringExitCode(report, evaluated);
     }
     // Group by rule for a readable report.
     for (const r of report.rules) {

package/dist/commands/code-intel.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code-intel.command.d.ts","sourceRoot":"","sources":["../../src/commands/code-intel.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAuE9B,CAAC"}
+{"version":3,"file":"code-intel.command.d.ts","sourceRoot":"","sources":["../../src/commands/code-intel.command.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA6E9B,CAAC"}

package/dist/commands/code-intel.command.js

@@ -1,5 +1,6 @@
 import { buildCodeIntelligenceChecks, DoctorSeverity, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { detectGraphFreshness } from '@shrkcrft/graph';
 import { asJson, header, kv } from "../output/format-output.js";
 /**
  * `shrk code-intel` — one-shot view of the 14 code-intelligence
@@ -28,7 +29,10 @@ export const codeIntelCommand = {
         const checkId = flagString(args, 'check');
         const staleDaysRaw = flagString(args, 'stale-days');
         const staleDays = staleDaysRaw ? Number.parseInt(staleDaysRaw, 10) : undefined;
-        const options = {};
+        // Divergence against the working tree — the SAME check `shrk graph status`
+        // reports, so the two surfaces cannot contradict each other. Injected
+        // because `@shrkcrft/graph` sits above inspector in the layer order.
+        const options = { graphDivergence: detectGraphFreshness(cwd) };
         if (typeof staleDays === 'number' && Number.isFinite(staleDays) && staleDays > 0) {
             options.staleThresholdDays = staleDays;
         }

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

package/dist/commands/command-catalog.js

@@ -406,6 +406,14 @@ export const COMMAND_CATALOG = Object.freeze([
         surface: CommandSurface.Common,
         taskRole: CommandTaskRole.Validate,
     }),
+    entry({
+        command: 'check wiring --fix',
+        description: 'Deterministic autofix for `declared-but-not-registered`: append the missing id to its sink array. Dry-run by default; `--write` applies. Refuses anything ambiguous (N sinks, non-array sink, non-unique file/array) and lists what it left alone with the reason — it never guesses. [--write] [--json]',
+        category: 'core',
+        safetyLevel: SafetyLevel.WritesSource,
+        surface: CommandSurface.Advanced,
+        taskRole: CommandTaskRole.Apply,
+    }),
     entry({
         command: 'policy-lint explain',
         description: 'Dry-run ONE policyRule and print every hit with file:line — INCLUDING the hits an exemption (exemptFiles / exemptLines) or the lexical scan zone dropped, each labelled with which one applied. The author-loop view of what the gate sees. [--json]',

package/dist/commands/daily.commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daily.commands.d.ts","sourceRoot":"","sources":["../../src/commands/daily.commands.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,WAAW,EAAE,eAsFzB,CAAC;AAcF,eAAO,MAAM,WAAW,EAAE,eAoGzB,CAAC;AAKF,eAAO,MAAM,cAAc,EAAE,eAyG5B,CAAC"}
+{"version":3,"file":"daily.commands.d.ts","sourceRoot":"","sources":["../../src/commands/daily.commands.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAOhC,eAAO,MAAM,WAAW,EAAE,eAsFzB,CAAC;AAcF,eAAO,MAAM,WAAW,EAAE,eAoGzB,CAAC;AAKF,eAAO,MAAM,cAAc,EAAE,eAmH5B,CAAC"}

package/dist/commands/daily.commands.js

@@ -2,6 +2,7 @@ import { buildAiReadinessReport, buildTaskPacket, inspectSharkcraft, runDoctor,
 import { recommendPresets } from '@shrkcrft/presets';
 import { flagBool, flagNumber, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { tryExplainGateRule } from "./gates.command.js";
 // ────────────────────────────────────────────────────────────────────────
 // shrk next — "what should I do right now in this repo?"
 // ────────────────────────────────────────────────────────────────────────
@@ -177,9 +178,18 @@ export const explainCommand = {
     async run(args) {
         const topic = args.positional.join(' ').trim();
         if (!topic) {
-            process.stderr.write('Usage: shrk explain "<topic>"\n');
+            process.stderr.write('Usage: shrk explain "<topic>"   (a topic, or the id of any data-defined rule)\n');
             return 2;
         }
+        // A single token that exactly names a declared rule on ANY plane is
+        // explained as that rule — the one entrypoint the trust layer promises.
+        // Anything else keeps the original topic search, so no existing call
+        // changes meaning.
+        if (args.positional.length === 1) {
+            const asRule = await tryExplainGateRule(args, topic);
+            if (asRule !== undefined)
+                return asRule;
+        }
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const maxEntries = flagNumber(args, 'max-entries') ?? 6;
         const packet = buildTaskPacket(inspection, topic, { maxTokens: 2500 });