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

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;
+}

package/dist/gates/self-test-check.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One `selfTest` expectation, evaluated against a rule's EXTRACTED SET.
+ *
+ * Every gate-plane selfTest field asserts on the same thing — what the rule's
+ * primary selector extracted from the live tree — never on a ranker's output or
+ * on a registry lookup. `assertion` names that class explicitly, so a JSON
+ * reader can tell these apart from the ranker-surfaced and registry-existence
+ * expectations of agent-contract and pack tests, which answer different
+ * questions and fail for different reasons.
+ */
+export interface ISelfTestCheck {
+    /** The selfTest field this check came from. */
+    readonly field: 'expectMatchesAtLeast' | 'expectIds' | 'expectNotIds';
+    /** What the field asserts on — always the rule's extracted set on a gate plane. */
+    readonly assertion: 'extracted-set';
+    /** The floor (`expectMatchesAtLeast`), or the id this check is about. */
+    readonly expected: number | string;
+    /**
+     * `held` / `failed` were measured. `not-evaluable` means this plane shape
+     * cannot produce the set the field asserts on, so the field is neither a
+     * pass nor a fake "got 0".
+     */
+    readonly status: 'held' | 'failed' | 'not-evaluable';
+    /** The measured count, for `expectMatchesAtLeast`. */
+    readonly actual?: number;
+    /** One sentence naming the unit counted and, on failure, the selector consulted. */
+    readonly message: string;
+}
+//# sourceMappingURL=self-test-check.d.ts.map

package/dist/gates/self-test-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-test-check.d.ts","sourceRoot":"","sources":["../../src/gates/self-test-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,WAAW,GAAG,cAAc,CAAC;IACtE,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,eAAe,CAAC;IACrD,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/gates/self-test-check.js

@@ -0,0 +1 @@
+export {};

package/dist/gates/self-test-subject.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What a rule's primary selector resolved to, in the terms a `selfTest`
+ * asserts on.
+ *
+ * Each plane's coverage adapter produces one, and `evaluateSelfTest` reads
+ * nothing else. That is what keeps `gates coverage` and `gates try` from
+ * disagreeing about whether an expectation held: they hand the same subject to
+ * the same evaluator.
+ */
+export interface ISelfTestSubject {
+    /** Every distinct id the selector extracted, sorted. */
+    readonly ids: readonly string[];
+    /** What `expectMatchesAtLeast` counts. */
+    readonly unitsMatched: number;
+    /** The unit {@link unitsMatched} counts — `ids`, `content units`, `generated files`. */
+    readonly unitLabel: string;
+    /** What one "id" is on this plane — `registry ids`, `pattern matches (capture group 1 …)`. */
+    readonly idLabel: string;
+    /** The selector consulted, e.g. `registry "mcp-tools" — source a/*.ts (regex-capture)`. */
+    readonly consulted: string;
+    /**
+     * Set when this plane shape cannot produce the set a selfTest asserts on (a
+     * `command` baseline with no `watchFiles` to probe): the reason, printed
+     * instead of a fabricated "got 0".
+     */
+    readonly notEvaluable?: string;
+}
+//# sourceMappingURL=self-test-subject.d.ts.map

package/dist/gates/self-test-subject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-test-subject.d.ts","sourceRoot":"","sources":["../../src/gates/self-test-subject.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC"}

package/dist/gates/self-test-subject.js

@@ -0,0 +1 @@
+export {};

package/dist/gates/self-test.d.ts

@@ -0,0 +1,20 @@
+import type { IRuleSelfTest } from '@shrkcrft/core';
+import type { ISelfTestCheck } from './self-test-check.js';
+import type { ISelfTestSubject } from './self-test-subject.js';
+/**
+ * THE gate-plane `selfTest` evaluator: every declared expectation, checked
+ * against what the rule's primary selector extracted.
+ *
+ * `gates coverage` (a rule in config), `gates try` (a candidate that is not in
+ * config yet) and `shrk quality` all call this one function with the subject
+ * the plane's coverage adapter built. A second evaluator — even a faithful
+ * copy — is how a dry-run ends up passing a rule the gate then fails.
+ *
+ * Every check says what it counted and, when it fails, which selector it
+ * consulted, so a failure names the set it looked in instead of a bare
+ * "expected N match(es)". A field the plane shape cannot evaluate is reported
+ * `not-evaluable` with the reason — an unmeasured assertion is never a pass,
+ * and never a fabricated "got 0".
+ */
+export declare function evaluateSelfTest(selfTest: IRuleSelfTest | undefined, subject: ISelfTestSubject): readonly ISelfTestCheck[];
+//# sourceMappingURL=self-test.d.ts.map

