rsconstruct 0.9.42

Rust based fast build system
# Architecture Review Findings

Full-codebase architecture audit (2026-07-18). Distinct from `CODE_REVIEW_FINDINGS.md` (line-level bugs, all fixed): these are structural/design problems. Checkboxes track future remediation work.

Recurring failure pattern across the codebase: **knowledge duplicated across hand-synchronized places with nothing enforcing agreement**, plus **advertised contracts the code doesn't implement**. The line-level code is careful; the seams between subsystems are where the debt lives.

## High severity

- [x] 1. **Schema has no single source of truth — drift has already happened.** *(Done 2026-08-01, by enforcement rather than by the `FieldSpec` refactor: five schema-consistency tests in `src/config/tests.rs` iterate every plugin and assert known-fields ⊆ type table, no dead type arms, checksum ⊆ known, descriptions ⊆ known. They found more drift than the audit listed — 19 dead arms (incl. `markdownlint.local_repo`/`npm_stamp`, not just the 8 named) and ~100 fields with no type validation at all. All fixed: `command`/`output_dir`/`formats` moved to the generic arm, ~40 processor-specific entries added (each verified against its struct declaration), `FieldType` gained `Table`/`Array`. The tests immediately caught a wrong type I introduced (`tags.sorted_tags` as StringArray), which is the point. **The `FieldSpec` consolidation itself is still worth doing** — the "no dead arms" check is probabilistic because `expected_field_type` is a match, not data; turning it into data makes that check total. Left as follow-up.)* One config field's schema lives in 5–8 hand-synced places (struct field, serde default fn, `Default` impl, `known_fields()`, `field_descriptions()`, `checksum_fields()`, `expected_field_type` arm in `src/config/mod.rs:1205`, docs page). Adding a processor also touches central tables (`scan_defaults_for` ~92 arms, `processor_defaults_for` ~71 arms, `src/config/mod.rs:511-692`). Proven drift: dead `expected_field_type` arms for renamed fields (`marp_bin`, `mmdc_bin`, `drawio_bin`, `chromium_bin`, `libreoffice_bin`, `markdown_bin`, `checker`, `linter`); marp `args` default encoded twice with different values (`MarpConfig::default()` vs `processor_defaults_for("marp")`); marp `timeout_secs`/`max_attempts` missing from type validation. Worst consequence: a forgotten `checksum_fields` entry on an output-affecting field = **silently stale build outputs**. Fix direction (no macros): one static `FieldSpec { name, ty, description, in_checksum, required }` table per config, carried on the `ProcessorPlugin` inventory entry, from which known-fields/types/descriptions/defaults all derive; one test iterating `all_plugins()` asserting coverage. Invert the checksum default (in unless opted out with a reason) so mistakes cause spurious rebuilds instead of stale outputs.

- [x] 2. **Three advertised contracts are not real.** *(Done 2026-08-01: dead fail-fast chunk-size arms deleted — `batch_chunk_size` now only models the real behavior, and architecture.md's three batching passages rewritten to state it (batching on by default, whole group per chunk, `--batch-size -1` for per-product recovery). Phase system reduced to what exists: `Phase` enum and the 5 never-fired phases deleted, `run_phase` → `run_post_config_hooks`, `rsconstruct phases` replaced by `rsconstruct hooks`. Stale docs re-synced: interrupt section (tokio watch channel reality), `ProductDiscovery` → the real `Processor` trait, cache.md layout (descriptors/ + the four redb files), descriptor-key formula (+processor_version, +variant), `output_depends_on_input_name` restated as a known limitation, `src/registry.rs` comment fixed, auto-detect table replaced with a pointer to `processors list`.)*
  - Fail-fast batching is dead code: both `None` arms of the chunk-size logic are unreachable (`src/executor/execution.rs:381-386,766` vs `src/builder/build.rs:272`); default fail-fast sends the whole level in one chunk and `execute_checker_batch` smears one exit code over every product — architecture.md promises chunk-size-1 incremental recovery that doesn't exist.
  - Phase hooks (`src/phases.rs`): 5 of 6 phases never fire; `run_phase` is called exactly once (PostConfig, `src/config/mod.rs`); hooks receive only `&mut Config` so pipeline phases couldn't observe the graph anyway. The pipeline is enumerated 4 uncoordinated times (`phases::Phase`, `cli::BuildPhase`, `GraphSnapshot`, string-keyed `phase_timings`).
  - Docs describe removed/nonexistent systems: architecture.md's interrupt section (global flag + 50 ms poll — code uses a tokio watch channel), a four-method `ProductDiscovery` trait (doesn't exist), cache.md's "no separate database / descriptors live in objects/" (there is `descriptors/` + `db.redb`), `output_depends_on_input_name` (zero hits in src/), and `processors/mod.rs:26` references a `src/registry.rs` that doesn't exist.

