@event4u/agent-config 8.7.0 → 8.8.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_savings_report.ts

@@ -0,0 +1,100 @@
+/**
+ * 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]
+ *
+ * Default dir: agents/runtime/state/audit (the audit-log-v1 path where the
+ * orchestration layer writes telemetry lines). 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, type AuditLine, type SavingsReport } from './_lib/orchestration_savings.js';
+
+const DEFAULT_DIR = 'agents/runtime/state/audit';
+
+interface Options {
+    dir: string;
+    format: 'text' | 'json';
+}
+
+function parseArgs(argv: string[]): Options {
+    const opts: Options = { dir: DEFAULT_DIR, format: 'text' };
+    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'];
+    }
+    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}`);
+    }
+    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);
+    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."
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/src/scripts/schemas/evals.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/evals.schema.json",
+  "x-schemaVersion": "1.0.0",
+  "title": "Skill behavioural evals (evals.json)",
+  "$comment": "Behavioural-eval spec consumed by run_skill_evals.ts (scaffold/aggregate/report) and counted by skill_eval_coverage.ts. Distinct from triggers.json (activation/routing axis). Roadmap: road-to-skill-eval-coverage Phase 1. Assertion kinds mirror _grade_assertions() in run_skill_evals.ts exactly — add a kind there before adding it here.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["skill", "scenarios"],
+  "properties": {
+    "skill": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Skill slug; must match the parent skill directory name (evals/ lives under src/skills/<skill>/)."
+    },
+    "_calibration": {
+      "type": "string",
+      "description": "Optional free-text note recording calibration status / provenance (e.g. uncalibrated finding_floor placeholders). Advisory; ignored by the grader."
+    },
+    "skill_body_sha": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "Optional SHA-256 of the skill's SKILL.md body at the time these evals were authored/last verified. When present, lint_behavioural_eval_freshness flags the eval stale if the current SKILL.md sha differs — the body changed, so the eval may no longer exercise it. Absent = unpinned (out of scope for the staleness gate), mirroring lint_eval_freshness's upstream:null handling."
+    },
+    "scenarios": {
+      "type": "array",
+      "minItems": 1,
+      "description": "One or more behavioural cases. Each pairs a prompt fixture with deterministic pass/fail assertions on the produced output.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "prompt", "assertions"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$",
+            "description": "Stable scenario slug, unique within this file (run directories are named by it)."
+          },
+          "prompt": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The input fixture handed to the skill under test."
+          },
+          "assertions": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Pass/fail checks on the output. Prefer deterministic kinds (contains/file_exists/finding_floor); use rubric only where a deterministic check is impossible, and pin the judge as a known limit.",
+            "items": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind", "value"],
+                  "properties": {
+                    "kind": { "const": "contains" },
+                    "value": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Substring the output must contain (deterministic)."
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind", "path"],
+                  "properties": {
+                    "kind": { "const": "file_exists" },
+                    "path": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Path (run-relative or absolute) the skill must have produced (deterministic)."
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind", "n"],
+                  "properties": {
+                    "kind": { "const": "finding_floor" },
+                    "n": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "description": "Minimum number of findings the output must carry (counted deterministically). 0 is a trivially-passing floor (the grader passes when count >= n) — used where the case only guards against over-reporting."
+                    },
+                    "pattern": {
+                      "type": "string",
+                      "description": "Optional regex counted globally; without it, markdown list-item lines are counted (see _count_findings)."
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind", "criterion"],
+                  "properties": {
+                    "kind": { "const": "rubric" },
+                    "criterion": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Natural-language pass criterion graded by a sub-agent. NON-deterministic — the grader returns pass:null until a pinned judge fills it. Use only where no deterministic check exists; record the judge as a known limit."
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}