copperhead 0.3.0 → 0.5.0

package/src/commands/check.ts

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs';
 import { loadConfig } from '../config.js';
 import { runErc, runDrc } from '../kicad/cli.js';
 import { formatViolations, type CheckReport } from '../kicad/report.js';
-import { checkDrift, type DriftMismatch } from '../memory/drift.js';
+import { checkDrift, emptySchematicWarning, type DriftMismatch } from '../memory/drift.js';
 import { loadConstraints, checkForbiddenPins, type ConstraintViolation } from '../memory/constraints.js';
 import { pinNets } from '../kicad/sexp.js';
 import { openspecValidate } from '../openspec/cli.js';
@@ -16,7 +16,7 @@ export interface CheckResult {
   ok: boolean;
   erc: { ok: boolean; violations: number } | null;
   drc: { ok: boolean; violations: number } | null;
-  drift: { ok: boolean; mismatches: DriftMismatch[] };
+  drift: { ok: boolean; mismatches: DriftMismatch[]; warning?: string };
   openspec: { ok: boolean; detail: string } | null;
   constraints: { ok: boolean; violations: ConstraintViolation[] };
 }
@@ -41,9 +41,15 @@ export async function runCheck(repoRoot: string, log: (s: string) => void): Prom
   }
 
   let drift: DriftMismatch[] = [];
+  let driftWarning: string | null = null;
   if (config.schematic && existsSync(path.join(repoRoot, config.schematic))) {
     drift = await checkDrift(repoRoot, config.docs, config.schematic);
     log(drift.length === 0 ? 'drift ✓' : drift.map((m) => `drift: ${m.doc} claims "${m.claim}" but actual is "${m.actual}"`).join('\n'));
+    // Informational, never a failure: the zero-symbol drift exemption is for
+    // bootstrap, but an established repo that lost its schematic content
+    // deserves a visible note rather than a silent green.
+    driftWarning = await emptySchematicWarning(repoRoot, config.docs, config.schematic);
+    if (driftWarning) log(`drift warning: ${driftWarning}`);
   }
 
   let openspec: { ok: boolean; detail: string } | null = null;
@@ -78,7 +84,7 @@ export async function runCheck(repoRoot: string, log: (s: string) => void): Prom
     ok,
     erc: erc ? { ok: erc.ok, violations: erc.violations.length } : null,
     drc: drc ? { ok: drc.ok, violations: drc.violations.length } : null,
-    drift: { ok: drift.length === 0, mismatches: drift },
+    drift: { ok: drift.length === 0, mismatches: drift, ...(driftWarning ? { warning: driftWarning } : {}) },
     openspec,
     constraints: { ok: constraintViolations.length === 0, violations: constraintViolations },
   };

package/src/commands/create.ts

@@ -1,8 +1,13 @@
 import path from 'node:path';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { loadConfig } from '../config.js';
-import { runAgentLoop } from '../agent/loop.js';
+import { listSymbols } from '../kicad/sexp.js';
+import { checkDrift } from '../memory/drift.js';
+import { runAgentLoop, type BudgetExhaustedStats } from '../agent/loop.js';
+import type { RunMetaInput } from '../agent/runmeta.js';
+import type { ProgressRenderer } from '../agent/render.js';
 import { openspecInit } from '../openspec/cli.js';
 import { runCheck } from './check.js';
 
