vigiles 14.0.0 → 14.1.0

package/dist/rule-routing.d.ts

@@ -1,3 +1,41 @@
+/**
+ * rule-routing.ts — the deterministic (no-model) State-B routing PREVIEW.
+ *
+ * `rule-inventory.ts` answers a narrow question ("which prose lines name an
+ * off-the-shelf lint rule, and is it enabled?"). This goes one honest step
+ * further: it SEGMENTS the whole instruction file into atomic rules
+ * ({@link segmentInstructions}) and routes each one into the class that a real
+ * enforcement path would take — WITHOUT running a model:
+ *
+ *   reuse    → the rule text names an off-the-shelf lint rule ({@link INTENT_MAP})
+ *              → mechanism: flip one config line. The "narrow list we compile
+ *              very well" — everything else is honestly labelled, not force-fit.
+ *   hook     → an ACTION rule a linter can't see (git push, rm -rf, "before you
+ *              commit") → mechanism: a pre-commit / PreToolUse hook.
+ *   meta     → an agent-instruction, not a code rule ("read X first", "tell the
+ *              user", "you are …") → mechanism: stays prose. Split out of
+ *              `unrouted` so it never reads as "compilable but hard" (it isn't).
+ *   semantic → a judgment call ("readable", "single responsibility") no checker
+ *              can honestly decide → mechanism: stays prose.
+ *   unrouted → looks like a code rule but matched no off-the-shelf rule: HARD to
+ *              codify → mechanism `synthesize`: the opt-in SYNTHESIS tier (a
+ *              skill on your subscription) MIGHT write a custom checker, gated —
+ *              but it is NOT guaranteed (the gate may abstain). This is the
+ *              bucket audit must present clearly as "hard", never as done.
+ *
+ * NB "compile" is NOT used here — `vigiles compile` is the unrelated spec→markdown
+ * verb. Synthesis is its own opt-in tier; the mechanism value is `synthesize`.
+ *
+ * HONESTY BY CONSTRUCTION: the deterministic tier NEVER claims a rule is
+ * "synthesizable" — deciding that a custom rule can be written (and gating it)
+ * is exactly the work the opt-in model tier does. `unrouted` means "hard — a
+ * synthesis skill may try", never a promise; `meta`/`semantic` mean "not an
+ * enforceable code rule at all" (a different, honest kind of no).
+ *
+ * Pure, deterministic, dependency-free. Reuses `rule-inventory`'s hardened
+ * whole-token matcher + `INTENT_MAP`, and `segment`'s Tier-A segmenter.
+ */
+import { type SkippedBullet } from "./segment.js";
 import { type LinterName } from "./rule-inventory.js";
 import type { RuleCatalog } from "./core/rule-catalog.js";
 /** How a routed rule would be enforced (a MECHANISM ladder, not a 1-10 score). */
