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

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. */
@@ -157,7 +159,7 @@ function evaluateRule(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',
@@ -235,7 +237,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 +247,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));
     }
@@ -329,9 +331,10 @@ export const generatedCheckCommand = {
         const outcomes = prep.rules.map((r) => evaluateRule(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 +346,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: hintFor(o.rule),
+                        })),
+                        ...o.provenance.map((f) => ({
+                            id: f.file,
+                            file: f.file,
+                            message: f.message,
+                            hint: hintFor(o.rule),
+                        })),
+                    ],
+                    ...(o.skipReason ? { skipReason: o.skipReason } : {}),
+                    ...(o.error ? { error: o.error } : {}),
+                }))),
             }) + '\n');
             return exit;
         }
@@ -460,7 +490,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,7 +498,7 @@ 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);

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

package/dist/commands/policy-lint.command.js

@@ -2,6 +2,8 @@ import * as nodePath from 'node:path';
 import { runPolicyLint, } from '@shrkcrft/boundaries';
 import { classifyChangedScope, resolveChangedFiles, resolveProjectConfig } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { ExitCode } from "../exit-codes.js";
+import { buildGateEnvelope } from "../gates/gate-envelope.js";
 import { asJson, header, kv } from "../output/format-output.js";
 const VALID_SURFACES = new Set(['template', 'style', 'ts']);
 export const POLICY_EXPLAIN_SCHEMA = 'sharkcraft.policy-explain/v1';