@@ -51,14 +56,36 @@ export const STAGES: Stage[] = [
     name: 'schematic',
     isComplete: async (root) => {
       const config = await loadConfig(root);
-      return !!config.schematic && existsSync(path.join(root, config.schematic));
+      if (!config.schematic) return false;
+      const p = path.join(root, config.schematic);
+      if (!existsSync(p)) return false;
+      // Mere file existence is not completion: bootstrapping leaves a blank
+      // sheet on disk (a hand-scaffolded project, or the future fix for #19),
+      // and skipping this stage over a blank sheet cascades — layout and
+      // outputs then run against nothing. The stage's contract is "build the
+      // schematic from BOM.md", so completion means symbols exist AND the
+      // BOM/PINOUT tables agree with them (drift-clean); anything less keeps
+      // the stage active on the next resume so partial capture continues.
+      if (!(await listSymbols(p)).length) return false;
+      return (await checkDrift(root, config.docs, config.schematic)).length === 0;
     },
     prompt: () =>
       'Stage 4: schematic. Build the schematic sheet by sheet from BOM.md and SUBSYSTEMS.md. After each sheet, run run_erc and fix violations before moving on. Same net names and refdes everywhere. Update PINOUT.md as you assign pins; check the strapping table first.',
   },
   {
     name: 'layout-draft',
-    isComplete: (root, docs) => docHasContent(root, path.join(docs, 'LAYOUT.md'), '## Draft quality'),
+    isComplete: async (root, docs) => {
+      // The LAYOUT.md marker alone is not enough: `copperhead init` scaffolds
+      // LAYOUT.md with the literal "## Draft quality" heading, so an init-ed
+      // repo would skip this stage without a single footprint placed. Require
+      // a board with at least one footprint on it as well.
+      const config = await loadConfig(root);
+      if (!config.board) return false;
+      const p = path.join(root, config.board);
+      if (!existsSync(p)) return false;
+      if (!(await readFile(p, 'utf8')).includes('(footprint')) return false;
+      return docHasContent(root, path.join(docs, 'LAYOUT.md'), '## Draft quality');
+    },
     prompt: () =>
       'Stage 5: first-draft layout. Rule-driven placement written as real coordinates: connectors on edges, decoupling at IC pins, ESD at connectors, keepouts honored. Route power and short critical nets; leave the rest as ratsnest. Every routed net must pass run_drc. Then write the "## Draft quality" section in LAYOUT.md: exactly what is fine and what a human or specialist tool should redo. Non-optimal is acceptable; unlabeled non-optimal is not.',
   },
