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

package/dist/commands/ingest.command.js

@@ -458,32 +458,16 @@ export const contradictionsCommand = {
         return 0;
     },
 };
-export const generatedCommand = {
-    name: 'generated',
-    description: 'Generated-code classifier. Subcommands: `report` (default), `protect --write-drafts`. Read-only by default.',
-    usage: 'shrk [--cwd <dir>] generated [report|protect] [--format text|markdown|json] [--write-drafts]',
+/** Classify the tree's generated code (the `report` half of `shrk generated`). */
+export const generatedReportCommand = {
+    name: 'report',
+    description: 'Classify which parts of the tree are generated code. Read-only.',
+    usage: 'shrk [--cwd <dir>] generated report [--format text|markdown|json]',
     async run(args) {
-        const sub = args.positional[0] === 'protect' ? 'protect' : 'report';
-        const rest = { ...args, positional: args.positional.slice(args.positional[0] === 'report' || args.positional[0] === 'protect' ? 1 : 0) };
-        const cwd = resolveCwd(rest);
-        const format = parseFormat(flagString(rest, 'format'));
+        const cwd = resolveCwd(args);
+        const format = parseFormat(flagString(args, 'format'));
         const inspection = await inspectSharkcraft({ cwd });
         const report = buildGeneratedCodeReport({ inspection });
-        if (sub === 'protect') {
-            const writeDrafts = flagBool(rest, 'write-drafts');
-            const outDir = nodePath.join(cwd, INGEST_BASE);
-            if (writeDrafts) {
-                if (!existsSync(outDir))
-                    mkdirSync(outDir, { recursive: true });
-                const target = nodePath.join(outDir, 'GENERATED_PROTECT.md');
-                writeFileSync(target, renderGeneratedCodeReportMarkdown(report), 'utf8');
-                process.stdout.write(`Wrote ${target}\n`);
-                return 0;
-            }
-            process.stdout.write(renderGeneratedCodeReportMarkdown(report) + '\n');
-            process.stdout.write('\nRe-run with --write-drafts to save the recommended protect rules under sharkcraft/ingestion/.\n');
-            return 0;
-        }
         if (format === 'json')
             process.stdout.write(renderGeneratedCodeReportJson(report) + '\n');
         else if (format === 'markdown')
@@ -493,6 +477,48 @@ export const generatedCommand = {
         return 0;
     },
 };
+/** Recommend protect rules for the classified generated roots. */
+export const generatedProtectCommand = {
+    name: 'protect',
+    description: 'Recommend protect rules for the detected generated roots. Read-only unless --write-drafts (writes under sharkcraft/ingestion/).',
+    usage: 'shrk [--cwd <dir>] generated protect [--write-drafts]',
+    booleanFlags: new Set(['write-drafts']),
+    async run(args) {
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const report = buildGeneratedCodeReport({ inspection });
+        if (flagBool(args, 'write-drafts')) {
+            const outDir = nodePath.join(cwd, INGEST_BASE);
+            if (!existsSync(outDir))
+                mkdirSync(outDir, { recursive: true });
+            const target = nodePath.join(outDir, 'GENERATED_PROTECT.md');
+            writeFileSync(target, renderGeneratedCodeReportMarkdown(report), 'utf8');
+            process.stdout.write(`Wrote ${target}\n`);
+            return 0;
+        }
+        process.stdout.write(renderGeneratedCodeReportMarkdown(report) + '\n');
+        process.stdout.write('\nRe-run with --write-drafts to save the recommended protect rules under sharkcraft/ingestion/.\n');
+        return 0;
+    },
+};
+/**
+ * The `generated` group. The bare verb keeps its historical behaviour (the
+ * classifier report); `report` / `protect` are the classifier subverbs, and
+ * `list` / `check` / `update` / `explain` are the drift GATE (registered from
+ * `generated.command.ts`). One noun: that half FINDS what is generated, this
+ * half proves it has not drifted.
+ */
+export const generatedCommand = {
+    name: 'generated',
+    description: 'Generated-code classifier (`report` default, `protect --write-drafts`) + the generated-artifact drift GATE (`list | check | update | explain`, see docs/generated-drift.md). Read-only by default.',
+    usage: 'shrk [--cwd <dir>] generated [report|protect] [--format text|markdown|json] [--write-drafts]\n         (drift gate: shrk generated list | check [--headers-only] | update | explain --id <id>)',
+    booleanFlags: new Set(['write-drafts']),
+    async run(args) {
+        // Bare `shrk generated` (and any stray positional) → the classifier report,
+        // exactly as before the gate verbs joined the group.
+        return generatedReportCommand.run({ ...args, positional: [] });
+    },
+};
 export const stabilityCommand = {
     name: 'stability',
     description: 'Stability classification (stable/experimental/deprecated/legacy/generated/internal/public-api/high-risk). Read-only.',

package/dist/commands/policy-lint.command.d.ts

@@ -1,3 +1,40 @@
+import type { IPolicyRule, PolicySurface } from '@shrkcrft/core';
+import { type IPolicyFinding, type IPolicySuppression } from '@shrkcrft/boundaries';
 import { type ICommandHandler } from '../command-registry.js';
+export declare const POLICY_EXPLAIN_SCHEMA: "sharkcraft.policy-explain/v1";
+/** What ONE policy rule resolved to against the live tree. */
+export interface IPolicyExplain {
+    readonly schema: typeof POLICY_EXPLAIN_SCHEMA;
+    readonly ruleId: string;
+    readonly description?: string;
+    readonly surface: PolicySurface;
+    readonly severity: 'error' | 'warning';
+    readonly pattern: string;
+    readonly scan: string;
+    /** Content units the rule scanned (files, or inline-template bodies). */
+    readonly unitsScanned: number;
+    readonly status: string;
+    /** Every hit that COUNTED, with file:line. */
+    readonly findings: readonly IPolicyFinding[];
+    /** Every hit an exemption or the scan zone dropped, and which one applied. */
+    readonly suppressed: readonly IPolicySuppression[];
+    readonly exemptFiles: readonly string[];
+    readonly exemptLines?: string;
+    readonly diagnostics: readonly string[];
+    /** Why the rule scanned nothing, when it did. */
+    readonly skipReason?: string;
+}
+/**
+ * Dry-run ONE policy rule and return everything it saw — including the hits an
+ * exemption swallowed.
+ *
+ * Showing suppressed hits is the point: an exemption that silently deletes a
+ * finding is indistinguishable from a stale glob, so both the kept and the
+ * dropped hits are reported, each labelled with the exemption that applied.
+ */
+export declare function runPolicyExplain(cwd: string, rule: IPolicyRule, excludeDirs: readonly string[]): IPolicyExplain;
+/** Render an {@link IPolicyExplain}. Always returns 0 — explain is informational. */
+export declare function renderPolicyExplain(explain: IPolicyExplain, wantJson: boolean): number;
+export declare const policyLintExplainCommand: ICommandHandler;
 export declare const policyLintCommand: ICommandHandler;
 //# sourceMappingURL=policy-lint.command.d.ts.map

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":"AAIA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,iBAAiB,EAAE,eA6L/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

@@ -1,13 +1,117 @@
 import * as nodePath from 'node:path';
-import { runPolicyLint } from '@shrkcrft/boundaries';
+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';
+/**
+ * Dry-run ONE policy rule and return everything it saw — including the hits an
+ * exemption swallowed.
+ *
+ * Showing suppressed hits is the point: an exemption that silently deletes a
+ * finding is indistinguishable from a stale glob, so both the kept and the
+ * dropped hits are reported, each labelled with the exemption that applied.
+ */
+export function runPolicyExplain(cwd, rule, excludeDirs) {
+    const report = runPolicyLint(cwd, [rule], { excludeDirs });
+    const result = report.rules[0];
+    const skip = report.skipped[0];
+    return {
+        schema: POLICY_EXPLAIN_SCHEMA,
+        ruleId: rule.id,
+        ...(rule.description ? { description: rule.description } : {}),
+        surface: rule.surface,
+        severity: rule.severity ?? 'error',
+        pattern: rule.pattern,
+        scan: rule.scan ?? 'all',
+        unitsScanned: result?.unitsScanned ?? 0,
+        status: result?.status ?? 'error',
+        findings: report.findings,
+        suppressed: report.suppressed,
+        exemptFiles: rule.exemptFiles ?? [],
+        ...(rule.exemptLines ? { exemptLines: rule.exemptLines } : {}),
+        diagnostics: report.diagnostics,
+        ...(skip ? { skipReason: skip.reason } : {}),
+    };
+}
+/** Render an {@link IPolicyExplain}. Always returns 0 — explain is informational. */
+export function renderPolicyExplain(explain, wantJson) {
+    if (wantJson) {
+        process.stdout.write(asJson(explain) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Policy explain: ${explain.ruleId} (${explain.surface})`));
+    if (explain.description)
+        process.stdout.write(`  ${explain.description}\n`);
+    process.stdout.write(kv('pattern', `/${explain.pattern}/`) + '\n');
+    process.stdout.write(kv('scan zone', explain.scan) + '\n');
+    process.stdout.write(kv('units scanned', String(explain.unitsScanned)) + '\n');
+    process.stdout.write(kv('status', explain.status) + '\n');
+    if (explain.exemptFiles.length > 0) {
+        process.stdout.write(kv('exemptFiles', explain.exemptFiles.join(', ')) + '\n');
+    }
+    if (explain.exemptLines)
+        process.stdout.write(kv('exemptLines', explain.exemptLines) + '\n');
+    process.stdout.write(`\nHits that COUNT (${explain.findings.length}):\n`);
+    for (const f of explain.findings.slice(0, 60)) {
+        process.stdout.write(`  ✗ ${f.match}  (${f.file}:${f.line})${f.inlineTemplate ? ' [inline template]' : ''}\n`);
+    }
+    if (explain.findings.length > 60) {
+        process.stdout.write(`  … (${explain.findings.length - 60} more)\n`);
+    }
+    if (explain.suppressed.length > 0) {
+        process.stdout.write(`\nHits an exemption DROPPED (${explain.suppressed.length}):\n`);
+        for (const s of explain.suppressed.slice(0, 60)) {
+            process.stdout.write(`  – ${s.match}  (${s.file}:${s.line})  via ${s.via}\n`);
+        }
+        if (explain.suppressed.length > 60) {
+            process.stdout.write(`  … (${explain.suppressed.length - 60} more)\n`);
+        }
+    }
+    if (explain.skipReason) {
+        process.stdout.write(`\n! SKIPPED — ${explain.skipReason}. A rule that scans nothing is a bug in the rule,\n` +
+            '  not a pass. Fix the glob, or set `failOnEmpty: true` to make this a hard failure.\n');
+    }
+    for (const d of explain.diagnostics)
+        process.stdout.write(`  ! ${d}\n`);
+    return 0;
+}
+export const policyLintExplainCommand = {
+    name: 'explain',
+    description: 'Dry-run ONE policyRule and print every hit with file:line — INCLUDING the hits an exemption or the scan zone dropped, each labelled with which one applied.',
+    usage: 'shrk policy-lint explain <ruleId> [--json]',
+    booleanFlags: new Set(['json']),
+    async run(args) {
+        const id = args.positional[0] ?? flagString(args, 'id');
+        if (!id) {
+            process.stderr.write('Usage: shrk policy-lint explain <ruleId> [--json]\n');
+            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 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 ExitCode.UsageError;
+        }
+        const rel = nodePath.relative(cwd, loaded.value.sharkcraftDir).split(nodePath.sep).join('/');
+        const excludeDirs = rel && !rel.startsWith('..') ? [rel] : [];
+        return renderPolicyExplain(runPolicyExplain(cwd, rule, excludeDirs), flagBool(args, 'json'));
+    },
+};
 export const policyLintCommand = {
     name: 'policy-lint',
     description: 'Lint template/markup, stylesheet, and AOT-invisible TS surfaces against data-defined policyRules[] (e.g. flag raw markup when a primitive exists). Sees `.html` files AND inline `template:` strings — surfaces tsc/AOT cannot. Deterministic; no AI.',
     usage: 'shrk [--cwd <dir>] policy-lint [--surface template|style|ts] [--changed-only] [--new-only] [--since <ref>] [--only <ids>] [--json]\n         (--changed-only SCANS just the changed files; --new-only scans the whole tree but shows only findings the change introduced, hiding pre-existing baseline debt)',
+    booleanFlags: new Set(['json', 'changed-only', 'new-only']),
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');
@@ -25,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;
         }
@@ -35,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;
@@ -60,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;
@@ -116,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
@@ -126,12 +264,23 @@ export const policyLintCommand = {
         if (report.evaluated === 0) {
             process.stdout.write(`  ! Nothing evaluated — ${report.rules.length} rule(s) configured but none matched files in scope` +
                 (changedOnly || since ? ' (changed-only).\n' : '.\n'));
-            return 0;
+            for (const sk of report.skipped) {
+                process.stdout.write(`    – ${sk.ruleId}: ${sk.reason}${sk.failed ? '  (failOnEmpty → FAILED)' : ''}\n`);
+            }
+            // Scanning nothing is not a pass. `2` = not verified (the repo-wide
+            // contract); a `failOnEmpty` rule promotes it to a real failure.
+            return report.skipped.some((sk) => sk.failed) ? 1 : 2;
         }
         process.stdout.write(kv('rules evaluated', `${report.evaluated} of ${report.rules.length}`) + '\n');
         const errors = report.findings.filter((f) => f.severity === 'error').length;
         const warnings = report.findings.filter((f) => f.severity === 'warning').length;
         process.stdout.write(kv('findings', `${errors} error(s), ${warnings} warning(s)`) + '\n');
+        if (report.suppressed.length > 0) {
+            process.stdout.write(kv('suppressed', `${report.suppressed.length} hit(s) dropped by an exemption — see \`policy-lint explain <id>\``) + '\n');
+        }
+        for (const sk of report.skipped) {
+            process.stdout.write(`  ${sk.failed ? '✗' : '–'} ${sk.ruleId} ${sk.failed ? 'FAILED' : 'SKIPPED'} — ${sk.reason}\n`);
+        }
         if (newOnly) {
             process.stdout.write(kv('scope', `new-only (${hiddenBaseline} pre-existing finding(s) hidden — run without --new-only to see all)`) + '\n');
         }
@@ -140,6 +289,16 @@ export const policyLintCommand = {
             for (const d of report.diagnostics)
                 process.stdout.write(`  ! ${d}\n`);
         }
+        if (report.skipped.some((sk) => sk.failed)) {
+            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":"AA4BA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAKhC,eAAO,MAAM,wBAAwB,EAAE,eA8CtC,CAAC;AA6IF,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

@@ -8,17 +8,20 @@
  *       [--fail-if-taken]                       #   guard: non-zero when taken (free → 0)
  *       [--fail-if-missing]                     #   guard: non-zero when NOT registered
  *   shrk registry <name> where <id> [--json]    # declaration (+ consumer) sites
+ *   shrk registry <name> duplicates [--json]    # ids declared in more than one place
  *
  * `<name>` resolves a `registries[]` declaration in sharkcraft.config.ts — one
  * deterministic multi-root scan that answers "is this id taken / where is it"
  * without an agent re-running a fragile grep.
  */
 import { buildRegistryLifecycleReport, renderRegistryLifecycleReportText, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
-import { scanRegistry, registryExists, registryWhere, } from '@shrkcrft/boundaries';
+import { scanRegistry, registryDuplicates, registryExists, registryWhere, } from '@shrkcrft/boundaries';
 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.',
@@ -97,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) {
@@ -124,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
@@ -166,10 +178,41 @@ async function runRegistryInventory(args, name) {
         process.stdout.write(`${exists ? 'yes' : 'no'} — "${canonical}" is ${exists ? 'declared' : 'NOT declared'} in registry "${inventory.name}".\n`);
         return code;
     }
+    if (action === 'duplicates') {
+        // Two roots claiming the same id compile fine; whichever registration wins
+        // at runtime is an accident of load order. Every site is printed so the
+        // duplicate can be resolved, not merely detected.
+        const dupes = registryDuplicates(inventory);
+        if (json) {
+            process.stdout.write(asJson({
+                name: inventory.name,
+                scanned: inventory.entries.length,
+                duplicates: dupes,
+                diagnostics: [...inventory.diagnostics, ...loaded.planeDiagnostics],
+            }) + '\n');
+            return inventory.entries.length === 0 ? 2 : dupes.length > 0 ? 1 : 0;
+        }
+        if (inventory.entries.length === 0) {
+            process.stdout.write(`Registry "${inventory.name}" matched 0 ids — nothing was checked. This is NOT a pass;\n` +
+                '  the source selector is probably stale (see `shrk gates coverage`).\n');
+            return 2;
+        }
+        if (dupes.length === 0) {
+            process.stdout.write(`No duplicate ids in registry "${inventory.name}" (${inventory.entries.length} scanned). ✓\n`);
+            return 0;
+        }
+        process.stdout.write(`Duplicate ids in registry "${inventory.name}" (${dupes.length}):\n`);
+        for (const e of dupes) {
+            process.stdout.write(`  ✗ ${e.id}  (${e.sites.length} declarations)\n`);
+            for (const s of e.sites)
+                process.stdout.write(`      ${s.file}:${s.line}\n`);
+        }
+        return 1;
+    }
     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) {
@@ -187,13 +230,13 @@ async function runRegistryInventory(args, name) {
             process.stdout.write(`  consumed  ${s.file}:${s.line}\n`);
         return 0;
     }
-    process.stderr.write(`Unknown action "${action}". Usage: shrk registry ${name} list | exists <id> | where <id>\n`);
-    return 2;
+    process.stderr.write(`Unknown action "${action}". Usage: shrk registry ${name} list | exists <id> | where <id> | duplicates\n`);
+    return ExitCode.UsageError;
 }
 export const registryCommand = {
     name: 'registry',
     description: 'Registry inspections: lifecycle symmetry + declared-registry inventory. Read-only.',
-    usage: 'shrk registry lifecycle | <name> list | <name> exists <id> [--resolve] [--fail-if-taken|--fail-if-missing] | <name> where <id>',
+    usage: 'shrk registry lifecycle | <name> list | <name> exists <id> [--resolve] [--fail-if-taken|--fail-if-missing] | <name> where <id> | <name> duplicates',
     // Guard-mode + query flags take no value — declare them so `exists <id>
     // --fail-if-taken` (flag last) and `exists --resolve <id>` (flag first) both
     // keep the id as a positional instead of swallowing it.
@@ -205,13 +248,27 @@ 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);
         const loaded = await loadRegistries(cwd);
         const names = loaded.ok ? loaded.registries.map((r) => r.name) : [];
-        process.stderr.write('Usage: shrk registry lifecycle | <name> list | <name> exists <id> | <name> where <id>\n' +
+        process.stderr.write('Usage: shrk registry lifecycle | <name> list | <name> exists <id> | <name> where <id> | <name> duplicates\n' +
             (names.length > 0 ? `Declared registries: ${names.join(', ')}.\n` : 'No registries declared (sharkcraft.config.ts `registries[]`).\n'));
         return 2;
     },

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,CAsDrF;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,CAoFrF;AAyZD,eAAO,MAAM,aAAa,EAAE,eAgB3B,CAAC"}

package/dist/commands/wiring.command.js

@@ -24,6 +24,10 @@ export function renderWiringExplain(report, wantJson) {
         process.stdout.write(`  ${report.description}\n`);
     if (report.groupBy)
         process.stdout.write(kv('groupBy', report.groupBy) + '\n');
+    if (report.registeredMode === 'intersection') {
+        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');
@@ -52,6 +56,27 @@ export function renderWiringExplain(report, wantJson) {
             process.stdout.write(`  … (${report.registeredNotDeclared.length - SITE_DISPLAY_CAP} more)\n`);
         }
     }
+    if (report.overlap.length > 0) {
+        process.stdout.write(`\nPresent on BOTH sides (disjoint, ${report.overlap.length}):\n`);
+        for (const s of report.overlap.slice(0, SITE_DISPLAY_CAP)) {
+            process.stdout.write(`  ✗ ${s.token}  (${s.file}:${s.line})\n`);
+        }
+        if (report.overlap.length > SITE_DISPLAY_CAP) {
+            process.stdout.write(`  … (${report.overlap.length - SITE_DISPLAY_CAP} more)\n`);
+        }
+    }
+    if (report.hops && report.hops.length > 0) {
+        process.stdout.write('\nChain hops:\n');
+        for (const h of report.hops) {
+            process.stdout.write(`  hop ${h.index}: ${h.fromCount} → ${h.toCount}` +
+                `${h.missing > 0 ? `  ✗ ${h.missing} missing` : '  ✓'}\n`);
+        }
+    }
+    // A rule that checked NOTHING must never read like a clean pass.
+    if (report.skipReason) {
+        process.stdout.write(`\n! SKIPPED — ${report.skipReason}. A rule that matches nothing is a bug in the rule,\n` +
+            '  not a pass. Fix the selector, or set `failOnEmpty: true` to make this a hard failure.\n');
+    }
     for (const d of report.diagnostics)
         process.stdout.write(`  ! ${d}\n`);
     process.stdout.write(`\nVerdict: ${report.verdict}\n`);

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