vigiles 14.0.0 → 14.2.0

package/dist/rule-routing.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LANE_META = void 0;
 exports.routeRules = routeRules;
 exports.mergeRoutings = mergeRoutings;
 /**
@@ -41,6 +42,7 @@ exports.mergeRoutings = mergeRoutings;
  */
 const segment_js_1 = require("./segment.js");
 const rule_inventory_js_1 = require("./rule-inventory.js");
+const rule_signals_js_1 = require("./rule-signals.js");
 /** The mechanism each category maps to — a fixed, honest ladder. */
 const MECHANISM = {
     reuse: "config-line",
@@ -49,6 +51,28 @@ const MECHANISM = {
     semantic: "prose",
     unrouted: "synthesize",
 };
+/**
+ * The user-facing presentation of each routing category — its glyph + lane
+ * label. The SINGLE SOURCE the terminal summary reads (and the HTML report
+ * mirrors), so the category-name → lane-label mapping lives in one place.
+ *
+ * NB the type name `unrouted` is a WIRE value (it appears in the versioned
+ * `AuditReport` JSON), which is why it isn't renamed to its lane label `custom`;
+ * this table is where the human-facing name is resolved. The category meanings
+ * are documented in the file header; the mapping is tabled in
+ * `research/rule-enforcer-design.md` §4.
+ */
+exports.LANE_META = {
+    reuse: { glyph: "✓", label: "enforceable" },
+    hook: { glyph: "⛓", label: "hook" },
+    unrouted: { glyph: "⚙", label: "custom" },
+    semantic: { glyph: "✎", label: "judgment" },
+    meta: { glyph: "☰", label: "agent-note" },
+};
+// NORM_SIGNAL (a deontic modal ANYWHERE) keeps the POSSIBLE review tier to
+// genuine rule-candidates the imperative gate missed ("every function MUST have
+// a docstring") instead of arbitrary prose. It lives in ./rule-signals.ts
+// alongside the segment gate's RULE_PREDICATE twin so the two can't drift.
 /**
  * ACTION-rule cues — things a linter never sees (git, filesystem, shell,
  * process). A hook is the right gate, not a lint rule. Widened to the article's
@@ -56,7 +80,7 @@ const MECHANISM = {
  * (git-push + rm-rf only) reported ~2% hooks where the 252-rule hand-sort found
  * **37%** (the largest bucket); it was missing push-to-branch, before-push,
  * after-edit, tool-substitution, amend/rebase-pushed, and dependency guards.
- * See `research/rule-compiler-multilang-design.md` §5b (the hook lane).
+ * See `research/rule-enforcer-multilang-design.md` §5b (the hook lane).
  */
 const HOOK_CUES = [
     // — branch / push guards (vcs) —
@@ -155,38 +179,41 @@ const META_CUES = [
     /\bre-?fetch(?:ing)?\b/i,
     /\bwithout code changes\b/i,
 ];
+/** Every construct-prohibition maps to the same ESLint rule with a different
+ * selector — one named constant so the shared id isn't repeated as a literal. */
+const NO_RESTRICTED_SYNTAX = "no-restricted-syntax";
 const PATTERN_RULE_MAP = [
     {
         construct: "default exports",
-        rule: "no-restricted-syntax",
+        rule: NO_RESTRICTED_SYNTAX,
         linter: "eslint",
         pattern: /\b(?:no|never|avoid|don'?t\s+use|do\s+not\s+use|disallow|ban|forbid|prefer\s+named\s+(?:exports?\s+)?over)\b[^.\n]{0,24}\bdefault\s+exports?\b/i,
         configFix: '"no-restricted-syntax": ["error", { "selector": "ExportDefaultDeclaration", "message": "Use named exports." }]',
     },
     {
         construct: "enums",
-        rule: "no-restricted-syntax",
+        rule: NO_RESTRICTED_SYNTAX,
         linter: "eslint",
         pattern: /\b(?:no|never|avoid|don'?t\s+use|do\s+not\s+use|disallow|ban|forbid)\b[^.\n]{0,24}\benums?\b/i,
         configFix: '"no-restricted-syntax": ["error", { "selector": "TSEnumDeclaration", "message": "Use a union or const object instead of an enum." }]',
     },
     {
         construct: "for...in",
-        rule: "no-restricted-syntax",
+        rule: NO_RESTRICTED_SYNTAX,
         linter: "eslint",
         pattern: /\b(?:no|never|avoid|don'?t\s+use|do\s+not\s+use|disallow|ban|forbid)\b[^.\n]{0,16}\bfor[\s.]{0,3}in\b/i,
         configFix: '"no-restricted-syntax": ["error", { "selector": "ForInStatement", "message": "Use for...of or Object.keys()." }]',
     },
     {
         construct: "namespaces",
-        rule: "no-restricted-syntax",
+        rule: NO_RESTRICTED_SYNTAX,
         linter: "eslint",
         pattern: /\b(?:no|never|avoid|don'?t\s+use|do\s+not\s+use|disallow|ban|forbid)\b[^.\n]{0,24}\bnamespaces?\b/i,
         configFix: '"no-restricted-syntax": ["error", { "selector": "TSModuleDeclaration", "message": "Use ES modules instead of namespaces." }]',
     },
     {
         construct: "classes",
-        rule: "no-restricted-syntax",
+        rule: NO_RESTRICTED_SYNTAX,
         linter: "eslint",
         pattern: /\b(?:no|never|avoid|don'?t\s+use|do\s+not\s+use|disallow|ban|forbid)\b[^.\n]{0,12}\b(?<!css |style |styling |utility |tailwind |dom |react |component )(?:es6?\s+|javascript\s+)?class(?:es)?\b(?![\s-]*(?:name|attribute|selector|list))/i,
         configFix: '"no-restricted-syntax": ["error", { "selector": ":matches(ClassDeclaration, ClassExpression)", "message": "Prefer functions and closures over classes." }]',
@@ -221,27 +248,54 @@ function namedRuleTokens(text) {
     }
     return out;
 }
-/**
- * Route one atomic rule. Order matters: an ACTION cue (git push) wins over a
- * rule-name mention ("never commit console.log" is a hook, not a lint rule); a
- * META agent-instruction is pulled out before reuse so it isn't mismatched to a
- * rule; the DYNAMIC catalog (if present) and the static `INTENT_MAP` both feed
- * `reuse`; reuse wins over a soft semantic cue.
- */
+/** Combine two hits that a doc-token resolves to (a cross-linter id collision).
+ * enabled OR-s — a "**Enforced by:** X" claim is satisfied if ANY linter has X
+ * on, so we never cry "documented but OFF" when one linter enforces it — and
+ * provenance follows the enforcing linter. */
+function combineHits(a, b) {
+    if (a.enabled === b.enabled)
+        return { enabled: a.enabled, linter: a.linter };
+    return a.enabled ? a : b; // exactly one is on → it wins (enabled OR-s to true)
+}
+/** Build the doc-token → hit lookup from a (possibly polyglot) rule list. A rule
+ * is matchable by its id AND, for Pylint, its numeric code. A bare id CAN collide
+ * across linters (`no-else-return` is in both ESLint and Pylint) → combine
+ * conservatively. A numeric code is unique to its linter, so it never collides
+ * and KEEPS its own (linter, enabled) — a doc naming the Pylint code `R1705`
+ * still surfaces "documented but OFF" even when the symbol is enabled in ESLint. */
+function buildCatalogLookup(rules) {
+    const map = new Map();
+    const put = (key, hit) => {
+        const prev = map.get(key);
+        map.set(key, prev ? combineHits(prev, hit) : hit);
+    };
+    for (const r of rules) {
+        const hit = { enabled: r.enabled, linter: r.linter };
+        put(r.id, hit);
+        if (r.code)
+            put(r.code, hit);
+    }
+    return map;
+}
 function classify(text, catalog) {
     if (HOOK_CUES.some((re) => re.test(text)))
         return { category: "hook" };
     if (META_CUES.some((re) => re.test(text)))
         return { category: "meta" };
     // Dynamic catalog: a bullet that NAMES one of the repo's real rules → reuse,
-    // carrying whether it's currently enabled (a disabled hit = the "documented but
-    // OFF" nudge). Own-repo only — catalog is present only when the linter was
-    // enumerated with consent.
+    // carrying its linter + whether it's currently enabled (a disabled hit = the
+    // "documented but OFF" nudge). Own-repo only — catalog is present only when the
+    // linter was enumerated with consent.
     if (catalog) {
         for (const tok of namedRuleTokens(text)) {
-            const enabled = catalog.get(tok);
-            if (enabled !== undefined)
-                return { category: "reuse", rule: tok, enabled };
+            const hit = catalog.get(tok);
+            if (hit !== undefined)
+                return {
+                    category: "reuse",
+                    rule: tok,
+                    enabled: hit.enabled,
+                    linter: hit.linter,
+                };
         }
     }
     for (const m of rule_inventory_js_1.INTENT_MAP) {
@@ -266,11 +320,15 @@ const GUARD_RE = /^\*\*Guard:\*\*/;
 const GUIDANCE_RE = /^\*\*Guidance only\*\*/;
 const MARK_HEADING = /^(#{2,6})\s+(.*)$/;
 const RULE_ID_SHAPE = /^@?[a-z][a-z0-9._/-]*$/;
+// Pylint's numeric alias (C0116, W9006) — the catalog advertises these as
+// matchable, so a marker using one must parse as a rule id, not a prose claim.
+const PYLINT_CODE_SHAPE = /^[A-Z]\d+$/;
 /** Does this `**Enforced by:**` value parse as a lint-rule id (vs a prose claim
  * like "CI" or "the linter")? A hand-written marker is a CLAIM — only a rule-id
  * shape is treated as a real reuse rule. */
 function looksLikeRuleId(s) {
-    return s.length >= 3 && RULE_ID_SHAPE.test(s.trim());
+    const t = s.trim();
+    return (t.length >= 3 && RULE_ID_SHAPE.test(t)) || PYLINT_CODE_SHAPE.test(t);
 }
 /**
  * Extract rules from EXPLICIT structured markers (`**Enforced by:** \`rule\``,
@@ -284,6 +342,60 @@ function looksLikeRuleId(s) {
  * is a CLAIM — only a rule-id-shaped value becomes a reuse rule (gated + verified
  * against the catalog when present; never an inferred contradiction).
  */
+/** A `**Guidance only**` body is prose UNLESS its text is really an action/agent
+ * cue (promote-prose): route the whole body through classify and keep it prose
+ * (`semantic`) unless classify sees a genuine hook/meta signal. */
+function guidanceClassification(section, catalog) {
+    const c = classify(section.slice(1).join(" "), catalog);
+    return c.category === "hook" || c.category === "meta"
+        ? c
+        : { category: "semantic" };
+}
+/** Scan a marked section's BODY for the FIRST structured marker and return its
+ * classification, or null if the section declares none (or an `**Enforced by:**`
+ * whose value is a prose claim, not a rule id). */
+function markerFor(section, catalog) {
+    for (const raw of section.slice(1)) {
+        const bl = raw.trim();
+        const em = ENFORCED_RE.exec(bl);
+        if (em) {
+            if (!looksLikeRuleId(em[1]))
+                return null; // a prose claim, not a rule id
+            const rule = em[1].trim();
+            const hit = catalog?.get(rule);
+            return {
+                category: "reuse",
+                rule,
+                ...(hit !== undefined
+                    ? { enabled: hit.enabled, linter: hit.linter }
+                    : {}),
+            };
+        }
+        if (GUARD_RE.test(bl))
+            return { category: "hook" };
+        if (GUIDANCE_RE.test(bl))
+            return guidanceClassification(section, catalog);
+    }
+    return null;
+}
+/** Build a definitive (zero-heuristic) marker `RoutedRule` from a classification
+ * and its source location. */
+function markerRuleFrom(marked, loc) {
+    return {
+        text: loc.text,
+        quote: loc.quote,
+        file: loc.file,
+        lineStart: loc.lineStart,
+        lineEnd: loc.lineEnd,
+        confidence: "high",
+        category: marked.category,
+        mechanism: MECHANISM[marked.category],
+        source: "marker",
+        ...(marked.rule ? { rule: marked.rule } : {}),
+        ...(marked.linter ? { linter: marked.linter } : {}),
+        ...(marked.enabled !== undefined ? { enabled: marked.enabled } : {}),
+    };
+}
 function extractMarkedRules(text, file, catalog) {
     const lines = text.split("\n");
     const rules = [];
@@ -295,63 +407,92 @@ function extractMarkedRules(text, file, catalog) {
         let j = i + 1;
         while (j < lines.length && !MARK_HEADING.test(lines[j]))
             j++;
-        const section = lines.slice(i, j); // [heading … next-heading)
-        const heading = h[2].trim();
-        let marked = null;
-        for (const raw of section.slice(1)) {
-            const bl = raw.trim();
-            const em = ENFORCED_RE.exec(bl);
-            if (em) {
-                if (!looksLikeRuleId(em[1]))
-                    break; // a prose claim, not a rule id
-                const enabled = catalog?.get(em[1].trim());
-                marked = {
-                    category: "reuse",
-                    rule: em[1].trim(),
-                    ...(enabled !== undefined ? { enabled } : {}),
-                };
-                break;
-            }
-            if (GUARD_RE.test(bl)) {
-                marked = { category: "hook" };
-                break;
-            }
-            if (GUIDANCE_RE.test(bl)) {
-                // Route the guidance BODY through classify (promote-prose): a guidance
-                // whose text is really an action shows up as a would-be hook.
-                const body = section.slice(1).join(" ");
-                const c = classify(body, catalog);
-                // A guidance body that names a catalog rule is still "documented as
-                // guidance" — keep it prose unless it's a genuine action/agent cue.
-                marked =
-                    c.category === "hook" || c.category === "meta"
-                        ? c
-                        : { category: "semantic" };
-                break;
-            }
-        }
+        const marked = markerFor(lines.slice(i, j), catalog);
         if (!marked)
             continue;
         // Consume the section BODY lines (heading stays a non-candidate) so the
         // heuristic segmenter never re-emits this marked rule. (1-based.)
         for (let k = i + 1; k < j; k++)
             skip.add(k + 1);
-        rules.push({
-            text: heading,
+        rules.push(markerRuleFrom(marked, {
+            text: h[2].trim(),
             quote: lines[i],
             file,
             lineStart: i + 1,
             lineEnd: j,
-            confidence: "high",
-            category: marked.category,
-            mechanism: MECHANISM[marked.category],
-            source: "marker",
-            ...(marked.rule ? { rule: marked.rule } : {}),
-            ...(marked.enabled !== undefined ? { enabled: marked.enabled } : {}),
-        });
+        }));
     }
     return { rules, skip };
 }
+/** The rescue sources, OR-ed (any one promotes a bullet to confident). They are
+ * the higher-precision override of the segmenter's imperative-head cue, which
+ * alone would drop these medium-scoring bullets. */
+const RESCUE_SOURCES = [
+    // catalog — the text NAMES a rule the repo's live catalog actually has (ground
+    // truth, own-repo): rescues "The core layer must not import X (`boundaries/…`)".
+    (t, cat) => cat !== undefined && namedRuleTokens(t).some((tok) => cat.has(tok)),
+    // pattern — a construct-prohibition ("No default exports") → a real
+    // `no-restricted-syntax` rule.
+    (t) => PATTERN_RULE_MAP.some((r) => r.pattern.test(t)),
+    // intent — an INTENT_MAP keyword match ("No bare except clauses"): a
+    // code-shaped, high-precision reuse rule with no imperative verb.
+    (t) => rule_inventory_js_1.INTENT_MAP.some((m) => m.keywords.some((kw) => (0, rule_inventory_js_1.matchesWholeToken)(t, kw))),
+];
+/** A bullet is RESCUED — promoted to confident — if any rescue source maps it to
+ * a real off-the-shelf rule (independent of the medium opt-in). */
+function isRescued(text, catalog) {
+    return RESCUE_SOURCES.some((rescue) => rescue(text, catalog));
+}
+const foldToCandidate = (s) => ({
+    text: s.text,
+    exactQuote: s.text,
+    file: s.file,
+    lineStart: s.lineStart,
+    lineEnd: s.lineEnd,
+    confidence: "medium",
+});
+const toNoSignalSkip = (s) => ({
+    text: s.text,
+    file: s.file,
+    lineStart: s.lineStart,
+    lineEnd: s.lineEnd,
+    reason: "no-signal",
+});
+/**
+ * Split segmenter output into the three routed tiers:
+ *
+ * - CONFIDENT — high, a medium opt-in, or a RESCUE (names/matches a real rule).
+ * - POSSIBLE — a non-confident leftover carrying a norm modal (`NORM_SIGNAL`):
+ *   a genuine recall-miss surfaced for review ("every function must have a
+ *   docstring"), not routed as fact.
+ * - SKIPPED — the rest (index/description/section rejects + no-signal leftovers).
+ *
+ * THE LOAD-BEARING ASYMMETRY: a gate-rejected `no-signal` bullet is folded back
+ * as a candidate but promoted to confident ONLY by a RESCUE — NEVER by the
+ * blanket medium opt-in, which must not resurrect what the gate explicitly
+ * rejected. See `research/rule-enforcer-design.md` §2.
+ */
+function partitionCandidates(segments, rawSkipped, catalog, minConfidence) {
+    const rescued = (t) => isRescued(t, catalog);
+    const isConfident = (s) => minConfidence === "medium" || s.confidence === "high" || rescued(s.text);
+    const folds = rawSkipped
+        .filter((s) => s.reason === "no-signal")
+        .map(foldToCandidate);
+    const confident = [
+        ...segments.filter(isConfident),
+        ...folds.filter((s) => rescued(s.text)),
+    ];
+    const leftover = [
+        ...segments.filter((s) => !isConfident(s)),
+        ...folds.filter((s) => !rescued(s.text)),
+    ];
+    const possible = leftover.filter((s) => rule_signals_js_1.NORM_SIGNAL.test(s.text));
+    const skipped = [
+        ...rawSkipped.filter((s) => s.reason !== "no-signal"),
+        ...leftover.filter((s) => !rule_signals_js_1.NORM_SIGNAL.test(s.text)).map(toNoSignalSkip),
+    ];
+    return { confident, possible, skipped };
+}
 /**
  * Segment the instruction file and route every atomic rule deterministically.
  * Pure: the caller passes the concatenated instruction text (and an optional
@@ -360,36 +501,9 @@ function extractMarkedRules(text, file, catalog) {
 function routeRules(instructionText, file, options = {}) {
     const minConfidence = options.minConfidence ?? "high";
     const catalog = options.availableRules
-        ? new Map(options.availableRules.rules.map((r) => [r.id, r.enabled]))
+        ? buildCatalogLookup(options.availableRules.rules)
         : undefined;
-    // A MEDIUM segment that NAMES a rule the repo's catalog actually has is
-    // enforceable — the catalog is ground truth, so it's higher-precision than the
-    // segmenter's imperative-head cue. This rescues declarative-subject bullets
-    // ("The core layer must not import X (`boundaries/dependencies`)") that score
-    // medium (context+shape, no imperative head) and are otherwise dropped by the
-    // high-only default. Own-repo only (catalog present ⇒ enumerated with consent);
-    // the foreign-safe textual path stays conservative by design.
-    const namesCatalogRule = (text) => catalog !== undefined &&
-        namedRuleTokens(text).some((tok) => catalog.has(tok));
-    // A MEDIUM segment matching a construct-prohibition ("No default exports")
-    // scores medium ("No" is a prohibition head, not a verb) but is a real reuse
-    // rule (no-restricted-syntax) — rescue it, same as the catalog rescue. The
-    // patterns are their own precision gate (prohibition + construct proximity).
-    const matchesPatternRule = (text) => PATTERN_RULE_MAP.some((r) => r.pattern.test(text));
-    // A MEDIUM segment that matches an INTENT_MAP keyword (code-shaped, high-
-    // precision) is a real reuse rule — rescue it, same as catalog/restricted-
-    // syntax. Fixes construct-prohibitions with no verb ("No bare except clauses")
-    // that score medium and would otherwise drop before classify() reuses them.
-    const matchesIntentMap = (text) => rule_inventory_js_1.INTENT_MAP.some((m) => m.keywords.some((kw) => (0, rule_inventory_js_1.matchesWholeToken)(text, kw)));
-    // S0/S1 pre-pass: explicit markers are definitive and are CONSUMED (their body
-    // lines are skipped) so the heuristic segmenter can't double-count them.
-    const marked = extractMarkedRules(instructionText, file, catalog);
-    const segments = (0, segment_js_1.segmentInstructions)(instructionText, file, marked.skip).filter((s) => minConfidence === "medium" ||
-        s.confidence === "high" ||
-        namesCatalogRule(s.text) ||
-        matchesPatternRule(s.text) ||
-        matchesIntentMap(s.text));
-    const heuristicRules = segments.map((s) => {
+    const toRouted = (s) => {
         const c = classify(s.text, catalog);
         return {
             text: s.text,
@@ -405,9 +519,18 @@ function routeRules(instructionText, file, options = {}) {
             ...(c.linter ? { linter: c.linter } : {}),
             ...(c.enabled !== undefined ? { enabled: c.enabled } : {}),
         };
-    });
-    // Marker rules first (definitive), then the heuristic residue.
-    const rules = [...marked.rules, ...heuristicRules];
+    };
+    // S0/S1 pre-pass: explicit markers are definitive and are CONSUMED (their body
+    // lines are skipped) so the heuristic segmenter can't double-count them. The
+    // segmenter output then splits into confident / possible / skipped tiers.
+    const marked = extractMarkedRules(instructionText, file, catalog);
+    const { segments, skipped: rawSkipped } = (0, segment_js_1.segmentInstructions)(instructionText, file, marked.skip);
+    const tiers = partitionCandidates(segments, rawSkipped, catalog, minConfidence);
+    // Marker rules first (definitive), then the confident heuristic residue.
+    const rules = [
+        ...marked.rules,
+        ...tiers.confident.map(toRouted),
+    ];
     const counts = {
         reuse: 0,
         hook: 0,
@@ -417,7 +540,13 @@ function routeRules(instructionText, file, options = {}) {
     };
     for (const r of rules)
         counts[r.category]++;
-    return { segmented: rules.length, counts, rules };
+    return {
+        segmented: rules.length,
+        counts,
+        rules,
+        possible: tiers.possible.map(toRouted),
+        skipped: tiers.skipped,
+    };
 }
 /**
  * Merge per-file routings into one. Each instruction source is routed SEPARATELY
@@ -434,13 +563,17 @@ function mergeRoutings(routings) {
         unrouted: 0,
     };
     const rules = [];
+    const possible = [];
+    const skipped = [];
     let segmented = 0;
     for (const r of routings) {
         segmented += r.segmented;
         rules.push(...r.rules);
+        possible.push(...r.possible);
+        skipped.push(...r.skipped);
         for (const k of Object.keys(counts))
             counts[k] += r.counts[k];
     }
-    return { segmented, counts, rules };
+    return { segmented, counts, rules, possible, skipped };
 }
 //# sourceMappingURL=rule-routing.js.map

package/dist/rule-signals.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared LEXICAL signals for "is this text a rule?" — the deontic/imperative
+ * vocabulary the detection pipeline keys on, kept in ONE home so the stages that
+ * use it can't silently drift. These previously lived as near-duplicate
+ * deontic-modal regexes in `segment.ts` (`RULE_PREDICATE`) and `rule-routing.ts`
+ * (`NORM_SIGNAL`) with no cross-reference.
+ *
+ * Two stages consume them:
+ *
+ *  - the segment GATE (`src/segment.ts`) — precision-first accept/reject. Uses
+ *    `FORM_HEAD` (an imperative/prohibitive sentence HEAD) as a rule cue, and
+ *    `RULE_PREDICATE` (a deontic modal ANYWHERE) to stop a code-span-led
+ *    sentence being mis-rejected as a description.
+ *  - the routing POSSIBLE filter (`src/rule-routing.ts`) — recall recovery. Uses
+ *    `NORM_SIGNAL` to keep the "possible (review)" tier to genuine recall-misses
+ *    (a bullet that carries a norm modal) instead of flooding it with prose.
+ *
+ * `NORM_SIGNAL` and `RULE_PREDICATE` are BOTH "deontic modal anywhere" matchers
+ * with slightly different word lists ON PURPOSE — different jobs, calibrated
+ * separately against the OSS corpus. They are kept ADJACENT here so a widening
+ * of one prompts a review of the other, rather than the two drifting apart in
+ * separate files. See `research/rule-enforcer-design.md` §2.
+ */
+/**
+ * An imperative/prohibitive sentence HEAD ("Never …", "Avoid …", "No …") — the
+ * segment gate's `form` cue. Anchored at the start (a HEAD, not anywhere). The
+ * deontic verbs (require/disallow/forbid/ban/enforce) are common rule leads
+ * ("Require `curly` braces", "Disallow `var`"). NB "no" is bare `no` + the
+ * shared trailing `\b` (a boundary right after "no" — before a space OR a
+ * backtick), so "No bare except" / "No default exports" / "No `any`" all match,
+ * while "Note"/"Nowhere" (no boundary after "no") are rejected. The earlier
+ * `no\s+\S` form silently failed "No bare except" (the measured bug).
+ */
+export declare const FORM_HEAD: RegExp;
+/**
+ * A deontic modal ANYWHERE in the text — routing's POSSIBLE-tier recall gate.
+ * Narrow (modal verbs only) so the review tier stays genuine recall-misses.
+ */
+export declare const NORM_SIGNAL: RegExp;
+/**
+ * A deontic predicate ANYWHERE — the segment gate's description-reject guard: a
+ * code-span-led sentence carrying one of these is a RULE ("`const` is preferred
+ * over `let`"), not a description, so the description reject must NOT fire.
+ */
+export declare const RULE_PREDICATE: RegExp;
+//# sourceMappingURL=rule-signals.d.ts.map

package/dist/rule-signals.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Shared LEXICAL signals for "is this text a rule?" — the deontic/imperative
+ * vocabulary the detection pipeline keys on, kept in ONE home so the stages that
+ * use it can't silently drift. These previously lived as near-duplicate
+ * deontic-modal regexes in `segment.ts` (`RULE_PREDICATE`) and `rule-routing.ts`
+ * (`NORM_SIGNAL`) with no cross-reference.
+ *
+ * Two stages consume them:
+ *
+ *  - the segment GATE (`src/segment.ts`) — precision-first accept/reject. Uses
+ *    `FORM_HEAD` (an imperative/prohibitive sentence HEAD) as a rule cue, and
+ *    `RULE_PREDICATE` (a deontic modal ANYWHERE) to stop a code-span-led
+ *    sentence being mis-rejected as a description.
+ *  - the routing POSSIBLE filter (`src/rule-routing.ts`) — recall recovery. Uses
+ *    `NORM_SIGNAL` to keep the "possible (review)" tier to genuine recall-misses
+ *    (a bullet that carries a norm modal) instead of flooding it with prose.
+ *
+ * `NORM_SIGNAL` and `RULE_PREDICATE` are BOTH "deontic modal anywhere" matchers
+ * with slightly different word lists ON PURPOSE — different jobs, calibrated
+ * separately against the OSS corpus. They are kept ADJACENT here so a widening
+ * of one prompts a review of the other, rather than the two drifting apart in
+ * separate files. See `research/rule-enforcer-design.md` §2.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RULE_PREDICATE = exports.NORM_SIGNAL = exports.FORM_HEAD = void 0;
+/**
+ * An imperative/prohibitive sentence HEAD ("Never …", "Avoid …", "No …") — the
+ * segment gate's `form` cue. Anchored at the start (a HEAD, not anywhere). The
+ * deontic verbs (require/disallow/forbid/ban/enforce) are common rule leads
+ * ("Require `curly` braces", "Disallow `var`"). NB "no" is bare `no` + the
+ * shared trailing `\b` (a boundary right after "no" — before a space OR a
+ * backtick), so "No bare except" / "No default exports" / "No `any`" all match,
+ * while "Note"/"Nowhere" (no boundary after "no") are rejected. The earlier
+ * `no\s+\S` form silently failed "No bare except" (the measured bug).
+ */
+exports.FORM_HEAD = /^(?:use|avoid|prefer|never|always|don'?t|do not|no|must|should|keep|run|write|add|remove|only|require|requires?|disallow|forbid|ban|enforce)\b/i;
+/**
+ * A deontic modal ANYWHERE in the text — routing's POSSIBLE-tier recall gate.
+ * Narrow (modal verbs only) so the review tier stays genuine recall-misses.
+ */
+exports.NORM_SIGNAL = /\b(?:must(?:n't)?|should(?:n't)?|shall|never|always|avoids?|require[sd]?|forbidden|disallow(?:ed)?|prohibited|banned?|prefers?|do not|don't)\b/i;
+/**
+ * A deontic predicate ANYWHERE — the segment gate's description-reject guard: a
+ * code-span-led sentence carrying one of these is a RULE ("`const` is preferred
+ * over `let`"), not a description, so the description reject must NOT fire.
+ */
+exports.RULE_PREDICATE = /\b(?:must|should|shall|never|always|require|avoid|prefer|banned|forbidden|prohibited|allowed|disallowed|deprecated|discouraged|mandatory|do not|don'?t|only|instead)\b/i;
+//# sourceMappingURL=rule-signals.js.map

package/dist/segment.d.ts

@@ -22,12 +22,45 @@ export interface SegmentedRule {
     /** 3/3 cues => "high"; 2/3 => "medium". (Rejected candidates are never emitted.) */
     confidence: "high" | "medium";
 }
+/** Why the segmenter decided a bullet is NOT a rule (the transparency signal —
+ * see `research/rule-enforcer-design.md` §3). `index`/`description`/`leadin`/
+ * `no-signal` come from the gate; `section` means it sits under a non-rule
+ * heading (Setup / Commands / Key Files / Architecture …).
+ *
+ * `leadin` is a colon-terminated procedure/enumeration HEADER ("To add a
+ * setting:", "Run the full test suite:", "Python check:") whose enforceable
+ * content — if any — lives in the sub-bullets/code-block it introduces (verified
+ * on the OSS corpus: the sub-items are segmented independently, so dropping the
+ * header loses nothing). Kept DISTINCT from `no-signal` on purpose: routing
+ * re-surfaces `no-signal` skips in the "possible (review)" recall tier, and a
+ * lead-in is a CONFIDENT drop that must not re-enter that tier. */
+export type RejectReason = "index" | "description" | "leadin" | "no-signal" | "section";
+/** A BULLET the segmenter saw but did NOT treat as a rule, with the reason — so
+ * the audit report can be honest about what it set aside (a heuristic misses
+ * declarative rules; showing skips lets a human eyeball a wrong drop). Bounded to
+ * list items on purpose; rejected paragraph prose is not reported (too noisy). */
+export interface SkippedBullet {
+    readonly text: string;
+    readonly file: string | undefined;
+    readonly lineStart: number;
+    readonly lineEnd: number;
+    readonly reason: RejectReason;
+}
+/** The segmenter's full output: the confident/medium candidate rules PLUS the
+ * bullets it rejected (with reasons), so nothing is silently dropped. */
+export interface SegmentResult {
+    readonly segments: SegmentedRule[];
+    readonly skipped: SkippedBullet[];
+}
 /**
  * Split a CLAUDE.md / AGENTS.md into atomic candidate rules with provenance.
  *
  * Deterministic Tier-A heuristic. Code fences and tables are excluded from
  * candidacy. Candidate units are (a) list items with attached continuation
- * lines and (b) sentences of paragraphs under a rule-ish heading.
+ * lines and (b) sentences of paragraphs under a rule-ish heading. This function
+ * is a thin DISPATCHER — each block type is handled by its own pure helper
+ * (`handleListItem` / `handleParagraph`); the state it threads is the fence
+ * toggle and the current `HeadingState`.
  */
-export declare function segmentInstructions(markdown: string, file?: string, skipLines?: ReadonlySet<number>): SegmentedRule[];
+export declare function segmentInstructions(markdown: string, file?: string, skipLines?: ReadonlySet<number>): SegmentResult;
 //# sourceMappingURL=segment.d.ts.map