@quolu/lattice 0.20.0 → 0.21.0

package/src/seam-verification.mjs

@@ -0,0 +1,201 @@
+/**
+ * 変換の受入判定（ADR 0137 Decision 4・ADR 0138）。
+ *
+ * 五条件をすべて満たしたときだけ採用する。1つでも欠けたら棄却であり、どれが欠けたかを残す。
+ * 「だいたい良さそう」で通す経路を作らない——外部挙動を変えうる変更を、便益の証明なしに
+ * 受け入れないための面である。
+ *
+ * 実行を伴う観測（focused test、再index）は呼び出し側が行い、ここは観測から判定だけを作る。
+ */
+
+import { compileSchedulabilityGraphV2 } from './schedulability-compiler-v2.mjs';
+import { todoSelfDigest } from './todo-contracts.mjs';
+
+const GRAPH_SCHEMA = 'lattice.normalized_boundary_graph.v2';
+const EXPORT_NAMED = /^\s*export\s+(?:async\s+)?(?:function|class|const|let|var)\s+([A-Za-z_$][\w$]*)/u;
+const EXPORT_LIST = /^\s*export\s*\{([^}]*)\}/u;
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const sortedUnique = (values) => [...new Set(values)].sort(compareText);
+
+/**
+ * moduleが外へ出している名前を読む。
+ *
+ * 分割で外部の消費者が影響を受けるかは、原pathの公開面が変わったかで決まる。原pathが
+ * 同じ名前を同じだけ出し続けるなら、原pathをimportしている側は一行も変わらない
+ * （ADR 0137 Decision 3）。
+ */
+export function readExportSurface(text) {
+  if (typeof text !== 'string') return [];
+  const names = [];
+  for (const line of text.split('\n')) {
+    const named = EXPORT_NAMED.exec(line);
+    if (named) { names.push(named[1]); continue; }
+    const list = EXPORT_LIST.exec(line);
+    if (!list) continue;
+    for (const entry of list[1].split(',')) {
+      const parts = entry.split(/\s+as\s+/u).map((part) => part.trim());
+      const name = parts.length > 1 ? parts[1] : parts[0];
+      if (/^[A-Za-z_$][\w$]*$/u.test(name)) names.push(name);
+    }
+  }
+  return sortedUnique(names);
+}
+
+/**
+ * 外部挙動同等性を、原pathの公開面が保たれたかで判定する。
+ *
+ * 名前が欠ければ、その原pathをimportしている外部が壊れる。増えるだけなら既存の消費者は
+ * 影響を受けないので、欠落だけを違反とする。
+ */
+export function compareExportSurface({ before, after } = {}) {
+  const original = readExportSurface(before);
+  const residual = new Set(readExportSurface(after));
+  const missing = original.filter((name) => !residual.has(name));
+  return { preserved: missing.length === 0, missing };
+}
+
+/**
+ * 変換後のwitness setを作る。
+ *
+ * 所有面へ移ったtaskは、その新pathを所有し書き込む。宣言は移動先を指すよう写し、
+ * 中身の意味は変えない——ここで新しい所有を発明すると、判定が実態から外れる。
+ */
+export function buildPostTransformWitnessSet({ witnessSet, candidate, affectedTestsByPath } = {}) {
+  const owned = (candidate?.surfaces ?? []).filter(({ role }) => role === 'task_owned');
+  if (owned.length === 0) return { witnessSet: null, reasons: ['no_owned_surface'] };
+  const next = structuredClone(witnessSet);
+  const reasons = [];
+  for (const [index, surface] of owned.entries()) {
+    const taskId = surface.owner_task_ids[0];
+    const witness = next?.manual_witness?.[taskId];
+    if (witness === undefined) { reasons.push(`witness_missing:${taskId}`); continue; }
+    const affected = affectedTestsByPath?.[surface.path];
+    if (!Array.isArray(affected)) { reasons.push(`affected_tests_missing:${surface.path}`); continue; }
+    witness.owns = [{ kind: 'path', target: surface.path }];
+    witness.writes = [surface.path];
+    witness.affected_tests = sortedUnique(affected);
+    if (Array.isArray(witness.concern_anchors)) {
+      witness.concern_anchors = witness.concern_anchors
+        .filter((entry) => entry.within.target === candidate.source_path)
+        .map((entry) => ({ ...entry, within: { kind: 'path', target: surface.path } }));
+    }
+    // 宣言だけ移して観測の裏付けを旧pathに残すと、宣言と証拠が別の資源を指す。
+    // query setとprovenanceも移動先へ揃える。
+    const queryId = `seam-post-${String(index).padStart(3, '0')}`;
+    witness.sensor_provenance = {
+      queries: [{ query_id: queryId, expect: { kind: 'affected', path: surface.path } }],
+    };
+    if (Array.isArray(next.sensor_query_set?.queries)) {
+      next.sensor_query_set.queries = next.sensor_query_set.queries
+        .filter((query) => query.id !== queryId)
+        .concat([{ id: queryId, operation: 'affected', target: surface.path }]);
+    }
+  }
+  if (reasons.length > 0) return { witnessSet: null, reasons: sortedUnique(reasons) };
+  if (Array.isArray(next.sensor_query_set?.queries)) {
+    next.sensor_query_set.queries.sort((left, right) => compareText(left.id, right.id));
+  }
+  // 宣言を書き換えた以上、自己digestを取り直す。古いまま出すと契約が拒否する。
+  next.witness_set_digest = '';
+  next.witness_set_digest = todoSelfDigest(next, 'witness_set_digest');
+  return { witnessSet: next, reasons: [] };
+}
+
+/**
+ * 競合graphから最小実行段階数を求める。既存のschedulability compilerへ載せる。
+ *
+ * 独自の近似を持たない。変換前後を同じ規則で測らないと、改善したという主張が
+ * 測り方の差で出てしまう。
+ */
+export function measureWaveCount({ taskIds, conflictPairs, executors } = {}) {
+  const todos = sortedUnique(taskIds ?? []);
+  if (todos.length === 0) return { waves: null, reason: 'no_todos' };
+  const seen = new Set();
+  const conflicts = [];
+  for (const pair of conflictPairs ?? []) {
+    const [left, right] = [...pair].sort(compareText);
+    if (left === right || !todos.includes(left) || !todos.includes(right)) continue;
+    const key = `${left}\u0000${right}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    conflicts.push({ todo_ids: [left, right], resource_id: `pair-${conflicts.length}` });
+  }
+  const compiled = compileSchedulabilityGraphV2({
+    schema_version: GRAPH_SCHEMA,
+    todos,
+    conflicts,
+    precedences: [],
+    unknowns: [],
+    capacity: Number.isSafeInteger(executors) && executors >= 1 ? executors : 1,
+  });
+  if (compiled.outcome !== 'compiled') {
+    return { waves: null, reason: compiled.code ?? compiled.outcome };
+  }
+  return { waves: compiled.plan.minimum_feasible_waves, reason: null };
+}
+
+const CONDITIONS = Object.freeze([
+  'behavior_equivalent',
+  'focused_tests_passed',
+  'sensor_fresh',
+  'overlap_reduced',
+  'parallelism_improved',
+]);
+
+/**
+ * 五条件を判定する。1つでも欠けたら`rejected`で、欠けた条件を残す。
+ *
+ * @param {object} options
+ * @param {{preserved: boolean, missing: string[]}} options.exportSurface 公開面の比較
+ * @param {boolean} options.focusedTestsPassed 変換後worktreeでのfocused test結果
+ * @param {boolean} options.sensorFresh 変換後の再indexが新pathを収載したか
+ * @param {{targetResolved: boolean, before: number, after: number}} options.conflictPairs 競合対の増減
+ * @param {{before: number|null, after: number|null}} options.waves 実行段階数の増減
+ */
+export function evaluateSeamVerification(options = {}) {
+  const {
+    exportSurface, focusedTestsPassed, sensorFresh, conflictPairs, waves,
+  } = options;
+  const detail = {};
+  const failures = [];
+
+  detail.behavior_equivalent = exportSurface?.preserved === true;
+  if (!detail.behavior_equivalent) {
+    failures.push(`behavior_equivalent:${(exportSurface?.missing ?? []).join(',') || 'unknown'}`);
+  }
+
+  detail.focused_tests_passed = focusedTestsPassed === true;
+  if (!detail.focused_tests_passed) failures.push('focused_tests_passed');
+
+  detail.sensor_fresh = sensorFresh === true;
+  if (!detail.sensor_fresh) failures.push('sensor_fresh');
+
+  // 対象競合が消えたことと、plan全体の競合対が増えていないことの両方を見る（ADR 0138）。
+  // componentだけを見ると、切った先で作った共有面が別の作業対の係争資源になっても通る。
+  const targetResolved = conflictPairs?.targetResolved === true;
+  const before = conflictPairs?.before;
+  const after = conflictPairs?.after;
+  const counted = Number.isSafeInteger(before) && Number.isSafeInteger(after);
+  detail.overlap_reduced = targetResolved && counted && after <= before;
+  if (!detail.overlap_reduced) {
+    failures.push(!targetResolved ? 'overlap_reduced:target_conflict_remains'
+      : !counted ? 'overlap_reduced:pair_count_unknown'
+        : `overlap_reduced:pairs_increased:${before}->${after}`);
+  }
+
+  // 競合が消えても波数が変わらないなら、その変換は並列化を解放していない。
+  const wavesBefore = waves?.before;
+  const wavesAfter = waves?.after;
+  const measured = Number.isSafeInteger(wavesBefore) && Number.isSafeInteger(wavesAfter);
+  detail.parallelism_improved = measured && wavesAfter < wavesBefore;
+  if (!detail.parallelism_improved) {
+    failures.push(measured ? `parallelism_improved:no_gain:${wavesBefore}->${wavesAfter}`
+      : 'parallelism_improved:waves_unknown');
+  }
+
+  return {
+    decision: failures.length === 0 ? 'accepted' : 'rejected',
+    conditions: Object.fromEntries(CONDITIONS.map((name) => [name, detail[name] === true])),
+    failures: sortedUnique(failures),
+  };
+}

package/src/todo-cli.mjs

@@ -1,7 +1,7 @@
 import { execFileSync } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import {
-  lstat, mkdir, open, readFile, realpath, rename, rm,
+  lstat, mkdir, open, readFile, realpath, rename, rm, writeFile,
 } from 'node:fs/promises';
 import path from 'node:path';
 import { parseTree } from 'jsonc-parser';
@@ -84,6 +84,7 @@ import {
   validateSeamProposalProjection,
 } from './seam-proposal-contracts.mjs';
 import { compileSeamProposalArtifact, declaredConcernSymbols } from './seam-proposal.mjs';
+import { applySeamProposal } from './seam-apply.mjs';
 import {
   parseTodoSourceRef, todoLegacyReconciliationDigest, validatePhaseTodoRevision,
   validateTodoRevision, validateTodoRevisionSet,
@@ -936,6 +937,91 @@ async function seamProposalCompile({ repoRoot, planKey }) {
   return result;
 }
 
+/**
+ * 着地時に使うsurface名。提案が出すhash由来の仮名を、人が読む名前へ置き換える。
+ *
+ * 名前を付けるのは判断なので製品が発明しない（AGENTS.md「装置の境界」）。与えられた名前は
+ * 導出の入力として最初から使う——後から改名すると、生成済みのimport指定子が旧名を指す。
+ */
+async function readSeamPathNames(repoRoot, inputRef) {
+  const value = await readJsonInput(repoRoot, inputRef, {
+    validate: (candidate) => candidate !== null && typeof candidate === 'object'
+      && !Array.isArray(candidate)
+      && candidate.schema === 'lattice.seam_path_names.v1'
+      && typeof candidate.names === 'object' && candidate.names !== null
+      && !Array.isArray(candidate.names)
+      && Object.entries(candidate.names)
+        .every(([key, target]) => isTodoIdentifier(key) && isTodoRef(target)),
+    invalidCode: 'SEAM_PATH_NAMES_INVALID',
+  });
+  return value.names;
+}
+
+/**
+ * 記録済みseam提案を隔離worktreeで適用し、五条件で採否を決める（ADR 0137・0138）。
+ *
+ * 本repositoryは変更しない。採用された変換の着地は別入口が持つ——検証と着地を同じ操作に
+ * すると、五条件を満たさない変換が「途中まで着地した」状態を作りうる。
+ */
+async function seamProposalApply({ repoRoot, planKey, pathNames = {}, land = false }) {
+  const store = await readTodoStore({ repoRoot });
+  const member = store.members.find(({ descriptor }) => descriptor.plan_key === planKey);
+  if (!member) {
+    throw new TodoStoreError('STORE_INCONSISTENT', 'plan_not_active', undefined, { plan_key: planKey });
+  }
+  const artifact = await readTodoSeamProposalArtifact({ repoRoot, store, planKey });
+  if (artifact === null) {
+    throw new TodoStoreError('SEAM_PROPOSAL_COMPILE_UNAVAILABLE', 'seam_proposal_absent', undefined, {
+      plan_key: planKey, next_action: 'compile_seam_proposal',
+    });
+  }
+  const witnessSet = await readTodoWitnessSet({ repoRoot, planKey });
+  if (witnessSet === null) {
+    throw new TodoStoreError('SEAM_PROPOSAL_COMPILE_UNAVAILABLE', 'witness_set_absent', undefined, {
+      plan_key: planKey, next_action: 'declare_witness_set_then_compile_independence',
+    });
+  }
+  const baseArtifact = await readTodoIndependenceArtifact({ repoRoot, store, planKey });
+  const { outcome: result, files } = await applySeamProposal({
+    repoRoot,
+    planKey,
+    pathNames,
+    sourceProposal: artifact,
+    witnessSet,
+    latticeBin: path.join(repoRoot, 'bin', 'lattice.mjs'),
+    sharedPathFor: (sourcePath) => sourcePath.replace(/(\.[^./]+)$/u, '.seam-shared$1'),
+    executors: witnessSet.capacity.executors,
+    compileIndependence: {
+      baseArtifact,
+      // 変換後のworktreeで、写した宣言と再indexした索引から実compileする。
+      // 仮想再compileの再実行では、実ソースで残余0である証拠にならない（ADR 0137 Decision 4）。
+      inWorktree: async ({ worktreePath, witnessSet: postWitness }) => compileTodoIndependence({
+        witnessSet: postWitness,
+        plan: member.plan,
+        baseSha: artifact.source_binding.base_sha,
+        compiledAt: new Date().toISOString(),
+        sensorEvidence: await collectWitnessSensorEvidence({
+          cwd: worktreePath, witnessSet: postWitness,
+        }),
+      }),
+    },
+  });
+  if (!land) return result;
+  // 着地は採用された変換だけへ。検証と着地を同じ操作にしないのは、五条件を満たさない変換が
+  // 途中まで着地した状態を作らないためである（ADR 0137）。
+  if (result.decision !== 'accepted' || files === null) {
+    return { ...result, landed: false, landed_paths: [] };
+  }
+  const landed = [];
+  for (const [target, text] of Object.entries(files)) {
+    const absolute = path.join(repoRoot, target);
+    await mkdir(path.dirname(absolute), { recursive: true });
+    await writeFile(absolute, text);
+    landed.push(target);
+  }
+  return { ...result, landed: true, landed_paths: landed.sort() };
+}
+
 function summarizeSeamProposalDecision(decision) {
   return {
     component_id: decision.component_id,
@@ -1637,6 +1723,18 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     && argv[1] === '--plan' && isTodoIdentifier(argv[2])
   && (argv.length === 3 || argv[3] === '--json')) {
     action = (repoRoot) => independence({ repoRoot, requestedPlanKey: argv[2] });
+  } else if (argv.length === 4 && argv[0] === 'seam-proposal' && argv[1] === 'apply'
+    && argv[2] === '--plan' && isTodoIdentifier(argv[3])) {
+    action = (repoRoot) => seamProposalApply({ repoRoot, planKey: argv[3] });
+  } else if (argv.length === 6 && argv[0] === 'seam-proposal' && argv[1] === 'land'
+    && argv[2] === '--plan' && isTodoIdentifier(argv[3])
+    && argv[4] === '--names' && isTodoRef(argv[5])) {
+    action = async (repoRoot) => seamProposalApply({
+      repoRoot,
+      planKey: argv[3],
+      pathNames: await readSeamPathNames(repoRoot, argv[5]),
+      land: true,
+    });
   } else if (argv.length === 4 && argv[0] === 'seam-proposal' && argv[1] === 'compile'
     && argv[2] === '--plan' && isTodoIdentifier(argv[3])) {
     action = (repoRoot) => seamProposalCompile({ repoRoot, planKey: argv[3] });

package/src/todo-gantt-html-independence.mjs

@@ -0,0 +1,157 @@
+import { DOCUMENT_STATUS, SEVERABILITY_LABEL, escapeHtmlAttribute, escapeHtmlText, foldIndex, planActivity, presentationLookup, refKey, renderPhaseProgress, renderRelationList, renderSeamProposalOverview, renderTaskIndex, statusMarkup, taskReference } from './todo-gantt-html-shared.mjs';
+
+/**
+ * 図の外が語るための独立性要約を、plan単位の投影から引ける形へ畳む（ADR 0129 Decision 3）。
+ */
+export function summarizeIndependence(layout) {
+  if (layout.independence === null) return null;
+  const byPlan = new Map(layout.independence.plans.map((plan) => [plan.plan_key, plan]));
+  return {
+    plans: layout.independence.plans,
+    byPlan,
+    verifiedTaskCount: layout.independence.plans
+      .reduce((total, plan) => total + plan.verified_task_count, 0),
+    unknownTaskCount: layout.independence.plans
+      .reduce((total, plan) => total + plan.unknown_task_ids.length, 0),
+    serializePairCount: layout.independence.plans
+      .reduce((total, plan) => total + plan.serialize_pairs.length, 0),
+  };
+}
+
+/** 記録が無いときだけADR 0063の既定をそのまま述べる。 */
+export function dispatchBasis(summary) {
+  if (summary === null) {
+    return 'ready frontier全件が既定です。一部だけを直列着手する場合は理由が必要です。';
+  }
+  const parts = [`検証済み並列 ${summary.verifiedTaskCount}工程`];
+  if (summary.serializePairCount > 0) parts.push(`要直列 ${summary.serializePairCount}組`);
+  if (summary.unknownTaskCount > 0) parts.push(`未検査 ${summary.unknownTaskCount}工程`);
+  return `${parts.join('、')}。未検査は依存線が無くても並列可の根拠になりません。`;
+}
+
+/** 個別ToDoについて、競合相手と切断可能性を言葉で示す。 */
+export function renderIndependenceNote(ref, node, summary) {
+  if (summary === null || node === undefined) return '';
+  const plan = summary.byPlan.get(ref.plan_key);
+  if (plan === undefined) return '';
+  const taskId = ref.task_id;
+  const state = node.visibility.independence;
+  if (state === null) return '';
+  if (state === 'verified') {
+    return '<p class="readiness-note"><strong>並列可否:</strong> 独立検証済です。記録時点の宣言境界では他のready工程と干渉しません。</p>';
+  }
+  if (state === 'unknown') {
+    return '<p class="readiness-note"><strong>並列可否:</strong> 未検査です。競合が無いのではなく、まだ判定していません。</p>';
+  }
+  const pairs = [
+    ...plan.serialize_pairs
+      .filter((pair) => pair.task_ids.includes(taskId))
+      .map((pair) => ({
+        other: pair.task_ids.find((id) => id !== taskId),
+        severability: pair.severability,
+        detail: pair.detail,
+      })),
+    ...plan.conflicts_with_active
+      .filter((entry) => entry.ready_task_id === taskId)
+      .map((entry) => ({
+        other: `${entry.active_task_id}（作業中）`,
+        severability: entry.severability,
+        detail: entry.detail,
+      })),
+  ];
+  const items = pairs.map((pair) => `<li>${escapeHtmlText(pair.other)} — ${escapeHtmlText(SEVERABILITY_LABEL[pair.severability] ?? pair.severability)}（資源 ${escapeHtmlText(pair.detail)}）</li>`).join('');
+  return `<p class="readiness-note"><strong>並列可否:</strong> 要直列です。</p><ul class="independence-conflicts">${items}</ul>`;
+}
+
+export 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) => {
+    const entries = relations.get(ownerKey);
+    if (entries === undefined) return;
+    let entry = entries.find((candidate) => refKey(candidate.ref) === refKey(ref));
+    if (entry === undefined) {
+      entry = { ref, joinIds: [] };
+      entries.push(entry);
+    }
+    entry.joinIds = [...new Set([...entry.joinIds, ...joinIds])].sort();
+  };
+  // 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);
+  }
+  const counts = { pending: 0, 'in-progress': 0, blocked: 0, done: 0 };
+  for (const section of sections) counts[section.state.status] += 1;
+  const active = sections.filter((section) => section.state.status === 'in-progress');
+  const ready = layout.nodes.filter((node) => node.visibility.next_ready);
+  const independenceSummary = summarizeIndependence(layout);
+  const readyHeadline = ready.length > 1
+    ? `<p class="readiness-note"><strong>同時dispatch推奨:</strong> ${ready.length}工程。${escapeHtmlText(dispatchBasis(independenceSummary))}</p>`
+    : ready.length === 1
+      ? '<p class="readiness-note"><strong>着手候補:</strong> 1工程です。</p>'
+      : '<p class="readiness-note">現在のready frontierは空です。</p>';
+  // ready件数によらず、記録があるなら内訳を述べる。1件の時だけ黙ると、
+  // その1件が未検査でも「候補が1つある」としか伝わらない。
+  const independenceNote = independenceSummary === null || ready.length > 1 ? ''
+    : `<p class="readiness-note"><strong>並列可否:</strong> ${escapeHtmlText(dispatchBasis(independenceSummary))}</p>`;
+  const dispatchSummary = `${readyHeadline}${independenceNote}`;
+  const activeLinks = active.length === 0 ? '<p>作業中の工程はありません。</p>'
+    : `<ul class="active-list">${active.map((section) => `<li><button type="button" data-select-node-key="${escapeHtmlAttribute(refKey(section.ref))}">${escapeHtmlText(taskReference(section, lookup))} — ${escapeHtmlText(section.task.title)}</button></li>`).join('')}</ul>`;
+  const overview = `<section class="right-overview" data-right-panel="overview"><h1>工程を選択してください</h1><p>左の依存工程図から工程を選ぶと、題名・状態・前提・後続を表示します。</p><div class="status-summary"><span>☐ 未着手 ${counts.pending}</span><span>▶ 作業中 ${counts['in-progress']}</span><span>✅ 完了 ${counts.done}</span><span>⛔ ブロック中 ${counts.blocked}</span></div>${dispatchSummary}${renderSeamProposalOverview(layout)}${renderPhaseProgress(readModel)}<h2>作業中</h2>${activeLinks}</section>`;
+  const details = sections.map((section) => {
+    const key = refKey(section.ref);
+    const node = nodeByKey.get(key);
+    const status = DOCUMENT_STATUS[section.state.status] ?? { mark: '?', label: '状態不明' };
+    const lane = lookup.lanes.get(JSON.stringify([section.ref.plan_key, section.task.lane]));
+    const category = lane === undefined ? section.task.lane : `${section.task.lane} — ${lane.name}`;
+    const categoryDescription = lane === undefined ? '' : `<p class="category-description">${escapeHtmlText(lane.description)}</p>`;
+    const blockedReason = section.state.status === 'blocked'
+      ? `<p><strong>ブロック理由:</strong> ${escapeHtmlText(section.state.blocked_reason ?? '理由未記録')}</p>` : '';
+    const sourceLine = section.anchorOutcome.origin_line === null ? '' : `:${section.anchorOutcome.origin_line}`;
+    const sourceRef = section.narrativeRef ?? '参照なし';
+    const anchorText = section.anchorOutcome.anchored
+      ? `元plan: ${sourceRef}${sourceLine} — 行対応を確認済み`
+      : `元plan: ${sourceRef}${sourceLine} — 行対応を確認できないため、本文位置との対応は表示していません`;
+    const readiness = node?.visibility.next_ready
+      ? `<p class="readiness-note">ready frontierの一員です。${ready.length > 1 ? '他のready工程と同時着手できるかは下の並列可否で判断してください。' : '現在の唯一の着手候補です。'}</p>`
+      : incoming.get(key).length === 0 ? '<p class="readiness-note">登録済みの前提工程はありません。図だけではdispatch可否を判定しません。</p>' : '';
+    const independenceNote = renderIndependenceNote(section.ref, node, independenceSummary);
+    // Say it plainly when the reader will not find this ToDo on the diagram.
+    const foldedNote = !folds.has(key) ? ''
+      : '<p class="fold-note">完走済みのため図には描いていません。図に出すには <code>lattice todo gantt --scope all</code> を実行してください。</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}${independenceNote}${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, folds, planActivity(readModel));
+  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>全工程一覧</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に登録された全工程を現在の状態とともに表示しています。planは動いているものを最終活動の新しい順で上に、完走したものを古い順で下にまとめ、plan内は登録順です。</p>${taskIndex}</section></div>`;
+}
+
+export function renderDiagramLegend(presentation, layout = null, expandable = false) {
+  const categories = (presentation?.lanes ?? []).map((lane) => `<div class="category-entry"><dt><code>${escapeHtmlText(lane.lane)}</code> — ${escapeHtmlText(lane.name)}</dt><dd>${escapeHtmlText(lane.description)}</dd></div>`).join('');
+  const categoryDetails = categories === '' ? '' : `<details class="category-legend"><summary>カテゴリ説明</summary><dl>${categories}</dl></details>`;
+  const foldedCount = layout?.scope?.folded_task_count ?? 0;
+  // The badge says what is missing from the diagram, so it is also the control
+  // that brings it back — a reader who notices the count is exactly the reader
+  // who wants to see it.
+  const foldChip = foldedCount === 0 ? ''
+    : expandable
+      ? `<button type="button" class="fold-chip" data-toggle-expanded aria-expanded="false"><span data-toggle-label data-collapsed-label="完走済み ${foldedCount}件を非表示（押すと表示）" data-expanded-label="完走済み ${foldedCount}件を表示中（押すと非表示）">完走済み ${foldedCount}件を非表示（押すと表示）</span></button>`
+      : `<span class="fold-chip">完走済み ${foldedCount}件を非表示</span>`;
+  const foldNote = foldedCount === 0 ? ''
+    : expandable
+      ? '<p class="fold-note">後続に作業中・未着手が残っていない完了工程は図から外しています。生きた工程とその直接の前提工程は必ず描きます。上のバッジを押すと外した工程も含めて描きます。総数・進捗・最長依存鎖は外す前の全工程で数えています。</p>'
+      : '<p class="fold-note">後続に作業中・未着手が残っていない完了工程は図から外しています。生きた工程とその直接の前提工程は必ず描きます。外した工程は右の「全工程」から辿れ、図に出すには <code>lattice todo gantt --scope all</code> を実行してください。総数・進捗・最長依存鎖は外す前の全工程で数えています。</p>';
+  const independenceLegend = layout.independence === null ? ''
+    : '<span>∥ 独立検証済</span><span>⛓ 要直列</span><span>? 未検査</span>';
+  // 独立性の記録がある間は「全件同時dispatchが既定」と無条件に述べない（ADR 0129 Decision 3）。
+  const dispatchSentence = layout.independence === null
+    ? 'ready frontierは全件同時dispatchが既定です。未登録の資源・host制約によりsubsetだけを選ぶ場合は理由を記録します。'
+    : '同時着手できるかはカードの並列可否で判断してください。未検査の工程は依存線が無くても並列可の根拠になりません。';
+  return `<div class="diagram-legend" aria-label="工程図の凡例"><span>${statusMarkup('pending', ' 未着手')}</span><span>${statusMarkup('in-progress', ' 作業中')}</span><span>${statusMarkup('done', ' 完了')}</span><span>${statusMarkup('blocked', ' ブロック中')}</span><span>破線枠: ready frontier</span>${independenceLegend}<span>太線: 構造上の最長依存鎖</span><span>半円: 非接触の線交差</span><span>黒丸: 論理上の合流</span>${foldChip}${categoryDetails}${foldNote}<p>縦方向は時間ではなく、登録済み依存関係による工程段階です。${dispatchSentence}構造上の最長依存鎖は各工程を同じ重みとして数え、実時間・工数・納期を表しません。</p></div>`;
+}