@event4u/agent-config 8.13.0 → 9.0.0

package/src/scripts/team_review_gate_hook.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * Team Review-Gate governance — `stop` concern (road-to-team-mode Phase 4).
+ *
+ * Minimal call-site for `src/scripts/ai_team/review_gate.ts`. On Stop it
+ * reads the dispatcher envelope, and — ONLY when `ai_team.enabled` AND
+ * `ai_team.review_gate.managed` are true — locates the newest stop-gate
+ * review job the codex plugin persisted for this session, parses its
+ * first-line ALLOW/BLOCK contract, applies the consecutive-BLOCK counter,
+ * and prints the circuit-breaker notice (exactly once per trip) to stdout
+ * for the dispatch layer to render. With `managed: false` (default) the
+ * hook exits 0 without touching anything — byte-identical pre-Phase-4
+ * Stop behavior.
+ *
+ * Composition point (documented, not yet wired): register this script as a
+ * `team-review-gate` concern in `src/scripts/hook_manifest.yaml` on the
+ * claude / cowork `stop` slots, after `chat-history` (ordering relative to
+ * the PLUGIN's own Stop hook is host-scheduled and irrelevant here — the
+ * verdict is read from the plugin's persisted job record, not from sibling
+ * hook output). Manifest registration drags the lint_hook_manifest +
+ * installer + tests/hooks snapshot surface, so it is left to the
+ * orchestrator; this file is dispatcher-shaped and drop-in ready.
+ *
+ * Contract: never blocks, exit 0 on every path, `fail_closed: false`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    find_latest_gate_transcript,
+    record_gate_verdict,
+} from './ai_team/review_gate.js';
+import { AI_TEAM_DEFAULTS, load_ai_team_config, type AiTeamConfig } from './ai_team/config.js';
+import { unwrap } from './hooks/envelope.js';
+
+function _read_stdin(): string {
+    try {
+        if (process.stdin.isTTY) {
+            return '';
+        }
+        return fs.readFileSync(0, 'utf-8');
+    } catch {
+        return '';
+    }
+}
+
+export function main(): number {
+    const [envelope] = unwrap(_read_stdin(), 'claude');
+
+    const event = String(envelope['event'] ?? '');
+    if (event !== '' && event !== 'stop') {
+        return 0;
+    }
+
+    const workspace_root =
+        String(envelope['workspace_root'] ?? '').trim() || process.cwd();
+    const session_id = String(envelope['session_id'] ?? '');
+
+    let config: AiTeamConfig;
+    try {
+        config = load_ai_team_config({ cwd: workspace_root });
+    } catch {
+        // A broken ai_team block must never break the Stop path — doctor
+        // owns reporting it. Defaults = managed off = strict no-op.
+        config = AI_TEAM_DEFAULTS;
+    }
+    if (!config.enabled || !config.review_gate.managed) {
+        return 0;
+    }
+
+    let notice: string | null = null;
+    try {
+        const gate = find_latest_gate_transcript(workspace_root, session_id);
+        if (gate === null) {
+            return 0; // no gate run this session — nothing to govern
+        }
+        const outcome = record_gate_verdict({
+            session_id,
+            transcript_text: gate.transcript,
+            dedupe_key: gate.job_id,
+            config,
+            project_root: workspace_root,
+        });
+        notice = outcome.notice;
+    } catch {
+        return 0; // fail-open — never block the agent loop
+    }
+
+    if (notice !== null) {
+        process.stdout.write(`${notice}\n`);
+    }
+    return 0;
+}
+
+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.exit(main());
+}

package/src/scripts/trigger_eval_grandfather.json

