copperhead 0.9.0 → 0.11.0

package/src/commands/create.ts

@@ -3,20 +3,24 @@ import { existsSync } from 'node:fs';
 import { readFile, mkdir, writeFile, readdir } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { loadConfig, resolveCompatSettings } from '../config.js';
-import { bootstrapKicadProject } from '../kicad/bootstrap.js';
+import { bootstrapKicadProject, markCreateOrigin } from '../kicad/bootstrap.js';
 import { exportSvg, runErc } from '../kicad/cli.js';
 import { listSymbols } from '../kicad/sexp.js';
+import { checkLegibility } from '../kicad/legibility.js';
+import { draftSchematicToText, defaultIntentPath } from '../kicad/draft/draft.js';
 import { isDirty, commitAll, changedFiles } from '../util/git.js';
 import type { CompatSettings, CopperheadConfig } from '../config.js';
 import { checkDrift } from '../memory/drift.js';
 import { runAgentLoop, makeProvider, type BudgetExhaustedStats } from '../agent/loop.js';
-import { diagnoseStageFailure, transcriptExcerpt, withTimeout, type StageDiagnosis } from '../agent/recovery.js';
+import { diagnoseStageFailure, transcriptExcerpt, withTimeout, symbolAvailabilityFacts, type StageDiagnosis } from '../agent/recovery.js';
 import type { Provider } from '../agent/types.js';
 import type { RunMetaInput } from '../agent/runmeta.js';
 import { fmtDuration, fmtTokens, type ProgressRenderer } from '../agent/render.js';
 import { copper, dim, ok, stageLine, warn } from '../agent/theme.js';
 import { openspecInit } from '../openspec/cli.js';
 import { sweepStaleTempDirs, pruneHistoryDir } from '../util/tmp.js';
+import { bomSymbolDossier } from '../kicad/dossier.js';
+import { symbolSearchDirs } from '../kicad/symlib.js';
 import { assertDiskSpace, DEFAULT_MIN_FREE_BYTES } from '../util/preflight.js';
 import { runCheck } from './check.js';
 import { emitCreateJlcpcbBom } from './export.js';
@@ -55,6 +59,32 @@ async function docHasHeading(repoRoot: string, rel: string, word: string): Promi
   return re.test(await readFile(p, 'utf8'));
 }
 
