Step 2 · Firmware skeleton / pin map freeze

Session & state check (before touching anything)

1. One step per session: if this session already did substantive work for another step, stop and ask for a fresh session.
2. Read docs/flow-state.md (recognize it by its canonical header line; a foreign file under this name → stop and ask). Missing → route the user to step1-onboard (Claude Code: /boardless-pcb:step1-onboard). Confirm step 1 is done; read docs/requirements.md + docs/dev-plan.md. Not satisfied → stop and report; never skip ahead.
3. This step already done with no issue targeting it → re-run: ask the user's intent before redoing anything. Already in-progress → a previous session aborted or another session is live: ask before proceeding. Marked rework → redo what the rework note in its row requires, then wrap up.
4. Issues-table entries with target step = 2 → fix mode (below).
5. Set step 2 in-progress. Rebuild context from disk only; rely on no conversation memory.

Execute

Adopt-and-audit path: if flow-state/requirements record an inherited pin map (inherited: <path>), do not re-derive it — ingest it into this flow's carriers (pin-map carrier + docs/pinmap.md), then audit at the depth its trust level prescribes: verified-rely-on → dual-source spot-check of the critical pins (boot/strapping, wake sources, bus sharing, reset defaults); reference-only → full dual-source verification of every pin. Inheritance changes the labor, never the bar: the checklist below, the gate, and the done criteria apply unchanged — an inherited pin map is a memory-grade prior, and priors only qualify as triggers for checks.

• Pin layer fully realized: gate polarities (active-low/high); if the design sleeps and wakes — your platform's wake semantics (level-triggered wake is not an edge event; e.g. on ESP32's EXT1 ANY_LOW mask, a pin currently low must never enter the mask — check the target MCU's equivalent rules); boot-mode/strapping-class pin constraints; bus sharing; every pin's reset default state with its safety implications.
• Input pins at a boundary where their driver's domain may power down get default pull resistors (a floating input invites shoot-through current).
• Business logic interface-only: control logic and modules as skeletons with frozen signatures; details iterate in step 7. Firmware at this step exists to produce pin constraints.
• Pin-level decision code must prove its pins are configured (idempotent reconfigure + guard assertions), with the rule captured in host unit tests.
• Dual-source verification for every pin: official datasheet page-by-page × EDA symbol library; the datasheet wins on conflict; log each check (pin, both sources, verdict) into the pinmap doc.

Deliverables: the firmware-side pin-map carrier — default board_pins.h; use whatever single artifact your firmware stack idiomatically uses (C header, devicetree overlay, BSP module) and record its actual path in this step's flow-state deliverables column — plus docs/pinmap.md, kept in sync (one assignment, two carriers — change one side, sync the other).

Fix mode (entries with target step = 2)

Fix only the listed issues; no opportunistic refactoring. Each fix: update both pin-map sides → append to docs/rework-log-N.md (symptom / root cause / fix; N = last row of the verification-rounds table + 1, i.e. the upcoming re-verification round) → set the issue fixed-pending-verify, citing the rework-log entry in the same edit (a bare status flip looks like tampering to the guard hook). Then assess cascading rework before routing the user: pin changes usually invalidate schematic, placement, and routing — set each invalidated step to rework with a one-line reason in its steps-table row. Route last: rework steps in order, then step6-verify, each in a fresh session.

Wrap up

⛔ Gate: present the complete pin-map table for user confirmation. Then mark step 2 done and tell the user: new session, run step3-schematic (Claude Code: /boardless-pcb:step3-schematic).