@quolu/lattice 0.12.12 → 0.12.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.12.12",
+  "version": "0.12.13",
   "description": "Lattice — phase-aware TODO graph compiler and conflict-aware orchestration runtime",
   "type": "module",
   "license": "MIT",

package/src/todo-dashboard-registry.mjs

@@ -6,6 +6,16 @@ import {
 } from 'node:fs/promises';
 import path from 'node:path';
 
+import packageJson from '../package.json' with { type: 'json' };
+
+/**
+ * The version of the code in THIS process. A daemon loads its modules once at
+ * startup and keeps serving them, so installing a new package does not change
+ * what the running daemon serves. The daemon reports the version it started
+ * with; anything else is code that has already been replaced on disk.
+ */
+export const TODO_DASHBOARD_CODE_VERSION = packageJson.version;
+
 const REGISTRY_SCHEMA = 'lattice.todo_dashboard_registry.v1';
 const DAEMON_SCHEMA = 'lattice.todo_dashboard_daemon.v1';
 const DEFAULT_PORT = 0;
@@ -182,7 +192,13 @@ async function daemonAttestation(descriptor, { timeoutMs = 2_000 } = {}) {
     if (body?.schema !== 'lattice.todo_dashboard_health.v1' || body.pid !== descriptor.pid
       || !Array.isArray(body.project_ids)) return null;
     const keys = Object.keys(body).sort().join(',');
-    if (keys === 'pid,port,project_ids,schema' && body.port === descriptor.port) return 'current';
+    // 'legacy' means "alive, but serving code we have already replaced" — the
+    // caller starts a replacement and stops it. A daemon that predates the
+    // version field, or one still running an older package, is exactly that.
+    if (keys === 'pid,port,project_ids,schema,version' && body.port === descriptor.port) {
+      return body.version === TODO_DASHBOARD_CODE_VERSION ? 'current' : 'legacy';
+    }
+    if (keys === 'pid,port,project_ids,schema' && body.port === descriptor.port) return 'legacy';
     if (keys === 'pid,project_ids,schema') return 'legacy';
     return null;
   } catch { return null; }

package/src/todo-gantt-html.mjs

@@ -6,7 +6,7 @@ import {
 } from './todo-markdown-renderer.mjs';
 import { renderTodoGanttSvg, TODO_GANTT_STATUS_PRESENTATION } from './todo-gantt-svg.mjs';
 
-export const TODO_GANTT_RENDERER_VERSION = 'lattice.todo_gantt_renderer.v9';
+export const TODO_GANTT_RENDERER_VERSION = 'lattice.todo_gantt_renderer.v10';
 export const TODO_GANTT_PROSE_MAX_BYTES = 8 * 1024 * 1024;
 export const TODO_GANTT_HTML_MAX_BYTES = 24 * 1024 * 1024;
 
@@ -131,14 +131,16 @@ function foldIndex(layout) {
   return new Map((layout?.folded ?? []).map((entry) => [refKey(entry.task), refKey(entry.fold)]));
 }
 
