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

package/dist/gates/run-gate-planes.d.ts

@@ -1,5 +1,6 @@
 import { type ISharkcraftInspection } from '@shrkcrft/inspector';
 import type { IGateRuleResult } from './gate-envelope.js';
+import type { IUnitStateNoteRow } from './i-unit-state-note-row.js';
 import type { IGateRuleView } from './gate-rule-view.js';
 /**
  * Run every data-defined plane's VIOLATION check and normalize the results.
@@ -11,6 +12,12 @@ import type { IGateRuleView } from './gate-rule-view.js';
  * per-plane verbs call. A second implementation of any plane's check would
  * eventually disagree with the verb, and the aggregate — the one wired into CI
  * — would be the copy nobody notices is wrong.
+ *
+ * The same holds for COVERAGE: each rule's `coverage` comes from the plane's
+ * own coverage function (the one its verb uses), so `gates check` and the
+ * per-plane verb can never disagree about how much of a rule's scope was
+ * examined. Round 13: so does each rule's `expectEmpty` acceptance
+ * (`unitAcceptance`, folded into the envelope's one settle) and its unit lines.
  */
 export interface IRunGatePlanesOptions {
     readonly cwd: string;
@@ -38,6 +45,13 @@ export interface IRunGatePlanesOptions {
 export interface IGatePlaneRun {
     readonly results: readonly IGateRuleResult[];
     readonly diagnostics: readonly string[];
+    /**
+     * Each rule's settled non-live selector units (round 13, K2) — what THE
+     * shared unit-state renderer (`unitStateNotes`) reads, so `gates check` lists
+     * a dead unit or a went-live marker exactly as the plane verb does. Kept off
+     * the envelope rows, which carry the `units` lines only.
+     */
+    readonly noteRows?: readonly IUnitStateNoteRow[];
 }
 /** Evaluate the given rules, dispatching each to its plane's real engine. */
 export declare function runGatePlanes(rules: readonly IGateRuleView[], options: IRunGatePlanesOptions): IGatePlaneRun;

package/dist/gates/run-gate-planes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-gate-planes.d.ts","sourceRoot":"","sources":["../../src/gates/run-gate-planes.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAsBrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpE;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;CAC7C;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,EAAE,qBAAqB,GAC7B,aAAa,CAef"}
+{"version":3,"file":"run-gate-planes.d.ts","sourceRoot":"","sources":["../../src/gates/run-gate-planes.ts"],"names":[],"mappings":"AAYA,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AA+BrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAa,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIpE;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;CAC7C;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAClD;AAqCD,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,EAAE,qBAAqB,GAC7B,aAAa,CA2Bf"}

package/dist/gates/run-gate-planes.js

@@ -1,21 +1,56 @@
-import { resolveSourceGlobs } from '@shrkcrft/core';
+import { failsWhenEmpty, resolveSourceGlobs, RuleEmptiness, settleRuleEmptiness, unitStateLists, UnitLivenessState, } from '@shrkcrft/core';
 import { checkDocReferences } from '@shrkcrft/inspector';
-import { buildRegistrationGraph, matchesAny, registrationOrphans, registrationUnprovided, registryDuplicates, runPolicyLint, runWiring, scanRegistry, } from '@shrkcrft/boundaries';
-import { evaluateBaselineRule } from "../commands/baseline.command.js";
-import { evaluateGeneratedRule, generatedHintFor } from "../commands/generated.command.js";
+import { buildRegistrationGraph, globListSelects, readScopeCoverage, readScopeHasUnread, registrationOrphans, registrationUnprovided, registryDuplicates, runPolicyLint, runWiring, scanRegistry, settleGlobLists, } from '@shrkcrft/boundaries';
+import { baselineCoverage, evaluateBaselineRule } from "../commands/baseline.command.js";
+import { evaluateGeneratedRule, generatedCoverage, generatedHintFor, } from "../commands/generated.command.js";
+import { docReferenceCoverage } from "../commands/docs-references.command.js";
+import { policyRuleCoverage } from "../commands/policy-lint.command.js";
+import { measureRegistrationRoles } from "./measure-registration-roles.js";
+import { registryLiveness } from "./registry-liveness.js";
+/** The unit fields a plane engine put on its result, passed through to the envelope rule (round 13). */
+function unitFields(r) {
+    return {
+        ...(r.unitAcceptance !== undefined ? { unitAcceptance: r.unitAcceptance } : {}),
+        ...(r.units !== undefined ? { units: r.units } : {}),
+        ...(r.unitLiveness !== undefined && r.unitLiveness.length > 0 ? { unitLiveness: r.unitLiveness } : {}),
+    };
+}
+/** The same, from a settle this module ran itself. */
+function livenessFields(l) {
+    if (l === undefined)
+        return {};
+    const nonLive = l.units.filter((u) => u.state !== UnitLivenessState.Live);
+    return {
+        ...(l.acceptance !== undefined ? { unitAcceptance: l.acceptance } : {}),
+        ...(l.dead.length + l.intendedEmpty.length + l.wentLive.length > 0 ? { units: unitStateLists(l) } : {}),
+        ...(nonLive.length > 0 ? { unitLiveness: nonLive } : {}),
+    };
+}
 /** Evaluate the given rules, dispatching each to its plane's real engine. */
 export function runGatePlanes(rules, options) {
     const results = [];
     const diagnostics = [];
     const byPlane = (plane) => rules.filter((r) => r.plane === plane).map((r) => r.raw);
-    results.push(...runWiringPlane(byPlane('wiring'), options, diagnostics));
-    results.push(...runPolicyPlane(byPlane('policy'), options));
-    results.push(...runRegistryPlane(byPlane('registry'), options));
-    results.push(...runRegistrationPlane(byPlane('registration'), options));
-    results.push(...runBaselinePlane(byPlane('baseline'), options));
-    results.push(...runGeneratedPlane(byPlane('generated'), options));
-    results.push(...runDocReferencePlane(byPlane('doc-reference'), options));
-    return { results, diagnostics };
+    const planeResults = [
+        ...runWiringPlane(byPlane('wiring'), options, diagnostics),
+        ...runPolicyPlane(byPlane('policy'), options),
+        ...runRegistryPlane(byPlane('registry'), options),
+        ...runRegistrationPlane(byPlane('registration'), options),
+        ...runBaselinePlane(byPlane('baseline'), options),
+        ...runGeneratedPlane(byPlane('generated'), options),
+        ...runDocReferencePlane(byPlane('doc-reference'), options),
+    ];
+    // Each rule's settled units leave its envelope row (the envelope carries the
+    // `units` lines) for the note rows THE shared unit-state renderer reads (K2).
+    const noteRows = [];
+    for (const r of planeResults) {
+        const { unitLiveness, ...row } = r;
+        results.push(row);
+        if (unitLiveness !== undefined) {
+            noteRows.push({ id: r.id, unitLiveness, reportedEmpty: r.status === 'skipped' || r.skipReason !== undefined });
+        }
+    }
+    return { results, diagnostics, noteRows };
 }
 function runWiringPlane(rules, options, diagnostics) {
     if (rules.length === 0)
@@ -39,6 +74,10 @@ function runWiringPlane(rules, options, diagnostics) {
             })),
             ...(skip ? { skipReason: skip.reason } : {}),
             ...(r.error ? { error: r.error } : {}),
+            // The engine's own coverage — a subset rule's registered-only tokens
+            // arrive here as unexamined, which is what makes it `partial`.
+            coverage: r.coverage,
+            ...unitFields(r),
         };
     });
 }
