@event4u/agent-config 8.13.0 → 9.0.0

package/src/agent-src/templates/scripts/telemetry_record.ts

@@ -63,6 +63,7 @@ interface RecordArgs {
     boundary: string;
     consulted: string[] | null;
     applied: string[] | null;
+    loaded: string[] | null;
     outcome: string[] | null;
     ts: string;
     payload_file: string | null;
@@ -78,6 +79,7 @@ function _build_event_from_args(args: RecordArgs): EngagementEvent {
         boundary_kind: args.boundary,
         consulted: _parse_kv_list(args.consulted ?? []),
         applied: _parse_kv_list(args.applied ?? []),
+        loaded: args.loaded && args.loaded.length > 0 ? _parse_kv_list(args.loaded) : null,
         outcomes: args.outcome && args.outcome.length > 0 ? [...args.outcome] : null,
     });
 }
@@ -101,6 +103,7 @@ function _build_event_from_payload(raw: string): EngagementEvent {
         boundary_kind: (d['boundary_kind'] as string) ?? '',
         consulted: _orEmpty(d['consulted']),
         applied: _orEmpty(d['applied']),
+        loaded: d['loaded'] === undefined || d['loaded'] === null ? null : _orEmpty(d['loaded']),
         outcomes: (d['outcomes'] as string[] | null | undefined) ?? null,
         tokens_estimate: (d['tokens_estimate'] as Record<string, number> | null | undefined) ?? null,
     });
@@ -121,6 +124,7 @@ function _parseArgs(argv: string[]): RecordArgs {
         boundary: 'task',
         consulted: null,
         applied: null,
+        loaded: null,
         outcome: null,
         ts: '',
         payload_file: null,
@@ -155,6 +159,7 @@ function _parseArgs(argv: string[]): RecordArgs {
             }
             a.boundary = v;
         } else if (tok === '--consulted') (a.consulted ??= []).push(next());