package/dist/gates/self-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-test.d.ts","sourceRoot":"","sources":["../../src/gates/self-test.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,OAAO,EAAE,gBAAgB,GACxB,SAAS,cAAc,EAAE,CAsE3B"}

package/dist/gates/self-test.js

@@ -0,0 +1,82 @@
+/**
+ * THE gate-plane `selfTest` evaluator: every declared expectation, checked
+ * against what the rule's primary selector extracted.
+ *
+ * `gates coverage` (a rule in config), `gates try` (a candidate that is not in
+ * config yet) and `shrk quality` all call this one function with the subject
+ * the plane's coverage adapter built. A second evaluator — even a faithful
+ * copy — is how a dry-run ends up passing a rule the gate then fails.
+ *
+ * Every check says what it counted and, when it fails, which selector it
+ * consulted, so a failure names the set it looked in instead of a bare
+ * "expected N match(es)". A field the plane shape cannot evaluate is reported
+ * `not-evaluable` with the reason — an unmeasured assertion is never a pass,
+ * and never a fabricated "got 0".
+ */
+export function evaluateSelfTest(selfTest, subject) {
+    if (!selfTest)
+        return [];
+    const where = `consulted: ${subject.consulted}`;
+    const out = [];
+    if (subject.notEvaluable !== undefined) {
+        const unmeasurable = (field, expected) => ({
+            field,
+            assertion: 'extracted-set',
+            expected,
+            status: 'not-evaluable',
+            message: `selfTest.${field} cannot be evaluated: ${subject.notEvaluable} — ${where}`,
+        });
+        if (selfTest.expectMatchesAtLeast !== undefined) {
+            out.push(unmeasurable('expectMatchesAtLeast', selfTest.expectMatchesAtLeast));
+        }
+        if ((selfTest.expectIds ?? []).length > 0) {
+            out.push(unmeasurable('expectIds', (selfTest.expectIds ?? []).join(', ')));
+        }
+        if ((selfTest.expectNotIds ?? []).length > 0) {
+            out.push(unmeasurable('expectNotIds', (selfTest.expectNotIds ?? []).join(', ')));
+        }
+        return out;
+    }
+    if (selfTest.expectMatchesAtLeast !== undefined) {
+        const floor = selfTest.expectMatchesAtLeast;
+        const got = subject.unitsMatched;
+        const held = got >= floor;
+        out.push({
+            field: 'expectMatchesAtLeast',
+            assertion: 'extracted-set',
+            expected: floor,
+            actual: got,
+            status: held ? 'held' : 'failed',
+            message: held
+                ? `${got} ${subject.unitLabel} (at least ${floor} expected)`
+                : `expected at least ${floor} ${subject.unitLabel}, got ${got} — ${where}`,
+        });
+    }
+    const present = new Set(subject.ids);
+    for (const id of selfTest.expectIds ?? []) {
+        const held = present.has(id);
+        out.push({
+            field: 'expectIds',
+            assertion: 'extracted-set',
+            expected: id,
+            status: held ? 'held' : 'failed',
+            message: held
+                ? `"${id}" is in the extracted set`
+                : `expected id "${id}" was NOT extracted — not among the ${subject.ids.length} ` +
+                    `${subject.idLabel}; ${where}`,
+        });
+    }
+    for (const id of selfTest.expectNotIds ?? []) {
+        const held = !present.has(id);
+        out.push({
+            field: 'expectNotIds',
+            assertion: 'extracted-set',
+            expected: id,
+            status: held ? 'held' : 'failed',
+            message: held
+                ? `"${id}" is not in the extracted set`
+                : `id "${id}" was extracted but is listed in expectNotIds — ${where}`,
+        });
+    }
+    return out;
+}

