Step7 Integrate

---
name: step7-integrate
description: "Step 7 · Full firmware integration + human visual-inspection gate + fab files (closing)"
disable-model-invocation: true
---

# Step 7 · Full firmware integration & closing

## 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` (canonical header line; foreign file → stop and ask). Confirm step 6 is `done` and the open-issues table has no `open` or `fixed-pending-verify` entries (`deferred` entries pass this gate — they are settled at the definition-of-done below). Read `docs/dev-plan.md`, `docs/pinmap.md`, the module inventory and verification summary. Not satisfied → stop and report.
3. This step already `done` → re-run: ask the user's intent first. Already `in-progress` → a previous session aborted (normal for long integration work) or another session is live: ask, then resume from the on-disk state. Already `waiting` (release findings routed to their steps, or an integration handoff sent to step 6) → this re-entry is expected once they clear: resume where you left off — integration (§1–2) after a settled handoff, the §4 readback after release findings.
4. Set step 7 `in-progress`. Rebuild context from disk only.

## Execute

### 1. Full firmware
Flesh out the interfaces frozen in step 2 into complete business logic, feature by feature against the plan's feature list (e.g. control logic, UI, storage, communication, power management — whatever the product defines). For paths the platform-capability probe marked "not simulatable", use multi-source evidence (full host state-machine coverage + mocked API argument assertions + official documentation citations) and phrase the DoD conditionally.

### 2. Firmware-first debugging (the priority inverts here)
By this step the hardware has been verified module by module, so when a bug appears **the default attribution is firmware**. Solve it on the firmware side first — logic, driver usage, init order, timing/peripheral configuration — exhausting candidate fixes autonomously: try one, check it against the failing behavior, roll back and log the ones that didn't hold, and consult the user for none of it. Never touch the PCB in this loop:

```text
bug found:
    assume firmware; enumerate & try firmware-side fixes    # logic / config /
                                                            # init order / driver usage
    solved → record and move on                             # the overwhelmingly common case
    exhausted, AND the evidence shows the hardware design itself cannot do
    what the plan requires (or two verified modules conflict at system level):
        → register in the flow-state issues table (source = step 7,
          target step = step6, status = open, severity); set step 7 `waiting`
        → guide the user: new session, **step6-verify** (Claude Code: `/boardless-pcb:step6-verify`)
          (step 6 will carry the entry verbatim into its audit and settle it)
```

Two lines that must not blur:
- **Firmware-first ≠ masking.** Fixing firmware that misuses verified hardware is exactly this step's job; compensating a genuine hardware design defect in firmware to dodge a rollback remains forbidden — the hook still watches.
- **The PCB escape hatch stays open.** In theory this step is fully decoupled from PCB design; in practice a system-level hardware issue can still surface here. Rare is not never.

### 3. ⛔ Hard gate: human visual inspection
DRC and scripts guarantee rule correctness (clearance/connectivity/netlist); **visual soundness can only be judged by a human**. Hand the user an inspection checklist and ask them to check in the EDA and report back:
- Silkscreen: designators readable, not over pads/vias, consistent orientation, polarity/pin-1 marks present
- Routing: no obviously redundant detours, no suspicious acute angles, critical loop shapes as intended
- Details: mousebites/process edges, mounting holes, test-point accessibility
Fix silkscreen-class findings on the spot; copper-class findings go through the rollback path.

### 4. Fab files — export, then release (export ≠ release)
**Export** after inspection passes: Gerber, drill, BOM (for assembly), pick-and-place coordinates, assembly notes (DNP list, ★special-part flags, post-fab measurement list **with criteria**, deferred-issues list **with severities**).
**Release gate** — read the exported package back independently before calling it released:
- Gerber/drill opened in an independent viewer (not the EDA's own preview): layers aligned, apertures sane
- Solder-mask slivers, annular rings, copper-to-board-edge clearance checked against the fab's capability table
- Stackup/impedance table matches what the fab actually offers
- BOM ↔ MPN ↔ footprint consistency; CPL rotations and origin convention; assembly side and component-height constraints
- Polarity/pin-1 marks present where assembly needs them
Only a package that passes readback is "released".

**Release-finding routing** (a failed readback is a finding with an address, not a dead end):
- Pure export artifacts (origin convention, format, missing layer) → fix here, re-run readback
- BOM ↔ MPN ↔ footprint mismatches → issues entry, target `3`
- Assembly side / rotation / height / mechanical → issues entry, target `4`
- Copper, holes, mask, stackup/impedance vs `docs/fab-profile.md` → issues entry, target `5` (target `4` if placement is implicated)
Present the findings and their proposed routing to the user first — every issues-table entry passes through the user's hands — then register them (with severity and evidence), set step 7 `waiting`, and follow the earliest-step rule until they clear; re-enter here and re-run the readback. (Unlike §2's integration handoffs — target `step6`, attribution unknown — release findings carry their own attribution from the readback and go straight to their step.)

## Wrap up
**Definition-of-done check**: DRC clean ✓ netlist consistent ✓ every verification item at `sim-pass`/`evidence-pass`, with all `post-fab-required` items listed with criteria in the assembly notes ✓ **deferred entries (with severities) re-presented to the user for final acknowledgement, then listed in the assembly notes** ✓ all three human gates passed (structure sign-off / module table & verification plan review / visual inspection) ✓ fab package passed independent readback ✓ → mark step 7 `done` in flow-state.
One last thing (optional): if this run surfaced lessons worth keeping or frustrations with the flow, the user is welcome to feed them back to this plugin's repository in whatever form they prefer (issue/PR) — that is exactly how this flow came to exist.