@event4u/agent-config 7.4.0 → 8.0.0

package/src/scripts/mine_missing_guardrails.ts

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * A4 — Ablation-mining (learning-loop #1). Correlate rule *absence* with failure
+ * across INDEPENDENT runs (distinct `work_id`) and surface *missing-guardrail*
+ * candidates for the human to promote via `learning-to-rule-or-skill`.
+ *
+ * Read-only over `audit-log-v1` (`agents/runtime/state/audit/*.jsonl`). Raw
+ * counts only — NO auto-promotion, NO mutation. Correlation, not causation:
+ * every candidate carries the confounding caveat. A candidate is a *question*
+ * for a human, never an answer.
+ *
+ * Signal (per phase P, rule R):
+ *   - `success_with_rule`     = success lines in P where R ∈ rules_applied
+ *   - `failure_without_rule`  = blocked/error lines in P where R ∉ rules_applied
+ *   R is a candidate when its absence co-occurs with failure often enough
+ *   (`failure_without_rule` ≥ --min-count, over ≥2 distinct failing work_ids)
+ *   AND R is otherwise a success-associated rule in P (`success_with_rule` ≥ 1).
+ *
+ * Exit 0 always (an empty audit log is a valid state, not an error).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+export const DEFAULT_AUDIT_DIR = path.join(ROOT, 'agents', 'runtime', 'state', 'audit');
+export const SCHEMA_VERSION = 1;
+const FAILURE_OUTCOMES = new Set(['blocked', 'error']);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Rec = Record<string, any>;
+
+/** Read audit-log-v1 phase records from `*.jsonl` (or one `<month>.jsonl`). */
+export function loadRecords(auditDir: string, month: string | null = null): Rec[] {
+    const out: Rec[] = [];
+    let files: string[];
+    if (month) {
+        files = [path.join(auditDir, `${month}.jsonl`)];
+    } else {
+        let names: string[] = [];
+        try {
+            names = fs.readdirSync(auditDir);
+        } catch {
+            return out;
+        }
+        files = names.filter((n) => n.endsWith('.jsonl')).sort().map((n) => path.join(auditDir, n));
+    }
+    for (const p of files) {
+        let text: string;
+        try {
+            text = fs.readFileSync(p, 'utf-8');
+        } catch {
+            continue;
+        }
+        for (const raw of text.split('\n')) {
+            const line = raw.trim();
+            if (!line) continue;
+            let rec: Rec;
+            try {
+                rec = JSON.parse(line) as Rec;
+            } catch {
+                continue;
+            }
+            if (rec.schema_version !== SCHEMA_VERSION) continue;
+            if (rec.type === 'supersede' || rec.type === 'note') continue;
+            if (typeof rec.phase !== 'string' || typeof rec.outcome !== 'string') continue;
+            if (!Array.isArray(rec.rules_applied)) continue;
+            out.push(rec);
+        }
+    }
+    return out;
+}
+
+export interface Candidate {
+    phase: string;
+    rule: string;
+    success_with_rule: number;
+    failure_without_rule: number;
+    failure_work_ids: string[];
+    success_without_rule: number;
+    failure_with_rule: number;
+}
+
+export function mineCandidates(records: Rec[], minCount: number): Candidate[] {
+    const phases = new Set<string>();
+    const rules = new Set<string>();
+    for (const r of records) {
+        phases.add(r.phase as string);
+        for (const rule of r.rules_applied as string[]) rules.add(rule);
+    }
+    const out: Candidate[] = [];
+    for (const phase of [...phases].sort()) {
+        const inPhase = records.filter((r) => r.phase === phase);
+        for (const rule of [...rules].sort()) {
+            let succWith = 0;
+            let succWithout = 0;
+            let failWith = 0;
+            const failWithoutIds = new Set<string>();
+            for (const r of inPhase) {
+                const has = (r.rules_applied as string[]).includes(rule);
+                const isSuccess = r.outcome === 'success';
+                const isFailure = FAILURE_OUTCOMES.has(r.outcome as string);
+                if (isSuccess && has) succWith += 1;
+                else if (isSuccess && !has) succWithout += 1;
+                else if (isFailure && has) failWith += 1;
+                else if (isFailure && !has) {
+                    failWithoutIds.add(typeof r.work_id === 'string' ? r.work_id : (r.id as string));
+                }
+            }
+            const failWithout = failWithoutIds.size;
+            // Candidate: absence co-occurs with failure across ≥2 distinct runs,
+            // and the rule is otherwise success-associated in this phase.
+            if (failWithout >= minCount && failWithout >= 2 && succWith >= 1) {
+                out.push({
+                    phase,
+                    rule,
+                    success_with_rule: succWith,
+                    failure_without_rule: failWithout,
+                    failure_work_ids: [...failWithoutIds].sort(),
+                    success_without_rule: succWithout,
+                    failure_with_rule: failWith,
+                });
+            }
+        }
+    }
+    // Strongest signal first: most distinct failing runs, then most successes-with.
+    out.sort(
+        (a, b) =>
+            b.failure_without_rule - a.failure_without_rule ||
+            b.success_with_rule - a.success_with_rule ||
+            (a.phase < b.phase ? -1 : a.phase > b.phase ? 1 : a.rule < b.rule ? -1 : 1),
+    );
+    return out;
+}
+
+const CONFOUND_NOTE =
+    'Correlation, NOT causation. A rule absent from failing runs may reflect the ' +
+    'task type or phase shape, not a missing guardrail. Low N inflates noise. ' +
+    'Each candidate is a question for a human — promote (or reject) only via ' +
+    'learning-to-rule-or-skill. Never auto-add a rule from this output.';
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    let auditDir = DEFAULT_AUDIT_DIR;
+    let month: string | null = null;
+    let minCount = 2;
+    let asJson = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--audit-dir') auditDir = argv[++i] ?? auditDir;
+        else if (a === '--month') month = argv[++i] ?? null;
+        else if (a === '--min-count') minCount = parseInt(argv[++i] ?? '2', 10) || 2;
+        else if (a === '--json') asJson = true;
+    }
+    const records = loadRecords(auditDir, month);
+    const candidates = mineCandidates(records, minCount);
+    if (asJson) {
+        process.stdout.write(
+            JSON.stringify(
+                { schema_version: SCHEMA_VERSION, records: records.length, min_count: minCount, confounding: CONFOUND_NOTE, candidates },
+                null,
+                2,
+            ) + '\n',
+        );
+        return 0;
+    }
+    if (records.length === 0) {
+        process.stdout.write('missing-guardrails: no audit-log-v1 records found (nothing to mine).\n');
+        return 0;
+    }
+    if (candidates.length === 0) {
+        process.stdout.write(`missing-guardrails: ${records.length} record(s), 0 candidates (min-count ${minCount}).\n`);
+        return 0;
+    }
+    process.stdout.write(`missing-guardrails: ${candidates.length} candidate(s) from ${records.length} record(s):\n\n`);
+    for (const c of candidates) {
+        process.stdout.write(
+            `  [${c.phase}] rule '${c.rule}' — absent in ${c.failure_without_rule} failing run(s), ` +
+                `present in ${c.success_with_rule} success(es). ` +
+                `(fail-with-rule ${c.failure_with_rule}, success-without ${c.success_without_rule})\n`,
+        );
+    }
+    process.stdout.write(`\n⚠️  ${CONFOUND_NOTE}\n`);
+    return 0;
+}
+
+const _isCli =
+    process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCli) process.exit(main());

