@event4u/agent-config 9.17.0 → 9.18.0

package/src/scripts/_lib/router_match.ts

@@ -0,0 +1,301 @@
+/**
+ * THE single trigger-matcher implementation for `dist/router.json`.
+ *
+ * Parity by construction: every surface that answers "which rules fire on
+ * this prompt?" — router replay (`router_telemetry.ts`), trigger-coverage
+ * CI (`trigger_coverage.ts`), `agent-config explain route`, and
+ * `agent-config route:explain` — MUST import the matchers from this module.
+ * A second implementation of these semantics anywhere in the tree is a
+ * violation (enforced by `tests/scripts/router_match_parity.test.ts`); the
+ * historical divergence this kills was `cmd_explain.ts` shipping unanchored
+ * keyword matching while the replay path was anchored.
+ *
+ * Canonical semantics: `docs/contracts/rule-router.md` § `triggers:` shape
+ * (the trigger-semantics table — anchored `keyword`, unanchored `phrase`,
+ * `command` prefix, `path_prefix` / `file_pattern` over open files).
+ *
+ * Extracted verbatim from `router_telemetry.ts` (which re-exports the same
+ * names for existing importers). Behaviour is pinned by the routing-matrix
+ * and trigger-coverage suites — do not "fix" quirks here.
+ */
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type Trigger = Record<string, JsonValue>;
+
+export interface Rule {
+  id?: JsonValue;
+  triggers?: JsonValue;
+  [key: string]: JsonValue;
+}
+
+export interface Router {
+  kernel?: JsonValue;
+  tier_1?: JsonValue;
+  tier_2?: JsonValue;
+  [key: string]: JsonValue;
+}
+
+// ── fnmatch (Python fnmatch.fnmatch) ─────────────────────────────────────
+
+/**
+ * Translate a Unix shell pattern into a RegExp, matching CPython's
+ * `fnmatch.translate`. `*` → `.*`, `?` → `.`, `[...]` char classes
+ * preserved (with `!` → `^` negation), everything else escaped.
+ * Matching is case-sensitive on POSIX (the corpus paths are POSIX).
+ */
+function _fnmatchToRegExp(pat: string): RegExp {
+  let res = "";
+  let i = 0;
+  const n = pat.length;
+  while (i < n) {
+    const c = pat[i] as string;
+    i += 1;
+    if (c === "*") {
+      res += ".*";
+    } else if (c === "?") {
+      res += ".";
+    } else if (c === "[") {
+      let j = i;
+      if (j < n && pat[j] === "!") {
+        j += 1;
+      }
+      if (j < n && pat[j] === "]") {
+        j += 1;
+      }
+      while (j < n && pat[j] !== "]") {
+        j += 1;
+      }
+      if (j >= n) {
+        res += "\\[";
+      } else {
+        let stuff = pat.slice(i, j);
+        if (!stuff.includes("-")) {
+          stuff = stuff.replace(/\\/g, "\\\\");
+        } else {
+          // Faithful port of CPython's dash-handling in fnmatch.translate:
+          // split the class body on `-` (bounded to [i, j)), escaping each
+          // chunk, then re-join with `-` so ranges survive.
+          const chunks: string[] = [];
+          let k = pat[i] === "!" ? i + 2 : i + 1;
+          let start = i;
+          while (true) {
+            const rel = pat.slice(k, j).indexOf("-");
+            if (rel < 0) {
+              break;
+            }
+            const idx = k + rel;
+            chunks.push(pat.slice(start, idx));
+            start = idx + 1;
+            k = idx + 3;
+          }
+          chunks.push(pat.slice(start, j));
+          stuff = chunks
+            .map((s) => s.replace(/\\/g, "\\\\").replace(/-/g, "\\-"))
+            .join("-");
+        }
+        // Escape regex set-meta chars except backslash/dash already handled.
+        stuff = stuff.replace(/([&~|])/g, "\\$1");
+        i = j + 1;
+        if (stuff.startsWith("!")) {
+          stuff = "^" + stuff.slice(1);
+        } else if (stuff.startsWith("^") || stuff.startsWith("[")) {
+          stuff = "\\" + stuff;
+        }
+        res += `[${stuff}]`;
+      }
+    } else {
+      res += c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^(?:${res})$`, "s");
+}
+
+export function _fnmatch(name: string, pat: string): boolean {
+  return _fnmatchToRegExp(pat).test(name);
+}
+
+// ── Trigger matching ─────────────────────────────────────────────────────
+
+/** Apply one trigger to a prompt + context; return True on match. */
+/** Unicode word character — letters, digits, underscore (incl. umlauts). */
+const _WORD_CHAR = /[\p{L}\p{N}_]/u;
+
+function _isWordChar(c: string | undefined): boolean {
+  return c !== undefined && _WORD_CHAR.test(c);
+}
+
+/**
+ * Word-boundary-anchored keyword match (road-to-tested-routing Phase 3).
+ *
+ * A `keyword` occurrence counts only when its word-character edges sit on
+ * word boundaries: `ac` no longer fires inside "black", `plan` no longer
+ * fires inside "planet". Two deliberate reliefs:
+ *
+ * - An edge that is itself a NON-word character (e.g. `__()`, `/image:`,
+ *   `trans(`, an emoji) carries no boundary requirement on that side —
+ *   punctuation-shaped keywords keep their exact substring semantics.
+ * - The right boundary accepts one optional plural `s` ("icons", "options",
+ *   "secrets" still fire their singular keyword). Richer inflection (German
+ *   verb endings: "implementiere", "committen") is a DOCUMENTED accepted
+ *   recall cost of anchoring — the matrices carry standalone-token phrasings
+ *   for those languages instead.
+ *
+ * `phrase` deliberately stays unanchored substring; since this change the
+ * two trigger kinds genuinely differ.
+ */
+export function keyword_matches_anchored(prompt_lower: string, kw_lower: string): boolean {
+  if (kw_lower === "") {
+    return false;
+  }
+  const needLeft = _isWordChar(kw_lower[0]);
+  const needRight = _isWordChar(kw_lower[kw_lower.length - 1]);
+  let idx = prompt_lower.indexOf(kw_lower);
+  while (idx !== -1) {
+    const leftOk = !needLeft || !_isWordChar(prompt_lower[idx - 1]);
+    let rightOk = true;
+    if (needRight) {
+      let end = idx + kw_lower.length;
+      if (prompt_lower[end] === "s") {
+        end += 1; // optional plural `s`
+      }
+      rightOk = !_isWordChar(prompt_lower[end]);
+    }
+    if (leftOk && rightOk) {
+      return true;
+    }
+    idx = prompt_lower.indexOf(kw_lower, idx + 1);
+  }
+  return false;
+}
+
+export function trigger_matches(
+  trigger: Trigger,
+  prompt: string,
+  open_files?: Iterable<string> | null,
+  command?: string | null,
+): boolean {
+  const prompt_lower = prompt.toLowerCase();
+  if ("keyword" in trigger) {
+    return keyword_matches_anchored(prompt_lower, String(trigger["keyword"]).toLowerCase());
+  }
+  if ("phrase" in trigger) {
+    return prompt_lower.includes(String(trigger["phrase"]).toLowerCase());
+  }
+  if ("command" in trigger) {
+    if (!command) {
+      return false;
+    }
+    return command.startsWith(String(trigger["command"]));
+  }
+  if ("path_prefix" in trigger) {
+    if (!open_files) {
+      return false;
+    }
+    const pref = String(trigger["path_prefix"]);
+    for (const p of open_files) {
+      if (String(p).startsWith(pref)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  if ("file_pattern" in trigger) {
+    if (!open_files) {
+      return false;
+    }
+    const pat = String(trigger["file_pattern"]);
+    for (const p of open_files) {
+      if (_fnmatch(String(p), pat)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  return false;
+}
+
+export interface MatchedTrigger {
+  tier: string;
+  rule: JsonValue | undefined;
+  trigger: Trigger;
+}
+
+export interface ActivatedRule {
+  tier: string;
+  rule: JsonValue | undefined;
+}
+
+export interface MatchResult {
+  matched_triggers: MatchedTrigger[];
+  activated_rules: ActivatedRule[];
+}
+
+export function _asRuleList(value: JsonValue | undefined): Rule[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value as unknown as Rule[];
+}
+
+export function _asTriggerList(value: JsonValue | undefined): Trigger[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value as unknown as Trigger[];
+}
+
+/**
+ * Return the matched-triggers + activated-rules for one prompt.
+ *
+ * Kernel rules are always active. tier_1 always considered. tier_2
+ * only considered when `profile == 'full'`.
+ */
+export function match_prompt(
+  router: Router,
+  prompt: string,
+  profile = "full",
+  open_files?: Iterable<string> | null,
+  command?: string | null,
+): MatchResult {
+  const tiers: Array<[string, Rule[]]> = [
+    ["tier_1", _asRuleList(router["tier_1"])],
+  ];
+  if (profile === "full") {
+    tiers.push(["tier_2", _asRuleList(router["tier_2"])]);
+  }
+
+  const matched_triggers: MatchedTrigger[] = [];
+  const activated_rules: ActivatedRule[] = [];
+
+  for (const [tier_name, rules] of tiers) {
+    for (const rule of rules) {
+      const rule_id = rule["id"];
+      const rule_triggers = _asTriggerList(rule["triggers"]);
+      let rule_hit = false;
+      for (const trig of rule_triggers) {
+        if (trigger_matches(trig, prompt, open_files, command)) {
+          matched_triggers.push({ tier: tier_name, rule: rule_id, trigger: trig });
+          rule_hit = true;
+        }
+      }
+      if (rule_hit) {
+        activated_rules.push({ tier: tier_name, rule: rule_id });
+      }
+    }
+  }
+
+  // Kernel rules are always active.
+  const kernel = Array.isArray(router["kernel"]) ? router["kernel"] : [];
+  for (const kid of kernel) {
+    activated_rules.push({ tier: "kernel", rule: kid });
+  }
+
+  return { matched_triggers, activated_rules };
+}

package/src/scripts/annotate_r1_outcomes.ts

@@ -0,0 +1,258 @@
+#!/usr/bin/env tsx
+/**
+ * Gate R1 outcome annotation helper (quarterly cadence — see
+ * docs/contracts/plan-review-gates.md § 7).
+ *
+ * Walks the `## Risk Register` sections of ARCHIVED roadmaps
+ * (agents/roadmaps/archive/*.md), and for every register row that has no
+ * recorded outcome yet, prompts the operator:
+ *
+ *   helped  — the mitigation prevented the risk (or materially reduced it)
+ *   fired   — the risk fired despite (or without) the mitigation
+ *   unknown — cannot be judged (yet)
+ *
+ * Each answer appends one `r1_mitigation_outcome` event to the tracked
+ * metrics JSONL (agents/evidence/metrics/gate-metrics.jsonl) — ids +
+ * counters only, PII-free by construction. Already-annotated rows
+ * (same file + rank in the JSONL) are skipped, so re-runs are idempotent.
+ *
+ * Not a gate: no `scanned:` line, no gate-coverage entry. Exit 0 on
+ * completion (including nothing-to-annotate), 2 on internal error.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/annotate_r1_outcomes            # interactive
+ *   ./scripts-run src/scripts/annotate_r1_outcomes --list     # show pending only
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as readline from 'node:readline';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { splitMarkdownRow } from './_lib/md_table.js';
+
+const ARCHIVE_DIR = 'agents/roadmaps/archive';
+const METRICS_FILE = 'agents/evidence/metrics/gate-metrics.jsonl';
+const OUTCOMES = new Set(['helped', 'fired', 'unknown']);
+
+interface RegisterRow {
+    file: string;
+    rank: number;
+    item: string;
+    mitigation: string;
+}
+
+/** § 1.2 register columns: Rank | Item | Risk type | Description | Mitigation | Anchored under. */
+const REGISTER_CELLS = 6;
+const ITEM_CELL = 1;
+const MITIGATION_CELL = 4;
+
+export function extractRegisterRows(file: string, content: string): RegisterRow[] {
+    const rows: RegisterRow[] = [];
+    const lines = content.split(/\r?\n/);
+    let inRegister = false;
+    for (const line of lines) {
+        if (/^##\s+Risk Register\s*$/.test(line)) {
+            inRegister = true;
+            continue;
+        }
+        if (inRegister && /^##\s+/.test(line)) break;
+        if (!inRegister) continue;
+        if (!line.trim().startsWith('|')) continue;
+        // Escape-aware split, shared with both validators: a per-column
+        // `[^|]*` regex mis-aligns on a `\|` inside a cell — the shape the
+        // contract's own §1.2 example uses (`product \| implementation`) —
+        // and then records the Description as the mitigation.
+        const cells = splitMarkdownRow(line);
+        if (cells.length < REGISTER_CELLS) continue;
+        const rank = cells[0] ?? '';
+        if (!/^\d+$/.test(rank)) continue; // header / separator / prose row
+        rows.push({
+            file,
+            rank: Number(rank),
+            item: (cells[ITEM_CELL] ?? '').trim(),
+            mitigation: (cells[MITIGATION_CELL] ?? '').trim(),
+        });
+    }
+    return rows;
+}
+
+export function annotatedKeys(metricsText: string): Set<string> {
+    const keys = new Set<string>();
+    for (const line of metricsText.split('\n')) {
+        if (line.trim() === '') continue;
+        try {
+            const ev = JSON.parse(line) as { event?: string; file?: string; rank?: number };
+            if (ev.event === 'r1_mitigation_outcome' && ev.file !== undefined && ev.rank !== undefined) {
+                keys.add(`${ev.file}#${String(ev.rank)}`);
+            }
+        } catch {
+            // tolerate foreign lines — the JSONL is append-only and shared
+        }
+    }
+    return keys;
+}
+
+/**
+ * Ask one question. Resolves `null` on EOF instead of hanging or throwing:
+ * `rl.question`'s callback never fires once the stream ends, so a piped or
+ * scheduled invocation would otherwise block forever — and an interface that is
+ * ALREADY closed (the input ran out between two prompts) throws
+ * `ERR_USE_AFTER_CLOSE` from `question`, which is the same end-of-input state
+ * and must end the pass just as cleanly.
+ */
+function ask(rl: readline.Interface, q: string): Promise<string | null> {
+    return new Promise((resolve) => {
+        if ((rl as { closed?: boolean }).closed === true) {
+            resolve(null);
+            return;
+        }
+        let settled = false;
+        const onClose = (): void => {
+            if (!settled) {
+                settled = true;
+                resolve(null);
+            }
+        };
+        rl.once('close', onClose);
+        try {
+            rl.question(q, (answer) => {
+                settled = true;
+                rl.removeListener('close', onClose);
+                resolve(answer);
+            });
+        } catch {
+            rl.removeListener('close', onClose);
+            if (!settled) {
+                settled = true;
+                resolve(null);
+            }
+        }
+    });
+}
+
+export interface AnnotateIo {
+    /**
+     * readline input; defaults to `process.stdin`.
+     *
+     * Injected by the tests to drive the EOF path deterministically — a
+     * caller-supplied stream is a deliberate non-TTY answer channel, so the
+     * TTY refusal below applies to `process.stdin` only.
+     */
+    input?: NodeJS.ReadableStream;
+}
+
+export async function main(argv?: readonly string[], io: AnnotateIo = {}): Promise<number> {
+    const args = argv ?? process.argv.slice(2);
+    const listOnly = args.includes('--list');
+
+    if (!fs.existsSync(ARCHIVE_DIR)) {
+        process.stdout.write(`No archive directory at ${ARCHIVE_DIR} — nothing to annotate.\n`);
+        return 0;
+    }
+
+    const files = fs
+        .readdirSync(ARCHIVE_DIR)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => path.join(ARCHIVE_DIR, f));
+
+    const metricsText = fs.existsSync(METRICS_FILE) ? fs.readFileSync(METRICS_FILE, 'utf8') : '';
+    const done = annotatedKeys(metricsText);
+
+    const pending: RegisterRow[] = [];
+    for (const f of files) {
+        const rows = extractRegisterRows(f, fs.readFileSync(f, 'utf8'));
+        for (const r of rows) {
+            if (!done.has(`${r.file}#${String(r.rank)}`)) pending.push(r);
+        }
+    }
+
+    if (pending.length === 0) {
+        process.stdout.write('✅  No un-annotated Risk-Register rows in archived roadmaps.\n');
+        return 0;
+    }
+
+    process.stdout.write(`${String(pending.length)} un-annotated mitigation(s) in archived roadmaps:\n`);
+    if (listOnly) {
+        for (const r of pending) {
+            process.stdout.write(`  ${r.file} #${String(r.rank)} — ${r.item}\n`);
+        }
+        return 0;
+    }
+
+    // Interactive-only by construction: the annotation pass is a human quarterly
+    // cadence, so a non-TTY invocation is refused up front with the read-only
+    // alternative rather than left to block on a prompt nobody can answer.
+    if (io.input === undefined && process.stdin.isTTY !== true) {
+        process.stderr.write(
+            '❌  annotate_r1_outcomes needs an interactive terminal (stdin is not a TTY).\n' +
+                '    Use --list for the read-only pending inventory.\n',
+        );
+        return 2;
+    }
+
+    const rl = readline.createInterface({ input: io.input ?? process.stdin, output: process.stdout });
+    try {
+        for (const r of pending) {
+            process.stdout.write(`\n${r.file} #${String(r.rank)}\n  risk: ${r.item}\n  mitigation: ${r.mitigation}\n`);
+            let answer = '';
+            let eof = false;
+            while (!OUTCOMES.has(answer)) {
+                const raw = await ask(rl, '  outcome [helped/fired/unknown, s=skip]: ');
+                if (raw === null) {
+                    eof = true;
+                    break;
+                }
+                answer = raw.trim().toLowerCase();
+                if (answer === 's' || answer === 'skip') break;
+            }
+            if (eof) {
+                process.stdout.write('\n⚠️  stdin closed — ending the annotation pass early.\n');
+                break;
+            }
+            if (!OUTCOMES.has(answer)) continue;
+            const event = {
+                event: 'r1_mitigation_outcome',
+                date: new Date().toISOString().slice(0, 10),
+                file: r.file,
+                rank: r.rank,
+                outcome: answer,
+            };
+            // The metrics dir need not exist yet (a repo whose first recorded
+            // event is this one). Creating it here rather than letting
+            // `appendFileSync` throw matters because the throw would land AFTER
+            // the operator answered — an ENOENT crash that discards answers a
+            // human just typed. `recursive: true` is a no-op once it exists.
+            fs.mkdirSync(path.dirname(METRICS_FILE), { recursive: true });
+            fs.appendFileSync(METRICS_FILE, `${JSON.stringify(event)}\n`);
+        }
+    } finally {
+        rl.close();
+    }
+    process.stdout.write('\n✅  Annotation pass complete.\n');
+    return 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv1;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    main()
+        .then((code) => process.exit(code))
+        .catch((exc: unknown) => {
+            const msg = exc instanceof Error ? exc.message : String(exc);
+            process.stderr.write(`❌  Internal error: ${msg}\n`);
+            process.exit(2);
+        });
+}