@@ -87,22 +114,31 @@ export interface CreateOptions {
   briefPath: string;
   model: string;
   interactive?: boolean;
+  /** Forwarded to each stage's run (attended continue-on-exhaustion prompt). */
+  onBudgetExhausted?: (stats: BudgetExhaustedStats) => Promise<number>;
   log: (s: string) => void;
+  renderer?: ProgressRenderer;
+  /** Command-level metadata; stage and brief identity are filled in per stage. */
+  meta?: Omit<RunMetaInput, 'stage' | 'brief'>;
 }
 
 export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; completed: string[] }> {
   const brief = await readFile(path.resolve(opts.briefPath), 'utf8');
+  // Hashed from the content already in hand: a brief edited mid-pipeline shows
+  // up as a different sha256 in the next stage's metadata (AC-8.1).
+  const briefMeta = { path: opts.briefPath, sha256: createHash('sha256').update(brief).digest('hex') };
   const config = await loadConfig(opts.repoRoot);
   await openspecInit(opts.repoRoot);
   const completed: string[] = [];
 
-  for (const stage of STAGES) {
+  for (const [i, stage] of STAGES.entries()) {
     if (await stage.isComplete(opts.repoRoot, config.docs)) {
       opts.log(`stage ${stage.name}: already complete (resuming past it)`);
       completed.push(stage.name);
       continue;
     }
     opts.log(`stage ${stage.name}: running`);
+    const stageTurns = config.stageMaxTurns?.[stage.name];
     const res = await runAgentLoop({
       repoRoot: opts.repoRoot,
       model: opts.model,
@@ -110,12 +146,33 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
       stagePrompt: stage.prompt(brief),
       interactive: opts.interactive ?? false,
       allowDirty: true, // stages build on each other's uncommitted state within the pipeline
+      ...(stageTurns !== undefined ? { maxTurns: stageTurns } : {}),
+      ...(opts.onBudgetExhausted ? { onBudgetExhausted: opts.onBudgetExhausted } : {}),
       log: opts.log,
+      ...(opts.renderer ? { renderer: opts.renderer } : {}),
+      meta: {
+        ...opts.meta,
+        command: 'create',
+        stage: { name: stage.name, index: i + 1, total: STAGES.length },
+        brief: briefMeta,
+      },
     });
     if (res.outcome !== 'success') {
       opts.log(`stage ${stage.name} did not complete (${res.outcome}); re-run copperhead create to resume here`);
       return { ok: false, completed };
     }
+    // A successful run is not the same as a completed stage: an agent can
+    // finish "done" with all gates green having only planned the work (seen
+    // with the schematic stage: one header edit, ERC "clean" on an empty
+    // sheet). Advancing anyway lets every later stage run against a design
+    // that isn't there, so hold the pipeline until this stage's repo-state
+    // contract is actually met.
+    if (!(await stage.isComplete(opts.repoRoot, config.docs))) {
+      opts.log(
+        `stage ${stage.name}: run succeeded but the stage contract is not met yet (partial work committed); re-run copperhead create to continue this stage`,
+      );
+      return { ok: false, completed };
+    }
     completed.push(stage.name);
   }
 

package/src/commands/sync.ts

@@ -7,6 +7,8 @@ import { loadConstraints, checkForbiddenPins } from '../memory/constraints.js';
 import { pinNets } from '../kicad/sexp.js';
 import { openspecValidate } from '../openspec/cli.js';
 import { runAgentLoop } from '../agent/loop.js';
+import type { RunMetaInput } from '../agent/runmeta.js';
+import type { ProgressRenderer } from '../agent/render.js';
 
 /**
  * `copperhead sync` (design D14): deterministic verify phase, then an optional
@@ -169,6 +171,7 @@ export async function syncResolve(
   report: SyncReport,
   model: string,
   log: (s: string) => void,
+  extras?: { renderer?: ProgressRenderer; meta?: RunMetaInput },
 ): Promise<{ ok: boolean }> {
   const reportText = formatSyncReport(report);
   const res = await runAgentLoop({
@@ -177,6 +180,8 @@ export async function syncResolve(
     request: 'resolve design-state inconsistencies found by copperhead sync',
     stagePrompt: `You are resolving drift found by the deterministic sync verifier. The inconsistency report is below. Truth precedence: the KiCad files are ground truth for as-built facts (fix the docs to match); openspec specs and SPEC.md budgets are ground truth for requirements. Do NOT touch anything listed as a requirement violation; those are for the human. Apply each proposed resolution, verify, and finish.\n\n${reportText}`,
     log,
+    ...(extras?.renderer ? { renderer: extras.renderer } : {}),
+    ...(extras?.meta ? { meta: extras.meta } : {}),
   });
   return { ok: res.outcome === 'success' };
 }

package/src/config.ts

@@ -8,6 +8,8 @@ export interface CopperheadConfig {
   docs: string;
   model: string | null;
   maxTurns: number;
+  /** Per-stage overrides for the create pipeline, keyed by stage name. */
+  stageMaxTurns?: Record<string, number>;
   maxRepairCycles: number;
   budgets: Record<string, number>;
   /** Content hashes of generated docs, for init idempotency (AC-1.4). */
@@ -34,20 +36,36 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
     return { schematic: null, board: null, ...DEFAULTS };
   }
   const raw = JSON.parse(await readFile(p, 'utf8')) as Partial<CopperheadConfig>;
+  // A zero/negative/non-integer stage budget would exhaust the stage on turn 0;
+  // drop such entries rather than let a config typo stall the pipeline.
+  const stageMaxTurns = Object.fromEntries(
+    Object.entries(raw.stageMaxTurns ?? {}).filter(([, v]) => Number.isInteger(v) && v > 0),
+  );
   return {
     schematic: raw.schematic ?? null,
     board: raw.board ?? null,
     docs: raw.docs ?? DEFAULTS.docs,
     model: raw.model ?? null,
     maxTurns: raw.maxTurns ?? DEFAULTS.maxTurns,
+    ...(Object.keys(stageMaxTurns).length ? { stageMaxTurns } : {}),
     maxRepairCycles: raw.maxRepairCycles ?? DEFAULTS.maxRepairCycles,
     budgets: raw.budgets ?? {},
     ...(raw.generatedHashes ? { generatedHashes: raw.generatedHashes } : {}),
   };
 }
 
