@hegemonart/get-design-done 1.26.0 → 1.27.1

package/scripts/lib/session-runner/index.ts

@@ -86,6 +86,336 @@ const RATE_GUARD_PROVIDER = 'anthropic';
 /** Default retries (first attempt + 1 retry). */
 const DEFAULT_MAX_RETRIES = 2;
 
+// ── Plan 27-06 — Peer-CLI delegation primitives ─────────────────────────────
+//
+// Lazy registry loader: the registry is a .cjs module under scripts/lib/peer-cli
+// landed by Plan 27-05. Tests inject a stub via SessionRunnerOptions.registryOverride;
+// real callers fall through to the live module. Resolution is anchored to the
+// repo root via the same `_nodeRequire` we use for jittered-backoff/rate-guard
+// so the runner survives test sandboxes that chdir.
+//
+// We swallow load errors and return null → caller treats as "no peer available"
+// → falls back to local SDK. This keeps the session-runner functional even on
+// fresh checkouts where Plan 27-05 hasn't landed yet.
+
+interface PeerRegistry {
+  dispatch: (
+    role: string,
+    tier: string | null,
+    text: string,
+    opts: { cwd?: string; [k: string]: unknown },
+  ) => Promise<{ result: unknown; peer: string; protocol: 'acp' | 'asp' } | null>;
+}
+
+let _peerRegistryCache: PeerRegistry | null | undefined;
+
+/**
+ * Resolve the peer-CLI registry. Memoized; returns null if the module
+ * isn't installable (missing file, require throws, shape mismatch).
+ * Tests bypass this entirely by passing `registryOverride` on the
+ * SessionRunnerOptions.
+ */
+function loadPeerRegistry(): PeerRegistry | null {
+  if (_peerRegistryCache !== undefined) return _peerRegistryCache;
+  try {
+    const mod = _nodeRequire(
+      _resolve(_REPO_ROOT, 'scripts/lib/peer-cli/registry.cjs'),
+    );
+    if (mod && typeof mod === 'object' && typeof (mod as { dispatch?: unknown }).dispatch === 'function') {
+      _peerRegistryCache = mod as PeerRegistry;
+      return _peerRegistryCache;
+    }
+  } catch {
+    // registry.cjs missing or threw on require — treat as "no peers available"
+  }
+  _peerRegistryCache = null;
+  return _peerRegistryCache;
+}
+
+/**
+ * Visible-for-testing reset of the peer-registry cache. The session-runner
+ * caches the registry module after first resolve so production runs don't
+ * re-require it per call; tests that swap process state (chdir into a
+ * sandbox, write a different registry.cjs, etc.) can call this between
+ * tests to force reload. Production code never calls this.
+ */
+export function _resetPeerRegistryCache(): void {
+  _peerRegistryCache = undefined;
+}
+
+/**
+ * Parse a `delegate_to` value into (peer, role). Returns null when the
+ * value is missing, the literal "none" opt-out, or doesn't match the
+ * `<peer>-<role>` shape. The session-runner uses this to figure out
+ * which role to ask the registry for.
+ *
+ * Note: validate-frontmatter.ts already enforces the value shape at lint
+ * time — by the time a `delegate_to` reaches session-runner it's been
+ * validated against the capability matrix. We re-parse here defensively
+ * because the runner is consumed by tests that may pass arbitrary
+ * strings, and the cost of an extra split is trivial.
+ */
+function parseDelegateTo(value: string | undefined): { peer: string; role: string } | null {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  if (value === 'none') return null;
+  const dashIdx = value.indexOf('-');
+  if (dashIdx <= 0 || dashIdx >= value.length - 1) return null;
+  return {
+    peer: value.slice(0, dashIdx),
+    role: value.slice(dashIdx + 1),
+  };
+}
+
+/**
+ * Try to dispatch a session via peer-CLI before falling back to the
+ * Anthropic SDK. Returns either a fully-built SessionResult on peer
+ * success, or null when the caller should continue to the local path.
+ *
+ * Per CONTEXT D-07 (transparent fallback): every failure path inside
+ * this helper returns null — peer-absent, registry-load-failure,
+ * adapter-error, dispatch-throw, anything. The local SDK path then
+ * runs as if the delegation never happened. Failure is observable
+ * only as a placeholder log call (and, once Plan 27-08 wires real
+ * events, as a `peer_call_failed` chain entry).
+ */
+async function tryDelegate(args: {
+  opts: SessionRunnerOptions;
+  sanitizedPrompt: string;
+  transcriptPath: string;
+  sessionId: string;
+  sanitizer: { sanitized: string; applied: readonly string[]; removedSections: readonly string[] };
+}): Promise<SessionResult | null> {
+  const { opts, sanitizedPrompt, transcriptPath, sanitizer } = args;
+  const parsed = parseDelegateTo(opts.delegateTo);
+  if (parsed === null) return null; // not configured / explicit opt-out
+
+  const role = typeof opts.delegateRole === 'string' && opts.delegateRole.length > 0
+    ? opts.delegateRole
+    : parsed.role;
+  const tier = opts.delegateTier === undefined ? null : opts.delegateTier;
+
+  const dispatcher: PeerRegistry['dispatch'] | null = (() => {
+    if (typeof opts.registryOverride === 'function') return opts.registryOverride;
+    const reg = loadPeerRegistry();
+    return reg !== null ? reg.dispatch : null;
+  })();
+  if (dispatcher === null) {
+    // No registry available at all — fall through to local.
+    _logPeerCallFailed({
+      peer: parsed.peer, role, errorClass: 'registry_missing',
+      sessionId: args.sessionId, stage: opts.stage,
+    });
+    return null;
+  }
+
+  // v1.27.1 — emit peer_call_started before dispatcher invocation so the
+  // events.jsonl trail captures the attempt even if the dispatcher hangs.
+  _logPeerCallStarted({
+    peer: parsed.peer, role,
+    sessionId: args.sessionId, stage: opts.stage,
+  });
+  const dispatchStartedAt = Date.now();
+
+  let dispatchResult: { result: unknown; peer: string; protocol: 'acp' | 'asp' } | null = null;
+  try {
+    dispatchResult = await dispatcher(role, tier, sanitizedPrompt, { cwd: process.cwd() });
+  } catch (err) {
+    _logPeerCallFailed({
+      peer: parsed.peer,
+      role,
+      errorClass: 'dispatch_threw',
+      message: err instanceof Error ? err.message : String(err),
+      sessionId: args.sessionId,
+      stage: opts.stage,
+    });
+    return null; // transparent fallback
+  }
+
+  if (dispatchResult === null) {
+    // Registry returned null — peer absent, capability mismatch, or
+    // adapter-side error. Per D-07 we fall back silently.
+    _logPeerCallFailed({
+      peer: parsed.peer, role, errorClass: 'registry_returned_null',
+      sessionId: args.sessionId, stage: opts.stage,
+    });
+    return null;
+  }
+
+  // v1.27.1 — peer round-trip succeeded. Emit peer_call_complete with the
+  // measured latency. Token counts + cost are 0 / null because adapters
+  // don't surface usage in v1.27 (Plan 27-04 spec deferred it); reflector
+  // tolerates null cost (Plan 26-06 cost-arbitrage analysis).
+  _logPeerCallComplete({
+    peer: dispatchResult.peer,
+    role,
+    latencyMs: Date.now() - dispatchStartedAt,
+    tokensIn: 0,
+    tokensOut: 0,
+    costUsd: null,
+    sessionId: args.sessionId,
+    stage: opts.stage,
+  });
+
+  // Peer succeeded. Build a SessionResult that mirrors the local path's
+  // shape so downstream consumers (stage-handlers, transcript readers,
+  // tests) treat both paths uniformly. We do NOT write a transcript file
+  // for delegated calls in v1.27.0 — the peer broker (Plan 27-03) keeps
+  // its own logs and Plan 27-08 wires the events that observers need.
+  // The transcript_path field still points at the would-be path so any
+  // consumer that probes it sees a stable string (existsSync will be
+  // false, which is correct: the file isn't ours to write).
+  const finalText = _coerceFinalText(dispatchResult.result);
+  return {
+    status: 'completed',
+    transcript_path: transcriptPath,
+    turns: 1,
+    usage: { input_tokens: 0, output_tokens: 0, usd_cost: 0 },
+    ...(finalText !== undefined ? { final_text: finalText } : {}),
+    tool_calls: [],
+    sanitizer: {
+      applied: [...sanitizer.applied],
+      removedSections: [...sanitizer.removedSections],
+    },
+  };
+}
+
+/** Best-effort extract a final text string from the adapter's free-form result. */
+function _coerceFinalText(result: unknown): string | undefined {
+  if (typeof result === 'string' && result.length > 0) return result;
+  if (result !== null && typeof result === 'object') {
+    const obj = result as Record<string, unknown>;
+    if (typeof obj['final_text'] === 'string' && obj['final_text'].length > 0) {
+      return obj['final_text'] as string;
+    }
+    if (typeof obj['text'] === 'string' && obj['text'].length > 0) {
+      return obj['text'] as string;
+    }
+    if (typeof obj['output'] === 'string' && obj['output'].length > 0) {
+      return obj['output'] as string;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * v1.27.1 — wires Plan 27-08's `peer_call_failed` event for real.
+ * Phase 22 `appendEvent` accepts the new event type (registered in
+ * KNOWN_EVENT_TYPES via Plan 27-08), so the reflector and downstream
+ * telemetry consumers see delegation drops as a measurement signal.
+ *
+ * Errors from `appendEvent` (e.g., events.jsonl unwritable) are
+ * swallowed — peer-call telemetry is observability, not critical
+ * path. STATE.md remains the durable record of session outcomes.
+ *
+ * Operators can additionally set `GDD_PEER_DEBUG=1` to emit a
+ * one-line stderr breadcrumb mirroring the event for live tailing.
+ */
+function _logPeerCallFailed(args: {
+  peer: string;
+  role: string;
+  errorClass: string;
+  message?: string;
+  sessionId?: string;
+  stage?: SessionRunnerOptions['stage'];
+}): void {
+  try {
+    appendEvent({
+      type: 'peer_call_failed',
+      timestamp: new Date().toISOString(),
+      sessionId: args.sessionId ?? 'unknown',
+      ...(args.stage !== undefined && args.stage !== 'init' && args.stage !== 'custom' ? { stage: args.stage } : {}),
+      payload: {
+        runtime_role: 'peer',
+        peer_id: args.peer,
+        role: args.role,
+        error_class: args.errorClass,
+        ...(args.message !== undefined ? { message: args.message } : {}),
+      },
+    });
+  } catch {
+    // Telemetry is best-effort — never let an event-stream failure
+    // break the actual session flow.
+  }
+  if (process.env['GDD_PEER_DEBUG'] === '1') {
+    const payload = JSON.stringify({
+      type: 'peer_call_failed',
+      peer_id: args.peer,
+      role: args.role,
+      error_class: args.errorClass,
+      ...(args.message !== undefined ? { message: args.message } : {}),
+      ts: new Date().toISOString(),
+    });
+    // eslint-disable-next-line no-console
+    console.error(`[peer-cli] ${payload}`);
+  }
+}
+
+/**
+ * v1.27.1 — emit `peer_call_started` event. Fired once at the beginning
+ * of a delegation attempt, before the dispatcher is invoked. Pairs with
+ * `peer_call_complete` (success path) or `peer_call_failed` (any failure
+ * path, transparent to caller per D-07).
+ */
+function _logPeerCallStarted(args: {
+  peer: string;
+  role: string;
+  sessionId?: string;
+  stage?: SessionRunnerOptions['stage'];
+}): void {
+  try {
+    appendEvent({
+      type: 'peer_call_started',
+      timestamp: new Date().toISOString(),
+      sessionId: args.sessionId ?? 'unknown',
+      ...(args.stage !== undefined && args.stage !== 'init' && args.stage !== 'custom' ? { stage: args.stage } : {}),
+      payload: {
+        runtime_role: 'peer',
+        peer_id: args.peer,
+        role: args.role,
+      },
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * v1.27.1 — emit `peer_call_complete` event. Fired after a successful
+ * dispatcher round-trip. Cost is null when the adapter doesn't return
+ * usage data (some peers don't surface token counts); the reflector
+ * tolerates null cost for arbitrage analysis (Plan 26-06).
+ */
+function _logPeerCallComplete(args: {
+  peer: string;
+  role: string;
+  latencyMs: number;
+  tokensIn: number;
+  tokensOut: number;
+  costUsd: number | null;
+  sessionId?: string;
+  stage?: SessionRunnerOptions['stage'];
+}): void {
+  try {
+    appendEvent({
+      type: 'peer_call_complete',
+      timestamp: new Date().toISOString(),
+      sessionId: args.sessionId ?? 'unknown',
+      ...(args.stage !== undefined && args.stage !== 'init' && args.stage !== 'custom' ? { stage: args.stage } : {}),
+      payload: {
+        runtime_role: 'peer',
+        peer_id: args.peer,
+        role: args.role,
+        latency_ms: args.latencyMs,
+        tokens_in: args.tokensIn,
+        tokens_out: args.tokensOut,
+        cost_usd: args.costUsd,
+      },
+    });
+  } catch {
+    // best-effort
+  }
+}
+
 /** Baseline retry backoff parameters (matches jittered-backoff defaults for
  *  the SDK-retry case; 1s base → 30s cap). */
 const RETRY_BACKOFF = { baseMs: 1000, maxMs: 30_000 } as const;
@@ -408,6 +738,38 @@ export async function run(opts: SessionRunnerOptions): Promise<SessionResult> {
     }
   }
 
+  // -- 6.5. Peer-CLI delegation try (Plan 27-06 wiring, v1.27.1). ---------
+  // If the agent's frontmatter declares `delegate_to: <peer>-<role>` AND the
+  // peer is allowlisted AND the registry can route, run the prompt on the
+  // peer-CLI and return early. On peer-absent / peer-error / null result,
+  // fall through transparently to the local SDK loop (D-07).
+  //
+  // tryDelegate is a no-op when opts.delegateTo is undefined / 'none', when
+  // the registry can't load, when the peer isn't allowlisted, when the
+  // dispatcher returns null, or when the dispatcher throws. In all those
+  // cases tryDelegate returns null and we proceed to the local SDK path.
+  const peerResult = await tryDelegate({
+    opts,
+    sanitizedPrompt,
+    transcriptPath,
+    sessionId,
+    sanitizer: sanResult,
+  });
+  if (peerResult !== null) {
+    emit('session.completed', opts.stage, sessionId, {
+      stage: opts.stage,
+      sessionId,
+      status: peerResult.status,
+      turns: peerResult.turns,
+      usage: peerResult.usage,
+      transcript_path: transcriptPath,
+      sanitizer: { applied: [...peerResult.sanitizer.applied], removedSections: [...peerResult.sanitizer.removedSections] },
+    });
+    transcript.close();
+    if (opts.signal !== undefined) opts.signal.removeEventListener('abort', onExternalAbort);
+    return peerResult;
+  }
+
   // -- 7. Retry-once loop. ------------------------------------------------
   const maxAttempts = opts.maxRetries !== undefined && opts.maxRetries > 0
     ? opts.maxRetries

package/scripts/lib/session-runner/types.ts

@@ -118,6 +118,66 @@ export interface SessionRunnerOptions {
     applied: readonly string[];
     removedSections: readonly string[];
   };
+
+  /**
+   * Phase 27 (Plan 27-06) — peer-CLI delegation.
+   *
+   * Optional. When set to `<peer>-<role>` (e.g. `gemini-research`), the
+   * session-runner attempts to dispatch the call to the named peer-CLI
+   * via `scripts/lib/peer-cli/registry.cjs#dispatch` BEFORE invoking the
+   * local Anthropic SDK. The peer's response, when successful, becomes
+   * the SessionResult — no SDK call is made.
+   *
+   * Fallback (CONTEXT D-07): if the registry returns `null` (peer
+   * absent / opt-out / adapter error / dispatch error) OR throws, the
+   * session-runner silently retries with the local Anthropic SDK. The
+   * caller never sees the peer failure — failure is a measurement
+   * signal, not a cycle-breaker.
+   *
+   * Special values:
+   *   - `none`      → explicit opt-out; never delegate. Same as omitting the field.
+   *   - undefined   → default behavior; never delegate.
+   *
+   * The session-runner never reads agent frontmatter on its own. Callers
+   * (pipeline-runner, explore, discuss, etc.) are responsible for
+   * resolving the agent's `delegate_to:` frontmatter and passing it
+   * through this option.
+   */
+  delegateTo?: string;
+
+  /**
+   * Phase 27 (Plan 27-06) — role hint for peer-CLI dispatch.
+   *
+   * Used only when `delegateTo` is set. Defaults to the role parsed out
+   * of `delegateTo` (e.g. `delegateTo: "gemini-research"` → role
+   * `"research"`). Provide explicitly when the caller wants to override
+   * the parsed value (rare).
+   */
+  delegateRole?: string;
+
+  /**
+   * Phase 27 (Plan 27-06) — tier hint for peer-CLI dispatch.
+   *
+   * Currently advisory; the registry's capability matrix doesn't gate
+   * on tier. Used by adapters for telemetry and by Plan 27-08 events.
+   * Defaults to null (let the adapter pick).
+   */
+  delegateTier?: string | null;
+
+  /**
+   * Phase 27 (Plan 27-06) — registry override for tests.
+   *
+   * Default loads `scripts/lib/peer-cli/registry.cjs` lazily on first
+   * delegation attempt. Tests inject a stub `dispatch()` to avoid
+   * spawning real peers. The override mirrors the registry's `dispatch`
+   * signature: `(role, tier, text, opts) => Promise<{result,peer,protocol} | null>`.
+   */
+  registryOverride?: (
+    role: string,
+    tier: string | null,
+    text: string,
+    opts: { cwd?: string; [k: string]: unknown },
+  ) => Promise<{ result: unknown; peer: string; protocol: 'acp' | 'asp' } | null>;
 }
 
 /**

package/scripts/validate-frontmatter.ts

@@ -14,10 +14,100 @@
  */
 
 import { existsSync, statSync, readdirSync } from 'node:fs';
-import { join, basename } from 'node:path';
+import { join, basename, dirname, resolve } from 'node:path';
+import { createRequire } from 'node:module';
 
 import { readFrontmatter } from '../tests/helpers.ts';
 
+// ── delegate_to capability matrix loader (Plan 27-06) ──────────────────────
+//
+// The `delegate_to: <peer>-<role> | none` field is validated against the
+// capability matrix exported by scripts/lib/peer-cli/registry.cjs (Plan
+// 27-05). Loading the .cjs from a .ts module under the strip-types loader
+// requires createRequire — and we anchor it to the repo root so the
+// validator survives being invoked from any cwd.
+//
+// Loading is lazy + defensive: if the registry module isn't on disk yet
+// (e.g. during a fresh clone before Plan 27-05 lands, or in a partial
+// checkout), we fall back to an inline literal mirror of the locked D-05
+// capability matrix so this validator never crashes a CI run on a
+// missing dependency. The literal mirror MUST stay in sync with
+// registry.cjs's CAPABILITY_MATRIX — tests assert equivalence.
+function _findRepoRootFromHere(): string {
+  // process.argv[1] is the validator script path under strip-types; walk
+  // up from its directory looking for package.json. Fall back to cwd.
+  const start: string = (() => {
+    const argv1 = process.argv[1];
+    if (typeof argv1 === 'string' && argv1.length > 0) return dirname(argv1);
+    return process.cwd();
+  })();
+  let dir = resolve(start);
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'package.json'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+/** Locked D-05 capability matrix mirror — fallback when registry.cjs unloadable. */
+const _DELEGATE_MATRIX_FALLBACK: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  codex: Object.freeze(['execute']),
+  copilot: Object.freeze(['review', 'research']),
+  cursor: Object.freeze(['debug', 'plan']),
+  gemini: Object.freeze(['research', 'exploration']),
+  qwen: Object.freeze(['write']),
+});
+
+let _delegateMatrixCache: Readonly<Record<string, readonly string[]>> | null = null;
+
+/**
+ * Return the live capability matrix as a `peer -> roles[]` map. Cached
+ * after first call. Uses registry.cjs as the source of truth; falls back
+ * to the inline mirror only if the registry module fails to load.
+ */
+export function loadDelegateMatrix(): Readonly<Record<string, readonly string[]>> {
+  if (_delegateMatrixCache !== null) return _delegateMatrixCache;
+  try {
+    const root = _findRepoRootFromHere();
+    const req = createRequire(join(root, 'package.json'));
+    const reg = req(resolve(root, 'scripts/lib/peer-cli/registry.cjs')) as {
+      CAPABILITY_MATRIX?: Record<string, { roles: readonly string[] }>;
+    };
+    if (reg && typeof reg.CAPABILITY_MATRIX === 'object' && reg.CAPABILITY_MATRIX !== null) {
+      const out: Record<string, readonly string[]> = {};
+      for (const [peer, cap] of Object.entries(reg.CAPABILITY_MATRIX)) {
+        if (cap && Array.isArray(cap.roles)) {
+          out[peer] = Object.freeze([...cap.roles]);
+        }
+      }
+      _delegateMatrixCache = Object.freeze(out);
+      return _delegateMatrixCache;
+    }
+  } catch {
+    // fall through to fallback
+  }
+  _delegateMatrixCache = _DELEGATE_MATRIX_FALLBACK;
+  return _delegateMatrixCache;
+}
+
+/**
+ * Build the flat set of valid `<peer>-<role>` IDs from the capability
+ * matrix. e.g. `gemini-research`, `codex-execute`, etc. The literal
+ * string `"none"` is the explicit opt-out and is accepted separately.
+ */
+export function validDelegateIds(): readonly string[] {
+  const matrix = loadDelegateMatrix();
+  const out: string[] = [];
+  for (const [peer, roles] of Object.entries(matrix)) {
+    for (const role of roles) {
+      out.push(`${peer}-${role}`);
+    }
+  }
+  return Object.freeze(out.sort());
+}
+
 // Importing a type from generated.d.ts satisfies the Plan 20-00 rule that
 // every Tier-1 TS file participates in the codegen graph. We don't use
 // IntelSchema at runtime; the re-export keeps it visible for static checks.
@@ -42,6 +132,22 @@ export interface AgentFrontmatter {
   'default-tier'?: 'haiku' | 'sonnet' | 'opus';
   'reasoning-class'?: 'high' | 'medium' | 'low';
   'size_budget'?: 'S' | 'M' | 'L' | 'XL';
+  /**
+   * Phase 27 (Plan 27-06) — peer-CLI delegation hint.
+   *
+   * Optional. Default unset = use local Anthropic call. Setting
+   * `delegate_to: gemini-research` tells session-runner "try delegate
+   * first, fall back to local on peer-absent / peer-error". Setting
+   * `delegate_to: none` explicitly opts out (e.g. security-sensitive
+   * agents). See agents/README.md "Peer-CLI delegation (delegate_to)"
+   * for the additive-superset rationale (CONTEXT D-06).
+   *
+   * Valid values are `<peer>-<role>` IDs that the peer-CLI registry
+   * capability matrix knows (e.g. `gemini-research`, `codex-execute`,
+   * `cursor-debug`, `cursor-plan`, `copilot-review`, `copilot-research`,
+   * `qwen-write`) plus the literal string `"none"`.
+   */
+  'delegate_to'?: string;
 }
 
 const REQUIRED_FIELDS: readonly (keyof AgentFrontmatter)[] = [
@@ -169,6 +275,48 @@ export function validateReasoningClass(
   return violations;
 }
 
+/**
+ * Validate the optional Phase 27 (Plan 27-06) `delegate_to` field. Returns
+ * an array of violation messages; empty means the agent passes.
+ *
+ * Rules (CONTEXT D-06):
+ *   1. `delegate_to` is OPTIONAL. Absence = use local Anthropic call.
+ *   2. If present, value MUST be a string.
+ *   3. The literal value `"none"` is accepted as the explicit opt-out.
+ *   4. Any other value MUST match a `<peer>-<role>` ID drawn from the
+ *      peer-CLI capability matrix (Plan 27-05's registry.cjs is the
+ *      source of truth; loadDelegateMatrix() resolves it lazily with
+ *      a literal fallback if the registry is unloadable).
+ *
+ * The 26 v1.26 baseline agents do not carry this field; this helper
+ * returns `[]` for them. The validator runs trivially clean on them.
+ */
+export function validateDelegateTo(
+  fm: Record<string, unknown>,
+  agentName: string,
+): string[] {
+  const violations: string[] = [];
+  const has = 'delegate_to' in fm && !isMissing(fm['delegate_to']);
+  if (!has) return violations;
+
+  const raw = fm['delegate_to'];
+  if (typeof raw !== 'string') {
+    violations.push(
+      `delegate_to: invalid value "${String(raw)}" for agent "${agentName}" — must be a string ("none" or "<peer>-<role>" e.g. "gemini-research")`,
+    );
+    return violations;
+  }
+  if (raw === 'none') return violations; // explicit opt-out
+
+  const valid = validDelegateIds();
+  if (!valid.includes(raw)) {
+    violations.push(
+      `delegate_to: invalid value "${raw}" for agent "${agentName}" — must be "none" or one of: ${valid.join(', ')} (peer-CLI capability matrix; see scripts/lib/peer-cli/registry.cjs)`,
+    );
+  }
+  return violations;
+}
+
 function walkMd(dir: string): string[] {
   const out: string[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -234,6 +382,16 @@ function main(): void {
       console.log(`${f}:${msg}`);
       violations++;
     }
+
+    // Plan 27-06 — peer-CLI delegate_to validation (additive optional field).
+    const delegateViolations = validateDelegateTo(
+      fm as Record<string, unknown>,
+      agentName,
+    );
+    for (const msg of delegateViolations) {
+      console.log(`${f}:${msg}`);
+      violations++;
+    }
   }
 
   console.log(`summary: ${files.length} file(s) checked, ${violations} violation(s)`);