@event4u/agent-config 8.7.0 → 8.9.0

package/src/scripts/memory_replay.ts

@@ -0,0 +1,285 @@
+#!/usr/bin/env tsx
+/**
+ * Memory-retrieval replay rig (road-to-memory-retrieval-economy Phase 0).
+ *
+ * Replays the corpus-derived query set (tests/fixtures/memory-replay/ —
+ * provenance note in queries.yml; council 2026-07-08 Option-A verdict)
+ * against the fixture memory root and measures, with the REAL tokenizer
+ * (token_count.ts, cl100k_base — never chars/4, roadmap D2):
+ *
+ *   --baseline   full-envelope payload per query → pins
+ *                internal/bench/reports/memory-retrieval-baseline.json
+ *   --paired     index-mode envelope + memory_get(needed) payload vs the
+ *                full baseline → run report + the three falsification
+ *                checks from Phase 1b (token saving ≥30%, zero missed
+ *                needed-fetches; the judge arm is reported as
+ *                out-of-band — see report field `judge`)
+ *   --check      CI regression: index-mode payload for the replay set must
+ *                not exceed the recorded baseline's index payload by >5%.
+ *                INERT (exit 0) while no baseline file exists.
+ *
+ * Exit codes: 0 ok/inert · 1 check failed or paired falsification red ·
+ * 2 usage/fixture error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import * as YAML from 'yaml';
+
+import {
+    _setIntakeRoot,
+    _setKnowledgeRoot,
+    _setMemoryRoot,
+    retrieve_v1,
+} from './memory_lookup.js';
+import { gpt_tokens, TIKTOKEN_AVAILABLE } from './_lib/token_count.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+export const FIXTURE_DIR = path.join(ROOT, 'tests', 'fixtures', 'memory-replay');
+export const BASELINE_PATH = path.join(
+    ROOT,
+    'internal',
+    'bench',
+    'reports',
+    'memory-retrieval-baseline.json',
+);
+
+export interface ReplayQuery {
+    readonly id: string;
+    readonly types: string[];
+    readonly keys: string[];
+    readonly limit: number;
+    readonly needed: string[];
+}
+
+export function load_queries(): ReplayQuery[] {
+    const raw = YAML.parse(fs.readFileSync(path.join(FIXTURE_DIR, 'queries.yml'), 'utf-8')) as {
+        queries: ReplayQuery[];
+    };
+    return raw.queries;
+}
+
+/** Point the lookup module at the fixture memory tree. */
+export function bind_fixture_root(): void {
+    const memRoot = path.join(FIXTURE_DIR, 'memory-root');
+    _setMemoryRoot(memRoot);
+    _setKnowledgeRoot(path.join(memRoot, 'knowledge'));
+    _setIntakeRoot(path.join(memRoot, 'intake-does-not-exist'));
+}
+
+/** Real-tokenizer size of an envelope, serialized the way a host sees it. */
+export function envelope_tokens(envelope: unknown): number {
+    return gpt_tokens(JSON.stringify(envelope)).tokens;
+}
+
+interface PerQuery {
+    id: string;
+    full_tokens: number;
+    needed_found: number;
+    needed_total: number;
+    index_tokens?: number;
+    fetch_tokens?: number;
+    index_plus_fetch_tokens?: number;
+    saving_pct?: number;
+    missed_needed?: string[];
+}
+
+/** IDs present in a v1 envelope's entries. */
+function _entry_ids(envelope: Record<string, unknown>): Set<string> {
+    const out = new Set<string>();
+    for (const e of (envelope['entries'] as Array<Record<string, unknown>>) ?? []) {
+        out.add(String(e['id'] ?? ''));
+    }
+    return out;
+}
+
+type RetrieveV1 = (
+    types: string[],
+    keys: string[],
+    limit?: number,
+    options?: { detail?: 'index' | 'full' },
+) => Record<string, unknown>;
+
+/** Optional Phase-1 surfaces, absent before P1 lands. */
+async function _phase1(): Promise<{
+    retrieve_v1_detail: RetrieveV1 | null;
+    memory_get: ((ids: string[]) => Record<string, unknown>) | null;
+}> {
+    const mod = (await import('./memory_lookup.js')) as Record<string, unknown>;
+    const hasDetail = typeof mod['retrieve_v1'] === 'function' && (mod['retrieve_v1'] as { length: number }).length >= 0;
+    const memoryGet = typeof mod['memory_get_v1'] === 'function'
+        ? (mod['memory_get_v1'] as (ids: string[]) => Record<string, unknown>)
+        : null;
+    // Detail support is feature-detected by probing the options seam: before
+    // Phase 1, passing options is harmless (extra arg ignored) but index mode
+    // is only REAL when memory_get exists too.
+    return { retrieve_v1_detail: hasDetail ? (retrieve_v1 as unknown as RetrieveV1) : null, memory_get: memoryGet };
+}
+
+export async function run(mode: 'baseline' | 'paired' | 'check'): Promise<number> {
+    bind_fixture_root();
+    const queries = load_queries();
+    if (queries.length < 20) {
+        process.stderr.write(`memory_replay: replay set too small (${queries.length} < 20)\n`);
+        return 2;
+    }
+    const p1 = await _phase1();
+    const perQuery: PerQuery[] = [];
+
+    for (const q of queries) {
+        const full = retrieve_v1(q.types, q.keys, q.limit);
+        const fullIds = _entry_ids(full);
+        const foundNeeded = q.needed.filter((n) => fullIds.has(n));
+        const row: PerQuery = {
+            id: q.id,
+            full_tokens: envelope_tokens(full),
+            needed_found: foundNeeded.length,
+            needed_total: q.needed.length,
+        };
+
+        if (mode !== 'baseline' && p1.retrieve_v1_detail !== null && p1.memory_get !== null) {
+            const index = p1.retrieve_v1_detail(q.types, q.keys, q.limit, { detail: 'index' });
+            const indexIds = _entry_ids(index);
+            const missed = q.needed.filter((n) => !indexIds.has(n));
+            const fetched = p1.memory_get(q.needed);
+            row.index_tokens = envelope_tokens(index);
+            row.fetch_tokens = envelope_tokens(fetched);
+            row.index_plus_fetch_tokens = row.index_tokens + row.fetch_tokens;
+            row.saving_pct =
+                Math.round((1 - row.index_plus_fetch_tokens / row.full_tokens) * 1000) / 10;
+            row.missed_needed = missed;
+        }
+        perQuery.push(row);
+    }
+
+    const agg = {
+        queries: perQuery.length,
+        full_tokens: perQuery.reduce((s, r) => s + r.full_tokens, 0),
+        needed_recall: perQuery.reduce((s, r) => s + r.needed_found, 0) /
+            perQuery.reduce((s, r) => s + r.needed_total, 0),
+        index_plus_fetch_tokens: perQuery.every((r) => r.index_plus_fetch_tokens !== undefined)
+            ? perQuery.reduce((s, r) => s + (r.index_plus_fetch_tokens ?? 0), 0)
+            : null,
+    };
+    const saving_pct = agg.index_plus_fetch_tokens === null
+        ? null
+        : Math.round((1 - agg.index_plus_fetch_tokens / agg.full_tokens) * 1000) / 10;
+
+    const report = {
+        schema_version: 1,
+        kind: `memory-retrieval-${mode}`,
+        roadmap: 'road-to-memory-retrieval-economy',
+        corpus_provenance:
+            'corpus-derived (council 2026-07-08 Option A) — see tests/fixtures/memory-replay/queries.yml header; claims scoped to corpus-derived replay queries',
+        tokenizer: TIKTOKEN_AVAILABLE ? 'cl100k_base (tiktoken)' : 'PROXY chars/4 — NOT evidence (D2)',
+        aggregate: { ...agg, saving_pct },
+        per_query: perQuery,
+    };
+
+    if (mode === 'baseline') {
+        fs.mkdirSync(path.dirname(BASELINE_PATH), { recursive: true });
+        fs.writeFileSync(BASELINE_PATH, JSON.stringify(report, null, 2) + '\n');
+        process.stdout.write(
+            `✅  baseline pinned: ${agg.queries} queries · full=${agg.full_tokens} tok · ` +
+                `needed-recall=${(agg.needed_recall * 100).toFixed(1)}%\n`,
+        );
+        return agg.needed_recall === 1 ? 0 : 1;
+    }
+
+    if (mode === 'paired') {
+        if (agg.index_plus_fetch_tokens === null) {
+            process.stderr.write(
+                'memory_replay: paired mode needs Phase 1 (detail + memory_get_v1) — not available\n',
+            );
+            return 2;
+        }
+        const missedTotal = perQuery.reduce((s, r) => s + (r.missed_needed?.length ?? 0), 0);
+        const out = path.join(
+            path.dirname(BASELINE_PATH),
+            'memory-retrieval-run.json',
+        );
+        const checks = {
+            'a-token-saving-ge-30pct': (saving_pct ?? 0) >= 30,
+            'b-judge-win-rate': 'OUT-OF-BAND — run check_quality_regression paired judge before flip sign-off',
+            'c-zero-missed-needed': missedTotal === 0,
+        };
+        fs.writeFileSync(out, JSON.stringify({ ...report, falsification: checks }, null, 2) + '\n');
+        process.stdout.write(
+            `paired: full=${agg.full_tokens} vs index+fetch=${agg.index_plus_fetch_tokens} ` +
+                `(saving ${saving_pct}%) · missed-needed=${missedTotal} → ${out}\n`,
+        );
+        return checks['a-token-saving-ge-30pct'] && checks['c-zero-missed-needed'] ? 0 : 1;
+    }
+
+    // --check: inert without a baseline; else compare index payload drift.
+    if (!fs.existsSync(BASELINE_PATH)) {
+        process.stdout.write('memory_replay --check: no baseline pinned — inert.\n');
+        return 0;
+    }
+    if (agg.index_plus_fetch_tokens === null) {
+        // Phase 1 not landed: guard the FULL payload against >5% growth
+        // instead, so the baseline still means something pre-split.
+        const pinned = JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf-8')) as {
+            aggregate: { full_tokens: number };
+        };
+        const limitTok = pinned.aggregate.full_tokens * 1.05;
+        if (agg.full_tokens > limitTok) {
+            process.stdout.write(
+                `❌  memory_replay --check: full payload ${agg.full_tokens} exceeds baseline ` +
+                    `${pinned.aggregate.full_tokens} by >5%\n`,
+            );
+            return 1;
+        }
+        process.stdout.write('✅  memory_replay --check: within baseline (+5%).\n');
+        return 0;
+    }
+    const pinned = JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf-8')) as {
+        aggregate: { full_tokens: number };
+    };
+    const limitTok = pinned.aggregate.full_tokens * 1.05;
+    if ((agg.index_plus_fetch_tokens ?? 0) > limitTok) {
+        process.stdout.write(
+            `❌  memory_replay --check: index payload ${agg.index_plus_fetch_tokens} exceeds ` +
+                `baseline full ${pinned.aggregate.full_tokens} by >5%\n`,
+        );
+        return 1;
+    }
+    process.stdout.write('✅  memory_replay --check: index payload within baseline (+5%).\n');
+    return 0;
+}
+
+export async function main(argv: readonly string[] = process.argv.slice(2)): Promise<number> {
+    const mode = argv.includes('--baseline')
+        ? 'baseline'
+        : argv.includes('--paired')
+          ? 'paired'
+          : argv.includes('--check')
+            ? 'check'
+            : null;
+    if (mode === null) {
+        process.stderr.write('usage: memory_replay.ts --baseline | --paired | --check\n');
+        return 2;
+    }
+    return run(mode);
+}
+
+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 {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    main().then((code) => process.exit(code));
+}

