docs(ci): end-to-end CI map — what runs, why it's poor, what to do now

[gunbai-bot]

Consolidating map for ROADMAP §1. The other CI plan docs are slices (selection-vs-scheduling, compute-envelope, merge-freshness, measurement-loop); this one is the whole pipeline in one place, linking each slice at the point it applies (no dual representation).

Built from two independent audits that agree (neat-dove-397 Explore + quick-ant-298, the §1 CI lead), both verified on origin/main.

What it covers:

• §1 — the CI pipeline exactly as it runs today (trigger → derived ci.yml → single job → composed floor → memory-aware width → .dag affected-set).
• §2 — why it runs poorly: one root (utilization decisions — placement, runner count, caps — are not derived from the on-fabric model; they're demand-blind hand/host knobs), six faces.
• §3 — the "graveyard" resolved: mostly one missing consumer, not many broken features (placement predicate DEAD; fleet inventory alive-as-input; width loop / scheduler / ci.yml derivation / affected-set LIVE).
• §4 — leverage-ranked actions, none a tweak (derive runner deployment → enable resolve cache → cross-host matrix → edge-b rust selection → collapse dispatch dup).
• §5 — the two open operator decisions (target ceiling; build-placement-now vs fence).

Docs-only. ROADMAP §1 gains a one-line pointer (orphan-doc gate).

[briansrls]

Review — strong PR; notes focused on the Ergonomics LANE

Overall this is high quality. The charter (ci-process-end-to-end.md) is an excellent push→execute map, and the §1 reframe — "CI as the substrate integration dogfood; deliverable = shared abstractions proven by CI consuming them, faster CI falls out" — is the right DESIGN §6 move (prices the lane in displaced cost, not a KPI). Docs-only, low risk. Most of my feedback is on the new Ergonomics LANE, since that's what I want to grow into a dedicated project.

1. The keystone lens cites a now-resolved example — and would land inert (self-refuting)

The inert-abstraction lens bullet names cached_stage (#5512) as the inert witness ("tested green, consumed by nothing"). But #5512 has since wired it live — cached_stage now wraps stage_resolve via a Miss-always stub — which the Fix half's "wire the seams" bullet already describes (cached_stage wraps stage_resolve with a stub lookup → the resolve-cache seam is live). So inside the lane, cached_stage is cited as both inert (audit) and wired (fix); the moment #5512 + #5533 both land, that's a contradiction.

The deeper problem: by the lane's own §6 guardrail ("an inert lens is itself a lie; keep every lens wired to a discovered fail-closed witness"), the keystone needs a currently-inert carrier as its first RED witness — else the lens lands inert, the exact pattern it exists to catch.

Concrete fix — this PR's own charter already names the witness. Charter §4 lists Placement / Materialization / RealizationObjective as "modeled + witness-passing, no non-test consumer." Point the inert-abstraction lens at those as its discovered RED witness, and keep cached_stage as the Fix-half worked example of the full arc (seeded inert → caught → wired with a scaffold-marked stub). That ties the PR's two halves together and gives the keystone a real failing input on day one.

2. "ban source comments" is the riskiest item and the most orthogonal to folds

It's a load-bearing grammar change (02_parse/syntax), it's documentation-hygiene rather than fold-ergonomics, and it's in visible tension with this very PR (a 249-line prose doc) and with DESIGN.md / the .dag comment corpus. The lane's own "ergonomics is the #1 purity-trap magnet" guardrail applies to its own scope — I'd split this into its own runway (or down-rank it well below the fold items) and denominate its displaced cost more concretely than "inflate LOC, block review." It's the item most likely to swallow the lane.

3. Single-authority: name one home for resolve-cache enablement

The resolve-cache seam now appears in the Ergonomics LANE ("wire the seams"), §1 ("resolve-cache enabled" milestone), and §2 (caching by realization). Cross-linked, not duplicated — but each [ ] wants one owning lane. Suggestion: §1/§2 own enabling the cache (the realization work); the Ergonomics LANE owns only that the seam lands consumed-or-scaffold-marked (the construction-justification rule). One sentence fixes the boundary.

4. Minor — charter ↔ §1 dual-representation, and the [confirm] scalars

The stated principle is "link, don't restate," but ROADMAP §1 and the charter both fully enumerate G1–G5, the caching forks, and the shared-abstractions list. Consider keeping §1 to the [ ] items + G-labels + pointers and letting the charter hold the prose, or the two will drift (the §6 cost the doc itself warns about). Separately, the [confirm] scalars (width ~4, ~191s cold resolve) are load-bearing for the §10 operator decisions (target ceiling) — worth confirming before deciding on them.

Net: merge-ready as docs. The one thing I'd fix before this becomes the canonical ergonomics-lane charter is #1 — give the keystone lens a live witness (Placement/Materialization) and reframe cached_stage as the resolved worked-example.

---

Generated by Claude Code