+export async function writeBriefHash(
+  repoRoot: string,
+  docsDir: string,
+  briefMeta: { path: string; sha256: string },
+): Promise<void> {
+  const file = path.join(repoRoot, docsDir, 'BRIEF.sha256');
+
+  await mkdir(path.dirname(file), { recursive: true });
+
+  try {
+    await writeFile(
+      file,
+      `brief: ${briefMeta.path}
+sha256: ${briefMeta.sha256}
+`,
+      {
+        encoding: 'utf8',
+        flag: 'wx',
+      },
+    );
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code !== 'EEXIST') throw err;
+  }
+}
+
 /**
  * Returns true when a directory exists and contains at least one file
  * matching the optional glob-style extension list (case-insensitive).
@@ -86,16 +116,23 @@ export const STAGES: Stage[] = [
       const p = path.join(root, docs, 'SPEC.md');
       if (!existsSync(p)) return false;
       const text = await readFile(p, 'utf8');
-      const budgetsMatch = /^#{1,6}\s.*\bBudgets?\b/im.test(text);
-      if (!budgetsMatch) return false;
-      // Find the Budgets section and strip HTML comments (single or multi-line)
-      const afterBudgets = text.split(/^#{1,6}\s.*\bBudgets?\b/im)[1] ?? '';
-      const firstNewline = afterBudgets.indexOf('\n');
-      const afterHeadingLine = firstNewline >= 0 ? afterBudgets.slice(firstNewline + 1) : '';
-      const nextSection = afterHeadingLine.search(/^#{1,6}\s/m);
+      const heading = /^(#{1,6})\s.*\bBudgets?\b.*$/im.exec(text);
+      if (!heading) return false;
+      // The section runs to the next heading of the SAME OR SHALLOWER depth, not to
+      // the next heading of any depth (I17): a real spec routinely splits its budgets
+      // into subsections — "## 3. Electrical budgets" followed immediately by
+      // "### 3.1 Input and rails" — which leaves the parent's own body empty and read
+      // as an unfilled placeholder. Subheadings are part of the section, not its end.
+      const depth = heading[1]!.length;
+      const afterHeadingLine = text.slice(heading.index + heading[0].length);
+      const nextSection = afterHeadingLine.search(new RegExp(`^#{1,${depth}}\\s`, 'm'));
       const section = nextSection >= 0 ? afterHeadingLine.slice(0, nextSection) : afterHeadingLine;
+      // Strip HTML comments (single or multi-line); headings inside the section are
+      // structure, not content, so a section of nothing but subheadings still fails.
       const cleanSection = section.replace(/<!--[\s\S]*?-->/g, '');
-      const realLines = cleanSection.split('\n').filter((l) => l.trim().length > 0);
+      const realLines = cleanSection
+        .split('\n')
+        .filter((l) => l.trim().length > 0 && !/^#{1,6}\s/.test(l.trim()));
       return realLines.length > 0;
     },
     prompt: (brief) =>
@@ -148,7 +185,7 @@ export const STAGES: Stage[] = [
       });
     },
     prompt: () =>
-      'Stage 3: part selection. Write docs/BOM.md with the fixed table format (| Refdes | Value | Footprint | MPN | Rationale |). Every MPN you introduce is flagged UNVERIFIED with a datasheet-verifiable justification. Check leakage/quiescent current of every part against the power budget. Run check_drift before finishing.',
+      'Stage 3: part selection. Write docs/BOM.md with the fixed table format (| Refdes | Value | Footprint | MPN | Rationale |). The Value column holds the COMPONENT VALUE and nothing else — "4.7uF", "1M", "500mAh Li-Po", "STM32F103C8T6" — because stage 4 draws it on the sheet as that part\'s Value field, where a description ("1S Li-Po cell, 500 mAh, bare leads") collides with neighbouring symbols and fails the legibility gate. Put the prose in the Rationale column instead; that is the column for it, and nothing draws it. One row per refdes: a grouped row ("SW3-SW16", "C5-C8") is not a BOM row and the schematic stage cannot match it. Every MPN you introduce is flagged UNVERIFIED with a datasheet-verifiable justification. Check leakage/quiescent current of every part against the power budget. The design must be capturable with the KiCad symbol libraries installed on THIS machine: run search_symbols for every IC, module, connector and other active part before committing it to the BOM, and if a part has no installed symbol, pick one that has — stage 4 draws only from installed symbols, and a BOM row it cannot resolve makes the whole run unwinnable. Existence is not enough: confirm the chosen symbol with symbol_pins so the pin numbers you wire in stage 4 are real. Multi-unit symbols (gate packs, dual opamps) are fine — the engine places each unit separately under the one refdes, and net endpoints use plain package pin numbers. Run check_drift before finishing.',
   },
   {
     name: 'schematic',
@@ -174,10 +211,35 @@ export const STAGES: Stage[] = [
       // schematic, advancing the pipeline against unverified work. Returning
       // false here keeps the stage active so it re-runs, fixes ERC, and commits
       // through the normal finish gate.
-      return (await runErc(p)).ok;
+      if (!(await runErc(p)).ok) return false;
+      // Legibility is the one stage-4 output no electrical gate sees (AC-16.22):
+      // an ERC-clean sheet with text over symbol bodies passes everything above
+      // while being unreviewable. Error-severity findings keep the stage active;
+      // advisories never block.
+      const legibility = await checkLegibility(p, {
+        docsDir: path.join(root, config.docs),
+        ...(config.legibility ? { config: config.legibility } : {}),
+      });
+      if (legibility.counts.error !== 0) return false;
+      // Drafting mode: the schematic must match a re-draft of the current IR
+      // (AC-16.20) — an intent edited after the last draft_schematic call means
+      // the sheet on disk no longer reflects the design and the stage stays
+      // active until a re-draft.
+      const intentRel = defaultIntentPath(config.schematic);
+      if (existsSync(path.join(root, intentRel))) {
+        const dry = await draftSchematicToText({
+          repoRoot: root,
+          schematic: config.schematic,
+          intentPath: intentRel,
+          docsDir: config.docs,
+        });
+        if (!dry.ok) return false;
+        if (dry.text !== (await readFile(p, 'utf8'))) return false;
+      }
+      return true;
     },
     prompt: () =>
-      'Stage 4: schematic. An empty KiCad project has already been scaffolded and wired into .copperhead/config.json (an empty schematic and a blank board with a default outline). Populate the existing schematic with edit_file — write_file refuses KiCad files, so add lib_symbols, symbols, and connectivity by anchored edits into the file that already exists. Work ONE part at a time, not in large blocks: add a symbol (its lib_symbols entry if new, then its placement), run run_erc, fix any violation, then move to the next part — small incremental edits keep a geometry or grid slip local instead of forcing a full-block rewrite. When you add a lib_symbols entry, use the exact canonical KiCad lib_id (e.g. Device:R, Connector:USB_C_Receptacle_USB2.0_16P) and reproduce the real part\'s pins faithfully — never invent pin numbers, names, or electrical types. Once symbols are placed, run verify_symbols and reconcile every divergence it reports (a wrong lib_id or pin set passes ERC but is still wrong); if it flags a renamed symbol, adopt the real name it suggests. Build subsystem by subsystem from BOM.md and SUBSYSTEMS.md. Same net names and refdes everywhere. Two KiCad rules the pipeline has repeatedly tripped on: (1) a net label placed on a pin only NAMES the net — it is NOT an electrical connection unless a wire actually reaches the pin; ERC will report the pin unconnected until you draw the wire. (2) Place every symbol origin and every wire endpoint on the 1.27mm (50mil) grid; an off-grid pin silently fails to connect and costs turns to diagnose. Update PINOUT.md as you assign pins; check the strapping table first.',
+      'Stage 4: schematic. An empty KiCad project has already been scaffolded and wired into .copperhead/config.json. You author INTENT, never geometry: write the netlist-intent IR and call draft_schematic — the deterministic engine computes every coordinate, wire, label, power symbol, and group box, and the sheet it draws satisfies the drafting standard by construction (captioned group boxes per SUBSYSTEMS.md subsystem, left-to-right flow, rails up and grounds down, net labels between groups, filled title block). The IR (schematic.intent.json) is JSON: {"version": 1, "parts": [{"ref", "libId", "value", "footprint", "group"}], "nets": [{"name", "pins": ["REF.PIN", …], "kind"?}], "noConnect": ["REF.PIN", …], "hints"?: {"groupOrder"?, "paper"?, "date"?}}. Build it from BOM.md (same refdes and values — validation cross-checks and refuses mismatches) and SUBSYSTEMS.md (every non-power part names one subsystem heading as its group). Use exact canonical KiCad lib_ids (e.g. Device:R) and REAL pin numbers from the library: the pin dossier below (when present) already lists every BOM part\'s installed symbol and its real pins — work from it and from symbol_pins rather than reading .kicad_sym files, and validation lists a part\'s actual pins when you name one that does not exist. Name nets as a reader expects: a bus or interface shares a prefix (I2S_BCLK, I2S_DIN, I2S_LRCLK; SPI_…; BTN_…) so the drawing colours the family together, differential pairs end in +/- or P/N, and part values carry their unit (F, H, R). Declare every deliberately unused pin in noConnect; power rails are recognized from pin types automatically (override with "kind" only when the inference is wrong — the draft report lists every net\'s resolved class). Pass the full IR as intent_json to draft_schematic; the report embeds the legibility findings and the score for the fresh sheet. To repair ANY finding (ERC, legibility, validation), fix the IR and call draft_schematic again — edit_file is refused on the drafted sheet. Text-collision findings scale with TEXT LENGTH: a net label, part value, or SUBSYSTEMS heading that is shorter draws a smaller box, so renaming a colliding net (and updating PINOUT.md) or tightening a long heading is a real repair lever; paper size and declaration order are not (placement is grid-derived). When the draft is clean run run_erc and check_drift, update PINOUT.md to match the IR\'s pin assignments, and finish.',
   },
   {
     name: 'layout-draft',
@@ -259,6 +321,36 @@ async function emitJlcpcbAfterOutputs(stageName: string, opts: CreateOptions): P
   if (out) opts.log(stageLine('outputs', `emitted ${out} (JLCPCB assembly BOM)`, 'ok'));
 }
 
+/**
+ * The generic "contract not met" line names no defect. For the schematic stage
+ * the most common gap after the electrical gates go green is legibility, so
+ * name the finding counts by kind — the resume then starts on the actual work
+ * instead of rediscovering it.
+ */
+async function contractGapDetail(stageName: string, root: string, config: CopperheadConfig): Promise<string> {
+  const generic = 'the run finished but the stage completion contract is not met — no usable artifact was produced';
+  if (stageName !== 'schematic' || !config.schematic) return generic;
+  const p = path.join(root, config.schematic);
+  if (!existsSync(p)) return generic;
+  try {
+    const report = await checkLegibility(p, {
+      docsDir: path.join(root, config.docs),
+      ...(config.legibility ? { config: config.legibility } : {}),
+    });
+    if (report.counts.error > 0) {
+      const byKind = new Map<string, number>();
+      for (const f of report.findings.filter((f) => f.severity === 'error')) {
+        byKind.set(f.kind, (byKind.get(f.kind) ?? 0) + 1);
+      }
+      const counts = [...byKind].map(([k, n]) => `${k}: ${n}`).join(', ');
+      return `the schematic stage contract is not met: ${report.counts.error} error-severity legibility finding(s) remain (${counts}); resume to reconcile them`;
+    }
+  } catch {
+    // fall through: an unreadable schematic already fails earlier contract steps
+  }
+  return generic;
+}
+
 /** Stages whose output is a KiCad file worth rendering to an image (5.4). */
 const KICAD_STAGES = new Set(['schematic', 'layout-draft', 'outputs']);
 