@@ -65,6 +104,8 @@ function runPolicyPlane(rules, options) {
             })),
             ...(skip ? { skipReason: skip.reason } : {}),
             ...(r.error ? { error: r.error } : {}),
+            coverage: policyRuleCoverage(r),
+            ...unitFields(r),
         };
     });
 }
@@ -77,12 +118,58 @@ function runRegistryPlane(decls, options) {
     return decls.map((decl) => {
         const inventory = scanRegistry(options.cwd, decl, { excludeDirs: options.excludeDirs });
         const dupes = registryDuplicates(inventory);
-        const empty = inventory.entries.length === 0;
+        // A source file the reader could not read (over the read cap) makes the
+        // inventory incomplete. Zero ids over it is not "matched nothing" (never a
+        // failOnEmpty failure), and "no duplicates" over it is not a pass: its
+        // coverage is the file record, so the rule settles PARTIAL.
+        const empty = inventory.entries.length === 0 && !readScopeHasUnread(inventory.readScope);
+        // The registry's globs settled with their `expectEmpty` markers (round 13)
+        // — only when a unit is marked, or the inventory is empty (what it is
+        // decided from). The registry verbs read the same `registryLiveness`.
+        const marked = [decl.source, decl.consumer].some((s) => (s?.expectEmptyUnits?.length ?? 0) > 0);
+        const liveness = marked || empty ? registryLiveness(options.cwd, decl, options.excludeDirs) : undefined;
+        // `failOnEmpty` makes a dead inventory BLOCK, exactly as a failOnEmpty
+        // wiring rule does; without it an empty registry stays a loud skip. A
+        // registry has no severity of its own, so THE failOnEmpty authority answers
+        // for a warning-severity rule (default off; an explicit `true` promotes it).
+        const failOnEmpty = failsWhenEmpty({
+            ...(decl.failOnEmpty !== undefined ? { failOnEmpty: decl.failOnEmpty } : {}),
+            severity: 'warning',
+        });
+        const staleReason = failOnEmpty
+            ? 'matched 0 ids — failOnEmpty: the source selector is probably stale'
+            : 'matched 0 ids — the source selector is probably stale';
+        // THE rule-emptiness settle: every source inclusion glob marked
+        // `expectEmpty` and no source file matched → an inventory over a planned
+        // directory, accepted and printed; anything else is the loud skip.
+        const emptiness = empty && liveness !== undefined
+            ? settleRuleEmptiness({
+                subject: decl.name,
+                unitLabel: 'ids',
+                filesMatched: inventory.readScope.read,
+                unitsMatched: 0,
+                unread: false,
+                liveness,
+                primaryLists: ['source.files'],
+                failOnEmpty,
+                noFilesReason: staleReason,
+                noUnitsReason: staleReason,
+            })
+            : undefined;
+        const intended = emptiness?.state === RuleEmptiness.IntendedEmpty && emptiness.coverage !== undefined;
+        const skipped = emptiness?.skipped === true;
+        const skipReason = emptiness?.skipReason ?? staleReason;
         return {
             id: decl.name,
             type: 'registry',
-            status: empty ? 'skipped' : dupes.length > 0 ? 'failed' : 'passed',
-            severity: 'warning',
+            status: skipped
+                ? emptiness?.fails
+                    ? 'failed'
+                    : 'skipped'
+                : dupes.length > 0
+                    ? 'failed'
+                    : 'passed',
+            severity: emptiness?.fails ? 'error' : 'warning',
             counts: { ids: inventory.entries.length, duplicates: dupes.length },
             violations: dupes.map((d) => ({
                 id: d.id,
@@ -90,7 +177,16 @@ function runRegistryPlane(decls, options) {
                 message: `declared in ${d.sites.length} places: ${d.sites.map((s) => `${s.file}:${s.line}`).join(', ')}`,
                 hint: 'remove the duplicate declaration — which one wins is load-order roulette',
             })),
-            ...(empty ? { skipReason: 'matched 0 ids — the source selector is probably stale' } : {}),
+            ...(skipped ? { skipReason } : {}),
+            coverage: intended && emptiness?.coverage !== undefined
+                ? emptiness.coverage
+                : readScopeCoverage({
+                    unit: 'ids',
+                    expected: inventory.entries.length,
+                    examined: inventory.entries.length,
+                    ...(skipped ? { reason: skipReason } : {}),
+                }, inventory.readScope),
+            ...livenessFields(liveness),
         };
     });
 }
@@ -112,24 +208,56 @@ function runRegistrationPlane(idioms, options) {
     const graph = buildRegistrationGraph(options.cwd, idioms, { excludeDirs: options.excludeDirs });
     const unprovided = registrationUnprovided(graph, options.changedFiles);
     const orphans = registrationOrphans(graph, options.changedFiles);
-    const ownsFile = (idiom, file) => matchesAny(file, [
-        ...resolveSourceGlobs(idiom.declared),
-        ...resolveSourceGlobs(idiom.consumed),
-        ...resolveSourceGlobs(idiom.provided),
-    ]);
+    // Per ROLE list: a role's `!x` subtracts from that role only, so it never
+    // disowns a file another role of the idiom reads.
+    const ownsFile = (idiom, file) => [idiom.declared, idiom.consumed, idiom.provided].some((role) => globListSelects(file, resolveSourceGlobs(role)));
     return idioms.map((idiom) => {
         const mine = unprovided.filter((t) => [...t.declared, ...t.consumed].some((site) => ownsFile(idiom, site.file)));
         const myOrphans = orphans.filter((t) => t.provided.some((site) => ownsFile(idiom, site.file)));
-        const empty = graph.tokens.length === 0;
+        // "Is this idiom empty?" and "which role examined nothing?" come from the
+        // ONE measurement `gates coverage` reads too. Keying emptiness on the
+        // graph's token union used to print a ✓ over an idiom whose declared glob
+        // had moved (its provided/consumed roles kept the union non-empty), while
+        // coverage FAILED the same idiom.
+        const roles = measureRegistrationRoles(options.cwd, idiom, options.excludeDirs);
+        const failOnEmpty = failsWhenEmpty({
+            ...(idiom.failOnEmpty !== undefined ? { failOnEmpty: idiom.failOnEmpty } : {}),
+            severity: 'warning',
+        });
+        const staleReason = `the declared role extracted 0 tokens${failOnEmpty ? ' (failOnEmpty)' : ''}, ` +
+            'so the declared selector is probably stale';
+        // THE rule-emptiness settle (round 13) on the declared role — the idiom's
+        // primary selector: every declared inclusion glob marked `expectEmpty` and
+        // no declared file matched → a planned token space, accepted; 0 tokens out
+        // of live declared files is the loud skip it always was.
+        const emptiness = roles.error === undefined && roles.empty
+            ? settleRuleEmptiness({
+                subject: idiom.name,
+                unitLabel: 'declared tokens',
+                filesMatched: roles.declared.filesScanned,
+                unitsMatched: 0,
+                unread: false,
+                liveness: roles.liveness ?? settleGlobLists({ subject: idiom.name, lists: [], marks: [] }),
+                primaryLists: ['declared.files'],
+                failOnEmpty,
+                noFilesReason: staleReason,
+                noUnitsReason: staleReason,
+            })
+            : undefined;
+        const skipped = emptiness?.skipped === true;
         return {
             id: idiom.name,
             type: 'registration',
-            status: empty
-                ? 'skipped'
-                : mine.length > 0
-                    ? 'failed'
-                    : 'passed',
-            severity: 'warning',
+            status: roles.error !== undefined
+                ? 'error'
+                : skipped
+                    ? emptiness?.fails
+                        ? 'failed'
+                        : 'skipped'
+                    : mine.length > 0
+                        ? 'failed'
+                        : 'passed',
+            severity: emptiness?.fails ? 'error' : 'warning',
             counts: { tokens: graph.tokens.length, unprovided: mine.length, orphans: myOrphans.length },
             violations: mine.map((t) => ({
                 id: t.token,
@@ -137,7 +265,12 @@ function runRegistrationPlane(idioms, options) {
                 message: 'declared/consumed but provided by nothing — resolves to nothing at runtime',
                 hint: `trace it with \`shrk wiring chain ${t.token}\``,
             })),
-            ...(empty ? { skipReason: 'registration graph matched 0 tokens' } : {}),
+            ...(skipped ? { skipReason: emptiness?.skipReason ?? staleReason } : {}),
+            ...(roles.error !== undefined ? { error: roles.error } : {}),
+            // A dead role is an unexamined unit: the rule settles to `partial`, never
+            // ✓. An intended-empty role rides on the acceptance instead.
+            coverage: roles.coverage,
+            ...livenessFields(roles.liveness),
         };
     });
 }
@@ -154,6 +287,7 @@ function runBaselinePlane(rules, options) {
                 counts: { committed: 0, current: 0 },
                 violations: [],
                 skipReason: '`command` compute skipped by --no-spawn',
+                coverage: { unit: 'baseline computes', expected: 1, examined: 0, reason: 'skipped by --no-spawn' },
             };
         }
         const o = evaluateBaselineRule(options.cwd, rule, options.excludeDirs, options.changedFiles);
@@ -169,6 +303,8 @@ function runBaselinePlane(rules, options) {
             ].map((v) => ({ ...v, hint: rule.hint ?? `bless with \`shrk baseline update --id ${rule.id}\`` })),
             ...(o.skipReason ? { skipReason: o.skipReason } : {}),
             ...(o.error ? { error: o.error } : {}),
+            coverage: baselineCoverage(o),
+            ...unitFields(o),
         };
     });
 }
