vigiles 13.0.0 → 14.1.0

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): SegmentedRule[];
+export declare function segmentInstructions(markdown: string, file?: string, skipLines?: ReadonlySet<number>): SegmentResult;
 //# sourceMappingURL=segment.d.ts.map

package/dist/segment.js

@@ -11,10 +11,108 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.segmentInstructions = segmentInstructions;
 // --- Heuristic vocabulary --------------------------------------------------
-/** Imperative/prohibitive head the candidate must START with (form cue). */
-const FORM_HEAD = /^(?:use|avoid|prefer|never|always|don'?t|do not|no\s+\S|must|should|keep|run|write|add|remove|only)\b/i;
-/** Rule-ish heading gate for prose-under-heading candidacy. */
-const RULE_HEADING = /rules?|conventions?|style|guidelines?|standards?|do(?:n'?ts?)?s?|never|always|must|require/i;
+/** Imperative/prohibitive head the candidate must START with (form cue). The
+ * deontic verbs (require/disallow/forbid/ban/enforce) are common rule leads —
+ * "Require `curly` braces", "Disallow `var`" — so they belong here. NB "no" is
+ * `no\s` (the prohibition word + whitespace) NOT the old `no\s+\S`, which — via
+ * the shared trailing `\b` — only matched when the word after "No " began at a
+ * boundary, so "No bare except" / "No default exports" silently failed the form
+ * cue. Bare `no` + the shared `\b` (checked right after "no", a boundary before
+ * a space OR a backtick) matches "No bare" AND "No `any`", while "Note"/"Nowhere"
+ * (no boundary after "no") are still rejected. */
+const 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;
+/**
+ * Rule-ish heading gate for prose-under-heading candidacy. Word-bounded so the
+ * `do` alternate can't match inside `Documentation`/`Adoption`/`Download` (the
+ * measured bug). Accept-heading vocabulary grounded in the OSS-corpus survey
+ * (`## Coding Standards`/`## Code Style`/`## Naming`/`## Good practices`/
+ * `## Error Handling` are the real code-norm sections).
+ */
+const RULE_HEADING = /\b(?:rules?|conventions?|code[ -]?style|style|guidelines?|standards?|naming|good practices?|error handling|do'?s?\s*(?:and|&|\/)\s*don'?ts?|don'?ts?|never|always|must|require)\b/i;
+/**
+ * Anti-context heading: a section whose content is overwhelmingly index /
+ * command / setup / narrative, not enforceable norms (the corpus's #1
+ * false-positive source). Content under one of these is rejected outright —
+ * UNLESS the heading is also rule-ish (`## Testing conventions` keeps its
+ * bullets), so the accept signal wins a tie.
+ */
+const ANTI_HEADING = /\b(?:commands?|setup|install(?:ation)?|usage|getting started|quick ?start|examples?|key files|(?:code)?base structure|project structure|repository structure|architecture|overview|directory|layout|environment|commits?|pull requests?|testing|scripts?|dependencies|roadmap|changelog|table of contents|where to look)\b/i;
+/**
+ * INDEX-SMELL veto: a bullet whose content is a code span followed by a
+ * separator + description (`` `src/x.ts` — Type system ``, `` `npm test` — run ``)
+ * is a keyFiles/command INDEX entry, never a rule. The single highest-value
+ * rejection signal (the corpus's dominant false positive).
+ */
+const INDEX_SMELL = /^`[^`]+`\s*[:—–-]\s/;
+/**
+ * Broader index/reference-entry shapes the backtick INDEX_SMELL misses — from
+ * real-corpus leakage: a path MAPPING (`next-dev.ts → next-dev-server.ts`), a
+ * bullet LED by a file path + em-dash (`packages/x/ — Session replay`), or a
+ * `Label: <path>` pointer (`Skill file: .agents/skills/…`). Paths in these are
+ * backtick-wrapped, so we test a backtick-stripped shadow. The path DISCRIMINATOR
+ * — a file extension (`.ts`) or a trailing slash — is what keeps a rule id
+ * (`@scope/no-explicit-any`, no extension) from being mistaken for a path, so a
+ * rule-naming bullet is never rejected as an index entry.
+ */
+const INDEX_ARROW = /[\w./@-]*\.[a-z]{1,6}\b\s*(?:→|->|=>)/;
+// A multi-segment slash PATH before an arrow is a path-mapping/index row
+// (`node_modules/@astrojs/react/… → packages/…`) — ≥2 slashes keeps it path-
+// specific so a prose "A → B" isn't caught.
+const INDEX_ARROW_PATH = /[\w@.-]+(?:\/[\w@.*-]+){2,}\s*(?:→|->|=>)/;
+const INDEX_LABEL_PATH = /^[A-Za-z][\w ]{0,24}:\s+\.?[\w@-]*\/[\w@./-]*(?:\.[a-z0-9]{1,6}\b|\/)/;
+const INDEX_PATH_LED = /^[\w@.-]+\/[\w@./-]*(?:\.[a-z0-9]{1,6}\b|\/)/;
+function looksLikeIndexEntry(t) {
+    if (INDEX_SMELL.test(t))
+        return true;
+    const bare = t.replace(/`/g, " ").trim();
+    if (INDEX_ARROW.test(bare) || INDEX_ARROW_PATH.test(bare))
+        return true;
+    if (INDEX_LABEL_PATH.test(bare))
+        return true;
+    return INDEX_PATH_LED.test(bare) && /\s[—–]\s/.test(bare);
+}
+/**
+ * DESCRIPTION-LED reject: a segment that DESCRIBES a code entity rather than
+ * instructing about it. It leads with a backticked identifier/path, then a
+ * copula / code-KIND noun / descriptive verb ("`Foo` class in `x` executes …",
+ * "`bar` is the loader", "`apps/x` handles …"). A real rule leads with a VERB
+ * ("Use `Foo`", "Never `bar`") — never the code span itself — so a code-span
+ * lead-in followed by a descriptive word is an architecture/index sentence, the
+ * dogfood's #1 segmenter false positive (39% of the "hard" bucket was this
+ * kind of noise). High-precision: only when the descriptive word IMMEDIATELY
+ * follows the leading code span.
+ */
+const DESCRIPTION_LED = /^`[^`]+`\s+(?:is|are|was|were|lives?|live|contains?|holds?|handles?|executes?|provides?|represents?|maps?|points?|implements?|exports?|defines?|wraps?|stores?|returns?|the|a|an|class|function|module|component|file|package|hook|utility|helper|type|interface|enum|constant|method|directory|folder|dir)\b/i;
+// A deontic predicate makes a code-span-led sentence a RULE, not a description
+// ("`const` is preferred over `let`", "`AbstractBase` class must be extended") —
+// so the description reject must NOT fire. Guards the copula/kind-noun ambiguity.
+const 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;
+function looksLikeDescription(t) {
+    const s = t.trim();
+    return DESCRIPTION_LED.test(s) && !RULE_PREDICATE.test(s);
+}
+/**
+ * RULE-NAME cue: a backticked token that is SHAPED like an off-the-shelf lint
+ * rule — a scoped/plugin rule (`@typescript-eslint/consistent-type-imports`,
+ * `import/no-cycle`) or a ≥3-segment kebab id (`no-floating-promises`). Requiring
+ * the backticks kills prose false positives (`up-to-date`, `state-of-the-art`,
+ * a file path). Naming a rule is a STRONG signal a bullet is an enforceable rule
+ * even when it has no imperative verb — the corpus's rule-naming bullets
+ * ("No floating promises (`@ts.../no-floating-promises`)") otherwise score
+ * "medium" and get dropped by the high-only default.
+ */
+const RULE_NAME_IN_CODE = /`[^`]*(?:@[a-z][\w-]*\/[a-z][\w-]*|[a-z][\w-]*\/[a-z][\w-]*-[\w-]+|(?:no|prefer|require|consistent|max|min|func|id|sort|valid|padding|dot|array|object)-[a-z][a-z0-9-]+)[^`]*`/i;
+/**
+ * Leading markdown decoration a rule may be wrapped in — emphasis (`**bold**`),
+ * blockquote, checkbox, or a status emoji. Stripped on a SHADOW string before
+ * the imperative-head test so `- **Never** …` / `✅ Use const` still read as
+ * imperative. Provenance (exactQuote/offsets) is unaffected — only the form cue
+ * sees the stripped text.
+ */
+const LEAD_DECORATION = /^(?:\s+|>+|\*+|_+|~+|\[[ xX]\]\s*|[✅❌☑✔✖✗⚠ℹ])+/u;
+function stripLeadDecoration(s) {
+    return s.replace(LEAD_DECORATION, "").trimStart();
+}
 /** Declarative subjects — these signal a statement, not an instruction. */
 const DECLARATION = /^(?:this|these|those|it|we|our|there)\b/i;
 /** Line consisting only of a bare URL. */
@@ -101,14 +199,9 @@ const VERBS = new Set([
     "filters",
     "merge",
     "merges",
-    "be",
-    "is",
-    "are",
-    "have",
-    "has",
-    "may",
-    "should",
-    "must",
+    // Copulas/modals (be/is/are/have/has/may/should/must) are deliberately NOT
+    // here: as "shape" verbs they made the cue near-vacuous (almost any English
+    // sentence passed). Deontic modals still live in FORM_HEAD (the form cue).
     "pin",
     "pins",
     "lint",
@@ -157,6 +250,13 @@ const VERBS = new Set([
     "squash",
     "enforce",
     "enforces",
+    "regenerate",
+    "regenerates",
+    "regen",
+    "rebuild",
+    "rebuilds",
+    "generate",
+    "generates",
     "define",
     "defines",
     "declare",
@@ -210,27 +310,50 @@ 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.
  */
 function gate(text, isBullet, underRuleHeading) {
     const t = text.trim();
-    const form = FORM_HEAD.test(t);
+    // Reject an index/command/reference entry outright (`` `path` — description ``,
+    // `a.ts → b.ts`, `dir/x — …`, `Label: path`) — the corpus's dominant false
+    // positive. No cue count can rescue it.
+    if (looksLikeIndexEntry(t))
+        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 { 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 { 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);
+    const form = FORM_HEAD.test(head);
     const shape = t.length >= 15 &&
         t.length <= 300 &&
         hasVerbish(t) &&
         !isLinkOnly(t) &&
-        !DECLARATION.test(t);
+        !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. */
@@ -286,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];
@@ -304,7 +427,9 @@ function emitFromSpan(src, lineOffsets, file, span, confidence) {
     };
 }
 // --- Scanner ---------------------------------------------------------------
-const LIST_ITEM = /^(\s*)([-*+])(\s+)(.*)$/;
+// Ordered (`1.`/`1)`) and emoji (`✅`/`❌`) bullets count as list items too —
+// the native `-*+` class missed them, so shouted/numbered rules were invisible.
+const LIST_ITEM = /^(\s*)([-*+]|\d+[.)]|[✅❌☑✔✖✗])(\s+)(.*)$/u;
 const HEADING = /^(#{1,6})\s+(.*)$/;
 const FENCE = /^\s*(```|~~~)/;
 const TABLE_LINE = /^\s*\|/;
