vigiles 14.1.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",
@@ -50,13 +52,27 @@ const MECHANISM = {
     unrouted: "synthesize",
 };
 /**
- * A deontic/norm signal ANYWHERE in a bullet — the marker of a rule the imperative
- * gate missed because the norm isn't at the head ("every function MUST have a
- * docstring", "public APIs SHOULD stay stable"). Used to keep the POSSIBLE review
- * tier to genuine rule-candidates instead of arbitrary unparsed prose. Deliberately
- * narrow (modal verbs only) so it doesn't re-admit the noise it exists to exclude.
+ * 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.
  */
-const 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;
+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
@@ -64,7 +80,7 @@ const NORM_SIGNAL = /\b(?:must(?:n't)?|should(?:n't)?|shall|never|always|avoids?
  * (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) —
@@ -163,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." }]',
@@ -323,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 = [];
@@ -334,66 +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 hit = catalog?.get(em[1].trim());
-                marked = {
-                    category: "reuse",
-                    rule: em[1].trim(),
-                    ...(hit !== undefined
-                        ? { enabled: hit.enabled, linter: hit.linter }
-                        : {}),
-                };
-                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.linter ? { linter: marked.linter } : {}),
-            ...(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
@@ -404,35 +503,6 @@ function routeRules(instructionText, file, options = {}) {
     const catalog = options.availableRules
         ? 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)));
-    // A segment is CONFIDENT if it's high, rescued by the catalog/pattern/intent, or
-    // the caller opted into medium. Everything else the segmenter emitted is a
-    // POSSIBLE rule (medium, unrescued) — surfaced for review, not routed as fact.
-    // A RESCUE — the text NAMES/matches a real rule (catalog / restricted-syntax /
-    // intent). This promotes even a gate-rejected bullet to confident, because it
-    // provably maps to an off-the-shelf rule; independent of the medium opt-in.
-    const isRescued = (text) => namesCatalogRule(text) ||
-        matchesPatternRule(text) ||
-        matchesIntentMap(text);
-    const isConfident = (s) => minConfidence === "medium" || s.confidence === "high" || isRescued(s.text);
     const toRouted = (s) => {
         const c = classify(s.text, catalog);
         return {
@@ -451,58 +521,16 @@ function routeRules(instructionText, file, options = {}) {
         };
     };
     // 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.
+    // 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);
-    // A bullet the gate rejected as `no-signal` is a rule CANDIDATE only if it
-    // carries a deontic/norm signal (a modal like must/should/never/avoid) — that
-    // keeps the POSSIBLE review tier to genuine recall-misses ("every function must
-    // have a docstring") instead of flooding it with prose ("README.md documents
-    // v2"). A no-signal bullet WITHOUT a norm signal is confidently not a rule, so
-    // it stays SKIPPED alongside the index/description/section rejects. A folded
-    // candidate that NAMES/matches a real rule is still rescued to CONFIDENT.
-    const asCandidate = (s) => ({
-        text: s.text,
-        exactQuote: s.text,
-        file: s.file,
-        lineStart: s.lineStart,
-        lineEnd: s.lineEnd,
-        confidence: "medium",
-    });
-    // Real SEGMENTS route by the full confident check (incl. the medium opt-in).
-    // Gate-rejected `no-signal` bullets are folded back in as candidates, but they
-    // are promoted to confident ONLY by a real RESCUE — NEVER by the blanket medium
-    // opt-in, which must not resurrect bullets the gate explicitly rejected.
-    const noSignal = rawSkipped.filter((s) => s.reason === "no-signal");
-    const folds = noSignal.map(asCandidate);
-    const heuristicRules = [
-        ...segments.filter(isConfident),
-        ...folds.filter((s) => isRescued(s.text)),
-    ].map(toRouted);
-    // The non-confident leftovers split by the norm signal: a rule-ish bullet
-    // (carries a deontic modal) is a genuine recall-miss → POSSIBLE (review); the
-    // rest is prose → SKIPPED with a `no-signal` reason (visible, not dropped).
-    const leftover = [
-        ...segments.filter((s) => !isConfident(s)),
-        ...folds.filter((s) => !isRescued(s.text)),
+    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 possible = leftover
-        .filter((s) => NORM_SIGNAL.test(s.text))
-        .map(toRouted);
-    const skipped = [
-        ...rawSkipped.filter((s) => s.reason !== "no-signal"),
-        ...leftover
-            .filter((s) => !NORM_SIGNAL.test(s.text))
-            .map((s) => ({
-            text: s.text,
-            file: s.file,
-            lineStart: s.lineStart,
-            lineEnd: s.lineEnd,
-            reason: "no-signal",
-        })),
-    ];
-    // Marker rules first (definitive), then the heuristic residue.
-    const rules = [...marked.rules, ...heuristicRules];
     const counts = {
         reuse: 0,
         hook: 0,
@@ -512,7 +540,13 @@ function routeRules(instructionText, file, options = {}) {
     };
     for (const r of rules)
         counts[r.category]++;
-    return { segmented: rules.length, counts, rules, possible, skipped };
+    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

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

@@ -23,10 +23,18 @@ export interface SegmentedRule {
     confidence: "high" | "medium";
 }
 /** Why the segmenter decided a bullet is NOT a rule (the transparency signal —
- * see `research/rule-compiler-design.md` §3). `index`/`description`/`no-signal`
- * come from the gate; `section` means it sits under a non-rule heading
- * (Setup / Commands / Key Files / Architecture …). */
-export type RejectReason = "index" | "description" | "no-signal" | "section";
+ * 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
@@ -49,7 +57,10 @@ export interface SegmentResult {
  *
  * 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>): SegmentResult;
 //# sourceMappingURL=segment.d.ts.map