From 1a01f7c427a9ed8f68b3bbaf1f793ab2ece7da87 Mon Sep 17 00:00:00 2001
From: Igor Gerasimov <gerasimowigor@gmail.com>
Date: Wed, 29 Jul 2026 13:42:57 +0200
Subject: [PATCH] =?UTF-8?q?feat(consilium):=20ADR-005=20Phase=201=20?=
 =?UTF-8?q?=E2=80=94=20tier-per-round=20develop=20scope=20(scope:=20top)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The PDO-819 develop round shipped all 6 action points in one ~100-file
MR the operator closed as unreviewable. The binary p0/all chooser (#580)
dead-ends after the P0 merge: the next verdict starts at P1 and the p0
scope filters to empty.

- filterDevScope (pure, exported, unit-tested): scope 'top' keeps only
  the HIGHEST priority tier still present (P0→P1→P2→P3→unprioritized) —
  each round ships one small MR and the next round's verdict naturally
  carries the following tier, all the way to convergence.
- develop()/route/hook accept 'top'; the UI chooser offers
  'Only <tier> (n) — small MR' with the tier resolved dynamically.
- ADR-005 records the full mechanism: Phase 2 (stacked MRs in one
  round, bottom-up merge) and Phase 3 (repo-map size-aware grouping)
  as proposed follow-ups.

loop-fsm + develop-route: 161 passed (4 new). tsc + vite build clean.
---
 client/src/hooks/use-consilium-loops.ts       |  6 +-
 client/src/pages/ConsiliumLoopDetail.tsx      | 30 +++++----
 docs/adr/ADR-005-mr-splitting.md              | 64 +++++++++++++++++++
 server/routes/consilium-loops.ts              |  4 +-
 .../consilium/consilium-loop-controller.ts    | 37 ++++++++---
 .../consilium-loops-develop-route.test.ts     | 11 ++++
 tests/unit/consilium/loop-fsm.test.ts         | 21 ++++++
 7 files changed, 148 insertions(+), 25 deletions(-)
 create mode 100644 docs/adr/ADR-005-mr-splitting.md

diff --git a/client/src/hooks/use-consilium-loops.ts b/client/src/hooks/use-consilium-loops.ts
index 12a9a40..bfd68df 100644
--- a/client/src/hooks/use-consilium-loops.ts
+++ b/client/src/hooks/use-consilium-loops.ts
@@ -518,9 +518,9 @@ export function useApproveMerge() {
  */
 export function useDevelopLoop() {
   const qc = useQueryClient();
-  return useMutation<ConsiliumLoopRow, Error, { id: string; scope?: "p0" | "all" }>({
-    // MR-size control: `scope: "p0"` develops only the P0s (small reviewable MR);
-    // omitted/"all" keeps the historical full-verdict round.
+  return useMutation<ConsiliumLoopRow, Error, { id: string; scope?: "p0" | "top" | "all" }>({
+    // MR-size control: `scope: "top"` develops only the highest remaining priority
+    // tier (small reviewable MR); omitted/"all" keeps the historical full round.
     mutationFn: ({ id, scope }) =>
       apiRequest("POST", `${LIST_KEY}/${id}/develop`, scope ? { scope } : undefined),
     onSuccess: (_data, { id }) => {
diff --git a/client/src/pages/ConsiliumLoopDetail.tsx b/client/src/pages/ConsiliumLoopDetail.tsx
index 826dedd..8221652 100644
--- a/client/src/pages/ConsiliumLoopDetail.tsx
+++ b/client/src/pages/ConsiliumLoopDetail.tsx
@@ -2806,11 +2806,18 @@ export default function ConsiliumLoopDetail() {
   const latestActionPointCount = Array.isArray(latestRound?.openActionPoints)
     ? latestRound!.openActionPoints.length
     : 0;
-  // MR-size control: P0 slice of the latest verdict — offered as a smaller round.
-  const latestP0Count = Array.isArray(latestRound?.openActionPoints)
-    ? (latestRound!.openActionPoints as ActionPoint[]).filter((ap) => ap.priority === "P0")
-        .length
-    : 0;
+  // MR-size control (ADR-005 Phase 1): the HIGHEST priority tier still present in
+  // the latest verdict — offered as a smaller round (mirrors server filterDevScope).
+  const latestAps: ActionPoint[] = Array.isArray(latestRound?.openActionPoints)
+    ? (latestRound!.openActionPoints as ActionPoint[])
+    : [];
+  const tierRankOf = (p?: string): number =>
+    ({ P0: 0, P1: 1, P2: 2, P3: 3 } as Record<string, number>)[p ?? ""] ?? 4;
+  const topTierRank = latestAps.length
+    ? Math.min(...latestAps.map((ap) => tierRankOf(ap.priority)))
+    : 4;
+  const topTierLabel = ["P0", "P1", "P2", "P3", "unprioritized"][topTierRank];
+  const topTierCount = latestAps.filter((ap) => tierRankOf(ap.priority) === topTierRank).length;
   const canDevelop =
     isVerdictTerminalLoopState(loop.state) && latestActionPointCount > 0;
 
@@ -2887,7 +2894,8 @@ export default function ConsiliumLoopDetail() {
   async function handleDevelop(scopeArg?: unknown) {
     // Normalize: plain onClick callers pass a click event — only the two literal
     // scopes ride to the server; anything else means "all" (historical behaviour).
-    const scope = scopeArg === "p0" || scopeArg === "all" ? scopeArg : undefined;
+    const scope =
+      scopeArg === "p0" || scopeArg === "top" || scopeArg === "all" ? scopeArg : undefined;
     setDevelopScopeOpen(false);
     try {
       await developLoop.mutateAsync({ id, scope });
@@ -2965,9 +2973,9 @@ export default function ConsiliumLoopDetail() {
               <Button
                 size="sm"
                 onClick={() =>
-                  // A meaningful scope choice exists only when the verdict has BOTH
-                  // P0s and non-P0s — otherwise hand off the full list directly.
-                  latestP0Count > 0 && latestP0Count < latestActionPointCount
+                  // A meaningful scope choice exists only when the top tier is a
+                  // strict subset of the verdict — otherwise hand off directly.
+                  topTierCount > 0 && topTierCount < latestActionPointCount
                     ? setDevelopScopeOpen(true)
                     : handleDevelop()
                 }
@@ -3219,8 +3227,8 @@ export default function ConsiliumLoopDetail() {
           </AlertDialogHeader>
           <AlertDialogFooter>
             <AlertDialogCancel>Cancel</AlertDialogCancel>
-            <AlertDialogAction onClick={() => void handleDevelop("p0")}>
-              Only P0s ({latestP0Count}) — small MR
+            <AlertDialogAction onClick={() => void handleDevelop("top")}>
+              Only {topTierLabel} tier ({topTierCount}) — small MR
             </AlertDialogAction>
             <AlertDialogAction onClick={() => void handleDevelop("all")}>
               All action points ({latestActionPointCount})
diff --git a/docs/adr/ADR-005-mr-splitting.md b/docs/adr/ADR-005-mr-splitting.md
new file mode 100644
index 0000000..6aa7656
--- /dev/null
+++ b/docs/adr/ADR-005-mr-splitting.md
@@ -0,0 +1,64 @@
+# ADR-005: Splitting a large verdict into several small, well-sized MRs
+
+- **Status**: accepted (Phase 1 implemented; Phases 2–3 proposed)
+- **Date**: 2026-07-29
+- **Context anchor**: PDO-819 develop round shipped ALL 6 action points in one MR
+  (~100 changed files across many components) — the operator closed it as
+  unreviewable. ADR-004 fixed *what* an MR is (a result); this ADR fixes *how big*
+  one may be.
+
+## Problem
+
+A develop round implements the WHOLE verdict in one branch → one MR. A verdict
+routinely carries 5–10 heavyweight action points across priority tiers (P0..P3),
+so the single MR grows beyond human review capacity. The loop's value collapses
+exactly at its human gate.
+
+## Decision
+
+An MR must be a REVIEWABLE unit. The loop reaches the full verdict through
+multiple small MRs, using its own round mechanism as the splitter.
+
+### Phase 1 — tier-per-round (implemented)
+
+`develop(loopId, { scope })` with `scope: "top"` filters the verdict to the
+HIGHEST priority tier still present (P0 → P1 → P2 → P3 → unprioritized;
+`filterDevScope`, pure + unit-tested). Flow:
+
+```
+verdict (2×P0 + 3×P1 + 2×P2)
+  → develop scope:"top"  → MR₁ = the 2 P0s   → review → merge
+  → next review round (auto) → verdict = remainder
+  → develop scope:"top"  → MR₂ = the 3 P1s   → review → merge
+  → …until convergence
+```
+
+The UI's "Hand off to SDLC" opens a chooser — "Only <tier> (n) — small MR" vs
+"All action points (m)" — whenever the top tier is a strict subset. Sequential by
+design: each tier waits for the previous merge, which keeps every MR based on
+reviewed, merged code (no stacked-conflict class).
+
+### Phase 2 — stacked MRs in one round (proposed)
+
+For operators who want the whole verdict IN FLIGHT at once: the executor splits
+the verdict into tier chunks, builds them in one worktree lineage, and pushes a
+BRANCH STACK — MR₁ (P0 → main), MR₂ (P1 → branch₁), MR₃ (P2 → branch₂) — reviewed
+and merged bottom-up (Graphite-style). Requires FSM surgery: `prRef` becomes a
+stack, `awaiting_merge` gates each level, partial-merge states. Deliberately a
+separate change; Phase 1 covers the need sequentially.
+
+### Phase 3 — size-aware grouping ("правильно оценена")
+
+Priority is a proxy; the real budget is blast radius. The planner estimates the
+files each action point touches (repo-map assisted) and groups APs into MR-sized
+chunks under a byte/file budget (e.g. ≤20 files per MR), splitting a tier or
+merging small tiers as needed. The verdict then presents estimated MR sizes
+BEFORE the operator commits to a scope.
+
+## Consequences
+
+- Phase 1 changes no FSM semantics: absent scope stays byte-identical; each round
+  still produces exactly one MR, only its contents narrow.
+- Multi-round convergence takes more wall-clock (review+merge per tier) — the
+  accepted cost of reviewability.
+- Phases 2–3 are additive follow-ups; nothing in Phase 1 blocks them.
diff --git a/server/routes/consilium-loops.ts b/server/routes/consilium-loops.ts
index 1b23b33..99636bf 100644
--- a/server/routes/consilium-loops.ts
+++ b/server/routes/consilium-loops.ts
@@ -403,8 +403,8 @@ export function registerConsiliumLoopRoutes(
     // MR-size control: optional `scope` narrows the round to the P0s — the operator
     // ships a small reviewable MR and lets the next round carry the remainder.
     const rawScope = (req.body as { scope?: unknown } | undefined)?.scope;
-    if (rawScope !== undefined && rawScope !== "p0" && rawScope !== "all") {
-      return res.status(400).json({ error: 'scope must be "p0" or "all"' });
+    if (rawScope !== undefined && rawScope !== "p0" && rawScope !== "top" && rawScope !== "all") {
+      return res.status(400).json({ error: 'scope must be "p0", "top" or "all"' });
     }
     const result =
       rawScope !== undefined
diff --git a/server/services/consilium/consilium-loop-controller.ts b/server/services/consilium/consilium-loop-controller.ts
index 9918338..0e7aca4 100644
--- a/server/services/consilium/consilium-loop-controller.ts
+++ b/server/services/consilium/consilium-loop-controller.ts
@@ -483,6 +483,28 @@ const SDLC_DEV_MAX_ACTION_POINTS = 24;
  */
 export const SDLC_DEV_REDRIVE_GRACE_MS = SDLC_DEV_GRACE_MS * SDLC_DEV_MAX_ACTION_POINTS;
 
+/**
+ * MR-size control (ADR-005 Phase 1): the develop-scope filter. `"top"` keeps ONLY
+ * the highest-priority tier still present in the verdict (P0 → P1 → P2 → P3 →
+ * unprioritized), so each round ships one small, reviewable MR and the loop's next
+ * round naturally carries the following tier. `"p0"` is the narrower historical
+ * scope (empty once the P0s are merged); `"all"`/absent is the full verdict.
+ * Pure + exported for direct unit-testing.
+ */
+export function filterDevScope(
+  actionPoints: readonly ActionPoint[],
+  scope?: "p0" | "top" | "all",
+): ActionPoint[] {
+  if (scope === "p0") return actionPoints.filter((ap) => ap.priority === P0_PRIORITY);
+  if (scope === "top") {
+    const TIER_RANK: Record<string, number> = { P0: 0, P1: 1, P2: 2, P3: 3 };
+    const rank = (ap: ActionPoint): number => TIER_RANK[ap.priority ?? ""] ?? 4;
+    const best = Math.min(...actionPoints.map(rank));
+    return actionPoints.filter((ap) => rank(ap) === best);
+  }
+  return [...actionPoints];
+}
+
 /**
  * Liveness heartbeat: minimum interval between `updated_at` touches of the loop
  * row from the dispatchSdlc progress sink. A LIVE multi-AP round beats at every
@@ -1257,7 +1279,7 @@ export class ConsiliumLoopController {
    */
   async develop(
     loopId: string,
-    opts?: { scope?: "p0" | "all" },
+    opts?: { scope?: "p0" | "top" | "all" },
   ): Promise<DevelopResult> {
     const loop = await this.storage.getLoop(loopId);
     if (!loop) return { ok: false, code: "NOT_FOUND" };
@@ -1266,14 +1288,11 @@ export class ConsiliumLoopController {
     // FULL action points (ALL priorities) — SERVER-READ from the verdict; the
     // close-out reads only `openActionPoints`, but openP0 feeds the round audit.
     const allActionPoints = await this.resolveDevActionPoints(loop);
-    // MR-SIZE CONTROL: `scope: "p0"` develops ONLY the P0s — one small, reviewable
-    // MR per round; after its merge the loop's next review round re-derives the
-    // remainder and the operator ships it as the NEXT round's MR. Default "all"
-    // (absent opts) is byte-identical to the historical full-list handoff.
-    const actionPoints =
-      opts?.scope === "p0"
-        ? allActionPoints.filter((ap) => ap.priority === P0_PRIORITY)
-        : allActionPoints;
+    // MR-SIZE CONTROL (ADR-005 Phase 1): scope the round — `"top"` ships only the
+    // highest remaining priority tier as one small MR; after its merge the next
+    // review round re-derives the remainder (next tier). Default "all" (absent
+    // opts) is byte-identical to the historical full-list handoff.
+    const actionPoints = filterDevScope(allActionPoints, opts?.scope);
     if (actionPoints.length === 0) return { ok: false, code: "NO_ACTION_POINTS" };
 
     // Re-validate the persisted repoPath: global allowlist THEN project workspace.
diff --git a/tests/unit/consilium/consilium-loops-develop-route.test.ts b/tests/unit/consilium/consilium-loops-develop-route.test.ts
index 51a1939..6f642ee 100644
--- a/tests/unit/consilium/consilium-loops-develop-route.test.ts
+++ b/tests/unit/consilium/consilium-loops-develop-route.test.ts
@@ -114,6 +114,17 @@ describe("POST /api/consilium-loops/:id/develop", () => {
     });
   });
 
+  it('MR-size control: scope:"top" passes through (highest remaining tier)', async () => {
+    const { app, controller } = makeApp();
+    const res = await request(app)
+      .post(`/api/consilium-loops/${LOOP_ID}/develop`)
+      .send({ scope: "top" });
+    expect(res.status).toBe(200);
+    expect(controller.develop as ReturnType<typeof vi.fn>).toHaveBeenCalledWith(LOOP_ID, {
+      scope: "top",
+    });
+  });
+
   it("MR-size control: an unknown scope → 400, develop NOT called", async () => {
     const { app, controller } = makeApp();
     const res = await request(app)
diff --git a/tests/unit/consilium/loop-fsm.test.ts b/tests/unit/consilium/loop-fsm.test.ts
index 1a31862..7bc2ee9 100644
--- a/tests/unit/consilium/loop-fsm.test.ts
+++ b/tests/unit/consilium/loop-fsm.test.ts
@@ -12,6 +12,7 @@ import {
   pickJudgeOutput,
   composeCancelExplanation,
   ConsiliumLoopController,
+  filterDevScope,
   MAX_CONCURRENT_DEV_HANDOFFS,
   SDLC_DEV_REDRIVE_GRACE_MS,
   type LoopEvent,
@@ -1448,3 +1449,23 @@ describe("developing liveness heartbeat — one-coder-sized redrive (no babysitt
     await flush();
   });
 });
+
+describe("filterDevScope (ADR-005 Phase 1 — MR-size control)", () => {
+  const aps = [
+    { title: "a", priority: "P1" },
+    { title: "b", priority: "P2" },
+    { title: "c", priority: "P1" },
+    { title: "d" }, // unprioritized
+  ];
+  it('"top" keeps only the highest tier still present (P1 here — the P0s are merged)', () => {
+    expect(filterDevScope(aps, "top").map((ap) => ap.title)).toEqual(["a", "c"]);
+  });
+  it('"top" falls through to the unprioritized bucket when nothing carries a tier', () => {
+    expect(filterDevScope([{ title: "x" }, { title: "y" }], "top")).toHaveLength(2);
+  });
+  it('"p0" / "all" / absent keep their historical shapes', () => {
+    expect(filterDevScope(aps, "p0")).toHaveLength(0);
+    expect(filterDevScope(aps, "all")).toHaveLength(4);
+    expect(filterDevScope(aps)).toHaveLength(4);
+  });
+});