copperhead 0.6.0 → 0.7.0

package/src/kicad/symlib.ts

@@ -0,0 +1,248 @@
+/**
+ * Cross-check the schematic's `lib_symbols` against the KiCad symbol libraries
+ * installed on the machine (I9).
+ *
+ * The create pipeline currently has the model hand-author every `lib_symbols`
+ * entry — pins, names, electrical types, geometry — under a `lib_id` that
+ * *claims* to be a canonical KiCad part (`Device:R`, `Connector:USB_C_...`).
+ * ERC only checks the net graph as drawn, so an entry whose pins silently
+ * diverge from the real library part (wrong pin count, a missing shield/CC pin,
+ * swapped numbers) passes every gate while being wrong. This module reads the
+ * real `(symbol …)` out of the installed `.kicad_sym` and reports divergences so
+ * the model — or a reviewer — can reconcile them.
+ *
+ * It is deliberately a *checker*, not an auto-replacer: KiCad renames symbols
+ * across versions (e.g. `USB_C_Receptacle_USB2.0` became `…_14P`/`…_16P` in
+ * KiCad 10), so blindly splicing by lib_id would fail on exactly the parts that
+ * matter most. When the exact name is absent, we surface close candidates
+ * instead of guessing.
+ */
+
+import { readFile, readdir, access } from 'node:fs/promises';
+import path from 'node:path';
+import { parseSexp, children, child, isList, type SexpNode } from './sexp.js';
+
+const tag = (n: SexpNode): string | null => (isList(n) && typeof n[0] === 'string' ? n[0] : null);
+const atomAt = (node: SexpNode[] | undefined, idx: number): string | undefined => {
+  const v = node?.[idx];
+  return typeof v === 'string' ? v : undefined;
+};
+
+// KiCad has two spellings for an unnamed pin: the legacy `~` sentinel and, in
+// newer library format, an empty string. They are semantically identical, so
+// normalize before comparing or the check floods with phantom `~` vs "" diffs.
+const normPinName = (n: string): string => (n === '~' ? '' : n);
+
+export interface LibPin {
+  number: string;
+  name: string;
+  /** electrical type: passive | power_in | bidirectional | input | … */
+  type: string;
+}
+
+/**
+ * Candidate directories holding KiCad's stock `.kicad_sym` libraries, most
+ * specific first. Env overrides win (KiCad exports these), then the standard
+ * install locations for Linux/macOS/Windows. Only existing dirs are returned.
+ */
+export async function symbolSearchDirs(env = process.env): Promise<string[]> {
+  const fromEnv = [
+    env.KICAD_SYMBOL_DIR,
+    env.KICAD10_SYMBOL_DIR,
+    env.KICAD9_SYMBOL_DIR,
+    env.KICAD8_SYMBOL_DIR,
+  ].filter((v): v is string => !!v);
+  const defaults = [
+    '/usr/share/kicad/symbols',
+    '/usr/local/share/kicad/symbols',
+    '/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols',
+    'C:/Program Files/KiCad/share/kicad/symbols',
+  ];
+  const out: string[] = [];
+  for (const dir of [...fromEnv, ...defaults]) {
+    try {
+      await access(dir);
+      if (!out.includes(dir)) out.push(dir);
+    } catch {
+      // not present on this machine; skip
+    }
+  }
+  return out;
+}
+
+/** Path to `<lib>.kicad_sym` in the first search dir that has it, or null. */
+export async function findLibraryFile(lib: string, dirs: string[]): Promise<string | null> {
+  for (const dir of dirs) {
+    const p = path.join(dir, `${lib}.kicad_sym`);
+    try {
+      await access(p);
+      return p;
+    } catch {
+      // try next dir
+    }
+  }
+  return null;
+}
+
+/** Collect pins (number, name, electrical type) from a `(symbol …)` node,
+ * including its nested unit sub-symbols. Same walk `libPinDefs` uses, plus the
+ * electrical-type atom that pin-position parsing does not need. */
+export function pinsOfSymbolNode(sym: SexpNode[]): LibPin[] {
+  const pins: LibPin[] = [];
+  const walk = (n: SexpNode): void => {
+    if (!isList(n)) return;
+    if (tag(n) === 'pin') {
+      const num = atomAt(child(n, 'number'), 1);
+      if (num !== undefined) {
+        pins.push({
+          number: num,
+          name: atomAt(child(n, 'name'), 1) ?? '~',
+          type: typeof n[1] === 'string' ? n[1] : '?',
+        });
+      }
+    }
+    for (const c of n) walk(c);
+  };
+  walk(sym);
+  return pins;
+}
+
+/** The top-level `(symbol "name" …)` entries of a parsed `.kicad_sym` root. */
+function librarySymbols(root: SexpNode[]): Map<string, SexpNode[]> {
+  const map = new Map<string, SexpNode[]>();
+  for (const sym of children(root, 'symbol')) {
+    const name = atomAt(sym, 1);
+    if (name) map.set(name, sym);
+  }
+  return map;
+}
+
+/**
+ * Resolve a `lib_id` (e.g. `Device:R`) to the real library part's pins.
+ * `extends` derived symbols inherit their base's pins, so we follow one such
+ * link (loop-guarded). Returns the pins, or — when the exact symbol is absent —
+ * the closest-named candidates so a caller can suggest the real name.
+ */
+export async function resolveLibrarySymbol(
+  libId: string,
+  dirs: string[],
+): Promise<
+  | { status: 'ok'; pins: LibPin[] }
+  | { status: 'no-symbol'; candidates: string[] }
+  | { status: 'no-library' }
+> {
+  const [lib, name] = libId.includes(':') ? [libId.slice(0, libId.indexOf(':')), libId.slice(libId.indexOf(':') + 1)] : ['', libId];
+  const file = await findLibraryFile(lib, dirs);
+  if (!file) return { status: 'no-library' };
+  const root = parseSexp(await readFile(file, 'utf8'))[0];
+  if (root === undefined || !isList(root)) return { status: 'no-library' };
+  const symbols = librarySymbols(root);
+
+  let current = name;
+  const seen = new Set<string>();
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    const sym = symbols.get(current);
+    if (!sym) break;
+    const pins = pinsOfSymbolNode(sym);
+    if (pins.length) return { status: 'ok', pins };
+    // no pins of its own → follow an `extends` base if present
+    const base = atomAt(child(sym, 'extends'), 1);
+    if (!base) return { status: 'ok', pins }; // genuinely pinless (e.g. a graphic)
+    current = base;
+  }
+
+  // exact name not found: offer near matches (case-insensitive substring both ways)
+  const q = name.toLowerCase();
+  const candidates = [...symbols.keys()]
+    .filter((k) => {
+      const lk = k.toLowerCase();
+      return lk.includes(q) || q.includes(lk);
+    })
+    .slice(0, 8);
+  return { status: 'no-symbol', candidates };
+}
+
+export interface SymbolFinding {
+  libId: string;
+  kind: 'no-library' | 'no-symbol' | 'pin-count' | 'pin-mismatch';
+  detail: string;
+}
+
+/** A schematic lib_symbols entry: its lib_id and the pins as authored. */
+function schematicLibSymbols(root: SexpNode[]): { libId: string; pins: LibPin[] }[] {
+  const libs = child(root, 'lib_symbols');
+  if (!libs) return [];
+  return children(libs, 'symbol').map((sym) => ({
+    libId: atomAt(sym, 1) ?? '',
+    pins: pinsOfSymbolNode(sym),
+  }));
+}
+
+/**
+ * Compare every lib_symbols entry in a schematic against the installed library.
+ * Returns one finding per divergence; an empty array means every resolvable
+ * symbol matched. A part whose library is not installed is reported once (so
+ * the model knows the check could not run for it) but never treated as a
+ * mismatch — absence of the library is not evidence of wrong pins.
+ */
+export async function verifySchematicSymbols(
+  schPath: string,
+  env = process.env,
+): Promise<{ findings: SymbolFinding[]; checked: number; skipped: number }> {
+  const dirs = await symbolSearchDirs(env);
+  const root = parseSexp(await readFile(schPath, 'utf8'))[0];
+  const findings: SymbolFinding[] = [];
+  if (root === undefined || !isList(root)) return { findings, checked: 0, skipped: 0 };
+
+  let checked = 0;
+  let skipped = 0;
+  for (const entry of schematicLibSymbols(root)) {
+    if (!entry.libId) continue;
+    const resolved = await resolveLibrarySymbol(entry.libId, dirs);
+    if (resolved.status === 'no-library') {
+      skipped++;
+      findings.push({
+        libId: entry.libId,
+        kind: 'no-library',
+        detail: `library for "${entry.libId}" is not installed on this machine; cannot verify its pins`,
+      });
+      continue;
+    }
+    if (resolved.status === 'no-symbol') {
+      findings.push({
+        libId: entry.libId,
+        kind: 'no-symbol',
+        detail: resolved.candidates.length
+          ? `"${entry.libId}" does not exist in the installed library — closest real symbols: ${resolved.candidates.join(', ')}. Use one of these lib_ids (KiCad renames symbols across versions).`
+          : `"${entry.libId}" does not exist in the installed library and no close match was found; confirm the lib_id.`,
+      });
+      continue;
+    }
+    checked++;
+    const real = resolved.pins;
+    const authored = entry.pins;
+    const realByNum = new Map(real.map((p) => [p.number, p]));
+    const authByNum = new Map(authored.map((p) => [p.number, p]));
+    if (real.length !== authored.length) {
+      findings.push({
+        libId: entry.libId,
+        kind: 'pin-count',
+        detail: `pin count differs: schematic has ${authored.length} pin(s) [${[...authByNum.keys()].join(',')}], the real ${entry.libId} has ${real.length} [${[...realByNum.keys()].join(',')}]`,
+      });
+    }
+    // per-pin name/type divergence on shared pin numbers
+    for (const [num, rp] of realByNum) {
+      const ap = authByNum.get(num);
+      if (!ap) continue; // count mismatch already reported the gap
+      if (normPinName(ap.name) !== normPinName(rp.name) || ap.type !== rp.type) {
+        findings.push({
+          libId: entry.libId,
+          kind: 'pin-mismatch',
+          detail: `pin ${num}: schematic has (name "${ap.name}", ${ap.type}), real part has (name "${rp.name}", ${rp.type})`,
+        });
+      }
+    }
+  }
+  return { findings, checked, skipped };
+}

