@event4u/agent-config 8.10.0 → 8.11.0

package/src/scripts/analysis_freshness.ts

@@ -1,362 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Project-analysis freshness loop — a cheap *heuristic* staleness signal.
- *
- * Ported from the retired Python `src/scripts/analysis_freshness.py` (ADR-200,
- * Python→TypeScript migration). The CLI contract is pinned — the
- * required mutually-exclusive group (`--stamp FILE | --stamp-all | --check FILE
- * | --check-all`), the argparse usage banner + error text (missing required
- * group → exit 2, conflicting args → exit 2, missing value → exit 2,
- * `-h`/`--help` → exit 0), the git probe (`git -C REPO_ROOT … check=False`,
- * stdout stripped), the freshness-header regex + path-token regex, the
- * staleness bands, `sorted(ANALYSIS_DIR.glob("*.md"))`, and byte-identical
- * stdout. snake_case kept.
- *
- * `project-analyzer` output under ``agents/evidence/analysis/*.md`` is rich but
- * has no signal for *"is this still current?"*. This script adds a one-line
- * freshness header and a probe that tells the agent whether a high-tier
- * re-analysis is likely worth it. File-first, no runtime.
- *
- * Header shape (top of each analysis file):
- *
- *     <!-- analyzed: 2026-06-15 | commit: 57588489 | files: 4 -->
- *
- * Usage:
- *   python3 src/scripts/analysis_freshness.py --stamp agents/evidence/analysis/foo.md
- *   python3 src/scripts/analysis_freshness.py --stamp-all
- *   python3 src/scripts/analysis_freshness.py --check agents/evidence/analysis/foo.md
- *   python3 src/scripts/analysis_freshness.py --check-all
- */
-
-import { spawnSync } from 'node:child_process';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const _HERE = path.resolve(fileURLToPath(import.meta.url));
-// _HERE = Path(__file__).resolve().parent ; REPO_ROOT = _HERE.parent.parent
-const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-// Mutable binding so tests can sandbox the scan target (mirrors the pytest
-// monkeypatch.setattr seam used by sibling lint twins).
-let ANALYSIS_DIR = path.join(REPO_ROOT, 'agents', 'evidence', 'analysis');
-
-function _setAnalysisDirForTest(p: string): void {
-    ANALYSIS_DIR = p;
-}
-
-// _HEADER_RE = re.compile(
-//   r"<!--\s*analyzed:\s*(?P<date>[\d-]+)\s*\|\s*commit:\s*(?P<commit>[0-9a-f]+)"
-//   r"\s*\|\s*files:\s*(?P<files>\d+)\s*-->")
-const _HEADER_RE =
-    /<!--[\s]*analyzed:[\s]*(?<date>[\d-]+)[\s]*\|[\s]*commit:[\s]*(?<commit>[0-9a-f]+)[\s]*\|[\s]*files:[\s]*(?<files>\d+)[\s]*-->/;
-// _PATH_RE = re.compile(r"`(?P<p>(?:src|docs|agents|scripts|tests)/[\w./-]+)`")
-const _PATH_RE = /`(?<p>(?:src|docs|agents|scripts|tests)\/[\w./-]+)`/g;
-
-// Heuristic staleness bands by count of changed files over the analyzed paths.
-const _AGING = 1;
-const _STALE = 8;
-
-/**
- * subprocess.run(["git", "-C", REPO_ROOT, *args], capture_output=True,
- * text=True, check=False).stdout.strip()
- *
- * Python `str.strip()` removes leading + trailing whitespace; `text=True`
- * decodes stdout as UTF-8. On a non-zero exit, stdout is still returned
- * (check=False), and a failure to spawn yields "" (mirrors empty stdout).
- */
-function _git(...args: string[]): string {
-    const res = spawnSync('git', ['-C', REPO_ROOT, ...args], { encoding: 'utf8' });
-    const out = res.stdout ?? '';
-    return _pyStrip(out);
-}
-
-/** Python str.strip() — strips the ASCII + Unicode whitespace set Python uses. */
-function _pyStrip(s: string): string {
-    // Python str.strip() default whitespace: spaces, \t \n \r \v \f and a set
-    // of Unicode whitespace. For git output the ASCII set is sufficient; mirror
-    // \s plus the explicit C0 set Python treats as whitespace.
-    return s.replace(/^[\s… ]+/, '').replace(/[\s… ]+$/, '');
-}
-
-function _head_short(): string {
-    return _git('rev-parse', '--short', 'HEAD') || 'unknown';
-}
-
-/** Best-effort: repo paths the doc cites (deduped, existing only). */
-function _referenced_paths(text: string): string[] {
-    const seen: string[] = [];
-    _PATH_RE.lastIndex = 0;
-    let m: RegExpExecArray | null;
-    while ((m = _PATH_RE.exec(text)) !== null) {
-        const p = m.groups?.p as string;
-        if (!seen.includes(p) && _exists(path.join(REPO_ROOT, p))) {
-            seen.push(p);
-        }
-    }
-    return seen;
-}
-
-function _exists(p: string): boolean {
-    try {
-        fs.statSync(p);
-        return true;
-    } catch {
-        return false;
-    }
-}
-
-function cmd_stamp(p: string): number {
-    const text = fs.readFileSync(p, 'utf-8');
-    const paths = _referenced_paths(text);
-    // Backfill the analyzed date from the file's own last commit (honest for
-    // retro-stamps); go-forward stamps land on today via a fresh re-stamp.
-    const date = _git('log', '-1', '--format=%cs', '--', p) || _git('log', '-1', '--format=%cs');
-    const header = `<!-- analyzed: ${date} | commit: ${_head_short()} | files: ${paths.length} -->`;
-    const body = _HEADER_RE.test(text)
-        ? _lstripNewlines(_subFirst(_HEADER_RE, text, ''))
-        : text;
-    fs.writeFileSync(p, header + '\n' + body, 'utf-8');
-    process.stdout.write(`  stamped ${_relToRoot(p)} → ${header}\n`);
-    return 0;
-}
-
-/** re.sub(pattern, "", text, count=1) — replace first match only. */
-function _subFirst(re: RegExp, text: string, repl: string): string {
-    const m = re.exec(text);
-    if (!m) {
-        return text;
-    }
-    return text.slice(0, m.index) + repl + text.slice(m.index + m[0].length);
-}
-
-/** str.lstrip("\n") — strip leading newlines only. */
-function _lstripNewlines(s: string): string {
-    return s.replace(/^\n+/, '');
-}
-
-function _relToRoot(p: string): string {
-    return path.relative(REPO_ROOT, p).split(path.sep).join('/');
-}
-
-function cmd_check(p: string): number {
-    const text = fs.readFileSync(p, 'utf-8');
-    const m = _HEADER_RE.exec(text);
-    if (!m) {
-        process.stdout.write(`  ⚠️  ${_relToRoot(p)} — no freshness header (run --stamp)\n`);
-        return 0;
-    }
-    const commit = m.groups?.commit as string;
-    const paths = _referenced_paths(text);
-    const scope = paths.length ? paths : ['.'];
-    let changed = _git('diff', '--name-only', `${commit}..HEAD`, '--', ...scope).split('\n');
-    changed = changed.filter((c) => _pyStrip(c) !== '');
-    const n = changed.length;
-    const band =
-        n === 0 ? 'fresh' : n < _STALE ? 'aging' : 'STALE — re-analysis likely worth it';
-    let verdict: string;
-    if (n >= _AGING) {
-        verdict = n >= _STALE ? `⚠️  ${band}` : `·  ${band}`;
-    } else {
-        verdict = '✅  fresh';
-    }
-    process.stdout.write(
-        `  ${verdict} — ${_relToRoot(p)}: ${n} changed file(s) ` +
-            `over ${scope.length} analyzed path(s) since ${commit}\n`,
-    );
-    return 0;
-}
-
-/** sorted(ANALYSIS_DIR.glob("*.md")). */
-function _iter_analysis(): string[] {
-    let entries: fs.Dirent[];
-    try {
-        entries = fs.readdirSync(ANALYSIS_DIR, { withFileTypes: true });
-    } catch {
-        return [];
-    }
-    const out: string[] = [];
-    for (const ent of entries) {
-        // glob("*.md") matches files + dirs ending in .md, non-recursively.
-        if (ent.name.endsWith('.md')) {
-            out.push(path.join(ANALYSIS_DIR, ent.name));
-        }
-    }
-    out.sort();
-    return out;
-}
-
-// ---------------------------------------------------------------------------
-// argparse-faithful CLI
-// ---------------------------------------------------------------------------
-
-const _PROG = 'analysis_freshness.py';
-const _USAGE =
-    `usage: ${_PROG} [-h]\n` +
-    `                             (--stamp FILE | --stamp-all | --check FILE | --check-all)\n`;
-
-interface Args {
-    stamp: string | null;
-    stamp_all: boolean;
-    check: string | null;
-    check_all: boolean;
-}
-
-class ArgError {
-    constructor(public readonly code: number) {}
-}
-
-function _argError(msg: string): never {
-    process.stderr.write(_USAGE + `${_PROG}: error: ${msg}\n`);
-    throw new ArgError(2);
-}
-
-function _parseArgs(argv: readonly string[]): Args {
-    // Mirror argparse's parse_args precedence for this parser:
-    //   1. -h/--help  → print + exit 0 (fires immediately on encounter).
-    //   2. missing value (--stamp / --check with no following token) → exit 2.
-    //   3. mutex conflict (two group members) → exit 2 (during parse).
-    //   4. required-group-not-satisfied → exit 2 (end of parse_known_args).
-    //   5. unrecognized extras → exit 2 (after parse_known_args returns,
-    //      only when 4 passed). Extras are collected, then reported together.
-    let stamp: string | null = null;
-    let stamp_all = false;
-    let check: string | null = null;
-    let check_all = false;
-    let firstSeen: string | null = null;
-    const extras: string[] = [];
-
-    const conflict = (current: string): void => {
-        if (firstSeen !== null && firstSeen !== current) {
-            _argError(`argument ${current}: not allowed with argument ${firstSeen}`);
-        }
-        if (firstSeen === null) {
-            firstSeen = current;
-        }
-    };
-
-    let i = 0;
-    while (i < argv.length) {
-        const a = argv[i] as string;
-        if (a === '-h' || a === '--help') {
-            // argparse prints full help (usage + description + options) and
-            // exits 0. Tests do NOT byte-compare help prose; print the usage
-            // banner (deterministic head) and exit 0.
-            process.stdout.write(_USAGE);
-            throw new ArgError(0);
-        }
-        if (a === '--stamp') {
-            const v = argv[i + 1];
-            if (v === undefined) {
-                _argError('argument --stamp: expected one argument');
-            }
-            conflict('--stamp');
-            stamp = v as string;
-            i += 2;
-            continue;
-        }
-        if (a === '--check') {
-            const v = argv[i + 1];
-            if (v === undefined) {
-                _argError('argument --check: expected one argument');
-            }
-            conflict('--check');
-            check = v as string;
-            i += 2;
-            continue;
-        }
-        if (a === '--stamp-all') {
-            conflict('--stamp-all');
-            stamp_all = true;
-            i += 1;
-            continue;
-        }
-        if (a === '--check-all') {
-            conflict('--check-all');
-            check_all = true;
-            i += 1;
-            continue;
-        }
-        // Unknown token: collect, defer error to after the required-group check.
-        extras.push(a);
-        i += 1;
-    }
-
-    // 4. Required mutex group must be satisfied (fires before the extras check).
-    if (firstSeen === null) {
-        _argError('one of the arguments --stamp --stamp-all --check --check-all is required');
-    }
-
-    // 5. Now report any unrecognized extras (group was satisfied).
-    if (extras.length) {
-        _argError(`unrecognized arguments: ${extras.join(' ')}`);
-    }
-
-    return { stamp, stamp_all, check, check_all };
-}
-
-function main(argv?: readonly string[]): number {
-    let args: Args;
-    try {
-        args = _parseArgs(argv ?? process.argv.slice(2));
-    } catch (exc) {
-        if (exc instanceof ArgError) {
-            return exc.code;
-        }
-        throw exc;
-    }
-
-    if (args.stamp !== null) {
-        return cmd_stamp(args.stamp);
-    }
-    if (args.check !== null) {
-        return cmd_check(args.check);
-    }
-    if (args.stamp_all) {
-        for (const p of _iter_analysis()) {
-            cmd_stamp(p);
-        }
-        return 0;
-    }
-    if (args.check_all) {
-        for (const p of _iter_analysis()) {
-            cmd_check(p);
-        }
-        return 0;
-    }
-    return 0;
-}
-
-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;
-    }
-    // A symlinked invocation (e.g. via an installed `.augment/` projection,
-    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
-    // import.meta.url is the resolved real path while argv[1] keeps the
-    // symlink path. Compare realpaths so the entry guard still fires
-    // (without this the CLI silently no-ops when run through a symlink).
-    try {
-        const here = fs.realpathSync(fileURLToPath(import.meta.url));
-        const argv = fs.realpathSync(path.resolve(process.argv[1]));
-        return here === argv;
-    } catch {
-        return false;
-    }
-}
-
-if (_isCliEntry() || process.argv[1] === _HERE) {
-    process.exitCode = main();
-}
-
-export {
-    REPO_ROOT,
-    ANALYSIS_DIR,
-    _setAnalysisDirForTest,
-    cmd_stamp,
-    cmd_check,
-    main,
-};

