Step2 Pinmap

---
name: step2-pinmap
description: "Step 2 · Firmware skeleton, freeze the pin map (pin layer complete; business logic interface-only)"
disable-model-invocation: true
---

# 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`)**.