-function renderTaskIndexEntry(section, lookup, folds) {
+function renderTaskIndexEntry(section, lookup) {
   const key = refKey(section.ref);
   const status = DOCUMENT_STATUS[section.state.status] ?? { mark: '?', label: '状態不明' };
   const blockedReason = section.state.status === 'blocked'
     ? `<span class="task-index-blocked-reason">— ${escapeHtmlText(section.state.blocked_reason ?? '理由未記録')}</span>` : '';
-  // A folded ToDo keeps its row here — the index is the complete list — but
-  // selecting it points at the fold node that actually stands on the diagram.
-  const selectKey = folds.get(key) ?? key;
+  // A folded ToDo keeps its row here — the index is the complete list — and it
+  // selects its OWN detail. Pointing the row at the fold node standing in for it
+  // on the diagram would open nothing: a fold node is not a ToDo, so no detail
+  // panel carries its key.
+  const selectKey = key;
   return `<li><button type="button" data-select-node-key="${escapeHtmlAttribute(selectKey)}"><span class="task-index-status status-${escapeHtmlAttribute(section.state.status)}" role="img" aria-label="${escapeHtmlAttribute(status.label)}">${escapeHtmlText(status.mark)}</span><span class="task-index-reference">${escapeHtmlText(taskReference(section, lookup))}</span><strong>${escapeHtmlText(section.task.title)}</strong>${blockedReason}</button></li>`;
 }
 
@@ -156,13 +158,33 @@ function renderTaskIndex(sections, lookup, folds = new Map()) {
     const drawn = plan.tasks.filter((section) => !folds.has(refKey(section.ref)));
     const folded = plan.tasks.filter((section) => folds.has(refKey(section.ref)));
     const drawnList = drawn.length === 0 ? ''
-      : `<ol class="task-index-list">${drawn.map((section) => renderTaskIndexEntry(section, lookup, folds)).join('')}</ol>`;
+      : `<ol class="task-index-list">${drawn.map((section) => renderTaskIndexEntry(section, lookup)).join('')}</ol>`;
     const foldedList = folded.length === 0 ? ''
-      : `<details class="task-index-folded"><summary>完走済みとして畳んだ工程 ${folded.length}件</summary><ol class="task-index-list">${folded.map((section) => renderTaskIndexEntry(section, lookup, folds)).join('')}</ol></details>`;
+      : `<details class="task-index-folded"><summary>完走済みとして畳んだ工程 ${folded.length}件</summary><ol class="task-index-list">${folded.map((section) => renderTaskIndexEntry(section, lookup)).join('')}</ol></details>`;
     return `<section class="task-index-plan"><h2><code>${escapeHtmlText(plan.planKey)}</code></h2>${drawnList}${foldedList}</section>`;
   }).join('');
 }
 