@@ -1,5 +1,5 @@
 {
-    "_note": "Shrink-only grandfather allowlist for check_trigger_eval_presence (road-to-composition-ratchet). Skills listed here predate the trigger-eval presence gate and may lack evals/triggers.json. Entries may ONLY be removed (when the skill gains a triggers.json or is deleted) — never added. Frozen 2026-07-08 at 221 of 264 skills.",
+    "_note": "Shrink-only grandfather allowlist for check_trigger_eval_presence (road-to-composition-ratchet). Skills listed here predate the trigger-eval presence gate and may lack evals/triggers.json. Entries may ONLY be removed (when the skill gains a triggers.json or is deleted) \u2014 never added. Frozen 2026-07-08 at 221 of 264 skills.",
     "skills": [
         "accessibility-auditor",
         "activation-design",
@@ -64,7 +64,6 @@
         "emit-tickets",
         "error-handling-patterns",
         "expansion-playbook",
-        "fe-design",
         "feature-planning",
         "file-editor",
         "finishing-a-development-branch",

package/src/scripts/utilization_report.ts

@@ -0,0 +1,225 @@
+/**
+ * utilization_report.ts — U1 loaded-vs-fired utilization report
+ * (road-to-ecosystem-harvest-reliability-measurement, P1).
+ *
+ * PRIVACY: session engagement logs are personal data. This tool is
+ * LOCAL-ONLY and REPORT-ONLY by default — it is deliberately NOT wired into
+ * `task ci`; the opt-in gate flags below are for a consumer's own CI, never
+ * this repo's. The report header restates this.
+ *
+ * Consumes (never redefines) the pre-registered window criteria at
+ * docs/design/utilization-window-criteria.md (CLAIMS
+ * `utilization-window-decidability`):
+ *   floor  — ≥ 100 task/phase-step boundaries · ≥ 2 recording periods ≥ 14
+ *            days apart (host identity is not in the schema) · ≥ 45 days
+ *            since 2026-07-12. Below floor → UNDERPOWERED report, no verdicts.
+ *   D1     — loaded-never-consulted over the window → retirement candidate
+ *            (REAP verdict; kernel + safety floors exempt by construction).
+ *            Without the U1a denominator in the data the report degrades to
+ *            consulted-set analysis and says so.
+ *   D2     — consulted-never-applied with ≥ 5 consultations and
+ *            applied-ratio < 10% → trigger-review queue (REVIEW verdict).
+ *   D3/D4  — above floor: ≥ 1 named decision per artifact kind (or a stated
+ *            reason); below floor: honest null, gates stay closed.
+ *
+ * Verdicts: REAP (cut candidate — reversible quarantine with a manifest,
+ * never hard delete), KEEP, REVIEW. Session floor: no verdict below
+ * MIN_SESSIONS distinct task_ids — absence of evidence is not evidence of
+ * absence.
+ *
+ * Opt-in CI-gate flags (consumer-side only): --fail-under-utilization <pct>
+ * exits 3 when overall fired/loaded falls below the threshold;
+ * --fail-on-stale-days <n> exits 3 when the newest event is older than n
+ * days. Neither flag is used in this repo's pipelines.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { aggregate } from '../agent-src/templates/scripts/telemetry/aggregator.js';
+
+export const WINDOW_START_ISO = '2026-07-12T00:00:00Z';
+export const FLOOR_BOUNDARIES = 100;
+export const FLOOR_ELAPSED_DAYS = 45;
+export const FLOOR_PERIOD_GAP_DAYS = 14;
+export const MIN_SESSIONS = 4; // session floor for any verdict
+export const D2_MIN_CONSULTED = 5;
+export const D2_APPLIED_RATIO_LT = 0.10;
+
+export interface VerdictRow {
+    kind: string;
+    id: string;
+    loaded: number;
+    consulted: number;
+    applied: number;
+    verdict: 'REAP' | 'KEEP' | 'REVIEW';
+    rule: 'D1' | 'D2' | '—';
+}
+
+export interface KernelInfo {
+    kernel: Set<string>;
+    safety_floors: Set<string>;
+}
+
+/** Kernel rule ids (type: always / alwaysApply) + *-safety-floor ids — exempt from REAP. */
+export function read_exempt(rulesDir: string): KernelInfo {
+    const kernel = new Set<string>();
+    const safety = new Set<string>();
+    for (const name of fs.readdirSync(rulesDir)) {
+        if (!name.endsWith('.md')) continue;
+        const id = name.replace(/\.md$/, '');
+        if (id.endsWith('-safety-floor')) safety.add(id);
+        const head = fs.readFileSync(path.join(rulesDir, name), 'utf-8').slice(0, 400);
+        if (/^type:\s*["']?always["']?/m.test(head) || /^alwaysApply:\s*true/m.test(head)) {
+            kernel.add(id);
+        }
+    }
+    return { kernel, safety_floors: safety };
+}
+
+export function decide(
+    row: { kind: string; id: string; loaded: number; consulted: number; applied: number },
+    exempt: KernelInfo,
+    sessions: number,
+): VerdictRow {
+    const base = { ...row } as VerdictRow;
+    if (sessions < MIN_SESSIONS) {
+        base.verdict = 'KEEP';
+        base.rule = '—';
+        return base; // below the session floor no negative verdict is allowed
+    }
+    const isExempt = row.kind === 'rules'
+        && (exempt.kernel.has(row.id) || exempt.safety_floors.has(row.id));
+    if (row.loaded > 0 && row.consulted === 0 && !isExempt) {
+        base.verdict = 'REAP';
+        base.rule = 'D1';
+        return base;
+    }
+    if (row.consulted >= D2_MIN_CONSULTED && row.applied / row.consulted < D2_APPLIED_RATIO_LT) {
+        base.verdict = 'REVIEW';
+        base.rule = 'D2';
+        return base;
+    }
+    base.verdict = 'KEEP';
+    base.rule = '—';
+    return base;
+}
+
+interface FloorState {
+    boundaries: number;
+    sessions: number;
+    elapsed_days: number;
+    periods_ok: boolean;
+    above_floor: boolean;
+    has_loaded: boolean;
+}
+
+function day_diff(aIso: string, bIso: string): number {
+    return Math.abs(Date.parse(aIso) - Date.parse(bIso)) / 86_400_000;
+}
+
+export function assess_floor(logPath: string): FloorState {
+    const agg = aggregate(logPath);
+    // sessions = distinct task_ids; boundaries = parsed events. Recording
+    // periods: earliest vs latest ts ≥ FLOOR_PERIOD_GAP_DAYS apart (the
+    // schema-preserving degradation recorded in the criteria doc).
+    const text = fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf-8') : '';
+    const taskIds = new Set<string>();
+    for (const line of text.split('\n')) {
+        const m = line.match(/"task_id":"([^"]+)"/);
+        if (m) taskIds.add(m[1] ?? '');
+    }
+    const elapsed = agg.latest_ts ? day_diff(WINDOW_START_ISO, agg.latest_ts) : 0;
+    const periodsOk = agg.earliest_ts !== null && agg.latest_ts !== null
+        && day_diff(agg.earliest_ts, agg.latest_ts) >= FLOOR_PERIOD_GAP_DAYS;
+    return {
+        boundaries: agg.parsed_events,
+        sessions: taskIds.size,
+        elapsed_days: Math.floor(elapsed),
+        periods_ok: periodsOk,
+        above_floor: agg.parsed_events >= FLOOR_BOUNDARIES && periodsOk
+            && elapsed >= FLOOR_ELAPSED_DAYS,
+        has_loaded: agg.loaded_events > 0,
+    };
+}
+
+export async function main(argv: string[]): Promise<number> {
+    const arg = (flag: string): string | null => {
+        const i = argv.indexOf(flag);
+        return i !== -1 ? argv[i + 1] ?? null : null;
+    };
+    const logPath = arg('--log') ?? '.agent-engagement.jsonl';
+    const rulesDir = arg('--rules-dir') ?? 'dist/agent-src/rules';
+    const failUnder = arg('--fail-under-utilization');
+    const failStale = arg('--fail-on-stale-days');
+    const out: string[] = [];
+    out.push('# Utilization report — loaded vs fired');
+    out.push('');
+    out.push('> LOCAL-ONLY, REPORT-ONLY. Session transcripts/engagement logs are personal');
+    out.push('> data; this tool never runs in `task ci` and its output stays out of git.');
+    out.push('> Criteria consumed from docs/design/utilization-window-criteria.md — the');
+    out.push('> report applies D1-D4, it does not redefine them. A REAP verdict is a');
+    out.push('> QUARANTINE candidate (reversible move + manifest: what/when/why/restore),');
+    out.push('> never a hard delete.');
+    out.push('');
+
+    const floor = assess_floor(logPath);
+    out.push(`- boundaries recorded: ${floor.boundaries} (floor ${FLOOR_BOUNDARIES})`);
+    out.push(`- distinct sessions: ${floor.sessions} (verdict floor ${MIN_SESSIONS})`);
+    out.push(`- recording span ≥ ${FLOOR_PERIOD_GAP_DAYS}d: ${floor.periods_ok}`);
+    out.push(`- loaded denominator present: ${floor.has_loaded}${floor.has_loaded ? '' : ' — D1 degrades to consulted-set analysis (stated per the criteria doc)'}`);
+    out.push('');
+
+    const agg = aggregate(logPath);
+    const exempt = read_exempt(rulesDir);
+    const rows = agg.stats().map((s) => decide(
+        { kind: s.kind, id: s.artefact_id, loaded: s.loaded, consulted: s.consulted, applied: s.applied },
+        exempt,
+        floor.sessions,
+    ));
+
+    if (!floor.above_floor) {
+        out.push('## Verdict: UNDERPOWERED (window floor not met — D4 path)');
+        out.push('');
+        out.push('No REAP/REVIEW verdicts are issued below the observation floor;');
+        out.push('lifecycle-automation and field-outcome-ledger gates stay closed.');
+        out.push('Interim observed counts follow (informational only):');
+    } else {
+        out.push('## Verdicts (D3 path — above floor)');
+    }
+    out.push('');
+    out.push('| kind | id | loaded | consulted | applied | verdict | rule |');
+    out.push('|---|---|---:|---:|---:|---|---|');
+    const ranked = [...rows].sort((a, b) => (a.consulted - b.consulted) || (b.loaded - a.loaded));
+    for (const r of ranked) {
+        const verdict = floor.above_floor ? r.verdict : '—';
+        const rule = floor.above_floor ? r.rule : '—';
+        out.push(`| ${r.kind} | \`${r.id}\` | ${r.loaded} | ${r.consulted} | ${r.applied} | ${verdict} | ${rule} |`);
+    }
+    process.stdout.write(`${out.join('\n')}\n`);
+
+    // Opt-in consumer CI gates (exit 3) — never wired in this repo.
+    if (failUnder !== null) {
+        const totLoaded = rows.reduce((n, r) => n + r.loaded, 0);
+        const totFired = rows.reduce((n, r) => n + (r.loaded > 0 && r.consulted > 0 ? 1 : 0), 0);
+        const denom = rows.filter((r) => r.loaded > 0).length;
+        const pct = denom > 0 && totLoaded > 0 ? (totFired / denom) * 100 : 100;
+        if (pct < Number(failUnder)) return 3;
+    }
+    if (failStale !== null && agg.latest_ts !== null) {
+        if (day_diff(agg.latest_ts, new Date().toISOString()) > Number(failStale)) return 3;
+    }
+    return 0;
+}
+
+const isMain = process.argv[1] !== undefined
+    && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+if (isMain) {
+    main(process.argv.slice(2)).then(
+        (code) => process.exit(code),
+        (err) => {
+            process.stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+            process.exit(1);
+        },
+    );
+}

package/src/server/schemas/settings.ts

@@ -304,7 +304,15 @@ export const settingsSchema = z.object({
         suppress_setup_hint: z.boolean().default(false).describe(
             'Suppress the one-line wizard/init recommendation to set up the codex plugin on Claude-Code hosts. Cosmetic only — never changes behavior.',
         ),
-    }).default({ enabled: false, model: 'auto', allow_delegate: false, max_calls_per_day: 50, suppress_setup_hint: false }),
+        review_gate: z.object({
+            managed: z.boolean().default(false).describe(
+                "Managed governance of the codex plugin's Stop-hook Review Gate (road-to-team-mode Phase 4). false (default) = byte-identical pre-Phase-4 behavior: no counting, no circuit breaker. true = count consecutive BLOCK verdicts per session and trip the circuit breaker at max_consecutive_blocks.",
+            ),
+            max_consecutive_blocks: z.number().int().min(1).default(3).describe(
+                'Circuit-breaker bound: after this many CONSECUTIVE BLOCK verdicts in one session, a visible notice is injected exactly once and the managed layer stops re-blocking — the user decides, never an infinite Claude↔Codex loop. An ALLOW verdict resets the counter. Positive integer.',
+            ),
+        }).default({ managed: false, max_consecutive_blocks: 3 }),
+    }).default({ enabled: false, model: 'auto', allow_delegate: false, max_calls_per_day: 50, suppress_setup_hint: false, review_gate: { managed: false, max_consecutive_blocks: 3 } }),
     onboarding: z.object({
         onboarded: z.boolean().default(false).describe(
             'Set to true once the developer has completed `agent-config setup`. The onboarding-gate rule blocks the first turn of every chat until this is true. Toggle back to false to re-trigger the wizard.',