[META] FastLED #3339 LPC bring-up lessons — fbuild structural follow-up across 4 axes

[zackees]

Goal

Roll up the structural lessons from the FastLED LPC845-BRK bring-up incident (FastLED/FastLED#3300 / #3325 / #3339) into a single point of triage for the fbuild side. The Python-side fixes already landed (FastLED#3339, merged). This meta tracks the fbuild-side counterparts identified during a four-axis audit of fbuild's issue tracker — each gap got its own focused issue; this list ties them together so the maintainer has one URL.

How this list was built

Four sub-agents fanned out in parallel against four independent axes of fbuild coverage. Each agent compared lessons from the FastLED incident against fbuild's open + closed issues. Concrete gaps with no existing tracker became individual issues; gaps already covered by an existing tracker were noted and not duplicated.

The four axes:

1. Reset + serial wire-protocol — DTR/RTS, reset method dispatch, boot-mode detection.
2. Deploy + flash path — pyocd/CMSIS-DAP integration, artifact verification, handoff timing.
3. Agent-facing tooling + hook policy — forbidden-tool guards, agent docs parity.
4. Bring-up + autoresearch parity — end-to-end orchestrator, schema validation, hardware CI.

Sub-issues

Axis 1 — Reset + serial wire-protocol (4 issues)

Parent: #684 (closed) — hard_reset_blocking DTR=low fix. The structural follow-ups:

• #687 — fbuild-serial: BoardFamily enum + polymorphic ResetMethod dispatch registry.
• #688 — fbuild-serial::boot_mode: generalize to per-family BootModeClassifier registry (ESP-only today).
• #689 — docs: USB CDC DTR/RTS control-line semantics matrix per board family.
• #686 — fbuild-serial: vendor a serial-probe CLI + shared BOARD_FINGERPRINTS table (companion to closed fbuild-serial: hard_reset_blocking leaves DTR=low — fatal for CDC-ACM bridges (LPC11U35, FTDI CDC). Mirror the FastLED #3300/#3339 lessons. #684, parallel to FastLED#3339).

Axis 2 — Deploy + flash path (4 issues)

• #690 — fbuild-deploy: pre-deploy artifact size validation against board flash region.
• #691 — fbuild: standardize flash→monitor handoff timing as per-family HandoffTiming on BoardFamily.
• #692 — fbuild-deploy: enumerate supported deploy protocols per board; fail fast on unsupported.
• #693 — fbuild-serial: USB-level bootloader re-enumeration detection (complement to fbuild-serial::boot_mode: generalize to per-family BootModeClassifier registry (ESP-only today) #688 serial-line classifier).

Axis 3 — Agent-facing tooling + hook policy (2 issues)

• #694 — ci/hooks: ban direct pyocd/esptool/dfu-util/picotool invocation (mirror FastLED check_forbidden_commands).
• #695 — agents/docs/: agent-facing documentation directory + top-level CLAUDE.md routing table (mirror FastLED).

Axis 4 — Bring-up + autoresearch parity (3 issues)

• #696 — ci: nightly hardware-attached bring-up CI runner (multi-family).
• #697 — fbuild-cli: promote bring-up orchestrator to first-class fbuild bringup <board> command.
• #698 — fbuild-rpc-validate: reusable host-side JSON-RPC schema fetch + validate component.

Dependency hints (for ordering work)

• #687 is a load-bearing prerequisite for #691 (HandoffTiming lives on BoardFamily) and partially for #693 (TouchBaud1200 consumes the bootloader watcher).
• #686 is the data foundation for fbuild-serial: BoardFamily enum + polymorphic ResetMethod dispatch registry #687, fbuild-deploy: enumerate supported deploy protocols per board; fail fast on unsupported #692, fbuild-serial: USB-level bootloader re-enumeration detection (complement to #688 serial-line classifier) #693, fbuild-rpc-validate: reusable host-side JSON-RPC schema fetch + validate component #698. The fingerprint table is the cheapest first land.
• #689 is the design doc that underpins fbuild-serial: BoardFamily enum + polymorphic ResetMethod dispatch registry #687 and fbuild: standardize flash→monitor handoff timing as per-family HandoffTiming on BoardFamily #691 — landing it first reduces design-review friction on the code issues.
• #695 (agents/docs/) blocks nothing technically but accelerates every other issue's review cycle.

Suggested rough order: #686 → #689 → #695 → #687 → #691 → #694 → rest.

Out of scope (deliberately not filed)

Three candidate gaps surfaced during the audit but were ruled out:

• Application-specific bring-up details — 3-way pass-criteria tuple, per-board echo sentinel value, watchdog feed pattern. These belong on the FastLED side.
• Cross-repo agent rule sync — governance-level meta-question, not actionable as a single fbuild ticket.
• Skill / slash-command registration — Claude Code plugin infrastructure concern, not fbuild's responsibility.

Refs

• FastLED/FastLED#3300 — the LPC845-BRK bring-up "silence" incident (root).
• FastLED/FastLED#3325 — bisection plan (false trail invalidated by #3339).
• FastLED/FastLED#3336 — agent doc/hook rule banning ad-hoc PowerShell SerialPort probes; resolved by FastLED#3339.
• FastLED/FastLED#3339 — the FastLED-side fix that merged (Python DTR/RTS + port detection + serial_probe.py helper + hook ban).
• FastLED/fbuild#586 — existing LPC845-BRK on-hand burn-down meta. This issue intersects but is broader (covers all board families).
• FastLED/fbuild#684 (closed) — the hard_reset_blocking DTR=low fix that opened the audit.

Filed during the audit fan-out on FastLED/FastLED#3339.

[zackees]

All 13 listed sub-issues are now merged and closed:

Axis	Issue	PR
1. Reset + serial	#684 (closed pre-meta)	#685
1. Reset + serial	#686 — board fingerprints + serial probe CLI	#700
1. Reset + serial	#687 — ResetMethod + dispatch_reset + manager wiring	#703
1. Reset + serial	#688 — BootModeClassifier + ArmHardFault matcher	#706
1. Reset + serial	#689 — usb-cdc-control-line-matrix.md	#701
2. Deploy + flash	#690 — pre-deploy artifact size validation	#707
2. Deploy + flash	#691 — HandoffTiming per-family	#704
2. Deploy + flash	#692 — deploy method validation + fail-fast	#708
2. Deploy + flash	#693 — USB bootloader re-enumeration watcher	#709
3. Agent tooling	#694 — forbidden_commands.py hook	#705
3. Agent tooling	#695 — agents/docs/ + CLAUDE.md routing	#702
4. Bring-up + autoresearch	#696 — nightly hardware-CI scaffold	#710
4. Bring-up + autoresearch	#697 — fbuild bringup orchestrator scaffold	#711
4. Bring-up + autoresearch	#698 — rpc_validate JSON-RPC schema validator	#714

Net structural delta on the fbuild side, mirroring the FastLED-side FastLED/FastLED#3339:

• New BoardFamily-keyed dispatch surfaces: idle_dtr_rts (fbuild-serial: hard_reset_blocking leaves DTR=low — fatal for CDC-ACM bridges (LPC11U35, FTDI CDC). Mirror the FastLED #3300/#3339 lessons. #684/fbuild-serial: vendor a serial-probe CLI + shared BOARD_FINGERPRINTS table (companion to closed #684, parallel to FastLED #3339) #686), reset_method + dispatch_reset (fbuild-serial: BoardFamily enum + polymorphic ResetMethod dispatch registry #687), handoff_timing (fbuild: standardize flash→monitor handoff timing as per-family HandoffTiming on BoardFamily #691), BootModeClassifier::Registry::for_family (fbuild-serial::boot_mode: generalize to per-family BootModeClassifier registry (ESP-only today) #688), bootloader-watcher BootloaderSignature::for_family (fbuild-serial: USB-level bootloader re-enumeration detection (complement to #688 serial-line classifier) #693).
• New host tooling: fbuild serial probe list|find|read (fbuild-serial: vendor a serial-probe CLI + shared BOARD_FINGERPRINTS table (companion to closed #684, parallel to FastLED #3339) #686), fbuild bringup <env> (fbuild-cli: promote bring-up orchestrator to first-class command #697), agents/docs/ (agents/docs/: agent-facing documentation directory + top-level CLAUDE.md routing table (mirror FastLED) #695).
• New guard rails: pre-deploy artifact-size validation (fbuild-deploy: pre-deploy artifact size validation against board flash region #690), pre-deploy method validation (fbuild-deploy: enumerate supported deploy protocols per board; fail fast on unsupported #692), forbidden_commands.py hook banning ad-hoc pyocd / esptool / dfu-util / picotool / probe-rs (ci/hooks: ban direct pyocd / esptool / dfu-util / picotool invocation (mirror FastLED check_forbidden_commands) #694).
• New data + docs: BOARD_FINGERPRINTS table (fbuild-serial: vendor a serial-probe CLI + shared BOARD_FINGERPRINTS table (companion to closed #684, parallel to FastLED #3339) #686), ENVIRONMENT_TO_VCOM (fbuild-serial: vendor a serial-probe CLI + shared BOARD_FINGERPRINTS table (companion to closed #684, parallel to FastLED #3339) #686), docs/usb-cdc-control-line-matrix.md (docs: USB CDC DTR/RTS control-line semantics matrix per board family #689) + handoff-timing table (fbuild: standardize flash→monitor handoff timing as per-family HandoffTiming on BoardFamily #691), agents/docs/hardware-ci-setup.md (ci: nightly hardware-attached bring-up CI runner (multi-family) #696).
• New scaffolds awaiting hardware: .github/workflows/hw-ci.yml (ci: nightly hardware-attached bring-up CI runner (multi-family) #696), tests/hw/ fixtures (ci: nightly hardware-attached bring-up CI runner (multi-family) #696).
• New host-side validators: fbuild_serial::rpc_validate::{RpcSchema, ValidationReport} (fbuild-rpc-validate: reusable host-side JSON-RPC schema fetch + validate component #698).

No additional issues surfaced during the audit beyond the 13 originally fanned out. Each follow-up not landed in this round is named in its parent issue's "Out of scope" section.

Closing the meta.