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

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/finish/run-finish.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-finish.d.ts","sourceRoot":"","sources":["../../src/finish/run-finish.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAiB7B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAQ7D,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IAClG,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC;IACnD,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAmBD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAmJnF"}
+{"version":3,"file":"run-finish.d.ts","sourceRoot":"","sources":["../../src/finish/run-finish.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAiB7B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,eAAO,MAAM,aAAa,EAAG,sBAA+B,CAAC;AAQ7D,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IAClG,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC;IACnD,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAmBD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CA2JnF"}

package/dist/finish/run-finish.js

@@ -88,16 +88,22 @@ export async function runFinishGates(input) {
         const report = buildImportHygieneReport(cwd, { files: codeChanged });
         const errors = report.counts?.['error'] ?? (report.verdict === 'errors' ? report.findings.length : 0);
         const warnings = report.counts?.['warning'] ?? (report.verdict === 'warnings' ? report.findings.length : 0);
+        // Only the findings that actually DRIVE the verdict become "failing items".
+        // An allowlisted import is downgraded to `info` by design and is not what
+        // failed — listing it anyway pads the renderer's 15-item cap and can push a
+        // real error out of view, while its allowlist justification reads like a
+        // fix instruction. A fix-list that names non-failures is not a fix-list.
+        const driving = report.findings.filter((f) => report.verdict === 'errors' ? f.severity === 'error' : f.severity === 'warning');
         gates.push({
             name: 'imports',
             status: report.verdict === 'errors' ? 'fail' : 'pass',
-            detail: `verdict=${report.verdict} (${report.findings.length} finding(s))`,
+            detail: `verdict=${report.verdict} (${driving.length} of ${report.findings.length} finding(s) drive it)`,
             errors,
             warnings,
-            items: report.findings.map((f) => ({
+            items: driving.map((f) => ({
                 file: f.file,
                 line: f.line,
-                message: `${f.kind}: ${f.suggestedFix || f.reason || f.snippet}`.trim(),
+                message: `[${f.severity}] ${f.kind}: ${f.suggestedFix || f.reason || f.snippet}`.trim(),
             })),
         });
     }

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

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-view.d.ts

@@ -0,0 +1,35 @@
+import { type IBaselineRule, type IGeneratedArtifactRule, type IPolicyRule, type IRegistrationIdiom, type IRegistryDeclaration, type IRuleSelfTest, type IWiringRule } from '@shrkcrft/core';
+/** Which data-defined plane a rule belongs to. */
+export type GatePlane = 'wiring' | 'policy' | 'registry' | 'registration' | 'baseline' | 'generated';
+/** Every plane, in the order `shrk gates list` prints them. */
+export declare const GATE_PLANES: readonly GatePlane[];
+/**
+ * One data-defined rule, normalized across planes.
+ *
+ * The trust layer's whole job is to answer "what did this rule actually match?"
+ * for ANY rule, so it needs one shape to iterate. The plane-specific rule object
+ * rides along in `raw` for the explain dispatch.
+ */
+export interface IGateRuleView {
+    readonly id: string;
+    readonly plane: GatePlane;
+    readonly description?: string;
+    readonly severity: 'error' | 'warning';
+    /** True when a zero-match is a hard failure rather than a loud skip. */
+    readonly failOnEmpty: boolean;
+    readonly selfTest?: IRuleSelfTest;
+    /** The underlying rule, for the plane-specific explainer. */
+    readonly raw: IWiringRule | IPolicyRule | IRegistryDeclaration | IRegistrationIdiom | IBaselineRule | IGeneratedArtifactRule;
+}
+/** The config planes this view is built from. */
+export interface IGatePlanes {
+    readonly wiringRules?: readonly IWiringRule[];
+    readonly policyRules?: readonly IPolicyRule[];
+    readonly registries?: readonly IRegistryDeclaration[];
+    readonly registrationGraph?: readonly IRegistrationIdiom[];
+    readonly baselines?: readonly IBaselineRule[];
+    readonly generatedArtifacts?: readonly IGeneratedArtifactRule[];
+}
+/** Flatten every declared rule across every plane into one iterable list. */
+export declare function collectGateRules(planes: IGatePlanes): IGateRuleView[];
+//# sourceMappingURL=gate-rule-view.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gate-rule-view.d.ts","sourceRoot":"","sources":["../../src/gates/gate-rule-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAExB,kDAAkD;AAClD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAErG,+DAA+D;AAC/D,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAO3C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EACR,WAAW,GACX,WAAW,GACX,oBAAoB,GACpB,kBAAkB,GAClB,aAAa,GACb,sBAAsB,CAAC;CAC5B;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACtD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACjE;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,EAAE,CAqErE"}

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

@@ -0,0 +1,81 @@
+import { failsWhenEmpty, } from '@shrkcrft/core';
+/** Every plane, in the order `shrk gates list` prints them. */
+export const GATE_PLANES = [
+    'wiring',
+    'policy',
+    'registry',
+    'registration',
+    'baseline',
+    'generated',
+];
+/** Flatten every declared rule across every plane into one iterable list. */
+export function collectGateRules(planes) {
+    const out = [];
+    for (const r of planes.wiringRules ?? []) {
+        out.push({
+            id: r.id,
+            plane: 'wiring',
+            ...(r.description ? { description: r.description } : {}),
+            severity: r.severity ?? 'error',
+            failOnEmpty: failsWhenEmpty(r),
+            ...(r.selfTest ? { selfTest: r.selfTest } : {}),
+            raw: r,
+        });
+    }
+    for (const r of planes.policyRules ?? []) {
+        out.push({
+            id: r.id,
+            plane: 'policy',
+            ...(r.description ? { description: r.description } : {}),
+            severity: r.severity ?? 'error',
+            failOnEmpty: failsWhenEmpty(r),
+            ...(r.selfTest ? { selfTest: r.selfTest } : {}),
+            raw: r,
+        });
+    }
+    for (const r of planes.registries ?? []) {
+        out.push({
+            id: r.name,
+            plane: 'registry',
+            ...(r.description ? { description: r.description } : {}),
+            // A registry is an inventory, not a gate — it never fails a build on its
+            // own, so it carries no severity of its own.
+            severity: 'warning',
+            failOnEmpty: false,
+            raw: r,
+        });
+    }
+    for (const r of planes.registrationGraph ?? []) {
+        out.push({
+            id: r.name,
+            plane: 'registration',
+            ...(r.description ? { description: r.description } : {}),
+            severity: 'warning',
+            failOnEmpty: false,
+            raw: r,
+        });
+    }
+    for (const r of planes.baselines ?? []) {
+        out.push({
+            id: r.id,
+            plane: 'baseline',
+            ...(r.description ? { description: r.description } : {}),
+            severity: r.severity ?? 'error',
+            failOnEmpty: failsWhenEmpty(r),
+            ...(r.selfTest ? { selfTest: r.selfTest } : {}),
+            raw: r,
+        });
+    }
+    for (const r of planes.generatedArtifacts ?? []) {
+        out.push({
+            id: r.id,
+            plane: 'generated',
+            ...(r.description ? { description: r.description } : {}),
+            severity: r.severity ?? 'error',
+            failOnEmpty: failsWhenEmpty(r),
+            ...(r.selfTest ? { selfTest: r.selfTest } : {}),
+            raw: r,
+        });
+    }
+    return out;
+}

package/dist/gates/rule-coverage.d.ts

@@ -0,0 +1,53 @@
+import type { IGateRuleView } from './gate-rule-view.js';
+export declare const GATE_COVERAGE_SCHEMA: "sharkcraft.gate-coverage/v1";
+/**
+ * Whether a rule is connected to anything at all.
+ *
+ * `empty` is the finding this whole surface exists for: a stale selector that
+ * matches nothing passes every gate forever, so the ONLY way to notice is to
+ * report the match count itself and flag zero. `failed-expectation` is the
+ * stronger form — the author wrote down what the rule should match, and it
+ * doesn't.
+ */
+export type GateCoverageStatus = 'ok' | 'empty' | 'error' | 'failed-expectation';
+export interface IGateCoverage {
+    readonly id: string;
+    readonly plane: IGateRuleView['plane'];
+    readonly description?: string;
+    readonly status: GateCoverageStatus;
+    /** Files the rule's primary selector matched. */
+    readonly filesMatched: number;
+    /** Ids/units the rule extracted (findings scanned, for the policy plane). */
+    readonly unitsMatched: number;
+    /** What "units" means for this plane, for honest reporting. */
+    readonly unitLabel: string;
+    /** A few of the extracted ids, so the author can eyeball correctness. */
+    readonly sampleIds: readonly string[];
+    /** True when a zero match is a hard failure for this rule. */
+    readonly failOnEmpty: boolean;
+    readonly error?: string;
+    /** Unmet `selfTest` expectations, each a human-readable sentence. */
+    readonly expectationFailures: readonly string[];
+}
+export interface IGateCoverageReport {
+    readonly schema: typeof GATE_COVERAGE_SCHEMA;
+    readonly rules: readonly IGateCoverage[];
+    readonly total: number;
+    readonly empty: number;
+    readonly errored: number;
+    readonly expectationFailures: number;
+    /**
+     * `pass` — every rule matched something and met its expectations.
+     * `stale` — at least one rule matched nothing (or broke an expectation).
+     */
+    readonly verdict: 'pass' | 'stale';
+}
+/**
+ * Resolve every declared rule against the live tree and report what it matched.
+ *
+ * The `command`-compute baseline is the one rule kind that cannot be inspected
+ * without side effects; it is reported as un-inspected (never as `empty`), so
+ * the report never claims a fact it did not check.
+ */
+export declare function buildGateCoverage(cwd: string, rules: readonly IGateRuleView[], excludeDirs?: readonly string[]): IGateCoverageReport;
+//# sourceMappingURL=rule-coverage.d.ts.map

package/dist/gates/rule-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-coverage.d.ts","sourceRoot":"","sources":["../../src/gates/rule-coverage.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,eAAO,MAAM,oBAAoB,EAAG,6BAAsC,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,GAAG,oBAAoB,CAAC;AAEjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAsHD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,mBAAmB,CA4DrB"}

package/dist/gates/rule-coverage.js

@@ -0,0 +1,165 @@
+import { inspectSource, runPolicyLint, scanGeneratedFiles, wiringSourceSide, } from '@shrkcrft/boundaries';
+export const GATE_COVERAGE_SCHEMA = 'sharkcraft.gate-coverage/v1';
+/** Evaluate the author's declared expectations against what the rule extracted. */
+function checkExpectations(selfTest, ids, unitsMatched) {
+    if (!selfTest)
+        return [];
+    const out = [];
+    if (selfTest.expectMatchesAtLeast !== undefined &&
+        unitsMatched < selfTest.expectMatchesAtLeast) {
+        out.push(`expected at least ${selfTest.expectMatchesAtLeast} match(es), got ${unitsMatched}`);
+    }
+    const present = new Set(ids);
+    for (const id of selfTest.expectIds ?? []) {
+        if (!present.has(id))
+            out.push(`expected id "${id}" was NOT extracted`);
+    }
+    for (const id of selfTest.expectNotIds ?? []) {
+        if (present.has(id))
+            out.push(`id "${id}" was extracted but is listed in expectNotIds`);
+    }
+    return out;
+}
+function matchWiring(cwd, rule, excludeDirs) {
+    const side = wiringSourceSide(rule);
+    if (!side)
+        return { filesMatched: 0, unitsMatched: 0, unitLabel: 'ids', ids: [], error: 'rule sets no source side' };
+    const insp = inspectSource(cwd, side, excludeDirs);
+    return {
+        filesMatched: insp.filesScanned,
+        unitsMatched: insp.ids.length,
+        unitLabel: 'ids',
+        ids: insp.ids,
+        ...(insp.error ? { error: insp.error } : {}),
+    };
+}
+function matchPolicy(cwd, rule, excludeDirs) {
+    const report = runPolicyLint(cwd, [rule], { excludeDirs });
+    const result = report.rules[0];
+    return {
+        // A policy rule's "files" and "units" differ only for inline templates.
+        filesMatched: result?.unitsScanned ?? 0,
+        unitsMatched: result?.unitsScanned ?? 0,
+        unitLabel: 'content units',
+        ids: [],
+        ...(result?.error ? { error: result.error } : {}),
+    };
+}
+function matchRegistry(cwd, decl, excludeDirs) {
+    const insp = inspectSource(cwd, decl.source, excludeDirs);
+    return {
+        filesMatched: insp.filesScanned,
+        unitsMatched: insp.ids.length,
+        unitLabel: 'ids',
+        ids: insp.ids,
+        ...(insp.error ? { error: insp.error } : {}),
+    };
+}
+function matchRegistration(cwd, idiom, excludeDirs) {
+    const insp = inspectSource(cwd, idiom.declared, excludeDirs);
+    return {
+        filesMatched: insp.filesScanned,
+        unitsMatched: insp.ids.length,
+        unitLabel: 'declared tokens',
+        ids: insp.ids,
+        ...(insp.error ? { error: insp.error } : {}),
+    };
+}
+function matchBaseline(cwd, rule, excludeDirs) {
+    // Only the EXTRACTOR half can be inspected without spawning. A command
+    // compute is reported honestly as un-inspectable rather than guessed at —
+    // `shrk baseline explain --id X` runs it on purpose.
+    if (rule.compute.kind !== 'extractor' || !rule.compute.source) {
+        return {
+            filesMatched: 0,
+            unitsMatched: 0,
+            unitLabel: 'entries (command compute — not inspected)',
+            ids: [],
+        };
+    }
+    const insp = inspectSource(cwd, rule.compute.source, excludeDirs);
+    return {
+        filesMatched: insp.filesScanned,
+        unitsMatched: insp.ids.length,
+        unitLabel: 'entries',
+        ids: insp.ids,
+        ...(insp.error ? { error: insp.error } : {}),
+    };
+}
+function matchGenerated(cwd, rule, excludeDirs) {
+    const scan = scanGeneratedFiles(cwd, rule, excludeDirs);
+    const files = [...scan.generated.keys()];
+    return {
+        filesMatched: files.length,
+        unitsMatched: files.length,
+        unitLabel: 'generated files',
+        ids: files,
+    };
+}
+/**
+ * Resolve every declared rule against the live tree and report what it matched.
+ *
+ * The `command`-compute baseline is the one rule kind that cannot be inspected
+ * without side effects; it is reported as un-inspected (never as `empty`), so
+ * the report never claims a fact it did not check.
+ */
+export function buildGateCoverage(cwd, rules, excludeDirs = []) {
+    const out = [];
+    for (const view of rules) {
+        let match;
+        switch (view.plane) {
+            case 'wiring':
+                match = matchWiring(cwd, view.raw, excludeDirs);
+                break;
+            case 'policy':
+                match = matchPolicy(cwd, view.raw, excludeDirs);
+                break;
+            case 'registry':
+                match = matchRegistry(cwd, view.raw, excludeDirs);
+                break;
+            case 'registration':
+                match = matchRegistration(cwd, view.raw, excludeDirs);
+                break;
+            case 'baseline':
+                match = matchBaseline(cwd, view.raw, excludeDirs);
+                break;
+            default:
+                match = matchGenerated(cwd, view.raw, excludeDirs);
+                break;
+        }
+        const expectationFailures = checkExpectations(view.selfTest, match.ids, match.unitsMatched);
+        const uninspected = match.unitLabel.includes('not inspected');
+        const status = match.error !== undefined
+            ? 'error'
+            : expectationFailures.length > 0
+                ? 'failed-expectation'
+                : match.unitsMatched === 0 && !uninspected
+                    ? 'empty'
+                    : 'ok';
+        out.push({
+            id: view.id,
+            plane: view.plane,
+            ...(view.description ? { description: view.description } : {}),
+            status,
+            filesMatched: match.filesMatched,
+            unitsMatched: match.unitsMatched,
+            unitLabel: match.unitLabel,
+            sampleIds: match.ids.slice(0, 5),
+            failOnEmpty: view.failOnEmpty,
+            ...(match.error ? { error: match.error } : {}),
+            expectationFailures,
+        });
+    }
+    const empty = out.filter((r) => r.status === 'empty').length;
+    const errored = out.filter((r) => r.status === 'error').length;
+    const expectationFailures = out.filter((r) => r.status === 'failed-expectation').length;
+    return {
+        schema: GATE_COVERAGE_SCHEMA,
+        rules: out,
+        total: out.length,
+        empty,
+        errored,
+        expectationFailures,
+        verdict: empty + errored + expectationFailures > 0 ? 'stale' : 'pass',
+    };
+}

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAMhB,MAAM,uBAAuB,CAAC;AA8X/B,wBAAgB,aAAa,IAAI,eAAe,CAiY/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CrE;AAwID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAEA,OAAO,EACL,eAAe,EAMhB,MAAM,uBAAuB,CAAC;AA0Z/B,wBAAgB,aAAa,IAAI,eAAe,CAqZ/C;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgDrE;AAwID;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAoDxE"}

package/dist/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { loadDotenv } from "./env/load-dotenv.js";
 import { CommandRegistry, extractGlobalCompress, extractGlobalCwd, extractGlobalExitTrailer, parseArgs, } from "./command-registry.js";
-import { argvHasExitTrailer, argvHasStrict, emitPipeExitSignal, promoteForStrict } from "./exit-codes.js";
+import { argvHasExitTrailer, argvHasNoHints, argvHasStrict, emitPipeExitSignal, promoteForStrict, } from "./exit-codes.js";
 import { runCommandWithCompression } from "./output/output-compression.js";
 import { initCommand } from "./commands/init.command.js";
 import { inspectCommand } from "./commands/inspect.command.js";
@@ -34,7 +34,10 @@ import { archCommand } from "./commands/arch.command.js";
 import { frameworkCommand } from "./commands/framework.command.js";
 import { apiDiffCommand } from "./commands/api-diff.command.js";
 import { gateCommand } from "./commands/gate.command.js";
-import { policyLintCommand } from "./commands/policy-lint.command.js";
+import { policyLintCommand, policyLintExplainCommand } from "./commands/policy-lint.command.js";
+import { baselineCheckCommand, baselineCommand, baselineDiffCommand, baselineExplainCommand, baselineListCommand, baselineUpdateCommand, } from "./commands/baseline.command.js";
+import { generatedCheckCommand, generatedExplainCommand, generatedListCommand, generatedUpdateCommand, } from "./commands/generated.command.js";
+import { gatesCommand, gatesCoverageCommand, gatesExplainCommand, gatesListCommand, } from "./commands/gates.command.js";
 import { wiringCommand } from "./commands/wiring.command.js";
 import { reuseCommand } from "./commands/reuse.command.js";
 import { migrateCommand } from "./commands/migrate.command.js";
@@ -44,7 +47,7 @@ import { compressCommand, expandCommand } from "./commands/compress.command.js";
 import { alignCommand, unalignCommand } from "./commands/cache-align.command.js";
 import { reviewCommand } from "./commands/review.command.js";
 import { onboardCommand } from "./commands/onboard.command.js";
-import { contradictionsCommand, generatedCommand, ingestCommand, } from "./commands/ingest.command.js";
+import { contradictionsCommand, generatedCommand, generatedProtectCommand, generatedReportCommand, ingestCommand, } from "./commands/ingest.command.js";
 import { contextBuildCommand, contextRefreshCommand, contextStatusCommand, understandTaskCommand, validateChangeCommand, } from "./commands/task-context.command.js";
 import { testCommand } from "./commands/test.command.js";
 import { planParentCommand, planReviewCommand } from "./commands/plan.command.js";
@@ -206,6 +209,26 @@ export function buildRegistry() {
     registry.register(apiDiffCommand);
     registry.register(gateCommand);
     registry.register(policyLintCommand);
+    registry.registerSubcommand('policy-lint', policyLintExplainCommand);
+    // The two shell-executing planes (baseline/generated) + the trust layer.
+    registry.register(baselineCommand);
+    registry.registerSubcommand('baseline', baselineListCommand);
+    registry.registerSubcommand('baseline', baselineCheckCommand);
+    registry.registerSubcommand('baseline', baselineDiffCommand);
+    registry.registerSubcommand('baseline', baselineUpdateCommand);
+    registry.registerSubcommand('baseline', baselineExplainCommand);
+    // `generated` already exists as the generated-code CLASSIFIER (report /
+    // protect). These add the drift GATE under the same noun.
+    registry.registerSubcommand('generated', generatedReportCommand);
+    registry.registerSubcommand('generated', generatedProtectCommand);
+    registry.registerSubcommand('generated', generatedListCommand);
+    registry.registerSubcommand('generated', generatedCheckCommand);
+    registry.registerSubcommand('generated', generatedUpdateCommand);
+    registry.registerSubcommand('generated', generatedExplainCommand);
+    registry.register(gatesCommand);
+    registry.registerSubcommand('gates', gatesListCommand);
+    registry.registerSubcommand('gates', gatesCoverageCommand);
+    registry.registerSubcommand('gates', gatesExplainCommand);
     registry.register(wiringCommand);
     registry.register(reuseCommand);
     registry.register(migrateCommand);
@@ -532,6 +555,7 @@ export async function runCli(argv) {
             emitPipeExitSignal(command, exitCode, {
                 piped: !process.stdout.isTTY,
                 trailer: argvHasExitTrailer(argv),
+                noHints: argvHasNoHints(argv),
             });
         }
         return exitCode;