@@ -183,6 +319,7 @@ function runDocReferencePlane(rules, options) {
         return [];
     const inspection = options.inspection;
     if (!inspection) {
+        const skipReason = 'registries not loaded — doc references were not resolved';
         return rules.map((rule) => ({
             id: rule.id,
             type: 'doc-reference',
@@ -190,7 +327,8 @@ function runDocReferencePlane(rules, options) {
             severity: rule.severity ?? 'error',
             counts: { files: 0, tokens: 0 },
             violations: [],
-            skipReason: 'registries not loaded — doc references were not resolved',
+            skipReason,
+            coverage: { unit: 'references', expected: 0, examined: 0, reason: skipReason },
         }));
     }
     return rules.map((rule) => {
@@ -210,6 +348,8 @@ function runDocReferencePlane(rules, options) {
             })),
             ...(res.skipReason ? { skipReason: res.skipReason } : {}),
             ...(res.error ? { error: res.error } : {}),
+            coverage: docReferenceCoverage(res),
+            ...unitFields(res),
         };
     });
 }
@@ -256,6 +396,8 @@ function runGeneratedPlane(rules, options) {
                     ? { skipReason: 'regen drift check skipped by --no-spawn (headers + classification still ran)' }
                     : {}),
             ...(o.error ? { error: o.error } : {}),
