@event4u/agent-config 7.5.0 → 8.1.0

package/src/scripts/_lib/knowledge_events.ts

@@ -0,0 +1,193 @@
+/**
+ * Typed observation-event schema — road-to-knowledge-system Phase 5
+ * (living-context capture). During normal task work, an agent that
+ * observes one of these four conditions appends an event to the
+ * gitignored `agents/knowledge/intake/events-YYYY-MM.jsonl` stream —
+ * never a tracked page mid-task. Consolidation (`/team-knowledge
+ * consolidate`) reads this stream and proposes tracked-page
+ * creates/updates as a reviewable batch.
+ *
+ * Four event types, one per capture trigger:
+ *   - convention_detected — a coding standard/pattern observed with evidence
+ *   - mistake_made        — an error traced to a followed (possibly stale) context
+ *   - api_shape_learned   — a request/response shape observed on a real call
+ *   - context_stale       — observed reality contradicts a documented page
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface ConventionDetectedEvent {
+    type: 'convention_detected';
+    ts: string; // ISO-8601
+    pattern: string;
+    evidence: string[]; // file:line references
+    sampleSize: number;
+    scope: 'project' | 'global';
+}
+
+export interface MistakeMadeEvent {
+    type: 'mistake_made';
+    ts: string;
+    errorCategory: string;
+    contextSource: string | null; // which knowledge page (if any) was followed
+    correction: string;
+    recurrenceKey: string;
+}
+
+export interface ApiShapeLearnedEvent {
+    type: 'api_shape_learned';
+    ts: string;
+    endpoint: string;
+    method: string;
+    requestSchema: unknown;
+    responseSchema: unknown;
+}
+
+export interface ContextStaleEvent {
+    type: 'context_stale';
+    ts: string;
+    pagePath: string;
+    field: string;
+    expected: unknown;
+    actual: unknown;
+    evidence: string;
+}
+
+export type KnowledgeEvent = ConventionDetectedEvent | MistakeMadeEvent | ApiShapeLearnedEvent | ContextStaleEvent;
+
+export type ValidationResult = { valid: true; event: KnowledgeEvent } | { valid: false; errors: string[] };
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function isNonEmptyString(v: unknown): v is string {
+    return typeof v === 'string' && v.length > 0;
+}
+
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+
+/** Validates the shape for the declared `type`. Does not require the event to be well-formed JSON — call after JSON.parse. */
+export function validateEvent(raw: unknown): ValidationResult {
+    const errors: string[] = [];
+    if (!isPlainObject(raw)) {
+        return { valid: false, errors: ['event must be a JSON object'] };
+    }
+    if (!isNonEmptyString(raw.ts) || !ISO_RE.test(raw.ts)) {
+        errors.push('ts must be an ISO-8601 timestamp string');
+    }
+
+    switch (raw.type) {
+        case 'convention_detected': {
+            if (!isNonEmptyString(raw.pattern)) errors.push('pattern is required');
+            if (!Array.isArray(raw.evidence) || raw.evidence.length === 0 || !raw.evidence.every((e) => typeof e === 'string')) {
+                errors.push('evidence must be a non-empty string array');
+            }
+            if (typeof raw.sampleSize !== 'number' || raw.sampleSize < 1) errors.push('sampleSize must be a positive number');
+            if (raw.scope !== 'project' && raw.scope !== 'global') errors.push('scope must be "project" or "global"');
+            break;
+        }
+        case 'mistake_made': {
+            if (!isNonEmptyString(raw.errorCategory)) errors.push('errorCategory is required');
+            if (raw.contextSource !== null && !isNonEmptyString(raw.contextSource)) {
+                errors.push('contextSource must be a string or null');
+            }
+            if (!isNonEmptyString(raw.correction)) errors.push('correction is required');
+            if (!isNonEmptyString(raw.recurrenceKey)) errors.push('recurrenceKey is required');
+            break;
+        }
+        case 'api_shape_learned': {
+            if (!isNonEmptyString(raw.endpoint)) errors.push('endpoint is required');
+            if (!isNonEmptyString(raw.method)) errors.push('method is required');
+            if (!('requestSchema' in raw)) errors.push('requestSchema is required');
+            if (!('responseSchema' in raw)) errors.push('responseSchema is required');
+            break;
+        }
+        case 'context_stale': {
+            if (!isNonEmptyString(raw.pagePath)) errors.push('pagePath is required');
+            if (!isNonEmptyString(raw.field)) errors.push('field is required');
+            if (!('expected' in raw)) errors.push('expected is required');
+            if (!('actual' in raw)) errors.push('actual is required');
+            if (!isNonEmptyString(raw.evidence)) errors.push('evidence is required');
+            break;
+        }
+        default:
+            errors.push(
+                `unknown type "${String(raw.type)}" (expected one of convention_detected|mistake_made|api_shape_learned|context_stale)`,
+            );
+    }
+
+    if (errors.length > 0) {
+        return { valid: false, errors };
+    }
+    return { valid: true, event: raw as unknown as KnowledgeEvent };
+}
+
+const INTAKE_DIR = path.join('agents', 'knowledge', 'intake');
+
+/** sorted(events-*.jsonl) under the intake dir — absolute-or-relative per `dir`. */
+export function intakeFiles(dir: string = INTAKE_DIR): string[] {
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir);
+    } catch {
+        return [];
+    }
+    return names
+        .filter((n) => n.startsWith('events-') && n.endsWith('.jsonl'))
+        .sort()
+        .map((n) => path.join(dir, n));
+}
+
+function monthlyFile(dir: string, ts: string): string {
+    const ym = ts.slice(0, 7); // "YYYY-MM"
+    return path.join(dir, `events-${ym}.jsonl`);
+}
+
+/** Appends a validated event as one JSONL line to the current month's intake file. Throws if the event fails validation. */
+export function appendEvent(event: KnowledgeEvent, dir: string = INTAKE_DIR): void {
+    const result = validateEvent(event);
+    if (!result.valid) {
+        throw new Error(`invalid knowledge event: ${result.errors.join('; ')}`);
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    const file = monthlyFile(dir, event.ts);
+    fs.appendFileSync(file, JSON.stringify(event) + '\n', 'utf8');
+}
+
+/** Deletes every `events-*.jsonl` file under `dir` — called by `/team-knowledge consolidate` once a batch has been proposed and approved. All-or-nothing by design: consolidation processes the FULL pending backlog in one pass, so there is no partial-consumption state to track. No-op (never throws) if the dir does not exist or is already empty. */
+export function clearAllEvents(dir: string = INTAKE_DIR): void {
+    for (const file of intakeFiles(dir)) {
+        try {
+            fs.unlinkSync(file);
+        } catch {
+            // Already gone — fine.
+        }
+    }
+}
+
+/** Reads and validates every line across all intake files under `dir`. Malformed JSON lines are skipped (not thrown), matching the tolerant-reader convention used by memory_signal.ts's own intake scan. */
+export function readAllEvents(dir: string = INTAKE_DIR): KnowledgeEvent[] {
+    const out: KnowledgeEvent[] = [];
+    for (const file of intakeFiles(dir)) {
+        let text: string;
+        try {
+            text = fs.readFileSync(file, 'utf8');
+        } catch {
+            continue;
+        }
+        for (const rawLine of text.split('\n')) {
+            const line = rawLine.trim();
+            if (!line) continue;
+            let parsed: unknown;
+            try {
+                parsed = JSON.parse(line);
+            } catch {
+                continue;
+            }
+            const result = validateEvent(parsed);
+            if (result.valid) out.push(result.event);
+        }
+    }
+    return out;
+}

package/src/scripts/_lib/subagent_steering.ts

@@ -1,9 +1,9 @@
 /**
  * Subagent steering & guardrails (Phase 5).
  *
- * Pure, no-I/O. The guardrails that keep auto-dispatch from becoming a token
- * sink: the N=3 per-target budget, the kill-switch, and the rollback
- * guardrail-threshold checks. Contract:
+ * Pure helpers (isLayerDisabled, budgetHalt, breachedGuardrails) + one
+ * I/O reader (readOrchestrationMetrics) that aggregates telemetry from
+ * the audit-log-v1 JSONL to feed into breachedGuardrails. Contract:
  * `src/agent-src/contexts/execution/subagent-steering.md`.
  *
  * Automatic cohort-level disable is OUT OF SCOPE — a config package runs no
@@ -41,6 +41,53 @@ export function budgetHalt(consecutiveFailures: number): boolean {
     return consecutiveFailures >= MAX_ATTEMPTS_PER_TARGET;
 }
 
+/**
+ * Failure-type stop (road-to-flow-learnings Phase 2) — an APPLICATION of the
+ * N=3 budget at subagent-type granularity, never a new mechanism: two
+ * consecutive verification-failed returns from the same subagent type plus
+ * the escalation step exhaust the three-attempt budget. When this fires the
+ * orchestrator stops dispatching that type for the session, surfaces both
+ * failures to the human, and runs the remaining slices in-session. There is
+ * still NO automatic cohort-disable — the Iron Law above stands unchanged.
+ */
+export const MAX_CONSECUTIVE_TYPE_FAILURES = MAX_ATTEMPTS_PER_TARGET - 1;
+
+/** True when a subagent type has exhausted its in-session dispatch budget. */
+export function typeStop(consecutiveVerificationFailures: number): boolean {
+    return consecutiveVerificationFailures >= MAX_CONSECUTIVE_TYPE_FAILURES;
+}
+
+/** Decision returned by {@link sliceDispatchAllowed}. */
+export interface SliceDispatchDecision {
+    readonly allowed: boolean;
+    readonly reason: string;
+}
+
+/**
+ * Ordered-slice dependency gate (road-to-flow-learnings Phase 2) — makes the
+ * `do-in-steps` contract deterministic: a slice that declares a parent MUST
+ * NOT dispatch before the parent's return has been verified by the
+ * orchestrator. Slices without a declared parent (roots / independent
+ * slices) always pass this gate.
+ */
+export function sliceDispatchAllowed(
+    declaredParent: string | null,
+    verifiedReturns: ReadonlySet<string>,
+): SliceDispatchDecision {
+    if (declaredParent === null || declaredParent.length === 0) {
+        return { allowed: true, reason: 'no declared parent — root or independent slice' };
+    }
+    if (verifiedReturns.has(declaredParent)) {
+        return { allowed: true, reason: `parent '${declaredParent}' has a verified return` };
+    }
+    return {
+        allowed: false,
+        reason:
+            `parent '${declaredParent}' has no verified return in session state — ` +
+            'verify (or revise) the parent before dispatching this slice',
+    };
+}
+
 export interface GuardrailMetrics {
     /** Observed token spend / single-agent baseline (e.g. 2.4 = 2.4x). */
     token_ratio: number;
@@ -62,3 +109,68 @@ export function breachedGuardrails(m: GuardrailMetrics): string[] {
     if (m.user_override_rate > GUARDRAILS.user_override_rate) breached.push('user_override');
     return breached;
 }
+
+/** Raw orchestration entry parsed from an audit-log-v1 JSONL line. */
+export interface OrchEntry {
+    task_size_estimate: number;
+    spawn_count: number;
+    token_delta: number;
+    outcome: string;
+    verify_mode: string;
+}
+
+/**
+ * Read orchestration telemetry lines from audit-log JSONL and aggregate into
+ * GuardrailMetrics. Uses dependency-injected line reader for testability.
+ *
+ * token_ratio approximation: (task_size_estimate + token_delta) /
+ * task_size_estimate (proxy for orchestrated/single-agent ratio; 1.0 when
+ * task_size_estimate == 0). Positive token_delta = orchestration cost more.
+ *
+ * user_override_rate cannot be measured from telemetry alone — returns 0.
+ */
+export function readOrchestrationMetrics(
+    lines: string[],
+): GuardrailMetrics {
+    const entries: OrchEntry[] = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+            const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+            if (parsed['input_kind'] !== 'orchestration') continue;
+            const orch = parsed['orchestration'] as Record<string, unknown> | undefined;
+            if (!orch) continue;
+            entries.push({
+                task_size_estimate: Number(orch['task_size_estimate'] ?? 0),
+                spawn_count: Number(orch['spawn_count'] ?? 0),
+                token_delta: Number(orch['token_delta'] ?? 0),
+                outcome: String(orch['outcome'] ?? ''),
+                verify_mode: String(orch['verify_mode'] ?? ''),
+            });
+        } catch {
+            // skip malformed lines
+        }
+    }
+
+    if (entries.length === 0) {
+        return { token_ratio: 1, spawn_failure_rate: 0, verify_skip_rate: 0, user_override_rate: 0 };
+    }
+
+    const token_ratios = entries.map(e =>
+        e.task_size_estimate > 0
+            ? (e.task_size_estimate + e.token_delta) / e.task_size_estimate
+            : 1,
+    );
+    const token_ratio = token_ratios.reduce((a, b) => a + b, 0) / token_ratios.length;
+
+    const failures = entries.filter(e => e.outcome === 'BLOCKED' || e.outcome === 'killed').length;
+    const verify_skips = entries.filter(e => e.verify_mode === 'none').length;
+
+    return {
+        token_ratio,
+        spawn_failure_rate: failures / entries.length,
+        verify_skip_rate: verify_skips / entries.length,
+        user_override_rate: 0, // cannot measure from telemetry alone
+    };
+}