package/dist/gates/settle-verdict.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The CLI's one exit guard — `settleVerdict(proposed, coverage)`: a verb
+ * PROPOSES an exit from what it found, and the coverage of what it examined may
+ * veto a clean one (proposed `0` with any shortfall → `2`; `1`, `2` and `3` are
+ * never changed).
+ *
+ * Round 11 review: the fold moved to `@shrkcrft/core` so the boundary
+ * orchestrator (read by finish, quality and the MCP tools, which cannot import
+ * the CLI) settles with the SAME function instead of a second copy. This path
+ * stays as a re-export so every CLI caller — `buildGateEnvelope`, `quality`,
+ * `gate` — keeps its import unchanged.
+ */
+export { settleVerdict } from '@shrkcrft/core';
+//# sourceMappingURL=settle-verdict.d.ts.map

package/dist/gates/settle-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle-verdict.d.ts","sourceRoot":"","sources":["../../src/gates/settle-verdict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/gates/settle-verdict.js

@@ -0,0 +1,13 @@
+/**
+ * The CLI's one exit guard — `settleVerdict(proposed, coverage)`: a verb
+ * PROPOSES an exit from what it found, and the coverage of what it examined may
+ * veto a clean one (proposed `0` with any shortfall → `2`; `1`, `2` and `3` are
+ * never changed).
+ *
+ * Round 11 review: the fold moved to `@shrkcrft/core` so the boundary
+ * orchestrator (read by finish, quality and the MCP tools, which cannot import
+ * the CLI) settles with the SAME function instead of a second copy. This path
+ * stays as a re-export so every CLI caller — `buildGateEnvelope`, `quality`,
+ * `gate` — keeps its import unchanged.
+ */
+export { settleVerdict } from '@shrkcrft/core';

package/dist/gates/settled-verdict.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A verdict after the coverage guard has run — the only shape a verdict verb
+ * may render its final line from. Defined in `@shrkcrft/core` next to
+ * `settleVerdict` (round 11 review: one settle derivation for the CLI and the
+ * engines below it); re-exported here so CLI imports stay unchanged.
+ */
+export type { ISettledVerdict } from '@shrkcrft/core';
+//# sourceMappingURL=settled-verdict.d.ts.map

package/dist/gates/settled-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settled-verdict.d.ts","sourceRoot":"","sources":["../../src/gates/settled-verdict.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/gates/settled-verdict.js

@@ -0,0 +1 @@
+export {};

package/dist/gates/template-registry-coverage.d.ts

@@ -0,0 +1,18 @@
+import type { IVerdictCoverage } from '@shrkcrft/core';
+/**
+ * THE coverage record of a template-registry verdict: the registered
+ * templates, minus any whose operations were never checked (`changes()` threw
+ * with sample variables). ZERO registered is an empty request — "nothing to
+ * verify", never a pass — unless the caller's `--allow-empty` valve accepts it.
+ *
+ * `templates doctor` and `check templates` settle on this one record, so the
+ * two readers cannot answer "are the templates valid?" two ways over zero
+ * templates (round 11 review: the doctor said 2, `check templates` said OK 0).
+ */
+export declare function templateRegistryCoverage(input: {
+    readonly total: number;
+    readonly unchecked?: readonly string[];
+    readonly root: string;
+    readonly acceptance?: Pick<IVerdictCoverage, 'acceptedBy'>;
+}): IVerdictCoverage;
+//# sourceMappingURL=template-registry-coverage.d.ts.map

package/dist/gates/template-registry-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-registry-coverage.d.ts","sourceRoot":"","sources":["../../src/gates/template-registry-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;CAC5D,GAAG,gBAAgB,CAcnB"}

package/dist/gates/template-registry-coverage.js