+        else if (tok === '--loaded') (a.loaded ??= []).push(next());
         else if (tok === '--applied') (a.applied ??= []).push(next());
         else if (tok === '--outcome') {
             const v = next();

package/src/config/agent-settings.template.yml

@@ -62,10 +62,15 @@ projection:
   # rules ALWAYS project (unconditional by definition); untagged rules fail
   # safe and ship. Example consumer scope:
   #   rule_workspaces: [engineering]
-  # Default flip to a scoped value is a human release gate — see
-  # agents/settings/contexts/consumer-scoping-audit-2026-07-07.md.
+  # DEFAULT FLIPPED 2026-07-13 (the Phase-1 human gate, maintainer-approved,
+  # evidence-gated): the default below lists EVERY consumer workspace, so
+  # exactly the exclusively-maintainer specification rules drop from consumer
+  # installs (the audited 16-rule lever — see
+  # agents/settings/contexts/consumer-scoping-audit-2026-07-07.md) while all
+  # domain safety floors and domain rules keep shipping. Narrowing further
+  # (e.g. [engineering] only) stays a per-install user choice.
   # An EMPTY list is inactive (= legacy-all); only a non-empty list scopes.
-  rule_workspaces: []
+  rule_workspaces: [engineering, product, finance, founder, gtm, ops, small-business, construction, legal-review-prep]
   #
   # Optional second axis, same semantics per pack ids (packs.yml). When set,
   # a non-kernel rule also needs a `packs:` intersection to project — e.g.
@@ -622,10 +627,14 @@ worktrees:
 
 # --- AI Council (external second-opinion network) ---
 #
-# Configuration moved to `agents/.ai-council.yml` as of the Step-2
-# consolidation roadmap. Consumer projects opt in by copying the
-# reference file from the package (`agents/.ai-council.yml`) into their
-# own `agents/` tree and flipping `enabled: true` per provider.
+# The council config is NOT here and is NOT project-local. It lives ONLY
+# user-global at `~/.event4u/agent-config/settings/.ai-council.yml` — one
+# file, configured once, serving every project / worktree / CWD (ADR-104,
+# superseding ADR-093). The project tree is NEVER searched; a
+# `.ai-council.yml` under any `agents/` tree is ignored. To opt in, copy
+# the shape from `agents/templates/.ai-council.yml.example` to that
+# user-global path and flip `enabled: true` per provider — do NOT drop it
+# into a project's `agents/` tree.
 #
 # See `docs/contracts/ai-council-config.md` for the schema.
 
@@ -665,9 +674,24 @@ ai_team:
   # plugin on Claude-Code hosts. Cosmetic only — never changes behavior.
   suppress_setup_hint: false
 
-  # NOTE for future keys: `review_gate` (managed loop-bound governance of
-  # the plugin's Stop-hook Review Gate) lands in a later team-mode phase
-  # (Phase 4) — do not add it here ahead of that phase.
+  # Managed governance of the codex plugin's Stop-hook Review Gate
+  # (road-to-team-mode Phase 4). The gate itself stays upstream's; these
+  # keys only govern it. Upstream's own warning: "The review gate can
+  # create a long-running Claude/Codex loop and may drain usage limits
+  # quickly."
+  review_gate:
+    # false (default) = byte-identical pre-Phase-4 behavior: no counting,
+    # no circuit breaker, our Stop path never touches the gate. true =
+    # count consecutive BLOCK verdicts per session and trip the circuit
+    # breaker at the bound below.
+    managed: false
+
+    # 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.
+    max_consecutive_blocks: 3
 
 # --- Onboarding ---
 #

package/src/config/prelaunch-areas.yml

@@ -0,0 +1,36 @@
+# Pre-launch diagnostic — fixed coverage-area vocabulary
+# (road-to-ecosystem-harvest-prelaunch-diagnostics Phase 1, Source L).
+#
+# The AREA code is the middle segment of the immutable finding-ID grammar
+# `AC-<AREA>-NNN` (docs/contracts/prelaunch-diagnostics.md). Codes are
+# append-only: renaming or re-using a code would re-assign IDs and break
+# every committed baseline. Add new areas at the end; never delete.
+#
+# `launch_gate: true` areas participate in the regression gate's
+# Pass→Finding CI trigger and block a "ready" verdict while Unknown.
+schema_version: prelaunch-areas-v1
+areas:
+  auth:
+    code: AUTH
+    launch_gate: true
+    description: Authentication, authorization, tenancy boundaries on the launch surface.
+  migrations:
+    code: MIG
+    launch_gate: true
+    description: Schema/data migrations shipped with the launch — reversibility, expand-contract, backfill safety.
+  secrets:
+    code: SEC
+    launch_gate: true
+    description: Secrets, tokens, key handling touched by the launch — storage, rotation, exposure paths.
+  observability:
+    code: OBS
+    launch_gate: false
+    description: Telemetry proving rollout health — the metric, alert, and pager path for the new surface.
+  rollback:
+    code: RBK
+    launch_gate: true
+    description: Rollback contract — trip wires, decision windows, abort paths, named irreversible steps.
+  agent-governance:
+    code: AGOV
+    launch_gate: false
+    description: AI/agent surfaces shipped with the launch — tool grants, egress paths, injection exposure.

package/src/scripts/_cli/cmd_doctor.ts

@@ -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>;
 
@@ -2028,6 +2029,79 @@ function _settings_flag(val: unknown): boolean {
     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);
@@ -2049,14 +2123,21 @@ function _read_ai_team_block(project_root: string): 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 presence probe of
- *     `$CODEX_HOME/auth.json` (default `~/.codex/auth.json`) — token
- *     expiry cannot be validated without a billable call; runtime expiry
- *     is caught by `OpenAICliClient._AUTH_FAILURE_PATTERNS`.
+ *     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`. Detection is read-only — doctor
- *     never writes under `~/.claude/`.
+ *     `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.
@@ -2074,8 +2155,6 @@ function _check_team(project_root: string): Dict {
             ? (gateRaw as Dict)
             : {};
     const gate_managed = _settings_flag(gate['managed']);
-    const bound = gate['max_consecutive_blocks'];
-    const bound_present = typeof bound === 'number' && Number.isInteger(bound) && bound > 0;
 
     if (!enabled) {
         if (gate_managed) {
@@ -2110,12 +2189,26 @@ function _check_team(project_root: string): Dict {
         remedies.push('install the codex CLI: `npm install -g @openai/codex`');
     }
 
-    // (a, cont.) codex auth — presence probe of $CODEX_HOME/auth.json.
+    // (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);
-    const auth_glyph = authed ? '✅' : '❌';
+    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.
@@ -2123,34 +2216,33 @@ function _check_team(project_root: string): Dict {
         shutilWhich('claude') !== null || pathExists(claude_plugin.claude_config_dir());
     let plugin_str: string;
     if (is_claude_host) {
-        const plugin_present = claude_plugin.codex_plugin_installed();
-        plugin_str = `codex plugin ${plugin_present ? '✅' : '❌'}`;
-        if (!plugin_present) {
+        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 consistency.
-    let gate_str: string;
-    if (gate_managed && !bound_present) {
-        gate_str = 'review-gate ⚠️ on, loop bound absent';
-        remedies.push(
-            'set `ai_team.review_gate.max_consecutive_blocks` (loop bound; ' +
-                'ships with the Review-Gate governance phase) or set ' +
-                '`ai_team.review_gate.managed: false`',
-        );
-    } else {
-        gate_str = `review-gate ${gate_managed ? 'on' : 'off'}`;
-    }
+    // (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}) · ` +
-        `codex auth ${auth_glyph} (${auth_path}) · ${plugin_str} · ${gate_str}`;
+        `${auth_str} · ${plugin_str} · ${gate_str}`;
     if (remedies.length > 0) {
         return {
             id: 'team',

package/src/scripts/_lib/claude_plugin.ts

@@ -79,14 +79,89 @@ 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/`.
+ * detection never writes under `~/.claude/`. Presence only — for
+ * namespace-resistant identity use `codex_plugin_identity()`.
  */
 export function codex_plugin_installed(): boolean {
-    return _plugin_id_recorded(CODEX_PLUGIN_ID);
+    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;
+}