package/src/scripts/orchestration_record.ts

@@ -0,0 +1,140 @@
+/**
+ * Orchestration telemetry recorder — CLI.
+ *
+ * Appends ONE validated audit-log-v1 line (with an `orchestration` object) to
+ * the monthly audit log, from the counts the orchestrating agent has after an
+ * auto-dispatch. One command instead of hand-authored JSON — the reliable,
+ * lock-respecting (2026-06-30 no-hook decision) capture path.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/orchestration_record \
+ *     --spawn-count 1 --token-delta -72000 --provenance measured \
+ *     --tier-chosen lite --tier-source inferred --task-class read-only-fanout \
+ *     [--tiers sonnet,opus] [--wall-clock-ms 18500] [--dispatch-outcome DONE] \
+ *     [--dir <audit-dir>] [--dry-run]
+ *
+ * Read by `src/scripts/orchestration_savings_report.ts`.
+ */
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+    buildOrchestrationLine,
+    type Provenance,
+    type TierChosen,
+    type TierSource,
+    type DispatchOutcome,
+    type VerifyMode,
+    type Band,
+    type LinePhase,
+    type LineOutcome,
+    type RecordInput,
+} from './_lib/orchestration_record.js';
+
+const DEFAULT_DIR = 'agents/runtime/state/audit';
+
+type Flags = Record<string, string | boolean>;
+
+function parseFlags(argv: string[]): Flags {
+    const flags: Flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === undefined || !a.startsWith('--')) continue;
+        const eq = a.indexOf('=');
+        if (eq !== -1) {
+            flags[a.slice(2, eq)] = a.slice(eq + 1);
+            continue;
+        }
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            flags[key] = next;
+            i++;
+        } else {
+            flags[key] = true; // boolean flag (e.g. --dry-run)
+        }
+    }
+    return flags;
+}
+
+function str(flags: Flags, key: string): string | undefined {
+    const v = flags[key];
+    return typeof v === 'string' ? v : undefined;
+}
+
+function int(flags: Flags, key: string): number | undefined {
+    const v = str(flags, key);
+    if (v === undefined) return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : NaN; // NaN → caught by the lib's isInt validation
+}
+
+/** Deterministic content-hash id (contract allows "ULID or content hash"). */
+function contentHashId(input: RecordInput): string {
+    const canonical = JSON.stringify({
+        ts: input.ts,
+        spawn_count: input.spawn_count,
+        token_delta: input.token_delta,
+        tier_chosen: input.tier_chosen ?? null,
+        task_class: input.task_class ?? null,
+    });
+    return crypto.createHash('sha256').update(canonical).digest('hex').slice(0, 26).toUpperCase();
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const flags = parseFlags(argv);
+    const dir = str(flags, 'dir') ?? DEFAULT_DIR;
+    const dryRun = flags['dry-run'] === true;
+    const ts = new Date().toISOString();
+
+    const partial: Omit<RecordInput, 'id'> = {
+        spawn_count: int(flags, 'spawn-count') ?? NaN,
+        token_delta: int(flags, 'token-delta') ?? NaN,
+        token_delta_provenance: str(flags, 'provenance') as Provenance | undefined,
+        tiers: str(flags, 'tiers')?.split(',').map((s) => s.trim()).filter(Boolean),
+        tier_chosen: str(flags, 'tier-chosen') as TierChosen | undefined,
+        tier_source: str(flags, 'tier-source') as TierSource | undefined,
+        task_class: str(flags, 'task-class'),
+        task_size_estimate: int(flags, 'task-size-estimate'),
+        wall_clock_ms: int(flags, 'wall-clock-ms'),
+        dispatch_tokens: int(flags, 'dispatch-tokens'),
+        session_tier: str(flags, 'session-tier'),
+        dispatch_outcome: str(flags, 'dispatch-outcome') as DispatchOutcome | undefined,
+        verify_mode: str(flags, 'verify-mode') as VerifyMode | undefined,
+        phase: str(flags, 'phase') as LinePhase | undefined,
+        outcome: str(flags, 'outcome') as LineOutcome | undefined,
+        confidence_band: str(flags, 'confidence-band') as Band | undefined,
+        risk_class: str(flags, 'risk-class') as Band | undefined,
+        persona: str(flags, 'persona'),
+        work_id: str(flags, 'work-id'),
+        ts,
+    };
+    const input: RecordInput = { ...partial, id: contentHashId({ ...partial, id: '' }) };
+
+    const { line, errors } = buildOrchestrationLine(input);
+    if (errors.length || line === null) {
+        process.stderr.write('orchestration_record: refused — invalid input:\n');
+        for (const e of errors) process.stderr.write(`  - ${e}\n`);
+        return 1;
+    }
+
+    const serialized = JSON.stringify(line);
+    if (dryRun) {
+        process.stdout.write(serialized + '\n');
+        return 0;
+    }
+
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `${ts.slice(0, 7)}.jsonl`);
+    fs.appendFileSync(file, serialized + '\n', 'utf8');
+    process.stdout.write(`orchestration telemetry recorded → ${file} (id ${line.id})\n`);
+    return 0;
+}
+
+if (process.argv[1] !== undefined) {
+    const invokedUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === invokedUrl) process.exit(main());
+}

