@event4u/agent-config 8.9.0 → 8.10.0

package/docs/self-review-gate.md

@@ -0,0 +1,51 @@
+# Self-review gate (dogfooded PR review)
+
+The package reviews its own PRs with the exact machinery it ships —
+[`adversarial-review`](../src/skills/adversarial-review/SKILL.md) +
+[`agent-security-review`](../src/skills/agent-security-review/SKILL.md) — via
+[`.github/workflows/self-review-gate.yml`](../.github/workflows/self-review-gate.yml)
+and [`src/scripts/self_review_gate.ts`](../src/scripts/self_review_gate.ts).
+
+`road-to-maintainer-bus-factor` Phase 1.
+
+## Current status — ADVISORY, inert without a secret
+
+This is an **honest floor, not independent human review**, and today it is
+**advisory + inert-without-secret**. Do not read it as "every PR is
+AI-reviewed" — that is only true once the maintainer arms it (below).
+
+| Job | Runs | Spend | Blocks merge |
+|---|---|---|---|
+| `gate-dry-run` | every PR | none (no API) | never — prints the review plan only |
+| `live-advisory` | every PR **iff** `ANTHROPIC_API_KEY` is set | one review call | never — posts findings, records what *would* block |
+
+Without the `ANTHROPIC_API_KEY` repo secret, `live-advisory` is a **logged
+no-op** (never a failing check) — exactly the `cross-model-canary.yml` pattern.
+
+## The teeth (defined + wired, not yet armed)
+
+`self_review_gate.ts` exposes pure, unit-tested:
+
+- `classifyBlocking(finding)` — a finding is merge-blocking **iff**
+  `kind ∈ {security, claim}` **and** `severity ∈ {critical, high}`. Style and
+  correctness findings, and low/medium security findings, advise only. (Council
+  2026-07-08, claude-sonnet-4-5 + gpt-4o: a 100 %-blocking gate at
+  solo-maintainer token cost gets ignored or gamed — block only on the narrow
+  security/claim × high+ intersection.)
+- `gateVerdict(findings, {enforce})` — mirrors
+  `check_quality_regression.gateVerdict`: `0` pass / `2` block. Shipped
+  `enforce: false` (advisory always returns `0` and reports the would-block
+  set).
+
+## Arming it (maintainer, one flip)
+
+1. Add the `ANTHROPIC_API_KEY` repo secret (per-PR budget sign-off) — turns
+   `live-advisory` from no-op into a real dogfooded review.
+2. Pass `--enforce` in the live job to arm the teeth (block on
+   security/claim × high+).
+3. Require the `Self-review gate` check in branch protection
+   (`road-to-maintainer-bus-factor` Phase 2) so even solo merges pass the gate.
+4. Record the floor CLAIM on the proof page **once it is live** — not before
+   (an inert gate is not a passed gate).
+
+Blocker `self-review-gate-cost` (maintainer-owned) gates steps 1–2.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.9.0",
+    "version": "8.10.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/src/scripts/_lib/orchestration_record.ts

