vigiles 12.7.0 → 12.8.0

package/dist/rule-inventory.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Rule-inventory — the deterministic, foreign-safe teaser surface of the
+ * `audit` rule-compile tier (design: `research/audit-rule-compile-tier.md`).
+ *
+ * Finds prose rules in a `CLAUDE.md` / `AGENTS.md` that map to an off-the-shelf
+ * lint rule, and whether that rule already appears in the repo's lint config.
+ * The remedy for a documented-but-unconfigured intent is a one-line config
+ * change, not synthesis — so this is a cheap, high-value nudge.
+ *
+ * NO model. NO config execution (textual grep only — never resolves/executes
+ * `eslint.config.js`, which would be the RCE path). HIGH PRECISION by
+ * construction: only rule-name / code-token-shaped keywords are matched, and
+ * only as whole tokens. Bare prose words are excluded on purpose — a raw
+ * keyword match (`token`, `!`, `await`, `secret`, `silently`, …) sprays false
+ * positives on real instruction files (measured: 107 raw hits over 4 real
+ * CLAUDE.md files, ~all garbage). The model-driven analysis (extract → classify
+ * → compile → gate → run) lives in the OPT-IN tier, not here.
+ *
+ * MULTI-LINTER by shape, ESLint-first by data. The matcher is linter-agnostic;
+ * each mapping is keyed by linter, so adding Ruff / Clippy / Pylint / RuboCop /
+ * Stylelint is additive DATA (a curation task), not a refactor. The OPT-IN tier
+ * should resolve "is this rule enabled" via vigiles's existing multi-linter
+ * `checkLinterRule` engine (which execs the config) — kept out of this
+ * exec-free, foreign-safe surface on purpose.
+ */
+/** Linters vigiles's cross-reference engine already understands. */
+export type LinterName = "eslint" | "ruff" | "clippy" | "pylint" | "rubocop" | "stylelint";
+/** One prose→rule mapping for a single linter. `keywords` are rule-name/token-shaped. */
+export interface IntentMapping {
+    readonly intent: string;
+    readonly linter: LinterName;
+    /** Whole-token, code-shaped triggers only (no bare English words). */
+    readonly keywords: readonly string[];
+    /** The off-the-shelf rule that enforces this intent. */
+    readonly rule: string;
+    /** The one-line config change that turns it on. */
+    readonly configFix: string;
+    /** True if a `recommended` preset typically enables this rule (so a bare
+     * recommended-extends is evidence it may already be on). */
+    readonly inRecommended?: boolean;
+}
+/**
+ * Curated from agent-rules-compiler's `rule-map.json`, keeping ONLY the
+ * specific (rule-name / code-token) keywords and dropping every bare-word
+ * trigger the FP measurement flagged (`token`, `secret`, `password`, `await`,
+ * `!`, `aria`, `silently`, `prefix`, `complexity`, `barrel`, `cycle`, …).
+ *
+ * ESLint-only today — Ruff/Clippy/Pylint/RuboCop/Stylelint entries append here
+ * with their own `linter` + rule-name keywords, no code change.
+ */
+export declare const INTENT_MAP: readonly IntentMapping[];
+/**
+ * Whether the mapped rule is visible in the lint config text (textual grep —
+ * imperfect, labelled). `contradiction` is the sharpest state: the harness
+ * documents the rule as a norm, yet the config EXPLICITLY sets it to off/0 —
+ * the docs and the config disagree.
+ */
+export type ConfigState = "in-config" | "not-in-config" | "preset-maybe" | "contradiction";
+/** One documented-intent → off-the-shelf-rule finding. */
+export interface RuleInventoryItem {
+    readonly intent: string;
+    readonly linter: LinterName;
+    /** The rule-name/token that matched in the instruction file. */
+    readonly matched: string;
+    /** The off-the-shelf rule that enforces it. */
+    readonly rule: string;
+    /** Whether `rule` appears anywhere in the provided config text. */
+    readonly configState: ConfigState;
+    /** The one-line config change to enforce it (shown when not in config). */
+    readonly configFix: string;
+}
+/** Options for {@link buildRuleInventory}. */
+export interface RuleInventoryOptions {
+    /**
+     * Restrict to the repo's detected linter(s). When omitted, all linters are
+     * considered — safe because the keywords are rule-name-specific, but a caller
+     * that knows the repo is Python-only can pass `["ruff"]` to avoid a stray
+     * cross-language rule-name collision.
+     */
+    readonly linters?: readonly LinterName[];
+}
+/**
+ * A keyword matches only as a WHOLE token: bounded by start/end or a
+ * non-`[\w/@.-]` character on each side (so `no-console` matches in
+ * `` `no-console` `` and `enforce no-console;` but `no-console-x` does not,
+ * and prose containing the substring elsewhere never trips it).
+ */
+export declare function matchesWholeToken(text: string, keyword: string): boolean;
+export declare function buildRuleInventory(instructionText: string, configText: string, options?: RuleInventoryOptions): RuleInventoryItem[];
+//# sourceMappingURL=rule-inventory.d.ts.map

