feat(library-selection): #205 Phase 6 acceptance gates + Phase 8 CLI/docs (#208)

Continues #205 on top of the foundation merged in PR #207. No-op for
runtime behaviour; adds gates that *prove* the foundation behaves as
specified, plus a diagnostic CLI and architecture docs.

## Phase 6 — acceptance gates (#[ignore]'d, CI-only)

- `crates/fbuild-build/tests/teensylc_acceptance.rs` — builds teensyLC
  Blink end-to-end and asserts AC#1:
  * `.bss` <= 3 KB
  * No `fnet_` / `snooze_` / `RadioHead` / `mbedtls` symbol substrings
    (#204 regression guard)
  * `setup` / `loop` symbols present
  * `compile_commands.json` TU count <= 250
  * No FNET / Snooze / RadioHead / mbedtls entries in compile DB
- `crates/fbuild-build/tests/stm32_acceptance.rs` — builds an
  stm32f103c8 sketch that `#include`s `<SPI.h>` and asserts AC#4:
  * `SPIClass` symbol present in ELF
  * compile_commands.json contains an SPI library entry
  * No manual allowlist needed (closes #202)

Both gates use `fbuild_test_support::{ElfProbe, CompileDb}` from PR #207
and are gated behind `#[ignore]` because they download real toolchains
and Teensyduino / STM32duino frameworks. CI runs them via
`cargo test -- --ignored`.

## Phase 8 — diagnostic CLI

- `fbuild lib-select <project> -e <env>` — drives the resolver in-process
  and prints the selected library set.
- `--explain` shows per-library trigger header + unresolved includes.
- `--json` emits machine-readable output (`{ selected, unresolved,
  included_files, seeds, framework }`).
- Mutually-exclusive flags (`conflicts_with`).
- New `crates/fbuild-cli/src/lib_select.rs` (~420 LoC) owns the diagnostic
  flow without depending on `fbuild-build` — uses
  `fbuild-packages::library` directly to keep the CLI a leaf binary.
- 3 new tests in `crates/fbuild-cli/tests/lib_select.rs` (help-output,
  missing-project exit code, flag-conflict).

## Phase 8 — architecture docs

- `docs/architecture/library-selection.md` — new subsystem doc
  covering scanner / walker / resolver, path-prefix attribution,
  two-pass convergence, future Phase 4 cache.
- `docs/CLAUDE.md` table updated.
- `docs/INDEX.md` FAQ entries added.
- `docs/architecture/README.md` lists the new doc.
- `tasks/lessons.md` appended with the LDF-semantics lesson.

## Verification

- `uv run soldr cargo check --workspace --all-targets` — green.
- `uv run soldr cargo clippy --workspace --all-targets -- -D warnings` —
  green (only pre-existing `clippy.toml` MSRV info note).
- `uv run soldr cargo fmt --all --check` — clean.
- `RUSTDOCFLAGS="-D warnings" uv run soldr cargo doc --workspace
  --no-deps` — green.
- `uv run soldr cargo test -p fbuild-cli` — 13 passed, 0 failed
  (3 new lib_select + existing).
- Phase 6 acceptance tests `#[ignore]`'d; CI runs them with
  `--ignored`.

## Out of scope (still tracked)

- Phase 4 — zccache K/V memoization (gated on zackees/zccache#130).
- Phase 7 — perf gates wired into `bench/fastled-examples`.
- Baseline numeric capture (`tasks/baseline-205.md` placeholder).

Refs: #202, #204, #205,
zackees/zccache#130

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: zackees

Cargo.lock

@@ -26,3 +26,4 @@ tempfile = { workspace = true }
 
 [dev-dependencies]
 filetime = { workspace = true }
+fbuild-test-support = { path = "../fbuild-test-support" }

crates/fbuild-build/Cargo.toml

@@ -0,0 +1,122 @@
+//! Acceptance gate for #205 AC#4 / closes #202: stm32f103c8 SPI auto-discovery.
+//!
+//! This integration test verifies that an stm32f103c8 Blink sketch which
+//! `#include`s `<SPI.h>` builds with no manual library allowlist, and that
+//! the bundled `Arduino_Core_STM32` SPI library is automatically discovered
+//! by fbuild's library-selection layer.
+//!
+//! Run with:
+//! `uv run soldr cargo test -p fbuild-build --test stm32_acceptance -- --ignored`
+//!
+//! Marked `#[ignore]` because it downloads the ARM GCC toolchain plus the
+//! STM32duino cores (cached after first run) and performs a full firmware
+//! build — too heavy for default `cargo test`.
+//!
+//! Acceptance criteria (#205 AC#4):
+//! 1. The build succeeds.
+//! 2. `compile_commands.json` references at least one source file under
+//!    the SPI library (substring `SPI`).
+//! 3. The ELF contains a symbol whose mangled name contains `SPIClass`.
+
+use std::path::{Path, PathBuf};
+
+use fbuild_build::{BuildOrchestrator, BuildParams};
+use fbuild_core::BuildProfile;
+use fbuild_test_support::{CompileDb, ElfProbe};
+
+#[test]
+#[ignore = "downloads STM32duino + builds firmware; CI-only"]
+fn stm32f103c8_blink_with_spi_auto_discovers_library_205_ac4() {
+    // Use a temporary project dir so we can write our own SPI-using sketch
+    // independent of whatever ships in the fixture.
+    let tmp = tempfile::TempDir::new().unwrap();
+    let project_dir = tmp.path();
+
+    std::fs::write(
+        project_dir.join("platformio.ini"),
+        "[env:stm32f103c8]\n\
+         platform = ststm32\n\
+         board = bluepill_f103c8\n\
+         framework = arduino\n",
+    )
+    .unwrap();
+
+    let src = project_dir.join("src");
+    std::fs::create_dir_all(&src).unwrap();
+    std::fs::write(
+        src.join("main.cpp"),
+        "#include <Arduino.h>\n\
+         #include <SPI.h>\n\
+         void setup() { SPI.begin(); }\n\
+         void loop() {}\n",
+    )
+    .unwrap();
+
+    let build_dir = project_dir.join(".fbuild/build");
+    let params = BuildParams {
+        project_dir: project_dir.to_path_buf(),
+        env_name: "stm32f103c8".to_string(),
+        clean: true,
+        profile: BuildProfile::Release,
+        build_dir: build_dir.clone(),
+        verbose: true,
+        jobs: None,
+        generate_compiledb: true,
+        compiledb_only: false,
+        log_sender: None,
+        symbol_analysis: false,
+        symbol_analysis_path: None,
+        no_timestamp: false,
+        src_dir: None,
+        pio_env: Default::default(),
+        extra_build_flags: Vec::new(),
+        watch_set_cache: None,
+    };
+
+    let orchestrator = fbuild_build::stm32::orchestrator::Stm32Orchestrator;
+    let result = orchestrator
+        .build(&params)
+        .expect("stm32f103c8 build with SPI must succeed");
+    assert!(result.success, "build did not report success");
+
+    let elf = result
+        .elf_path
+        .as_ref()
+        .expect("stm32 build must produce ELF");
+    let probe = ElfProbe::open(elf).expect("ELF parses");
+    assert!(
+        probe
+            .has_symbol_containing("SPIClass")
+            .expect("symbol query"),
+        "AC#4: SPIClass symbol must be present in ELF — closes #202"
+    );
+
+    let compdb = locate_compile_commands(&build_dir, "stm32f103c8")
+        .expect("compile_commands.json should land in build dir");
+    let db = CompileDb::from_path(&compdb).expect("parse compile_commands.json");
+    let spi_entries: Vec<_> = db.entries_matching("SPI").collect();
+    assert!(
+        !spi_entries.is_empty(),
+        "AC#4: compile_commands.json must reference an SPI library entry — \
+         closes #202; found {} entries with no SPI hit",
+        db.tu_count()
+    );
+}
+
+fn locate_compile_commands(build_dir: &Path, env: &str) -> Option<PathBuf> {
+    let candidates = [
+        build_dir.join(env).join("compile_commands.json"),
+        build_dir.join("compile_commands.json"),
+    ];
+    for c in candidates {
+        if c.exists() {
+            return Some(c);
+        }
+    }
+    for entry in walkdir::WalkDir::new(build_dir).into_iter().flatten() {
+        if entry.file_name() == "compile_commands.json" {
+            return Some(entry.into_path());
+        }
+    }
+    None
+}

crates/fbuild-build/tests/stm32_acceptance.rs

@@ -0,0 +1,131 @@
+//! Phase 6.a acceptance gate for issue #205 on the teensyLC Blink target.
+//!
+//! Runs the full TeensyOrchestrator build against the in-repo
+//! `tests/platform/teensylc` fixture and asserts:
+//!
+//! * `.bss` size <= 3 KB (#205 AC#1).
+//! * No `fnet_*`, `snooze_*`, `RadioHead`, or `mbedtls` symbols leaked into
+//!   the linked ELF (#205 AC#1, #204 regression guard).
+//! * The Arduino/Teensy `setup` and `loop` symbols are present (#205 A-11).
+//! * `compile_commands.json` has <= 250 translation units (was 451 pre-fix
+//!   per the #205 issue body).
+//! * `compile_commands.json` references no `FNET`, `Snooze`, `RadioHead`, or
+//!   `mbedtls` files (#204 root-cause guard).
+//!
+//! This test downloads Teensyduino + arm-gcc on the first run and is
+//! therefore CI-only — it is gated behind `#[ignore]` and runs via
+//! `uv run soldr cargo test -p fbuild-build --test teensylc_acceptance -- --ignored`.
+
+use std::path::PathBuf;
+
+use fbuild_build::{BuildOrchestrator, BuildParams};
+use fbuild_core::BuildProfile;
+use fbuild_test_support::{CompileDb, ElfProbe};
+
+#[test]
+#[ignore = "downloads Teensyduino + builds firmware; CI-only"]
+fn teensylc_blink_meets_205_acceptance_criteria() {
+    let project_dir = repo_fixture("teensylc");
+    let build_dir = tempfile::TempDir::new().unwrap();
+
+    let params = BuildParams {
+        project_dir: project_dir.clone(),
+        env_name: "teensyLC".to_string(),
+        clean: true,
+        profile: BuildProfile::Release,
+        build_dir: build_dir.path().to_path_buf(),
+        verbose: true,
+        jobs: None,
+        generate_compiledb: true,
+        compiledb_only: false,
+        log_sender: None,
+        symbol_analysis: false,
+        symbol_analysis_path: None,
+        no_timestamp: false,
+        src_dir: None,
+        pio_env: Default::default(),
+        extra_build_flags: Vec::new(),
+        watch_set_cache: None,
+    };
+
+    let result = fbuild_build::teensy::orchestrator::TeensyOrchestrator
+        .build(&params)
+        .expect("teensyLC build must succeed for acceptance gate");
+    assert!(result.success, "build did not report success");
+
+    // ── ELF probes (AC#1) ───────────────────────────────────────────────
+    let elf = result
+        .elf_path
+        .as_ref()
+        .expect("teensy build must produce ELF");
+    let probe = ElfProbe::open(elf).expect("ELF parses");
+    let bss = probe.section_size(".bss").expect("bss query");
+    assert!(bss <= 3 * 1024, "AC#1: .bss must be <= 3KB; got {bss}");
+
+    for forbidden in ["fnet_", "snooze_", "RadioHead", "mbedtls"] {
+        assert!(
+            !probe
+                .has_symbol_containing(forbidden)
+                .expect("symbol query"),
+            "AC#1: forbidden symbol substring '{forbidden}' present in ELF — \
+             #204 regression"
+        );
+    }
+    for required in ["setup", "loop"] {
+        assert!(
+            probe.has_symbol(required).expect("symbol query")
+                || probe.has_symbol_containing(required).expect("symbol query"),
+            "A-11: required symbol '{required}' missing from ELF"
+        );
+    }
+
+    // ── compile_commands.json probes (AC#1, A-20..A-22) ─────────────────
+    let compdb_path = locate_compile_commands(build_dir.path(), "teensyLC")
+        .expect("compile_commands.json should land in build dir");
+    let db = CompileDb::from_path(&compdb_path).expect("parse compile_commands.json");
+    assert!(
+        db.tu_count() <= 250,
+        "AC#1: TU count must be <= 250; got {} entries",
+        db.tu_count()
+    );
+    let forbidden_hits = db.forbidden_present(&["FNET", "Snooze", "RadioHead", "mbedtls"]);
+    assert!(
+        forbidden_hits.is_empty(),
+        "AC#1 / #204: compile_commands.json must not include any of \
+         FNET/Snooze/RadioHead/mbedtls; found: {:?}",
+        forbidden_hits
+    );
+}
+
+fn repo_fixture(name: &str) -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .unwrap()
+        .parent()
+        .unwrap()
+        .join("tests/platform")
+        .join(name)
+}
+
+fn locate_compile_commands(build_dir: &std::path::Path, env: &str) -> Option<PathBuf> {
+    // Per fbuild's layout the file lives at one of:
+    //   <build_dir>/<env>/compile_commands.json
+    //   <build_dir>/compile_commands.json
+    // Search both, prefer the per-env path.
+    let candidates = [
+        build_dir.join(env).join("compile_commands.json"),
+        build_dir.join("compile_commands.json"),
+    ];
+    for c in candidates {
+        if c.exists() {
+            return Some(c);
+        }
+    }
+    // Fallback: walk the build_dir for any compile_commands.json.
+    for entry in walkdir::WalkDir::new(build_dir).into_iter().flatten() {
+        if entry.file_name() == "compile_commands.json" {
+            return Some(entry.into_path());
+        }
+    }
+    None
+}

crates/fbuild-build/tests/teensylc_acceptance.rs

@@ -14,6 +14,7 @@ path = "src/main.rs"
 fbuild-core = { path = "../fbuild-core" }
 fbuild-config = { path = "../fbuild-config" }
 fbuild-deploy = { path = "../fbuild-deploy" }
+fbuild-library-select = { path = "../fbuild-library-select" }
 fbuild-packages = { path = "../fbuild-packages" }
 fbuild-paths = { path = "../fbuild-paths" }
 tokio = { workspace = true }
@@ -28,3 +29,4 @@ ctrlc = "3.5.2"
 blake3 = { workspace = true }
 sha2 = { workspace = true }
 tempfile = { workspace = true }
+walkdir = { workspace = true }