@@ -0,0 +1,24 @@
+/**
+ * THE coverage record of a template-registry verdict: the registered
+ * templates, minus any whose operations were never checked (`changes()` threw
+ * with sample variables). ZERO registered is an empty request — "nothing to
+ * verify", never a pass — unless the caller's `--allow-empty` valve accepts it.
+ *
+ * `templates doctor` and `check templates` settle on this one record, so the
+ * two readers cannot answer "are the templates valid?" two ways over zero
+ * templates (round 11 review: the doctor said 2, `check templates` said OK 0).
+ */
+export function templateRegistryCoverage(input) {
+    const unchecked = input.unchecked ?? [];
+    return {
+        unit: 'templates',
+        expected: input.total,
+        examined: input.total - unchecked.length,
+        root: input.root,
+        reason: input.total === 0
+            ? 'no template is registered'
+            : 'changes() threw with sample variables, so their operations were never checked',
+        ...(unchecked.length > 0 ? { unexamined: unchecked.slice(0, 20), unexaminedTotal: unchecked.length } : {}),
+        ...(input.acceptance ?? {}),
+    };
+}

package/dist/gates/unit-state-notes.d.ts

@@ -0,0 +1,40 @@
+import type { IUnitStateNoteRow } from './i-unit-state-note-row.js';
+import type { IUnitStateNotes } from './i-unit-state-notes.js';
+/** Options for {@link unitStateNotes}. */
+interface IUnitStateNotesOptions {
+    /**
+     * The verb's `--fail-on-dead-units` value, when the verb TAKES the flag
+     * (`undefined` = it does not, so no "pass --fail-on-dead-units" hint).
+     */
+    readonly failOnDeadUnits?: boolean;
+    /**
+     * Also list every INTENDED-EMPTY unit (round 13, K6), each as its one
+     * per-unit line under a neutral bullet — never a ✓ (the acceptance belongs to
+     * the settled verdict). The explain views opt in: an introspection names
+     * every unit state. The verbs do not; their acceptance line carries it.
+     */
+    readonly intendedEmpty?: boolean;
+}
+/**
+ * THE unit-state block every plane verb prints (round 13, K2) — the one
+ * renderer, so `policy-lint`, `check wiring`, `baseline check`, `generated
+ * check`, `docs references check`, `registry <name> list|duplicates`, `gates
+ * check`, the explain surfaces and finish's plane sub-gates say about a
+ * selector unit exactly what `gates coverage` and `check boundaries` say:
+ *
+ *   - an unmarked DEAD unit of a rule that is not already reported as matching
+ *     nothing (a dead import-edges `to.files` under an accepted fence
+ *     included) — advisory: listed, the ✓ withheld, the exit unchanged, with
+ *     ONE footer carrying `DEAD_SELECTOR_CAUSES`;
+ *   - a LOCAL `expectEmpty` marker whose target appeared (went live) — the
+ *     fence is a stale assertion: listed, the ✓ withheld;
+ *   - a PACK marker that went live — INFO in its own block, never a failure
+ *     and never withholding the ✓ (the consumer cannot edit it).
+ *
+ * Each line is `• <rule id>: <formatUnitLiveness(u)>` — the one per-unit line;
+ * a surface adds decoration only, never its own state words. The verb reads
+ * `stale` to qualify its clean line (`qualifyCleanForUnits`).
+ */
+export declare function unitStateNotes(rows: readonly IUnitStateNoteRow[], options?: IUnitStateNotesOptions): IUnitStateNotes;
+export {};
+//# sourceMappingURL=unit-state-notes.d.ts.map

package/dist/gates/unit-state-notes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-state-notes.d.ts","sourceRoot":"","sources":["../../src/gates/unit-state-notes.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,0CAA0C;AAC1C,UAAU,sBAAsB;IAC9B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAOD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,iBAAiB,EAAE,EAClC,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAmDjB"}

package/dist/gates/unit-state-notes.js