package/src/scripts/orchestration_savings_report.ts

@@ -0,0 +1,124 @@
+/**
+ * Orchestration savings report — CLI.
+ *
+ * Reads accumulated orchestration telemetry from the audit-log-v1 JSONL files
+ * and prints an aggregate token-savings report. Read-only; no network, no
+ * mutation. Handles a missing/empty audit dir gracefully.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/orchestration_savings_report \
+ *     [--dir <path>] [--format text|json] [--weights lite=1,medium=5,high=15]
+ *
+ * Default dir: agents/runtime/state/audit (the audit-log-v1 path where the
+ * orchestration layer writes telemetry lines). `--weights` tunes the
+ * provider-neutral tier weights behind the MODELED cost-%. See
+ * `src/agent-src/contexts/execution/orchestration-telemetry.md`.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { aggregateOrchestrationSavings, DEFAULT_TIER_WEIGHTS, type AuditLine, type SavingsReport, type TierWeights } from './_lib/orchestration_savings.js';
+
+const DEFAULT_DIR = 'agents/runtime/state/audit';
+
+interface Options {
+    dir: string;
+    format: 'text' | 'json';
+    weights: TierWeights;
+}
+
+/** Parse `lite=1,medium=5,high=15` → weight map. Returns undefined if nothing valid parsed. */
+function parseWeights(spec: string | undefined): TierWeights | undefined {
+    if (!spec) return undefined;
+    const w: TierWeights = {};
+    for (const pair of spec.split(',')) {
+        const [k, v] = pair.split('=');
+        const n = Number(v);
+        if (k && Number.isFinite(n)) w[k.trim()] = n;
+    }
+    return Object.keys(w).length ? w : undefined;
+}
+
+function parseArgs(argv: string[]): Options {
+    const opts: Options = { dir: DEFAULT_DIR, format: 'text', weights: DEFAULT_TIER_WEIGHTS };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === undefined) continue;
+        if (a === '--dir') opts.dir = argv[++i] ?? opts.dir;
+        else if (a.startsWith('--dir=')) opts.dir = a.slice('--dir='.length);
+        else if (a === '--format') opts.format = (argv[++i] as Options['format']) ?? opts.format;
+        else if (a.startsWith('--format=')) opts.format = a.slice('--format='.length) as Options['format'];
+        else if (a === '--weights') opts.weights = parseWeights(argv[++i]) ?? opts.weights;
+        else if (a.startsWith('--weights=')) opts.weights = parseWeights(a.slice('--weights='.length)) ?? opts.weights;
+    }
+    if (opts.format !== 'text' && opts.format !== 'json') opts.format = 'text';
+    return opts;
+}
+
+/** Read + parse every `.jsonl` line in `dir`. Malformed lines are skipped. */
+export function readAuditLines(dir: string): AuditLine[] {
+    if (!fs.existsSync(dir)) return [];
+    const lines: AuditLine[] = [];
+    for (const entry of fs.readdirSync(dir).sort()) {
+        if (!entry.endsWith('.jsonl')) continue;
+        const raw = fs.readFileSync(path.join(dir, entry), 'utf8');
+        for (const ln of raw.split('\n')) {
+            const trimmed = ln.trim();
+            if (!trimmed) continue;
+            try {
+                lines.push(JSON.parse(trimmed) as AuditLine);
+            } catch {
+                // Skip malformed line — a partial write must not crash the report.
+            }
+        }
+    }
+    return lines;
+}
+
+function renderText(r: SavingsReport, dir: string): string {
+    const out: string[] = [];
+    out.push('Orchestration savings report');
+    out.push(`  source: ${dir}`);
+    out.push(`  dispatches: ${r.dispatches}  (total spawns: ${r.total_spawns})`);
+    out.push(`  net token_delta: ${r.net_token_delta}  (negative = net saved)`);
+    out.push(`  tokens saved: ${r.tokens_saved}   tokens added: ${r.tokens_added}`);
+    out.push(`  provenance: measured ${r.by_provenance.measured.dispatches} (Δ ${r.by_provenance.measured.net_token_delta}) · estimated ${r.by_provenance.estimated.dispatches} (Δ ${r.by_provenance.estimated.net_token_delta})`);
+    out.push(`  measured share: ${(r.measured_share * 100).toFixed(0)}%`);
+    if (Object.keys(r.by_tier).length) {
+        out.push('  by tier (Δ tokens):');
+        for (const [tier, d] of Object.entries(r.by_tier).sort()) out.push(`    ${tier}: ${d}`);
+    }
+    if (Object.keys(r.by_task_class).length) {
+        out.push('  by task_class (Δ tokens):');
+        for (const [cls, d] of Object.entries(r.by_task_class).sort()) out.push(`    ${cls}: ${d}`);
+    }
+    const mc = r.modeled_cost;
+    if (mc.cost_reduction_pct !== null) {
+        out.push(`  MODELED cost reduction: ${(mc.cost_reduction_pct * 100).toFixed(0)}%  (over ${mc.covered_dispatches}/${r.dispatches} dispatch(es) with tier data)`);
+        out.push(`    weights ${JSON.stringify(mc.weights)} · baseline ${mc.baseline_cost_units} → delegated ${mc.delegated_cost_units} cost-units · MODEL, not measured $`);
+    } else {
+        out.push('  MODELED cost reduction: n/a (needs dispatch_tokens + session_tier + tier_chosen on a dispatch)');
+    }
+    out.push('  notes:');
+    for (const n of r.notes) out.push(`    - ${n}`);
+    return out.join('\n');
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const opts = parseArgs(argv);
+    const lines = readAuditLines(opts.dir);
+    const report = aggregateOrchestrationSavings(lines, opts.weights);
+    if (opts.format === 'json') {
+        process.stdout.write(JSON.stringify({ ...report, source: opts.dir }, null, 2) + '\n');
+    } else {
+        process.stdout.write(renderText(report, opts.dir) + '\n');
+    }
+    return 0;
+}
+
+if (process.argv[1] !== undefined) {
+    const invokedUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === invokedUrl) process.exit(main());
+}

