@event4u/agent-config 8.12.0 → 9.0.0

package/src/scripts/_cli/cmd_doctor.ts

@@ -29,7 +29,7 @@
  * scope · global-binary · claude-plugin · stale-orphans · manifest-integrity ·
  * lockfile-freshness · bridge-drift · mcp-mode · mcp-beta-readiness ·
  * offline-readiness · python-runtime · humanizer-runtime · tier-usage-readiness ·
- * council-cli ·
+ * council-cli · team ·
  * unsupported-combos · wizard-state.
  * Each emits a structured `{id, status, message, remedy}` record with
  * `status` ∈ `ok` / `warn` / `fail` / `skipped` (rendered
@@ -99,6 +99,7 @@ import {
 } from '../_lib/agent_settings.js';
 import * as ai_council_clients from '../ai_council/clients.js';
 import * as ai_council_config from '../ai_council/config.js';
+import { review_gate_doctor_signal } from '../ai_team/review_gate.js';
 
 type Dict = Record<string, unknown>;
 
@@ -747,6 +748,7 @@ const CHECK_IDS = [
     'humanizer-runtime',
     'tier-usage-readiness',
     'council-cli',
+    'team',
     'unsupported-combos',
     'wizard-state',
     'settings-review-pending',
@@ -769,6 +771,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'humanizer-runtime',
     'tier-usage-readiness',
     'council-cli',
+    'team',
     'wizard-state',
     'settings-review-pending',
 ]);
@@ -1975,6 +1978,287 @@ function pyFloat(value: number): string {
     return String(value);
 }
 
