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

package/dist/policy/evaluate-policy.d.ts

@@ -1,4 +1,9 @@
-import { type IPolicyRule, type PolicySurface } from '@shrkcrft/core';
+import { type IPolicyRule, type IUnitLiveness, type IUnitStateLists, type IVerdictCoverage, type PolicySurface } from '@shrkcrft/core';
+import type { IPolicyRuleLiveness } from './i-policy-rule-liveness.js';
+import type { IReadScope } from '../util/read-scope.js';
+import type { IUnreadFile } from '../util/unread-file.js';
+import type { IDeadGlobUnit } from '../util/i-dead-glob-unit.js';
+import type { IGlobNegation } from '../util/i-glob-negation.js';
 export declare const POLICY_LINT_SCHEMA: "sharkcraft.policy-lint/v1";
 /**
  * A chunk of content to scan for one rule. For whole files `baseLine` is 1; for
@@ -52,6 +57,49 @@ export interface IPolicyRuleResult {
     /** Content units actually scanned — the stale-glob signal. */
     readonly unitsScanned: number;
     readonly error?: string;
+    /**
+     * What the rule examined against what it was asked to (`IVerdictCoverage`,
+     * unit `content units`) — the ONE per-rule record `policy-lint`, `gates
+     * check`, `quality`, `shrk gate` and `finish` all settle on. A rule that
+     * scanned nothing, or is misconfigured, examined nothing (`expected: 0` — a
+     * shortfall). The engine fills it in; it never decides a verdict from it.
+     */
+    readonly coverage: IVerdictCoverage;
+    /**
+     * Glob-matched files in the rule's scope that the one reader did not read
+     * (over the read cap, or unreadable). Set only when non-empty. `coverage`
+     * names them too: such a rule is never a pass.
+     */
+    readonly unread?: readonly IUnreadFile[];
+    /**
+     * Globs of the rule's own `files[]` that do nothing — an inclusion glob
+     * that selects no file in the walk, or a negation that excludes none — a
+     * dead unit inside a rule whose other globs keep it scanning. Set only when
+     * non-empty, and only for author-written `files` (a surface's default globs
+     * are not the author's selector). Advisory; `gates coverage` reports it.
+     */
+    readonly deadGlobs?: readonly string[];
+    /** The units behind {@link deadGlobs}, same order, each with its reason (`globListUnits`). */
+    readonly deadGlobUnits?: readonly IDeadGlobUnit[];
+    /** Live negations of the rule's own `files[]`, each with the files it excludes. Set only when non-empty. */
+    readonly negations?: readonly IGlobNegation[];
+    /**
+     * Set only when the rule scanned nothing BECAUSE of its own `files[]`
+     * negations: its inclusion globs matched files and these negations excluded
+     * every one (`globListUnits`' `allExcluded`). That is not a stale selector,
+     * so its skip reason and coverage reason say what happened instead.
+     */
+    readonly excludedByNegations?: readonly IGlobNegation[];
+    /**
+     * The acceptance of the rule's `expectEmpty` units — settle record B of its
+     * `files` (round 13). Folded into the envelope's ONE settle beside
+     * {@link coverage}; when the rule is intended-empty it IS {@link coverage}.
+     */
+    readonly unitAcceptance?: IVerdictCoverage;
+    /** The rule's dead / intended-empty / went-live `files` units as printed lines (`unitStateLists`). */
+    readonly units?: IUnitStateLists;
+    /** The rule's non-live `files` units (dead, intended-empty, went-live, unproven), for `--fail-on-dead-units` (`selectorUnitFails`). */
+    readonly unitLiveness?: readonly IUnitLiveness[];
 }
 /** A rule that scanned nothing, reported loudly instead of as a green pass. */
 export interface IPolicySkip {
@@ -74,9 +122,21 @@ export interface IPolicyReport {
      * Count of rules that actually scanned ≥1 unit. A rule whose globs matched 0
      * files (e.g. a `style` rule in a project with no stylesheets) is NOT
      * evaluated — a loud skip rather than a green pass. Misconfigured rules count
-     * as evaluated so their error is not swallowed.
+     * as evaluated so their error is not swallowed, and so does a rule whose
+     * globs matched a file the reader could not read (it ran, and is PARTIAL:
+     * its coverage names the unread file). A rule ACCEPTED as intended-empty
+     * (round 13 — every inclusion glob of its `files` marked `expectEmpty`, 0
+     * files matched) is counted too, so the verdict path's `evaluated === 0`
+     * NOT-VERIFIED guard never reads an accepted plan as "nothing ran"; the
+     * printed "N evaluated" excludes it: N = `evaluated − acceptedEmpty`.
      */
     readonly evaluated: number;
+    /**
+     * Rules accepted as intended-empty (round 13, K6): they examined 0 files, so
+     * a renderer prints them apart — `N evaluated, M accepted as
+     * intended-empty` — never inside the evaluated count.
+     */
+    readonly acceptedEmpty: number;
     readonly verdict: 'pass' | 'errors' | 'warnings';
 }
 /** Resolves the content units to scan for a given rule (injected for purity/testability). */
@@ -89,6 +149,23 @@ export type PolicyUnitResolver = (rule: IPolicyRule) => readonly IPolicyUnit[];
  * them, so `explain` can show what was matched AND what was let through. A
  * misconfigured rule (uncompilable regex) degrades to a diagnostic — never
  * throws, so one bad rule cannot crash the check.
+ *
+ * `scopeOf` reports each rule's read scope: the glob-matched files the one
+ * reader read and the ones it did not. A rule with an unread file in scope
+ * examined less than its globs matched, so its coverage is the file record
+ * (`readScopeCoverage`) and it is never a pass. When the unread file is why it
+ * scanned no unit at all, it is PARTIAL, not a `failOnEmpty` failure: it
+ * matched something it could not read, which is not "matched nothing".
+ */
+export declare function evaluatePolicy(rules: readonly IPolicyRule[], resolve: PolicyUnitResolver, scopeOf?: (rule: IPolicyRule) => IReadScope, 
+/**
+ * The rule's own `files` judged per unit and settled with its `expectEmpty`
+ * markers (round 13) — `runPolicyLint` supplies it from the walk it already
+ * did. A rule that scanned nothing is decided from it by THE rule-emptiness
+ * settle (`settleRuleEmptiness`): every inclusion glob intended-empty and no
+ * file matched → accepted (`passed`, the acceptance as its coverage), never a
+ * failOnEmpty failure. Absent (hand-driven, or no own `files`): no unit is
+ * marked, so an empty rule is a loud skip exactly as before.
  */
-export declare function evaluatePolicy(rules: readonly IPolicyRule[], resolve: PolicyUnitResolver): IPolicyReport;
+livenessOf?: (rule: IPolicyRule) => IPolicyRuleLiveness | undefined): IPolicyReport;
 //# sourceMappingURL=evaluate-policy.d.ts.map

package/dist/policy/evaluate-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate-policy.d.ts","sourceRoot":"","sources":["../../src/policy/evaluate-policy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"evaluate-policy.d.ts","sourceRoot":"","sources":["../../src/policy/evaluate-policy.ts"],"names":[],"mappings":"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"}