package/src/scripts/schemas/domain-truth.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/domain-truth.schema.json",
+  "x-schemaVersion": "1.0.0",
+  "title": "Domain-truth fixtures (domain-truth.json)",
+  "$comment": "Domain-SOUNDNESS fixtures for non-coding default-surface skills (road-to-domain-soundness Phase 1). DISTINCT from evals.json (behavioural output quality) and triggers.json (activation): a domain-truth case asserts the embedded domain heuristic is actually CORRECT off the forged TS/PHP stacks. Every case's answer key must be traceable to a CITED external method/standard — never the skill's own output (that validates nothing). A skill lacking this file is `unvalidated`; presence + a passing run makes it `validated`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["skill", "domain", "cases"],
+  "properties": {
+    "skill": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Skill slug; must match the parent skill directory name."
+    },
+    "domain": {
+      "type": "string",
+      "enum": ["finance", "founder", "ops", "content"],
+      "description": "The non-coding domain whose ground truth this fixture checks."
+    },
+    "_note": {
+      "type": "string",
+      "description": "Optional free-text note (calibration / provenance status). Advisory."
+    },
+    "cases": {
+      "type": "array",
+      "minItems": 1,
+      "description": "One or more domain-truth cases: a scenario + a domain-correct answer key with a SOURCED rationale.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "scenario", "check", "source"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$",
+            "description": "Stable case slug, unique within this file."
+          },
+          "scenario": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The input scenario handed to the skill under test."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The CITED external method/standard the answer key is traceable to (a finance text, an IC framework, a named practice). A case whose key cannot cite an external basis is not a domain-truth case — it is rejected. NEVER the skill's own output."
+          },
+          "check": {
+            "description": "How soundness is judged. Deterministic where the domain has a right number; rubric where it does not (the rubric criterion must name the cited practice, graded by a pinned judge, recorded as a known-limit — never a hidden LLM-judge).",
+            "oneOf": [
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["kind", "expected"],
+                "properties": {
+                  "kind": { "const": "deterministic" },
+                  "expected": {
+                    "type": ["number", "string"],
+                    "description": "The computed-correct answer (e.g. a runway in months, an NPV) with the working shown in `rationale`."
+                  },
+                  "tolerance": {
+                    "type": "number",
+                    "minimum": 0,
+                    "description": "Absolute tolerance for a numeric expected value (0 = exact)."
+                  },
+                  "rationale": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The working that derives `expected` from the cited method, so a maintainer without the domain can check the key against the source, not against the skill."
+                  }
+                },
+                "required": ["kind", "expected", "rationale"]
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["kind", "criterion"],
+                "properties": {
+                  "kind": { "const": "rubric" },
+                  "criterion": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Pass criterion phrased as \"matches <named practice>\", graded by a pinned judge. NON-deterministic — recorded as a known-limit with a witness."
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}