- [x] 3. **Cache-key composition is decentralized, with correctness holes behind it.** *(Done 2026-08-01: new `src/cache_key.rs` owns composition. The opaque `Product.config_hash: Option<String>` — spliced by four contributors using three different separator conventions — is replaced by `CacheKey`, an ordered list of named `(Component, value)` pairs (`Config`/`Analyzer`/`ToolVersion`/`Variant`) folded into the digest by one function. The component kind is mixed into the digest, so a config value and a tool value that happen to be equal no longer collide, and `variant` — previously spliced into `descriptor_key` separately — is now a normal component. Payoff: `rsconstruct product show` prints the components individually, so any descriptor-key change is attributable to exactly one contributor. **Tool-version keying is now on by default** (`[build] hash_tool_versions`, default true): `processor_tool_hashes` no longer returns an empty map without a lock file, and identifies tools by a content hash of the resolved binary — no `--version` subprocess, mtime-cached, and strictly stronger than a version string since it also catches a rebuilt binary reporting an unchanged version. A lock file, when present, still refines the identity. Integration tests pin both directions (upgrade invalidates; `hash_tool_versions = false` doesn't); the upgrade test was verified to fail against the old behavior, reproducing the exact "Skipping (unchanged)" symptom. B1/B2/B7 had already closed the other three holes.)* Key material assembled in ≥5 uncoordinated places (`Product::descriptor_key` `src/graph.rs:98`, `output_config_hash` allowlist, `extend_config_hash`, `apply_tool_version_hashes` — which uses a different combination style — and per-processor `checksum_fields`). Concrete holes:
  - Creator `output_dirs`/`output_files` are excluded from the config hash with a comment claiming outputs are "part of the product's identity" — true only of the legacy key. **Changing a creator's output_dirs = permanent silent SKIP.**
  - `cache = false` (`StandardConfig.cache`) is documented, validated, described — and read by no code. A documented no-op.
  - Tool-version keying is opt-in: without `tools lock`, upgrading a tool leaves all cached PASSes valid.
  - Legacy `CacheEntry`/`CACHE_TABLE` is never written but still consulted by status (`builder/build.rs` stale/new split) — every non-current product reports "new".
  Fix direction: a single `CacheKey` builder owning every component; delete legacy types; hash installed tool versions by default.

- [x] 4. **Testing is architecturally unenforced.** CI workflows contain no `cargo test` at all. ~150 of ~436 integration tests silently self-disable when a tool is missing (82 `tool_available()` early-return sites + the `test_checker!` macro's skip guards) — a skip is indistinguishable from a pass, in a project whose creed is "never silently skip." Near-zero unit tests in core modules: all of `src/executor/`, all of `src/builder/`, 8 of 9 `src/object_store/` files, `src/checksum.rs`, `src/watcher.rs`; everything is exercised through 569 spawns of the real binary. Fix direction: CI job with the full tool matrix + a `RSCONSTRUCT_TEST_REQUIRE_TOOLS=1` mode turning skips into failures; unit-test the pure cores (executor policy/retry, checksum, object-store validity/restore, run_checker chunking).
  *Done 2026-08-01:* skips are gone unconditionally — `tool_available()` replaced by a panicking `require_tool()` (no env-var mode; tests never skip, period), which immediately surfaced a broken venv black/a2x, a pdfunite probe that had always skipped, and a hadolint rule violation. CI test job added (`.github/workflows/test.yml`, registry-driven tool install + `cargo test` on every push). The named pure cores now have unit tests: `IncrementalPolicy::classify` decision table, `compute_parallel_levels`/`has_failed_dependency`, batch chunk-size + batching-gate decisions (extracted to free fns), `run_checker` chunk packing (extracted to `checker_chunk_ranges`), `execute_checker_batch*` fan-out semantics, checksum core (injection-proofing, buffer boundaries, MISSING/order semantics, per-context caching), object-store validity/restore (tiered blob verification, corrupted-output re-restore, tree order-insensitive change detection, read-only descriptor overwrite). Still integration-only: the retry loop body, `src/builder/`, `src/watcher.rs` — those unit tests are blocked on the finding 6/7 extractions.

- [x] 5. **No output layer — the `--json` contract is unenforceable.** *(Done 2026-08-01: new `src/output.rs` is the sink — `info`/`detail`/`warn`/`error`/`diagnostic`, each consulting the quiet/json predicate in one place, with the stdout-vs-stderr decision made by the function you call rather than at each site (`info`/`detail` → stdout; `warn`/`error`/`diagnostic` → stderr, so they survive `--json` without corrupting it). The entire build path — all of `src/executor/` and `src/object_store/` — is migrated and now contains **zero** bare `println!`. The key part is that this is now **enforced**: a unit test scans those modules and fails with the offending file:line if a bare `println!` reappears, which is what makes it a contract rather than the habit that had already failed (12 guards across ~445 sites). Verified the test catches a deliberately introduced violation. End-to-end, every stdout line parses as JSON across `--json`, `--json -v`, `--json --color=always`, `--json -v --color=always`. **Not done:** migrating the ~400 `println!` sites in command handlers (`tools list`, `sloc`, `processors files`, …). Those already branch on `is_json_mode()` and print their own JSON document, which *is* the machine output in that mode — they are not the leak risk, and rewriting them would be churn with no contract behind it.)* 437 `println!/eprintln!` sites across 32 modules; JSON gating checked in only ~17 files, `quiet()` at 8 sites. Verbose/colored lines leak into `--json` stdout today (`src/executor/execution.rs:408,523,735`; unconditional `println!` in `flush_words`), and the test harness tolerates it (`BuildResult::parse` discards non-JSON lines). `runtime_flags` itself is fine (write-once OnceLock); the missing piece is a single emit-sink. Fix direction: one `output` module (`emit_human`/`emit_event` consulting quiet/json/color), migrate call sites, and a test asserting every stdout line under `--json -v` parses as JSON.

## Medium severity

- [ ] 6. **God modules and inverted layering.**
  - `src/processors/mod.rs` (1,897 lines) = subprocess infra + tool-install engine + `ToolInfo` table + build stats + the actual processor contract; graph/analyzers/executor import "processors" for non-processor reasons. Extract `exec`, `tools`, `stats` modules.
  - `src/graph.rs` (1,330 lines) mixes the core data model with six renderers and imports `crate::cli` types (`DisplayOptions` etc.) and spawns Graphviz; `builder/tools.rs` duplicates a parallel renderer set. Move renderers out; move display types to a neutral module.
  - Module cycle: `processors → config → registries → processors` — config is not a leaf layer.
  - `src/main.rs` (~958 lines): ~620-line `run()` with inline command bodies (Cache handling, init_project scaffolding, formatting per match arm).
  - Tool installation split across two layers (`processors/mod.rs` engine + `builder/tools.rs` orchestration, whose `run_tools_command` is ~620 lines, with a duplicated `tool_runtime` helper).
  - Visibility is convention-only (~80 `pub(crate)/pub(super)` in 35k lines); none of the layer boundaries are compiler-enforced.

- [ ] 7. **`Builder` is a god object; the pipeline is not a first-class thing.** One struct, impl blocks in 10 files, ~35 public entry points; `Builder::build` (~240 lines) mixes CLI semantics (alias expansion), config mutation, tool preflight, orchestration, presentation, and exit-code mapping. Nothing between "whole build" and "one product" is testable/reusable; a daemon/LSP mode (anticipated by `BuildContext`'s docs) would have to re-enter through the CLI-shaped surface. Fix direction: extract a `BuildPipeline` type (discover→analyze→resolve→classify→execute) with a reporter interface; `Builder` becomes the thin command dispatcher.

- [ ] 8. **Processor trait + capability model accretion.** *(Partly done 2026-08-01 — the two items below are closed; the SimpleChecker/SimpleGenerator generics rewrite and the tags/pdfunite discovery-contract violation remain.)*
  - [x] **The panicking `discover()` default and the duplicate accessors are gone.** `standard_config() -> Option<&StandardConfig>` is deleted: all 27 implementations returned the same `&self.config.standard` that the required `scan_config()` already returns, and the `Option` is what forced the `discover` default to `.expect()` — a required method wearing a default's clothes that panicked for any processor implementing one accessor but not the other. `discover()` now reads `scan_config()` and is a real default. `config_json()`'s default follows the same accessor.
  - [x] **`is_native` double-declaration is now pinned by a test.** A `SimpleGenerator` declares it in `SimpleGeneratorParams` (where it decides whether `config.command` is a required tool) and again in the plugin registration (where it drives `processors list`), with nothing linking them. `simple_generator_is_native_declarations_agree` compares the two for all 12 SimpleGenerators; verified it fails when either is flipped alone. (A broader "native ⇒ no required tools" invariant was tried first and rejected: it has real exceptions — tera renders in-process but its template functions shell out to `git`, and clippy is non-native yet runs `cargo` rather than its configured command.)
  - 15 methods, 2 required; ~~default `discover()` panics at runtime (`.expect(...)`) — a required method disguised as a default (38 impls override it); `scan_config()`/`standard_config()` are duplicate accessors~~; `discover_for_clean`/`tool_version_commands`/`config_has_fix` each have exactly one overrider.
  - Capability drift is live: `fix list` filters on static `can_fix` alone while `fix` also honors `config_has_fix` — a configured `script.fix_command` is fixable but invisible in the list (`builder/fix.rs:117` vs `:21-22`); `black` declares `can_fix: true` with no fix params (works by accident; `supports_fix_batch()` wrongly false, silently disabling batch fixing); `is_native` declared twice per SimpleGenerator.
  - `SimpleChecker`/`SimpleGenerator` are hardwired to `StandardConfig`: one extra config field forces a ~100-line hand-rolled processor (pandoc, aspell). Fix: make them generic over `C: Serialize + KnownFields + AsRef<StandardConfig>` — plain generics, no macros.
  - Discovery contract inconsistently honored: tags and pdfunite/ipdfunite walk the filesystem directly (evading ignore rules and virtual files, re-running IO every fixed-point pass) despite architecture.md's "processors never walk the filesystem".

- [ ] 9. **Executor scheduling wastes parallelism structurally.** Level-barrier model: the longest product in a level stalls the entire next level even for products whose real dependencies finished; one thread per batch group; static contiguous chunk partitioning with no work stealing; a thread blocked on a `max_jobs` permit can't take other work. The adjacency lists/failure propagation/semaphores needed for a ready-queue scheduler already exist. This is the one *expensive* fix — gate it on a `--trace` profile of a real project. Related: "needs rebuild" is computed three times (classify, per-level, post-execution) with intentional divergence held together by comments; reify estimate-vs-authoritative checksums as distinct types.

- [ ] 10. **Graph identity is maintained by convention.** *(Partly done 2026-08-01: the canonical rebuild path and the transitive closure are in; the checker-identity scheme and `retain_products`' stale indexes remain.)* ~~`Product.id == index` across three parallel Vecs, upheld manually~~ — now assigned inside `register_product` from the vector length, so the invariant holds by construction; `retain_products` deliberately leaves stale indexes (doc-comment guard only); ~~`filter_by_targets` rebuilds the world, duplicating `add_product`'s registration logic (two sites that must evolve in lockstep)~~ — both now call `register_product`, the single place that knows what "adding a product to the graph" means (a test asserts a filtered graph is indistinguishable from a directly-built one: every lookup index, the id invariant, and per-product state like `output_dirs`); ~~and takes **no transitive closure** — a `-t` build can keep a consumer while dropping its producer~~ *(fixed as B4)*. Checker identity `(processor, primary_input, variant)` is a second, weaker scheme: same-primary-input checkers collide by design, and a non-superset re-declaration is silently ignored where the generator path hard-errors. Fix direction: ~~one canonical rebuild path~~; explicit product identity keys; ~~close over upstream producers in target filtering~~.

- [ ] 11. **Config pipeline fragility beyond the schema tables.** *(Partly done 2026-08-01 — the two sub-items below are closed; the toml_edit substitution rewrite, the `--iset`/`--pset` path (already closed by B3), the provenance span invariant, and the 5× re-parse remain.)*
  - [x] **`extract_var_names` no longer splits on `=`.** It parses the TOML and reads the `[vars]` table's keys. The line scanner split each line on the first `=`, so a multi-line array item like `"a=b"` recorded a bogus variable named `"a` — which made the undefined-variable check *too permissive*, since a genuinely undefined `${a}` would then validate. (The scanner's stated reason for being textual — "avoid parse errors on variable references" — didn't hold: an unsubstituted `${var}` is ordinary string content to a TOML parser.) Tests pin both the name extraction and the end-to-end consequence. B9 already closed the partial-reference half of this bullet.
  - [x] **`is_multi_instance` hard-errors on ambiguity.** `classify_section` returns a three-way `SectionShape` — `SingleInstance` / `MultiInstance` / `Ambiguous { colliding }` — instead of a bool that had to resolve every case. A section whose sub-table names collide with known config field names is now rejected at validation time, naming the exact keys and how to fix them, rather than being silently reinterpreted as single-instance. That silent path is what made adding a config field in a future release able to retroactively change how an existing user's config parsed. Unit tests cover all three shapes plus scan-field collisions; verified end-to-end.
  - Textual substitution can't see partial references: `src_dirs = ["${base}/src"]` matches neither substitution nor the undefined-var scan — flows through silently as a literal, contradicting the documented "undefined references produce an error". No escape mechanism for literal `${...}`. ~~`extract_var_names` naively splits on `=` (multi-line arrays with `a=b` items record junk names).~~ Fix: substitute on the parsed value tree (toml_edit), which also eliminates the provenance line-number coupling.
  - ~~`is_multi_instance` heuristic: instance names colliding with any known field silently reinterpret the section; adding a field in a future release can retroactively change how an existing user's config parses~~; Lua plugins can never be multi-instance, no diagnostic.
  - `--iset`/`--pset` are a second, weaker validation path: skips `must_fields`, the src_dirs rule, and the `max_jobs > 0` guard (`--iset x.max_jobs=0` bypasses the deadlock protection); override ordering makes the `CliOverride` provenance arm in `apply_output_dir_defaults` unreachable. Route overrides through `validate_single_processor`.
  - Provenance spans depend on a cross-module invariant (blanked vars lines + no-newline inline values) stated only in comments; span-walk multi-instance heuristic duplicated with different logic than the parser's.
  - `Config::load` parses the same bytes ~5 times across two parser crates.

- [x] 12. **Object store: two engineering standards side by side.** *(Done 2026-08-01. Descriptor atomicity, the explain-vs-rebuild divergence and the mtime-cache bypass in `needs_rebuild_descriptor` had been fixed earlier; this pass closed the rest. **Tree arms no longer ignore `output_paths`** — a declared output the descriptor never saw is now existence-checked, so adding an output to a product invalidates instead of silently skipping. **`restore_from_descriptor` was the last full-hash path**: it used `calculate_checksum` (whole-file read) where the sibling paths used the mtime-cached `verify_checksum` — that was the third redundant hash of every cached output byte per no-op build. Now routed through `verify_checksum`; `calculate_checksum` had no other caller and is deleted. **Remote pull is landed rather than removed**: `remote_pull` defaulted to true and was fully plumbed to the store while every fetch path sat behind `#[allow(dead_code)]`, so a configured remote was silently write-only and a populated bucket could never satisfy a restore. Descriptors are now pushed on write (previously only objects were, so a remote could never hold a complete entry) and pulled on a local miss via `get_descriptor_pulling`/`ensure_object`. Reporting paths (`--explain`, `product show`) use a separate non-downloading `object_available` so they agree with the build without the side effect of populating the cache; `can_restore_descriptor` is evaluated lazily in `classify` so skipped products don't drag objects down. Corrupt remote objects are rejected before admission (checksum) and malformed descriptors before storage (parse) — four unit tests over a `file://` backend cover cold-restore, pull-disabled, tree round-trip and corruption rejection. Vestigial `validity.rs` deleted. **Not done:** the Marker/Blob/Tree → one-`Vec<TreeEntry>` normalization, and the single-vs-multi-process decision; both are refactors rather than correctness holes now that the arms agree.)*
  - Blobs: atomic, format-tagged, read-only, verified (exemplary). Descriptors: plain `fs::write` over a read-only file with an acknowledged chmod-retry race; a torn descriptor permanently breaks `cache trim`. Apply the blob discipline (temp+rename) to descriptors.
  - Marker/Blob/Tree: ~20 match arms across 7 functions with real drift — `explain_descriptor` existence-checks where `needs_rebuild_descriptor` content-verifies (`--explain` can disagree with the build); Tree arms ignore `output_paths` entirely. Normalize to one `Vec<TreeEntry>` model (Marker = empty, Blob = single pathless entry).
  - Five persistence mechanisms (db.redb, mtime.redb, deps.redb, webcache.redb, JSON descriptors + blobs) with three concurrency models; the `db.redb` open-lock makes two concurrent rsconstruct processes impossible anyway, so the multi-process blob safety is unreachable. Decide single-process vs multi-process and align.
  - Remote cache is half a feature: blob push works (one exists-check + one upload subprocess per object, serial), descriptor push/fetch and object fetch are `#[allow(dead_code)]` — a populated bucket can never satisfy a restore. Land pull or error on the config.
  - Output verification bypasses the mtime cache: `needs_rebuild_descriptor` full-hashes every cached output byte via a function documented as "not hot-path", twice per no-op build (classify + per-level), third time on restore — catastrophic for cached trees like `.venv`. Route through `checksum_fast` or store `(mtime, size)` in tree entries.

- [x] 13. **Subprocess execution and exit codes.** *(Done 2026-08-01: ~26 bypassing spawn sites reduced to 2 documented exceptions. `run_command_with_stdin` added to the central path — it pumps the stdin write concurrently with draining stdout/stderr via `tokio::join!`, which is what the hand-rolled spawns needed a writer thread for; a unit test round-trips 1 MB through `cat` to pin that the deadlock is gone. Converted: aspell's stdin-feeding spawn, all **three** copies of dot→SVG (`processors::dot_to_svg`, `BuildGraph::to_svg`, `tools_graph_svg` — now one implementation), linux_module's `uname`, the tera analyzer's `git ls-files` (ctx threaded through `scan_hash_pieces`/`scan_template`), git clean + git ls-files in builder/clean, the dot probes in builder/graph, `tool_lock::query_tool_version`, and the seven pip/npm/gem/dpkg package probes in builder/tools + builder/doctor (collapsed into two helpers from seven copies of the same block). Routing `uname` through the checked path immediately surfaced the predicted drift: linux_module invoked it without declaring it, so it needed both a `required_tools()` entry and a TOOLS registry entry. The two remaining exceptions — tool installation (must inherit the terminal for `sudo`'s password prompt) and `open_file` (launches a detached viewer that must outlive rsconstruct, where `kill_on_drop` is exactly wrong) — are commented at the call site and documented in architecture.md, whose "all subprocess execution goes through run_command" claim is now accurate rather than aspirational. **Interrupt state consolidated**: the standalone `Arc<AtomicBool>` threaded through `build`/`watch`/`Executor::new` was set on the same line as `ctx.interrupt()` and only ever read OR'd with it — pure redundancy, and one call site constructed a throwaway always-false instance. Deleted; `BuildContext` is now the single source. Verified end-to-end that Ctrl+C still interrupts a running build and exits 130.)*
  - ~~`classify_error`'s fallback substring-matches the rendered error chain, which embeds subprocess stderr: tool output containing "unknown field" → exit 2; "interrupted" → 130. The typed `RsconstructError` path already covers the main producers and survives context wrapping — delete the string-matching fallback (keep the io::Error chain check), type the stragglers, default to BuildError.~~ *(Done 2026-08-01: the four load-bearing untyped producers — toml parse, serde deserialize, variable substitution, invalid-config aggregation, unknown shell — are now typed `ConfigError`s; the string fallback is deleted; unit tests pin that tool stderr can never influence the exit code.)*
  - Interrupt state is triplicated: standalone `Arc<AtomicBool>` threaded through signatures + `BuildContext.interrupted` + the tokio watch channel; the executor ORs the first two. Consolidate into BuildContext (its own docs say that was the plan).

## Low severity

- [ ] 14. **Cross-platform support is aspirational.** cfg discipline is perfect (zero `#[cfg]` outside platform.rs), but unix assumptions live above it: hard `flock` dependency (libreoffice), `/dev/null` in curl args (remote_cache), `$HOME` tilde expansion, apt-centric install methods, Linux-only release CI. The Windows branches in platform.rs have plausibly never been compiled. Either add a `cargo check --target x86_64-pc-windows-msvc` CI job or declare unix-only and delete the branches.
- [ ] 15. **Watch mode discards `event.paths`** — full Builder + FileIndex + discovery + classify on every debounced event; latency scales with project size, not change size. Acceptable today; blocks future incrementality (same root as finding 7).
- [x] 16. **Unbounded growth:** webcache stores full HTTP bodies keyed by URL forever (no TTL/eviction, reopens its DB per fetch, duplicates the object store's job); mtime.redb accumulates entries for deleted files. Fold webcache into the CAS; prune mtime entries during `cache trim`.
  *Done 2026-08-01:* webcache entries now carry a fetch timestamp and expire after `[cache] webcache_ttl_secs` (default 7 days; 0 disables the cache). This was a **correctness** bug as much as a growth one — with no expiry, a JSON schema that changed upstream was never picked up, and the only remedy was knowing `cache webcache clear` existed. The DB is opened once per process behind a `OnceLock` instead of `Database::create` per fetch (redb allows one handle, so the old code also serialized every webcache operation against itself). `rsconstruct cache trim` now reclaims three kinds of dead weight instead of one: unreferenced objects, mtime rows whose file no longer exists (`checksum::prune_mtime_cache`), and expired webcache entries — verified end-to-end reclaiming 4 mtime rows after deleting two inputs. `webcache list` gained Age/State columns. Integration tests pin both directions of expiry against a seeded cache. **Not done:** folding the webcache into the CAS. It is a different thing — keyed by URL with time-based invalidation, not by content hash — and putting it in the CAS would need a URL→content index that is itself the webcache. The TTL closes the actual defect.
- [x] 17. **Vestigial code:** `scan_root_valid` always returns true, called ~20 times; `ctx!` macro still marked "will be removed once migrated"; `main.rs` hand-resolves scan defaults for `terms` bypassing the defaults framework; fixed-point discovery loop hits its 10-pass cap silently without erroring or injecting the final pass's virtual files.
  *Done 2026-08-01:* `scan_root_valid` and its `checker_auto_detect_with_scan_root` wrapper deleted (22 references across 12 files). `ctx!` deleted — the comment was accurate, not stale: `errors::ctx()` is `#[track_caller]`, so the macro was never needed, and **the codebase now has zero `macro_rules!`**, making the project's stated goal real (CLAUDE.md's exception clause removed). The `terms`/`tags` hand-resolution is replaced by `instance_config_or_default()`, which also fixed a live panic — `rsconstruct tags check` crashed with "scan fields not resolved" in any project that hadn't declared `[processor.tags]`; the now-unused `resolve_scan` went with it. Discovery cap was fixed earlier as B10.

## Concrete bugs surfaced by this review (fixable independently of refactors)

- [x] B1. Creator `output_dirs`/`output_files` change never invalidates cache → permanent stale SKIP (finding 3) *(Done 2026-08-01: both fields added to `CreatorConfig::checksum_fields()`, matching `ExplicitConfig`; the "outputs are part of the product's identity" comment was true only of the legacy key.)*
- [x] B2. `cache = false` config field is a no-op (finding 3) *(Done 2026-08-01: field deleted — wiring it into the executor's hot path risked new bugs for a feature nobody could ever have used; reintroduce deliberately with tests if wanted.)*
- [x] B3. `--iset <x>.max_jobs=0` bypasses the load-time deadlock guard; overrides skip semantic validation generally (finding 11) *(Done 2026-08-01: `apply_overrides` re-runs `validate_single_processor` over all instances after applying; integration test pins the max_jobs=0 rejection. The "unreachable CliOverride provenance arm" sub-claim didn't hold up: `apply_output_dir_defaults` runs before overrides, so overridden values are never remapped — the arm is defense-in-depth, left in place.)*
- [x] B4. `filter_by_targets` takes no transitive closure — `-t` can drop a kept consumer's producer (finding 10) *(Done 2026-08-01: worklist closure over `dependencies` before the graph rebuild; unit tests cover single-hop, chains, and that consumers are not pulled in.)*
- [x] B5. `fix list` and `fix` disagree on what's fixable (`can_fix` vs `can_fix || config_has_fix`) (finding 8) *(Done 2026-08-01: shared `is_fixable` predicate used by both.)*
- [x] B6. `black` declares `can_fix: true` with no fix params — violates the documented invariant; batch fixing silently disabled for it (finding 8) *(Done 2026-08-01: `fix_prepend_args: ["--quiet"]` — same reformat-in-place behavior, now explicit, and batch fixing engages.)*
- [x] B7. Status stale/new distinction reads a table nothing writes — always reports "new" (finding 3) *(Done 2026-08-01: status now classifies via `explain_descriptor` on both paths — which also fixed the finding-12 asymmetry by making the Blob arm content-verify — and the legacy `CACHE_TABLE`/`CacheEntry` were deleted.)*
- [x] B8. `--json -v` leaks non-JSON lines onto stdout (finding 5) *(Done 2026-08-01: worse than reported — plain `--json` leaked build-phase lines with no `-v` at all, and `--color=always` put raw ANSI escapes on stdout. Fixed via a `human_output_enabled()` predicate replacing the quiet-only guards, forcing executor verbosity off in JSON mode, moving `--keep-going` error lines to stderr, and making JSON mode unconditionally disable color. Integration test asserts every stdout line parses as JSON across four flag combinations.)*
- [x] B9. `"${var}/suffix"` partial variable references pass through silently as literals (finding 11) *(Done 2026-08-01: post-substitution residual scan errors on any remaining `${...}` outside comments; docs now state a reference must be the entire quoted value.)*
- [x] B10. Fixed-point discovery non-convergence at the 10-pass cap is silent (finding 17) *(Done 2026-08-01: hard GraphError at the cap naming the still-adding processors; the cap is now `[build] max_discovery_passes` (default 10) per the config-knob rule.)*

## Suggested order of attack

1. **Cheap + high value:** the `FieldSpec` consolidation (collapses findings 1, parts of 3 and 8); delete the fake contracts (dead batching arms, unfired phases, string-match exit fallback, legacy cache table) and re-sync the three stale docs; CI test job + strict-skip mode (finding 4).
2. **The concrete bugs B1–B10** — each is small and independent.
3. **Structural:** output sink (5), descriptor atomicity + Tree normalization (12), Builder/pipeline split (7), module extractions (6).
4. **Only with profiling evidence:** the ready-queue scheduler (9).