package/src/scripts/_lib/text_similarity.ts

@@ -0,0 +1,75 @@
+/**
+ * Token-based Jaccard similarity — the dedup primitive for the
+ * road-to-knowledge-system capture-hygiene layer (Phase 2).
+ *
+ * Deterministic, no embeddings, no network. Thresholds per the
+ * 2026-07-05 council verdict (AutoSci dedup discipline, adapted):
+ *   >= MERGE_THRESHOLD  → treat as a duplicate, suggest the matched entry
+ *   >= WARN_THRESHOLD   → surface the nearest match, let the human decide
+ *   below WARN_THRESHOLD → no conflict, proceed to create
+ *
+ * Deliberately does NOT touch `memory_signal.ts` — that script is a
+ * byte-faithful parity twin of its retired Python original ("no
+ * behaviour changes" is a load-bearing contract of that file). This
+ * module is consumed as an ADDITIONAL, advisory check layered on top,
+ * from `check_memory_similarity.ts` and later the knowledge-page
+ * consolidation flow (Phase 5).
+ */
+
+export const MERGE_THRESHOLD = 0.8;
+export const WARN_THRESHOLD = 0.4;
+
+export type SimilarityClass = 'merge' | 'warn' | 'create';
+
+const TOKEN_RE = /[a-z0-9]+/g;
+
+/** Lowercase, split on non-alphanumeric runs, drop empties. Order-independent by design (Jaccard is set-based). */
+export function tokenize(text: string): Set<string> {
+    const tokens = (text.toLowerCase().match(TOKEN_RE) ?? []).filter((t) => t.length > 0);
+    return new Set(tokens);
+}
+
+/** Jaccard(A, B) = |A ∩ B| / |A ∪ B|. Two empty inputs are defined as identical (1.0); one empty vs. non-empty is 0. */
+export function jaccardSimilarity(a: string, b: string): number {
+    const setA = tokenize(a);
+    const setB = tokenize(b);
+    if (setA.size === 0 && setB.size === 0) return 1.0;
+    if (setA.size === 0 || setB.size === 0) return 0.0;
+
+    let intersection = 0;
+    for (const tok of setA) {
+        if (setB.has(tok)) intersection++;
+    }
+    const union = setA.size + setB.size - intersection;
+    return union === 0 ? 1.0 : intersection / union;
+}
+
+export function classifySimilarity(score: number): SimilarityClass {
+    if (score >= MERGE_THRESHOLD) return 'merge';
+    if (score >= WARN_THRESHOLD) return 'warn';
+    return 'create';
+}
+
+export interface Candidate {
+    id: string;
+    text: string;
+}
+
+export interface SimilarityMatch {
+    id: string;
+    text: string;
+    score: number;
+    classification: SimilarityClass;
+}
+
+/** Best (highest-score) match across candidates, or null when candidates is empty. Ties resolve to the first candidate in iteration order (deterministic given a deterministic input order). */
+export function findMostSimilar(target: string, candidates: Iterable<Candidate>): SimilarityMatch | null {
+    let best: SimilarityMatch | null = null;
+    for (const candidate of candidates) {
+        const score = jaccardSimilarity(target, candidate.text);
+        if (best === null || score > best.score) {
+            best = { id: candidate.id, text: candidate.text, score, classification: classifySimilarity(score) };
+        }
+    }
+    return best;
+}

