merge-forecast
Predicts merge conflicts before any agent runs, certifies the safe fan-out width, and emits a foundation-first merge schedule.
merge-forecast
ADLC phase: P2 Decompose · Gate: the requested fan-out width never exceeds the width that is certified conflict-safe.
What it defends against
Fanning agents out wide only to have their branches collide at merge time burns
the parallel speedup twice: once building, once untangling. merge-forecast
scores every parallel-eligible ticket pair for scope overlap, namespace
collision, import radius, and historical co-change, then certifies the largest
independent set as the safe width and orders the merge foundation-first. A hard
scope-overlap veto or an over-wide --width fails the gate before any agent
runs.
Usage
adlc merge-forecast [--tickets <path>] [--width <N>] [--build-min <X>] [--merge-min <Y>]
[--co-change-limit <N>] [--conflict-threshold <F>] [--json]| Flag | Default | Description |
|---|---|---|
--tickets <path> | .adlc/tickets.json | Path to the tickets file. |
--width <N> | — | Desired fan-out width; gate fails if it exceeds the certified width. |
--build-min <X> | — | Mean ticket build time in minutes (for backpressure width). |
--merge-min <Y> | — | Mean merge-rebase-regreen time in minutes. |
--co-change-limit <N> | 500 | Git-log depth for co-change mining. |
--conflict-threshold <F> | 0.5 | Pair score at or above this triggers a SEQUENCE verdict. |
--json | off | Machine-readable JSON output. |
The forecast walks the tree and mines co-change from the git repository root, so it gives the same result from any subdirectory; --tickets and --graph-coupling paths resolve from the working directory. Outside a git repository the working directory is the root and co-change is skipped with a warning.
The --co-change-limit option must be an integer >= 1. When git history yields zero commits or empty co-change pairs, merge-forecast outputs a descriptive warning in warnings.
Tickets with no scope or an empty scope emit a warning (ticket "<id>" has no scope defined), and tickets whose declared scope matches zero files in the repository emit a warning (ticket "<id>" scope matches 0 files in repo). Any pair involving an unscoped or zero-match ticket is treated as SEQUENCE (score 1.0, signal unscoped) and excluded from parallel wave width calculations.
Exit codes
--width exceeds the certified width, or a vetoed / high-risk pair is scheduled concurrently.Example
$ adlc merge-forecast --width 4
certifiedWidth: 2 recommendedWidth: 2
AUTH-1 ↔ AUTH-2 SEQUENCE scope-overlap (1.00) — declared scopes overlap
Gate failed:
--width 4 exceeds certifiedWidth 2
exit 2Go deeper
quartermaster
The operator-local supply layer. Decides which model runs which lifecycle job from a registry outside the repo, and routes build work by derived class rather than by the caller's label.
build-gate
Denies starting a high-risk ticket's build in a degraded (context-rot) session unless an audited override is durably recorded.