package/src/scripts/export_replay_corpus.ts

@@ -1,208 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Field-corpus exporter for router-telemetry replays
- * (road-to-token-proof-and-story Phase 2).
- *
- * Reads one or more `.agent-chat-history` JSONL logs (schema: one JSON object
- * per line; user turns are `{"t": "user", "text": "..."}`), extracts real
- * prompts, applies a built-in redaction pass, and emits a
- * `router_telemetry`-compatible corpus (`prompts:` entries with
- * `{id, text, command}`), so the three/four replay arms run on
- * consumer-shaped traffic instead of synthetic tasks.
- *
- * PRIVACY GATE (operator, non-optional): the built-in redaction is a
- * mechanical first pass — emails, home paths, key-shaped tokens, long hex,
- * URLs with credentials. The exported file MUST be human-reviewed under the
- * low-impact-corpus privacy floor BEFORE it is stored, committed, or fed to
- * any report that leaves the machine. The tool prints this reminder and
- * defaults to a `.local.yaml` output name so an unreviewed export cannot be
- * committed silently (gitignored pattern).
- *
- * Usage:
- *   ./scripts-run src/scripts/export_replay_corpus \
- *     --history agents/runtime/.agent-chat-history \
- *     [--history <other-repo>/agents/runtime/.agent-chat-history ...] \
- *     [--out internal/bench/corpora/field-prompts.local.yaml] \
- *     [--limit 200] [--min-chars 20]
- *
- * Exit codes: 0 written · 1 usage/file error.
- */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import process from 'node:process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const _HERE = fileURLToPath(import.meta.url);
-const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-const DEFAULT_OUT = path.join(REPO_ROOT, 'internal/bench/corpora/field-prompts.local.yaml');
-
-export interface FieldPrompt {
-  id: string;
-  text: string;
-  command: string | null;
-}
-
-const REDACTIONS: Array<[RegExp, string]> = [
-  // emails
-  [/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '<EMAIL>'],
-  // API-key-shaped tokens (sk-…, ghp_…, xox…, AKIA…, long base64-ish runs)
-  [/\b(?:sk-[A-Za-z0-9_-]{10,}|ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,}|xox[a-z]-[A-Za-z0-9-]{10,}|AKIA[A-Z0-9]{12,})\b/g, '<KEY>'],
-  // credentials embedded in URLs
-  [/(https?:\/\/)[^\s/@]+:[^\s/@]+@/g, '$1<CREDENTIALS>@'],
-  // absolute home paths (macOS/Linux)
-  [/(?:\/Users|\/home)\/[A-Za-z0-9._-]+/g, '<HOME>'],
-  // long hex blobs (hashes, tokens)
-  [/\b[a-f0-9]{32,}\b/gi, '<HEX>'],
-  // IPv4
-  [/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, '<IP>'],
-];
-
-/** Mechanical first-pass redaction — NOT a substitute for the operator review. */
-export function redact(text: string): string {
-  let out = text;
-  for (const [re, sub] of REDACTIONS) {
-    out = out.replace(re, sub);
-  }
-  return out;
-}
-
-/** Extract user prompts from one .agent-chat-history JSONL file. */
-export function extract_prompts(jsonlText: string, minChars: number): string[] {
-  const out: string[] = [];
-  for (const line of jsonlText.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    let obj: Record<string, unknown>;
-    try {
-      obj = JSON.parse(trimmed) as Record<string, unknown>;
-    } catch {
-      continue; // tolerate partial/corrupt lines — logs are append-only
-    }
-    if (obj['t'] !== 'user' || typeof obj['text'] !== 'string') continue;
-    const text = (obj['text'] as string).trim();
-    if (text.length < minChars) continue;
-    out.push(text);
-  }
-  return out;
-}
-
-/** First `/token` of a prompt that looks like a slash command. */
-export function detect_command(text: string): string | null {
-  const m = /^\/([a-z0-9:_-]+)/i.exec(text.trim());
-  return m ? `/${(m[1] as string).toLowerCase()}` : null;
-}
-
-/** Build the corpus entries: redacted, de-duplicated, capped. */
-export function build_corpus(rawPrompts: string[], limit: number): FieldPrompt[] {
-  const seen = new Set<string>();
-  const out: FieldPrompt[] = [];
-  for (const raw of rawPrompts) {
-    const text = redact(raw);
-    const key = text.slice(0, 200);
-    if (seen.has(key)) continue;
-    seen.add(key);
-    out.push({
-      id: `field-${String(out.length + 1).padStart(3, '0')}`,
-      text,
-      command: detect_command(text),
-    });
-    if (out.length >= limit) break;
-  }
-  return out;
-}
-
-function _yamlQuote(s: string): string {
-  return JSON.stringify(s); // JSON string is valid YAML double-quoted scalar
-}
-
-export function to_yaml(prompts: FieldPrompt[]): string {
-  const lines: string[] = [
-    '# Field replay corpus — exported by export_replay_corpus.',
-    '# PRIVACY: operator review REQUIRED before this file is stored/committed',
-    '# (low-impact-corpus privacy floor). Redaction here is a mechanical first',
-    '# pass only. Replay caveat: intent triggers are informational-only in',
-    '# router_telemetry — replay UNDERCOUNTS intent-triggered rule loads.',
-    'prompts:',
-  ];
-  for (const p of prompts) {
-    lines.push(`  - id: ${p.id}`);
-    lines.push(`    text: ${_yamlQuote(p.text)}`);
-    if (p.command) lines.push(`    command: ${_yamlQuote(p.command)}`);
-  }
-  return lines.join('\n') + '\n';
-}
-
-export function main(argv: string[]): number {
-  const histories: string[] = [];
-  let out = DEFAULT_OUT;
-  let limit = 200;
-  let minChars = 20;
-  for (let i = 0; i < argv.length; i += 1) {
-    const a = argv[i] as string;
-    if (a === '--history') histories.push(String(argv[(i += 1)] ?? ''));
-    else if (a === '--out') out = path.resolve(String(argv[(i += 1)] ?? ''));
-    else if (a === '--limit') limit = Number(argv[(i += 1)]);
-    else if (a === '--min-chars') minChars = Number(argv[(i += 1)]);
-    else if (a === '-h' || a === '--help') {
-      process.stdout.write(
-        'usage: export_replay_corpus --history <jsonl> [--history ...] [--out FILE] [--limit N] [--min-chars N]\n',
-      );
-      return 0;
-    } else {
-      process.stderr.write(`error: unknown argument: ${a}\n`);
-      return 1;
-    }
-  }
-  if (histories.length === 0 || !Number.isFinite(limit) || limit <= 0) {
-    process.stderr.write('error: at least one --history <path> is required\n');
-    return 1;
-  }
-  const raw: string[] = [];
-  for (const h of histories) {
-    let text: string;
-    try {
-      text = fs.readFileSync(h, 'utf-8');
-    } catch (e) {
-      process.stderr.write(`error: cannot read ${h}: ${(e as Error).message}\n`);
-      return 1;
-    }
-    raw.push(...extract_prompts(text, minChars));
-  }
-  const corpus = build_corpus(raw, limit);
-  fs.mkdirSync(path.dirname(out), { recursive: true });
-  fs.writeFileSync(out, to_yaml(corpus), 'utf-8');
-  process.stdout.write(
-    `wrote ${corpus.length} prompt(s) → ${path.relative(REPO_ROOT, out)}\n` +
-      '⚠️  PRIVACY GATE: operator review required before this corpus is stored,\n' +
-      '   committed, or used in any report (low-impact-corpus privacy floor).\n',
-  );
-  return 0;
-}
-
-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;
-    }
-    // A symlinked invocation (e.g. via an installed `.augment/` projection,
-    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
-    // import.meta.url is the resolved real path while argv[1] keeps the
-    // symlink path. Compare realpaths so the entry guard still fires
-    // (without this the CLI silently no-ops when run through a symlink).
-    try {
-        const here = fs.realpathSync(fileURLToPath(import.meta.url));
-        const argv = fs.realpathSync(path.resolve(process.argv[1]));
-        return here === argv;
-    } catch {
-        return false;
-    }
-}
-
-const _IS_MAIN =
-  _isCliEntry();
-if (_IS_MAIN) {
-  process.exit(main(process.argv.slice(2)));
-}