@event4u/agent-config 8.13.0 → 9.1.0

package/src/scripts/smoke_host_loadability.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# smoke_host_loadability.sh — real-host loadability smoke
+# (road-to-ecosystem-harvest-skill-quality-gates Phase 4, Source G).
+#
+# The static check (check_host_loadability.ts) proves the generated trees
+# PARSE; this smoke proves the real Claude Code CLI actually ACCEPTS them:
+#
+#   1. `claude plugin validate .claude-plugin` — the host's own validator on
+#      the marketplace manifest + plugin dirs.
+#   2. Temp-home install: add this repo as a marketplace in a throwaway HOME,
+#      install the bootstrap-shim plugin, assert it shows up in
+#      `claude plugin list`. Nothing touches the developer's real ~/.claude.
+#   3. Metadata cross-consistency (marketplace ↔ plugin dirs ↔ docs):
+#      lint_marketplace + lint_marketplace_install_completeness +
+#      lint_supported_tools_matrix + check_host_loadability.
+#
+# Contract: OPTIONAL in CI (runners without the claude CLI skip with exit 0
+# and a notice), REQUIRED before releases — pass --require to make a missing
+# CLI a failure (wired into the release flow, see docs/contracts/release-pr-gating.md).
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+REQUIRE=0
+for arg in "$@"; do
+  case "$arg" in
+    --require) REQUIRE=1 ;;
+    *) echo "usage: smoke_host_loadability.sh [--require]" >&2; exit 2 ;;
+  esac
+done
+
+CLAUDE_BIN="${CLAUDE_CLI:-$(command -v claude || true)}"
+if [ -n "$CLAUDE_BIN" ] && [ ! -x "$CLAUDE_BIN" ]; then
+  CLAUDE_BIN=""
+fi
+if [ -z "$CLAUDE_BIN" ]; then
+  if [ "$REQUIRE" -eq 1 ]; then
+    echo "❌  claude CLI not found and --require set (release gate). Install Claude Code or set CLAUDE_CLI." >&2
+    exit 1
+  fi
+  echo "⚠️  claude CLI not found — real-host smoke skipped (static checks still run)."
+  ./scripts-run src/scripts/check_host_loadability --root .
+  ./scripts-run src/scripts/lint_supported_tools_matrix
+  exit 0
+fi
+
+MARKETPLACE_NAME="$(node -e "console.log(JSON.parse(require('node:fs').readFileSync('.claude-plugin/marketplace.json','utf8')).name)")"
+PLUGIN_NAME="$(node -e "console.log(JSON.parse(require('node:fs').readFileSync('.claude-plugin/marketplace.json','utf8')).plugins[0].name)")"
+
+echo "→ 1/3 host-CLI manifest validation (claude plugin validate)"
+# validate expects the directory that CONTAINS .claude-plugin/.
+"$CLAUDE_BIN" plugin validate "$REPO_ROOT"
+
+echo "→ 2/3 temp-home install + load assertion (${PLUGIN_NAME}@${MARKETPLACE_NAME})"
+TMP_HOME="$(mktemp -d)"
+cleanup() { rm -rf "$TMP_HOME"; }
+trap cleanup EXIT
+export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-}"
+HOME="$TMP_HOME" "$CLAUDE_BIN" plugin marketplace add "$REPO_ROOT"
+HOME="$TMP_HOME" "$CLAUDE_BIN" plugin install "${PLUGIN_NAME}@${MARKETPLACE_NAME}"
+if ! HOME="$TMP_HOME" "$CLAUDE_BIN" plugin list | grep -q "$PLUGIN_NAME"; then
+  echo "❌  plugin '${PLUGIN_NAME}' not listed after temp-home install — host did not load it" >&2
+  exit 1
+fi
+
+echo "→ 3/3 metadata cross-consistency (marketplace ↔ plugin dirs ↔ docs)"
+./scripts-run src/scripts/lint_marketplace
+./scripts-run src/scripts/lint_marketplace_install_completeness
+./scripts-run src/scripts/lint_supported_tools_matrix
+./scripts-run src/scripts/check_host_loadability --root .
+
+echo "✅  host-loadability smoke green (validate + temp-home install + cross-consistency)"

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.',
@@ -335,6 +343,21 @@ export const settingsSchema = z.object({
             preview_description: z.boolean().default(false).describe(
                 'When /create-pr runs, show the generated title and body and wait for confirmation before opening the PR. Off by default (zero-friction PR creation); turn on if you want a last-look gate.',
             ),
+            detail_level: z.enum(['min', 'med', 'max']).default('min').describe(
+                'Verbosity tier for the generated PR description body. min (default) = title + 2-3 sentence what/why/impact + linked ticket (token-frugal); med = min + grouped changes + tests note; max = med + how-to-test + edge cases + reviewer guidance. Critical info (breaking changes, migrations, security, rollback) is ALWAYS included at every tier — the tier governs explanatory depth, never whether a critical callout appears.',
+            ),
+            api_examples: z.boolean().default(true).describe(
+                'JSON request/response examples for API-endpoint changes. true (default) = include a fenced example ONLY when grounded in a real source (response DTO/resource, OpenAPI/schema, test fixture, or an actual probe); no grounded source → a one-line pointer, never an invented example. false = never add API examples.',
+            ),
+            screenshots: z.boolean().default(false).describe(
+                'Screenshots for frontend changes. false (default) = never attempt. true = attempt when the host has browser/preview tooling and the diff touches a frontend surface; capability-gated (emits a one-line note and leaves the placeholder when tooling is absent, never fails or blocks the PR). Before/after + changed-region highlighting is best-effort.',
+            ),
+            ui_paths: z.array(z.string()).default([]).describe(
+                'Optional glob list that makes frontend detection explicit instead of heuristic (e.g. ["resources/views/**", "src/pages/**"]). Empty (default) = a light path/extension heuristic that fails open (no false enrichment when the surface is ambiguous).',
+            ),
+            api_paths: z.array(z.string()).default([]).describe(
+                'Optional glob list that makes API-endpoint detection explicit instead of heuristic (e.g. ["app/Http/Controllers/Api/**", "src/pages/api/**"]). Empty (default) = a light path/extension heuristic that fails open.',
+            ),
         }),
     }),
     memory: z.object({