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

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;AAMhC,eAAO,MAAM,qBAAqB,EAAG,8BAAuC,CAAC;AAE7E,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,cAAc,CAqBhB;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CA0CtF;AAGD,eAAO,MAAM,wBAAwB,EAAE,eA8BtC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAmN/B,CAAC"}

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

@@ -1,13 +1,115 @@
 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 { 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 2;
+        }
+        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;
+        }
+        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;
+        }
+        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');
@@ -126,12 +228,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 +253,10 @@ 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 with `failOnEmpty: true` matched nothing — that is a bug in the rule, not a pass.\n');
+            return 1;
+        }
         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-resolve.d.ts

@@ -12,9 +12,14 @@
  *   3. singular/plural normalization (`commands` ↔ `command`),
  *   4. suffix strip/append (`button` ↔ `button-command`, `foo` ↔ `foo.tool`).
  *
- * The first layer that lands on a DECLARED id wins; when nothing resolves, the
- * noun is returned unchanged and unmatched (the honest "genuinely not declared"
- * answer). No layer invents an id that isn't in the registry.
+ * Layers 3 and 4 CHAIN: the singular/plural variants and the suffix transform
+ * compose, so a doubly-off noun still lands (`buttons` →(plural)→ `button`
+ * →(suffix)→ `button-command`) where a single layer would no-op. When both
+ * transforms fire, the resolution reports `SingularPluralSuffix`.
+ *
+ * The first candidate that lands on a DECLARED id wins; when nothing resolves,
+ * the noun is returned unchanged and unmatched (the honest "genuinely not
+ * declared" answer). No layer invents an id that isn't in the registry.
  */
 /** How a noun resolved to its canonical registered id (for a truthful report). */
 export declare enum ERegistryResolveVia {
@@ -22,7 +27,9 @@ export declare enum ERegistryResolveVia {
     Alias = "alias",
     Case = "case-fold",
     SingularPlural = "singular/plural",
-    Suffix = "suffix"
+    Suffix = "suffix",
+    /** Both a singular/plural AND a suffix transform were applied (chained). */
+    SingularPluralSuffix = "singular/plural+suffix"
 }
 export interface IRegistryResolution {
     /** The canonical id to test for existence (may equal the input noun). */

package/dist/commands/registry-resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry-resolve.d.ts","sourceRoot":"","sources":["../../src/commands/registry-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,kFAAkF;AAClF,oBAAY,mBAAmB;IAC7B,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,IAAI,cAAc;IAClB,cAAc,oBAAoB;IAClC,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;CACnC;AAYD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,EACrD,IAAI,EAAE,MAAM,GACX,mBAAmB,CAmDrB"}
+{"version":3,"file":"registry-resolve.d.ts","sourceRoot":"","sources":["../../src/commands/registry-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,kFAAkF;AAClF,oBAAY,mBAAmB;IAC7B,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,IAAI,cAAc;IAClB,cAAc,oBAAoB;IAClC,MAAM,WAAW;IACjB,4EAA4E;IAC5E,oBAAoB,2BAA2B;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;CACnC;AAYD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,EACrD,IAAI,EAAE,MAAM,GACX,mBAAmB,CAwErB"}

package/dist/commands/registry-resolve.js

@@ -12,9 +12,14 @@
  *   3. singular/plural normalization (`commands` ↔ `command`),
  *   4. suffix strip/append (`button` ↔ `button-command`, `foo` ↔ `foo.tool`).
  *
- * The first layer that lands on a DECLARED id wins; when nothing resolves, the
- * noun is returned unchanged and unmatched (the honest "genuinely not declared"
- * answer). No layer invents an id that isn't in the registry.
+ * Layers 3 and 4 CHAIN: the singular/plural variants and the suffix transform
+ * compose, so a doubly-off noun still lands (`buttons` →(plural)→ `button`
+ * →(suffix)→ `button-command`) where a single layer would no-op. When both
+ * transforms fire, the resolution reports `SingularPluralSuffix`.
+ *
+ * The first candidate that lands on a DECLARED id wins; when nothing resolves,
+ * the noun is returned unchanged and unmatched (the honest "genuinely not
+ * declared" answer). No layer invents an id that isn't in the registry.
  */
 /** How a noun resolved to its canonical registered id (for a truthful report). */
 export var ERegistryResolveVia;
@@ -24,6 +29,8 @@ export var ERegistryResolveVia;
     ERegistryResolveVia["Case"] = "case-fold";
     ERegistryResolveVia["SingularPlural"] = "singular/plural";
     ERegistryResolveVia["Suffix"] = "suffix";
+    /** Both a singular/plural AND a suffix transform were applied (chained). */
+    ERegistryResolveVia["SingularPluralSuffix"] = "singular/plural+suffix";
 })(ERegistryResolveVia || (ERegistryResolveVia = {}));
 function singularPluralVariants(noun) {
     const out = [];
@@ -60,28 +67,47 @@ export function resolveRegistryNoun(declaredIds, aliases, noun) {
     if (ciHit !== undefined) {
         return { canonical: ciHit, matched: true, via: ERegistryResolveVia.Case };
     }
-    // 3. Singular/plural.
-    for (const variant of singularPluralVariants(noun)) {
-        const v = variant.toLowerCase();
-        const hit = declaredIds.find((d) => d.toLowerCase() === v);
-        if (hit !== undefined) {
-            return { canonical: hit, matched: true, via: ERegistryResolveVia.SingularPlural };
+    // 3 + 4. Chained singular/plural × suffix strip/append.
+    //
+    // Build an ordered candidate list — the noun itself first, then its
+    // singular/plural variants (plural variants BEFORE the suffix test) — and for
+    // EACH candidate test an exact (case-insensitive) match against the declared
+    // ids, then a suffix strip, then a suffix append. The first candidate that
+    // lands on a DECLARED id wins. Because the transforms compose, a doubly-off
+    // noun (`buttons` →(plural)→ `button` →(suffix)→ `button-command`) resolves
+    // where either layer alone would no-op. `via` records which transforms fired:
+    // a variant matching exactly is `SingularPlural`, the original noun matching
+    // by suffix is `Suffix`, and a variant matching by suffix is the chained
+    // `SingularPluralSuffix`. The original noun can never match here EXACTLY (the
+    // identity / case-fold short-circuits above already handled that).
+    const candidates = [noun, ...singularPluralVariants(noun)];
+    for (const candidate of candidates) {
+        const isVariant = candidate !== noun;
+        const cLower = candidate.toLowerCase();
+        const exact = declaredIds.find((d) => d.toLowerCase() === cLower);
+        if (exact !== undefined && isVariant) {
+            return { canonical: exact, matched: true, via: ERegistryResolveVia.SingularPlural };
         }
-    }
-    // 4. Suffix strip/append. A declared id whose trailing `-`/`.`/`_` segment,
-    //    once stripped, equals the noun (`button` ← `button-command`); or the noun
-    //    plus a suffix another declared id carries yields a declared id.
-    const suffixStripped = declaredIds.find((d) => {
-        const stripped = d.replace(/[-_.][a-z0-9]+$/i, '');
-        return stripped.toLowerCase() === lower && stripped.toLowerCase() !== d.toLowerCase();
-    });
-    if (suffixStripped !== undefined) {
-        return { canonical: suffixStripped, matched: true, via: ERegistryResolveVia.Suffix };
-    }
-    for (const d of declaredIds) {
-        const m = d.match(/([-_.][a-z0-9]+)$/i);
-        if (m && `${lower}${m[1].toLowerCase()}` === d.toLowerCase()) {
-            return { canonical: d, matched: true, via: ERegistryResolveVia.Suffix };
+        const suffixStripped = declaredIds.find((d) => {
+            const stripped = d.replace(/[-_.][a-z0-9]+$/i, '');
+            return stripped.toLowerCase() === cLower && stripped.toLowerCase() !== d.toLowerCase();
+        });
+        if (suffixStripped !== undefined) {
+            return {
+                canonical: suffixStripped,
+                matched: true,
+                via: isVariant ? ERegistryResolveVia.SingularPluralSuffix : ERegistryResolveVia.Suffix,
+            };
+        }
+        for (const d of declaredIds) {
+            const m = d.match(/([-_.][a-z0-9]+)$/i);
+            if (m && `${cLower}${m[1].toLowerCase()}` === d.toLowerCase()) {
+                return {
+                    canonical: d,
+                    matched: true,
+                    via: isVariant ? ERegistryResolveVia.SingularPluralSuffix : ERegistryResolveVia.Suffix,
+                };
+            }
         }
     }
     // Nothing resolved — the honest unmatched identity.

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;AAKhC,eAAO,MAAM,wBAAwB,EAAE,eA8CtC,CAAC;AAoLF,eAAO,MAAM,eAAe,EAAE,eA4B7B,CAAC"}

package/dist/commands/registry.command.js

@@ -8,13 +8,14 @@
  *       [--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";
@@ -166,6 +167,37 @@ 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`);
@@ -187,13 +219,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`);
+    process.stderr.write(`Unknown action "${action}". Usage: shrk registry ${name} list | exists <id> | where <id> | duplicates\n`);
     return 2;
 }
 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.
@@ -211,7 +243,7 @@ export const registryCommand = {
         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/trace.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6EhC,eAAO,MAAM,YAAY,EAAE,eAwH1B,CAAC"}
+{"version":3,"file":"trace.command.d.ts","sourceRoot":"","sources":["../../src/commands/trace.command.ts"],"names":[],"mappings":"AAmBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA8EhC,eAAO,MAAM,YAAY,EAAE,eA+H1B,CAAC"}

package/dist/commands/trace.command.js

@@ -17,6 +17,7 @@ const TRACE_ROLE_ORDER = [
     TraceRole.Declare,
     TraceRole.Register,
     TraceRole.Consume,
+    TraceRole.Render,
     TraceRole.Reference,
 ];
 function renderTraceLiteral(report, limit) {
@@ -31,7 +32,7 @@ function renderTraceLiteral(report, limit) {
     }
     // Mirror `shrk registry <name> where`'s `<role>  file:line` line idiom so the
     // two surfaces read the same — `trace literal` is the same scanner + classifier
-    // without a pre-declared registry, just with two extra roles (`registered`,
+    // without a pre-declared registry, just with extra roles (`register`, `render`,
     // `reference`). The raw source line stays in `--json` (`text`); the human view
     // is classification-first (direction), not a grep-style text dump.
     process.stdout.write('\n');
@@ -154,6 +155,11 @@ export const traceCommand = {
         process.stdout.write(header(`Trace: ${query}`));
         if (!resolution.bestMatch) {
             process.stdout.write('  no matches found.\n');
+            // The bare-`trace` path resolves a FUZZY registry query, not an exact
+            // string literal — quotes are stripped by the shell, so we can't tell a
+            // literal from a query and must not auto-route. Point the agent at the
+            // exact-literal tracer (`trace literal`) so a no-match here isn't a dead end.
+            process.stderr.write(`hint: to trace an exact string literal across files, use: shrk trace literal "${query}"\n`);
             return 1;
         }
         process.stdout.write(`Confidence: ${resolution.confidence}\n`);

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,EAAwB,KAAK,eAAe,EAAmB,MAAM,wBAAwB,CAAC;AAKrG;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAsDrF;AA+TD,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"}