package/dist/rule-inventory.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * Rule-inventory — the deterministic, foreign-safe teaser surface of the
+ * `audit` rule-compile tier (design: `research/audit-rule-compile-tier.md`).
+ *
+ * Finds prose rules in a `CLAUDE.md` / `AGENTS.md` that map to an off-the-shelf
+ * lint rule, and whether that rule already appears in the repo's lint config.
+ * The remedy for a documented-but-unconfigured intent is a one-line config
+ * change, not synthesis — so this is a cheap, high-value nudge.
+ *
+ * NO model. NO config execution (textual grep only — never resolves/executes
+ * `eslint.config.js`, which would be the RCE path). HIGH PRECISION by
+ * construction: only rule-name / code-token-shaped keywords are matched, and
+ * only as whole tokens. Bare prose words are excluded on purpose — a raw
+ * keyword match (`token`, `!`, `await`, `secret`, `silently`, …) sprays false
+ * positives on real instruction files (measured: 107 raw hits over 4 real
+ * CLAUDE.md files, ~all garbage). The model-driven analysis (extract → classify
+ * → compile → gate → run) lives in the OPT-IN tier, not here.
+ *
+ * MULTI-LINTER by shape, ESLint-first by data. The matcher is linter-agnostic;
+ * each mapping is keyed by linter, so adding Ruff / Clippy / Pylint / RuboCop /
+ * Stylelint is additive DATA (a curation task), not a refactor. The OPT-IN tier
+ * should resolve "is this rule enabled" via vigiles's existing multi-linter
+ * `checkLinterRule` engine (which execs the config) — kept out of this
+ * exec-free, foreign-safe surface on purpose.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INTENT_MAP = void 0;
+exports.matchesWholeToken = matchesWholeToken;
+exports.buildRuleInventory = buildRuleInventory;
+/**
+ * Curated from agent-rules-compiler's `rule-map.json`, keeping ONLY the
+ * specific (rule-name / code-token) keywords and dropping every bare-word
+ * trigger the FP measurement flagged (`token`, `secret`, `password`, `await`,
+ * `!`, `aria`, `silently`, `prefix`, `complexity`, `barrel`, `cycle`, …).
+ *
+ * ESLint-only today — Ruff/Clippy/Pylint/RuboCop/Stylelint entries append here
+ * with their own `linter` + rule-name keywords, no code change.
+ */
+exports.INTENT_MAP = [
+    {
+        intent: "no console.log / use the logger",
+        linter: "eslint",
+        keywords: ["console.log", "no-console"],
+        rule: "no-console",
+        configFix: '"no-console": "error"',
+    },
+    {
+        intent: "no `any` type",
+        linter: "eslint",
+        keywords: ["no-explicit-any", "@typescript-eslint/no-explicit-any"],
+        rule: "@typescript-eslint/no-explicit-any",
+        inRecommended: true,
+        configFix: '"@typescript-eslint/no-explicit-any": "error"',
+    },
+    {
+        intent: "no eslint-disable / no linter suppressors",
+        linter: "eslint",
+        keywords: ["eslint-disable", "eslint-comments/no-use"],
+        rule: "eslint-comments/no-use",
+        configFix: "enable eslint-comments/no-use OR linterOptions.noInlineConfig: true",
+    },
+    {
+        intent: "no @ts-ignore / @ts-expect-error abuse",
+        linter: "eslint",
+        keywords: [
+            "@ts-ignore",
+            "ts-expect-error",
+            "ban-ts-comment",
+            "@typescript-eslint/ban-ts-comment",
+        ],
+        rule: "@typescript-eslint/ban-ts-comment",
+        inRecommended: true,
+        configFix: '"@typescript-eslint/ban-ts-comment": "error"',
+    },
+    {
+        intent: "no hardcoded secrets",
+        linter: "eslint",
+        keywords: ["no-secrets"],
+        rule: "no-secrets/no-secrets",
+        configFix: "add eslint-plugin-no-secrets rule no-secrets/no-secrets",
+    },
+    {
+        intent: "no empty catch / no swallowed errors",
+        linter: "eslint",
+        keywords: ["no-empty"],
+        rule: "no-empty",
+        inRecommended: true,
+        configFix: '"no-empty": ["error", {"allowEmptyCatch": false}]',
+    },
+    {
+        intent: "no var / prefer const-let",
+        linter: "eslint",
+        keywords: ["no-var", "prefer-const"],
+        rule: "no-var",
+        configFix: '"no-var": "error"',
+    },
+    {
+        intent: "strict equality ===",
+        linter: "eslint",
+        keywords: ["eqeqeq"],
+        rule: "eqeqeq",
+        configFix: '"eqeqeq": "error"',
+    },
+    {
+        intent: "template literals over concatenation",
+        linter: "eslint",
+        keywords: ["prefer-template"],
+        rule: "prefer-template",
+        configFix: '"prefer-template": "error"',
+    },
+    {
+        intent: "no debugger",
+        linter: "eslint",
+        keywords: ["no-debugger"],
+        rule: "no-debugger",
+        inRecommended: true,
+        configFix: '"no-debugger": "error"',
+    },
+    {
+        intent: "restricted / deprecated imports",
+        linter: "eslint",
+        keywords: ["no-restricted-imports", "import/no-restricted-paths"],
+        rule: "no-restricted-imports",
+        configFix: '"no-restricted-imports": ["error", {…}]',
+    },
+    {
+        intent: "no circular deps",
+        linter: "eslint",
+        keywords: ["import/no-cycle", "no-cycle"],
+        rule: "import/no-cycle",
+        configFix: '"import/no-cycle": "error"',
+    },
+    {
+        intent: "function length / complexity caps",
+        linter: "eslint",
+        keywords: [
+            "max-lines-per-function",
+            "max-depth",
+            "max-params",
+            "max-statements",
+        ],
+        rule: "max-lines-per-function",
+        configFix: '"max-lines-per-function": ["error", 40]',
+    },
+    {
+        intent: "no unused vars",
+        linter: "eslint",
+        keywords: ["no-unused-vars", "@typescript-eslint/no-unused-vars"],
+        rule: "@typescript-eslint/no-unused-vars",
+        inRecommended: true,
+        configFix: '"@typescript-eslint/no-unused-vars": "error"',
+    },
+    {
+        intent: "no non-null assertion",
+        linter: "eslint",
+        keywords: [
+            "no-non-null-assertion",
+            "@typescript-eslint/no-non-null-assertion",
+        ],
+        rule: "@typescript-eslint/no-non-null-assertion",
+        inRecommended: true,
+        configFix: '"@typescript-eslint/no-non-null-assertion": "error"',
+    },
+    {
+        intent: "no floating promises",
+        linter: "eslint",
+        keywords: [
+            "no-floating-promises",
+            "@typescript-eslint/no-floating-promises",
+        ],
+        rule: "@typescript-eslint/no-floating-promises",
+        inRecommended: true,
+        configFix: '"@typescript-eslint/no-floating-promises": "error"',
+    },
+    {
+        intent: "react hooks deps",
+        linter: "eslint",
+        keywords: ["react-hooks/exhaustive-deps", "exhaustive-deps"],
+        rule: "react-hooks/exhaustive-deps",
+        configFix: '"react-hooks/exhaustive-deps": "error"',
+    },
+    // Added from the hand-verified rule-adherence corpus (real repos: motion,
+    // mapbox) — both are documented in the wild and have an off-the-shelf rule.
+    {
+        intent: "no default exports",
+        linter: "eslint",
+        keywords: ["import/no-default-export", "no-default-export"],
+        rule: "import/no-default-export",
+        configFix: '"import/no-default-export": "error"',
+    },
+    {
+        intent: "no TODO / FIXME comments",
+        linter: "eslint",
+        keywords: ["no-warning-comments"],
+        rule: "no-warning-comments",
+        configFix: '"no-warning-comments": ["error", {"terms": ["todo", "fixme"], "location": "anywhere"}]',
+    },
+];
+/** Escape a keyword for use inside a RegExp. */
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * A keyword matches only as a WHOLE token: bounded by start/end or a
+ * non-`[\w/@.-]` character on each side (so `no-console` matches in
+ * `` `no-console` `` and `enforce no-console;` but `no-console-x` does not,
+ * and prose containing the substring elsewhere never trips it).
+ */
+function matchesWholeToken(text, keyword) {
+    const re = new RegExp(`(^|[^\\w/@.-])${escapeRe(keyword)}([^\\w/@.-]|$)`, "i");
+    return re.test(text);
+}
+/**
+ * Build the deterministic rule inventory. Pure: caller passes the instruction
+ * file text (concatenated CLAUDE.md/AGENTS.md) and the lint config text (any
+ * `eslint.config.*` / `.eslintrc*` / `ruff.toml` / … contents concatenated, or
+ * "" if none). Returns one item per documented intent whose keyword resolves.
+ * `not-in-config` items are the actionable nudges.
+ */
+/** ESLint re-exports some core rules under `@typescript-eslint/`; treat the base
+ * and scoped names as the same rule when checking the config text (so a repo that
+ * has base `no-unused-vars` satisfies the `@typescript-eslint/no-unused-vars`
+ * intent, and vice-versa). oxlint/biome use the SAME rule names, so once their
+ * config files are in the read set this handles them for free. */
+function variantsOf(rule) {
+    const TS = "@typescript-eslint/";
+    if (rule.startsWith(TS))
+        return [rule, rule.slice(TS.length)];
+    if (!rule.includes("/"))
+        return [rule, TS + rule];
+    return [rule];
+}
+/** True if the rule (or a base/scoped variant) appears in the config text. */
+function ruleInConfig(configText, rule) {
+    return variantsOf(rule).some((v) => matchesWholeToken(configText, v));
+}
+/**
+ * Whether the rule (or a variant) is EXPLICITLY disabled in the config text —
+ * `"no-console": "off"`, `no-console: 0`, `"no-console": ["off", …]`. Distinct
+ * from mere presence ({@link ruleInConfig}): a documented rule that the config
+ * turns OFF is a contradiction (docs say enforce, config disables), not an
+ * enforcement. Textual only — never resolves/executes the config (the RCE path).
+ * Conservative: matches only a literal off/0 severity right after the rule key,
+ * so a real `"error"`/`"warn"`/`1`/`2` never trips it.
+ */
+function ruleSetOff(configText, rule) {
+    return variantsOf(rule).some((v) => {
+        const re = new RegExp(`["']?${escapeRe(v)}["']?\\s*:\\s*(?:\\[\\s*)?["']?(?:off|0)\\b`, "i");
+        return re.test(configText);
+    });
+}
+/** Index of the first WHOLE-token occurrence of `keyword` in `text` (the keyword
+ * itself, not the boundary char), or -1. */
+function firstTokenIndex(text, keyword) {
+    const re = new RegExp(`(^|[^\\w/@.-])(${escapeRe(keyword)})([^\\w/@.-]|$)`, "i");
+    const m = re.exec(text);
+    return m ? m.index + m[1].length : -1;
+}
+/**
+ * Whether the matched mention is a documented opt-OUT ("`no-explicit-any` is off
+ * intentionally", "we disable X") rather than a norm to enforce. When the author
+ * deliberately turns a rule off, a not-in-config state is CONSISTENT, not a gap —
+ * nudging them to enable it is actively wrong advice (found dogfooding
+ * pmndrs/react-spring). Deterministic negation window around the matched token;
+ * conservative on purpose — only strong off/disable cues, so it never suppresses
+ * a genuine "enforce this" nudge. */
+function isDocumentedOptOut(text, keyword) {
+    const idx = firstTokenIndex(text, keyword);
+    if (idx < 0)
+        return false;
+    // Test the context on EITHER SIDE of the token, never the token itself — else
+    // the cue `disable` would match inside the rule name `eslint-disable` and
+    // self-suppress every mention of it. Left/right windows are separate strings.
+    // NB: `disabled` (full word) not `disable` — `disable` would match inside the
+    // rule name `eslint-disable`, which can appear in a NEIGHBOURING token's window.
+    const CUE = /\b(?:off|disabled|not enforced|not enabled|turned off)\b/i;
+    const left = text.slice(Math.max(0, idx - 48), idx);
+    const right = text.slice(idx + keyword.length, idx + keyword.length + 48);
+    return CUE.test(left) || CUE.test(right);
+}
+/** A `recommended`-style preset extend anywhere in the config text — evidence
+ * that preset-enabled rules may already be on even when not named literally.
+ * Coarse on purpose: presence of a preset downgrades a not-named preset rule to
+ * `preset-maybe` (no false "unenforced" alarm) rather than claiming it's off. */
+function extendsRecommended(configText) {
+    return /recommended/i.test(configText);
+}
+function buildRuleInventory(instructionText, configText, options = {}) {
+    const linters = options.linters;
+    const items = [];
+    for (const m of exports.INTENT_MAP) {
+        if (linters && !linters.includes(m.linter))
+            continue;
+        const matched = m.keywords.find((kw) => matchesWholeToken(instructionText, kw));
+        if (!matched)
+            continue;
+        const off = ruleSetOff(configText, m.rule);
+        const inConfig = ruleInConfig(configText, m.rule);
+        // A rule the author documents as deliberately OFF, and whose config agrees
+        // (absent, or literally set to off), is consistent — not a gap. Skip it so we
+        // never nudge "enable X" against an intentional opt-out, and never flag a
+        // documented opt-out as a contradiction.
+        if (isDocumentedOptOut(instructionText, matched) && (off || !inConfig)) {
+            continue;
+        }
+        // Precedence: an explicit off/0 is a contradiction even though the rule name
+        // is technically "in config" — so it must be checked before `in-config`.
+        const configState = off
+            ? "contradiction"
+            : inConfig
+                ? "in-config"
+                : m.inRecommended && extendsRecommended(configText)
+                    ? "preset-maybe"
+                    : "not-in-config";
+        items.push({
+            intent: m.intent,
+            linter: m.linter,
+            matched,
+            rule: m.rule,
+            configState,
+            configFix: m.configFix,
+        });
+    }
+    return items;
+}
+//# sourceMappingURL=rule-inventory.js.map