@@ -315,12 +440,14 @@ const TABLE_LINE = /^\s*\|/;
  * candidacy. Candidate units are (a) list items with attached continuation
  * lines and (b) sentences of paragraphs under a rule-ish heading.
  */
-function segmentInstructions(markdown, file) {
+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;
     let i = 0;
     const lineSpan = (a, b) => ({
         start: lineOffsets[a],
@@ -342,6 +469,10 @@ function segmentInstructions(markdown, file) {
         const h = HEADING.exec(line);
         if (h) {
             currentHeadingIsRuleish = RULE_HEADING.test(h[2]);
+            // Anti-context only when it is NOT also rule-ish, so an accept word wins a
+            // tie (`## Testing conventions` keeps its bullets; `## Testing` drops them).
+            currentHeadingIsAntiContext =
+                ANTI_HEADING.test(h[2]) && !currentHeadingIsRuleish;
             i++;
             continue;
         }
@@ -350,6 +481,13 @@ function segmentInstructions(markdown, file) {
             i++;
             continue;
         }
+        // A line already CONSUMED by the structured-marker pre-pass (a marked
+        // section's body) is not re-segmented — this is the span-consumption that
+        // stops a marked rule being double-counted by the heuristic. (1-based.)
+        if (skipLines?.has(i + 1)) {
+            i++;
+            continue;
+        }
         // List items (with attached continuation lines).
         const li = LIST_ITEM.exec(line);
         if (li) {
@@ -381,8 +519,11 @@ function segmentInstructions(markdown, file) {
             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);
-            if (conf !== null) {
+            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) {
                 // Only attempt splitting for single-line items (keeps offsets exact).
                 const spans = multiLine
                     ? [trimSpan(markdown, contentSpan)]
@@ -394,12 +535,27 @@ function segmentInstructions(markdown, file) {
                 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;
         }
@@ -439,7 +595,7 @@ function segmentInstructions(markdown, file) {
                     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));
                 }
@@ -449,6 +605,6 @@ function segmentInstructions(markdown, file) {
         }
         i++;
     }
-    return out;
+    return { segments: out, skipped };
 }
 //# sourceMappingURL=segment.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "13.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",
@@ -90,6 +90,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@jackchuka/mdschema": "^0.12.8",
     "@microsoft/api-extractor": "^7.58.9",
     "@types/js-yaml": "^4.0.9",
     "@types/minimatch": "^5.1.2",
@@ -127,7 +128,6 @@
     "@ast-grep/lang-rust": "^0.0.7",
     "@ast-grep/napi": "^0.43.0",
     "@iarna/toml": "^2.2.5",
-    "@jackchuka/mdschema": "^0.12.8",
     "ci-info": "^4.4.0",
     "cosmiconfig": "^9.0.1",
     "glob": "^13.0.6",

package/skills/linter-docs/clippy.md

@@ -1,6 +1,6 @@
 # Clippy — Reference
 
-Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom lints).
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and the planned rule-synthesis skill (write custom lints, not yet shipped).
 
 ## Check Existing Lints First
 

package/skills/linter-docs/eslint.md

@@ -1,6 +1,6 @@
 # ESLint — Reference
 
-Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom rules).
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and the planned rule-synthesis skill (write custom rules, not yet shipped).
 
 ## Check Existing Plugins First
 