@@ -278,7 +370,10 @@ function isManagedPath(f: string, config: CopperheadConfig): boolean {
     f.startsWith('openspec/') ||
     f.startsWith('outputs/') ||
     f.startsWith('firmware/') ||
+    f.startsWith('sym-lib-cache/') ||
     f === '.gitignore' ||
+    path.basename(f) === 'sym-lib-table' ||
+    path.basename(f) === 'schematic.intent.json' ||
     /\.(kicad_sch|kicad_pcb|kicad_pro|kicad_prl)$/.test(f)
   );
 }
@@ -387,15 +482,22 @@ async function diagnose(input: {
     const p = provider;
     const excerpt = await transcriptExcerpt(input.transcriptDir);
     return await withTimeout(
-      () =>
-        diagnoseStageFailure(p, {
+      async () => {
+        // Fact-check symbol-availability claims before the model judges them: a
+        // refusal narrating "library not installed" is adjudicated from the
+        // machine's actual libraries, not from the narration (I15/#197). Inside
+        // the watchdog, so a wedged filesystem scan cannot outlive timeoutMs.
+        const symbolFacts = await symbolAvailabilityFacts(`${input.failure}\n${excerpt}`).catch(() => '');
+        return diagnoseStageFailure(p, {
           stageName: input.stageName,
           stageGoal: input.stageGoal,
           failure: input.failure,
           excerpt,
           attempt: input.attempt,
           maxAttempts: input.maxAttempts,
-        }),
+          ...(symbolFacts ? { symbolFacts } : {}),
+        });
+      },
       input.timeoutMs,
       () => p.close?.(),
     );
@@ -643,7 +745,16 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
   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 resolvedBrief = path.resolve(opts.briefPath);
+  const relativeBrief = path.relative(opts.repoRoot, resolvedBrief);
+  const briefPath =
+    relativeBrief.startsWith('..') || path.isAbsolute(relativeBrief)
+      ? `external:${path.basename(resolvedBrief)}`
+      : relativeBrief;
+  const briefMeta = {
+    path: briefPath,
+    sha256: createHash('sha256').update(brief).digest('hex'),
+  };
   const config = await loadConfig(opts.repoRoot);
   // Fail fast on a nearly-full disk (4.1): a create run writes fab outputs and
   // KiCad local history and can otherwise fill the disk mid-stage, failing with
@@ -663,6 +774,11 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
   const pruned = await pruneHistoryDir(opts.repoRoot);
   if (pruned) opts.log(dim(`startup: pruned ${pruned} old .history/ entrie(s) to cap local-history growth`));
   await openspecInit(opts.repoRoot);
+  // Stamp the repo create-produced before any stage runs: the marker scopes the
+  // legibility finish gate and the fab release gate, and it must hold on
+  // resumed runs whose project predates the marker (bootstrapKicadProject
+  // no-ops on those, so it cannot be the only writer).
+  await markCreateOrigin(opts.repoRoot);
   const completed: string[] = [];
   const stageCosts: StageCost[] = [];
 
@@ -682,6 +798,15 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
       opts.log(stageLine(stage.name, 'already complete (resuming past it)', 'ok'));
       await commitResumedStage(opts, config, stage.name);
       completed.push(stage.name);
+      if (stage.name === 'spec-seed') {
+        try {
+          await writeBriefHash(opts.repoRoot, config.docs, briefMeta);
+        } catch (err) {
+          opts.log(
+            `warning: could not record brief provenance (${(err as Error).message})`,
+          );
+        }
+      }
       stageCosts.push({ name: stage.name, resumed: true, wallMs: 0, turns: 0, tokensIn: 0, tokensOut: 0, cacheHits: 0 });
       await emitJlcpcbAfterOutputs(stage.name, opts);
       continue;
@@ -721,13 +846,38 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
           `running${attempt > 1 ? ` (attempt ${attempt}/${config.maxStageRetries + 1})` : ''}`,
         ),
       );