package/src/scripts/parity/phase_gate.ts

@@ -2,7 +2,7 @@
 /**
  * phase_gate.ts — Python→TypeScript migration phase gate.
  *
- * Phase 1 Step 10 of `agents/roadmaps/road-to-typescript-only-scripts.md`.
+ * Phase 1 Step 10 of `agents/roadmaps/archive/road-to-typescript-only-scripts.md`.
  *
  * Reads `src/scripts/parity/phase-manifest.json` and enforces:
  *

package/src/scripts/parity/replay.ts

@@ -196,6 +196,27 @@ export function runReplay(options: ReplayOptions): ReplayReport {
     const tsScript = `${scriptBase}.ts`;
     const tsxCommand = resolveTsxCommand(cwd);
 
+    // Local python-skip guard (teardown D2): the replay harness is migration
+    // tooling — it byte-compares a live `python3 <script>.py` run against the
+    // tsx twin, which requires BOTH the runtime and the original `.py` to
+    // exist. Post-teardown neither holds; fail fast with a clear message
+    // instead of a spawn error, so the python-free-env shim retirement does
+    // not depend on porting this harness to a frozen-golden design.
+    if (spawnSync("python3", ["--version"], { encoding: "utf8" }).status !== 0) {
+        return {
+            script: options.script,
+            status: "fail",
+            cases: options.caseDirs.map((caseDir) => ({
+                caseDir,
+                diffs: [],
+                error:
+                    "python3 unavailable — the golden-replay harness needs the pre-teardown " +
+                    "python runtime plus the original .py; freeze the baseline to a TS golden " +
+                    "instead (teardown D2 medium-term).",
+            })),
+        };
+    }
+
     const cases: CaseResult[] = [];
     for (const caseDirRaw of options.caseDirs) {
         const caseDir = path.resolve(cwd, caseDirRaw);

package/src/scripts/project_thin_rules.ts

@@ -68,6 +68,70 @@ export function kernel_ids(): Set<string> {
     return new Set();
 }
 
+/**
+ * id → workspaces for every non-kernel router entry (router.json schema v2,
+ * road-to-request-scoped-rule-load Phase 1). Rules absent from the map (or
+ * with an empty list) fail safe: they stay in scope.
+ */
+export function rule_workspaces_map(): Map<string, string[]> {
+    const data = JSON.parse(fs.readFileSync(ROUTER, 'utf-8')) as Record<string, unknown>;
+    const map = new Map<string, string[]>();
+    for (const tier of ['tier_1', 'tier_2']) {
+        const entries = data[tier];
+        if (!Array.isArray(entries)) continue;
+        for (const e of entries) {
+            const obj = e as Record<string, unknown>;
+            const ws = Array.isArray(obj.workspaces) ? obj.workspaces.map((w) => String(w)) : [];
+            map.set(String(obj.id), ws);
+        }
+    }
+    return map;
+}
+
+/**
+ * Whether a rule id survives a workspace scope. Kernel always survives;
+ * `scope === null` = legacy-all. An out-of-scope non-kernel rule is dropped
+ * entirely — neither body nor pointer line (the pointer floor shrinks with
+ * consumer scoping).
+ */
+export function id_in_scope(
+    rule_id: string,
+    scope: readonly string[] | null,
+    kernel: ReadonlySet<string>,
+    wsMap: ReadonlyMap<string, string[]>,
+    fallback_ws: readonly string[] = [],
+): boolean {
+    if (scope === null || kernel.has(rule_id)) {
+        return true;
+    }
+    // Router map first (schema v2); `type: manual` rules are reference-only
+    // and never emitted to the router — their frontmatter is the fallback.
+    const ws = wsMap.get(rule_id) ?? fallback_ws;
+    if (ws.length === 0) {
+        return true; // untagged / unknown → fail safe
+    }
+    return ws.some((w) => scope.includes(w));
+}
+
+/** `workspaces:` list parsed straight from a rule file's frontmatter. */
+export function fm_workspaces(text: string): string[] {
+    const [fm] = split_frontmatter(text);
+    // Flow style: `workspaces: [a, b, c]`
+    const flow = /^workspaces:[ \t]*\[([^\]]*)\]/m.exec(fm);
+    if (flow) {
+        return (flow[1] as string)
+            .split(',')
+            .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+            .filter((s) => s.length > 0);
+    }
+    // Block style; tolerate the list being the LAST frontmatter key.
+    const m = /^workspaces:[ \t]*\n((?:[ \t]+-[ \t]+.*(?:\n|$))+)/m.exec(fm);
+    if (!m) {
+        return [];
+    }
+    return [...(m[1] as string).matchAll(/-[ \t]+(\S+)/g)].map((x) => x[1] as string);
+}
+
 /** Return [frontmatter_including_fences, body]. Empty fm if none. */
 export function split_frontmatter(text: string): [string, string] {
     if (text.startsWith('---\n')) {
@@ -123,12 +187,19 @@ export function thin_entry(rule_id: string, text: string): string {
 }
 
 /** Map {filename: thin_or_full_text} for every rule. Kernel stays full. */
-export function build_thin(rules_dir: string = RULES_SOURCE): Map<string, string> {
+export function build_thin(
+    rules_dir: string = RULES_SOURCE,
+    scope: readonly string[] | null = null,
+): Map<string, string> {
     const kernel = kernel_ids();
+    const wsMap = scope !== null ? rule_workspaces_map() : new Map<string, string[]>();
     const out = new Map<string, string>();
     for (const p of _globSortedMd(rules_dir)) {
         const text = fs.readFileSync(p, 'utf-8');
         const stem = path.basename(p).replace(/\.md$/, '');
+        if (!id_in_scope(stem, scope, kernel, wsMap, fm_workspaces(text))) {
+            continue; // out of workspace scope — no body, no pointer line
+        }
         out.set(path.basename(p), kernel.has(stem) ? text : thin_entry(stem, text));
     }
     return out;
@@ -163,12 +234,24 @@ function _python_round1(x: number): number {
     return r / 10;
 }
 
-/** Eager vs thin token footprint for the rule layer. */
-export function measure(rules_dir: string = RULES_SOURCE): ThinMeasure {
+/** Eager vs thin token footprint for the rule layer (scope applies to both arms). */
+export function measure(
+    rules_dir: string = RULES_SOURCE,
+    scope: readonly string[] | null = null,
+): ThinMeasure {
     const kernel = kernel_ids();
-    const mdPaths = _globSortedMd(rules_dir);
+    const wsMap = scope !== null ? rule_workspaces_map() : new Map<string, string[]>();
+    const mdPaths = _globSortedMd(rules_dir).filter((p) =>
+        id_in_scope(
+            path.basename(p).replace(/\.md$/, ''),
+            scope,
+            kernel,
+            wsMap,
+            fm_workspaces(fs.readFileSync(p, 'utf-8')),
+        ),
+    );
     const eager_blob = mdPaths.map((p) => fs.readFileSync(p, 'utf-8')).join('');
-    const thin_blob = [...build_thin(rules_dir).values()].join('');
+    const thin_blob = [...build_thin(rules_dir, scope).values()].join('');
     const eager = token_count.measure(eager_blob);
     const thin = token_count.measure(thin_blob);
     const n = mdPaths.length;
@@ -198,9 +281,13 @@ export function measure(rules_dir: string = RULES_SOURCE): ThinMeasure {
 }
 
 /** Write thin rule files to `out_dir`; return the count written. */
-export function write_thin(out_dir: string, rules_dir: string = RULES_SOURCE): number {
+export function write_thin(
+    out_dir: string,
+    rules_dir: string = RULES_SOURCE,
+    scope: readonly string[] | null = null,
+): number {
     fs.mkdirSync(out_dir, { recursive: true });
-    const files = build_thin(rules_dir);
+    const files = build_thin(rules_dir, scope);
     for (const [name, text] of files) {
         fs.writeFileSync(path.join(out_dir, name), text, 'utf-8');
     }
@@ -293,22 +380,26 @@ interface ParsedArgs {
     measure: boolean;
     out: string | null;
     json: boolean;
+    workspaces: string[] | null;
 }
 
 // argparse `prog` defaults to basename(sys.argv[0]) → `project_thin_rules.py`.
-const _USAGE = 'usage: project_thin_rules.py [-h] [--measure] [--out OUT] [--json]\n';
+const _USAGE =
+    'usage: project_thin_rules.py [-h] [--measure] [--out OUT] [--json] [--workspaces WS]\n';
 
-// Full `-h` help block, byte-identical to argparse's rendering.
+// Full `-h` help block.
 const _HELP =
     _USAGE +
     '\n' +
     'Thin-projection of the rule layer (lean-initial-context build-out, Phase 3.1).\n' +
     '\n' +
     'optional arguments:\n' +
-    '  -h, --help  show this help message and exit\n' +
-    '  --measure   print the eager-vs-thin token delta\n' +
-    '  --out OUT   write thin rule files to this dir\n' +
-    '  --json\n';
+    '  -h, --help       show this help message and exit\n' +
+    '  --measure        print the eager-vs-thin token delta\n' +
+    '  --out OUT        write thin rule files to this dir\n' +
+    '  --json\n' +
+    '  --workspaces WS  comma-separated workspace scope (router.json v2 fields);\n' +
+    '                   kernel always survives, out-of-scope rules drop entirely\n';
 
 function _argError(msg: string): never {
     process.stderr.write(_USAGE);
@@ -317,7 +408,7 @@ function _argError(msg: string): never {
 }
 
 function parse_args(argv: string[]): ParsedArgs {
-    const out: ParsedArgs = { measure: false, out: null, json: false };
+    const out: ParsedArgs = { measure: false, out: null, json: false, workspaces: null };
     for (let i = 0; i < argv.length; i += 1) {
         const a = argv[i] as string;
         if (a === '-h' || a === '--help') {
@@ -336,6 +427,19 @@ function parse_args(argv: string[]): ParsedArgs {
             i += 1;
         } else if (a.startsWith('--out=')) {
             out.out = a.slice('--out='.length);
+        } else if (a === '--workspaces') {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                _argError('argument --workspaces: expected one argument');
+            }
+            out.workspaces = next.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+            i += 1;
+        } else if (a.startsWith('--workspaces=')) {
+            out.workspaces = a
+                .slice('--workspaces='.length)
+                .split(',')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
         } else {
             _argError(`unrecognized arguments: ${a}`);
         }
@@ -357,12 +461,12 @@ export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     if (args.out !== null) {
-        const n = write_thin(args.out);
+        const n = write_thin(args.out, RULES_SOURCE, args.workspaces);
         process.stdout.write(`wrote ${n} thin rule files → ${args.out}\n`);
         return 0;
     }
 
-    const m = measure();
+    const m = measure(RULES_SOURCE, args.workspaces);
     if (args.json) {
         // `saved_pct` is a Python float (round(..., 1)); wrap it so an
         // integer-valued result still renders as `N.0` (json.dumps parity).

package/src/scripts/release.ts

@@ -151,6 +151,18 @@ class CalledProcessError extends Error {
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const PACKAGE_JSON = path.join(REPO_ROOT, 'package.json');
 const MARKETPLACE_JSON = path.join(REPO_ROOT, '.claude-plugin', 'marketplace.json');
+// Source-of-truth project-settings template. Carries an `agent_config_version`
+// pin that check_template_pin_drift requires to equal package.json.version. We
+// bump the src twin here; `task release-prepare` (run right after the bump)
+// regenerates the dist/agent-src/ twin from it.
+const PROJECT_TEMPLATE = path.join(
+    REPO_ROOT,
+    'src',
+    'agent-src',
+    'templates',
+    'agents',
+    'agent-project-settings.example.yml',
+);
 const CHANGELOG = path.join(REPO_ROOT, 'CHANGELOG.md');
 const MAIN_BRANCH = 'main';
 const REMOTE = 'origin';
@@ -879,6 +891,29 @@ function set_marketplace_version(p: string, version: string): void {
     fs.writeFileSync(p, jsonDumpsIndent(data, 2) + '\n', 'utf-8');
 }
 
+function set_template_pin(p: string, version: string): void {
+    // Rewrite the single `agent_config_version:` line in place, preserving the
+    // rest of the YAML byte-for-byte. Quoted value to match the existing pin
+    // style and check_template_pin_drift's tolerant parse.
+    const text = fs.readFileSync(p, 'utf-8');
+    const lines = text.split('\n');
+    let found = false;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (/^\s*agent_config_version\s*:/.test(lines[i]!)) {
+            lines[i] = lines[i]!.replace(
+                /^(\s*agent_config_version\s*:\s*).*/,
+                `$1"${version}"`,
+            );
+            found = true;
+            break;
+        }
+    }
+    if (!found) {
+        die(`set_template_pin: no \`agent_config_version:\` line in ${p}`);
+    }
+    fs.writeFileSync(p, lines.join('\n'), 'utf-8');
+}
+
 // ─── preflight ────────────────────────────────────────────────────────────────
 
 /**
@@ -982,6 +1017,7 @@ function print_preview(plan: Plan): void {
     process.stdout.write('Files to change:\n');
     process.stdout.write(`  · ${path.relative(REPO_ROOT, PACKAGE_JSON)}\n`);
     process.stdout.write(`  · ${path.relative(REPO_ROOT, MARKETPLACE_JSON)}\n`);
+    process.stdout.write(`  · ${path.relative(REPO_ROOT, PROJECT_TEMPLATE)}\n`);
     process.stdout.write(`  · ${path.relative(REPO_ROOT, CHANGELOG)}\n`);
     process.stdout.write('  · regenerated derived files via `task release-prepare`\n');
     process.stdout.write(
@@ -1204,9 +1240,10 @@ function execute(
         if (resume && current_pkg === plan.target) {
             _step(2, total, `Files already at ${plan.target} — skip bump`);
         } else {
-            _step(2, total, 'Bump package.json + marketplace.json, prepend CHANGELOG');
+            _step(2, total, 'Bump package.json + marketplace.json + template pin, prepend CHANGELOG');
             set_package_version(PACKAGE_JSON, plan.target);
             set_marketplace_version(MARKETPLACE_JSON, plan.target);
+            set_template_pin(PROJECT_TEMPLATE, plan.target);
             prepend_changelog(CHANGELOG, plan.changelog_entry);
         }
 
@@ -1727,6 +1764,7 @@ export {
     prepend_changelog,
     set_package_version,
     set_marketplace_version,
+    set_template_pin,
     resolve_bump,
     _detect_in_flight_target,
     print_preview,