package/dist/rule-routing.d.ts

@@ -0,0 +1,46 @@
+import { type LinterName } from "./rule-inventory.js";
+/** How a routed rule would be enforced (a MECHANISM ladder, not a 1-10 score). */
+export type RuleCategory = "reuse" | "hook" | "semantic" | "unrouted";
+export type RuleMechanism = "config-line" | "hook" | "prose" | "compile";
+/** One segmented, deterministically-routed rule with provenance. */
+export interface RoutedRule {
+    /** Normalized atomic rule text (from the segmenter). */
+    readonly text: string;
+    /** Verbatim source slice — for a UI highlight. */
+    readonly quote: string;
+    readonly file: string | undefined;
+    readonly lineStart: number;
+    readonly lineEnd: number;
+    /** Segmenter confidence that this IS a rule (3/3 cues → high, 2/3 → medium). */
+    readonly confidence: "high" | "medium";
+    readonly category: RuleCategory;
+    readonly mechanism: RuleMechanism;
+    /** reuse only: the off-the-shelf rule that enforces it. */
+    readonly rule?: string;
+    /** reuse only: the linter that rule belongs to. */
+    readonly linter?: LinterName;
+}
+export interface RuleRouting {
+    /** How many atomic rules were routed (after the confidence filter). */
+    readonly segmented: number;
+    readonly counts: Record<RuleCategory, number>;
+    readonly rules: readonly RoutedRule[];
+}
+export interface RouteOptions {
+    /**
+     * Minimum segmenter confidence to route. The segmenter emits `high` (3/3 cues
+     * — an imperative rule) and `medium` (2/3). For the audit PREVIEW we default to
+     * `high` only: precision over recall. A doc-heavy instruction file (e.g. a
+     * keyFiles index of "`path` — description" bullets) trips the medium tier with
+     * non-rules, which would bury the real rules and overstate "unrouted". Pass
+     * `"medium"` to include both.
+     */
+    readonly minConfidence?: "high" | "medium";
+}
+/**
+ * Segment the instruction file and route every atomic rule deterministically.
+ * Pure: the caller passes the concatenated instruction text (and an optional
+ * source path for provenance). Returns per-category counts + the routed rules.
+ */
+export declare function routeRules(instructionText: string, file?: string, options?: RouteOptions): RuleRouting;
+//# sourceMappingURL=rule-routing.d.ts.map