+/**
+ * Detail panel for a fold node.
+ *
+ * A fold node is the only thing standing on the diagram for the history it
+ * summarises, so it must open like any other node — otherwise clicking the
+ * folded part of the plan does nothing and the folded ToDos become unreachable.
+ */
+function renderFoldDetail(fold, members, lookup) {
+  const laneLabels = fold.lanes.map((lane) => {
+    const entry = lookup.lanes.get(JSON.stringify([fold.ref.plan_key, lane]));
+    return entry === undefined ? lane : `${lane} — ${entry.name}`;
+  });
+  const chain = fold.longest_chain_task_count === 0 ? ''
+    : `<p><strong>構造上の最長依存鎖:</strong> このうち${fold.longest_chain_task_count}工程が乗っています。</p>`;
+  const memberList = members.length === 0
+    ? '<p class="relation-empty">構成工程を復元できませんでした。</p>'
+    : `<ol class="task-index-list">${members.map((section) => renderTaskIndexEntry(section, lookup)).join('')}</ol>`;
+  return `<article class="task-detail fold-detail" data-detail-key="${escapeHtmlAttribute(refKey(fold.ref))}" hidden><header><span class="detail-status status-done">▣ 完走済み（畳み込み）</span><span class="detail-reference">${escapeHtmlText(`${fold.task_count}工程`)}</span></header><h1>完了済み ${escapeHtmlText(String(fold.task_count))}件</h1><p><strong>plan:</strong> <code>${escapeHtmlText(fold.ref.plan_key)}</code></p><p class="detail-category"><strong>カテゴリ:</strong> ${escapeHtmlText(laneLabels.join('、'))}</p>${chain}<p class="fold-note">後続に作業中・未着手の工程が残っていないため、まとめて1個のノードとして描いています。図に全件を描くには <code>lattice todo gantt --scope all</code> を実行してください。</p><section><h2>含まれる工程 ${escapeHtmlText(String(members.length))}件</h2>${memberList}</section></article>`;
+}
+
 function presentationLookup(presentation) {
   return {
     lanes: new Map((presentation?.lanes ?? []).map((lane) => [JSON.stringify([lane.plan_key, lane.lane]), lane])),
@@ -175,14 +197,19 @@ function taskReference(section, lookup) {
   return number === undefined ? `ID ${section.task.task_id}` : `工程 ${number.display_number}`;
 }
 
-function renderRelationList(relations, sectionByKey, lookup, emptyText) {
+function renderRelationList(relations, sectionByKey, lookup, emptyText, folds = new Map()) {
   if (relations.length === 0) return `<p class="relation-empty">${escapeHtmlText(emptyText)}</p>`;
   return `<ul class="relation-list">${relations.map((relation) => {
-    const target = sectionByKey.get(refKey(relation.ref));
+    const targetKey = refKey(relation.ref);
+    const target = sectionByKey.get(targetKey);
     if (target === undefined) return '';
     const join = relation.joinIds.length === 0 ? ''
       : `<span class="relation-kind">合流条件: ${escapeHtmlText(relation.joinIds.join(', '))}</span>`;
-    return `<li><button type="button" data-select-node-key="${escapeHtmlAttribute(refKey(target.ref))}"><strong>${escapeHtmlText(taskReference(target, lookup))}</strong><span>${escapeHtmlText(target.task.title)}</span></button>${join}</li>`;
+    // Mark the ones the diagram no longer draws separately, so the reader knows
+    // why they cannot find this box on screen.
+    const reference = folds.has(targetKey)
+      ? `▣ ${taskReference(target, lookup)}` : taskReference(target, lookup);
+    return `<li><button type="button" data-select-node-key="${escapeHtmlAttribute(targetKey)}"><strong>${escapeHtmlText(reference)}</strong><span>${escapeHtmlText(target.task.title)}</span></button>${join}</li>`;
   }).join('')}</ul>`;
 }
 
@@ -211,6 +238,7 @@ function renderRightPane(sections, layout, presentation, readModel) {
   const lookup = presentationLookup(presentation);
   const sectionByKey = new Map(sections.map((section) => [refKey(section.ref), section]));
   const nodeByKey = new Map(layout.nodes.map((node) => [refKey(node.ref), node]));
+  const folds = foldIndex(layout);
   const incoming = new Map(sections.map((section) => [refKey(section.ref), []]));
   const outgoing = new Map(sections.map((section) => [refKey(section.ref), []]));
   const addRelation = (relations, ownerKey, ref, joinIds) => {
@@ -223,7 +251,10 @@ function renderRightPane(sections, layout, presentation, readModel) {
     }
     entry.joinIds = [...new Set([...entry.joinIds, ...joinIds])].sort();
   };
-  for (const edge of layout.edges) {
+  // Premises and successors come from the FULL graph. `layout.edges` is the
+  // drawn graph, where a fold unit's interior dependencies have been contracted
+  // away — reading those here would tell a folded ToDo it has no premises.
+  for (const edge of layout.full_edges ?? layout.edges) {
     addRelation(incoming, refKey(edge.to), edge.from, edge.join_ids);
     addRelation(outgoing, refKey(edge.from), edge.to, edge.join_ids);
   }
@@ -256,10 +287,25 @@ function renderRightPane(sections, layout, presentation, readModel) {
     const readiness = node?.visibility.next_ready
       ? `<p class="readiness-note">ready frontierの一員です。${ready.length > 1 ? '他のready工程と同時dispatchするのが既定です。subsetだけを選ぶ場合は理由を記録してください。' : '現在の唯一の着手候補です。'}</p>`
       : incoming.get(key).length === 0 ? '<p class="readiness-note">登録済みの前提工程はありません。図だけではdispatch可否を判定しません。</p>' : '';
-    return `<article class="task-detail" data-detail-key="${escapeHtmlAttribute(key)}" hidden><header><span class="detail-status status-${escapeHtmlAttribute(section.state.status)}">${escapeHtmlText(status.mark)} ${escapeHtmlText(status.label)}</span><span class="detail-reference">${escapeHtmlText(taskReference(section, lookup))}</span></header><h1>${escapeHtmlText(section.task.title)}</h1><p class="detail-category"><strong>カテゴリ:</strong> ${escapeHtmlText(category)}</p>${categoryDescription}<p><strong>正規ID:</strong> <code>${escapeHtmlText(`${section.ref.plan_key}/${section.task.task_id}`)}</code></p>${blockedReason}${readiness}<section><h2>前提工程</h2>${renderRelationList(incoming.get(key), sectionByKey, lookup, '登録済みの前提工程はありません。')}</section><section><h2>後続工程</h2>${renderRelationList(outgoing.get(key), sectionByKey, lookup, '登録済みの後続工程はありません。')}</section><p class="anchor-status">${escapeHtmlText(anchorText)}</p><details class="task-diagnostics"><summary>開発者向け診断</summary><dl><dt>canonical ref</dt><dd><code>${escapeHtmlText(`${section.ref.project_id}/${section.ref.plan_key}/${section.task.task_id}`)}</code></dd><dt>anchor</dt><dd>${escapeHtmlText(section.anchorOutcome.anchored ? 'verified' : section.anchorOutcome.reason)}</dd></dl></details></article>`;
+    // A folded ToDo has no box of its own on the diagram. Say which fold node
+    // stands in for it, and make that node one click away.
+    const foldKey = folds.get(key);
+    const foldedNote = foldKey === undefined ? ''
+      : `<p class="fold-note">この工程は図の上では ▣ 畳み込みノードにまとめられています。<button type="button" class="fold-return" data-select-node-key="${escapeHtmlAttribute(foldKey)}">畳み込みノードを開く</button></p>`;
+    return `<article class="task-detail" data-detail-key="${escapeHtmlAttribute(key)}" hidden><header><span class="detail-status status-${escapeHtmlAttribute(section.state.status)}">${escapeHtmlText(status.mark)} ${escapeHtmlText(status.label)}</span><span class="detail-reference">${escapeHtmlText(taskReference(section, lookup))}</span></header><h1>${escapeHtmlText(section.task.title)}</h1><p class="detail-category"><strong>カテゴリ:</strong> ${escapeHtmlText(category)}</p>${categoryDescription}<p><strong>正規ID:</strong> <code>${escapeHtmlText(`${section.ref.plan_key}/${section.task.task_id}`)}</code></p>${blockedReason}${readiness}${foldedNote}<section><h2>前提工程</h2>${renderRelationList(incoming.get(key), sectionByKey, lookup, '登録済みの前提工程はありません。', folds)}</section><section><h2>後続工程</h2>${renderRelationList(outgoing.get(key), sectionByKey, lookup, '登録済みの後続工程はありません。', folds)}</section><p class="anchor-status">${escapeHtmlText(anchorText)}</p><details class="task-diagnostics"><summary>開発者向け診断</summary><dl><dt>canonical ref</dt><dd><code>${escapeHtmlText(`${section.ref.project_id}/${section.ref.plan_key}/${section.task.task_id}`)}</code></dd><dt>anchor</dt><dd>${escapeHtmlText(section.anchorOutcome.anchored ? 'verified' : section.anchorOutcome.reason)}</dd></dl></details></article>`;
   }).join('');
-  const taskIndex = renderTaskIndex(sections, lookup, foldIndex(layout));
-  return `<div class="right-toolbar"><button type="button" data-show-overview>概要</button><button type="button" data-show-selected hidden>選択工程へ戻る</button><button type="button" data-show-task-index>元Markdown全文</button></div><div class="right-content">${overview}<div data-right-panel="details" hidden>${details}</div><section class="task-index" data-right-panel="task-index" hidden><h1>全工程</h1><p>Latticeに登録された全工程を、現在の状態とともに登録順で表示しています。</p>${taskIndex}</section></div>`;
+  const membersByFold = new Map();
+  for (const [taskKey, foldKey] of folds) {
+    const section = sectionByKey.get(taskKey);
+    if (section === undefined) continue;
+    if (!membersByFold.has(foldKey)) membersByFold.set(foldKey, []);
+    membersByFold.get(foldKey).push(section);
+  }
+  const foldDetails = (layout.scope?.folds ?? [])
+    .map((fold) => renderFoldDetail(fold, membersByFold.get(refKey(fold.ref)) ?? [], lookup))
+    .join('');
+  const taskIndex = renderTaskIndex(sections, lookup, folds);
+  return `<div class="right-toolbar"><button type="button" data-show-overview>概要</button><button type="button" data-show-selected hidden>選択工程へ戻る</button><button type="button" data-show-task-index>元Markdown全文</button></div><div class="right-content">${overview}<div data-right-panel="details" hidden>${details}${foldDetails}</div><section class="task-index" data-right-panel="task-index" hidden><h1>全工程</h1><p>Latticeに登録された全工程を、現在の状態とともに登録順で表示しています。</p>${taskIndex}</section></div>`;
 }
 
 function renderDiagramLegend(presentation, layout = null) {
@@ -327,6 +373,9 @@ body{display:grid;grid-template-rows:minmax(0,1fr);height:100vh;margin:0;backgro
 .task-index-list{margin:0;padding:0;list-style:none}.task-index-list li+li{margin-top:8px}.task-index-list button{display:grid;width:100%;grid-template-columns:1.5rem auto minmax(0,1fr);gap:4px 8px;align-items:baseline}
 .task-index-status{grid-row:1 / span 2;color:var(--text-secondary);font-size:13.5px;text-align:center}.task-index-status.status-in-progress{color:var(--accent)}.task-index-status.status-done{color:var(--good)}.task-index-status.status-blocked{color:var(--critical)}
 .task-index-reference{color:var(--text-secondary);font-size:12px;white-space:nowrap}.task-index-list strong{font-size:13.5px;font-weight:600;overflow-wrap:anywhere}.task-index-blocked-reason{grid-column:2 / -1;color:var(--text-secondary);font-size:12px;overflow-wrap:anywhere}
+.fold-detail>section{margin-top:16px}.fold-detail h2{margin:0 0 12px;font-size:16px;font-weight:600}
+.fold-return{margin-left:8px;padding:2px 8px;border:1px solid var(--border);border-radius:4px;background:var(--surface-2);color:var(--text-primary);font:500 12px/1.6 system-ui,-apple-system,"Hiragino Sans","Yu Gothic UI",sans-serif;cursor:pointer}
+.fold-return:focus-visible{outline:2px solid var(--text-primary);outline-offset:2px}
 .todo-gantt text{font-family:system-ui,-apple-system,"Hiragino Sans","Yu Gothic UI",sans-serif;pointer-events:none}
 .todo-node .node-surface{fill:var(--surface-2);stroke:var(--border);stroke-width:1}
 .todo-node .node-meta{fill:var(--text-secondary);font-size:12px;font-weight:500}

package/src/todo-gantt-layout.mjs

@@ -403,7 +403,7 @@ export function layoutTodoGantt(readModel, chainProjection, options = {}) {
 
   // Only the geometry stage below sees the narrowed graph.
   const projected = scope === 'all'
-    ? { nodes: full.nodes, edges: full.edges, foldedByKey: new Map(), folds: [], refined: false }
+    ? { nodes: full.nodes, edges: full.edges, foldedByKey: new Map(), folds: [], grouping: null }
     : projectTodoGanttScope({
       nodes: full.nodes, edges: full.edges, wave: fullWaves.wave, longestChainKeys: longestNodeKeys,
     });
@@ -619,6 +619,16 @@ export function layoutTodoGantt(readModel, chainProjection, options = {}) {
     },
     nodes: projectedNodes,
     edges: projectedEdges,
+    // Every dependency in the plan, before folding contracted any of them away.
+    // The diagram draws `edges`; anything that describes a ToDo in words — the
+    // premises and successors in the right pane — reads this instead, so a
+    // folded ToDo keeps telling the truth about what it depended on.
+    full_edges: full.edges.map((edge) => ({
+      from: { ...full.nodesByKey.get(edge.from).ref },
+      to: { ...full.nodesByKey.get(edge.to).ref },
+      kinds: [...edge.kinds].sort(compareText),
+      join_ids: [...edge.joinIdentities.values()].map(({ join_id }) => join_id).sort(compareText),
+    })),
     connectors: junctionConnectors,
     groups: {
       plans: [...planMap.entries()].map(([plan_key, task_count]) => ({ plan_key, task_count })),
@@ -628,7 +638,7 @@ export function layoutTodoGantt(readModel, chainProjection, options = {}) {
       requested: scope,
       folded_task_count: projected.foldedByKey.size,
       fold_node_count: projected.folds.length,
-      per_wave_refinement: projected.refined,
+      grouping: projected.grouping,
       folds: projected.folds.map((entry) => ({
         ref: { ...entry.ref },
         task_count: entry.task_count,

package/src/todo-gantt-live.mjs

@@ -1,5 +1,7 @@
 import { createServer } from 'node:http';
 
+import { TODO_DASHBOARD_CODE_VERSION } from './todo-dashboard-registry.mjs';
+
 const LOOPBACK = '127.0.0.1';
 const POLL_MS = 500;
 const HTTP_ERROR_SCHEMA = 'lattice.todo_gantt_http_error.v1';
@@ -136,8 +138,12 @@ export async function startTodoGanttDashboardServer({ registry, port = 0, redire
       if (url.pathname === '/__lattice/health') {
         response.writeHead(200, { 'content-type': 'application/json; charset=utf-8',
           'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+        // `version` is the package this process loaded at startup, not the one
+        // installed on disk. That difference is the whole point: it is how a
+        // caller learns the daemon is serving code that has been superseded.
         response.end(`${JSON.stringify({ schema: 'lattice.todo_dashboard_health.v1', pid: process.pid,
-          port: actualPort, project_ids: registry.list().map(({ projectId }) => projectId) })}\n`);
+          port: actualPort, project_ids: registry.list().map(({ projectId }) => projectId),
+          version: TODO_DASHBOARD_CODE_VERSION })}\n`);
         return;
       }
       if (url.pathname === '/' || url.pathname === '/projects/') {

package/src/todo-gantt-scope.mjs

@@ -10,10 +10,16 @@
  * where that projection narrows.
  *
  * The rule is "fold the dead branches": a completed ToDo that no longer leads
- * to any live work is history, and history collapses into one labelled node
- * per finished branch. Completed ToDos that are still the direct premise of
- * live work stay visible, because they are the context for what is dispatchable
- * right now.
+ * to any live work is history, and history collapses into as few labelled nodes
+ * as the graph allows — one per plan when nothing forbids it. Completed ToDos
+ * that are still the direct premise of live work stay visible, because they are
+ * the context for what is dispatchable right now.
+ *
+ * Grouping by connectivity was tried first and does not compress real plans: a
+ * store whose finished ToDos rarely declare dependencies on each other yields
+ * one fold unit per ToDo, which draws the same number of boxes as no folding at
+ * all while hiding every title. History is grouped by the plan it belongs to,
+ * not by whether its members happen to be wired together.
  *
  * This module is pure graph math over the layout's internal node/edge shape.
  * It must run AFTER dependency waves, the longest dependency chain and the
@@ -89,50 +95,59 @@ function foldableKeys(nodes, distance, foldDistance) {
 }
 
 /**
- * Group foldable nodes into fold units.
+ * Grouping strategies, coarsest first. The projection takes the first one whose
+ * contraction stays acyclic.
+ *
+ * - `plan`: one fold unit per plan. All history of a finished plan becomes one
+ *   node. This is the target shape and it is what a reader wants to see.
+ * - `plan_stage`: additionally split per kept-node depth. A cycle can only close
+ *   through a node kept on screen, and that axis is exactly what `keptDepth`
+ *   measures, so this is the smallest refinement that removes the usual cause.
+ * - `plan_wave`: additionally split per dependency wave. Provably acyclic —
+ *   every dependency edge strictly increases the wave, so a contracted edge
+ *   between two units always increases it too and no cycle can exist.
+ */
+const GROUPING_LADDER = Object.freeze(['plan', 'plan_stage', 'plan_wave']);
+
+/**
+ * Number of kept (non-foldable) nodes lying before each node on the longest
+ * path. Crossing a kept node strictly increases it; edges between two foldable
+ * nodes leave it unchanged.
  *
- * `byComponent` groups each weakly connected component of the foldable subgraph
- * into one unit — the compact projection, one node per finished branch.
- * `byComponentAndWave` additionally splits each component per dependency wave.
- * The latter is always acyclic once contracted (every dependency edge strictly
- * increases the wave, so contracted edges do too), which makes it the
- * guaranteed-safe refinement when contraction would otherwise close a cycle.
+ * Edges always increase the wave (`assignWaves` is a longest-path layering), so
+ * visiting nodes in ascending wave order settles every predecessor first.
  */
-function groupFoldable(nodes, edges, foldable, wave, splitByWave) {
-  const parent = new Map([...foldable].map((key) => [key, key]));
-  const find = (key) => {
-    let root = key;
-    while (parent.get(root) !== root) root = parent.get(root);
-    let cursor = key;
-    while (parent.get(cursor) !== root) {
-      const next = parent.get(cursor);
-      parent.set(cursor, root);
-      cursor = next;
+function keptDepth(nodes, edges, foldable, wave) {
+  const incoming = new Map(nodes.map(({ key }) => [key, []]));
+  for (const edge of edges) incoming.get(edge.to).push(edge.from);
+  const depth = new Map();
+  const ordered = [...nodes].sort((left, right) => wave.get(left.key) - wave.get(right.key)
+    || compareText(left.key, right.key));
+  for (const node of ordered) {
+    let best = 0;
+    for (const predecessor of incoming.get(node.key)) {
+      const settled = depth.get(predecessor);
+      if (settled === undefined) continue;
+      const candidate = settled + (foldable.has(predecessor) ? 0 : 1);
+      if (candidate > best) best = candidate;
     }
-    return root;
-  };
-  const union = (left, right) => {
-    const leftRoot = find(left);
-    const rightRoot = find(right);
-    if (leftRoot === rightRoot) return;
-    if (compareText(leftRoot, rightRoot) <= 0) parent.set(rightRoot, leftRoot);
-    else parent.set(leftRoot, rightRoot);
-  };
-  const nodeByKey = new Map(nodes.map((node) => [node.key, node]));
-  for (const edge of edges) {
-    if (!foldable.has(edge.from) || !foldable.has(edge.to)) continue;
-    // A fold unit never spans plans: the diagram groups by plan and a unit that
-    // straddled two plans would have no honest lane to sit in.
-    if (nodeByKey.get(edge.from).ref.plan_key !== nodeByKey.get(edge.to).ref.plan_key) continue;
-    union(edge.from, edge.to);
+    depth.set(node.key, best);
   }
+  return depth;
+}
 
+/** Group foldable nodes into fold units under one of `GROUPING_LADDER`. */
+function groupFoldable(nodes, foldable, strategy, axes) {
+  const nodeByKey = new Map(nodes.map((node) => [node.key, node]));
+  // A fold unit never spans plans: the diagram groups by plan and a unit that
+  // straddled two plans would have no honest lane to sit in.
+  const axisOf = (key) => (strategy === 'plan' ? null
+    : strategy === 'plan_stage' ? axes.stage.get(key)
+      : axes.wave.get(key));
   const unitByNode = new Map();
   const members = new Map();
   for (const key of [...foldable].sort(compareText)) {
-    const unitKey = splitByWave
-      ? JSON.stringify([find(key), wave.get(key)])
-      : JSON.stringify([find(key), null]);
+    const unitKey = JSON.stringify([nodeByKey.get(key).ref.plan_key, axisOf(key)]);
     unitByNode.set(key, unitKey);
     if (!members.has(unitKey)) members.set(unitKey, []);
     members.get(unitKey).push(key);
@@ -249,15 +264,14 @@ function isAcyclic(nodes, edges) {
 /**
  * Project the full dependency graph onto the `live` scope.
  *
- * Contracting a weakly connected component can close a cycle: with a fold
- * distance of 1 the shape `f1 -> s -> f2` is reachable, where `s` is a
- * completed ToDo kept as the direct premise of live work and `f1`/`f2` belong
- * to the same fold unit. Contracting that unit would produce
- * `summary -> s -> summary`. So the contraction is verified, and on a cycle the
- * grouping is refined to (component, wave) — provably acyclic, because every
- * dependency edge strictly increases the wave.
+ * Contraction can close a cycle: with a fold distance of 1 the shape
+ * `f1 -> s -> f2` is reachable, where `s` is a completed ToDo kept as the direct
+ * premise of live work and `f1`/`f2` land in the same fold unit. Contracting
+ * that unit would produce `summary -> s -> summary`. So each candidate grouping
+ * is verified and the coarsest acyclic one wins. The last rung is provably
+ * acyclic, so the throw below is a backstop, never a routine outcome.
  *
- * @returns {{nodes: Array, edges: Array, foldedByKey: Map, folds: Array, refined: boolean}}
+ * @returns {{nodes: Array, edges: Array, foldedByKey: Map, folds: Array, grouping: string}}
  */
 export function projectTodoGanttScope({
   nodes, edges, wave, longestChainKeys = new Set(), foldDistance = DEFAULT_FOLD_DISTANCE,
@@ -265,24 +279,25 @@ export function projectTodoGanttScope({
   const distance = distanceToLive(nodes, edges, wave);
   const foldable = foldableKeys(nodes, distance, foldDistance);
   if (foldable.size === 0) {
-    return { nodes, edges, foldedByKey: new Map(), folds: [], refined: false };
+    return { nodes, edges, foldedByKey: new Map(), folds: [], grouping: null };
   }
 
-  let refined = false;
-  let grouping = groupFoldable(nodes, edges, foldable, wave, false);
-  let summaryByUnit = buildSummaryNodes(nodes, grouping.members, longestChainKeys);
-  let contracted = contract(nodes, edges, grouping.unitByNode, summaryByUnit);
-  if (!isAcyclic(contracted.nodes, contracted.edges)) {
-    refined = true;
-    grouping = groupFoldable(nodes, edges, foldable, wave, true);
-    summaryByUnit = buildSummaryNodes(nodes, grouping.members, longestChainKeys);
-    contracted = contract(nodes, edges, grouping.unitByNode, summaryByUnit);
-    if (!isAcyclic(contracted.nodes, contracted.edges)) {
-      throw new TodoGanttScopeError('TODO_SCOPE_CONTRACTION_CYCLIC',
-        'todo gantt scope contraction produced a cycle after per-wave refinement',
-        { fold_unit_count: grouping.members.size });
-    }
+  const axes = { wave, stage: keptDepth(nodes, edges, foldable, wave) };
+  let selected = null;
+  for (const strategy of GROUPING_LADDER) {
+    const grouping = groupFoldable(nodes, foldable, strategy, axes);
+    const summaryByUnit = buildSummaryNodes(nodes, grouping.members, longestChainKeys);
+    const contracted = contract(nodes, edges, grouping.unitByNode, summaryByUnit);
+    if (!isAcyclic(contracted.nodes, contracted.edges)) continue;
+    selected = { strategy, grouping, summaryByUnit, contracted };
+    break;
   }
+  if (selected === null) {
+    throw new TodoGanttScopeError('TODO_SCOPE_CONTRACTION_CYCLIC',
+      'todo gantt scope contraction produced a cycle under every grouping',
+      { attempted_groupings: [...GROUPING_LADDER] });
+  }
+  const { grouping, summaryByUnit, contracted } = selected;
 
   const foldedByKey = new Map();
   for (const [nodeKey, unitKey] of grouping.unitByNode) {
@@ -292,5 +307,7 @@ export function projectTodoGanttScope({
     .sort((left, right) => compareText(left.key, right.key))
     .map((summary) => ({ ref: { ...summary.ref }, ...summary.fold }));
 
-  return { nodes: contracted.nodes, edges: contracted.edges, foldedByKey, folds, refined };
+  return {
+    nodes: contracted.nodes, edges: contracted.edges, foldedByKey, folds, grouping: selected.strategy,
+  };
 }