package/src/scripts/ai-video/test-pipeline.sh

@@ -26,7 +26,7 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
 PROJECT="$ROOT/agents/reference/ai-video/examples/banana-arc"
 
 PASS=0

package/src/scripts/ai_council/clients.ts

@@ -384,9 +384,25 @@ export class AnthropicClient extends ExternalAIClient {
         const latency_ms = _elapsedMs(t0);
         let text = '';
         const content = _getattr(response, 'content', null);
-        if (_pyTruthy(content)) {
-            const first = (content as unknown[])[0];
-            text = (_getattr(first, 'text', '') as string) || '';
+        if (_pyTruthy(content) && Array.isArray(content)) {
+            // Join every text-type block. Extended-thinking models (e.g.
+            // claude-fable-5) return a `thinking`/`reasoning` block FIRST, so the
+            // legacy `content[0].text` extraction yielded '' despite real output
+            // (observed: 3191 output_tokens, text len 0). Collect text from all
+            // `type === 'text'` (or untyped) blocks; skip thinking / tool_use.
+            const parts: string[] = [];
+            for (const block of content as unknown[]) {
+                const btype = _getattr(block, 'type', null);
+                const btext = _getattr(block, 'text', '') as string;
+                if ((btype === null || btype === 'text') && typeof btext === 'string' && btext) {
+                    parts.push(btext);
+                }
+            }
+            text = parts.join('');
+            if (!text) {
+                const first = (content as unknown[])[0];
+                text = (_getattr(first, 'text', '') as string) || '';
+            }
         }
         const usage = _getattr(response, 'usage', null);
         return new CouncilResponse({

package/src/scripts/append_contested.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env tsx
+/**
+ * Contested-annotation writer — road-to-knowledge-system Phase 5. When a
+ * live contradiction is found between a knowledge page and observed
+ * reality and the user declines an immediate fix (see the hybrid
+ * immediate-fix flow in `knowledge-pages.md`), this appends an
+ * append-only `contested:` entry to the page's frontmatter — never a
+ * silent rewrite of the claimed content. `check_knowledge_pages.ts`
+ * already warns once a page carries 2+ unresolved entries; this script
+ * is the writer half of that contract.
+ *
+ * Usage:
+ *   append_contested.ts --page <path> --trigger <trigger> --evidence "<text>" --session <id> --timestamp <ISO-8601>
+ *
+ * Exit codes: 0 = appended, 1 = usage error / page not found, 3 = internal error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+
+const PROG = 'append_contested.ts';
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/;
+
+export interface ContestedEntry {
+    timestamp: string;
+    trigger: string;
+    evidence: string;
+    session: string;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Appends `entry` to the page's frontmatter `contested:` array (creating the array/frontmatter block if absent). The page body is never touched. */
+export function appendContestedEntry(content: string, entry: ContestedEntry): string {
+    const match = FRONTMATTER_RE.exec(content);
+    const body = match ? content.slice(match[0].length) : content;
+
+    let fm: Record<string, unknown> = {};
+    if (match?.[1] !== undefined) {
+        const parsed = YAML.parse(match[1]);
+        if (isPlainObject(parsed)) fm = parsed;
+    }
+
+    const existing = Array.isArray(fm.contested) ? fm.contested : [];
+    fm.contested = [...existing, entry];
+
+    const rendered = YAML.stringify(fm).trimEnd();
+    return `---\n${rendered}\n---\n${body}`;
+}
+
+function printUsage(): void {
+    process.stdout.write(
+        `usage: ${PROG} --page PATH --trigger TRIGGER --evidence TEXT --session ID --timestamp ISO8601\n`,
+    );
+}
+
+export function main(argv: string[]): number {
+    let page: string | null = null;
+    let trigger: string | null = null;
+    let evidence: string | null = null;
+    let session: string | null = null;
+    let timestamp: string | null = null;
+
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help') {
+            printUsage();
+            return 0;
+        } else if (arg === '--page') {
+            page = argv[++i] ?? null;
+        } else if (arg === '--trigger') {
+            trigger = argv[++i] ?? null;
+        } else if (arg === '--evidence') {
+            evidence = argv[++i] ?? null;
+        } else if (arg === '--session') {
+            session = argv[++i] ?? null;
+        } else if (arg === '--timestamp') {
+            timestamp = argv[++i] ?? null;
+        } else {
+            process.stderr.write(`${PROG}: error: unrecognized argument: ${arg}\n`);
+            printUsage();
+            return 1;
+        }
+    }
+
+    if (!page || !trigger || !evidence || !session || !timestamp) {
+        process.stderr.write(`${PROG}: error: --page, --trigger, --evidence, --session, and --timestamp are all required\n`);
+        printUsage();
+        return 1;
+    }
+
+    let content: string;
+    try {
+        content = fs.readFileSync(page, 'utf8');
+    } catch {
+        process.stderr.write(`${PROG}: error: page not found: ${page}\n`);
+        return 1;
+    }
+
+    const updated = appendContestedEntry(content, { timestamp, trigger, evidence, session });
+    fs.writeFileSync(page, updated, 'utf8');
+    process.stdout.write(`${PROG}: appended contested entry to ${page}.\n`);
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/audit_auto_rules.ts

@@ -21,6 +21,7 @@
  * - `agents/reports/auto-rules-audit.json` — deterministic, machine-readable.
  * - `agents/reports/auto-rules-audit.md`   — ranked summary for review.
  */
+import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -256,7 +257,16 @@ export function render_markdown(rules: RuleEntry[]): string {
     const total_stub = rules.reduce((s, r) => s + r.stub_chars, 0);
     const total_body = rules.reduce((s, r) => s + r.body_chars, 0);
     const total_desc = rules.reduce((s, r) => s + r.description_chars, 0);
+    // Freshness marker — required by check_generated_artefact_headers (Phase 8.2)
+    const commitShort = (() => {
+        try {
+            const r = spawnSync('git', ['rev-parse', '--short', 'HEAD'], { encoding: 'utf-8' });
+            return r.stdout.trim() || 'unknown';
+        } catch { return 'unknown'; }
+    })();
+    const dateStr = new Date().toISOString().slice(0, 10);
     const lines: string[] = [
+        `<!-- analyzed: ${dateStr} | commit: ${commitShort} | files: ${rules.length} -->`,
         '# Auto-Rule Audit',
         '',
         'Generated by `scripts/audit_auto_rules.py` for Phase 5 of',
@@ -266,7 +276,7 @@ export function render_markdown(rules: RuleEntry[]): string {
         '## Totals',
         '',
         `- auto-rules: **${rules.length}**`,
-        `- registry-stub cost (counts against 49,512 cap): **${_comma(total_stub)}** chars`,
+        `- registry-stub cost (counts against the budgets.yml cap): **${_comma(total_stub)}** chars`,
         `- description chars (subset of stub cost): **${_comma(total_desc)}** chars`,
         `- body chars (informational, NOT in budget): **${_comma(total_body)}** chars`,
         '',

package/src/scripts/audit_mcp_tools.ts

@@ -10,7 +10,7 @@
  *
  * Reads the source-of-truth catalog at
  * `src/scripts/mcp_server/consumer_tool_catalog.json` and the handler
- * registry at `src/scripts/mcp_server/tools.py`, emits
+ * registry at `src/scripts/mcp_server/tools.ts`, emits
  * `docs/contracts/mcp-tool-inventory.md` with every tool cited by
  * `<file>:<line>`.
  *
@@ -26,11 +26,12 @@ const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/audit_mcp_tools.ts → parent.parent.parent of the .py file = repo root.
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 export const CATALOG = path.join(ROOT, 'src/scripts/mcp_server/consumer_tool_catalog.json');
-export const TOOLS_PY = path.join(ROOT, 'src/scripts/mcp_server/tools.py');
+export const TOOLS_TS = path.join(ROOT, 'src/scripts/mcp_server/tools.ts');
 export const OUT = path.join(ROOT, 'docs/contracts/mcp-tool-inventory.md');
 
-// Match `"<name>": BuiltinTool(` in the ALLOWLIST dict.
-const HANDLER_RE = /^\s*"([a-z_]+)"\s*:\s*BuiltinTool\(/;
+// Match `<name>: {` entries at 4-space indent inside the TS ALLOWLIST record
+// (deeper keys like `input_schema: {` sit at 8+ spaces and never match).
+const HANDLER_RE = /^ {4}([a-z_]+): \{$/;
 // Match `"name": "<name>",` in the catalog json (for catalog citations).
 const CATALOG_NAME_RE = /^\s*"name"\s*:\s*"([a-z_]+)"\s*,?\s*$/;
 
@@ -70,11 +71,24 @@ function _relativeToRoot(p: string): string {
 
 function _index_handlers(): Map<string, number> {
     const out = new Map<string, number>();
-    const lines = _splitlines(fs.readFileSync(TOOLS_PY, 'utf-8'));
-    // enumerate(..., 1)
+    const lines = _splitlines(fs.readFileSync(TOOLS_TS, 'utf-8'));
+    // Only index entries inside the `export const ALLOWLIST` block.
+    let inAllowlist = false;
     for (let idx = 0; idx < lines.length; idx += 1) {
         const i = idx + 1;
-        const m = HANDLER_RE.exec(lines[idx] as string);
+        const line = lines[idx] as string;
+        if (line.startsWith('export const ALLOWLIST')) {
+            inAllowlist = true;
+            continue;
+        }
+        if (inAllowlist && line.startsWith('};')) {
+            inAllowlist = false;
+            continue;
+        }
+        if (!inAllowlist) {
+            continue;
+        }
+        const m = HANDLER_RE.exec(line);
         if (m) {
             out.set(m[1] as string, i);
         }
@@ -129,9 +143,9 @@ function _render(catalog: Catalog, handlers: Map<string, number>, cat_lines: Map
     lines.push('');
     lines.push('# MCP tool inventory');
     lines.push('');
-    lines.push('> Generated by [`scripts/audit_mcp_tools.py`](../../scripts/audit_mcp_tools.py)');
+    lines.push('> Generated by [`src/scripts/audit_mcp_tools.ts`](../../src/scripts/audit_mcp_tools.ts)');
     lines.push('> from the source-of-truth catalog');
-    lines.push('> [`scripts/mcp_server/consumer_tool_catalog.json`](../../scripts/mcp_server/consumer_tool_catalog.json).');
+    lines.push('> [`src/scripts/mcp_server/consumer_tool_catalog.json`](../../src/scripts/mcp_server/consumer_tool_catalog.json).');
     lines.push('> Do **not** hand-edit; rerun `./scripts-run src/scripts/audit_mcp_tools --write`.');
     lines.push('>');
     lines.push('> Step-11 Phase 5 Step 3 (an internal parity roadmap (local-only)).');
@@ -154,12 +168,12 @@ function _render(catalog: Catalog, handlers: Map<string, number>, cat_lines: Map
         const cat_line = cat_lines.get(name);
         const cat_cite =
             cat_line !== undefined
-                ? `[\`consumer_tool_catalog.json:${cat_line}\`](../../scripts/mcp_server/consumer_tool_catalog.json#L${cat_line})`
+                ? `[\`consumer_tool_catalog.json:${cat_line}\`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L${cat_line})`
                 : '_missing_';
         const h_line = handlers.get(name);
         const h_cite =
             h_line !== undefined
-                ? `[\`tools.py:${h_line}\`](../../scripts/mcp_server/tools.py#L${h_line})`
+                ? `[\`tools.ts:${h_line}\`](../../src/scripts/mcp_server/tools.ts#L${h_line})`
                 : '_stub-only_';
         lines.push(`| \`${name}\` | \`${side}\` | ${transports} | ${cat_cite} | ${h_cite} |`);
     }