+/** Which level of the model-selection precedence chain won. */
+export type ModelSource = 'flag' | 'env' | 'config' | 'openai-key' | 'anthropic-key';
+
+export interface ResolvedModel {
+  model: string;
+  source: ModelSource;
+}
+
 /**
  * Model selection precedence: flag > COPPERHEAD_MODEL > config > available key.
+ * The winning source is returned alongside the model so run metadata can
+ * record why a run used the model it did (AC-8.1/8.2).
  *
  * Accepted values (same set for `--model`, COPPERHEAD_MODEL, and `model` in
  * .copperhead/config.json):
@@ -55,6 +73,8 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
  * - `claude`  : the Anthropic provider on its default model.
  * - `claude-*`: any Anthropic model id, passed through verbatim, e.g.
  *               `claude-opus-4-5`. Anything starting with `claude` routes here.
+ * - `codex`   : the locally installed Codex CLI using its saved ChatGPT login.
+ * - `codex:*` : Codex CLI with an explicit model id, e.g. `codex:gpt-5.6`.
  * - `gpt-5`   : the OpenAI provider on its default model.
  * - anything else: sent to the OpenAI provider verbatim as a model id, e.g.
  *               `gpt-5-mini` or `o3`.
@@ -62,16 +82,16 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
  * Routing is prefix-based, not a fixed list (see makeProvider in agent/loop.ts),
  * so a model released after this build still works without a code change. The
  * cost is that a typo like `claud-sonnet-5` silently routes to OpenAI and fails
- * there. The chosen provider must have its key set: ANTHROPIC_API_KEY for
- * `claude*`, OPENAI_API_KEY otherwise.
+ * there. Anthropic and direct OpenAI providers require their API keys; `codex`
+ * instead requires a locally installed and authenticated Codex CLI.
  */
