@event4u/agent-config 9.17.0 → 9.18.1

package/src/scripts/_cli/cmd_route_explain.ts

@@ -0,0 +1,269 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config route:explain "<prompt>" [--files a,b]` — deterministic,
+ * offline trace of which rules the router's triggers match for one prompt.
+ *
+ * The validation surface the routing-correctness mandate asks for: matched
+ * triggers, tier, injected-vs-pointer disposition, budget consumption, and
+ * rejected candidates — all from `dist/router.json` + the ONE shared matcher
+ * (`_lib/router_match.ts`, parity-by-construction with `router_telemetry`
+ * and `explain route`).
+ *
+ * Measurement level (ADR-126): this shows TRIGGER MATCHING only. Whether the
+ * host actually invokes a matched rule is a different measurement and is NOT
+ * made here — the mandatory first output line says so on every run.
+ *
+ * Exit codes: `0` at least one non-kernel rule matched, `1` nothing matched
+ * (kernel is always active, so "no match" still leaves the kernel), `2`
+ * invocation error (missing prompt, unreadable router.json).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    match_prompt,
+    _asRuleList,
+    type Router,
+    type Rule,
+    type Trigger,
+} from '../_lib/router_match.js';
+import { measure, method_note } from '../_lib/token_count.js';
+import { load_agent_settings } from '../_lib/agent_settings.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const ROUTER_JSON = path.join(REPO_ROOT, 'dist', 'router.json');
+const RULES_DIST_DIR = path.join(REPO_ROOT, 'dist', 'agent-src', 'rules');
+
+export const MEASUREMENT_HEADER =
+    'Measurement level: trigger matching only — what the host actually invokes is NOT measured here (ADR-126).';
+
+interface RuleReport {
+    id: string;
+    tier: string;
+    matched: string[]; // "kind: value" labels
+    routes_to: string[];
+    disposition: string;
+    body_chars: number;
+    body_tokens_gpt: number;
+}
+
+interface Report {
+    measurement_level: string;
+    prompt: string;
+    files: string[];
+    profile: string;
+    projection_mode: string;
+    kernel_always: string[];
+    matches: RuleReport[];
+    rejected: { reason: string; ids: string[] }[];
+    budget: { matched_chars: number; matched_tokens_gpt: number; method: string };
+}
+
+function _trigger_label(trigger: Trigger): string {
+    for (const kind of ['keyword', 'phrase', 'command', 'path_prefix', 'file_pattern']) {
+        if (kind in trigger) {
+            return `${kind}: ${String(trigger[kind])}`;
+        }
+    }
+    return `trigger: ${JSON.stringify(trigger)}`;
+}
+
+/** Projection mode from settings; the shipped default is eager-all. */
+export function _projection_mode(): string {
+    try {
+        const settings = load_agent_settings({ cwd: REPO_ROOT }) as Record<string, unknown>;
+        const lp = settings['lean_projection'];
+        if (lp !== null && typeof lp === 'object' && !Array.isArray(lp)) {
+            const mode = (lp as Record<string, unknown>)['mode'];
+            if (typeof mode === 'string' && mode.trim() !== '') {
+                return mode.trim();
+            }
+        }
+    } catch {
+        // settings unreadable → shipped default
+    }
+    return 'eager-all';
+}
+
+function _disposition(tier: string, projection_mode: string): string {
+    if (tier === 'kernel') {
+        return 'injected (kernel, always full-bodied)';
+    }
+    // Disposition is decided at projection time, not at runtime — say so
+    // instead of inventing a runtime injection the router does not perform.
+    return projection_mode === 'eager-all'
+        ? `injected at projection time (${tier}, lean_projection.mode: eager-all)`
+        : `router-resolved pointer at projection time (${tier}, lean_projection.mode: ${projection_mode})`;
+}
+
+function _rule_body_size(rule_id: string): { chars: number; tokens: number } {
+    const p = path.join(RULES_DIST_DIR, `${rule_id}.md`);
+    try {
+        const text = fs.readFileSync(p, 'utf-8');
+        const m = measure(text);
+        return { chars: m.chars, tokens: m.tokens_gpt };
+    } catch {
+        return { chars: 0, tokens: 0 };
+    }
+}
+
+export function build_report(
+    router: Router,
+    prompt: string,
+    files: string[],
+    profile: string,
+): Report {
+    const projection_mode = _projection_mode();
+    const result = match_prompt(router, prompt, profile, files.length > 0 ? files : null, null);
+
+    const matchedByRule = new Map<string, { tier: string; labels: string[] }>();
+    for (const mt of result.matched_triggers) {
+        const id = String(mt.rule);
+        const entry = matchedByRule.get(id) ?? { tier: mt.tier.replace('_', '-'), labels: [] };
+        entry.labels.push(_trigger_label(mt.trigger));
+        matchedByRule.set(id, entry);
+    }
+
+    const routesById = new Map<string, string[]>();
+    for (const tierKey of ['tier_1', 'tier_2'] as const) {
+        for (const rule of _asRuleList(router[tierKey])) {
+            routesById.set(String(rule['id']), ((rule['routes_to'] as unknown[]) ?? []).map(String));
+        }
+    }
+
+    const matches: RuleReport[] = [...matchedByRule.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([id, { tier, labels }]) => {
+            const size = _rule_body_size(id);
+            return {
+                id,
+                tier,
+                matched: labels,
+                routes_to: routesById.get(id) ?? [],
+                disposition: _disposition(tier, projection_mode),
+                body_chars: size.chars,
+                body_tokens_gpt: size.tokens,
+            };
+        });
+
+    const rejected_no_match: string[] = [];
+    for (const tierKey of ['tier_1', 'tier_2'] as const) {
+        if (tierKey === 'tier_2' && profile !== 'full') continue;
+        for (const rule of _asRuleList(router[tierKey])) {
+            const id = String(rule['id']);
+            if (!matchedByRule.has(id)) rejected_no_match.push(id);
+        }
+    }
+    rejected_no_match.sort();
+    const rejected: Report['rejected'] = [
+        { reason: 'no trigger matched', ids: rejected_no_match },
+    ];
+    if (profile !== 'full') {
+        rejected.push({
+            reason: `tier-2 excluded by profile '${profile}' (tier-2 is considered under profile 'full' only)`,
+            ids: _asRuleList(router['tier_2']).map((r: Rule) => String(r['id'])).sort(),
+        });
+    }
+
+    const kernel_always = (Array.isArray(router['kernel']) ? router['kernel'] : []).map(String);
+    const matched_chars = matches.reduce((s, m) => s + m.body_chars, 0);
+    const matched_tokens = matches.reduce((s, m) => s + m.body_tokens_gpt, 0);
+
+    return {
+        measurement_level: MEASUREMENT_HEADER,
+        prompt,
+        files,
+        profile,
+        projection_mode,
+        kernel_always,
+        matches,
+        rejected,
+        budget: { matched_chars, matched_tokens_gpt: matched_tokens, method: method_note() },
+    };
+}
+
+export function render_text(report: Report): string {
+    const out: string[] = [];
+    out.push(report.measurement_level);
+    out.push('');
+    out.push(`prompt: ${JSON.stringify(report.prompt)}`);
+    if (report.files.length > 0) out.push(`files: ${report.files.join(', ')}`);
+    out.push(`profile: ${report.profile} · projection mode: ${report.projection_mode}`);
+    out.push('');
+    out.push(`kernel (always active, ${report.kernel_always.length}): ${report.kernel_always.join(', ')}`);
+    out.push('');
+    out.push(`matched rules (${report.matches.length}):`);
+    for (const m of report.matches) {
+        out.push(`  · ${m.id}  [${m.tier}]`);
+        for (const label of m.matched) out.push(`      matched ${label}`);
+        out.push(`      disposition: ${m.disposition}`);
+        if (m.routes_to.length > 0) out.push(`      routes_to: ${m.routes_to.join(', ')}`);
+        out.push(`      body: ${m.body_chars} chars ≈ ${m.body_tokens_gpt} GPT tokens`);
+    }
+    if (report.matches.length === 0) {
+        out.push('  · (no trigger matched — only kernel rules active)');
+    }
+    out.push('');
+    out.push(
+        `budget consumption of matched non-kernel bodies: ${report.budget.matched_chars} chars`
+        + ` ≈ ${report.budget.matched_tokens_gpt} GPT tokens (${report.budget.method})`,
+    );
+    for (const r of report.rejected) {
+        out.push(`rejected — ${r.reason}: ${r.ids.length} rule(s)`);
+    }
+    return out.join('\n') + '\n';
+}
+
+export function main(argv: string[]): number {
+    const args = [...argv];
+    const as_json = args.includes('--json');
+    let files: string[] = [];
+    let profile = 'full';
+    const positional: string[] = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] as string;
+        if (a === '--json') continue;
+        if (a === '--files') {
+            files = String(args[++i] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+        } else if (a.startsWith('--files=')) {
+            files = a.slice('--files='.length).split(',').map((s) => s.trim()).filter(Boolean);
+        } else if (a === '--profile') {
+            profile = String(args[++i] ?? 'full');
+        } else if (a.startsWith('--profile=')) {
+            profile = a.slice('--profile='.length);
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write(
+                'usage: agent-config route:explain "<prompt>" [--files a,b] [--profile full|balanced] [--json]\n',
+            );
+            return 0;
+        } else {
+            positional.push(a);
+        }
+    }
+    const prompt = positional.join(' ').trim();
+    if (!prompt) {
+        process.stderr.write('route:explain: a prompt is required\n');
+        return 2;
+    }
+    let router: Router;
+    try {
+        router = JSON.parse(fs.readFileSync(ROUTER_JSON, 'utf-8')) as Router;
+    } catch (e) {
+        process.stderr.write(`route:explain: cannot read ${ROUTER_JSON}: ${String(e)}\n`);
+        return 2;
+    }
+    const report = build_report(router, prompt, files, profile);
+    if (as_json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    } else {
+        process.stdout.write(render_text(report));
+    }
+    return report.matches.length === 0 ? 1 : 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+if (process.argv[1] && (import.meta.url === pathToFileURL(process.argv[1]).href || path.resolve(process.argv[1]) === _HERE)) {
+    process.exitCode = main(process.argv.slice(2));
+}

package/src/scripts/_dispatch.bash

@@ -208,6 +208,15 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              router + projection freshness, host bridge status.
                              Flags: --platform <p>, --workspace <path>, --json, --strict,
                              --no-freshness
+  route:explain              Deterministic rule-routing trace for one prompt: matched
+                             triggers, tier, injected-vs-pointer disposition, budget
+                             consumption, rejected candidates. Trigger-match level only
+                             (what the host invokes is not measured).
+                             Flags: --files a,b, --profile full|balanced, --json
+  route:audit                Replay the router matcher over the last N user prompts of
+                             the chat-history log; renders matched rules per prompt.
+                             Trigger-match level only; read-only, no LLM call.
+                             Flags: --last N, --record (opt-in recorder), --weekly, --json
   hooks:replay               Replay a fixture through the universal dispatcher with
                              AGENT_CONFIG_REPLAY=1 (no writes under agents/runtime/state/).
                              Usage: hooks:replay --platform <name> --event <event>
@@ -1171,6 +1180,18 @@ cmd_versions() {
 
 # `agent-config explain <config|rule|route>` — print the decision chain
 # behind a configuration or routing outcome. Read-only diagnostic; never
+# Router-matcher replay over recent chat-history prompts (read-only).
+# See scripts/_cli/cmd_route_audit.ts.
+cmd_route_audit() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_route_audit.ts" "$@"
+}
+
+# Deterministic rule-routing trace (trigger-match measurement level only).
+# See scripts/_cli/cmd_route_explain.ts.
+cmd_route_explain() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_route_explain.ts" "$@"
+}
+
 # edits state. See scripts/_cli/cmd_explain.ts.
 cmd_explain() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_explain.ts" "$@"
@@ -1235,6 +1256,8 @@ main() {
     hooks:status)            cmd_hooks_status "$@" ;;
     hooks:doctor)            cmd_hooks_doctor "$@" ;;
     routing:doctor)          cmd_routing_doctor "$@" ;;
+    route:explain)           cmd_route_explain "$@" ;;
+    route:audit)             cmd_route_audit "$@" ;;
     hooks:replay)            cmd_hooks_replay "$@" ;;
     reach:doctor)            cmd_reach_doctor "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;

package/src/scripts/_lib/git_env.ts

@@ -0,0 +1,40 @@
+/**
+ * Environment for child `git` invocations that must resolve from their `cwd`.
+ *
+ * Git hooks export `GIT_DIR` (and often `GIT_INDEX_FILE`), and every child
+ * process inherits them. An inherited `GIT_DIR` **overrides** repository
+ * discovery, so `execFileSync('git', […], { cwd })` silently operates against
+ * the hook's repository instead of `cwd`. In a linked worktree the two differ,
+ * and the symptom is not an error but wrong data: `git log -- <path>` returns
+ * nothing, which the Gate R1 grandfather clause reads as "no pre-activation
+ * baseline" and reports as `missing_register` on every grandfathered roadmap.
+ *
+ * That made the pre-push enforcement layer fire spuriously while CI — which
+ * runs the same gate WITHOUT `GIT_DIR` — stayed green: the worst shape for a
+ * gate, since the failure looks like a content problem and the authoritative
+ * layer disagrees with the local one.
+ *
+ * Every gate in this family therefore runs git through this env: the variables
+ * that redirect discovery are removed, so `cwd` is the only thing that decides.
+ */
+
+/** Git env vars that override repository discovery and must not be inherited. */
+export const GIT_DISCOVERY_VARS: readonly string[] = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_COMMON_DIR',
+    'GIT_NAMESPACE',
+    'GIT_PREFIX',
+];
+
+/** `process.env` minus the discovery-overriding variables. */
+export function gitEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+    const env: NodeJS.ProcessEnv = { ...base };
+    for (const key of GIT_DISCOVERY_VARS) {
+        delete env[key];
+    }
+    return env;
+}

package/src/scripts/_lib/md_table.ts

@@ -0,0 +1,27 @@
+/**
+ * Markdown table-row splitting, escape-aware.
+ *
+ * Both plan-governance validators parse pipe tables whose cells legitimately
+ * contain an escaped pipe: the Risk-Register contract example writes
+ * `product \| implementation`, and findings text routinely describes unions or
+ * flags (`text\|json`). Splitting on every `|` shifts every later cell by one,
+ * so `Risk type` becomes `product \` and a findings row's `Status` becomes a
+ * fragment of its own Finding text — a spurious block with no fix except
+ * rewording the prose.
+ *
+ * One definition, imported by both validators: the same defect appearing twice
+ * is what made this a shared helper rather than a local function.
+ */
+
+/** Split on unescaped `|` only, drop the outer delimiters, unescape, trim. */
+export function splitMarkdownRow(line: string): string[] {
+    let inner = line.trim();
+    if (inner.startsWith('|')) {
+        inner = inner.slice(1);
+    }
+    // A trailing pipe is a delimiter only when it is not itself escaped.
+    if (inner.endsWith('|') && !inner.endsWith('\\|')) {
+        inner = inner.slice(0, -1);
+    }
+    return inner.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, '|').trim());
+}

package/src/scripts/_lib/planning_settings.ts

@@ -0,0 +1,43 @@
+/**
+ * Gate-R2 settings escape hatch, shared by the validator and the dispatcher.
+ *
+ * It lives here rather than in either script because BOTH R2 enforcement layers
+ * must honour it: `check_completion_review` (the gate) and
+ * `dispatch_r2_reviewer --verify` / `--verify-current` (the manifest
+ * re-derivation CI step). A reader that only the gate consulted left the second,
+ * blocking layer firing with the gate nominally switched off. `check_*` already
+ * imports the scope hash from `dispatch_*`, so putting the predicate in either
+ * one would make the import cycle back on itself.
+ *
+ * Fail-open by design: an unreadable or unparseable settings file, or a missing
+ * key, leaves the gate ACTIVE (`=== false` is the only disabling value).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+function planningFlagIsFalse(settingsDir: string, key: string): boolean {
+    const settingsPath = path.join(settingsDir, '.agent-settings.yml');
+    let raw: string;
+    try {
+        raw = fs.readFileSync(settingsPath, 'utf-8');
+    } catch {
+        return false;
+    }
+    try {
+        const parsed = parseYaml(raw) as unknown;
+        if (parsed === null || typeof parsed !== 'object') return false;
+        const planning = (parsed as Record<string, unknown>)['planning'];
+        if (planning === null || typeof planning !== 'object') return false;
+        return (planning as Record<string, unknown>)[key] === false;
+    } catch {
+        return false;
+    }
+}
+
+/** `planning.completion_review === false` in `<dir>/.agent-settings.yml`. */
+export function completionReviewDisabled(settingsDir: string): boolean {
+    return planningFlagIsFalse(settingsDir, 'completion_review');
+}