package/skills/linter-docs/pylint.md

@@ -1,6 +1,6 @@
 # Pylint — Reference
 
-Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom checkers).
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and the planned rule-synthesis skill (write custom checkers, not yet shipped).
 
 ## Check Existing Plugins First
 

package/skills/linter-docs/rubocop.md

@@ -1,6 +1,6 @@
 # RuboCop — Reference
 
-Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom cops).
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and the planned rule-synthesis skill (write custom cops, not yet shipped).
 
 ## Check Existing Gems First
 

package/skills/linter-docs/ruff.md

@@ -1,6 +1,6 @@
 # Ruff — Reference
 
-Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom rules).
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and the planned rule-synthesis skill (write custom rules, not yet shipped).
 
 ## Check Existing Rules First
 

package/skills/linter-docs/stylelint.md

@@ -1,6 +1,6 @@
 # Stylelint — Reference
 
-Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and `pr-to-lint-rule` (write custom rules).
+Shared linter reference for vigiles skills. Used by `strengthen` (find existing rules) and the planned rule-synthesis skill (write custom rules, not yet shipped).
 
 ## Check Existing Plugins First
 

package/skills/strengthen/SKILL.md

@@ -142,12 +142,12 @@ Group the output into tiers:
 → enforce("eslint/sonarjs/cognitive-complexity", "Keep functions simple")
 ```
 
-**Tier 4: No match** (stays as guidance, or candidate for `/pr-to-lint-rule`)
+**Tier 4: No match** (stays as guidance — candidate for a future rule-synthesis skill)
 
 ```
 "research-first": guidance("Google unfamiliar APIs first.")
-→ No linter rule can enforce this. Stays as guidance.
-→ Want me to run /pr-to-lint-rule to create a custom rule?
+→ No linter rule can enforce this. Stays as guidance for now.
+→ (Custom-rule synthesis is planned but not yet shipped.)
 ```
 
 ### Step 6: Apply Changes
@@ -168,4 +168,4 @@ Group the output into tiers:
 4. Run `npm run build && npx vigiles compile` to verify
 5. If compilation fails, report the error and revert
 
-**For Tier 4 (no match):** Ask the user if they want to run `/pr-to-lint-rule` for any of the unmatched rules to create custom rules.
+**For Tier 4 (no match):** Tell the user these rules stay as guidance — custom-rule synthesis is a planned skill, not yet available.