@@ -45,6 +45,10 @@ export interface RecordInput {
     session_tier?: string | null | undefined;
     dispatch_outcome?: DispatchOutcome | undefined;
     verify_mode?: VerifyMode | undefined;
+    /** QUALITY: subagent return adopted without parent rework. Optional boolean (null = not measured). */
+    first_pass_success?: boolean | undefined;
+    /** QUALITY: slice retried on a higher tier after a verification failure. Optional boolean (null = not measured). */
+    escalated?: boolean | undefined;
     // Audit-log envelope (sensible defaults for a dispatch record)
     phase?: LinePhase | undefined;
     outcome?: LineOutcome | undefined;
@@ -127,6 +131,13 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     const phase = input.phase ?? 'implement';
     if (!PHASES.includes(phase)) errors.push(`phase must be one of ${PHASES.join(' | ')}`);
 
+    if (input.first_pass_success !== undefined && typeof input.first_pass_success !== 'boolean') {
+        errors.push('first_pass_success must be a boolean (true = return adopted without parent rework) or omitted');
+    }
+    if (input.escalated !== undefined && typeof input.escalated !== 'boolean') {
+        errors.push('escalated must be a boolean (true = retried on a higher tier after verification failure) or omitted');
+    }
+
     if (!input.ts) errors.push('ts (ISO-8601 UTC) is required');
     if (!input.id) errors.push('id (ULID or content hash) is required');
 
@@ -146,6 +157,8 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         tier_source: input.tier_source ?? null,
         dispatch_tokens: input.dispatch_tokens ?? null,
         session_tier: input.session_tier ?? null,
+        first_pass_success: input.first_pass_success ?? null,
+        escalated: input.escalated ?? null,
     };
 
     const line: Record<string, unknown> = {

package/src/scripts/_lib/orchestration_savings.ts

@@ -39,6 +39,10 @@ export interface OrchestrationRecord {
     dispatch_tokens?: number | null;
     /** The orchestrator's own tier — the baseline the downshift is measured against. */
     session_tier?: string | null;
+    /** QUALITY: subagent return adopted without parent rework. null/absent = pre-extension line / not measured. */
+    first_pass_success?: boolean | null;
+    /** QUALITY: slice retried on a higher tier after a verification failure. null/absent = pre-extension line / not measured. */
+    escalated?: boolean | null;
 }
 
 /** A parsed audit-log-v1 line (only the fields this aggregator touches). */
@@ -65,6 +69,21 @@ export interface ModeledCost {
     weights: TierWeights;
 }
 
+export interface QualityStats {
+    /** Dispatches carrying at least one of the two quality booleans (the n behind the ≥20 pairing gate). */
+    quality_lines: number;
+    /** Dispatches carrying a boolean first_pass_success. */
+    first_pass_lines: number;
+    first_pass_success_count: number;
+    /** first_pass_success_count / first_pass_lines, 0..1; null when no line carries the field. */
+    first_pass_success_rate: number | null;
+    /** Dispatches carrying a boolean escalated. */
+    escalated_lines: number;
+    escalated_count: number;
+    /** escalated_count / escalated_lines, 0..1; null when no line carries the field. */
+    escalation_rate: number | null;
+}
+
 export interface SavingsReport {
     /** Lines carrying an orchestration object with spawn_count > 0. */
     dispatches: number;
@@ -84,6 +103,8 @@ export interface SavingsReport {
     measured_share: number;
     /** Modeled downshift cost-% (tier-weight based). Distinct from the measured token counts. */
     modeled_cost: ModeledCost;
+    /** QUALITY dimension — paired with cost per council verdict; never report savings alone. */
+    quality: QualityStats;
     /** Honest caveats about what the number does and does not mean. */
     notes: string[];
 }
@@ -115,6 +136,15 @@ export function aggregateOrchestrationSavings(
         by_task_class: {},
         measured_share: 0,
         modeled_cost: { covered_dispatches: 0, baseline_cost_units: 0, delegated_cost_units: 0, cost_reduction_pct: null, weights },
+        quality: {
+            quality_lines: 0,
+            first_pass_lines: 0,
+            first_pass_success_count: 0,
+            first_pass_success_rate: null,
+            escalated_lines: 0,
+            escalated_count: 0,
+            escalation_rate: null,
+        },
         notes: [],
     };
 
@@ -154,6 +184,21 @@ export function aggregateOrchestrationSavings(
             report.modeled_cost.baseline_cost_units += dt * wSession;
             report.modeled_cost.delegated_cost_units += dt * wChosen;
         }
+
+        // Quality dimension — only booleans count; null/absent = pre-extension
+        // line / not measured (never a silent false).
+        const q = report.quality;
+        const fps = typeof o.first_pass_success === 'boolean';
+        const esc = typeof o.escalated === 'boolean';
+        if (fps || esc) q.quality_lines += 1;
+        if (fps) {
+            q.first_pass_lines += 1;
+            if (o.first_pass_success === true) q.first_pass_success_count += 1;
+        }
+        if (esc) {
+            q.escalated_lines += 1;
+            if (o.escalated === true) q.escalated_count += 1;
+        }
     }
 
     report.measured_share = report.dispatches === 0 ? 0 : report.by_provenance.measured.dispatches / report.dispatches;
@@ -161,6 +206,10 @@ export function aggregateOrchestrationSavings(
     const mc = report.modeled_cost;
     mc.cost_reduction_pct = mc.baseline_cost_units > 0 ? (mc.baseline_cost_units - mc.delegated_cost_units) / mc.baseline_cost_units : null;
 
+    const q = report.quality;
+    q.first_pass_success_rate = q.first_pass_lines > 0 ? q.first_pass_success_count / q.first_pass_lines : null;
+    q.escalation_rate = q.escalated_lines > 0 ? q.escalated_count / q.escalated_lines : null;
+
     // Honest caveats — always attached so a consumer never over-reads the number.
     if (report.dispatches === 0) {
         report.notes.push('No orchestration telemetry yet (0 dispatches). Data accrues as `subagents.auto: on` delegates real slices (recorded via orchestration_record).');
@@ -174,6 +223,9 @@ export function aggregateOrchestrationSavings(
         } else {
             report.notes.push('MODELED cost-% unavailable: no dispatch yet carries dispatch_tokens + session_tier + tier_chosen. Record those (orchestration_record --dispatch-tokens/--session-tier/--tier-chosen) to populate it.');
         }
+        if (q.quality_lines === 0) {
+            report.notes.push('QUALITY columns empty: no dispatch yet carries first_pass_success / escalated. Record them (orchestration_record --first-pass-success/--escalated) — cost and quality are reported as a PAIR, never savings alone.');
+        }
     }
 
     return report;

package/src/scripts/check_release_adjacent_health.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env tsx
+/**
+ * Release-adjacent workflow health tripwire — road-to-proof-under-real-conditions
+ * Phase 1. The "red for five releases without anyone noticing" detector:
+ * the MCP worker deploy failed on every release from one minor line to the
+ * next and nothing surfaced it, because post-tag workflows are nobody's PR.
+ *
+ * For each watched workflow, look at its most recent COMPLETED run on the
+ * default branch (any trigger). If that run's conclusion is not `success`
+ * and it finished more than --max-red-hours ago (default 48) with no newer
+ * successful run, the workflow counts as durably red → exit 1 and print a
+ * GitHub error annotation per offender. The calling workflow turns that
+ * into a visible failure on main.
+ *
+ * Auth: GITHUB_TOKEN (or GH_TOKEN) env. Repo: GITHUB_REPOSITORY env or
+ * --repo owner/name.
+ *
+ * Exit codes: 0 all green/absent · 1 durably-red workflow(s) · 2 usage/env.
+ */
+
+import { argv, env, exit } from 'node:process';
+
+const WATCHED = [
+    'publish-npm.yml',
+    'deploy-mcp-worker.yml',
+    'deploy-site.yml',
+    'site.yml',
+    'consumer-matrix.yml',
+    'release.yml',
+] as const;
+
+interface RunInfo {
+    conclusion: string | null;
+    updated_at: string;
+    html_url: string;
+}
+
+async function latestCompletedRun(
+    repo: string,
+    token: string,
+    workflow: string,
+    branch: string,
+): Promise<RunInfo | null> {
+    const url =
+        `https://api.github.com/repos/${repo}/actions/workflows/${workflow}/runs` +
+        `?status=completed&per_page=1${branch ? `&branch=${branch}` : ''}`;
+    const res = await fetch(url, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28',
+        },
+    });
+    if (res.status === 404) return null; // workflow not present (yet)
+    if (!res.ok) throw new Error(`GitHub API ${res.status} for ${workflow}: ${await res.text()}`);
+    const body = (await res.json()) as { workflow_runs?: RunInfo[] };
+    return body.workflow_runs?.[0] ?? null;
+}
+
+async function main(): Promise<number> {
+    const args = argv.slice(2);
+    const getOpt = (flag: string): string | undefined => {
+        const i = args.indexOf(flag);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const token = env.GITHUB_TOKEN ?? env.GH_TOKEN ?? '';
+    const repo = getOpt('--repo') ?? env.GITHUB_REPOSITORY ?? '';
+    const maxRedHours = Number(getOpt('--max-red-hours') ?? '48');
+    if (!token || !repo) {
+        process.stderr.write('❌  release-adjacent-health: GITHUB_TOKEN and GITHUB_REPOSITORY (or --repo) required.\n');
+        return 2;
+    }
+
+    // Tag/release-triggered workflows have no branch association — query
+    // without the branch filter for those; branch-scoped for PR/push ones.
+    const branchless = new Set(['publish-npm.yml', 'deploy-mcp-worker.yml', 'release.yml']);
+    let red = 0;
+    for (const wf of WATCHED) {
+        let run: RunInfo | null;
+        try {
+            run = await latestCompletedRun(repo, token, wf, branchless.has(wf) ? '' : 'main');
+        } catch (err) {
+            process.stderr.write(`⚠️  ${wf}: ${(err as Error).message}\n`);
+            continue; // transient API failure must not fake a red
+        }
+        if (!run) {
+            process.stderr.write(`·   ${wf}: no completed runs (or workflow absent) — skipping\n`);
+            continue;
+        }
+        if (run.conclusion === 'success') {
+            process.stderr.write(`✅  ${wf}: last completed run green\n`);
+            continue;
+        }
+        const ageHours = (Date.now() - Date.parse(run.updated_at)) / 3_600_000;
+        if (ageHours >= maxRedHours) {
+            process.stdout.write(
+                `::error::release-adjacent workflow durably red: ${wf} — last completed run ` +
+                    `'${run.conclusion}' ${ageHours.toFixed(0)}h ago with no newer success. ${run.html_url}\n`,
+            );
+            red += 1;
+        } else {
+            process.stderr.write(
+                `⚠️  ${wf}: last run '${run.conclusion}' ${ageHours.toFixed(0)}h ago (< ${maxRedHours}h window)\n`,
+            );
+        }
+    }
+    if (red > 0) {
+        process.stderr.write(`❌  ${red} release-adjacent workflow(s) durably red.\n`);
+        return 1;
+    }
+    process.stderr.write('✅  release-adjacent workflows healthy.\n');
+    return 0;
+}
+
+main().then(
+    (code) => exit(code),
+    (err) => {
+        process.stderr.write(`❌  release-adjacent-health crashed: ${(err as Error).stack ?? err}\n`);
+        exit(2);
+    },
+);

package/src/scripts/check_rule_invariants.ts

@@ -0,0 +1,275 @@
+#!/usr/bin/env tsx
+/**
+ * Kernel semantic-invariants checker.
+ *
+ * Counterfactual (2026-07-10): PRs #840/#844 showed MERGED on GitHub but their
+ * content vanished from main (merge commits unreachable after a history repair);
+ * re-landed as #847 (13f244c9b — non-destructive "Irreversible external action"
+ * row + "Never act while asking" clause) and #849 (2c46e7f3b — direct-answers
+ * "no duration estimates" + "never cite the rule"). This checker's invariant set
+ * covers those exact strings — it would have flagged the loss at CI time.
+ *
+ * Loads `tests/golden/invariants.json` and verifies that every invariant
+ * string (whitespace-normalised: runs of whitespace collapse to a single
+ * space) is present in BOTH the kernel rule's `src/rules/` source and its
+ * `dist/agent-src/rules/` projection. A missing string means a rule's
+ * behaviour guarantee was silently lost in a merge / condensation pass.
+ *
+ * Kernel set: docs/contracts/kernel-membership.md § 4 (9 locked rules).
+ *
+ * Usage:
+ *   npx tsx src/scripts/check_rule_invariants.ts [--root ROOT]
+ *   npx tsx src/scripts/check_rule_invariants.ts --mutation-selftest
+ *
+ * `--mutation-selftest` picks the first invariant and verifies the check
+ * WOULD fail if that string were absent (in-memory mutation) — guards the
+ * checker itself against a silently-green normalisation bug.
+ *
+ * Exit codes: 0 = clean / selftest passed, 1 = missing invariant(s) or
+ * selftest failure, 2 = usage error, 3 = internal error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// src/scripts/check_rule_invariants.ts → two dirs up is the repo root.
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+const INVARIANTS_JSON = 'tests/golden/invariants.json';
+
+interface InvariantEntry {
+    rule: string;
+    file: string;
+    dist: string;
+    strings: string[];
+}
+
+interface Miss {
+    rule: string;
+    file: string;
+    invariant: string;
+}
+
+/** Collapse every run of whitespace (incl. newlines) to a single space. */
+function normalize(text: string): string {
+    return text.replace(/\s+/g, ' ').trim();
+}
+
+function loadEntries(root: string): InvariantEntry[] {
+    const p = path.join(root, INVARIANTS_JSON);
+    const raw = fs.readFileSync(p, 'utf-8');
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) {
+        throw new Error(`${INVARIANTS_JSON}: expected a top-level array`);
+    }
+    for (const entry of parsed as InvariantEntry[]) {
+        if (
+            typeof entry.rule !== 'string' ||
+            typeof entry.file !== 'string' ||
+            typeof entry.dist !== 'string' ||
+            !Array.isArray(entry.strings) ||
+            entry.strings.some((s) => typeof s !== 'string' || s.length === 0)
+        ) {
+            throw new Error(
+                `${INVARIANTS_JSON}: malformed entry ${JSON.stringify(entry.rule ?? entry)}`,
+            );
+        }
+    }
+    return parsed as InvariantEntry[];
+}
+
+/** Check one entry against pre-normalised file contents. */
+function checkEntry(
+    entry: InvariantEntry,
+    normalizedByFile: ReadonlyMap<string, string>,
+): Miss[] {
+    const misses: Miss[] = [];
+    for (const target of [entry.file, entry.dist]) {
+        const haystack = normalizedByFile.get(target);
+        if (haystack === undefined) {
+            for (const s of entry.strings) {
+                misses.push({ rule: entry.rule, file: target, invariant: s });
+            }
+            continue;
+        }
+        for (const s of entry.strings) {
+            if (!haystack.includes(normalize(s))) {
+                misses.push({ rule: entry.rule, file: target, invariant: s });
+            }
+        }
+    }
+    return misses;
+}
+
+function readNormalized(root: string, entries: readonly InvariantEntry[]): Map<string, string> {
+    const out = new Map<string, string>();
+    for (const entry of entries) {
+        for (const target of [entry.file, entry.dist]) {
+            if (out.has(target)) {
+                continue;
+            }
+            const p = path.join(root, target);
+            try {
+                out.set(target, normalize(fs.readFileSync(p, 'utf-8')));
+            } catch {
+                // Leave absent — checkEntry reports every string as missing.
+            }
+        }
+    }
+    return out;
+}
+
+function scan(root: string): Miss[] {
+    const entries = loadEntries(root);
+    const normalizedByFile = readNormalized(root, entries);
+    const misses: Miss[] = [];
+    for (const entry of entries) {
+        misses.push(...checkEntry(entry, normalizedByFile));
+    }
+    return misses;
+}
+
+function formatText(misses: Miss[], invariantCount: number): string {
+    if (misses.length === 0) {
+        return `✅  All ${invariantCount} kernel rule invariants present in src + dist.`;
+    }
+    const lines: string[] = [
+        `❌  ${misses.length} missing kernel rule invariant(s):\n`,
+    ];
+    for (const m of misses) {
+        lines.push(`  🔴 ${m.rule} — ${m.file}\n     missing: "${m.invariant}"`);
+    }
+    lines.push(
+        '\nA kernel rule lost a load-bearing clause — likely a merge or condensation ' +
+            'dropped it silently (see the #840/#844 incident in this file header). ' +
+            'Restore the clause or deliberately update tests/golden/invariants.json.',
+    );
+    return lines.join('\n');
+}
+
+/**
+ * Mutation self-test: remove the first invariant string from its src file's
+ * content in-memory and verify the check catches the absence.
+ */
+function mutationSelftest(root: string): number {
+    const entries = loadEntries(root);
+    const first = entries[0];
+    if (first === undefined || first.strings[0] === undefined) {
+        process.stderr.write('mutation-selftest: no invariants defined\n');
+        return 1;
+    }
+    const invariant = first.strings[0];
+    const p = path.join(root, first.file);
+    const original = normalize(fs.readFileSync(p, 'utf-8'));
+    const needle = normalize(invariant);
+    if (!original.includes(needle)) {
+        process.stderr.write(
+            `mutation-selftest: baseline broken — "${invariant}" not present in ${first.file}\n`,
+        );
+        return 1;
+    }
+    const mutated = original.split(needle).join('');
+    if (mutated.includes(needle)) {
+        process.stderr.write('mutation-selftest: mutation did not remove the string\n');
+        return 1;
+    }
+    // Run the REAL check path against the mutated content: swap the src
+    // file's normalised content in-memory and assert checkEntry reports
+    // the removed invariant as missing.
+    const normalizedByFile = readNormalized(root, [first]);
+    normalizedByFile.set(first.file, mutated);
+    const misses = checkEntry(first, normalizedByFile);
+    const detected = misses.some(
+        (m) => m.file === first.file && m.invariant === invariant,
+    );
+    if (!detected) {
+        process.stderr.write(
+            `mutation-selftest: FAILED — removing "${invariant}" from ${first.file} was NOT detected\n`,
+        );
+        return 1;
+    }
+    process.stdout.write(
+        `✅  mutation-selftest passed: removing "${invariant}" from ${first.file} is detected.\n`,
+    );
+    return 0;
+}
+
+interface ParsedArgs {
+    root: string;
+    mutationSelftest: boolean;
+}
+
+function parse_args(argv: readonly string[]): ParsedArgs {
+    let root = ROOT;
+    let selftest = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i]!;
+        if (arg === '--root') {
+            const v = argv[++i];
+            if (v === undefined) {
+                _argparse_error('argument --root: expected one argument');
+            }
+            root = v;
+        } else if (arg.startsWith('--root=')) {
+            root = arg.slice('--root='.length);
+        } else if (arg === '--mutation-selftest') {
+            selftest = true;
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write(
+                'usage: check_rule_invariants [-h] [--root ROOT] [--mutation-selftest]\n',
+            );
+            process.exit(0);
+        } else {
+            _argparse_error(`unrecognized arguments: ${arg}`);
+        }
+    }
+    return { root, mutationSelftest: selftest };
+}
+
+function _argparse_error(message: string): never {
+    process.stderr.write(`check_rule_invariants: error: ${message}\n`);
+    process.exit(2);
+}
+
+function main(): number {
+    const args = parse_args(process.argv.slice(2));
+    try {
+        if (args.mutationSelftest) {
+            return mutationSelftest(args.root);
+        }
+        const entries = loadEntries(args.root);
+        const invariantCount = entries.reduce((n, e) => n + e.strings.length, 0);
+        const misses = scan(args.root);
+        process.stdout.write(formatText(misses, invariantCount) + '\n');
+        return misses.length ? 1 : 0;
+    } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`Internal error: ${msg}\n`);
+        return 3;
+    }
+}
+
+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 {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { type InvariantEntry, type Miss, ROOT, INVARIANTS_JSON, normalize, scan, main };