+            coverage: generatedCoverage(o, spawnSkipped),
+            ...unitFields(o),
         };
     });
 }

package/dist/gates/scaffold-selftest.d.ts

@@ -0,0 +1,56 @@
+import type { IGateCoverage } from './rule-coverage.js';
+/**
+ * A scaffolded `selfTest`, ready to paste (or to insert with `--write`).
+ *
+ * The trust layer asks every rule to carry `failOnEmpty` + a `selfTest`, so a
+ * stale glob after a directory move fails LOUD instead of passing over an empty
+ * set. In practice the selfTest is the step that gets skipped — not from
+ * disagreement, but because authoring the fixture inline (which ids to pin,
+ * what floor to set) is a blank page at the exact moment the author just wants
+ * the rule to work. A rule with no selfTest is invisible to the stale-glob
+ * detector, so the friction converts directly into missing coverage.
+ */
+export interface IScaffoldedSelfTest {
+    readonly ruleId: string;
+    readonly plane: string;
+    /** What the rule matches right now — the number the floor is derived from. */
+    readonly currentCount: number;
+    readonly expectMatchesAtLeast: number;
+    readonly expectIds: readonly string[];
+    /** The percentage of headroom left below the current count. */
+    readonly marginPercent: number;
+    /** The literal block to paste into the rule. */
+    readonly snippet: string;
+    /**
+     * Why some extracted ids were NOT pinned, or why `expectIds` is empty. Today
+     * this applies to the policy plane: a live finding is debt, and pinning it
+     * would turn paying the debt into a gate failure.
+     */
+    readonly note?: string;
+}
+/**
+ * Build a ready-to-commit `selfTest` from what the rule matches TODAY.
+ *
+ * The floor is deliberately BELOW the current count: pinning the exact number
+ * would turn every legitimate addition into a failure, and a rule that cries
+ * wolf on normal work gets its expectations deleted rather than fixed. The
+ * margin is what keeps the assertion about "the selector still bites" rather
+ * than about "the set never changes".
+ */
+export declare function scaffoldSelfTest(coverage: IGateCoverage, marginPercent: number, sampleSize?: number): IScaffoldedSelfTest;
+/** Outcome of inserting a scaffolded selfTest into the config text. */
+export interface IInsertResult {
+    readonly ok: boolean;
+    readonly text?: string;
+    readonly error?: string;
+}
+/**
+ * Insert the block into the rule whose `id` matches, in place.
+ *
+ * Refuses rather than guesses. A config is the file every gate reads, so a
+ * write that lands in the wrong rule — or in one of two rules sharing an id —
+ * would silently re-point an assertion at a different set, which is worse than
+ * making the author paste three lines by hand.
+ */
+export declare function insertSelfTest(configText: string, ruleId: string, snippet: string): IInsertResult;
+//# sourceMappingURL=scaffold-selftest.d.ts.map

