Debt filed by the merge-gate calibration on PR #17031 (merged at +5,821/−6): ai/scripts/benchmark/provider-lane-election.mjs landed at 2,753 lines in one file. The operator's verdict at merge is correct and this ticket owns the repair: one file should never be that long, and the leaf should have been decomposed.
Live latest-open sweep: checked latest 20 open issues at 2026-08-12T19:26Z; no equivalent found. A2A sweep: no in-flight claim on this scope (the merge-gate feedback is minutes old).
Context
The election plan (D#17015 r6 → epic #17018 AC-B → #17024/#17034) specified the election CONTRACT — counterbalanced matrix, receipt provenance, fixed envelope — and never prescribed a single-file runner. The shape emerged in implementation and passed THREE review seats (two GPT cycles, one Claude approval) because every seat audited boundaries and correctness and none audited file shape. That is a review-dimension gap, not an author failure: the maintainer test ("would I enjoy maintaining this in a year") exists in the substrate but no review checklist row carries it, so it was applied by nobody.
The Problem
A 2,753-line module bundles at least five separable concerns whose seams the file's OWN export list already names: CLI/plan orchestration, Compose/Docker runtime authority (resolveProviderLaneDockerAuthority, stats/top parsing), provider protocol adapters (ollama chat + openai embeddings probe/workload paths), workload dispatch + resource sampling, and report assembly/finalization (finalizeProviderLaneElection, projections, incomplete-report shapes). Reviewing it end-to-end costs a full context block per cycle; every future repair pays that toll, and the #17024 live run is about to bake more onto it.
The Architectural Reality
The sibling providerLaneElectionCore.mjs (1,215 lines, pure) already demonstrates the target pattern — a focused module with a closed contract. The wake substrate's flushDeferPolicy.mjs/wakeCoalescePolicy.mjs split and the #17029 store/promote split are the same idiom. The runner should follow it, keeping provider-lane-election.mjs as a thin CLI entry that composes the extracted modules.
The Fix
- Extract, mechanically and without behavior change:
providerLaneDockerAuthority.mjs, providerLaneProtocolAdapters.mjs, providerLaneWorkloadDispatch.mjs (incl. resource sampling), and providerLaneElectionReport.mjs (schema/validator/finalizer/projections) under ai/scripts/benchmark/helpers/. The existing exported-function boundaries are the cut lines; specs move with their surfaces.
- The CLI entry retains plan parsing + orchestration only (target: the entry file under ~500 lines).
- Sequencing constraint: land AFTER #17024's live election receipt is recorded (the instrument must not change between its validation and its authoritative run) and before the runner grows again for any follow-on election.
- Generator fix (decide here, not silently): add a soft per-file LOC tripwire for
ai/** production modules (warn-level lint at e.g. 800 lines, hard-fail at e.g. 1,500 with an explicit loc-exempt: <reason> marker) so file-shape debt surfaces at commit time instead of at the merge gate. If the lint owner rejects the mechanical guard, add the file-shape row to the pr-review template's audit list instead — one of the two must land, because three seats missing the same dimension is a class failure, not three individual ones.
Acceptance Criteria
Out of Scope
- Any behavior, contract, or schema change to the election itself.
- The live election run (#17024) and its receipts.
Decision Record impact
none (mechanical decomposition; the election contract and ADR-0014 §8 authority are untouched).
Related
PR #17031 (the merged instrument) · #17034 (its leaf) · #17024 (the live outcome — sequencing gate) · #17018 (epic context)
Origin Session ID: 8637b4b9-b852-45d9-b057-de34184aae8b
Retrieval Hint: "provider lane election runner decomposition LOC tripwire file shape review dimension"
Debt filed by the merge-gate calibration on PR #17031 (merged at +5,821/−6):
ai/scripts/benchmark/provider-lane-election.mjslanded at 2,753 lines in one file. The operator's verdict at merge is correct and this ticket owns the repair: one file should never be that long, and the leaf should have been decomposed.Live latest-open sweep: checked latest 20 open issues at 2026-08-12T19:26Z; no equivalent found. A2A sweep: no in-flight claim on this scope (the merge-gate feedback is minutes old).
Context
The election plan (D#17015 r6 → epic #17018 AC-B → #17024/#17034) specified the election CONTRACT — counterbalanced matrix, receipt provenance, fixed envelope — and never prescribed a single-file runner. The shape emerged in implementation and passed THREE review seats (two GPT cycles, one Claude approval) because every seat audited boundaries and correctness and none audited file shape. That is a review-dimension gap, not an author failure: the maintainer test ("would I enjoy maintaining this in a year") exists in the substrate but no review checklist row carries it, so it was applied by nobody.
The Problem
A 2,753-line module bundles at least five separable concerns whose seams the file's OWN export list already names: CLI/plan orchestration, Compose/Docker runtime authority (
resolveProviderLaneDockerAuthority, stats/top parsing), provider protocol adapters (ollama chat + openai embeddings probe/workload paths), workload dispatch + resource sampling, and report assembly/finalization (finalizeProviderLaneElection, projections, incomplete-report shapes). Reviewing it end-to-end costs a full context block per cycle; every future repair pays that toll, and the #17024 live run is about to bake more onto it.The Architectural Reality
The sibling
providerLaneElectionCore.mjs(1,215 lines, pure) already demonstrates the target pattern — a focused module with a closed contract. The wake substrate'sflushDeferPolicy.mjs/wakeCoalescePolicy.mjssplit and the #17029 store/promote split are the same idiom. The runner should follow it, keepingprovider-lane-election.mjsas a thin CLI entry that composes the extracted modules.The Fix
providerLaneDockerAuthority.mjs,providerLaneProtocolAdapters.mjs,providerLaneWorkloadDispatch.mjs(incl. resource sampling), andproviderLaneElectionReport.mjs(schema/validator/finalizer/projections) underai/scripts/benchmark/helpers/. The existing exported-function boundaries are the cut lines; specs move with their surfaces.ai/**production modules (warn-level lint at e.g. 800 lines, hard-fail at e.g. 1,500 with an explicitloc-exempt: <reason>marker) so file-shape debt surfaces at commit time instead of at the merge gate. If the lint owner rejects the mechanical guard, add the file-shape row to the pr-review template's audit list instead — one of the two must land, because three seats missing the same dimension is a class failure, not three individual ones.Acceptance Criteria
Out of Scope
Decision Record impact
none (mechanical decomposition; the election contract and ADR-0014 §8 authority are untouched).
Related
PR #17031 (the merged instrument) · #17034 (its leaf) · #17024 (the live outcome — sequencing gate) · #17018 (epic context)
Origin Session ID: 8637b4b9-b852-45d9-b057-de34184aae8b Retrieval Hint: "provider lane election runner decomposition LOC tripwire file shape review dimension"