-export function resolveModel(flag: string | undefined, config: CopperheadConfig, env = process.env): string {
-  if (flag) return flag;
-  if (env.COPPERHEAD_MODEL) return env.COPPERHEAD_MODEL;
-  if (config.model) return config.model;
-  if (env.OPENAI_API_KEY) return 'gpt-5';
-  if (env.ANTHROPIC_API_KEY) return 'claude';
+export function resolveModel(flag: string | undefined, config: CopperheadConfig, env = process.env): ResolvedModel {
+  if (flag) return { model: flag, source: 'flag' };
+  if (env.COPPERHEAD_MODEL) return { model: env.COPPERHEAD_MODEL, source: 'env' };
+  if (config.model) return { model: config.model, source: 'config' };
+  if (env.OPENAI_API_KEY) return { model: 'gpt-5', source: 'openai-key' };
+  if (env.ANTHROPIC_API_KEY) return { model: 'claude', source: 'anthropic-key' };
   throw new Error(
-    'no model configured: pass --model, set COPPERHEAD_MODEL, set model in .copperhead/config.json, or provide OPENAI_API_KEY/ANTHROPIC_API_KEY',
+    'no model configured: pass --model codex (uses your local Codex login), set COPPERHEAD_MODEL, set model in .copperhead/config.json, or provide OPENAI_API_KEY/ANTHROPIC_API_KEY',
   );
 }

package/src/kicad/cli.ts

@@ -3,11 +3,18 @@ import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { normalizeReport, type CheckReport } from './report.js';
+import { PreflightError } from '../util/preflight.js';
 
-export class KicadCliMissingError extends Error {
+export class KicadCliMissingError extends PreflightError {
   constructor() {
     super(
-      'kicad-cli not found on PATH. Install KiCad ≥ 8 (https://www.kicad.org/download/) and ensure kicad-cli is available.',
+      'kicad-cli not found on PATH',
+      'copperhead verifies every mutation with kicad-cli ERC/DRC; without it no edit can be checked, so no run can start',
+      [
+        'install KiCad ≥ 8: https://www.kicad.org/download/',
+        'ensure the kicad-cli binary is on PATH (on macOS it ships inside KiCad.app/Contents/MacOS)',
+        'confirm with "kicad-cli version", then rerun',
+      ],
     );
     this.name = 'KicadCliMissingError';
   }
@@ -32,16 +39,27 @@ async function runCheck(
   const out = path.join(dir, `${kind}.json`);
   const sub = kind === 'erc' ? ['sch', 'erc'] : ['pcb', 'drc'];
   try {
-    await execa(
+    const res = await execa(
       'kicad-cli',
       [...sub, '--format', 'json', '--exit-code-violations', '--output', out, ...extraArgs, filePath],
       { reject: false },
-    ).then((res) => {
-      if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
-        throw new KicadCliMissingError();
-      }
-    });
-    const raw = JSON.parse(await readFile(out, 'utf8'));
+    );
+    if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
+      throw new KicadCliMissingError();
+    }
+    let raw: unknown;
+    try {
+      raw = JSON.parse(await readFile(out, 'utf8'));
+    } catch {
+      // No report on disk means kicad-cli bailed before checking — usually the
+      // design file itself failed to load (syntax/schema corruption). The
+      // raw readFile ENOENT told the agent nothing actionable; kicad-cli's
+      // own output at least names the failure.
+      const detail = [res.stderr, res.stdout].filter(Boolean).join('\n').trim();
+      throw new Error(
+        `kicad-cli ${kind} produced no report — the ${kind === 'erc' ? 'schematic' : 'board'} file likely fails to load in KiCad. kicad-cli output: ${detail || '(none)'}`,
+      );
+    }
     return normalizeReport(raw, kind);
   } finally {
     await rm(dir, { recursive: true, force: true });
@@ -52,6 +70,39 @@ export function runErc(schPath: string): Promise<CheckReport> {
   return runCheck('erc', schPath);
 }
 
+/**
+ * Cheap loadability probe for a KiCad file: asks kicad-cli for a throwaway
+ * export and reports the failure text if the file won't load. Text edits on
+ * s-expression sources can silently corrupt the file; catching that at edit
+ * time (with KiCad's own error) beats an opaque failure at ERC/DRC time.
+ * Returns null when the file loads.
+ */
+/**
+ * Only schematics and boards have a cheap standalone load probe. Project
+ * files and symbol/footprint libraries do not: feeding them to a sch/pcb
+ * export "probe" would reject perfectly good files.
+ */
+export function isProbeableKicadFile(p: string): boolean {
+  return /\.kicad_(sch|pcb)$/.test(p);
+}
+
+export async function kicadLoadError(filePath: string): Promise<string | null> {
+  if (!isProbeableKicadFile(filePath)) return null;
+  const isSch = filePath.endsWith('.kicad_sch');
+  const dir = await mkdtemp(path.join(tmpdir(), 'copperhead-validate-'));
+  const args = isSch
+    ? ['sch', 'export', 'netlist', '--output', path.join(dir, 'probe.net'), filePath]
+    : ['pcb', 'export', 'pos', '--output', path.join(dir, 'probe.pos'), filePath];
+  try {
+    const res = await execa('kicad-cli', args, { reject: false });
+    if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
+    if (res.exitCode === 0) return null;
+    return [res.stderr, res.stdout].filter(Boolean).join('\n').trim() || `kicad-cli exited ${res.exitCode}`;
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
 export function runDrc(pcbPath: string): Promise<CheckReport> {
   return runCheck('drc', pcbPath);
 }

package/src/memory/constraints.ts

@@ -14,6 +14,13 @@ export interface Constraint {
   value?: string | number;
   source: string;
   affects: string[];
+  /**
+   * Subset of `affects` whose target artifact (schematic/board/BOM) did not
+   * exist when the constraint was recorded. No revisit obligation is open for
+   * these; they re-open at the start of the first run where the artifact
+   * exists (reopenDeferredAffects), then the marker is removed.
+   */
+  deferred?: string[];
 }
 
 export type ConstraintRegistry = Record<string, Constraint>;
@@ -28,6 +35,12 @@ export async function loadConstraints(repoRoot: string): Promise<ConstraintRegis
   return JSON.parse(await readFile(p, 'utf8')) as ConstraintRegistry;
 }
 
+export async function saveConstraints(repoRoot: string, registry: ConstraintRegistry): Promise<void> {
+  const p = constraintsPath(repoRoot);
+  await mkdir(path.dirname(p), { recursive: true });
+  await writeFile(p, JSON.stringify(registry, null, 2) + '\n', 'utf8');
+}
+
 export async function saveConstraint(
   repoRoot: string,
   key: string,
@@ -35,12 +48,86 @@ export async function saveConstraint(
 ): Promise<ConstraintRegistry> {
   const registry = await loadConstraints(repoRoot);
   registry[key] = constraint;
-  const p = constraintsPath(repoRoot);
-  await mkdir(path.dirname(p), { recursive: true });
-  await writeFile(p, JSON.stringify(registry, null, 2) + '\n', 'utf8');
+  await saveConstraints(repoRoot, registry);
   return registry;
 }
 
+/** The build artifact an `affects` item names, when it clearly names one. */
+export type AffectsTarget = 'schematic' | 'board' | 'bom';
+
+/**
+ * Items that name a not-yet-built artifact are deferrable; items that name a
+ * specific refdes, net, or doc fact return null and open a revisit obligation
+ * immediately. Misclassification is cheap in both directions: an unmatched
+ * artifact item just costs one ceremonial resolve_affected call (the old
+ * behavior for everything), and a deferred item still re-opens later.
+ */
+export function classifyAffectsTarget(item: string): AffectsTarget | null {
+  if (/\b(bom|part[-\s]?selection|mpn)\b/i.test(item)) return 'bom';
+  if (/\b(schematic|pinout|pin[-\s]?assign\w*|strapping|netlist)\b/i.test(item)) return 'schematic';
+  if (
+    /\b(layout|stackup|rout(?:e|es|ing)?|vias?|pours?|keepouts?|zones?|copper|traces?|board|pcb|mounting|thermal|silkscreen|assembly|current[-\s]?carrying)\b/i.test(
+      item,
+    )
+  )
+    return 'board';
+  return null;
+}
+
+interface ArtifactConfig {
+  schematic: string | null;
+  board: string | null;
+  docs: string;
+}
+
+export function affectsTargetExists(target: AffectsTarget, repoRoot: string, config: ArtifactConfig): boolean {
+  switch (target) {
+    case 'schematic':
+      return !!config.schematic;
+    case 'board':
+      return !!config.board;
+    case 'bom':
+      return existsSync(path.join(repoRoot, config.docs, 'BOM.md'));
+  }
+}
+
+export interface ReopenedAffects {
+  key: string;
+  item: string;
+}
+
+/**
+ * Run-start hook: re-open the revisit obligations that were deferred while
+ * their target artifact did not exist. Each re-opened item is removed from the
+ * registry's `deferred` marker in the same pass, so it re-opens exactly once —
+ * from then on it lives in the run's ledger like any other obligation.
+ */
+export async function reopenDeferredAffects(
+  repoRoot: string,
+  config: ArtifactConfig,
+  openObligation: (key: string, item: string) => void,
+): Promise<ReopenedAffects[]> {
+  const registry = await loadConstraints(repoRoot);
+  const reopened: ReopenedAffects[] = [];
+  for (const [key, c] of Object.entries(registry)) {
+    if (!c.deferred?.length) continue;
+    const stillDeferred: string[] = [];
+    for (const item of c.deferred) {
+      const target = classifyAffectsTarget(item);
+      if (target && !affectsTargetExists(target, repoRoot, config)) {
+        stillDeferred.push(item);
+        continue;
+      }
+      openObligation(key, item);
+      reopened.push({ key, item });
+    }
+    if (stillDeferred.length) c.deferred = stillDeferred;
+    else delete c.deferred;
+  }
+  if (reopened.length) await saveConstraints(repoRoot, registry);
+  return reopened;
+}
+
 export interface ConstraintViolation {
   key: string;
   description: string;

package/src/memory/drift.ts

@@ -35,10 +35,42 @@ export function parseMarkdownTables(md: string): TableRow[] {
 const isHeader = (row: TableRow): boolean =>
   row.cells.some((c) => /^(refdes|pin)$/i.test(c));
 
+/**
+ * The zero-symbol carve-out in checkDrift is right for the create pipeline,
+ * but it would let `check` silently pass an established repo whose schematic
+ * was emptied by accident while BOM.md still lists parts. `check` calls this
+ * alongside checkDrift and reports the result as a warning, not a failure:
+ * an empty sheet with a populated BOM is either bootstrap (fine) or an
+ * accident (worth a human look), and only a human can tell which.
+ */
+export async function emptySchematicWarning(
+  repoRoot: string,
+  docsDir: string,
+  schematic: string,
+): Promise<string | null> {
+  const symbols = await listSymbols(path.join(repoRoot, schematic));
+  if (symbols.length) return null;
+  const bomPath = path.join(repoRoot, docsDir, 'BOM.md');
+  if (!existsSync(bomPath)) return null;
+  const refs = parseMarkdownTables(await readFile(bomPath, 'utf8'))
+    .filter((r) => !isHeader(r))
+    .map((r) => r.cells[0])
+    .filter(Boolean);
+  if (!refs.length) return null;
+  return `schematic has zero symbols but BOM.md lists ${refs.length} refdes; if this repo is not mid-bootstrap, the schematic may have been emptied accidentally`;
+}
+
 export async function checkDrift(repoRoot: string, docsDir: string, schematic: string): Promise<DriftMismatch[]> {
   const mismatches: DriftMismatch[] = [];
   const schPath = path.join(repoRoot, schematic);
   const symbols = await listSymbols(schPath);
+  // A schematic with zero symbols is the bootstrap state: during the create
+  // pipeline the docs legitimately lead the schematic (part-selection writes
+  // BOM.md before any symbol exists), so comparing against an empty sheet
+  // deadlocks every docs-touching stage — or worse, teaches the agent to strip
+  // refdes from BOM.md to appease the gate (#21). Same reasoning as the
+  // "no schematic configured" carve-out in the check_drift tool.
+  if (!symbols.length) return mismatches;
   const byRef = new Map<string, SchematicSymbol>(symbols.map((s) => [s.ref, s]));
 
   const bomPath = path.join(repoRoot, docsDir, 'BOM.md');

package/src/memory/scaffold.ts

@@ -113,7 +113,8 @@ Generated by \`copperhead init\`; regenerated on re-runs (do not hand-edit).
 
 - \`schematic\` / \`board\`: repo-relative paths to the KiCad files copperhead operates on (currently: ${config.schematic ?? 'none'} / ${config.board ?? 'none'})
 - \`docs\`: design docs directory (docs-as-memory), default \`docs/\`
-- \`model\`: default model (\`gpt-5\` or \`claude\`); overridden by \`--model\` and \`COPPERHEAD_MODEL\`
+- \`model\`: default provider/model (\`codex\`, \`gpt-5\`, or \`claude\`); overridden by \`--model\` and \`COPPERHEAD_MODEL\`
+- local Codex uses the saved \`codex login\`; set \`COPPERHEAD_CODEX_PATH\` only when the executable is not on \`PATH\`
 - \`maxTurns\`: agent loop turn budget per run (default 40)
 - \`maxRepairCycles\`: ERC/DRC repair attempts before rollback (default 5)
 - \`budgets\`: free-form hard constraints (e.g. \`"sleep_current_uA": 25\`); surfaced verbatim into every run's system prompt