@@ -86,19 +88,19 @@ export const policyLintExplainCommand = {
         const id = args.positional[0] ?? flagString(args, 'id');
         if (!id) {
             process.stderr.write('Usage: shrk policy-lint explain <ruleId> [--json]\n');
-            return 2;
+            return ExitCode.UsageError;
         }
         const cwd = resolveCwd(args);
         const loaded = await resolveProjectConfig(cwd);
         if (!loaded.ok) {
             process.stderr.write(`Could not load config: ${loaded.error.message}\n`);
-            return 2;
+            return ExitCode.UsageError;
         }
         const rules = loaded.value.config.policyRules ?? [];
         const rule = rules.find((r) => r.id === id);
         if (!rule) {
             process.stderr.write(`No policy rule "${id}". Configured: ${rules.map((r) => r.id).join(', ') || '(none)'}\n`);
-            return 2;
+            return ExitCode.UsageError;
         }
         const rel = nodePath.relative(cwd, loaded.value.sharkcraftDir).split(nodePath.sep).join('/');
         const excludeDirs = rel && !rel.startsWith('..') ? [rel] : [];
@@ -127,7 +129,7 @@ export const policyLintCommand = {
             const bad = parts.filter((s) => !VALID_SURFACES.has(s));
             if (bad.length > 0) {
                 process.stderr.write(`Unknown --surface "${bad.join(', ')}". Use template | style | ts.\n`);
-                return 2;
+                return ExitCode.UsageError;
             }
             surfaces = parts;
         }
@@ -137,11 +139,12 @@ export const policyLintCommand = {
             const msg = loaded.error.message;
             if (wantJson) {
                 process.stdout.write(asJson({ schema: 'sharkcraft.policy-lint/v1', error: msg, rules: [], findings: [], diagnostics: [msg], evaluated: 0, verdict: 'errors' }) + '\n');
-                return 1;
+                return ExitCode.UsageError;
             }
             process.stdout.write(header('Policy lint'));
             process.stdout.write(`  ✗ Could not load config: ${msg}\n  Run \`shrk doctor\` for details.\n`);
-            return 1;
+            // A broken config is a USAGE error (3), not "violations found" (1).
+            return ExitCode.UsageError;
         }
         const rules = loaded.value.config.policyRules ?? [];
         const planeDiagnostics = loaded.value.planeDiagnostics;
@@ -162,7 +165,7 @@ export const policyLintCommand = {
             const unknown = requested.filter((id) => !known.has(id));
             if (unknown.length > 0) {
                 process.stderr.write(`Unknown --only rule id(s): ${unknown.join(', ')}. Configured: ${[...known].join(', ') || '(none)'}\n`);
-                return 2;
+                return ExitCode.UsageError;
             }
         }
         let changedFiles;
@@ -218,8 +221,41 @@ export const policyLintCommand = {
             report = { ...report, findings: newFindings, verdict };
         }
         if (wantJson) {
-            process.stdout.write(asJson({ ...report, ...(newOnly ? { newOnly: true, hiddenBaseline } : {}) }) + '\n');
-            return report.verdict === 'errors' ? 1 : 0;
+            const exit = report.verdict === 'errors' || report.skipped.some((sk) => sk.failed)
+                ? ExitCode.Failure
+                : report.evaluated === 0 || report.skipped.length > 0
+                    ? ExitCode.NotVerified
+                    : ExitCode.VerifiedPass;
+            process.stdout.write(asJson({
+                ...report,
+                ...(newOnly ? { newOnly: true, hiddenBaseline } : {}),
+                gate: buildGateEnvelope('policy-lint', exit, report.rules.map((r) => {
+                    const skip = report.skipped.find((s) => s.ruleId === r.ruleId);
+                    return {
+                        id: r.ruleId,
+                        type: 'policy',
+                        status: r.status,
+                        severity: r.severity,
+                        counts: {
+                            units: r.unitsScanned,
+                            findings: r.findingCount,
+                            suppressed: r.suppressedCount,
+                        },
+                        violations: report.findings
+                            .filter((f) => f.ruleId === r.ruleId)
+                            .map((f) => ({
+                            id: f.match,
+                            file: f.file,
+                            line: f.line,
+                            message: f.message,
+                            ...(f.suggest ? { hint: f.suggest } : {}),
+                        })),
+                        ...(skip ? { skipReason: skip.reason } : {}),
+                        ...(r.error ? { error: r.error } : {}),
+                    };
+                })),
+            }) + '\n');
+            return exit;
         }
         process.stdout.write(header('Policy lint'));
         // `evaluated` counts rules that actually scanned ≥1 file. When 0 rules
@@ -254,9 +290,15 @@ export const policyLintCommand = {
                 process.stdout.write(`  ! ${d}\n`);
         }
         if (report.skipped.some((sk) => sk.failed)) {
-            process.stdout.write('\nA rule with `failOnEmpty: true` matched nothing — that is a bug in the rule, not a pass.\n');
+            process.stdout.write('\nA rule that matched nothing is a bug in the rule, not a pass. (`error`-severity\n' +
+                '  rules fail on empty by default — set `failOnEmpty: false` if the set may be empty.)\n');
             return 1;
         }
+        // A non-failing skip still means "partially verified" — never a green 0.
+        if (report.skipped.length > 0 && report.findings.length === 0) {
+            process.stdout.write(`\n${report.skipped.length} rule(s) scanned nothing — partially verified, not a full green.\n`);
+            return 2;
+        }
         if (report.findings.length === 0 && report.diagnostics.length === 0) {
             process.stdout.write(newOnly
                 ? `\nNo NEW policy violations from this change${hiddenBaseline > 0 ? ` (${hiddenBaseline} pre-existing hidden)` : ''}. ✓\n`

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

@@ -1 +1 @@
-{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,wBAAwB,EAAE,eA8CtC,CAAC;AAoLF,eAAO,MAAM,eAAe,EAAE,eA4B7B,CAAC"}
+{"version":3,"file":"registry.command.d.ts","sourceRoot":"","sources":["../../src/commands/registry.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC,eAAO,MAAM,wBAAwB,EAAE,eA8CtC,CAAC;AAkMF,eAAO,MAAM,eAAe,EAAE,eA0C7B,CAAC"}

package/dist/commands/registry.command.js

@@ -20,6 +20,8 @@ import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { ExitCode } from "../exit-codes.js";
 import { asJson } from "../output/format-output.js";
 import { resolveRegistryNoun } from "./registry-resolve.js";
+/** The inventory verbs, used to detect (and forgive) a verb-first invocation. */
+const INVENTORY_VERBS = new Set(['list', 'exists', 'where', 'duplicates']);
 export const registryLifecycleCommand = {
     name: 'lifecycle',
     description: 'Scan the workspace for register/remove symmetry. Read-only.',
@@ -98,11 +100,20 @@ async function runRegistryInventory(args, name) {
     if (!decl) {
         const names = loaded.registries.map((r) => r.name);
         const avail = names.length > 0 ? `Declared registries: ${names.join(', ')}.` : 'No registries declared in sharkcraft.config.ts `registries[]`.';
-        if (json)
-            process.stdout.write(asJson({ error: `unknown registry "${name}"`, available: names }) + '\n');
-        else
+        // Typing the verb first is the common stumble (siblings are verb-first).
+        // Name the correct grammar instead of only reporting the miss.
+        const verbFirst = INVENTORY_VERBS.has(name);
+        if (json) {
+            process.stdout.write(asJson({ error: `unknown registry "${name}"`, available: names, ...(verbFirst ? { hint: `did you mean 'registry <name> ${name}'?` } : {}) }) + '\n');
+        }
+        else {
             process.stderr.write(`No registry named "${name}". ${avail}\n`);
-        return 2;
+            if (verbFirst) {
+                const example = names[0] ?? '<name>';
+                process.stderr.write(`"${name}" is a verb, not a registry — did you mean \`shrk registry ${example} ${name}\`?\n`);
+            }
+        }
+        return ExitCode.UsageError;
     }
     const inventory = scanRegistry(cwd, decl);
     if (action === 'list' || action === undefined) {
@@ -125,13 +136,13 @@ async function runRegistryInventory(args, name) {
     if (action === 'exists') {
         if (!id) {
             process.stderr.write(`Usage: shrk registry ${name} exists <id> [--resolve] [--fail-if-taken|--fail-if-missing]\n`);
-            return 2;
+            return ExitCode.UsageError;
         }
         const failIfTaken = flagBool(args, 'fail-if-taken');
         const failIfMissing = flagBool(args, 'fail-if-missing');
         if (failIfTaken && failIfMissing) {
             process.stderr.write('Pass at most one of --fail-if-taken / --fail-if-missing.\n');
-            return 2;
+            return ExitCode.UsageError;
         }
         // `--resolve` maps a human noun to the canonical registered id before the
         // existence test — via the registry's declared `aliases` map AND generic
@@ -201,7 +212,7 @@ async function runRegistryInventory(args, name) {
     if (action === 'where') {
         if (!id) {
             process.stderr.write(`Usage: shrk registry ${name} where <id>\n`);
-            return 2;
+            return ExitCode.UsageError;
         }
         const entry = registryWhere(inventory, id);
         if (json) {
@@ -220,7 +231,7 @@ async function runRegistryInventory(args, name) {
         return 0;
     }
     process.stderr.write(`Unknown action "${action}". Usage: shrk registry ${name} list | exists <id> | where <id> | duplicates\n`);
-    return 2;
+    return ExitCode.UsageError;
 }
 export const registryCommand = {
     name: 'registry',
@@ -237,7 +248,21 @@ export const registryCommand = {
             return registryLifecycleCommand.run(args);
         }
         if (sub !== undefined && sub.length > 0) {
-            // `<name> list | exists <id> | where <id>` — sub is the registry name.
+            // Grammar is `registry <name> <verb>`, but `baseline`/`generated` read
+            // verb-first, so `registry list <name>` is the instinctive form. Accept
+            // BOTH: when arg1 is a known verb and arg2 names a declared registry,
+            // swap them. The canonical order is unchanged; the stumble is removed.
+            const second = args.positional[1];
+            if (INVENTORY_VERBS.has(sub) && second !== undefined && second.length > 0) {
+                const loaded = await loadRegistries(resolveCwd(args));
+                const known = loaded.ok && findRegistry(loaded.registries, second) !== undefined;
+                if (known) {
+                    // [verb, name, ...rest] → [name, verb, ...rest]
+                    args.positional = [second, sub, ...args.positional.slice(2)];
+                    return runRegistryInventory(args, second);
+                }
+            }
+            // `<name> list | exists <id> | where <id> | duplicates` — sub is the name.
             return runRegistryInventory(args, sub);
         }
         const cwd = resolveCwd(args);

package/dist/exit-codes.d.ts

@@ -12,12 +12,19 @@
  *   0  VerifiedPass  — checks ran over a NON-EMPTY scope and passed. Never
  *                      returned when zero units were evaluated.
  *   1  Failure       — checks ran and found violations.
- *   2  NotVerified   — indeterminate: empty evaluation scope, degraded
- *                      fallback, short-circuit, timeout, or "refused to run".
- *                      Distinct from both pass and fail so a chain can branch
- *                      on it (`|| handle-indeterminate`). This is also the
- *                      code the CLI already uses for usage errors — both mean
- *                      "did not produce a verified result".
+ *   2  NotVerified   — indeterminate: empty evaluation scope, all rules
+ *                      skipped, degraded fallback, short-circuit, timeout, or
+ *                      "refused to run". Distinct from both pass and fail so a
+ *                      chain can branch on it (`|| handle-indeterminate`).
+ *   3  UsageError    — the request itself was malformed: unloadable config, an
+ *                      unknown rule id, a bad flag value. Split out of `2` on
+ *                      the GATE verbs because the two demand different
+ *                      responses: `2` means "the gate ran but proved nothing"
+ *                      (investigate the rules), `3` means "the gate never
+ *                      started" (fix the invocation or the config). Non-gate
+ *                      verbs keep returning `2` for usage errors — widening the
+ *                      split across the whole CLI would churn a documented
+ *                      contract far beyond what it buys.
  *
  * The `gen --typecheck` pre-write gate already refuses-to-nonzero rather than
  * emit an unverified artifact; this generalizes that instinct across the gate
@@ -27,7 +34,8 @@
 export declare enum ExitCode {
     VerifiedPass = 0,
     Failure = 1,
-    NotVerified = 2
+    NotVerified = 2,
+    UsageError = 3
 }
 /**
  * Promote a NotVerified (`2`) exit into a Failure-class nonzero (`1`) when the
@@ -61,12 +69,24 @@ export declare function argvHasExitTrailer(argv: readonly string[]): boolean;
  * so `check boundaries --json` (2 tokens) and a bare `finish` (1) both resolve.
  */
 export declare function isGateVerb(commandPath: string): boolean;
+/**
+ * True when the argv carries the global `--no-hints` (before the `--`
+ * sentinel). Suppresses advisory one-liners like the piped-exit note while
+ * leaving every real diagnostic — and the `--exit-trailer` machine channel —
+ * untouched. For a caller that has already internalised the warning and just
+ * wants clean stderr in captured logs.
+ */
+export declare function argvHasNoHints(argv: readonly string[]): boolean;
+/** Reset the one-time hint latch. Test-only seam. */
+export declare function resetPipeHintLatch(): void;
 /** Injectable surface for {@link emitPipeExitSignal} (isTTY + writer + trailer). */
 export interface IPipeExitOptions {
     /** True when shrk's stdout is NOT a terminal (i.e. piped/redirected). */
     readonly piped: boolean;
     /** True when `--exit-trailer` was requested. */
     readonly trailer: boolean;
+    /** True when `--no-hints` was requested — suppress the advisory note only. */
+    readonly noHints?: boolean;
     /** stderr writer; defaults to `process.stderr.write`. Overridable for tests. */
     readonly write?: (s: string) => void;
 }

package/dist/exit-codes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,oBAAY,QAAQ;IAClB,YAAY,IAAI;IAChB,OAAO,IAAI;IACX,WAAW,IAAI;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAGtE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM9D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAMnE;AA4BD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAMvD;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,GACrB,IAAI,CAWN"}
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,oBAAY,QAAQ;IAClB,YAAY,IAAI;IAChB,OAAO,IAAI;IACX,WAAW,IAAI;IACf,UAAU,IAAI;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAGtE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM9D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAMnE;AA4BD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAMvD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM/D;AASD,qDAAqD;AACrD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,gBAAgB,GACrB,IAAI,CAgBN"}

package/dist/exit-codes.js

@@ -12,12 +12,19 @@
  *   0  VerifiedPass  — checks ran over a NON-EMPTY scope and passed. Never
  *                      returned when zero units were evaluated.
  *   1  Failure       — checks ran and found violations.
- *   2  NotVerified   — indeterminate: empty evaluation scope, degraded
- *                      fallback, short-circuit, timeout, or "refused to run".
- *                      Distinct from both pass and fail so a chain can branch
- *                      on it (`|| handle-indeterminate`). This is also the
- *                      code the CLI already uses for usage errors — both mean
- *                      "did not produce a verified result".
+ *   2  NotVerified   — indeterminate: empty evaluation scope, all rules
+ *                      skipped, degraded fallback, short-circuit, timeout, or
+ *                      "refused to run". Distinct from both pass and fail so a
+ *                      chain can branch on it (`|| handle-indeterminate`).
+ *   3  UsageError    — the request itself was malformed: unloadable config, an
+ *                      unknown rule id, a bad flag value. Split out of `2` on
+ *                      the GATE verbs because the two demand different
+ *                      responses: `2` means "the gate ran but proved nothing"
+ *                      (investigate the rules), `3` means "the gate never
+ *                      started" (fix the invocation or the config). Non-gate
+ *                      verbs keep returning `2` for usage errors — widening the
+ *                      split across the whole CLI would churn a documented
+ *                      contract far beyond what it buys.
  *
  * The `gen --typecheck` pre-write gate already refuses-to-nonzero rather than
  * emit an unverified artifact; this generalizes that instinct across the gate
@@ -29,6 +36,7 @@ export var ExitCode;
     ExitCode[ExitCode["VerifiedPass"] = 0] = "VerifiedPass";
     ExitCode[ExitCode["Failure"] = 1] = "Failure";
     ExitCode[ExitCode["NotVerified"] = 2] = "NotVerified";
+    ExitCode[ExitCode["UsageError"] = 3] = "UsageError";
 })(ExitCode || (ExitCode = {}));
 /**
  * Promote a NotVerified (`2`) exit into a Failure-class nonzero (`1`) when the
@@ -116,6 +124,32 @@ export function isGateVerb(commandPath) {
         return true;
     return false;
 }
+/**
+ * True when the argv carries the global `--no-hints` (before the `--`
+ * sentinel). Suppresses advisory one-liners like the piped-exit note while
+ * leaving every real diagnostic — and the `--exit-trailer` machine channel —
+ * untouched. For a caller that has already internalised the warning and just
+ * wants clean stderr in captured logs.
+ */
+export function argvHasNoHints(argv) {
+    for (const t of argv) {
+        if (t === '--')
+            break;
+        if (t === '--no-hints')
+            return true;
+    }
+    return false;
+}
+/**
+ * Process-lifetime latch for the piped-exit hint. The note is advisory, so it
+ * pays rent once: a command that emits several gate verdicts in one process
+ * (or a `--watch` loop) should not repeat the same paragraph every cycle.
+ */
+let pipeHintEmitted = false;
+/** Reset the one-time hint latch. Test-only seam. */
+export function resetPipeHintLatch() {
+    pipeHintEmitted = false;
+}
 /**
  * Keep the honest `0`/`1`/`2` exit code READABLE through the shape agents reach
  * for first — the trailing pipe. `<gate> | head` reports `head`'s `$?`, so a true
@@ -136,9 +170,14 @@ export function emitPipeExitSignal(commandPath, code, opts) {
     if (!isGateVerb(commandPath))
         return;
     const write = opts.write ?? ((s) => void process.stderr.write(s));
-    if (opts.piped && code !== 0) {
+    // Advisory, and therefore rationed: stderr only, only when a NON-zero verdict
+    // would actually be lost to the pipe, at most once per process, and never
+    // under `--no-hints`. The structured channel (`--exit-trailer`) is unaffected
+    // by all of these — it is opt-in and always emitted when asked.
+    if (opts.piped && code !== 0 && !opts.noHints && !pipeHintEmitted) {
+        pipeHintEmitted = true;
         write(`note: stdout is piped — $? reflects the downstream command, not shrk (exit ${code}); ` +
-            `use PIPESTATUS[0] or --exit-trailer to read shrk's verdict.\n`);
+            `use PIPESTATUS[0] or --exit-trailer to read shrk's verdict (--no-hints silences this).\n`);
     }
     // The trailer is written LAST so it is the final stderr line a caller reads.
     if (opts.trailer)

package/dist/gates/gate-envelope.d.ts

@@ -0,0 +1,64 @@
+/**
+ * One machine-readable shape for every gate verb.
+ *
+ * `--json` has always been available on each plane, but each emitted its own
+ * schema (`sharkcraft.wiring/v1`, `sharkcraft.baseline/v1`, …), so a CI step or
+ * agent had to parse four shapes to answer one question: which rules ran, which
+ * failed, and why. This envelope is that answer, identical across planes.
+ *
+ * It is ADDITIVE. The per-plane payloads are published, documented, and asserted
+ * by tests; replacing them would break every existing consumer. The envelope
+ * rides along under a `gate` key, so `jq .gate` is the uniform read and nothing
+ * that worked before stops working.
+ */
+export declare const GATE_ENVELOPE_SCHEMA: "sharkcraft.gate/v1";
+/** Which data-defined plane produced a rule result. */
+export type GateRuleType = 'wiring' | 'policy' | 'registry' | 'registration' | 'baseline' | 'generated';
+/**
+ * Per-rule outcome, uniform across planes. `skipped` is deliberately a
+ * first-class status, not folded into `passed` — a rule that matched nothing
+ * enforced nothing.
+ */
+export type GateRuleStatus = 'passed' | 'failed' | 'skipped' | 'error';
+/** One violation, normalized. `id` is the offending token / entry / file. */
+export interface IGateViolation {
+    readonly id: string;
+    readonly file?: string;
+    readonly line?: number;
+    readonly message?: string;
+    readonly hint?: string;
+}
+/** One rule's result in the shared envelope. */
+export interface IGateRuleResult {
+    readonly id: string;
+    readonly type: GateRuleType;
+    readonly status: GateRuleStatus;
+    readonly severity: 'error' | 'warning';
+    /**
+     * Plane-appropriate match counts — e.g. `{declared, registered}` for wiring,
+     * `{committed, current}` for baseline, `{units, findings}` for policy. Always
+     * present so "what did this rule actually see?" is answerable uniformly.
+     */
+    readonly counts: Readonly<Record<string, number>>;
+    readonly violations: readonly IGateViolation[];
+    /** Why the rule checked nothing, when `status` is `skipped`. */
+    readonly skipReason?: string;
+    /** Set when the rule is misconfigured (`status: 'error'`). */
+    readonly error?: string;
+}
+/** The envelope emitted under the `gate` key of every gate verb's `--json`. */
+export interface IGateEnvelope {
+    readonly schema: typeof GATE_ENVELOPE_SCHEMA;
+    /** The verb that produced this, space-joined (e.g. `check wiring`). */
+    readonly verb: string;
+    /** The exit code this run returns — the same number the process exits with. */
+    readonly exit: number;
+    readonly rules: readonly IGateRuleResult[];
+    /** Rules that ran a real comparison (status !== 'skipped'). */
+    readonly evaluated: number;
+    readonly skipped: number;
+    readonly failed: number;
+}
+/** Build the envelope from already-normalized per-rule results. */
+export declare function buildGateEnvelope(verb: string, exit: number, rules: readonly IGateRuleResult[]): IGateEnvelope;
+//# sourceMappingURL=gate-envelope.d.ts.map

package/dist/gates/gate-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-envelope.d.ts","sourceRoot":"","sources":["../../src/gates/gate-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,EAAG,oBAA6B,CAAC;AAElE,uDAAuD;AACvD,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,cAAc,GACd,UAAU,GACV,WAAW,CAAC;AAEhB;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvE,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,oBAAoB,CAAC;IAC7C,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,aAAa,CAUf"}