@@ -29,10 +67,19 @@ export interface RoutedRule {
     readonly source?: "marker" | "heuristic";
 }
 export interface RuleRouting {
-    /** How many atomic rules were routed (after the confidence filter). */
+    /** How many CONFIDENT atomic rules were routed (high or rescued). */
     readonly segmented: number;
     readonly counts: Record<RuleCategory, number>;
+    /** The CONFIDENT tier — cleared the precision bar; these are the routed rules. */
     readonly rules: readonly RoutedRule[];
+    /** The POSSIBLE tier — rule-ish bullets (medium confidence) that did NOT clear
+     * the bar, still classified so a human can review + promote them. Detection is
+     * precision-first, so this is where a declarative rule ("Every X must Y") that
+     * the confident tier misses shows up. See `research/rule-compiler-design.md` §2. */
+    readonly possible: readonly RoutedRule[];
+    /** Bullets the segmenter decided were NOT rules, each with a reason — so the
+     * report is honest about what it set aside (§3). */
+    readonly skipped: readonly SkippedBullet[];
 }
 export interface RouteOptions {
     /**

package/dist/rule-routing.js

@@ -49,6 +49,14 @@ const MECHANISM = {
     semantic: "prose",
     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.
+ */
+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;
 /**
  * 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
@@ -221,27 +229,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 +301,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\``,
@@ -304,11 +343,13 @@ function extractMarkedRules(text, file, catalog) {
             if (em) {
                 if (!looksLikeRuleId(em[1]))
                     break; // a prose claim, not a rule id
-                const enabled = catalog?.get(em[1].trim());
+                const hit = catalog?.get(em[1].trim());
                 marked = {
                     category: "reuse",
                     rule: em[1].trim(),
-                    ...(enabled !== undefined ? { enabled } : {}),
+                    ...(hit !== undefined
+                        ? { enabled: hit.enabled, linter: hit.linter }
+                        : {}),
                 };
                 break;
             }
@@ -347,6 +388,7 @@ function extractMarkedRules(text, file, catalog) {
             mechanism: MECHANISM[marked.category],
             source: "marker",
             ...(marked.rule ? { rule: marked.rule } : {}),
+            ...(marked.linter ? { linter: marked.linter } : {}),
             ...(marked.enabled !== undefined ? { enabled: marked.enabled } : {}),
         });
     }
@@ -360,7 +402,7 @@ 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
@@ -381,15 +423,17 @@ function routeRules(instructionText, file, options = {}) {
     // 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) => {
+    // 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 {
             text: s.text,
@@ -405,7 +449,58 @@ function routeRules(instructionText, file, options = {}) {
             ...(c.linter ? { linter: c.linter } : {}),
             ...(c.enabled !== undefined ? { enabled: c.enabled } : {}),
         };
+    };
+    // 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, 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 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 = {
@@ -417,7 +512,7 @@ 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, skipped };
 }
 /**
  * Merge per-file routings into one. Each instruction source is routed SEPARATELY
@@ -434,13 +529,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/segment.d.ts

@@ -22,6 +22,28 @@ 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-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";
+/** 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.
  *
@@ -29,5 +51,5 @@ export interface SegmentedRule {
  * candidacy. Candidate units are (a) list items with attached continuation
  * lines and (b) sentences of paragraphs under a rule-ish heading.
  */
-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

package/dist/segment.js

@@ -310,8 +310,13 @@ function isLinkOnly(text) {
     const t = text.trim();
     return URL_ONLY.test(t) || LINK_ONLY.test(t);
 }
+/** The accept/reject view of a gate result, for sites that only need the split
+ * (atomize, the sub-span loop) and don't care about the reason. */
+function confidenceOf(g) {
+    return "confidence" in g ? g.confidence : null;
+}
 /**
- * Score the 3 cues. Returns confidence or null (reject).
+ * Score the 3 cues. Returns a confidence OR a reject reason.
  * - form: starts with an imperative/prohibitive head (or "No X").
  * - context: is a bullet OR sits under a rule-ish heading.
  * - shape: 15–300 chars, has a verb-ish token, not link-only, not a declaration.
@@ -322,18 +327,18 @@ function gate(text, isBullet, underRuleHeading) {
     // `a.ts → b.ts`, `dir/x — …`, `Label: path`) — the corpus's dominant false
     // positive. No cue count can rescue it.
     if (looksLikeIndexEntry(t))
-        return null;
+        return { reject: "index" };
     // Reject a DESCRIPTION-led sentence (`` `Foo` class in `x` executes … ``) — an
     // architecture/index sentence, not a rule (the dogfood's #1 false positive).
     if (looksLikeDescription(t))
-        return null;
+        return { reject: "description" };
     const context = isBullet || underRuleHeading;
     // RULE-NAME cue: a bullet/section line that NAMES an off-the-shelf rule is a
     // strong signal it's enforceable, even without an imperative verb — promote it
     // to high so the high-only default doesn't drop it (recovers rule-naming
     // bullets like "No floating promises (`@ts.../no-floating-promises`)").
     if (context && RULE_NAME_IN_CODE.test(t))
-        return "high";
+        return { confidence: "high" };
     // The form/declaration cues see the text with leading decoration stripped, so
     // `- **Never** …` reads as imperative and `**We** …` still reads declarative.
     const head = stripLeadDecoration(t);
@@ -345,10 +350,10 @@ function gate(text, isBullet, underRuleHeading) {
         !DECLARATION.test(head);
     const cues = (form ? 1 : 0) + (context ? 1 : 0) + (shape ? 1 : 0);
     if (cues >= 3)
-        return "high";
+        return { confidence: "high" };
     if (cues === 2)
-        return "medium";
-    return null;
+        return { confidence: "medium" };
+    return { reject: "no-signal" };
 }
 // --- Atomicity split -------------------------------------------------------
 /** Never split when an exception clause carries polarity/meaning. */
@@ -404,7 +409,7 @@ function atomize(src, contentSpan, isBullet, underRuleHeading) {
     // Both/all halves must independently pass the gate, else keep whole.
     for (const p of pieces) {
         const text = normalize(src.slice(p.start, p.end));
-        if (gate(text, isBullet, underRuleHeading) === null)
+        if (confidenceOf(gate(text, isBullet, underRuleHeading)) === null)
             return [whole];
     }
     return pieces.length > 1 ? pieces : [whole];
@@ -439,6 +444,7 @@ function segmentInstructions(markdown, file, skipLines) {
     const lines = markdown.split("\n");
     const lineOffsets = computeLineOffsets(lines);
     const out = [];
+    const skipped = [];
     let inFence = false;
     let currentHeadingIsRuleish = false;
     let currentHeadingIsAntiContext = false;
@@ -513,7 +519,8 @@ function segmentInstructions(markdown, file, skipLines) {
             const contentEnd = lineOffsets[endLine] + lines[endLine].length;
             const contentSpan = { start: contentStart, end: contentEnd };
             const wholeText = normalize(markdown.slice(contentStart, contentEnd));
-            const conf = gate(wholeText, true, currentHeadingIsRuleish);
+            const g = gate(wholeText, true, currentHeadingIsRuleish);
+            const conf = confidenceOf(g);
             // Reject bullets under an anti-context heading (Commands/Setup/Key Files/
             // Architecture/…) — the corpus's dominant false-positive locus.
             if (conf !== null && !currentHeadingIsAntiContext) {
@@ -528,12 +535,27 @@ function segmentInstructions(markdown, file, skipLines) {
                 else {
                     for (const s of spans) {
                         const text = normalize(markdown.slice(s.start, s.end));
-                        const c = gate(text, true, currentHeadingIsRuleish);
+                        const c = confidenceOf(gate(text, true, currentHeadingIsRuleish));
                         if (c !== null)
                             out.push(emitFromSpan(markdown, lineOffsets, file, s, c));
                     }
                 }
             }
+            else {
+                // This bullet was NOT treated as a rule — record it + why, so the audit
+                // report can be honest about what it set aside (transparency, §3). A
+                // rejection under an anti-context heading is a "section" skip; otherwise
+                // it's the gate's own reason.
+                skipped.push({
+                    text: wholeText,
+                    file,
+                    lineStart: offsetToLine(lineOffsets, contentStart),
+                    lineEnd: offsetToLine(lineOffsets, contentEnd - 1),
+                    reason: currentHeadingIsAntiContext || "confidence" in g
+                        ? "section"
+                        : g.reject,
+                });
+            }
             i = endLine + 1;
             continue;
         }
@@ -573,7 +595,7 @@ function segmentInstructions(markdown, file, skipLines) {
                     if (s.start >= s.end)
                         continue;
                     const text = normalize(markdown.slice(s.start, s.end));
-                    const c = gate(text, false, true);
+                    const c = confidenceOf(gate(text, false, true));
                     if (c !== null)
                         out.push(emitFromSpan(markdown, lineOffsets, file, s, c));
                 }
@@ -583,6 +605,6 @@ function segmentInstructions(markdown, file, skipLines) {
         }
         i++;
     }
-    return out;
+    return { segments: out, skipped };
 }
 //# sourceMappingURL=segment.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "14.0.0",
+  "version": "14.1.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",