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

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":"AA8BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6ShC,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,eA2DpC,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 { 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) {
@@ -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;
@@ -151,7 +160,7 @@ function evaluateRule(cwd, rule, excludeDirs, changedFiles) {
     if (currentCount === 0 && committedCount === 0) {
         return {
             rule,
-            status: rule.failOnEmpty ? 'failed' : 'skipped',
+            status: failsWhenEmpty(rule) ? 'failed' : 'skipped',
             committed,
             current: computed.text,
             committedCount,
@@ -190,6 +199,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 +226,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) {
@@ -314,9 +324,11 @@ export const baselineCheckCommand = {
         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 +339,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 +368,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;
@@ -414,7 +443,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 +484,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,7 +492,7 @@ 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);
         if (flagBool(args, 'json')) {
@@ -484,7 +513,9 @@ export const baselineExplainCommand = {
         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 +537,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,EAkJjE,CAAC"}

package/dist/commands/changelog-data.js

@@ -134,4 +134,24 @@ export const RELEASE_SURFACE_DELTAS = [
         ],
         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;AA2iChC,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');
@@ -532,6 +533,93 @@ const WIRING_CHECK_USAGE = 'shrk check wiring [--changed-only] [--since <ref>] [
     '    --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' +
     '  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`);
+        process.stdout.write(`      + ${e.insert}\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 +658,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 +668,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 +725,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 +742,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
@@ -722,10 +830,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/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 });

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

@@ -1,6 +1,16 @@
-import { type ICommandHandler } from '../command-registry.js';
+import { type ICommandHandler, type ParsedArgs } from '../command-registry.js';
 export declare const gatesListCommand: ICommandHandler;
 export declare const gatesCoverageCommand: ICommandHandler;
 export declare const gatesExplainCommand: ICommandHandler;
+/**
+ * Try to explain `id` as a data-defined rule on ANY plane.
+ *
+ * Returns the exit code when the id resolves to exactly one declared rule, or
+ * `undefined` when it is not a rule id at all — which lets `shrk explain` keep
+ * its original topic-search behaviour for everything else. This is the D2
+ * unification: a user holding a rule id no longer has to know which plane owns
+ * it, and no existing invocation changes meaning.
+ */
+export declare function tryExplainGateRule(args: ParsedArgs, id: string): Promise<number | undefined>;
 export declare const gatesCommand: ICommandHandler;
 //# sourceMappingURL=gates.command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"gates.command.d.ts","sourceRoot":"","sources":["../../src/commands/gates.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA+EhC,eAAO,MAAM,gBAAgB,EAAE,eAsD9B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA4ElC,CAAC;AAuCF,eAAO,MAAM,mBAAmB,EAAE,eA4FjC,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,eAe1B,CAAC"}
+{"version":3,"file":"gates.command.d.ts","sourceRoot":"","sources":["../../src/commands/gates.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,wBAAwB,CAAC;AAgFhC,eAAO,MAAM,gBAAgB,EAAE,eAsD9B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAuGlC,CAAC;AAuCF,eAAO,MAAM,mBAAmB,EAAE,eA4FjC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B;AAED,eAAO,MAAM,YAAY,EAAE,eAe1B,CAAC"}

package/dist/commands/gates.command.js

@@ -22,6 +22,7 @@ import { ExitCode } from "../exit-codes.js";
 import { asJson, header, kv } from "../output/format-output.js";
 import { collectGateRules, GATE_PLANES, } from "../gates/gate-rule-view.js";
 import { buildGateCoverage } from "../gates/rule-coverage.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
 import { baselineExplainCommand } from "./baseline.command.js";
 import { generatedExplainCommand } from "./generated.command.js";
 import { renderPolicyExplain, runPolicyExplain } from "./policy-lint.command.js";
@@ -37,7 +38,7 @@ async function prepare(args) {
             process.stdout.write(asJson({ schema: SCHEMA, error: msg }) + '\n');
         else
             process.stderr.write(`Could not load config: ${msg}\n  Run \`shrk doctor\` for details.\n`);
-        return { ok: false, code: ExitCode.NotVerified };
+        return { ok: false, code: ExitCode.UsageError };
     }
     const rel = nodePath.relative(cwd, loaded.value.sharkcraftDir).split(nodePath.sep).join('/');
     return {
@@ -89,7 +90,7 @@ export const gatesListCommand = {
             return prep.code;
         const planes = parsePlanes(args);
         if (!planes.ok)
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         const json = flagBool(args, 'json');
         const rules = planes.planes
             ? prep.value.rules.filter((r) => planes.planes.has(r.plane))
@@ -146,7 +147,7 @@ export const gatesCoverageCommand = {
             return prep.code;
         const planes = parsePlanes(args);
         if (!planes.ok)
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         const json = flagBool(args, 'json');
         const rules = planes.planes
             ? prep.value.rules.filter((r) => planes.planes.has(r.plane))
@@ -165,7 +166,29 @@ export const gatesCoverageCommand = {
                 ? ExitCode.NotVerified
                 : ExitCode.VerifiedPass;
         if (json) {
-            process.stdout.write(asJson({ ...report, hardFailures: hardFailures.length, exitCode: exit }) + '\n');
+            process.stdout.write(asJson({
+                ...report,
+                hardFailures: hardFailures.length,
+                exitCode: exit,
+                gate: buildGateEnvelope('gates coverage', exit, report.rules.map((r) => ({
+                    id: r.id,
+                    type: r.plane,
+                    status: r.status === 'ok'
+                        ? 'passed'
+                        : r.status === 'empty'
+                            ? r.failOnEmpty
+                                ? 'failed'
+                                : 'skipped'
+                            : r.status === 'error'
+                                ? 'error'
+                                : 'failed',
+                    severity: r.failOnEmpty ? 'error' : 'warning',
+                    counts: { files: r.filesMatched, units: r.unitsMatched },
+                    violations: r.expectationFailures.map((f) => ({ id: r.id, message: f })),
+                    ...(r.status === 'empty' ? { skipReason: `matched 0 ${r.unitLabel}` } : {}),
+                    ...(r.error ? { error: r.error } : {}),
+                }))),
+            }) + '\n');
             return exit;
         }
         process.stdout.write(header('Gate-rule coverage'));
@@ -244,7 +267,7 @@ export const gatesExplainCommand = {
         const id = args.positional[0] ?? flagString(args, 'id');
         if (!id) {
             process.stderr.write('Usage: shrk gates explain <id> [--json]\n');
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         }
         const prep = await prepare(args);
         if (!prep.ok)
@@ -252,25 +275,25 @@ export const gatesExplainCommand = {
         const matches = prep.value.rules.filter((r) => r.id === id);
         if (matches.length === 0) {
             process.stderr.write(`No gate rule "${id}". Run \`shrk gates list\` to see the ${prep.value.rules.length} declared rule(s).\n`);
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         }
         // An id may legitimately exist on two planes (a wiring rule and a registry
         // can share a name); `--plane` disambiguates instead of guessing.
         const planes = parsePlanes(args);
         if (!planes.ok)
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         const candidates = planes.planes
             ? matches.filter((r) => planes.planes.has(r.plane))
             : matches;
         if (candidates.length > 1) {
             process.stderr.write(`"${id}" exists on ${candidates.length} planes (${candidates.map((c) => c.plane).join(', ')}). ` +
                 'Disambiguate with --plane <p>.\n');
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         }
         const view = candidates[0];
         if (!view) {
             process.stderr.write(`No gate rule "${id}" on the requested plane.\n`);
-            return ExitCode.NotVerified;
+            return ExitCode.UsageError;
         }
         const json = flagBool(args, 'json');
         // The two shell-executing planes own their explain output (and their trust
@@ -319,6 +342,26 @@ export const gatesExplainCommand = {
         return ExitCode.VerifiedPass;
     },
 };
+/**
+ * Try to explain `id` as a data-defined rule on ANY plane.
+ *
+ * Returns the exit code when the id resolves to exactly one declared rule, or
+ * `undefined` when it is not a rule id at all — which lets `shrk explain` keep
+ * its original topic-search behaviour for everything else. This is the D2
+ * unification: a user holding a rule id no longer has to know which plane owns
+ * it, and no existing invocation changes meaning.
+ */
+export async function tryExplainGateRule(args, id) {
+    const cwd = resolveCwd(args);
+    const loaded = await resolveProjectConfig(cwd);
+    if (!loaded.ok)
+        return undefined;
+    const rules = collectGateRules(loaded.value.config);
+    if (!rules.some((r) => r.id === id))
+        return undefined;
+    const forwarded = { ...args, positional: [id] };
+    return gatesExplainCommand.run(forwarded);
+}
 export const gatesCommand = {
     name: 'gates',
     description: 'Rule-authoring trust layer: list every data-defined rule, show what each one MATCHED (the stale-selector detector), and explain any one of them. Read-only. Not `shrk gate`, which runs the quality-gate pipeline.',
@@ -329,6 +372,6 @@ export const gatesCommand = {
         process.stderr.write((sub ? `Unknown subcommand "${sub}". ` : '') +
             'Usage: shrk gates list | coverage [--plane <p>] [--strict] | explain <id>\n' +
             '(`shrk gate`, singular, runs the quality-gate pipeline — a different verb.)\n');
-        return ExitCode.NotVerified;
+        return ExitCode.UsageError;
     },
 };

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":"AA+BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyShC,eAAO,MAAM,oBAAoB,EAAE,eA2ClC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAuHnC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAmDpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiErC,CAAC"}