@hegemonart/get-design-done 1.19.6 → 1.21.0

package/scripts/lib/harness/detect.ts

@@ -0,0 +1,90 @@
+// scripts/lib/harness/detect.ts — Plan 21-10 (SDK-22 / SDK-23).
+//
+// Harness detection runtime. Inspects the process env (or an injected
+// env map for tests) and reports which agent harness the current process
+// is running inside: Claude Code, OpenAI Codex CLI, Google Gemini CLI,
+// or `unknown` when no harness can be identified.
+//
+// Precedence (highest wins):
+//   1. `GDD_HARNESS` — explicit override. Accepts 'claude-code' | 'codex'
+//      | 'gemini' | 'unknown' verbatim. Anything else → 'unknown'.
+//   2. `CLAUDECODE=1` OR `CLAUDE_CODE=1` → 'claude-code'.
+//   3. `CODEX_CLI_VERSION` set (any truthy value) → 'codex'.
+//   4. `GEMINI_CLI_VERSION` set (any truthy value) → 'gemini'.
+//   5. Fallback → 'unknown'.
+//
+// This module is pure — no side effects, no caching. Callers that want
+// process-wide caching go through `scripts/lib/harness/index.ts`, which
+// layers a `currentHarness()` helper on top.
+
+export type Harness = 'claude-code' | 'codex' | 'gemini' | 'unknown';
+
+/** The four canonical harness identifiers this plugin recognizes. */
+export const KNOWN_HARNESSES: readonly Harness[] = Object.freeze([
+  'claude-code',
+  'codex',
+  'gemini',
+  'unknown',
+]);
+
+/**
+ * Detect which agent harness the current process is running inside.
+ *
+ * Reads the supplied env map (defaults to `process.env`). Precedence is
+ * documented at the top of this file — the explicit `GDD_HARNESS` override
+ * wins over implicit env-var detection to make tests and simulated fixtures
+ * deterministic.
+ */
+export function detectHarness(env?: NodeJS.ProcessEnv): Harness {
+  const e: NodeJS.ProcessEnv = env ?? process.env;
+
+  // 1. Explicit override wins.
+  const override: string | undefined = e.GDD_HARNESS;
+  if (override !== undefined && override !== '') {
+    if (isHarness(override)) return override;
+    // Any other non-empty string → 'unknown' (override is present but invalid).
+    return 'unknown';
+  }
+
+  // 2. Claude Code: either CLAUDECODE or CLAUDE_CODE set to "1".
+  if (e.CLAUDECODE === '1' || e.CLAUDE_CODE === '1') {
+    return 'claude-code';
+  }
+
+  // 3. Codex: CODEX_CLI_VERSION present (any non-empty value).
+  if (e.CODEX_CLI_VERSION !== undefined && e.CODEX_CLI_VERSION !== '') {
+    return 'codex';
+  }
+
+  // 4. Gemini: GEMINI_CLI_VERSION present (any non-empty value).
+  if (e.GEMINI_CLI_VERSION !== undefined && e.GEMINI_CLI_VERSION !== '') {
+    return 'gemini';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * True for harnesses that this plugin fully supports (Claude Code, Codex,
+ * Gemini). False for `'unknown'`.
+ *
+ * Callers use this as a gate before invoking harness-specific code paths;
+ * an unknown harness falls back to CC-native tool names (see
+ * `tool-map.ts TOOL_MAPS.unknown`).
+ */
+export function isSupportedHarness(h: Harness): boolean {
+  return h === 'claude-code' || h === 'codex' || h === 'gemini';
+}
+
+/**
+ * Narrow an arbitrary string to the `Harness` union. Not exported — used
+ * only by `detectHarness` to validate the `GDD_HARNESS` override.
+ */
+function isHarness(s: string): s is Harness {
+  return (
+    s === 'claude-code' ||
+    s === 'codex' ||
+    s === 'gemini' ||
+    s === 'unknown'
+  );
+}

package/scripts/lib/harness/index.ts

@@ -0,0 +1,64 @@
+// scripts/lib/harness/index.ts — Plan 21-10 (SDK-22 / SDK-23).
+//
+// Public API for the harness module. Re-exports the detect + tool-map
+// surfaces and adds a `currentHarness()` helper that caches the
+// first-call result for the life of the process.
+//
+// Why cache? Harness identity is a process-scoped invariant. The env
+// vars that drive detection (CLAUDECODE, CODEX_CLI_VERSION,
+// GEMINI_CLI_VERSION, GDD_HARNESS) are set by the harness when it
+// spawns us — they do not change mid-process. Repeated env reads are
+// cheap but the cache avoids any chance of divergent reads if a
+// downstream caller mutates process.env (tests sometimes do this, and
+// we want `currentHarness()` to stay monotonic within a test unless
+// `resetHarnessCache()` is called explicitly).
+//
+// Use `resetHarnessCache()` in test `beforeEach` to re-read env after
+// mutating it.
+
+import { detectHarness, isSupportedHarness, type Harness } from './detect.ts';
+
+export { detectHarness, isSupportedHarness, type Harness } from './detect.ts';
+export {
+  TOOL_MAPS,
+  mapTool,
+  reverseMapTool,
+  CC_TOOLS,
+  type CCTool,
+} from './tool-map.ts';
+
+let cached: Harness | undefined = undefined;
+
+/**
+ * Cached harness lookup. On first call, reads `process.env` via
+ * `detectHarness()` and stores the result. Every subsequent call
+ * returns the cached value, regardless of later env mutations.
+ *
+ * Call `resetHarnessCache()` to force a re-read.
+ */
+export function currentHarness(): Harness {
+  if (cached === undefined) {
+    cached = detectHarness(process.env);
+  }
+  return cached;
+}
+
+/**
+ * Clear the `currentHarness()` cache. Tests that mutate `process.env`
+ * between cases should call this in `beforeEach` (or equivalently)
+ * so each case sees a fresh detection.
+ */
+export function resetHarnessCache(): void {
+  cached = undefined;
+}
+
+/**
+ * True when the currently detected harness exposes MCP protocol support.
+ * Used by gdd-sdk audit to decide whether to spawn the gdd-state MCP
+ * server or import handlers directly.
+ *
+ * Claude Code, Codex, and Gemini all speak MCP; only `'unknown'` does not.
+ */
+export function harnessSupportsMCP(): boolean {
+  return isSupportedHarness(currentHarness());
+}

package/scripts/lib/harness/tool-map.ts

@@ -0,0 +1,142 @@
+// scripts/lib/harness/tool-map.ts — Plan 21-10 (SDK-22 / SDK-23).
+//
+// Cross-harness tool-name lookup table + helpers. Given a Claude Code
+// tool name (`Read`, `Write`, `Edit`, etc.) and a harness identifier,
+// return the native tool name on that harness. Also supports inverse
+// mapping (harness-native name → CC name).
+//
+// The maps are frozen (Object.freeze at two levels) — consumers cannot
+// accidentally mutate the tables. Any mutation attempt throws in strict
+// mode, silently no-ops otherwise; tests assert frozenness explicitly
+// to lock the invariant.
+//
+// Task spawning — the CC `Task` tool has no direct native equivalent on
+// Codex or Gemini (both require spawning a nested CLI instance as a
+// shell subprocess rather than a tool call). The map returns `null`
+// for those slots; callers check for null and fall back to a
+// `shell("npx gdd-sdk …")` invocation. See AGENTS.md / GEMINI.md.
+
+import type { Harness } from './detect.ts';
+
+/**
+ * Canonical Claude Code tool names the plugin references in skill prose.
+ * This is the shape against which per-harness maps are typed so that
+ * adding a new CC tool to the canonical set fails TSC on every harness
+ * map that forgets to include it.
+ */
+export type CCTool =
+  | 'Read'
+  | 'Write'
+  | 'Edit'
+  | 'Bash'
+  | 'Grep'
+  | 'Glob'
+  | 'Task'
+  | 'WebSearch'
+  | 'WebFetch';
+
+/** All nine CC tool names — useful for iteration in tests. */
+export const CC_TOOLS: readonly CCTool[] = Object.freeze([
+  'Read',
+  'Write',
+  'Edit',
+  'Bash',
+  'Grep',
+  'Glob',
+  'Task',
+  'WebSearch',
+  'WebFetch',
+]);
+
+/**
+ * Per-harness lookup. Each entry maps every CC tool to its native name
+ * on that harness, or `null` when the harness has no direct equivalent
+ * (currently only `Task` on Codex + Gemini).
+ *
+ * The `unknown` row falls back to CC names — callers that cannot identify
+ * the harness get a reasonable default that works on Claude Code and
+ * fails loudly on any other harness (the harness will refuse an
+ * unrecognized tool call).
+ */
+export const TOOL_MAPS: Readonly<Record<Harness, Readonly<Record<CCTool, string | null>>>> = Object.freeze({
+  'claude-code': Object.freeze({
+    Read: 'Read',
+    Write: 'Write',
+    Edit: 'Edit',
+    Bash: 'Bash',
+    Grep: 'Grep',
+    Glob: 'Glob',
+    Task: 'Task',
+    WebSearch: 'WebSearch',
+    WebFetch: 'WebFetch',
+  }),
+  codex: Object.freeze({
+    Read: 'read_file',
+    Write: 'apply_patch',
+    Edit: 'apply_patch',
+    Bash: 'shell',
+    Grep: 'shell',
+    Glob: 'shell',
+    Task: null, // no native Task; use CLI subprocess
+    WebSearch: 'web_search',
+    WebFetch: 'shell',
+  }),
+  gemini: Object.freeze({
+    Read: 'read_file',
+    Write: 'write_file',
+    Edit: 'replace',
+    Bash: 'run_shell_command',
+    Grep: 'search_file_content',
+    Glob: 'glob',
+    Task: null, // no native Task; use CLI subprocess
+    WebSearch: 'google_web_search',
+    WebFetch: 'web_fetch',
+  }),
+  unknown: Object.freeze({
+    Read: 'Read',
+    Write: 'Write',
+    Edit: 'Edit',
+    Bash: 'Bash',
+    Grep: 'Grep',
+    Glob: 'Glob',
+    Task: 'Task',
+    WebSearch: 'WebSearch',
+    WebFetch: 'WebFetch',
+  }),
+});
+
+/**
+ * Return the harness-specific tool name for a CC tool. Returns `null`
+ * when the harness has no native equivalent — currently only `Task` on
+ * Codex + Gemini. Callers that receive `null` should fall back to a
+ * `shell`/`run_shell_command` invocation of `npx gdd-sdk …`.
+ */
+export function mapTool(harness: Harness, ccTool: CCTool): string | null {
+  const row = TOOL_MAPS[harness];
+  // Every Harness key is present in TOOL_MAPS by construction (the type
+  // forces it). The index result under `noUncheckedIndexedAccess` is
+  // still `string | null | undefined`; narrow with a hasOwnProperty
+  // check to keep TSC happy.
+  const native: string | null | undefined = row[ccTool];
+  return native ?? null;
+}
+
+/**
+ * Inverse of `mapTool` — given a harness-native tool name (e.g.
+ * `'read_file'`), return the CC tool it came from (`'Read'`). Returns
+ * `null` when the native name is not in the harness's map at all.
+ *
+ * Note: on Codex several CC tools share a native name (`Write`, `Edit`,
+ * `WebFetch` all share `apply_patch` / `shell`). The reverse mapper
+ * returns the FIRST CC match walking in declaration order
+ * (`Read` → `Write` → `Edit` → …) — callers that need disambiguation
+ * between, e.g., create vs. update must consult the full forward map
+ * or inspect tool-call arguments.
+ */
+export function reverseMapTool(harness: Harness, nativeName: string): CCTool | null {
+  const row = TOOL_MAPS[harness];
+  for (const cc of CC_TOOLS) {
+    if (row[cc] === nativeName) return cc;
+  }
+  return null;
+}

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

@@ -0,0 +1,396 @@
+// scripts/lib/init-runner/index.ts — public entry for the `gdd-sdk init`
+// runner (Plan 21-08, SDK-20).
+//
+// Public surface:
+//
+//   run(opts: InitRunnerOptions): Promise<InitRunnerResult>
+//   DEFAULT_RESEARCHERS: readonly ResearcherSpec[]
+//   + re-exports of submodule types + helpers.
+//
+// Orchestration algorithm:
+//
+//   1. Resolve cwd + .design/ path.
+//   2. Existence check on .design/STATE.md:
+//      - exists + !force → return status: 'already-initialized'
+//      - exists + force  → backup via backupExistingDesignDir
+//   3. ensureDesignDirs (idempotent).
+//   4. writeStateFromTemplate. Missing template → status: 'error'.
+//   5. spawnResearchersParallel with concurrency ?? 4.
+//   6. Filter to successful outcomes. Zero → status: 'no-researchers-succeeded'.
+//   7. Read each successful output; build SynthesizerInput[].
+//   8. spawnSynthesizer.
+//   9. Aggregate usage + emit lifecycle logs.
+//  10. Return InitRunnerResult.
+//
+// This module emits two logger events:
+//   * init.runner.started   — before researcher dispatch.
+//   * init.runner.completed — regardless of status.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { getLogger } from '../logger/index.ts';
+import {
+  spawnResearcher,
+  spawnResearchersParallel,
+} from './researchers.ts';
+import {
+  buildSynthesizerPrompt,
+  DEFAULT_SYNTHESIZER_PROMPT,
+  spawnSynthesizer,
+} from './synthesizer.ts';
+import {
+  backupExistingDesignDir,
+  ensureDesignDirs,
+  resolveStateTemplatePath,
+  writeStateFromTemplate,
+} from './scaffold.ts';
+import type {
+  InitRunnerOptions,
+  InitRunnerResult,
+  InitStatus,
+  ResearcherName,
+  ResearcherOutcome,
+  ResearcherSpec,
+} from './types.ts';
+
+// ---------------------------------------------------------------------------
+// Re-exports — consumers import everything from this file.
+// ---------------------------------------------------------------------------
+
+export type {
+  InitRunnerOptions,
+  InitRunnerResult,
+  InitStatus,
+  ResearcherName,
+  ResearcherOutcome,
+  ResearcherSpec,
+} from './types.ts';
+export { spawnResearcher, spawnResearchersParallel } from './researchers.ts';
+export {
+  buildSynthesizerPrompt,
+  DEFAULT_SYNTHESIZER_PROMPT,
+  spawnSynthesizer,
+} from './synthesizer.ts';
+export type {
+  SpawnSynthesizerArgs,
+  SpawnSynthesizerResult,
+  SynthesizerInput,
+} from './synthesizer.ts';
+export type {
+  SpawnParallelOptions,
+  SpawnResearcherOptions,
+} from './researchers.ts';
+export {
+  backupExistingDesignDir,
+  ensureDesignDirs,
+  resolveStateTemplatePath,
+  writeStateFromTemplate,
+} from './scaffold.ts';
+
+// ---------------------------------------------------------------------------
+// DEFAULT_RESEARCHERS — frozen roster of four
+// ---------------------------------------------------------------------------
+
+/**
+ * The locked 4-researcher roster run by default. Callers can override
+ * via `opts.researchers`, but the roster is stable enough that widening
+ * it would be a breaking change (CLI summary rendering, telemetry
+ * aggregation, and the synthesizer prompt all depend on exactly four).
+ */
+export const DEFAULT_RESEARCHERS: readonly ResearcherSpec[] = Object.freeze([
+  Object.freeze({
+    name: 'design-system-audit' as const,
+    prompt:
+      'Audit this repo for existing design system surface: design tokens (CSS vars, Tailwind config, JS const exports), components (file names + prop shapes), patterns (recurring UI idioms). Output .design/research/design-system-audit.md with findings organized as: Tokens, Components, Patterns, Gaps.',
+    outputPath: '.design/research/design-system-audit.md',
+  }),
+  Object.freeze({
+    name: 'brand-context' as const,
+    prompt:
+      'Scan this repo for brand signals: README, marketing/landing pages, style guides, voice/tone docs. Infer archetype (per reference/typography.md), voice, visual tone. Output .design/research/brand-context.md.',
+    outputPath: '.design/research/brand-context.md',
+  }),
+  Object.freeze({
+    name: 'accessibility-baseline' as const,
+    prompt:
+      'Scan this repo for WCAG conformance baseline: color contrast, keyboard navigation, ARIA labels, focus management, motion preferences. Output .design/research/accessibility-baseline.md with findings + a conformance score (AA / partial / fail).',
+    outputPath: '.design/research/accessibility-baseline.md',
+  }),
+  Object.freeze({
+    name: 'competitive-references' as const,
+    prompt:
+      'Identify 3-5 peer products in the same domain as this repo. Use WebSearch + WebFetch. For each, extract design patterns worth referencing. Output .design/research/competitive-references.md.',
+    outputPath: '.design/research/competitive-references.md',
+  }),
+]);
+
+// ---------------------------------------------------------------------------
+// run — top-level orchestrator
+// ---------------------------------------------------------------------------
+
+/** Default concurrency when not specified. Matches the 4-researcher roster. */
+const DEFAULT_CONCURRENCY = 4;
+
+/**
+ * Bootstrap a `.design/` directory for a fresh project. See module
+ * header for the algorithm. Never throws; every failure mode surfaces
+ * as `InitRunnerResult.status`.
+ */
+export async function run(opts: InitRunnerOptions): Promise<InitRunnerResult> {
+  const logger = getLogger();
+  const cwd = resolve(opts.cwd ?? process.cwd());
+  const designDir = resolve(cwd, '.design');
+  const researchers = opts.researchers ?? DEFAULT_RESEARCHERS;
+
+  logger.info('init.runner.started', {
+    cwd,
+    design_dir: designDir,
+    researcher_count: researchers.length,
+    force: opts.force === true,
+  });
+
+  // ------------------------------------------------------------------
+  // 1. Re-init safety check.
+  // ------------------------------------------------------------------
+  const stateMdPath = resolve(designDir, 'STATE.md');
+  let backupDir: string | null = null;
+  if (existsSync(stateMdPath)) {
+    if (opts.force !== true) {
+      const result = buildResult({
+        status: 'already-initialized',
+        cwd,
+        designDir,
+        researchers: [],
+        stateMdWritten: false,
+        designContextMdWritten: false,
+        totalUsage: zeroUsage(),
+      });
+      logger.info('init.runner.completed', logPayloadFor(result));
+      return result;
+    }
+    backupDir = backupExistingDesignDir(cwd);
+  }
+
+  // ------------------------------------------------------------------
+  // 2. Ensure .design/ + .design/research/ exist.
+  // ------------------------------------------------------------------
+  ensureDesignDirs(cwd);
+
+  // ------------------------------------------------------------------
+  // 3. Write STATE.md from template.
+  // ------------------------------------------------------------------
+  const templatePath =
+    opts.stateTemplatePath ?? resolveStateTemplatePath() ?? '';
+  const stateWritten = templatePath === ''
+    ? false
+    : writeStateFromTemplate({
+        cwd,
+        templatePath,
+        destPath: stateMdPath,
+      });
+
+  if (!stateWritten) {
+    const result = buildResult({
+      status: 'error',
+      cwd,
+      designDir,
+      researchers: [],
+      stateMdWritten: false,
+      designContextMdWritten: false,
+      totalUsage: zeroUsage(),
+      ...(backupDir !== null ? { backupDir } : {}),
+    });
+    logger.error('init.runner.completed', {
+      ...logPayloadFor(result),
+      reason: 'STATE-TEMPLATE.md not found or unreadable',
+      template_path: templatePath,
+    });
+    return result;
+  }
+
+  // ------------------------------------------------------------------
+  // 4. Spawn researchers in parallel.
+  // ------------------------------------------------------------------
+  const outcomes = await spawnResearchersParallel(researchers, {
+    concurrency: opts.concurrency ?? DEFAULT_CONCURRENCY,
+    budget: opts.budget,
+    maxTurns: opts.maxTurnsPerResearcher,
+    cwd,
+    ...(opts.runOverride !== undefined
+      ? { runOverride: opts.runOverride }
+      : {}),
+  });
+
+  const successful = outcomes.filter(
+    (o) => o.status === 'completed' && o.output_exists,
+  );
+  if (successful.length === 0) {
+    const totalUsage = aggregateUsage(outcomes);
+    const result = buildResult({
+      status: 'no-researchers-succeeded',
+      cwd,
+      designDir,
+      researchers: outcomes,
+      stateMdWritten: true,
+      designContextMdWritten: false,
+      totalUsage,
+      ...(backupDir !== null ? { backupDir } : {}),
+    });
+    logger.warn('init.runner.completed', {
+      ...logPayloadFor(result),
+      reason: 'all researchers failed or produced no output',
+    });
+    return result;
+  }
+
+  // ------------------------------------------------------------------
+  // 5. Load successful researcher outputs and spawn synthesizer.
+  // ------------------------------------------------------------------
+  const specByName = new Map<ResearcherName, ResearcherSpec>(
+    researchers.map((s) => [s.name, s]),
+  );
+  const synthesizerInputs = successful
+    .map((o) => {
+      const spec = specByName.get(o.name);
+      if (spec === undefined) return null;
+      const absPath = resolve(cwd, spec.outputPath);
+      let content: string;
+      try {
+        content = readFileSync(absPath, 'utf8');
+      } catch {
+        return null;
+      }
+      return { name: o.name, path: absPath, content };
+    })
+    .filter((x): x is { name: ResearcherName; path: string; content: string } =>
+      x !== null,
+    );
+
+  const synth = await spawnSynthesizer({
+    researcherOutputs: synthesizerInputs,
+    cwd,
+    budget: opts.synthesizerBudget,
+    maxTurns: opts.synthesizerMaxTurns,
+    ...(opts.runOverride !== undefined
+      ? { runOverride: opts.runOverride }
+      : {}),
+    ...(opts.synthesizerPromptOverride !== undefined
+      ? { promptOverride: opts.synthesizerPromptOverride }
+      : {}),
+  });
+
+  // ------------------------------------------------------------------
+  // 6. Aggregate + return.
+  // ------------------------------------------------------------------
+  const totalUsage = aggregateUsageAll(outcomes, synth.usage);
+  const designContextWritten = synth.status === 'completed';
+  const status: InitStatus = 'completed';
+
+  const result = buildResult({
+    status,
+    cwd,
+    designDir,
+    researchers: outcomes,
+    stateMdWritten: true,
+    designContextMdWritten: designContextWritten,
+    totalUsage,
+    ...(backupDir !== null ? { backupDir } : {}),
+  });
+
+  if (synth.status !== 'completed') {
+    logger.warn('init.runner.completed', {
+      ...logPayloadFor(result),
+      synthesizer_error: synth.error ?? 'unknown',
+    });
+  } else {
+    logger.info('init.runner.completed', logPayloadFor(result));
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function zeroUsage(): InitRunnerResult['total_usage'] {
+  return { input_tokens: 0, output_tokens: 0, usd_cost: 0 };
+}
+
+function aggregateUsage(
+  outcomes: readonly ResearcherOutcome[],
+): InitRunnerResult['total_usage'] {
+  let input = 0;
+  let output = 0;
+  let cost = 0;
+  for (const o of outcomes) {
+    input += o.usage.input_tokens;
+    output += o.usage.output_tokens;
+    cost += o.usage.usd_cost;
+  }
+  return { input_tokens: input, output_tokens: output, usd_cost: cost };
+}
+
+function aggregateUsageAll(
+  outcomes: readonly ResearcherOutcome[],
+  synthUsage: { input_tokens: number; output_tokens: number; usd_cost: number },
+): InitRunnerResult['total_usage'] {
+  const researcherUsage = aggregateUsage(outcomes);
+  return {
+    input_tokens: researcherUsage.input_tokens + synthUsage.input_tokens,
+    output_tokens: researcherUsage.output_tokens + synthUsage.output_tokens,
+    usd_cost: researcherUsage.usd_cost + synthUsage.usd_cost,
+  };
+}
+
+interface BuildResultInput {
+  readonly status: InitStatus;
+  readonly cwd: string;
+  readonly designDir: string;
+  readonly researchers: readonly ResearcherOutcome[];
+  readonly stateMdWritten: boolean;
+  readonly designContextMdWritten: boolean;
+  readonly totalUsage: InitRunnerResult['total_usage'];
+  readonly backupDir?: string;
+}
+
+function buildResult(input: BuildResultInput): InitRunnerResult {
+  const scaffold: InitRunnerResult['scaffold'] = input.backupDir !== undefined
+    ? {
+        state_md_written: input.stateMdWritten,
+        design_context_md_written: input.designContextMdWritten,
+        backup_dir: input.backupDir,
+      }
+    : {
+        state_md_written: input.stateMdWritten,
+        design_context_md_written: input.designContextMdWritten,
+      };
+
+  return Object.freeze({
+    status: input.status,
+    cwd: input.cwd,
+    design_dir: input.designDir,
+    researchers: input.researchers,
+    scaffold,
+    total_usage: input.totalUsage,
+  });
+}
+
+function logPayloadFor(result: InitRunnerResult): Record<string, unknown> {
+  return {
+    status: result.status,
+    cwd: result.cwd,
+    design_dir: result.design_dir,
+    researcher_total: result.researchers.length,
+    researcher_succeeded: result.researchers.filter(
+      (r) => r.status === 'completed' && r.output_exists,
+    ).length,
+    state_md_written: result.scaffold.state_md_written,
+    design_context_md_written: result.scaffold.design_context_md_written,
+    ...(result.scaffold.backup_dir !== undefined
+      ? { backup_dir: result.scaffold.backup_dir }
+      : {}),
+    total_usage: result.total_usage,
+  };
+}