package/dist/gates/scaffold-selftest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-selftest.d.ts","sourceRoot":"","sources":["../../src/gates/scaffold-selftest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,EACvB,aAAa,EAAE,MAAM,EACrB,UAAU,SAAI,GACb,mBAAmB,CA6BrB;AAmBD,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,aAAa,CA8Bf"}

package/dist/gates/scaffold-selftest.js

@@ -0,0 +1,119 @@
+/** Markers that make an id a poor anchor: it is likely to be renamed or removed. */
+const UNSTABLE = /(^|[^a-z])(tmp|temp|draft|wip|scratch|legacy|deprecated|old|new|test|fixture|sample|example|foo|bar|baz)([^a-z]|$)/i;
+/**
+ * How good an anchor an id is, higher is better.
+ *
+ * A selfTest is only as useful as the ids it pins: anchoring on a name that was
+ * always going to be deleted produces a rule that fails for a reason unrelated
+ * to the selector, which trains people to delete the selfTest. So the obviously
+ * temporary and the obviously generated are ranked last, and everything else is
+ * ordered deterministically by name so the same tree always scaffolds the same
+ * fixture.
+ */
+function stability(id) {
+    let score = 100;
+    if (UNSTABLE.test(id))
+        score -= 60;
+    // A long digit or hex run reads as generated (a hash, a timestamp, an index).
+    if (/\d{4,}/.test(id))
+        score -= 40;
+    if (/[0-9a-f]{8,}/i.test(id))
+        score -= 40;
+    // Trailing counters (`handlerV2`, `route3`) churn as versions advance.
+    if (/\d$/.test(id))
+        score -= 15;
+    return score;
+}
+/**
+ * Build a ready-to-commit `selfTest` from what the rule matches TODAY.
+ *
+ * The floor is deliberately BELOW the current count: pinning the exact number
+ * would turn every legitimate addition into a failure, and a rule that cries
+ * wolf on normal work gets its expectations deleted rather than fixed. The
+ * margin is what keeps the assertion about "the selector still bites" rather
+ * than about "the set never changes".
+ */
+export function scaffoldSelfTest(coverage, marginPercent, sampleSize = 3) {
+    // A plane whose extracted set mixes stable anchors with ids that are meant to
+    // go away (the policy plane: a live finding is debt) says which ids are safe
+    // to pin. Only those are scaffolded. Pinning a live violation would make
+    // `gates coverage` fail on the day the author fixes the code the rule forbids.
+    const ids = coverage.pinIds ?? coverage.allIds ?? coverage.sampleIds;
+    const count = coverage.unitsMatched;
+    const floor = Math.max(1, Math.floor(count * (1 - marginPercent / 100)));
+    const expectIds = [...ids]
+        .sort((a, b) => stability(b) - stability(a) || a.localeCompare(b))
+        .slice(0, Math.min(sampleSize, ids.length));
+    const snippet = [
+        'selfTest: {',
+        `  expectMatchesAtLeast: ${floor},`,
+        `  expectIds: [${expectIds.map((i) => `'${i}'`).join(', ')}],`,
+        '  expectNotIds: [],',
+        '},',
+    ].join('\n');
+    const note = pinNote(coverage);
+    return {
+        ruleId: coverage.id,
+        plane: coverage.plane,
+        currentCount: count,
+        expectMatchesAtLeast: floor,
+        expectIds,
+        marginPercent,
+        snippet,
+        ...(note ? { note } : {}),
+    };
+}
+/** Why a plane's pinnable set is narrower than what it extracted, when it is. */
+function pinNote(coverage) {
+    if (coverage.pinIds === undefined)
+        return undefined;
+    const pinnable = new Set(coverage.pinIds);
+    const live = (coverage.allIds ?? coverage.sampleIds).filter((id) => !pinnable.has(id));
+    const skipped = live.length > 0
+        ? `${live.length} id(s) matched by a live finding were not pinned (${live.slice(0, 3).join(', ')}` +
+            `${live.length > 3 ? ', …' : ''}). A finding is debt, and pinning it would fail the gate once the debt is paid. `
+        : '';
+    if (coverage.pinIds.length > 0)
+        return skipped ? skipped.trimEnd() : undefined;
+    return (`${skipped}No exempted hit to pin, so expectIds is left empty. Add a fixture file under the rule's ` +
+        '`exemptFiles` that contains the forbidden pattern. expectIds can then prove the pattern still bites.');
+}
+/**
+ * Insert the block into the rule whose `id` matches, in place.
+ *
+ * Refuses rather than guesses. A config is the file every gate reads, so a
+ * write that lands in the wrong rule — or in one of two rules sharing an id —
+ * would silently re-point an assertion at a different set, which is worse than
+ * making the author paste three lines by hand.
+ */
+export function insertSelfTest(configText, ruleId, snippet) {
+    // A registry declaration is keyed by `name`, every other plane by `id`. Both
+    // are the rule's identity as `gates list` prints it, so both are accepted —
+    // an author should not have to know which plane spells it which way.
+    const idPattern = new RegExp(`^([ \\t]*)(?:id|name):\\s*['"\`]${escapeRegex(ruleId)}['"\`]\\s*,?\\s*$`, 'gm');
+    const matches = [...configText.matchAll(idPattern)];
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            error: `no \`id: '${ruleId}'\` (or \`name:\`) line found in the config — is the rule contributed by a pack?`,
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            ok: false,
+            error: `"${ruleId}" appears ${matches.length} times — refusing to guess which rule to edit`,
+        };
+    }
+    const m = matches[0];
+    const indent = m[1] ?? '  ';
+    const lineEnd = configText.indexOf('\n', m.index);
+    const at = lineEnd === -1 ? configText.length : lineEnd + 1;
+    const block = snippet
+        .split('\n')
+        .map((l) => (l === '' ? l : indent + l))
+        .join('\n');
+    return { ok: true, text: configText.slice(0, at) + block + '\n' + configText.slice(at) };
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/gates/seam-rejected-rules.d.ts