@@ -0,0 +1,71 @@
+import { DEAD_SELECTOR_CAUSES, formatUnitLiveness, UnitLivenessState, } from '@shrkcrft/core';
+/**
+ * THE unit-state block every plane verb prints (round 13, K2) — the one
+ * renderer, so `policy-lint`, `check wiring`, `baseline check`, `generated
+ * check`, `docs references check`, `registry <name> list|duplicates`, `gates
+ * check`, the explain surfaces and finish's plane sub-gates say about a
+ * selector unit exactly what `gates coverage` and `check boundaries` say:
+ *
+ *   - an unmarked DEAD unit of a rule that is not already reported as matching
+ *     nothing (a dead import-edges `to.files` under an accepted fence
+ *     included) — advisory: listed, the ✓ withheld, the exit unchanged, with
+ *     ONE footer carrying `DEAD_SELECTOR_CAUSES`;
+ *   - a LOCAL `expectEmpty` marker whose target appeared (went live) — the
+ *     fence is a stale assertion: listed, the ✓ withheld;
+ *   - a PACK marker that went live — INFO in its own block, never a failure
+ *     and never withholding the ✓ (the consumer cannot edit it).
+ *
+ * Each line is `• <rule id>: <formatUnitLiveness(u)>` — the one per-unit line;
+ * a surface adds decoration only, never its own state words. The verb reads
+ * `stale` to qualify its clean line (`qualifyCleanForUnits`).
+ */
+export function unitStateNotes(rows, options = {}) {
+    const pick = (state, keep) => rows.flatMap((r) => (r.unitLiveness ?? []).filter((u) => u.state === state && keep(u, r)).map((u) => ({ id: r.id, u })));
+    const dead = pick(UnitLivenessState.Dead, (_u, r) => r.reportedEmpty !== true);
+    const local = pick(UnitLivenessState.WentLive, (u) => u.mark?.packageName === undefined);
+    const pack = pick(UnitLivenessState.WentLive, (u) => u.mark?.packageName !== undefined);
+    const intended = options.intendedEmpty === true ? pick(UnitLivenessState.IntendedEmpty, () => true) : [];
+    const unitLine = (x) => `${x.id}: ${formatUnitLiveness(x.u, { causes: false })}`;
+    const line = (x) => `  • ${unitLine(x)}\n`;
+    let text = '';
+    if (dead.length > 0) {
+        text += `\nDead selector units (${dead.length}) — each matches nothing, so it enforces nothing:\n`;
+        text += dead.map(line).join('');
+        // The causes ONCE, as a footer (`formatUnitLiveness(u, { causes: false })`
+        // on each line) — the wording `check boundaries` appends to each unit.
+        text += `  Dead selectors: ${DEAD_SELECTOR_CAUSES}.\n`;
+        if (options.failOnDeadUnits === false)
+            text += '  Pass --fail-on-dead-units to fail the run on them.\n';
+    }
+    if (local.length > 0) {
+        text += `\nexpectEmpty markers that went live (${local.length}) — each fence now has a target; remove the marker:\n`;
+        text += local.map(line).join('');
+    }
+    if (pack.length > 0) {
+        text +=
+            `\nINFO — pack expectEmpty markers that went live (${pack.length}) — the fence now has a target; ` +
+                "the pack's author removes the marker, and it never fails this run:\n";
+        text += pack.map(line).join('');
+    }
+    if (intended.length > 0) {
+        // A neutral bullet, never a ✓: the acceptance and its ✓ belong to the
+        // settled verdict (`verdictLine`, exit 0 only) — the same decoration
+        // `gates coverage` and `gates try` give an intended-empty unit.
+        text += `\nIntended-empty selector units (${intended.length}) — each marks a target that does not exist yet (expectEmpty):\n`;
+        text += intended.map((x) => `  · ${unitLine(x)}\n`).join('');
+    }
+    return {
+        dead: dead.length,
+        localWentLive: local.length,
+        packWentLive: pack.length,
+        text,
+        deadLines: dead.map(unitLine),
+        localWentLiveLines: local.map(unitLine),
+        packWentLiveLines: pack.map(unitLine),
+        stale: [
+            ...(dead.length > 0 ? [`${dead.length} dead selector unit(s)`] : []),
+            ...(local.length > 0 ? [`${local.length} expectEmpty unit(s) went live — remove the markers`] : []),
+        ],
+        staleIds: new Set([...dead, ...local].map((x) => x.id)),
+    };
+}

package/dist/gates/verdict-line.d.ts