package/src/memory/bom-table.ts

@@ -34,7 +34,161 @@ export interface TableRow {
    * Refdes or Pin column, so one check covers both doc types. */
   export const isHeader = (row: TableRow): boolean =>
     row.cells.some((c) => /^(refdes|pin)$/i.test(c));
-  
+
+  /**
+   * Data rows of the CANONICAL table(s) only — those introduced by a Refdes/Pin
+   * header row (`isHeader`). BOM.md and PINOUT.md legitimately carry supporting
+   * tables (a quiescent-current roll-up, a net-meaning legend); their rows are
+   * NOT parts/pins and must never be compared against the schematic. The flat
+   * `parseMarkdownTables(md).filter(!isHeader)` does exactly that — it merges
+   * every table's rows — so a second table's first cell gets read as a refdes and
+   * flagged "not in schematic", which pushes the agent to degrade good docs into
+   * bullet lists just to appease the drift gate.
+   *
+   * This groups lines into tables (a run of pipe-rows, ended by any non-pipe
+   * line), keeps only the groups whose first row is a Refdes/Pin header, and
+   * returns those groups' data rows (header dropped). A table with no recognized
+   * header — including a bare data-only block — is ignored, preserving the
+   * fixed-column contract (design D9) while letting docs hold extra tables.
+   */
+  export function parseCanonicalRows(md: string): TableRow[] {
+    return parseCanonicalTables(md).flatMap((t) => t.rows);
+  }
+
+  /**
+   * Like parseCanonicalRows, but keeps each kept table's header row so a caller
+   * can resolve columns by *name* instead of a fixed position. PINOUT.md's
+   * column count is not fixed in practice: the scaffold writes
+   * `Refdes | Pin | Name | Net | Notes`, but a hand- or LLM-authored table may
+   * legitimately drop the optional Name/Notes columns and write
+   * `Refdes | Pin | Net`. A fixed positional net index then reads the wrong cell
+   * and reports every pin as net "NC" against a doc that is in fact correct —
+   * a false drift the agent cannot diagnose (the doc plainly shows the net), so
+   * it loops on finish forever. Resolving by header name fixes that.
+   */
+  export function parseCanonicalTables(md: string): Array<{ header: TableRow; rows: TableRow[] }> {
+    const groups: TableRow[][] = [];
+    let current: TableRow[] | null = null;
+    for (const line of md.split('\n')) {
+      const t = line.trim();
+      if (!t.startsWith('|')) {
+        current = null; // a blank or prose line terminates the current table
+        continue;
+      }
+      const cells = t
+        .split('|')
+        .slice(1, -1)
+        .map((c) => c.trim());
+      if (cells.every((c) => /^:?-+:?$/.test(c))) continue; // separator row: stays within the table
+      if (!current) {
+        current = [];
+        groups.push(current);
+      }
+      current.push({ cells });
+    }
+    const tables: Array<{ header: TableRow; rows: TableRow[] }> = [];
+    for (const g of groups) {
+      if (g.length && isHeader(g[0]!)) tables.push({ header: g[0]!, rows: g.slice(1) });
+    }
+    return tables;
+  }
+
+  /**
+   * PINOUT.md pin assignments, resolved by column *name* and tolerant of the
+   * optional Name/Notes columns (see parseCanonicalTables). Only the canonical
+   * table that carries both a Pin and a Net header is read; a supporting table
+   * (e.g. a `Net | Role` legend) is ignored. Net names are compared bare, so the
+   * common `` `VBUS` `` markdown-backtick styling is stripped — the schematic
+   * stores plain net names, and a backtick-only difference is not real drift.
+   */
+  export function parsePinoutRows(md: string): Array<{ ref: string; pin: string; net: string }> {
+    const out: Array<{ ref: string; pin: string; net: string }> = [];
+    const strip = (s: string | undefined): string => (s ?? '').replace(/`/g, '').trim();
+    for (const { header, rows } of parseCanonicalTables(md)) {
+      const col = (re: RegExp): number => header.cells.findIndex((c) => re.test(c));
+      const refI = col(/^refdes$/i);
+      const pinI = col(/^pin$/i);
+      const netI = col(/^net$/i);
+      if (pinI < 0 || netI < 0) continue; // not the pin-assignment table
+      for (const row of rows) {
+        out.push({
+          ref: refI >= 0 ? strip(row.cells[refI]) : '',
+          pin: strip(row.cells[pinI]),
+          net: strip(row.cells[netI]),
+        });
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Fold the semantically-identical encodings that the model and KiCad render
+   * differently, so a value that differs only in *encoding* is not flagged as
+   * drift (#I11). A design that reached ERC-clean once churned for turns on
+   * `Ihold≥3A` vs `Ihold>=3A` and `0.1"` vs `0.1in` — byte differences with zero
+   * electrical meaning. Folded here: ≥/>=, ≤/<=, Ω/ohm(s), µ/μ/u, smart quotes,
+   * and the inch mark (`"` / `″` / a trailing `in`/`inch` after a number). NFKC
+   * first collapses width/compatibility variants; the explicit rules cover the
+   * cases NFKC leaves alone (≥, smart quotes, the ohm/inch words).
+   */
+  export function foldEncodings(s: string | undefined): string {
+    if (!s) return '';
+    return s
+      .normalize('NFKC')
+      .replace(/≥/g, '>=')
+      .replace(/≤/g, '<=')
+      .replace(/[ΩΩ]/g, 'ohm') // ohm sign U+2126 / greek capital omega U+03A9
+      .replace(/\bohms\b/gi, 'ohm')
+      .replace(/[µμ]/g, 'u') // micro sign U+00B5 / greek small mu U+03BC
+      .replace(/[“”″]/g, '"') // smart double quotes and double-prime → "
+      .replace(/[‘’′]/g, "'") // smart single quotes and prime → '
+      .replace(/(?<=[\d.])\s*(?:inches|inch|in)\b/gi, '"') // 0.1in / 0.1 inch → 0.1"
+      .trim();
+  }
+
+  /**
+   * Value-cell equality key: `foldEncodings` plus case- and whitespace-folding.
+   * Used to compare BOM.md value/footprint cells against schematic symbol values
+   * so an encoding/case/spacing-only difference is not reported as drift.
+   */
+  export function normalizeValue(s: string | undefined): string {
+    return foldEncodings(s).replace(/\s+/g, '').toLowerCase();
+  }
+
+  /**
+   * Footprint equality key: like `normalizeValue` but WITHOUT case-folding (F6).
+   * A footprint is a KiCad library reference (`Resistor_SMD:R_0603_1608Metric`)
+   * whose casing is significant — `R_0603` and `r_0603` are not the same library
+   * id — so lowercasing it would hide a real footprint difference. Encoding and
+   * spacing are still folded (a stray space or unicode variant is not real drift).
+   */
+  export function normalizeFootprint(s: string | undefined): string {
+    return foldEncodings(s).replace(/\s+/g, '');
+  }
+
+  /**
+   * Which of the canonical pin-assignment columns PINOUT.md actually provides.
+   * `checkDrift` uses this to emit ONE explicit "no Net column" message when the
+   * doc omits the column entirely, instead of silently checking nothing (a
+   * correct doc then looks unverified) or — the old positional bug (#I12) —
+   * reading the wrong cell and reporting every pin as a false `NC` mismatch.
+   * `hasTable` is false when the doc has no Refdes/Pin-headed table at all.
+   */
+  export function pinoutColumnReport(md: string): { hasTable: boolean; pin: boolean; net: boolean; refdes: boolean } {
+    let hasTable = false;
+    let pin = false;
+    let net = false;
+    let refdes = false;
+    for (const { header } of parseCanonicalTables(md)) {
+      hasTable = true;
+      const has = (re: RegExp): boolean => header.cells.some((c) => re.test(c));
+      if (has(/^pin$/i)) pin = true;
+      if (has(/^net$/i)) net = true;
+      if (has(/^refdes$/i)) refdes = true;
+    }
+    return { hasTable, pin, net, refdes };
+  }
+
   /**
    * A typed BOM.md data row, per the fixed column contract that `init` writes
    * (Refdes | Value | Footprint | MPN | Rationale — see scaffold.ts's
@@ -51,28 +205,45 @@ export interface TableRow {
   }
   
   /**
-   * Parses BOM.md's data rows into typed rows. Rows without a refdes in
-   * column 1 are dropped rather than thrown on: a hand-edited doc with a
-   * ragged or partial table shouldn't crash `check` or `export bom`, it
-   * should just be skipped (drift/export callers report the gaps that
-   * matter through their own comparisons against the schematic).
+   * Parses BOM.md's data rows into typed rows. Columns are resolved by header
+   * *name* (Refdes/Value/Footprint/MPN), falling back to the canonical position
+   * when a header is absent — the same header-name discipline `parsePinoutRows`
+   * uses (#I12), so a doc that reorders or drops an optional column is still read
+   * correctly instead of silently shifting every cell. Rows without a refdes are
+   * dropped rather than thrown on: a hand-edited doc with a ragged or partial
+   * table shouldn't crash `check` or `export bom`, it should just be skipped
+   * (drift/export callers report the gaps that matter against the schematic).
    */
   export function parseBomTable(md: string): BomRow[] {
-    const rows = parseMarkdownTables(md).filter((r) => !isHeader(r));
     const out: BomRow[] = [];
-    for (const row of rows) {
-      const [refdes, value, footprint, mpn] = row.cells;
-      if (!refdes) continue;
-      const flags: string[] = [];
-      if (mpn === 'UNVERIFIED') flags.push('UNVERIFIED');
-      else if (!mpn) flags.push('MISSING_MPN');
-      out.push({
-        refdes,
-        value: value || undefined,
-        footprint: footprint || undefined,
-        mpn: mpn || undefined,
-        flags,
-      });
+    for (const { header, rows } of parseCanonicalTables(md)) {
+      // Resolve by header name; -1 means "not found", so fall back to the
+      // canonical index for that column (Refdes 0, Value 1, Footprint 2, MPN 3).
+      const col = (re: RegExp, fallback: number): number => {
+        const i = header.cells.findIndex((c) => re.test(c));
+        return i >= 0 ? i : fallback;
+      };
+      const refI = col(/^refdes$/i, 0);
+      const valI = col(/^value$/i, 1);
+      const fpI = col(/^footprint$/i, 2);
+      const mpnI = col(/^mpn$/i, 3);
+      for (const row of rows) {
+        const refdes = row.cells[refI];
+        if (!refdes) continue;
+        const value = row.cells[valI];
+        const footprint = row.cells[fpI];
+        const mpn = row.cells[mpnI];
+        const flags: string[] = [];
+        if (mpn === 'UNVERIFIED') flags.push('UNVERIFIED');
+        else if (!mpn) flags.push('MISSING_MPN');
+        out.push({
+          refdes,
+          value: value || undefined,
+          footprint: footprint || undefined,
+          mpn: mpn || undefined,
+          flags,
+        });
+      }
     }
     return out;
   }

package/src/memory/drift.ts

@@ -2,7 +2,14 @@ import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { listSymbols, pinNets, type SchematicSymbol } from '../kicad/sexp.js';
-import { parseMarkdownTables, isHeader } from './bom-table.js';
+import {
+  parseCanonicalRows,
+  parseBomTable,
+  parsePinoutRows,
+  pinoutColumnReport,
+  normalizeValue,
+  normalizeFootprint,
+} from './bom-table.js';
 
 /**
  * Doc-vs-schematic drift check (AC-2.3). BOM.md and PINOUT.md use fixed table
@@ -31,8 +38,7 @@ export async function emptySchematicWarning(
   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))
+  const refs = parseCanonicalRows(await readFile(bomPath, 'utf8'))
     .map((r) => r.cells[0])
     .filter(Boolean);
   if (!refs.length) return null;
@@ -54,10 +60,11 @@ export async function checkDrift(repoRoot: string, docsDir: string, schematic: s
 
   const bomPath = path.join(repoRoot, docsDir, 'BOM.md');
   if (existsSync(bomPath)) {
-    const rows = parseMarkdownTables(await readFile(bomPath, 'utf8')).filter((r) => !isHeader(r));
+    // Resolve BOM columns by header name via the shared parseBomTable (F5), so
+    // the drift reader and `export bom` never disagree on a reordered table.
+    const rows = parseBomTable(await readFile(bomPath, 'utf8'));
     const seen = new Set<string>();
-    for (const row of rows) {
-      const [ref, value, footprint] = row.cells;
+    for (const { refdes: ref, value, footprint } of rows) {
       if (!ref) continue;
       seen.add(ref);
       const sym = byRef.get(ref);
@@ -65,10 +72,18 @@ export async function checkDrift(repoRoot: string, docsDir: string, schematic: s
         mismatches.push({ doc: 'BOM.md', claim: `${ref} exists`, actual: `${ref} not in schematic` });
         continue;
       }
-      if (value !== undefined && value !== sym.value) {
+      // Compare on the semantic value, not the byte-exact string: `Ihold≥3A` and
+      // `Ihold>=3A` are the same value written two ways (#I11). Raw `!==` flagged
+      // them as drift and whack-a-moled the agent across finish attempts.
+      if (value !== undefined && normalizeValue(value) !== normalizeValue(sym.value)) {
         mismatches.push({ doc: 'BOM.md', claim: `${ref} value ${value}`, actual: `${ref} value ${sym.value}` });
       }
-      if (footprint !== undefined && footprint !== '' && footprint !== sym.footprint) {
+      // Footprint compare folds encoding/spacing but keeps case (F6): a footprint
+      // library id is case-sensitive, so lowercasing would hide a real mismatch.
+      if (
+        footprint !== undefined &&
+        normalizeFootprint(footprint) !== normalizeFootprint(sym.footprint)
+      ) {
         mismatches.push({
           doc: 'BOM.md',
           claim: `${ref} footprint ${footprint}`,
@@ -85,11 +100,27 @@ export async function checkDrift(repoRoot: string, docsDir: string, schematic: s
 
   const pinoutPath = path.join(repoRoot, docsDir, 'PINOUT.md');
   if (existsSync(pinoutPath)) {
+    const pinoutMd = await readFile(pinoutPath, 'utf8');
     const nets = await pinNets(schPath);
     const netOf = new Map(nets.map((p) => [`${p.ref}:${p.pinNumber}`, p.net]));
-    const rows = parseMarkdownTables(await readFile(pinoutPath, 'utf8')).filter((r) => !isHeader(r));
-    for (const row of rows) {
-      const [ref, pinNumber, , net] = row.cells;
+    // If the doc has a Refdes/Pin table but no Net column, say so once and
+    // explicitly, rather than silently checking nothing (a correct doc then
+    // reads as unverified) — the counterpart to the old positional bug that
+    // reported every pin as a false NC (#I12). This tells the model what to fix
+    // (add the column) instead of leaving it guessing why nets aren't verified.
+    const cols = pinoutColumnReport(pinoutMd);
+    if (cols.hasTable && !cols.net) {
+      mismatches.push({
+        doc: 'PINOUT.md',
+        claim: 'the pin table has a Net column (expected header: Refdes | Pin | Net)',
+        actual: 'no Net column in the pin table, so pin-to-net assignments cannot be checked; add a Net column',
+      });
+    }
+    // Resolve columns by header name, not position: the PINOUT table may be
+    // `Refdes | Pin | Net` or the scaffold's `Refdes | Pin | Name | Net | Notes`.
+    // A fixed net index read every pin as "NC" on the 3-column form (#I12).
+    const rows = parsePinoutRows(pinoutMd);
+    for (const { ref, pin: pinNumber, net } of rows) {
       if (!ref || !pinNumber) continue;
       const k = `${ref}:${pinNumber}`;
       if (!netOf.has(k)) {

package/src/util/git.ts

@@ -1,10 +1,44 @@
 import { execa } from 'execa';
-import { cp, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { PreflightError } from './preflight.js';
 
+/**
+ * Paths copperhead must keep out of `git add -A`. KiCad ≥9 writes a
+ * git-backed local-history directory (`.history/`, complete with its own nested
+ * `.git`) into the project the first time kicad-cli touches it. Left untracked,
+ * that nested repo has an unborn HEAD, so a plain `git add -A` in the parent
+ * aborts with `error: '.history/' does not have a commit checked out` (exit
+ * 128) — which fails the commit at the end of every KiCad-touching stage
+ * (schematic, layout, outputs). Ignoring it is both correct (local history is
+ * never a project artifact) and the fix for that abort. Kept as a list so other
+ * KiCad transients can join it if they surface.
+ */
+const GIT_ADD_EXCLUDES = ['.history/'];
+
+/**
+ * Ensure the repo's root .gitignore lists each entry, appending only the
+ * missing ones. Idempotent and best-effort: a failure here must never block a
+ * commit, so it swallows its own errors. Run before any `git add -A` so a
+ * git-backed KiCad `.history/` (or similar nested repo) is skipped instead of
+ * aborting the add.
+ */
+export async function ensureIgnored(repo: string, entries: string[]): Promise<void> {
+  try {
+    const p = path.join(repo, '.gitignore');
+    const text = existsSync(p) ? await readFile(p, 'utf8') : '';
+    const present = new Set(text.split('\n').map((l) => l.trim()));
+    const missing = entries.filter((e) => !present.has(e));
+    if (!missing.length) return;
+    const prefix = text.length && !text.endsWith('\n') ? '\n' : '';
+    await writeFile(p, text + prefix + missing.join('\n') + '\n', 'utf8');
+  } catch {
+    // best-effort: .gitignore maintenance must never be the thing that fails a run
+  }
+}
+
 export interface GitSnapshot {
   head: string;
   stash: string | null;
@@ -147,6 +181,7 @@ export async function restore(repo: string, snap: GitSnapshot): Promise<void> {
 export async function preserveFailedRun(repo: string, runId: string): Promise<string | null> {
   try {
     if (!(await isDirty(repo))) return null;
+    await ensureIgnored(repo, GIT_ADD_EXCLUDES);
     // Never leave the audit trail staged: a staged-but-not-in-HEAD path is
     // deleted by restore()'s `reset --hard`, which silently defeats its
     // `clean -e .copperhead/runs` protection (that flag only spares untracked
@@ -181,6 +216,7 @@ export async function uncommittedCount(repo: string): Promise<number> {
 }
 
 export async function commitAll(repo: string, message: string): Promise<string> {
+  await ensureIgnored(repo, GIT_ADD_EXCLUDES);
   await git(repo, ['add', '-A']);
   await git(repo, ['commit', '-m', message]);
   return git(repo, ['rev-parse', 'HEAD']);