@@ -0,0 +1,28 @@
+import { type IResolvedProjectConfig } from '@shrkcrft/inspector';
+import type { IGateRuleResult } from './gate-envelope.js';
+import type { GatePlane } from './gate-rule-view.js';
+/**
+ * THE gate-plane reading of a pack element the merge seam refused (round 12
+ * review, R12-X1): a configured rule that did NOT run — an ERRORED row, `failed
+ * validation — NOT evaluated`, exactly as the boundary plane reports a rejected
+ * boundary rule.
+ *
+ * `resolveProjectConfig` has always returned the structured rejections
+ * (`planeOutcomes`), but every gate verb read only the `planeDiagnostics`
+ * strings: a pack policy rule whose `files` was negation-only was dropped, never
+ * entered the rule denominator, and `gates check` / `policy-lint` / `gates
+ * coverage` printed a ✓ at exit 0 over it while `packs contributions` and
+ * `packs doctor` exited 1 on the same tree. Every plane reader — `gates
+ * check|coverage|list`, `quality`, `policy-lint`, `check wiring`, `registry`,
+ * `baseline check`, `generated check`, `finish` — builds its rows here, so they
+ * cannot disagree about one rejected rule.
+ *
+ * A pack plane FILE that failed to import is one errored row per file (the
+ * rules inside it are unknown). A `duplicate-id` rejection is NOT a row: the id
+ * it collided with is a rule that runs (local wins), so it stays a diagnostic.
+ * `planes` narrows to the planes a verb reads; absent = every plane.
+ */
+export declare function seamRejectedRules(resolved: Pick<IResolvedProjectConfig, 'planeOutcomes' | 'projectRoot'>, planes?: readonly GatePlane[]): (IGateRuleResult & {
+    readonly type: GatePlane;
+})[];
+//# sourceMappingURL=seam-rejected-rules.d.ts.map