package/dist/policy/evaluate-policy.js

@@ -1,5 +1,8 @@
-import { failsWhenEmpty } from '@shrkcrft/core';
-import { lexCodeZones, zoneAt } from "../extract/code-zones.js";
+import { failsWhenEmpty, normalizeRuleList, RuleEmptiness, settleRuleEmptiness, } from '@shrkcrft/core';
+import { lexCodeZones, zoneKeepsAt } from "../extract/code-zones.js";
+import { allExcludedCause } from "../util/negation-cause.js";
+import { settleGlobLists } from "../util/settle-glob-lists.js";
+import { readScopeCoverage, readScopeHasUnread } from "../util/read-scope-coverage.js";
 import { safeCompile } from "../util/safe-regex.js";
 export const POLICY_LINT_SCHEMA = 'sharkcraft.policy-lint/v1';
 function lineWithin(content, index) {
@@ -24,19 +27,34 @@ function markerNear(lines, line, marker) {
     return above !== undefined && above.includes(marker);
 }
 /**
- * Whether the zone rule keeps a match at `index`. `all` keeps everything; the
- * narrower zones require the match to START in the named zone. Not applied to
- * inline-template units (their content is already a string body).
+ * Whether the zone rule keeps a match at `index`.
+ *
+ * Delegates the zone semantics to {@link zoneKeepsAt} — the one authority the
+ * extraction DSL also reads — and adds only the policy-specific exemption:
+ * inline-template units are NOT zoned, because their content is already a
+ * string body lifted out of a source file.
  */
 function zoneKeeps(zone, unit, zones, index) {
     if (zone === 'all' || unit.inlineTemplate || zones === undefined)
         return true;
-    const kind = zoneAt(zones, index);
-    if (zone === 'code')
-        return kind === 'code';
-    if (zone === 'strings')
-        return kind === 'string';
-    return kind === 'comment';
+    return zoneKeepsAt(zone, zones, index);
+}
+/** Why a rule that scanned no content unit examined nothing. */
+const NO_UNITS_REASON = '0 content units matched the rule globs';
+/**
+ * What one policy rule examined: every content unit its globs matched (whole
+ * files, or inline-template bodies). A rule that scanned nothing, or is
+ * misconfigured, examined nothing — `expected: 0`, which core's
+ * `coverageShortfall` reports as a gap. The one derivation; every surface that
+ * settles a policy verdict reads the record this puts on the rule result.
+ */
+function policyCoverage(outcome) {
+    const unit = 'content units';
+    if (outcome.kind === 'error')
+        return { unit, expected: 0, examined: 0, reason: 'the rule is misconfigured' };
+    if (outcome.kind === 'skipped')
+        return { unit, expected: 0, examined: 0, reason: outcome.reason };
+    return { unit, expected: outcome.units, examined: outcome.units };
 }
 /**
  * Pure policy evaluation. Each rule's regex is run over the units the resolver
@@ -46,18 +64,66 @@ function zoneKeeps(zone, unit, zones, index) {
  * them, so `explain` can show what was matched AND what was let through. A
  * misconfigured rule (uncompilable regex) degrades to a diagnostic — never
  * throws, so one bad rule cannot crash the check.
+ *
+ * `scopeOf` reports each rule's read scope: the glob-matched files the one
+ * reader read and the ones it did not. A rule with an unread file in scope
+ * examined less than its globs matched, so its coverage is the file record
+ * (`readScopeCoverage`) and it is never a pass. When the unread file is why it
+ * scanned no unit at all, it is PARTIAL, not a `failOnEmpty` failure: it
+ * matched something it could not read, which is not "matched nothing".
+ */
+export function evaluatePolicy(rules, resolve, scopeOf, 
+/**
+ * The rule's own `files` judged per unit and settled with its `expectEmpty`
+ * markers (round 13) — `runPolicyLint` supplies it from the walk it already
+ * did. A rule that scanned nothing is decided from it by THE rule-emptiness
+ * settle (`settleRuleEmptiness`): every inclusion glob intended-empty and no
+ * file matched → accepted (`passed`, the acceptance as its coverage), never a
+ * failOnEmpty failure. Absent (hand-driven, or no own `files`): no unit is
+ * marked, so an empty rule is a loud skip exactly as before.
  */
-export function evaluatePolicy(rules, resolve) {
+livenessOf) {
     const ruleResults = [];
     const findings = [];
     const suppressed = [];
     const diagnostics = [];
     const skipped = [];
     let evaluated = 0;
+    let acceptedEmpty = 0;
     let misconfigError = false;
     let misconfigWarn = false;
-    for (const rule of rules) {
-        const severity = rule.severity ?? 'error';
+    for (const authored of rules) {
+        const severity = authored.severity ?? 'error';
+        // The engine entry normalises idempotently (round 13): a loaded rule comes
+        // back as the SAME object; a hand-built `{ pattern, expectEmpty }` entry is
+        // a unit plus a marker; a malformed entry is a misconfigured rule — never
+        // an object handed to a glob reader, never a crash.
+        const normalized = normalizeRuleList(authored, 'files');
+        if (!normalized.ok) {
+            const msg = `rule "${authored.id}": ${normalized.error.message}`;
+            diagnostics.push(msg);
+            if (severity === 'error')
+                misconfigError = true;
+            else
+                misconfigWarn = true;
+            ruleResults.push({
+                ruleId: authored.id,
+                surface: authored.surface,
+                severity,
+                status: 'error',
+                findingCount: 0,
+                suppressedCount: 0,
+                unitsScanned: 0,
+                error: msg,
+                coverage: policyCoverage({ kind: 'error' }),
+            });
+            evaluated += 1;
+            continue;
+        }
+        const rule = normalized.value;
+        const lv = livenessOf?.(rule);
+        const acceptance = lv?.liveness.acceptance;
+        const acceptanceField = acceptance !== undefined ? { unitAcceptance: acceptance } : {};
         const { re, error } = safeCompile(rule.pattern, rule.flags);
         if (error || !re) {
             const msg = `rule "${rule.id}": ${error}`;
@@ -75,6 +141,7 @@ export function evaluatePolicy(rules, resolve) {
                 suppressedCount: 0,
                 unitsScanned: 0,
                 error: msg,
+                coverage: policyCoverage({ kind: 'error' }),
             });
             // A misconfigured rule attempted to run — count it as evaluated so its
             // error isn't swallowed by the gate's `evaluated === 0` skip path.
@@ -148,18 +215,77 @@ export function evaluatePolicy(rules, resolve) {
                 suppressedCount,
                 unitsScanned: units.length,
                 error: msg,
+                coverage: policyCoverage({ kind: 'error' }),
             });
             evaluated += 1;
             continue;
         }
-        if (units.length === 0) {
-            const failed = failsWhenEmpty(rule);
-            skipped.push({
+        const scope = scopeOf?.(rule);
+        const unreadField = scope !== undefined && scope.unread.length > 0 ? { unread: scope.unread } : {};
+        if (units.length === 0 && readScopeHasUnread(scope)) {
+            // Its globs matched files, but the reader could not read them. That is
+            // not a stale glob: it ran over everything readable (nothing) and is
+            // PARTIAL, naming the unread files. Never failOnEmpty's 1, never a pass.
+            evaluated += 1;
+            ruleResults.push({
                 ruleId: rule.id,
-                reason: '0 content units matched the rule globs',
-                failed,
+                surface: rule.surface,
                 severity,
+                status: 'passed',
+                findingCount: 0,
+                suppressedCount: 0,
+                unitsScanned: 0,
+                ...unreadField,
+                ...acceptanceField,
+                coverage: readScopeCoverage(policyCoverage({ kind: 'skipped', reason: NO_UNITS_REASON }), scope),
             });
+            continue;
+        }
+        if (units.length === 0) {
+            // THE rule-emptiness settle (round 13, `settleRuleEmptiness`): every
+            // inclusion glob of the rule's own `files` marked `expectEmpty` and no
+            // file matched → the empty result is the INTENDED one, accepted and
+            // printed; anything else — a dead or unmarked glob, files that yielded no
+            // content unit — is the loud skip it always was (failOnEmpty's 1, else 2).
+            const emptiedBy = lv?.units.allExcluded === true ? lv.units.negations : undefined;
+            const emptiness = settleRuleEmptiness({
+                subject: rule.id,
+                unitLabel: 'content units',
+                filesMatched: scope?.read ?? 0,
+                unitsMatched: 0,
+                unread: false,
+                emptiedByNegations: emptiedBy !== undefined,
+                ...(emptiedBy !== undefined ? { emptiedReason: `0 content units: ${allExcludedCause(emptiedBy)}` } : {}),
+                liveness: lv?.liveness ?? settleGlobLists({ subject: rule.id, lists: [], marks: [] }),
+                primaryLists: ['files'],
+                failOnEmpty: failsWhenEmpty(rule),
+                noFilesReason: NO_UNITS_REASON,
+                noUnitsReason: NO_UNITS_REASON,
+            });
+            if (emptiness.state === RuleEmptiness.IntendedEmpty && emptiness.coverage !== undefined) {
+                // Counted in `evaluated` (the verdict path's "nothing ran" guard must
+                // never read an accepted plan as a skip) AND in `acceptedEmpty`, which
+                // a renderer subtracts: `N evaluated, M accepted as intended-empty`.
+                evaluated += 1;
+                acceptedEmpty += 1;
+                ruleResults.push({
+                    ruleId: rule.id,
+                    surface: rule.surface,
+                    severity,
+                    status: 'passed',
+                    findingCount: 0,
+                    suppressedCount: 0,
+                    unitsScanned: 0,
+                    ...unreadField,
+                    // The acceptance IS the rule's coverage (the same record, folded once).
+                    coverage: emptiness.coverage,
+                    unitAcceptance: emptiness.coverage,
+                });
+                continue;
+            }
+            const failed = emptiness.fails;
+            const reason = emptiness.skipReason ?? NO_UNITS_REASON;
+            skipped.push({ ruleId: rule.id, reason, failed, severity });
             if (failed) {
                 if (severity === 'error')
                     misconfigError = true;
@@ -174,6 +300,9 @@ export function evaluatePolicy(rules, resolve) {
                 findingCount: 0,
                 suppressedCount: 0,
                 unitsScanned: 0,
+                ...unreadField,
+                ...acceptanceField,
+                coverage: readScopeCoverage(policyCoverage({ kind: 'skipped', reason: emptiedBy !== undefined ? allExcludedCause(emptiedBy) : reason }), scope),
             });
             continue;
         }
@@ -186,6 +315,9 @@ export function evaluatePolicy(rules, resolve) {
             findingCount: count,
             suppressedCount,
             unitsScanned: units.length,
+            ...unreadField,
+            ...acceptanceField,
+            coverage: readScopeCoverage(policyCoverage({ kind: 'ran', units: units.length }), scope),
         });
     }
     const hasError = misconfigError || findings.some((f) => f.severity === 'error');
@@ -198,6 +330,7 @@ export function evaluatePolicy(rules, resolve) {
         suppressed,
         skipped,
         evaluated,
+        acceptedEmpty,
         verdict: hasError ? 'errors' : hasWarn ? 'warnings' : 'pass',
     };
 }

package/dist/policy/i-policy-rule-liveness.d.ts

@@ -0,0 +1,15 @@
+import type { ISettledUnitLiveness } from '@shrkcrft/core';
+import type { IGlobListUnits } from '../util/i-glob-list-units.js';
+/**
+ * One policy rule's own `files` judged per unit and settled with its
+ * `expectEmpty` markers (round 13) — what `evaluatePolicy` decides a rule that
+ * scanned nothing from (`settleRuleEmptiness`), and what `runPolicyLint`
+ * reports as its dead / intended-empty / went-live units.
+ */
+export interface IPolicyRuleLiveness {
+    /** The list's units, by the one dead-unit decision (`globListUnits`). */
+    readonly units: IGlobListUnits;
+    /** The settle (`settleUnitLiveness` over `globListLivenessInput`). */
+    readonly liveness: ISettledUnitLiveness;
+}
+//# sourceMappingURL=i-policy-rule-liveness.d.ts.map

package/dist/policy/i-policy-rule-liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-policy-rule-liveness.d.ts","sourceRoot":"","sources":["../../src/policy/i-policy-rule-liveness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;CACzC"}

package/dist/policy/i-policy-rule-liveness.js

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

package/dist/policy/run-policy.d.ts

@@ -1,4 +1,4 @@
-import type { IPolicyRule, PolicySurface } from '@shrkcrft/core';
+import { type IPolicyRule, type PolicySurface } from '@shrkcrft/core';
 import { type IPolicyReport } from './evaluate-policy.js';
 export interface IRunPolicyOptions {
     /** Restrict to rules on these surfaces. */

package/dist/policy/run-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-policy.d.ts","sourceRoot":"","sources":["../../src/policy/run-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIjE,OAAO,EAAkB,KAAK,aAAa,EAAoB,MAAM,sBAAsB,CAAC;AAY5F,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CAkEf"}
+{"version":3,"file":"run-policy.d.ts","sourceRoot":"","sources":["../../src/policy/run-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AASxB,OAAO,EAAkB,KAAK,aAAa,EAAoB,MAAM,sBAAsB,CAAC;AAa5F,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AA2BD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,OAAO,GAAE,iBAAsB,GAC9B,aAAa,CAgMf"}

package/dist/policy/run-policy.js

@@ -1,6 +1,11 @@
 import * as nodePath from 'node:path';
-import { matchesAny } from "../scan/glob.js";
+import { normalizeRuleList, settleUnitLiveness, unitStateLists, UnitLivenessState, } from '@shrkcrft/core';
+import { globListSelects } from "../scan/glob.js";
+import { readScopeHasUnread, readScopeOf, unreadEntryWhollyMatches } from "../util/read-scope-coverage.js";
 import { readMatchingFiles } from "../util/walk-files.js";
+import { globListUnits } from "../util/dead-glob-units.js";
+import { globListLivenessInput } from "../util/glob-list-liveness-input.js";
+import { allExcludedCause } from "../util/negation-cause.js";
 import { extractInlineTemplates } from "./extract-templates.js";
 import { evaluatePolicy } from "./evaluate-policy.js";
 /** Per-surface default globs when a rule omits `files`. */
@@ -14,6 +19,25 @@ const SOURCE_EXT = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs'
 function globsFor(rule) {
     return rule.files && rule.files.length > 0 ? rule.files : SURFACE_DEFAULT_GLOBS[rule.surface];
 }
+// Why a rule scanned nothing when its OWN negations emptied its `files[]` is
+// THE shared cause (`allExcludedCause`, util/negation-cause.ts — the wiring
+// engine words its source side from the same module). The coverage reason
+// carries it bare (the shortfall line already says "0 content units"); the
+// skip reason leads with the count. `evaluatePolicy` words both.
+/** The report of a run with no rule in scope. */
+function emptyReport() {
+    return {
+        schema: 'sharkcraft.policy-lint/v1',
+        rules: [],
+        findings: [],
+        diagnostics: [],
+        suppressed: [],
+        skipped: [],
+        evaluated: 0,
+        acceptedEmpty: 0,
+        verdict: 'pass',
+    };
+}
 /**
  * Filesystem-backed policy-lint. Walks the project once; on the `template`
  * surface, source files contribute their inline `template:` bodies (with real
@@ -21,7 +45,19 @@ function globsFor(rule) {
  * output; the only IO is the read-only walk + reads.
  */
 export function runPolicyLint(projectRoot, rules, options = {}) {
-    let selected = rules;
+    // The engine entry normalises idempotently (round 13): a loaded rule comes
+    // back as the SAME object (so every per-rule memo below hits), a hand-built
+    // `{ pattern, expectEmpty }` entry becomes a unit plus a marker. A MALFORMED
+    // entry is left for `evaluatePolicy` to report as a misconfigured rule, and
+    // no glob reader below is ever handed it.
+    const malformed = new Set();
+    let selected = rules.map((r) => {
+        const n = normalizeRuleList(r, 'files');
+        if (n.ok)
+            return n.value;
+        malformed.add(r);
+        return r;
+    });
     if (options.surfaces && options.surfaces.length > 0) {
         const s = new Set(options.surfaces);
         selected = selected.filter((r) => s.has(r.surface));
@@ -32,29 +68,142 @@ export function runPolicyLint(projectRoot, rules, options = {}) {
     }
     if (options.changedOnly) {
         const changed = options.changedFiles ?? [];
-        selected = selected.filter((r) => changed.some((c) => matchesAny(c, globsFor(r))));
-    }
-    if (selected.length === 0) {
-        return {
-            schema: 'sharkcraft.policy-lint/v1',
-            rules: [],
-            findings: [],
-            diagnostics: [],
-            suppressed: [],
-            skipped: [],
-            evaluated: 0,
-            verdict: 'pass',
-        };
+        // A changed file the rule's own `files` EXCLUDE (a `!` entry) cannot put a
+        // finding in its scope, so it does not select the rule. A malformed rule
+        // has no footprint to prove it out of scope, so it stays in (and errors).
+        selected = selected.filter((r) => malformed.has(r) || changed.some((c) => globListSelects(c, globsFor(r))));
     }
+    if (selected.length === 0)
+        return emptyReport();
     // Under --changed-only, restrict the SCANNED files to the changed set too (not
     // just rule selection). Per-file regex findings have no cross-file dependency,
     // so a pre-existing violation in a file the diff never touched is out of scope
     // — this mirrors how `check boundaries`/wiring restrict to the changeset and
     // stops the gate failing RED on untouched legacy debt.
     const changedSet = options.changedOnly ? new Set(options.changedFiles ?? []) : undefined;
-    const allGlobs = [...new Set(selected.flatMap((r) => [...globsFor(r)]))];
-    const cache = readMatchingFiles(projectRoot, allGlobs, new Set(options.excludeDirs ?? []));
-    return evaluatePolicy(selected, (rule) => {
+    const excludeDirs = new Set(options.excludeDirs ?? []);
+    // One POSITIVE walk over the union; each rule selects its own units from it
+    // (`globListSelects`), so rule A's `!x` never removes x from rule B.
+    const allGlobs = [...new Set(selected.filter((r) => !malformed.has(r)).flatMap((r) => [...globsFor(r)]))];
+    const matched = readMatchingFiles(projectRoot, allGlobs, excludeDirs);
+    const cache = matched.files;
+    // The walk holds every file any selected rule's inclusion globs matched —
+    // the positive set — so a glob absent from it matched nothing.
+    const walked = [...cache.keys()];
+    const unitsByRule = new Map();
+    const unitsFor = (rule) => {
+        const memo = unitsByRule.get(rule);
+        if (memo !== undefined)
+            return memo;
+        const units = resolveUnits(rule);
+        unitsByRule.set(rule, units);
+        return units;
+    };
+    // What each rule's walk covered: the matched files in its scope (the
+    // changeset, under --changed-only) that were read, and the ones the reader
+    // reported UNREAD (over the read cap, or unreadable). The reader's own list
+    // is the one answer to "was this matched path left unexamined?". Nothing
+    // here re-derives the walk's skip rules or re-stats a path: a path the walk
+    // never reaches is neither read nor unread, which is exactly narrowing.
+    const scopeByRule = new Map();
+    const scopeFor = (rule) => {
+        const memo = scopeByRule.get(rule);
+        if (memo !== undefined)
+            return memo;
+        const raw = readScopeOf(matched, globsFor(rule), changedSet);
+        // An `exemptFiles` file's hits can only ever be suppressions, so leaving
+        // it unread cannot change the verdict: an explicit exemption is narrowing,
+        // not a gap (the keystone contract). Without this, a large exempted
+        // vendored or generated file made the rule NOT VERIFIED (2) for good, with
+        // no valve (`--allow-empty` never accepts a partial scope).
+        const exempt = rule.exemptFiles && rule.exemptFiles.length > 0 ? rule.exemptFiles : undefined;
+        const scope = exempt === undefined
+            ? raw
+            : { read: raw.read, unread: raw.unread.filter((u) => !unreadEntryWhollyMatches(u, exempt)) };
+        scopeByRule.set(rule, scope);
+        return scope;
+    };
+    // Per-glob units of the author's OWN `files[]`, off the walk this run already
+    // did, settled with the rule's `expectEmpty` markers (round 13): core's one
+    // authority, `settleUnitLiveness`, over THE gate-plane glob predicate
+    // (`globListLivenessInput`) — the same input `gates coverage` builds, so the
+    // two cannot disagree about one glob. The one dead-unit decision
+    // (`globListUnits`) judges a negation by what it EXCLUDES, and a glob that
+    // reaches an UNREAD file (or beneath an unlistable directory) the list keeps
+    // in scope is never dead. A surface's default globs are not a selector
+    // anyone wrote, so they are not judged.
+    const livenessByRule = new Map();
+    const livenessFor = (rule) => {
+        if (livenessByRule.has(rule))
+            return livenessByRule.get(rule);
+        const own = rule.files;
+        let value;
+        if (own !== undefined && own.length > 0 && !malformed.has(rule)) {
+            const units = globListUnits(walked, matched.unread, own);
+            const liveness = settleUnitLiveness(globListLivenessInput({
+                subject: rule.id,
+                lists: [{ list: 'files', globs: own, units }],
+                marks: rule.expectEmptyUnits ?? [],
+            }));
+            value = { units, liveness };
+        }
+        livenessByRule.set(rule, value);
+        return value;
+    };
+    // --changed-only SELECTS a rule because a changed PATH matches its globs,
+    // but the change may still put nothing in the rule's scope: the path was
+    // deleted, or it was read and holds nothing on the rule's surface (a `.ts`
+    // with no inline `template:` under a template rule), or it lies where no
+    // policy walk goes. That is narrowing — the change cannot have introduced a
+    // finding there — so the rule is narrowed out exactly like an unselected
+    // one, never reported as a rule that "matched nothing": `failOnEmpty` turns
+    // that into a FAILURE, so a pure deletion failed `policy-lint --changed-only`
+    // and, once `finish` / `shrk gate` stopped masking a selected rule that
+    // examined nothing, would have failed them too. A matched path left UNREAD
+    // keeps the rule in scope: PARTIAL, naming the file, never narrowed away.
+    const inScope = changedSet
+        ? selected.filter((rule) => malformed.has(rule) || unitsFor(rule).length > 0 || readScopeHasUnread(scopeFor(rule)))
+        : selected;
+    if (inScope.length === 0)
+        return emptyReport();
+    const report = evaluatePolicy(inScope, unitsFor, scopeFor, livenessFor);
+    // Each rule's units, reported: `evaluatePolicy` emits one result per rule, in
+    // order, so the index is the rule. Dead units are the UNMARKED dead ones
+    // only — a marked glob is intended-empty (accepted, on `unitAcceptance`) or
+    // went-live — and every non-live unit rides along for `--fail-on-dead-units`.
+    const skippedIds = new Set(report.skipped.map((s) => s.ruleId));
+    const ruleResults = report.rules.map((r, i) => {
+        const rule = inScope[i];
+        const lv = rule !== undefined ? livenessFor(rule) : undefined;
+        if (lv === undefined)
+            return r;
+        const settled = lv.liveness;
+        const deadSet = new Set(settled.dead.map((u) => u.unit));
+        const nonLive = settled.units.filter((u) => u.state !== UnitLivenessState.Live);
+        const listed = settled.dead.length + settled.intendedEmpty.length + settled.wentLive.length > 0;
+        // A rule its OWN negations emptied is not a stale selector: every file its
+        // inclusion globs select was excluded as written.
+        const emptied = lv.units.allExcluded && skippedIds.has(r.ruleId);
+        return {
+            ...r,
+            ...(deadSet.size > 0
+                ? {
+                    deadGlobs: lv.units.dead.filter((d) => deadSet.has(d.glob)).map((d) => d.glob),
+                    deadGlobUnits: lv.units.dead.filter((d) => deadSet.has(d.glob)),
+                }
+                : {}),
+            ...(lv.units.negations.length > 0 ? { negations: lv.units.negations } : {}),
+            ...(listed ? { units: unitStateLists(settled) } : {}),
+            ...(nonLive.length > 0 ? { unitLiveness: nonLive } : {}),
+            ...(emptied
+                ? { excludedByNegations: lv.units.negations, coverage: { ...r.coverage, reason: allExcludedCause(lv.units.negations) } }
+                : {}),
+        };
+    });
+    return { ...report, rules: ruleResults };
+    function resolveUnits(rule) {
+        if (malformed.has(rule))
+            return [];
         const globs = globsFor(rule);
         // `exemptFiles` never removes the file from the scan — it MARKS it, so the
         // hits it would have produced are reported as suppressed rather than
@@ -65,9 +214,10 @@ export function runPolicyLint(projectRoot, rules, options = {}) {
         for (const [path, content] of cache) {
             if (changedSet && !changedSet.has(path))
                 continue;
-            if (!matchesAny(path, globs))
+            // `files` `!` EXCLUDES (the file is out of scope); `exemptFiles` MARKS.
+            if (!globListSelects(path, globs))
                 continue;
-            const exemptFile = exempt !== undefined && matchesAny(path, exempt);
+            const exemptFile = exempt !== undefined && globListSelects(path, exempt);
             const ext = nodePath.extname(path).toLowerCase();
             if (rule.surface === 'template' && SOURCE_EXT.has(ext)) {
                 for (const tpl of extractInlineTemplates(content)) {
@@ -86,5 +236,5 @@ export function runPolicyLint(projectRoot, rules, options = {}) {
             }
         }
         return units;
-    });
+    }
 }