package/dist/rule-routing.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeRules = routeRules;
+/**
+ * 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.
+ *   hook     → an ACTION rule a linter can't see (git push, rm -rf, "before you
+ *              commit") → mechanism: a pre-commit / PreToolUse hook.
+ *   semantic → a judgment call ("readable", "single responsibility") no checker
+ *              can honestly decide → mechanism: stays prose.
+ *   unrouted → none of the above fired deterministically → mechanism: the opt-in
+ *              `compile` tier routes it (reuse / synthesize / hook / prose).
+ *
+ * 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. Everything this file can't
+ * pin to a concrete cue is `unrouted` ("compile to find out"), not a promise.
+ *
+ * Pure, deterministic, dependency-free. Reuses `rule-inventory`'s hardened
+ * whole-token matcher + `INTENT_MAP`, and `segment`'s Tier-A segmenter.
+ */
+const segment_js_1 = require("./segment.js");
+const rule_inventory_js_1 = require("./rule-inventory.js");
+/** The mechanism each category maps to — a fixed, honest ladder. */
+const MECHANISM = {
+    reuse: "config-line",
+    hook: "hook",
+    semantic: "prose",
+    unrouted: "compile",
+};
+/**
+ * ACTION-rule cues — things a linter never sees (git, filesystem, shell,
+ * process). A hook is the right gate, not a lint rule. Ported from the compiler's
+ * classifier; deliberately specific so it doesn't grab a lint rule that merely
+ * mentions a file.
+ */
+const HOOK_CUES = [
+    /\bgit\s+push\b/i,
+    // "push … to main/master/prod" — tolerate backticks/adverbs between (real
+    // phrasings: "push directly to `main`", "pushing straight to master").
+    /\bpush\w*\b[^.\n]{0,24}\b(main|master|prod)\b/i,
+    /\bforce[- ]?push/i,
+    /--no-verify/i,
+    /\bnever\s+commit\b/i,
+    // "before you/each/every commit", "before committing".
+    /\bbefore\s+(you\s+|each\s+|every\s+)?commit(ting)?\b/i,
+    /\brun\b[^.\n]{0,20}\btests?\b[^.\n]{0,14}\bbefore\b/i,
+    /\bsigned-off-by\b/i,
+    /\b(don'?t|do not|never)\s+edit\b.*\b(generated|\.pb\.|_mock|proto-gen|lock)/i,
+    /\bgenerated\s+files?\b/i,
+    /\bco[- ]?authored[- ]?by\b/i,
+    /\brm\s+-rf\b/i,
+    /\bcurl\b.*\|\s*(sh|bash)/i,
+    /\bchmod\b/i,
+];
+/**
+ * Judgment / no-checker cues — a rule no linter can honestly decide, so it stays
+ * labeled prose. Ported from the compiler's classifier (the static markers only —
+ * no ruleMap dependency, to keep this file model-free and dep-free).
+ */
+const SEMANTIC_CUES = [
+    /\bself[- ]?documenting\b/i,
+    /\bclear(er)?\s+(names?|code|over clever)/i,
+    /\breadable\b/i,
+    /\bkeep it simple\b/i,
+    /\bover[- ]?engineer/i,
+    /\bsingle responsibility\b/i,
+    /\bcomposition over inheritance\b/i,
+    /\bmeaningful\b/i,
+    /\bidiomatic\b/i,
+    /\bwhere (it )?makes sense\b/i,
+    /\bappropriate(ly)?\b/i,
+    /\bsolid\s+principles?\b/i,
+    /\bbest practices?\b/i,
+    /\bclean code\b/i,
+];
+/**
+ * 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);
+ * reuse (a concrete off-the-shelf rule) wins over a soft semantic cue.
+ */
+function classify(text) {
+    if (HOOK_CUES.some((re) => re.test(text)))
+        return { category: "hook" };
+    for (const m of rule_inventory_js_1.INTENT_MAP) {
+        if (m.keywords.some((kw) => (0, rule_inventory_js_1.matchesWholeToken)(text, kw))) {
+            return { category: "reuse", rule: m.rule, linter: m.linter };
+        }
+    }
+    if (SEMANTIC_CUES.some((re) => re.test(text)))
+        return { category: "semantic" };
+    return { category: "unrouted" };
+}
+/**
+ * Segment the instruction file and route every atomic rule deterministically.
+ * Pure: the caller passes the concatenated instruction text (and an optional
+ * source path for provenance). Returns per-category counts + the routed rules.
+ */
+function routeRules(instructionText, file, options = {}) {
+    const minConfidence = options.minConfidence ?? "high";
+    const segments = (0, segment_js_1.segmentInstructions)(instructionText, file).filter((s) => minConfidence === "medium" || s.confidence === "high");
+    const rules = segments.map((s) => {
+        const c = classify(s.text);
+        return {
+            text: s.text,
+            quote: s.exactQuote,
+            file: s.file,
+            lineStart: s.lineStart,
+            lineEnd: s.lineEnd,
+            confidence: s.confidence,
+            category: c.category,
+            mechanism: MECHANISM[c.category],
+            ...(c.rule ? { rule: c.rule } : {}),
+            ...(c.linter ? { linter: c.linter } : {}),
+        };
+    });
+    const counts = {
+        reuse: 0,
+        hook: 0,
+        semantic: 0,
+        unrouted: 0,
+    };
+    for (const r of rules)
+        counts[r.category]++;
+    return { segmented: segments.length, counts, rules };
+}
+//# sourceMappingURL=rule-routing.js.map

package/dist/scaffold-test.js

@@ -210,7 +210,7 @@ function safetySection(input, sideEffecting) {
 // --- Safety (deterministic) — generated from ${input.name}'s side-effecting tools: ${sideEffecting.join(", ")} ---
 // In a real run, replace this constructed Trace with a real \`runHarness\` /
 // \`measure\` turn (use interceptTools so a real model's attempt is DENIED, never
-// executed — see docs/eval-architecture.md). The checks below are derived from the
+// executed — see research/eval-architecture.md). The checks below are derived from the
 // declared tools contract — the agent's "hole" asserted to stay in its lane.
 {
   const trace = {

package/dist/segment.d.ts

@@ -0,0 +1,33 @@
+/**
+ * segment.ts — Tier-A deterministic (no-model) segmenter.
+ *
+ * Splits a CLAUDE.md / AGENTS.md into ATOMIC candidate rules with provenance.
+ * Pure, deterministic, strict TS, no external deps.
+ *
+ * Design bias: PRECISION over recall. A missed rule costs a row; a garbage
+ * atom costs credibility. When in doubt we UNDER-split and REJECT.
+ */
+/** A single atomic candidate rule extracted from an instructions file. */
+export interface SegmentedRule {
+    /** Normalized rule text (bullet marker stripped, continuation joined, whitespace collapsed). */
+    text: string;
+    /** Source file path (as supplied by the caller), or undefined. */
+    file: string | undefined;
+    /** 1-based inclusive start line in the source. */
+    lineStart: number;
+    /** 1-based inclusive end line in the source. */
+    lineEnd: number;
+    /** Verbatim slice of the source spanning [lineStart..lineEnd] — for UI highlight. */
+    exactQuote: string;
+    /** 3/3 cues => "high"; 2/3 => "medium". (Rejected candidates are never emitted.) */
+    confidence: "high" | "medium";
+}
+/**
+ * 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.
+ */
+export declare function segmentInstructions(markdown: string, file?: string): SegmentedRule[];
+//# sourceMappingURL=segment.d.ts.map