copperhead 0.6.0 → 0.8.0

package/src/layout/claude-ui-layout.md

@@ -0,0 +1,72 @@
+# Claude Code UI layout (measured reference)
+
+Captured from the real `claude` CLI (v2.1.220) under a pty + VT102 emulator at
+100x30, with per-cell SGR attributes extracted, so every color below is
+measured, not eyeballed. This is the reference to diff
+[repl-ui-layout.md](repl-ui-layout.md) against when editing copperhead's
+chrome.
+
+## State 1: idle prompt
+
+```text
+ 2| ▐▛███▜▌   Claude Code v2.1.220                       <- logo[#d77757]  name[bold, default fg] version[#999999]
+ 3|▝▜█████▛▘  Fable 5 with high effort · Claude Max      <- logo[#d77757]  model+plan[#999999]
+ 4|  ▘▘ ▝▝    ~/Github/chouhan-industries/copperhead     <- logo[#d77757]  cwd[#999999]
+ 5|
+ 6|   Tackle your toughest work with Opus 5. ...          <- notice body[default fg]
+ 7|   +1 more · /status                                   <- [#999999]
+..|                                                       <- content region, output scrolls here
+25|                                     ● high · /effort  <- meta right-aligned, all [#999999]
+26|─────────────────────────────────────────────────────  <- rule[#888888], full width
+27|❯ Try "create a util logging.py that..."               <- ❯ + nbsp[default], placeholder[faint], caret = real cursor
+28|─────────────────────────────────────────────────────  <- rule[#888888], full width
+29|  ⚠ Transcript saving is off · ...                     <- warning line (only when present)
+30|  ⏸ manual mode on · ? for shortcuts                   <- status left[#999999]
+```
+
+## State 2: slash menu open (upward overlay, input row fixed at 27)
+
+```text
+22|  /pr-review     Review a copperhead pull request...   <- hovered: label+desc[#b1b9f9], no inverse video
+23|                 spec workflow. Use when the user...   <- description wraps to a second row
+24|  /review        Review a GitHub pull request; ...     <- unhovered: [#999999]
+26|─────────────────────────────────────────────────────
+27|❯ /                                                    <- typed filter[default fg]
+28|─────────────────────────────────────────────────────
+30|  ⏸ manual mode on                                     <- status shrinks while menu is open
+```
+
+## State 3: Ctrl+C pressed once
+
+```text
+30|  Press Ctrl-C again to exit                           <- [#999999], replaces the status line
+```
+
+## Measured color palette
+
+| Role                        | Value             | Notes                                   |
+| --------------------------- | ----------------- | --------------------------------------- |
+| Accent (logo)               | `#d77757`         | truecolor; the only saturated color     |
+| Title (`Claude Code`)       | bold, default fg  | not white-forced: follows the theme     |
+| Secondary text              | `#999999`         | truecolor gray, softer than SGR 90      |
+| Rules                       | `#888888`         | one step darker than secondary text     |
+| Menu hover                  | `#b1b9f9`         | periwinkle, hover is a color change     |
+| Placeholder                 | faint (SGR 2)     | not fg-colored, uses the faint attr     |
+| Caret                       | terminal cursor   | real cursor, not a synthetic inverse    |
+
+## Structural notes vs copperhead's current implementation
+
+1. Grays: adopted. copperhead's `dim`/`ruleDim` are truecolor
+   `#999999`/`#888888` (with an SGR 90 fallback when truecolor is off).
+2. Menu hover: adopted as a color change. Claude recolors the row with
+   periwinkle `#b1b9f9`; copperhead recolors with `copperLight` (#eec9a5)
+   instead of inverse video.
+3. Hovered menu descriptions: adopted. Both wrap to a second row.
+4. Caret: adopted. copperhead parks the real terminal cursor in the input
+   row instead of drawing a synthetic inverse block.
+5. The name `Claude Code` is bold in the terminal's default foreground, so it
+   adapts to light/dark themes, it is not hard-coded white.
+6. There is a non-breaking space after `❯` in the prompt.
+
+To adopt any of these in copperhead, edit the corresponding line in
+[repl-ui-layout.md](repl-ui-layout.md) and paste it back.

package/src/layout/repl-ui-layout.md

@@ -0,0 +1,139 @@
+# REPL UI layout spec
+
+Captured from a real run (pty + VT102 emulator, 100x30). This file is the
+editing surface for the interactive shell's chrome: change any line below,
+paste it back, and the implementation follows. Every visual token maps to one
+function in `src/agent/theme.ts`, so color changes are one-line edits.
+
+## State 1: idle prompt
+
+```text
+ 1|                                                                        <- blank
+ 2|   ▄▟▙▄       copperhead v0.7.0                                         <- mark[copper]  name[bold] version[dim]
+ 3| ███  ███     claude via flag · kicad-cli 9.0.4                         <- mark[copper]  meta[dim]
+ 4|   ▀▜▛▀       ~/Github/chouhan-industries/copperhead                    <- mark[copper]  cwd[dim]
+ 5|                                                                        <- blank
+ 6| ▎ New repository?                                                      <- bar[copper] title[copper]
+ 7| ▎  `copperhead init` scaffolds docs/ from an existing schematic        <- bar[copper] body[default]
+ 8| ▎  `copperhead demo` runs the USB-C breakout create pipeline           <- bar[copper] body[default]
+ 9| ▎ Docs: https://docs.copperhead.sh                                     <- bar[copper] body[copper]
+10|                                                                        <- content region: echoes + agent
+..|  ❯ rename net KEY_DAH to KEY_DASH                                      <-   output scroll here, oldest
+..|  ▸ run_erc  clean — 0 violations                                       <-   scrolls off the top
+26|                                                     ● claude · main*   <- meta right-aligned: dot[copper] text[dim]
+27|──────────────────────────────────────────────────────────────────────  <- rule[dim], full width
+28|❯ Try "add reverse-polarity protection on VIN"                          <- prompt[copper]+nbsp, caret = real cursor, placeholder[dim] typed[bright]
+29|──────────────────────────────────────────────────────────────────────  <- rule[dim], full width
+30|  / for commands · pgup history · ctrl+c twice to quit         In copperhead   <- left[dim]  right[dim]
+```
+
+## State 2: slash menu open (overlays upward, input row never moves)
+
+```text
+16|  ❯ /demo         what copperhead does + how to try it                  <- hovered: ❯[copper] label+desc[copperLight], desc wraps to a 2nd row
+17|    /examples     example change-request prompts                        <- label[default] desc[default]
+..|    ...up to 10 items...
+26|  ↓ 10 more                                                             <- overflow marker[dim]
+27|──────────────────────────────────────────────────────────────────────  <- rule[dim]
+28|❯ /                                                                     <- typed filter[bright]
+29|──────────────────────────────────────────────────────────────────────  <- rule[dim]
+30|  / for commands · pgup history · ctrl+c twice to quit         In copperhead
+```
+
+## State 3: agent turn running (observability row pinned in the dock)
+
+```text
+26|                                                     ● claude · main*   <- meta stays
+27|──────────────────────────────────────────────────────────────────────
+28|⠹ Reflowing...              turn 2/40 · 1.2k in / 300 out · 12s · ERC   <- word left[copper], stats right[dim] busy[warn]
+29|──────────────────────────────────────────────────────────────────────
+30|  ctrl+c interrupts the run · output above scrolls into history
+```
+
+The working word is a PCB term (Routing, Etching, Reflowing, Soldering,
+Drilling, Plating, Probing, Fluxing, Tinning, Laminating, Silkscreening,
+Panelizing), one per turn, with animated dots: Claude Code's working verbs,
+board-shop edition; on rotation the old word crossfades char by char
+through `_` slots, dots included. Durable output (tool lines, turn markers, the outcome)
+scrolls in the content region; the observability row never moves. Between
+submit and the first turn a passive `… working` row shows briefly.
+
+First Ctrl+C at the prompt: input clears, row 30 becomes `press ctrl+c again to exit` [warn].
+
+History: every content line is kept in a session buffer (cap 5000). PgUp at
+the prompt scrolls the content region back through it (arrow keys / mouse
+wheel line-scroll too at an empty prompt), PgDn scrolls forward,
+any other key snaps back to the live tail; row 30 shows
+`history ↑N · pgup/pgdn scroll · any key returns` while scrolled. The same
+lines are mirrored by default to `.copperhead/runs/repl-<timestamp>.log`
+(plain text: SGR stripped, `sk-` keys redacted per AC-4.1); the path is
+printed when the session ends. Injected loggers (tests/embeds) disable the
+file sink.
+
+Startup: the full screen loads instantly (banner, callout, input dock), then
+the mark pulses in place twice over rows 2-4 (dot, thin ring, thick
+ring, full via) while the prompt is already usable. First run in a repo (no
+`.copperhead/` yet) uses slow timing (110ms/frame) and shows the New
+repository callout; later runs pulse fast (45ms/frame) and hide it.
+
+## Color tokens (src/agent/theme.ts)
+
+| Token         | SGR                | Current value             | Used for                               |
+| ------------- | ------------------ | ------------------------- | -------------------------------------- |
+| `copper`      | `38;2;184;115;51`  | #b87333 (brand: #b87333)  | mark, prompt ❯, callout bar, meta dot  |
+| `copperLight` | `38;2;238;201;165` | #eec9a5 (accent-high)     | hovered menu row                       |
+| `bold`        | `1`                | bold, default fg          | `copperhead` name (theme-adaptive)     |
+| `bright`      | `97`               | white                     | typed input text                       |
+| `dim`         | `38;2;153;153;153` | #999999 (SGR 90 fallback) | hints, placeholder, version, paths     |
+| `ruleDim`     | `38;2;136;136;136` | #888888 (SGR 90 fallback) | input-area rules                       |
+| `ok`          | `32`               | green                     | success lines (`check: all green`)     |
+| `warn`        | `33`               | amber                     | ctrl+c hint, cautions                  |
+| `err`         | `31`               | red                       | failures                               |
+
+Note: `copper` is the exact brand #b87333 on truecolor terminals
+(COLORTERM=truecolor/24bit); terminals without truecolor fall back to
+256-color 173. See [claude-ui-layout.md](claude-ui-layout.md) for the measured
+Claude Code reference palette to diff against.
+
+## Region -> source map
+
+| Region                | Source                                          |
+| --------------------- | ----------------------------------------------- |
+| Banner + callout      | `banner()` in `src/commands/repl.ts`            |
+| Meta line, status bar | `ask()` options in `src/commands/repl.ts`       |
+| Input rows, menu      | `src/util/live-prompt.ts` (`renderDock`)        |
+| Rules, callout, bars  | `src/agent/box.ts`                              |
+| Screen ownership      | `src/util/dock.ts` (alt screen + DECSTBM fence) |
+
+To iterate: edit the annotated lines above (text, alignment, or `[token]`
+tags), paste the block back, and the code gets updated to match. Verify with
+`npm run demo:ui` (see below).
+
+## Demo recording (npm run demo:ui)
+
+`npm run demo:ui` from the repo root runs `scripts/ui-demo.ts` via tsx: the
+real REPL UI with a canned agent run, no build step, no API key, no repo
+mutations. Same script every take, so recordings are reproducible.
+
+Standard take:
+
+1. Let the banner settle and the via mark pulse
+2. Type `/`, hover a few commands with the arrow keys, Esc to dismiss
+3. Type `rename net KEY_DAH to KEY_DASH`, Enter, let the mock run play
+   (~17s, four sections: propose, edit, verify, remember, each closed by a
+   summary line; the pinned observability row animates and the working word
+   morphs at each section)
+4. `/check` for the mock green ERC/DRC/drift pass
+5. Ctrl+C twice to exit
+
+The demo uses the current directory as the repo. A directory that already has
+`.copperhead/` gets the fast mark pulse and no callout; for the full
+first-run intro (slow pulse + New repository callout), run from a fresh
+directory:
+
+```bash
+cd $(mktemp -d) && node <repo>/node_modules/.bin/tsx <repo>/scripts/ui-demo.ts
+```
+
+The mark itself can be regenerated from the website logo geometry at any
+size with `node scripts/gen-logo.mjs <rows>`.

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/cli-args.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure argument helpers for the CLI surface. They live here rather than in
+ * cli.ts because that module wires up commander and parses argv at import
+ * time, which makes it untestable in-process: importing it runs the program.
+ * Anything with a branch worth pinning belongs on this side of the line.
+ */
+
+import path from 'node:path';
+import type { BudgetExhaustedStats } from '../agent/loop.js';
+
+/** Resolve `--repo` against the working directory; absolute paths pass through. */
+export function repoOf(opts: { repo?: string }): string {
+  return path.resolve(opts.repo ?? process.cwd());
+}
+
+/** `--max-turns` accepts only a positive integer; "5oops" and "NaN" refuse to start. */
+export function parseMaxTurns(raw: string): number {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`--max-turns must be a positive integer, got "${raw}"`);
+  }
+  return n;
+}
+
+/**
+ * Turns offered when the budget runs out: ceil of the ORIGINAL budget (design
+ * D1), so repeat extensions offer the same increment instead of escalating
+ * with the already-extended turn count.
+ */
+export function budgetExtraTurns(stats: Pick<BudgetExhaustedStats, 'maxTurns'>): number {
+  return Math.ceil(stats.maxTurns / 2);
+}
+
+/** The attended "continue?" question, with the cost of the run so far spelled out. */
+export function budgetPromptText(stats: BudgetExhaustedStats): string {
+  const k = (n: number): string => `${(n / 1000).toFixed(1)}k`;
+  return (
+    `Turn budget exhausted (${stats.turnsUsed} turns, ${k(stats.tokensIn)} in / ${k(stats.tokensOut)} out, ` +
+    `${stats.filesTouched.length} file(s) touched, ${stats.openObligations} open obligation(s)). ` +
+    `Continue with ${budgetExtraTurns(stats)} more turns?`
+  );
+}