+// ---------------------------------------------------------------------------
+// team check (road-to-team-mode Phase 1) — codex binary + auth, official
+// codex plugin on Claude-Code hosts, Review-Gate consistency.
+// ---------------------------------------------------------------------------
+
+/**
+ * Codex CLI home — `CODEX_HOME` env override (the codex CLI's own
+ * convention), else `~/.codex`.
+ */
+function _codex_home(): string {
+    const env = (process.env['CODEX_HOME'] ?? '').trim();
+    return env !== '' ? env : path.join(os.homedir(), '.codex');
+}
+
+/**
+ * Codex binary name for the team check — REUSES the council probe's binary
+ * discovery: when a council config exists and declares an enabled cli-mode
+ * `openai` member with a `binary` override, honour it; else the provider
+ * default from `_CLI_PROVIDER_META` (`codex`). Never throws — an unreadable
+ * or invalid council config falls back to the default binary (the council-cli
+ * check owns reporting that problem).
+ */
+function _team_codex_binary_name(project_root: string): string {
+    const default_bin = (_CLI_PROVIDER_META['openai'] as [string, boolean])[0];
+    const { load_council_config, resolve_config_path } = ai_council_config;
+    const council_path = resolve_config_path(project_root);
+    if (!pathExists(String(council_path))) {
+        return default_bin;
+    }
+    let cfg: ai_council_config.CouncilConfig;
+    try {
+        cfg = load_council_config(council_path);
+    } catch {
+        return default_bin;
+    }
+    const member = cfg.members.get('openai');
+    if (member && member.enabled && member.mode === 'cli' && member.binary) {
+        return member.binary;
+    }
+    return default_bin;
+}
+
+/** Settings-flag coercion shared with the tier-usage check (bool or string). */
+function _settings_flag(val: unknown): boolean {
+    if (typeof val === 'boolean') return val;
+    if (typeof val === 'string') {
+        return ['true', 'yes', 'on', '1'].includes(val.trim().toLowerCase());
+    }
+    return false;
+}
+
+/**
+ * Decode a JWT payload's `exp` claim (epoch seconds) — base64 decode only,
+ * NO signature verification, no network. Non-JWT / undecodable → null.
+ */
+function _jwt_exp(token: unknown): number | null {
+    if (typeof token !== 'string') return null;
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    try {
+        const payload: unknown = JSON.parse(
+            Buffer.from(parts[1] as string, 'base64url').toString('utf-8'),
+        );
+        if (typeof payload !== 'object' || payload === null) return null;
+        const exp = (payload as Record<string, unknown>)['exp'];
+        return typeof exp === 'number' && Number.isFinite(exp) && exp > 0 ? exp : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Coerce an explicit expiry field to epoch seconds (number or ISO string). */
+function _epoch_seconds(value: unknown): number | null {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+        // Heuristic: values past ~2286 in seconds are epoch milliseconds.
+        return value > 1e12 ? value / 1000 : value;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const ms = Date.parse(value);
+        return Number.isNaN(ms) ? null : ms / 1000;
+    }
+    return null;
+}
+
+/**
+ * Latest locally-derivable expiry (epoch seconds) from a codex `auth.json`,
+ * or null when none is derivable. Sources, all offline:
+ *
+ * - explicit `expires_at` / `expiry` / `exp` fields (top level; numbers in
+ *   seconds or ms, or ISO date strings), and
+ * - the `exp` claim of JWT tokens under `tokens.{access_token,id_token}`
+ *   (or the same keys top-level) — base64 payload decode only, never
+ *   signature verification.
+ *
+ * LATEST wins: the real codex auth.json holds a refresh_token, so an
+ * expired id_token sitting next to a live access_token is not an auth
+ * failure — WARN only when everything derivable is past.
+ */
+function _codex_auth_expiry(auth_path: string): number | null {
+    let data: unknown;
+    try {
+        data = JSON.parse(fs.readFileSync(auth_path, 'utf-8'));
+    } catch {
+        return null;
+    }
+    if (typeof data !== 'object' || data === null) return null;
+    const d = data as Record<string, unknown>;
+    const candidates: number[] = [];
+    for (const key of ['expires_at', 'expiry', 'exp']) {
+        const v = _epoch_seconds(d[key]);
+        if (v !== null) candidates.push(v);
+    }
+    const tokens_raw = d['tokens'];
+    const tokens =
+        typeof tokens_raw === 'object' && tokens_raw !== null && !Array.isArray(tokens_raw)
+            ? (tokens_raw as Record<string, unknown>)
+            : {};
+    for (const key of ['access_token', 'id_token']) {
+        const v = _jwt_exp(tokens[key] ?? d[key]);
+        if (v !== null) candidates.push(v);
+    }
+    return candidates.length > 0 ? Math.max(...candidates) : null;
+}
+
+/** The `ai_team` block from `.agent-settings.yml` — lenient, `{}` when absent. */
+function _read_ai_team_block(project_root: string): Dict {
+    const settings_file = project_settings_path(project_root);
+    if (!isFile(settings_file)) return {};
+    let content: string;
+    try {
+        content = readText0(settings_file);
+    } catch {
+        return {};
+    }
+    const loaded = yamlSafeLoad(content);
+    if (typeof loaded !== 'object' || loaded === null || Array.isArray(loaded)) return {};
+    const raw = (loaded as Dict)['ai_team'];
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return {};
+    return raw as Dict;
+}
+
+/**
+ * `team` health check — three sub-signals folded into one result:
+ *
+ * (a) codex binary present (council-probe binary discovery reused) AND
+ *     auth present. Auth is a READ-ONLY probe of `$CODEX_HOME/auth.json`
+ *     (default `~/.codex/auth.json`): presence, plus locally-derivable
+ *     expiry evidence (`_codex_auth_expiry` — explicit expiry fields or
+ *     JWT `exp` payloads; no network, no signature verification). Past
+ *     expiry → WARN; no derivable expiry → presence-only note in the
+ *     detail. Runtime expiry is still caught authoritatively by
+ *     `OpenAICliClient._AUTH_FAILURE_PATTERNS`.
+ * (b) on Claude-Code hosts (claude binary on PATH or the Claude config dir
+ *     present): the official codex plugin recorded in
+ *     `plugins/installed_plugins.json`, with namespace-resistant identity
+ *     via `codex_plugin_identity()` — a prefix match whose marketplace
+ *     source repo cannot be verified against `openai/codex-plugin-cc`
+ *     keeps ✅ but is annotated "identity not fully verified (prefix
+ *     match)". Detection is read-only — doctor never writes under
+ *     `~/.claude/`.
+ * (c) Review-Gate consistency: `ai_team.review_gate.managed` on while the
+ *     loop bound (`max_consecutive_blocks`, Phase 4 — unbuilt) is absent
+ *     → WARN.
+ *
+ * Absent feature ≠ broken feature: with `ai_team` absent or disabled the
+ * check reports ok ("team mode not configured (default-off)"); WARN fires
+ * only on failing sub-signals or inconsistent half-configured states.
+ */
+function _check_team(project_root: string): Dict {
+    const ai_team = _read_ai_team_block(project_root);
+    const enabled = _settings_flag(ai_team['enabled']);
+    const gateRaw = ai_team['review_gate'];
+    const gate =
+        typeof gateRaw === 'object' && gateRaw !== null && !Array.isArray(gateRaw)
+            ? (gateRaw as Dict)
+            : {};
+    const gate_managed = _settings_flag(gate['managed']);
+
+    if (!enabled) {
+        if (gate_managed) {
+            return {
+                id: 'team',
+                status: 'warn',
+                message:
+                    'half-configured: ai_team.review_gate.managed is on but ' +
+                    'ai_team.enabled is false — the gate never runs',
+                remedy:
+                    'set `ai_team.enabled: true` in .agent-settings.yml, or ' +
+                    'remove `ai_team.review_gate.managed`',
+            };
+        }
+        return {
+            id: 'team',
+            status: 'ok',
+            message: 'team mode not configured (default-off)',
+            remedy:
+                'opt in via `ai_team.enabled: true` in .agent-settings.yml, ' +
+                'then re-run `agent-config doctor --check team`',
+        };
+    }
+
+    const remedies: string[] = [];
+
+    // (a) codex binary — council-probe discovery reused.
+    const binary_name = _team_codex_binary_name(project_root);
+    const binary_resolved = shutilWhich(binary_name);
+    const binary_glyph = binary_resolved !== null ? '✅' : '❌';
+    if (binary_resolved === null) {
+        remedies.push('install the codex CLI: `npm install -g @openai/codex`');
+    }
+
+    // (a, cont.) codex auth — READ-ONLY probe of $CODEX_HOME/auth.json:
+    // presence + locally-derivable expiry evidence (no network).
+    const auth_path = path.join(_codex_home(), 'auth.json');
+    const authed = pathExists(auth_path);
+    let auth_str: string;
+    if (!authed) {
+        auth_str = `codex auth ❌ (${auth_path})`;
+        remedies.push('run `codex login`');
+    } else {
+        const expiry = _codex_auth_expiry(auth_path);
+        if (expiry !== null && expiry * 1000 < Date.now()) {
+            auth_str = `codex auth ⚠️ expired (${auth_path})`;
+            remedies.push('auth token appears expired — run `codex login`');
+        } else if (expiry === null) {
+            auth_str =
+                `codex auth ✅ (${auth_path}; ` +
+                'presence-only check — expiry not verifiable locally)';
+        } else {
+            auth_str = `codex auth ✅ (${auth_path})`;
+        }
+    }
+
+    // (b) official codex plugin — Claude-Code hosts only.
+    const is_claude_host =
+        shutilWhich('claude') !== null || pathExists(claude_plugin.claude_config_dir());
+    let plugin_str: string;
+    if (is_claude_host) {
+        const identity = claude_plugin.codex_plugin_identity();
+        if (!identity.installed) {
+            plugin_str = 'codex plugin ❌';
+            remedies.push(
+                'install the official codex plugin: ' +
+                    claude_plugin.CODEX_PLUGIN_INSTALL_HINT.map((c) => `\`${c}\``).join(' then '),
+            );
+        } else if (!identity.identity_verified) {
+            plugin_str = 'codex plugin ✅ — identity not fully verified (prefix match)';
+        } else {
+            plugin_str = 'codex plugin ✅';
+        }
+    } else {
+        plugin_str = 'codex plugin — (not a Claude Code host; fallback path applies)';
+    }
+
+    // (c) Review-Gate governance (Phase 4) — logic lives in
+    // src/scripts/ai_team/review_gate.ts (upstream gate probe + WARN
+    // states, incl. plugin-gate-on-while-unmanaged with the quoted
+    // upstream cost warning).
+    const gate_signal = review_gate_doctor_signal(project_root, gate);
+    const gate_str = gate_signal.gate_str;
+    remedies.push(...gate_signal.remedies);
+
+    const detail =
+        `codex binary ${binary_glyph} (${binary_name}) · ` +
+        `${auth_str} · ${plugin_str} · ${gate_str}`;
+    if (remedies.length > 0) {
+        return {
+            id: 'team',
+            status: 'warn',
+            message: `${remedies.length} team sub-signal(s) failing · ${detail}`,
+            remedy: remedies.join('; '),
+        };
+    }
+    return {
+        id: 'team',
+        status: 'ok',
+        message: `team mode enabled · ${detail}`,
+        remedy: '',
+    };
+}
+
 function _check_unsupported_combos(manifest: Dict): Dict {
     const global_only = new Set(['droid', 'qoder']);
     const bad: string[] = [];
@@ -2257,6 +2541,7 @@ function _run_checks(
         'humanizer-runtime': () => _check_humanizer_runtime(),
         'tier-usage-readiness': () => _check_tier_usage_readiness(project_root),
         'council-cli': () => _check_council_cli(project_root),
+        team: () => _check_team(project_root),
         'unsupported-combos': () => _check_unsupported_combos(manifest),
         'wizard-state': _check_wizard_state,
         'settings-review-pending': _check_settings_review_pending,
@@ -2329,6 +2614,7 @@ function _run_checks_no_manifest(
         'humanizer-runtime': () => _check_humanizer_runtime(),
         'tier-usage-readiness': () => _check_tier_usage_readiness(project_root),
         'council-cli': () => _check_council_cli(project_root),
+        team: () => _check_team(project_root),
         'unsupported-combos': () => _skipped_manifest_check('unsupported-combos'),
         'wizard-state': _check_wizard_state,
         'settings-review-pending': _check_settings_review_pending,
@@ -2818,6 +3104,7 @@ export {
     _check_mcp_beta_readiness,
     _check_tier_usage_readiness,
     _check_council_cli,
+    _check_team,
     _check_unsupported_combos,
     _check_wizard_state,
     _check_settings_review_pending,

package/src/scripts/_lib/claude_plugin.ts

@@ -27,6 +27,22 @@ export const CLAUDE_PLUGIN_INSTALL_HINT: readonly string[] = [
     `claude plugin install ${CLAUDE_PLUGIN_ID}@${CLAUDE_MARKETPLACE_NAME}`,
 ];
 
+/**
+ * Official OpenAI codex plugin for Claude Code (team mode's Claude-Code
+ * transport). Marketplace name verified against the upstream repo's
+ * `.claude-plugin/marketplace.json` (`name: "openai-codex"`, plugin
+ * `name: "codex"`) at HEAD 2026-07-12.
+ */
+export const CODEX_PLUGIN_ID = 'codex';
+export const CODEX_MARKETPLACE_NAME = 'openai-codex';
+export const CODEX_MARKETPLACE_REPO = 'openai/codex-plugin-cc';
+
+/** The one-time install commands surfaced when the codex plugin is missing. */
+export const CODEX_PLUGIN_INSTALL_HINT: readonly string[] = [
+    `claude plugin marketplace add ${CODEX_MARKETPLACE_REPO}`,
+    `claude plugin install ${CODEX_PLUGIN_ID}@${CODEX_MARKETPLACE_NAME}`,
+];
+
 /** Claude Code config dir — `CLAUDE_CONFIG_DIR` env override, else `~/.claude`. */
 export function claude_config_dir(): string {
     const env = (process.env['CLAUDE_CONFIG_DIR'] ?? '').trim();
@@ -34,11 +50,11 @@ export function claude_config_dir(): string {
 }
 
 /**
- * True when the agent-config plugin is recorded in Claude Code's
+ * True when a plugin with the given id is recorded in Claude Code's
  * `plugins/installed_plugins.json` (any marketplace — matched by the
- * `agent-config@` id prefix). Unreadable / absent file → false.
+ * `<id>@` key prefix). Unreadable / absent file → false. Read-only.
  */
-export function claude_plugin_installed(): boolean {
+function _plugin_id_recorded(plugin_id: string): boolean {
     const p = path.join(claude_config_dir(), 'plugins', 'installed_plugins.json');
     let data: unknown;
     try {
@@ -50,8 +66,102 @@ export function claude_plugin_installed(): boolean {
     const plugins = (data as { plugins?: unknown }).plugins;
     if (plugins === null || plugins === undefined || typeof plugins !== 'object') return false;
     return Object.keys(plugins as Record<string, unknown>).some((k) =>
-        k.startsWith(`${CLAUDE_PLUGIN_ID}@`),
+        k.startsWith(`${plugin_id}@`),
+    );
+}
+
+/**
+ * True when the agent-config plugin is recorded in Claude Code's
+ * `plugins/installed_plugins.json` (any marketplace — matched by the
+ * `agent-config@` id prefix). Unreadable / absent file → false.
+ */
+export function claude_plugin_installed(): boolean {
+    return _plugin_id_recorded(CLAUDE_PLUGIN_ID);
+}
+
+/**
+ * Codex plugin detection richness — presence plus namespace-resistant
+ * identity verification.
+ *
+ * `installed` — a `codex@<marketplace>` key exists in
+ * `plugins/installed_plugins.json` (prefix match, any marketplace).
+ * `identity_verified` — at least one such marketplace resolves, via the
+ * sibling `plugins/known_marketplaces.json` registry
+ * (`{ "<marketplace>": { source: { source: "github", repo: "owner/repo" } } }`
+ * — the real on-disk shape; `installed_plugins.json` entries themselves
+ * carry no repo/owner field), to the official upstream repo
+ * (`CODEX_MARKETPLACE_REPO`). When the registry file is absent, unreadable,
+ * or its entry has no `source.repo`, identity stays UNVERIFIED (honest
+ * fallback: prefix match only) — never inferred from the marketplace
+ * name alone, which any squatter can reuse.
+ */
+export interface CodexPluginIdentity {
+    readonly installed: boolean;
+    readonly identity_verified: boolean;
+}
+
+/** Marketplace names (the `@<marketplace>` suffix) a plugin id is installed from. */
+function _plugin_marketplaces(plugin_id: string): string[] {
+    const p = path.join(claude_config_dir(), 'plugins', 'installed_plugins.json');
+    let data: unknown;
+    try {
+        data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    } catch {
+        return [];
+    }
+    if (data === null || typeof data !== 'object') return [];
+    const plugins = (data as { plugins?: unknown }).plugins;
+    if (plugins === null || plugins === undefined || typeof plugins !== 'object') return [];
+    const prefix = `${plugin_id}@`;
+    return Object.keys(plugins as Record<string, unknown>)
+        .filter((k) => k.startsWith(prefix))
+        .map((k) => k.slice(prefix.length));
+}
+
+/** `source.repo` recorded for a marketplace in `known_marketplaces.json`, or null. */
+function _marketplace_source_repo(marketplace: string): string | null {
+    const p = path.join(claude_config_dir(), 'plugins', 'known_marketplaces.json');
+    let data: unknown;
+    try {
+        data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    } catch {
+        return null;
+    }
+    if (data === null || typeof data !== 'object') return null;
+    const entry = (data as Record<string, unknown>)[marketplace];
+    if (entry === null || entry === undefined || typeof entry !== 'object') return null;
+    const source = (entry as { source?: unknown }).source;
+    if (source === null || source === undefined || typeof source !== 'object') return null;
+    const repo = (source as { repo?: unknown }).repo;
+    return typeof repo === 'string' && repo.trim() !== '' ? repo.trim() : null;
+}
+
+/**
+ * Presence + identity of the official OpenAI codex plugin. Read-only:
+ * detection never writes under `~/.claude/`. See `CodexPluginIdentity`
+ * for the verification contract.
+ */
+export function codex_plugin_identity(): CodexPluginIdentity {
+    const marketplaces = _plugin_marketplaces(CODEX_PLUGIN_ID);
+    if (marketplaces.length === 0) {
+        return { installed: false, identity_verified: false };
+    }
+    const want = CODEX_MARKETPLACE_REPO.toLowerCase();
+    const identity_verified = marketplaces.some(
+        (m) => (_marketplace_source_repo(m) ?? '').toLowerCase() === want,
     );
+    return { installed: true, identity_verified };
+}
+
+/**
+ * True when the official OpenAI codex plugin is recorded in Claude Code's
+ * `plugins/installed_plugins.json` (any marketplace — matched by the
+ * `codex@` id prefix). Unreadable / absent file → false. Read-only:
+ * detection never writes under `~/.claude/`. Presence only — for
+ * namespace-resistant identity use `codex_plugin_identity()`.
+ */
+export function codex_plugin_installed(): boolean {
+    return codex_plugin_identity().installed;
 }
 
 /**

package/src/scripts/_lib/orchestration_record.ts

@@ -62,6 +62,10 @@ export interface RecordInput {
     first_pass_success?: boolean | undefined;
     /** QUALITY: slice retried on a higher tier after a verification failure. Optional boolean (null = not measured). */
     escalated?: boolean | undefined;
+    /** U5 (reliability-measurement): the subagent-type combination this dispatch
+     *  ran (ordered agent-type ids, e.g. ['implementer','implementer','judge']) —
+     *  with `outcome`, lets the orchestrator prefer combos that worked. Ids only. */
+    agent_combo?: string[] | undefined;
     // Audit-log envelope (sensible defaults for a dispatch record)
     phase?: LinePhase | undefined;
     outcome?: LineOutcome | undefined;
@@ -173,6 +177,7 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         session_tier: input.session_tier ?? null,
         first_pass_success: input.first_pass_success ?? null,
         escalated: input.escalated ?? null,
+        agent_combo: input.agent_combo ?? [],
     };
 
     const line: Record<string, unknown> = {

package/src/scripts/_lib/tool_adapter_registry.ts

@@ -0,0 +1,120 @@
+/**
+ * tool_adapter_registry.ts — canonical supported-tools adapter set.
+ *
+ * Single source of truth binding three surfaces that previously drifted
+ * independently (road-to-ecosystem-harvest-skill-quality-gates Phase 4,
+ * Source AA):
+ *
+ *   1. the README `## Supported tools` § "Project-installed" matrix,
+ *   2. this registry (reviewed, canonical),
+ *   3. the generator output roots in `check_generator_output_coverage.ts`.
+ *
+ * `lint_supported_tools_matrix.ts` fails CI when (1) ≠ (2) in either
+ * direction, and when a generator tool tag in (3) has no registry entry
+ * covering its root. Adding/removing a supported tool therefore requires
+ * touching README + registry (+ generator roots when native) in one commit.
+ */
+import { GENERATOR_OUTPUT_ROOTS } from '../check_generator_output_coverage.js';
+
+export interface AdapterEntry {
+    /** Tool name exactly as the README matrix first column renders it (without bold markers / parenthetical). */
+    readonly tool: string;
+    /** How the tool consumes the package. */
+    readonly kind: 'native' | 'agents-md' | 'marker';
+    /** Generated / written roots this tool reads (repo-relative). Empty for agents-md / marker tools. */
+    readonly roots: readonly string[];
+    /** Tool tag used by GENERATOR_OUTPUT_ROOTS, when the condense pipeline owns a root for it. */
+    readonly generator_tag?: string;
+}
+
+export const ADAPTER_REGISTRY: readonly AdapterEntry[] = [
+    {
+        tool: 'Claude Code',
+        kind: 'native',
+        roots: ['.claude/rules', '.claude/skills', '.claude/agents', '.claude/personas', '.claude/user-types'],
+        generator_tag: 'claude-code',
+    },
+    { tool: 'Cursor', kind: 'native', roots: ['.cursor/rules', '.cursor/commands'], generator_tag: 'cursor' },
+    { tool: 'Cline', kind: 'native', roots: ['.clinerules'] },
+    {
+        tool: 'Windsurf',
+        kind: 'native',
+        roots: ['.windsurfrules', '.windsurf/rules', '.windsurf/workflows'],
+        generator_tag: 'windsurf',
+    },
+    { tool: 'Gemini CLI', kind: 'native', roots: ['GEMINI.md'], generator_tag: 'gemini' },
+    { tool: 'GitHub Copilot', kind: 'native', roots: ['.github/copilot-instructions.md'] },
+    { tool: 'Roo Code', kind: 'agents-md', roots: [] },
+    { tool: 'Codex CLI', kind: 'agents-md', roots: [] },
+    { tool: 'Continue.dev', kind: 'agents-md', roots: [] },
+    { tool: 'Aider', kind: 'marker', roots: [] },
+    { tool: 'Augment', kind: 'marker', roots: ['.augment'], generator_tag: 'augment' },
+    { tool: 'Claude Desktop', kind: 'marker', roots: [] },
+];
+
+/**
+ * Extract the tool names from the README's `## Supported tools` §
+ * "Project-installed" table. Returns names with bold markers and trailing
+ * parentheticals stripped, in table order.
+ */
+export function parse_supported_tools(readme: string): string[] {
+    const section = readme.split(/^## Supported tools\s*$/m)[1];
+    if (section === undefined) return [];
+    // Stop at the next H2/H3 AFTER the first table (the "Plugin-installed" H3).
+    const lines = section.split('\n');
+    const tools: string[] = [];
+    let inTable = false;
+    for (const line of lines) {
+        const t = line.trim();
+        if (/^###\s/.test(t) && inTable) break; // next sub-section after the table
+        if (/^\|/.test(t)) {
+            inTable = true;
+            const cell = t.split('|')[1]?.trim() ?? '';
+            if (cell === '' || cell === 'Tool' || /^:?-+:?$/.test(cell)) continue;
+            const name = cell
+                .replace(/\*\*/g, '')
+                .replace(/\s*\(.*\)\s*$/, '')
+                .trim();
+            if (name && name !== '---') tools.push(name);
+        } else if (inTable && t !== '' && !/^\|/.test(t)) {
+            // Table ended (legend line etc.).
+            break;
+        }
+    }
+    return tools;
+}
+
+/** Compare README matrix ↔ registry ↔ generator roots. Returns human-readable errors; empty = green. */
+export function lint_matrix(readme: string): string[] {
+    const errors: string[] = [];
+    const readmeTools = parse_supported_tools(readme);
+    const readmeSet = new Set(readmeTools);
+    const registrySet = new Set(ADAPTER_REGISTRY.map((e) => e.tool));
+
+    for (const t of registrySet) {
+        if (!readmeSet.has(t)) {
+            errors.push(`registry tool '${t}' missing from the README Supported-tools matrix`);
+        }
+    }
+    for (const t of readmeSet) {
+        if (!registrySet.has(t)) {
+            errors.push(`README Supported-tools row '${t}' has no ADAPTER_REGISTRY entry`);
+        }
+    }
+
+    // Generator leg: every tool-tagged generator output root must be claimed
+    // by the registry entry carrying that tag.
+    const byTag = new Map(ADAPTER_REGISTRY.filter((e) => e.generator_tag).map((e) => [e.generator_tag, e]));
+    for (const { root, tool } of GENERATOR_OUTPUT_ROOTS) {
+        if (tool === null) continue;
+        const entry = byTag.get(tool);
+        if (!entry) {
+            errors.push(`generator output root '${root}' (tool '${tool}') has no ADAPTER_REGISTRY entry with that generator_tag`);
+            continue;
+        }
+        if (!entry.roots.includes(root)) {
+            errors.push(`generator output root '${root}' (tool '${tool}') is not listed in ADAPTER_REGISTRY entry '${entry.tool}'`);
+        }
+    }
+    return errors;
+}