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

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/commands/wiring.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wiring.command.d.ts","sourceRoot":"","sources":["../../src/commands/wiring.command.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAoFrF;AAyZD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}
+{"version":3,"file":"wiring.command.d.ts","sourceRoot":"","sources":["../../src/commands/wiring.command.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAwFrF;AAyZD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}

package/dist/commands/wiring.command.js

@@ -28,9 +28,10 @@ export function renderWiringExplain(report, wantJson) {
         process.stdout.write(kv('registeredMode', 'intersection (must be in EVERY sink)') + '\n');
     }
     process.stdout.write(kv('status', report.status) + '\n');
-    process.stdout.write(kv('declared', `${report.declared.distinctCount} distinct across ${report.declared.filesScanned} file(s)`) +
-        '\n');
-    process.stdout.write(kv('registered', `${report.registered.distinctCount} distinct across ${report.registered.filesScanned} file(s)`) + '\n');
+    process.stdout.write(kv('declared', `${report.declared.distinctCount} distinct across ${report.declared.filesScanned} file(s)` +
+        (report.declared.viaExtractor ? `  (via $use:${report.declared.viaExtractor})` : '')) + '\n');
+    process.stdout.write(kv('registered', `${report.registered.distinctCount} distinct across ${report.registered.filesScanned} file(s)` +
+        (report.registered.viaExtractor ? `  (via $use:${report.registered.viaExtractor})` : '')) + '\n');
     if (report.declared.error)
         process.stdout.write(`  ! declared side: ${report.declared.error}\n`);
     if (report.registered.error) {

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' | 'doc-reference';
+/**
+ * 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,GACX,eAAe,CAAC;AAEpB;;;;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"}

package/dist/gates/gate-envelope.js

@@ -0,0 +1,26 @@
+/**
+ * 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 const GATE_ENVELOPE_SCHEMA = 'sharkcraft.gate/v1';
+/** Build the envelope from already-normalized per-rule results. */
+export function buildGateEnvelope(verb, exit, rules) {
+    return {
+        schema: GATE_ENVELOPE_SCHEMA,
+        verb,
+        exit,
+        rules,
+        evaluated: rules.filter((r) => r.status !== 'skipped').length,
+        skipped: rules.filter((r) => r.status === 'skipped').length,
+        failed: rules.filter((r) => r.status === 'failed' || r.status === 'error').length,
+    };
+}

package/dist/gates/gate-rule-globs.d.ts

@@ -0,0 +1,33 @@
+import { type IWiringSource } from '@shrkcrft/core';
+import type { IGateRuleView } from './gate-rule-view.js';
+/**
+ * The FOOTPRINT of a gate rule: every project-relative glob it reads.
+ *
+ * `--changed-only` is only trustworthy if the footprint is complete. A rule
+ * scoped by its declared side alone would go unevaluated when the change edits
+ * the REGISTERED side — a registration deleted in file B silently skipping the
+ * rule declared over file A is the precise bug this plane exists to catch, so
+ * every side, every hop, and every watched input counts.
+ */
+export declare function gateRuleGlobs(view: IGateRuleView): readonly string[];
+/**
+ * EVERY extraction source a rule reads — both wiring sides, every union sink,
+ * every chain hop, a registry's consumer, all three registration roles.
+ *
+ * Collecting all of them (not just the rule's primary side) is what lets the
+ * coverage view name every consumer of a shared extractor. A rule that `$use`s
+ * one on its *registered* side is just as bound to that definition as one that
+ * uses it on `declared`, and listing only half of them would understate exactly
+ * the guarantee the shared extractor exists to provide.
+ */
+export declare function gateRuleSources(view: IGateRuleView): readonly IWiringSource[];
+/**
+ * Whether a rule's footprint intersects the changed set.
+ *
+ * A rule with NO resolvable footprint (a command baseline with no
+ * `watchFiles`) cannot be proven out of scope, so it stays IN scope. Guessing
+ * "probably unaffected" is how a `--changed-only` run silently stops checking
+ * the one thing that broke.
+ */
+export declare function ruleTouchedBy(view: IGateRuleView, changed: readonly string[]): boolean;
+//# sourceMappingURL=gate-rule-globs.d.ts.map

package/dist/gates/gate-rule-globs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-rule-globs.d.ts","sourceRoot":"","sources":["../../src/gates/gate-rule-globs.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,CAqBpE;AAcD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,aAAa,EAAE,CA+B7E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAItF"}

package/dist/gates/gate-rule-globs.js

@@ -0,0 +1,101 @@
+import { resolveSourceGlobs, } from '@shrkcrft/core';
+import { matchesAny } from '@shrkcrft/boundaries';
+/**
+ * The FOOTPRINT of a gate rule: every project-relative glob it reads.
+ *
+ * `--changed-only` is only trustworthy if the footprint is complete. A rule
+ * scoped by its declared side alone would go unevaluated when the change edits
+ * the REGISTERED side — a registration deleted in file B silently skipping the
+ * rule declared over file A is the precise bug this plane exists to catch, so
+ * every side, every hop, and every watched input counts.
+ */
+export function gateRuleGlobs(view) {
+    if (view.plane === 'policy')
+        return view.raw.files ?? [];
+    if (view.plane === 'baseline') {
+        const rule = view.raw;
+        // `watchFiles` is the ONLY footprint a command compute has — without it a
+        // command baseline can never be scoped, so it always runs (see below).
+        return [
+            ...gateRuleSources(view).flatMap(sourceGlobs),
+            ...(rule.watchFiles ?? []),
+            rule.baseline,
+        ];
+    }
+    if (view.plane === 'generated') {
+        const rule = view.raw;
+        return [
+            ...rule.generatedGlob,
+            ...(rule.sources ?? []).flatMap((s) => s.glob),
+            ...(rule.handMaintained ?? []),
+        ];
+    }
+    return gateRuleSources(view).flatMap(sourceGlobs);
+}
+/**
+ * Every glob one source reads: the files it scans, plus an `import-edges`
+ * source's TARGET globs.
+ *
+ * A fence whose footprint covered only the consumer side would go unevaluated
+ * when the target subtree moved — and "cannot be proven out of scope" must
+ * always resolve to staying IN scope, never to a quiet skip.
+ */
+function sourceGlobs(src) {
+    return [...resolveSourceGlobs(src), ...(src.to?.files ?? [])];
+}
+/**
+ * EVERY extraction source a rule reads — both wiring sides, every union sink,
+ * every chain hop, a registry's consumer, all three registration roles.
+ *
+ * Collecting all of them (not just the rule's primary side) is what lets the
+ * coverage view name every consumer of a shared extractor. A rule that `$use`s
+ * one on its *registered* side is just as bound to that definition as one that
+ * uses it on `declared`, and listing only half of them would understate exactly
+ * the guarantee the shared extractor exists to provide.
+ */
+export function gateRuleSources(view) {
+    switch (view.plane) {
+        case 'wiring': {
+            const rule = view.raw;
+            return [
+                rule.declared,
+                ...(Array.isArray(rule.registered)
+                    ? rule.registered
+                    : rule.registered
+                        ? [rule.registered]
+                        : []),
+                ...(rule.chain ?? []),
+            ].filter((s) => s !== undefined);
+        }
+        case 'registry': {
+            const decl = view.raw;
+            return decl.consumer ? [decl.source, decl.consumer] : [decl.source];
+        }
+        case 'registration': {
+            const idiom = view.raw;
+            return [idiom.declared, idiom.provided, idiom.consumed];
+        }
+        case 'baseline': {
+            const source = view.raw.compute.source;
+            return source ? [source] : [];
+        }
+        default:
+            // `policy` and `generated` select files by glob, not by an extraction
+            // source, so neither can reference a shared extractor.
+            return [];
+    }
+}
+/**
+ * Whether a rule's footprint intersects the changed set.
+ *
+ * A rule with NO resolvable footprint (a command baseline with no
+ * `watchFiles`) cannot be proven out of scope, so it stays IN scope. Guessing
+ * "probably unaffected" is how a `--changed-only` run silently stops checking
+ * the one thing that broke.
+ */
+export function ruleTouchedBy(view, changed) {
+    const globs = gateRuleGlobs(view).filter((g) => g.length > 0);
+    if (globs.length === 0)
+        return true;
+    return changed.some((file) => matchesAny(file, globs));
+}