package/dist/gates/seam-rejected-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seam-rejected-rules.d.ts","sourceRoot":"","sources":["../../src/gates/seam-rejected-rules.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAmBrD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,IAAI,CAAC,sBAAsB,EAAE,eAAe,GAAG,aAAa,CAAC,EACvE,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,GAC5B,CAAC,eAAe,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,EAAE,CAkDpD"}

package/dist/gates/seam-rejected-rules.js

@@ -0,0 +1,95 @@
+import { RejectionCause } from '@shrkcrft/core';
+import { ContributionKind, contributionFileLabel, formatEntryRejection, } from '@shrkcrft/inspector';
+/**
+ * Each gate-plane contribution kind → the plane its rules run on. A kind absent
+ * here (`reuse-primitive`) is not a gate plane. Doc references joined in round
+ * 13 (P3): their pack slot (`docReferenceFiles`) is declared, so a rejected
+ * pack doc-reference rule is an ERRORED row like every other plane's — before,
+ * it was a diagnostic string only.
+ */
+const PLANE_OF_KIND = {
+    [ContributionKind.WiringRule]: 'wiring',
+    [ContributionKind.PolicyRule]: 'policy',
+    [ContributionKind.Registry]: 'registry',
+    [ContributionKind.RegistrationIdiom]: 'registration',
+    [ContributionKind.Baseline]: 'baseline',
+    [ContributionKind.GeneratedArtifact]: 'generated',
+    [ContributionKind.DocReference]: 'doc-reference',
+};
+/**
+ * THE gate-plane reading of a pack element the merge seam refused (round 12
+ * review, R12-X1): a configured rule that did NOT run — an ERRORED row, `failed
+ * validation — NOT evaluated`, exactly as the boundary plane reports a rejected
+ * boundary rule.
+ *
+ * `resolveProjectConfig` has always returned the structured rejections
+ * (`planeOutcomes`), but every gate verb read only the `planeDiagnostics`
+ * strings: a pack policy rule whose `files` was negation-only was dropped, never
+ * entered the rule denominator, and `gates check` / `policy-lint` / `gates
+ * coverage` printed a ✓ at exit 0 over it while `packs contributions` and
+ * `packs doctor` exited 1 on the same tree. Every plane reader — `gates
+ * check|coverage|list`, `quality`, `policy-lint`, `check wiring`, `registry`,
+ * `baseline check`, `generated check`, `finish` — builds its rows here, so they
+ * cannot disagree about one rejected rule.
+ *
+ * A pack plane FILE that failed to import is one errored row per file (the
+ * rules inside it are unknown). A `duplicate-id` rejection is NOT a row: the id
+ * it collided with is a rule that runs (local wins), so it stays a diagnostic.
+ * `planes` narrows to the planes a verb reads; absent = every plane.
+ */
+export function seamRejectedRules(resolved, planes) {
+    const outcomes = resolved.planeOutcomes;
+    if (!outcomes)
+        return [];
+    const wanted = (kind) => {
+        const plane = PLANE_OF_KIND[kind];
+        return plane !== undefined && (planes === undefined || planes.includes(plane)) ? plane : undefined;
+    };
+    const rows = [];
+    const seen = new Set();
+    for (const r of outcomes.rejected) {
+        if (r.cause === RejectionCause.DuplicateId)
+            continue;
+        const plane = wanted(r.kind);
+        if (plane === undefined)
+            continue;
+        const file = contributionFileLabel(resolved.projectRoot, r.file);
+        const id = r.entryId ?? `${file}[${r.index}]`;
+        if (seen.has(`${plane}:${id}`))
+            continue;
+        seen.add(`${plane}:${id}`);
+        const pack = r.packageName ? `pack ${r.packageName} ` : '';
+        rows.push({
+            id,
+            type: plane,
+            status: 'error',
+            severity: 'error',
+            counts: {},
+            violations: [],
+            error: `${pack}${plane} rule failed validation at the pack-plane merge seam — NOT evaluated: ` +
+                `${formatEntryRejection(r)} (${file})`,
+            coverage: { unit: 'rules', expected: 1, examined: 0, subject: id, reason: 'failed validation — NOT evaluated' },
+        });
+    }
+    for (const f of outcomes.loadFailures) {
+        const plane = wanted(f.kind);
+        if (plane === undefined)
+            continue;
+        const file = contributionFileLabel(resolved.projectRoot, f.file);
+        const id = `${f.packageName}:${file}`;
+        if (seen.has(`${plane}:${id}`))
+            continue;
+        seen.add(`${plane}:${id}`);
+        rows.push({
+            id,
+            type: plane,
+            status: 'error',
+            severity: 'error',
+            counts: {},
+            violations: [],
+            error: `pack ${f.packageName} ${plane} rule file failed to load — none of its rules was evaluated: ${f.message}`,
+            coverage: { unit: 'rules', expected: 1, examined: 0, subject: id, reason: 'the rule file failed to load' },
+        });
+    }
+    return rows;
+}