+      // The BOM freezes before this stage, so every part's real pins are
+      // computable before the first turn — recomputed per attempt, since a
+      // rolled-back retry can run against a different BOM than its
+      // predecessor. Advisory only: any failure degrades to no block.
+      let dossierBlock = '';
+      if (stage.name === 'schematic') {
+        try {
+          const bomPath = path.join(opts.repoRoot, config.docs, 'BOM.md');
+          if (existsSync(bomPath)) {
+            // Bounded: a slow or wedged library scan must delay the stage by a
+            // fixed cost at most — on timeout the stage simply runs dossier-less.
+            const dossier = await withTimeout(
+              async () => bomSymbolDossier(await readFile(bomPath, 'utf8'), await symbolSearchDirs()),
+              60_000,
+            );
+            if (dossier) {
+              dossierBlock =
+                '\n\n## Installed-symbol pin dossier (machine-verified)\nEach BOM part resolved against the KiCad libraries installed on THIS machine: the top name-match lib_id and its REAL pins (number=name/electrical-type). Confirm the match fits the BOM part; alternatives are listed. Passives (R/C/L) draw from their canonical Device symbols and are omitted. Use these pins for REF.PIN endpoints instead of reading .kicad_sym files; for any part not listed, call symbol_pins.\n' +
+                dossier;
+            }
+          }
+        } catch {
+          // the dossier is context, never a gate — the stage runs without it
+        }
+      }
       const res = await runAgentLoop({
         repoRoot: opts.repoRoot,
         model: opts.model,
         request: `create pipeline stage: ${stage.name}`,
         stagePrompt: guidance
-          ? `${basePrompt}\n\n## Recovery guidance (a previous attempt did not complete this stage — do this differently)\n${guidance}`
-          : basePrompt,
+          ? `${basePrompt}${dossierBlock}\n\n## Recovery guidance (a previous attempt did not complete this stage — do this differently)\n${guidance}`
+          : `${basePrompt}${dossierBlock}`,
         interactive: opts.interactive ?? false,
         allowDirty: true, // stages build on each other's uncommitted state within the pipeline
         ...(stageTurns !== undefined ? { maxTurns: stageTurns } : {}),
@@ -755,11 +905,14 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
       // 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 the completion contract is the real gate.
+      // The run's own reason rides along: the diagnosis transcript excerpt holds
+      // only assistant text and tool results, so without it a hung call or a turn
+      // stopped at the hard cap reaches the diagnosis as a bare "provider-error".
       const failure =
         res.outcome !== 'success'
-          ? `the run ended as "${res.outcome}" (${res.exitPath})`
+          ? `the run ended as "${res.outcome}" (${res.exitPath})${res.summary ? `: ${res.summary}` : ''}`
           : !(await stage.isComplete(opts.repoRoot, config.docs))
-            ? 'the run finished but the stage completion contract is not met — no usable artifact was produced'
+            ? await contractGapDetail(stage.name, opts.repoRoot, config)
             : null;
       if (!failure) {
         stageDone = true;
@@ -818,6 +971,15 @@ export async function runCreate(opts: CreateOptions): Promise<{ ok: boolean; com
       return { ok: false, completed };
     }
     completed.push(stage.name);
+    if (stage.name === 'spec-seed') {
+      try {
+        await writeBriefHash(opts.repoRoot, config.docs, briefMeta);
+      } catch (err) {
+        opts.log(
+          `warning: could not record brief provenance (${(err as Error).message})`,
+        );
+      }
+    }
     await renderStageArtifacts(opts, stage.name, stageTranscriptDir);
     await emitJlcpcbAfterOutputs(stage.name, opts);
     logCumulative(opts, stageCosts);

package/src/commands/doctor.ts

@@ -1,5 +1,6 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { execa } from 'execa';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import {
@@ -12,8 +13,9 @@ import {
   type CompatSettings,
   type CopperheadConfig,
 } from '../config.js';
-import { kicadCliVersion } from '../kicad/cli.js';
+import { kicadCliVersion, MIN_KICAD_MAJOR } from '../kicad/cli.js';
 import { redactSecrets } from '../util/redact.js';
+import { isNotFoundError } from '../util/preflight.js';
 
 const execFileP = promisify(execFile);
 
@@ -44,6 +46,7 @@ export interface DoctorDeps {
   nodeVersion: string;
   kicadVersion: () => Promise<string>;
   gitVersion: () => Promise<string>;
+  openspecVersion: () => Promise<string>;
   env: NodeJS.ProcessEnv;
 }
 
@@ -54,6 +57,15 @@ function defaultDeps(): DoctorDeps {
     // `git --version` prints "git version 2.34.1"; keep only the number, the
     // report already labels the row "git".
     gitVersion: async () => (await execFileP('git', ['--version'])).stdout.trim().replace(/^git version\s+/, ''),
+    /**
+     * Probes `openspec --version` via execa, the same probe shape as the real
+     * call site (src/openspec/cli.ts): execa resolves Windows .cmd/.bat shims
+     * via cross-spawn without a shell, so a missing binary still yields ENOENT
+     * (what isNotFoundError expects) on every platform, instead of a
+     * shell-reported exit 127/"not found".
+     * @returns the trimmed stdout of `openspec --version` (e.g. "1.8.0").
+     */
+    openspecVersion: async () => (await execa('openspec', ['--version'])).stdout.trim(),
     env: process.env,
   };
 }
@@ -73,15 +85,46 @@ function nodeCheck(version: string): DoctorCheck {
   };
 }
 
+// MIN_KICAD_MAJOR (imported from kicad/cli.ts) enforces the minimum supported KiCad version for ERC/DRC.
+// Behaviour note: kicadCheck() returns status: 'fail' (exit non-zero) for any
+// kicad-cli version below this threshold, and for output that contains no
+// parseable N.N version token. This is intentional user-visible behaviour and
+// is NOT a no-op hint correction: users on KiCad 7 will see doctor fail where
+// it previously succeeded. The gate mirrors the README's stated requirement and
+// follows the same pattern as MIN_NODE_MAJOR above.
+
 async function kicadCheck(probe: () => Promise<string>): Promise<DoctorCheck> {
   try {
-    return { name: 'kicad-cli', status: 'ok', detail: await probe() };
+    const raw = await probe();
+    // Anchored match: require a version-shaped token at the start of a line so
+    // an incidental N.N elsewhere in stdout (e.g. "OpenGL 3.2 unsupported")
+    // does not shadow the real KiCad version. The `m` flag makes ^ match
+    // line-starts within a multi-line string.
+    const match = raw.match(/(?:^|\n)\s*(?:kicad-cli\s+)?v?(\d+)\.\d+/m);
+    const major = match ? Number(match[1]) : NaN;
+    if (!Number.isFinite(major)) {
+      return {
+        name: 'kicad-cli',
+        status: 'fail',
+        detail: raw || 'could not parse version',
+        hint: `copperhead needs KiCad >= ${MIN_KICAD_MAJOR}; install or configure a compatible kicad-cli.`,
+      };
+    }
+    if (major < MIN_KICAD_MAJOR) {
+      return {
+        name: 'kicad-cli',
+        status: 'fail',
+        detail: `${raw} (< ${MIN_KICAD_MAJOR})`,
+        hint: `copperhead needs KiCad >= ${MIN_KICAD_MAJOR}; upgrade KiCad (https://www.kicad.org/download/).`,
+      };
+    }
+    return { name: 'kicad-cli', status: 'ok', detail: raw };
   } catch {
     return {
       name: 'kicad-cli',
       status: 'fail',
       detail: 'not found on PATH',
-      hint: 'install KiCad >= 9 (bundles kicad-cli); ERC/DRC gates need it.',
+      hint: 'install KiCad >= 8 (bundles kicad-cli); ERC/DRC gates need it.',
     };
   }
 }
@@ -99,6 +142,41 @@ async function gitCheck(probe: () => Promise<string>): Promise<DoctorCheck> {
   }
 }
 
+/**
+ * Report whether the `openspec` CLI is reachable, needed for `validate_change`
+ * and the `create` pipeline. Fails soft like `kicadCheck`/`gitCheck`: a
+ * missing or erroring probe is returned as a `fail` check, never thrown.
+ * @param probe resolves the openspec version string, or rejects if the CLI
+ *   can't be run (e.g. not found on PATH).
+ * @returns an `ok` check with the version on success; a `fail` check with an
+ *   install hint when `probe` rejects with a not-found error (per
+ *   `isNotFoundError`), or a `fail` check with the flattened error message
+ *   otherwise.
+ */
+async function openspecCheck(probe: () => Promise<string>): Promise<DoctorCheck> {
+  try {
+    return { name: 'openspec', status: 'ok', detail: await probe() };
+  } catch (err) {
+    if (isNotFoundError(err)) {
+      return {
+        name: 'openspec',
+        status: 'fail',
+        detail: 'not found on PATH',
+        hint: 'npm i -g @fission-ai/openspec; validate_change and the create pipeline need it.',
+      };
+    }
+    // Collapse embedded newlines/whitespace from a raw shell/subprocess error:
+    // formatDoctor's column layout assumes a single-line detail, and wrapWords
+    // splits on plain spaces only.
+    const rawMessage = (err as Error).message || String(err);
+    return {
+      name: 'openspec',
+      status: 'fail',
+      detail: rawMessage.replace(/\s+/g, ' ').trim(),
+    };
+  }
+}
+
 /**
  * Map a resolved model to the credential its provider needs, mirroring
  * makeProvider's prefix routing (agent/loop.ts). Presence-only: it checks that a
@@ -131,9 +209,9 @@ export function checkCredential(
     const settings = compat ?? { apiKeyEnv: DEFAULT_API_KEY_ENV };
     // Display only: some endpoints embed a credential in the URL itself (a
     // query param, userinfo) — Gemini's compat endpoint does this with
-    // ?key=..., in a format redactSecrets' key-shape patterns don't cover.
-    // Drop the query and userinfo entirely rather than pattern-matching, so
-    // this holds regardless of what a given provider's key looks like.
+    // ?key=.... redactSecrets covers known key shapes, but a key embedded in
+    // a URL query isn't reliably one of them, so drop the query and userinfo
+    // entirely rather than pattern-matching, regardless of shape.
     // isLocalEndpoint() below still runs against the raw settings.baseURL,
     // never this.
     const where = (() => {
@@ -380,6 +458,7 @@ export async function runDoctor(opts: RunDoctorOptions): Promise<DoctorReport> {
     nodeCheck(deps.nodeVersion),
     await kicadCheck(deps.kicadVersion),
     await gitCheck(deps.gitVersion),
+    await openspecCheck(deps.openspecVersion),
     providerCheck(opts.model, config, deps.env),
   ];
   if (resolvedModel) {

package/src/commands/skill.ts

@@ -0,0 +1,127 @@
+import { loadConfig, resolveModel } from '../config.js';
+import { flatten, type ToolResult } from '../agent/envelope.js';
+import { makeProvider } from '../agent/loop.js';
+import { dispatchToolResult, registry, type RunContext } from '../agent/tools.js';
+import type { Provider } from '../agent/types.js';
+import { Transcript } from '../agent/transcript.js';
+import { ObligationsLedger } from '../agent/ledger.js';
+
+export class SkillCliError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SkillCliError';
+  }
+}
+
+export function catalogNameFromCli(name: string): string {
+  return name.replace(/-/g, '_');
+}
+
+export async function listSkills(repoRoot: string): Promise<{ name: string; available: boolean; description: string }[]> {
+  const ctx = await minimalCtx(repoRoot, false);
+  const listed = new Set(registry.list(ctx).map((e) => e.name));
+  return registry.skills().map((s) => ({
+    name: s.name,
+    available: listed.has(s.name),
+    description: s.schema.description,
+  }));
+}
+
+export async function runSkill(opts: {
+  repoRoot: string;
+  name: string;
+  args?: Record<string, unknown>;
+  provider: Provider;
+}): Promise<ToolResult> {
+  const catalogName = catalogNameFromCli(opts.name);
+  const entry = registry.get(catalogName);
+  if (!entry || entry.kind !== 'skill') throw new SkillCliError(`unknown skill "${opts.name}"`);
+  const ctx = await minimalCtx(opts.repoRoot);
+  if (!registry.list(ctx).some((e) => e.name === catalogName)) {
+    throw new SkillCliError(`skill "${opts.name}" is not available in this repo`);
+  }
+  return dispatchToolResult(ctx, entry.name, opts.args ?? {}, { provider: opts.provider });
+}
+
+export async function providerForSkillRun(repoRoot: string, modelFlag?: string): Promise<{ provider: Provider; model: string }> {
+  const config = await loadConfig(repoRoot);
+  try {
+    const { model } = resolveModel(modelFlag, config);
+    return { provider: await makeProvider(model), model };
+  } catch (err) {
+    const msg = (err as Error).message;
+    throw new SkillCliError(
+      msg.includes('no model') || msg.includes('API_KEY') || msg.includes('configured')
+        ? `${msg} — skill run needs OPENAI_API_KEY, ANTHROPIC_API_KEY, or --model for a saved-login provider (codex, claude-code, cursor).`
+        : msg,
+    );
+  }
+}
+
+export function formatSkillEnvelope(result: ToolResult, json: boolean): string {
+  if (json) return JSON.stringify(result, null, 2);
+  const body = flatten(result);
+  return result.ok ? body : `error: ${body}`;
+}
+
+/**
+ * One skill run plus the provider's lifecycle. A saved-login provider owns a
+ * `mkdtemp` working directory (and, on some backends, an in-flight subprocess);
+ * `runAgentLoop` closes it in a `finally` because leaving it behind orphans the
+ * process and fills the disk (I8). `skill run` has no agent loop to inherit that
+ * from, so the close lives here — around the throw path too, since an unknown or
+ * unavailable skill must not leak the provider it already built. Returns the text
+ * to print and the exit code, so the CLI's only job is `console.log` + `exit`.
+ */
+export async function runSkillCli(opts: {
+  repoRoot: string;
+  name: string;
+  args?: Record<string, unknown>;
+  provider: Provider;
+  json: boolean;
+  warn?: (line: string) => void;
+}): Promise<{ text: string; code: number }> {
+  try {
+    const result = await runSkill({
+      repoRoot: opts.repoRoot,
+      name: opts.name,
+      ...(opts.args ? { args: opts.args } : {}),
+      provider: opts.provider,
+    });
+    return { text: formatSkillEnvelope(result, opts.json), code: result.ok ? 0 : 1 };
+  } finally {
+    try {
+      await opts.provider.close?.();
+    } catch (err) {
+      (opts.warn ?? ((l: string) => console.error(l)))(
+        `warning: ${opts.provider.name} provider cleanup failed (${(err as Error).message})`,
+      );
+    }
+  }
+}
+
+async function minimalCtx(repoRoot: string, initializeTranscript = true): Promise<RunContext> {
+  const transcript = new Transcript(repoRoot);
+  if (initializeTranscript) await transcript.init();
+  return {
+    repoRoot,
+    config: await loadConfig(repoRoot),
+    transcript,
+    ledger: new ObligationsLedger(),
+    runId: 'skill',
+    interactive: false,
+    confirm: async () => true,
+    editsUnlocked: false,
+    changeId: null,
+    proposalValidated: false,
+    filesTouched: new Set(),
+    decisions: [],
+    lastErc: null,
+    lastDrc: null,
+    lastLegibility: null,
+    lastScore: null,
+    lastDrift: null,
+    repairCycles: 0,
+    finishRequest: null,
+  };
+}

package/src/commands/sync.ts

@@ -6,7 +6,7 @@ import { checkDrift } from '../memory/drift.js';
 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 { runAgentLoop, type RunResult } from '../agent/loop.js';
 import type { RunMetaInput } from '../agent/runmeta.js';
 import type { ProgressRenderer } from '../agent/render.js';
 
@@ -172,7 +172,7 @@ export async function syncResolve(
   model: string,
   log: (s: string) => void,
   extras?: { renderer?: ProgressRenderer; meta?: RunMetaInput },
-): Promise<{ ok: boolean }> {
+): Promise<{ ok: boolean; run: RunResult }> {
   const reportText = formatSyncReport(report);
   const res = await runAgentLoop({
     repoRoot,
@@ -183,5 +183,7 @@ export async function syncResolve(
     ...(extras?.renderer ? { renderer: extras.renderer } : {}),
     ...(extras?.meta ? { meta: extras.meta } : {}),
   });
-  return { ok: res.outcome === 'success' };
+  // The full RunResult travels with the verdict so a non-CLI caller (the MCP
+  // server) can report the transcript path and files touched the way `do` does.
+  return { ok: res.outcome === 'success', run: res };
 }