@@ -0,0 +1,18 @@
+import type { ISettledVerdict } from './settled-verdict.js';
+/**
+ * The final line of a verdict verb, rendered FROM the settled verdict — the
+ * only way a verb may print its clean (`✓`) sentence.
+ *
+ *   - exit `0`: `clean`, followed by one indented line per accepted gap, so a
+ *     waived shortfall is always visible next to the green;
+ *   - exit `2`: `notVerifiedLead` (the verb's own explanation, when it has one)
+ *     and then `NOT VERIFIED: <shortfalls> (this is not a pass)`;
+ *   - exit `1`: `(also not verified: <shortfalls>)` when a scope gap sits next
+ *     to the violations, otherwise empty — the verb already printed them;
+ *   - anything else: empty.
+ *
+ * It never returns `clean` for a non-zero exit, which is the property that
+ * keeps the banner and `$?` from disagreeing.
+ */
+export declare function verdictLine(s: ISettledVerdict, clean: string, notVerifiedLead?: string): string;
+//# sourceMappingURL=verdict-line.d.ts.map

package/dist/gates/verdict-line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict-line.d.ts","sourceRoot":"","sources":["../../src/gates/verdict-line.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAK5D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB/F"}

package/dist/gates/verdict-line.js

@@ -0,0 +1,40 @@
+import { ExitCode } from "../exit-codes.js";
+/** Shortfalls named on the verdict line before the rest are summarised. */
+const SHORTFALLS_SHOWN = 5;
+/**
+ * The final line of a verdict verb, rendered FROM the settled verdict — the
+ * only way a verb may print its clean (`✓`) sentence.
+ *
+ *   - exit `0`: `clean`, followed by one indented line per accepted gap, so a
+ *     waived shortfall is always visible next to the green;
+ *   - exit `2`: `notVerifiedLead` (the verb's own explanation, when it has one)
+ *     and then `NOT VERIFIED: <shortfalls> (this is not a pass)`;
+ *   - exit `1`: `(also not verified: <shortfalls>)` when a scope gap sits next
+ *     to the violations, otherwise empty — the verb already printed them;
+ *   - anything else: empty.
+ *
+ * It never returns `clean` for a non-zero exit, which is the property that
+ * keeps the banner and `$?` from disagreeing.
+ */
+export function verdictLine(s, clean, notVerifiedLead) {
+    if (s.exit === ExitCode.VerifiedPass) {
+        return [clean, ...s.accepted.map((a) => `  ${a}`)].filter((l) => l.length > 0).join('\n');
+    }
+    const listed = listShortfalls(s.shortfalls);
+    if (s.exit === ExitCode.NotVerified) {
+        if (s.shortfalls.length === 0) {
+            return notVerifiedLead ?? 'NOT VERIFIED — nothing was proved (this is not a pass).';
+        }
+        const line = `NOT VERIFIED: ${listed} (this is not a pass)`;
+        return notVerifiedLead ? `${notVerifiedLead}\n${line}` : line;
+    }
+    if (s.exit === ExitCode.Failure && s.shortfalls.length > 0) {
+        return `(also not verified: ${listed})`;
+    }
+    return '';
+}
+function listShortfalls(shortfalls) {
+    const shown = shortfalls.slice(0, SHORTFALLS_SHOWN).join('; ');
+    const rest = shortfalls.length - SHORTFALLS_SHOWN;
+    return rest > 0 ? `${shown}; … (+${rest} more)` : shown;
+}

package/dist/graph/graph-reuse-lookup.d.ts

@@ -0,0 +1,10 @@
+import type { GraphQueryApi } from '@shrkcrft/graph';
+import type { IReuseSymbolLookup } from '@shrkcrft/inspector';
+/**
+ * The reuse engine's graph questions, answered from one snapshot — shared by
+ * `shrk reuse` and `shrk reuse coverage`, so both resolve every curated entry
+ * (its declaration, import line and whether that import compiles) through the
+ * same lookups, via the inspector's `resolveCuratedReuse`.
+ */
+export declare function graphReuseLookup(api: GraphQueryApi): IReuseSymbolLookup;
+//# sourceMappingURL=graph-reuse-lookup.d.ts.map

package/dist/graph/graph-reuse-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-reuse-lookup.d.ts","sourceRoot":"","sources":["../../src/graph/graph-reuse-lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,kBAAkB,CAiCvE"}