@quolu/lattice 0.34.2 → 0.36.0

package/src/todo-cli.mjs

@@ -37,6 +37,8 @@ import {
   applyTodoRevisionSet,
   createTodoStoreWriter,
   TodoStoreError,
+  isPhaselessTodoPlanSchema,
+  TERMINAL_AUDIT_PHASE_ID,
   readTodoIndependenceArtifact,
   readTodoSeamProposalArtifact,
   readTodoStore,
@@ -52,8 +54,13 @@ import {
 } from './todo-store.mjs';
 import {
   appendTodoExtraction,
+  explainTodoExtraction,
   validateTodoExtraction,
 } from './todo-migration.mjs';
+import {
+  assertTodoDispatchShapeReviewed,
+  computeTodoDispatchShapeForPlan,
+} from './todo-dispatch-shape.mjs';
 import {
   computeReadyFrontier,
   projectTodoBindings,
@@ -93,6 +100,7 @@ import {
   validateWitnessDraft,
 } from './witness-scaffold.mjs';
 import {
+  explainPhaseTodoRevision, explainTodoRevision, explainTodoRevisionSet,
   parseTodoSourceRef, todoLegacyReconciliationDigest, validatePhaseTodoRevision,
   validateTodoRevision, validateTodoRevisionSet,
 } from './todo-revision.mjs';
@@ -109,6 +117,31 @@ const ACTOR_ENV_KEYS = Object.freeze([
   'LATTICE_TODO_ACTOR_AGENT',
 ]);
 
+/**
+ * `revise` / `revise-set` / `revise-phase` / `migrate`が実際に受理する最新契約のJSON
+ * Schemaを配布物から読む入口（`project-cli.mjs`の`runPlanCreateSchema`と同じ作法）。
+ *
+ * schemaを取る手段がCLIに無いと、AIはsrcを読んで必須keyを数えるしかなくなる
+ * （実運用で`phase_todo_revision.v3`の必須12 keyを試行錯誤で当てた）。storeは読まない
+ * ——`plan create --schema`と同じく決定的な出力・exit 0にする。
+ */
+const TODO_SCHEMA_COMMANDS = Object.freeze({
+  revise: { title: 'lattice.todo_revision.v2', file: 'lattice.todo_revision.v2.schema.json' },
+  'revise-set': { title: 'lattice.todo_revision_set.v3', file: 'lattice.todo_revision_set.v3.schema.json' },
+  'revise-phase': {
+    title: 'lattice.phase_todo_revision.v3', file: 'lattice.phase_todo_revision.v3.schema.json',
+  },
+  migrate: { title: 'lattice.todo_extraction.v2', file: 'lattice.todo_extraction.v2.schema.json' },
+});
+
+async function runTodoSchemaCommand(command, stdout) {
+  const spec = TODO_SCHEMA_COMMANDS[command];
+  const schemaUrl = new URL(`../docs/schemas/${spec.file}`, import.meta.url);
+  const schema = JSON.parse(await readFile(schemaUrl, 'utf8'));
+  if (schema?.title !== spec.title) throw new TypeError(`bundled ${command} schema invalid`);
+  stdout.write(`${JSON.stringify(schema)}\n`);
+}
+
 function usageFailure(stderr, argv) {
   const received = argv.length === 0 ? '(none)' : argv.join(' ').replace(/[\r\n]/gu, ' ');
   stderr.write(`lattice todo: unsupported command or arguments: ${received}\n`);
@@ -219,7 +252,11 @@ async function readMigrationInput(repoRoot, inputRef) {
     throw new TodoStoreError('INVALID_JSON', 'json_parse_failed');
   }
   if (!validateTodoExtraction(extraction)) {
-    throw new TodoStoreError('INVALID_TODO_EXTRACTION', 'schema_invalid');
+    // 「schema_invalid」だけでは何のfieldがどう壊れているか分からない（ADR 0130の案内規律）。
+    // explainは可否判定を変えず、診断だけを追加する。
+    const explained = explainTodoExtraction(extraction);
+    throw new TodoStoreError('INVALID_TODO_EXTRACTION', 'schema_invalid', undefined,
+      explained.valid ? undefined : { violation_reason: explained.reason, violation_path: explained.path });
   }
   return extraction;
 }
@@ -228,6 +265,7 @@ async function readRevisionInput(repoRoot, inputRef, {
   validate = validateTodoRevision,
   invalidCode = 'REVISION_INVALID',
   invalidReason = 'revision_schema_or_digest_invalid',
+  explain = explainTodoRevision,
 } = {}) {
   const canonicalRoot = await realpath(repoRoot);
   const absolute = path.resolve(canonicalRoot, inputRef);
@@ -264,7 +302,16 @@ async function readRevisionInput(repoRoot, inputRef, {
   try { revision = JSON.parse(text.slice(0, -1)); } catch {
     throw new TodoStoreError('INVALID_JSON', 'json_parse_failed');
   }
-  if (!validate(revision)) throw new TodoStoreError(invalidCode, invalidReason);
+  if (!validate(revision)) {
+    // 「schema_or_digest_invalid」だけでは何のfieldがどう壊れているか分からない
+    // （ADR 0130の案内規律）。explainは可否判定を変えず、診断だけを追加する。
+    // 呼び出し元がexplainを渡さない（phase decision入力等）場合はdetail無しのまま。
+    const explained = explain === null ? null : explain(revision);
+    throw new TodoStoreError(invalidCode, invalidReason, undefined,
+      explained === null || explained.valid ? undefined : {
+        violation_reason: explained.reason, violation_path: explained.path,
+      });
+  }
   if (text !== `${canonicalizeTodoArtifact(revision)}\n`) {
     throw new TodoStoreError(invalidCode, 'non_canonical_revision_bytes');
   }
@@ -369,6 +416,25 @@ function mutationActor(env) {
   return { host: entries[0].value, session: entries[1].value, agent: entries[2].value };
 }
 
+/**
+ * phase無しplanで、この変異の結果terminal-audit Phaseがgate_ready(全task done・未監査)に
+ * なっていれば助言を返す(ADR 0147)。doneの結果だけを見て機械的に判定するので、既にreview
+ * まで進んでいれば`gate_ready`ではなくなり、二重に案内しない。phase付きplanや、まだ
+ * pending taskが残っているplanではterminal-audit Phase自体が無い/gate_readyでないので、
+ * このヘルパはnullを返し既存の`advisory: null`の挙動を変えない。
+ */
+function terminalAuditDoneAdvisory(plan, phases) {
+  if (!isPhaselessTodoPlanSchema(plan.schema)) return null;
+  const phase = phases.find(({ phase_id }) => phase_id === TERMINAL_AUDIT_PHASE_ID);
+  if (phase?.status !== 'gate_ready') return null;
+  return {
+    terminal_audit_required: true, phase_id: TERMINAL_AUDIT_PHASE_ID, status: phase.status,
+    guidance: '全taskがdoneになった。このplanはphaseを持たないため、終端の重監査'
+      + '(todo phase review --plan <key> --phase terminal-audit → todo phase accept)を'
+      + '経るまで「閉じた」ことにはならない。',
+  };
+}
+
 async function mutate({
   repoRoot, env, planKey, taskId, kind, payload, evidenceRef, advisory = null,
 }) {
@@ -379,13 +445,18 @@ async function mutate({
   if (kind === 'done' && payload === 'evidence_promotion') {
     eventPayload = { done_mode: 'evidence_promotion', imported: true, evidence };
   }
-  const { event, snapshot } = await appendTodoEvent({
+  const { event, snapshot, plan, phases } = await appendTodoEvent({
     repoRoot,
     writer: createTodoStoreWriter({ caller: 'g5-authoring' }),
     planKey,
     event: { kind, task_id: taskId, actor, payload: eventPayload },
   });
   const task = snapshot.tasks.find(({ task_id: current }) => current === event.task_id);
+  // advisoryは呼び出し側(startTask)がstart用に既に組んでいればそれを尊重し、無ければ
+  // done時だけ終端監査の要否を調べる。block/unblock/reopenはnullのまま(既存挙動を変えない)。
+  // Phase状態はsnapshot(v1にはphasesキーが無い)でなく、appendTodoEventが別途返す
+  // 導出ビュー`phases`から読む。
+  const resolvedAdvisory = advisory ?? (kind === 'done' ? terminalAuditDoneAdvisory(plan, phases) : null);
   const result = {
     schema: 'lattice.todo_mutation_result.v2',
     project_id: event.project_id,
@@ -398,7 +469,7 @@ async function mutate({
     journal_head_digest: event.event_digest,
     snapshot_digest: snapshot.snapshot_digest,
     status: task.status,
-    advisory,
+    advisory: resolvedAdvisory,
     result_digest: '',
   };
   result.result_digest = todoSelfDigest(result, 'result_digest');
@@ -477,7 +548,32 @@ async function startAdvisory({ repoRoot, store, projection, planKey, taskId }) {
   };
 }
 
-async function startTask({ repoRoot, env, planKey, taskId, overrideReason, parallelFrontier }) {
+// 直列化の理由として認めない定型句。
+// worker数・セッション構成・作業者の都合は「並列にできない根拠」ではない。
+// 根拠になるのは実際の干渉だけ（同一fileへの書込衝突・外部資源の排他・順序依存）。
+// 単一プロセスのagentが「自分は1人だから」と直列へ逃げる事例が実運用で出たため、
+// frontierの既定（all_ready_parallel_by_default）を宣言だけでなく機構で守る。
+const SERIAL_NON_REASONS = [
+  /単一(?:の)?(?:セッション|エージェント|worker|ワーカー|プロセス|スレッド)/u,
+  /(?:逐次|順次|直列|シリアル)(?:実行|処理|化|に|で)/u,
+  /(?:一人|1人|ひとり|1名|単独)(?:で|の|しか)/u,
+  /(?:サブ)?エージェント(?:が|は)?(?:居ない|いない|使わない|使えない)/u,
+  /single[-\s]?(?:session|agent|worker|process|thread)/iu,
+  /\b(?:sequential|serial)(?:ly)?\s*(?:execution|processing|run|dispatch)?\b/iu,
+  /one[-\s]at[-\s]a[-\s]time|\bsolo\b|\bby myself\b/iu,
+];
+
+/**
+ * 直列化理由が「実際の干渉」を述べているかを検査する。
+ * worker数・セッション構成を述べただけの理由は根拠にならないので拒否する。
+ */
+function serialReasonNonInterference(reason) {
+  return SERIAL_NON_REASONS.find((pattern) => pattern.test(reason)) ?? null;
+}
+
+async function startTask({
+  repoRoot, env, planKey, taskId, overrideReason, parallelFrontier, serialConfirmed = false,
+}) {
   const store = await readTodoStore({ repoRoot });
   const projection = projectTodoStatus(store);
   const readyTask = projection.next_ready.find((task) => (
@@ -487,16 +583,60 @@ async function startTask({ repoRoot, env, planKey, taskId, overrideReason, paral
   if (parallelFrontier && !targetReady) {
     throw new TodoStoreError('PARALLEL_DISPATCH_INVALID', 'parallel_frontier_not_applicable');
   }
-  if (targetReady && projection.active_set.length === 0 && projection.next_ready.length > 1
-    && overrideReason === null && !parallelFrontier) {
+  const frontierContested = targetReady && projection.active_set.length === 0
+    && projection.next_ready.length > 1;
+  if (frontierContested && overrideReason === null && !parallelFrontier) {
     throw new TodoStoreError('PARALLEL_DISPATCH_REQUIRED', 'parallel_frontier_requires_declaration',
       undefined, {
         ready_count: projection.next_ready.length,
+        ready_task_ids: projection.next_ready.map((task) => task.task_id),
         frontier_digest: projection.dispatch_frontier.frontier_digest,
         parallel_start_flag: projection.dispatch_frontier.parallel_start_flag,
         serial_reason_flag: '--override-reason',
+        default_policy: projection.dispatch_frontier.policy,
+        guidance: '既定は全ready分の同時dispatch。並列で始めるなら --parallel-frontier を使う。'
+          + '--override-reason は「なぜ並列にできないか」を書く欄であり、'
+          + 'worker数・セッション構成・作業者の都合は根拠にならない'
+          + '（同一fileへの書込衝突・外部資源の排他・順序依存だけが根拠になる）。',
       });
   }
+  if (frontierContested && overrideReason !== null) {
+    if (serialReasonNonInterference(overrideReason) !== null) {
+      throw new TodoStoreError('PARALLEL_DISPATCH_INVALID', 'serial_reason_is_not_an_interference',
+        undefined, {
+          ready_count: projection.next_ready.length,
+          ready_task_ids: projection.next_ready.map((task) => task.task_id),
+          rejected_reason: overrideReason,
+          default_policy: projection.dispatch_frontier.policy,
+          parallel_start_flag: projection.dispatch_frontier.parallel_start_flag,
+          guidance: 'worker数・セッション構成・作業者の都合は直列化の根拠にならない。'
+            + 'readyが複数あるなら既定は同時dispatchであり、実行主体が1つしか無いことは'
+            + '並列にできない理由ではない（必要ならworkerを増やす）。'
+            + '直列にするなら、並列で走らせたときに実際に起きる干渉'
+            + '（同一fileへの書込衝突・外部資源の排他・順序依存）を書く。',
+        });
+    }
+    // 直列の申告は一度突き返して並列を再検討させる。
+    // 規則を書くだけでは読み飛ばされるため、再考をコマンドの往復で強制する。
+    if (!serialConfirmed) {
+      throw new TodoStoreError('PARALLEL_DISPATCH_RECONSIDER', 'consider_parallel_before_serial',
+        undefined, {
+          ready_count: projection.next_ready.length,
+          ready_task_ids: projection.next_ready.map((task) => task.task_id),
+          declared_reason: overrideReason,
+          default_policy: projection.dispatch_frontier.policy,
+          parallel_start_flag: projection.dispatch_frontier.parallel_start_flag,
+          serial_confirm_flag: '--serial-confirmed',
+          guidance: `並列を検討しなさい。ready ${projection.next_ready.length} 件は同時に着手できる`
+            + '前提で並んでおり、既定は全件同時dispatchである。'
+            + `まず ${projection.dispatch_frontier.parallel_start_flag} で全readyを起こし、`
+            + 'それぞれ別のworkerへ渡すことを検討する'
+            + '（実行主体が足りないなら増やす。増やせないことは並列にできない理由ではない）。'
+            + '検討した上でなお直列にするなら、同じ --override-reason に'
+            + ' --serial-confirmed を付けて再実行する。',
+        });
+    }
+  }
   const resolvedTaskId = readyTask?.task_id ?? taskId;
   // 助言はjournalへ書く前に確定させる。計算できないならstart自体を止める。
   const advisory = await startAdvisory({
@@ -526,6 +666,8 @@ async function phaseDecision({ repoRoot, env, planKey, phaseId, outcome, inputRe
   const input = await readRevisionInput(repoRoot, inputRef, {
     validate: (value) => validatePhaseDecisionInput(value, outcome),
     invalidCode: 'PHASE_DECISION_INVALID', invalidReason: 'phase_decision_schema_or_digest_invalid',
+    // phase decision入力はrevision契約と別形状。既定のrevision explainを誤って当てない。
+    explain: null,
   });
   const payload = outcome === 'accept'
     ? { review_event_digest: input.review_event_digest, decision_evidence: input.decision_evidence,
@@ -536,11 +678,13 @@ async function phaseDecision({ repoRoot, env, planKey, phaseId, outcome, inputRe
 }
 
 async function phaseMutation({ repoRoot, env, planKey, phaseId, kind, payload }) {
-  const { event, snapshot } = await appendTodoEvent({
+  const { event, snapshot, phases } = await appendTodoEvent({
     repoRoot, writer: createTodoStoreWriter({ caller: 'g5-authoring' }), planKey,
     event: { kind, phase_id: phaseId, actor: mutationActor(env), payload },
   });
-  const phase = snapshot.phases?.find(({ phase_id: current }) => current === phaseId);
+  // snapshot.phasesはv1(phase無しplan)には存在しない。導出ビュー`phases`を見る
+  // (これは暗黙のterminal-audit Phaseにも常に埋まっている)。
+  const phase = phases.find(({ phase_id: current }) => current === phaseId);
   if (phase === undefined) throw new TodoStoreError('STORE_INCONSISTENT', 'phase_not_active');
   const result = {
     schema: 'lattice.phase_mutation_result.v1', project_id: event.project_id,
@@ -556,23 +700,49 @@ async function phaseMutation({ repoRoot, env, planKey, phaseId, kind, payload })
 async function phaseStatus({ repoRoot, planKey }) {
   const store = await readTodoStore({ repoRoot });
   const [member] = selectMembers(store, planKey);
-  if (!['lattice.todo_plan.v4', 'lattice.todo_plan.v5'].includes(member.plan.schema)) {
-    throw new TodoStoreError('PHASE_UNAVAILABLE', 'plan_has_no_phase_contract');
-  }
+  // ADR 0147以降、phase無しplan(v1/v2/v3)もreadTodoStoreが導出済みの暗黙terminal-audit
+  // Phaseをmember.phasesへ積んでいる(snapshot artifactの形式は変えない・v1にはphasesキーが
+  // 無いのでsnapshot.phasesは直接読まない)。ここでPHASE_UNAVAILABLEへ拒否せず、その暗黙Phase
+  // をそのまま返す——`implicit`で機械可読に「宣言されたPhaseではない」ことを示す。
+  const implicit = isPhaselessTodoPlanSchema(member.plan.schema);
   const result = {
     schema: 'lattice.phase_status_result.v1', project_id: store.project_id,
     plan_key: member.plan.plan_key, plan_version: member.plan.plan_version,
     journal_head_digest: member.journal.events.at(-1).event_digest,
-    phases: member.snapshot.phases, result_digest: '',
+    implicit, phases: member.phases, result_digest: '',
   };
   result.result_digest = todoSelfDigest(result, 'result_digest');
   return result;
 }
 
-async function migrate({ repoRoot, inputRef }) {
+async function migrate({ repoRoot, inputRef, serializationReviewed = false }) {
   const extraction = await readMigrationInput(repoRoot, inputRef);
-  const imported = await appendTodoExtraction({ repoRoot, extraction });
+  // dispatch_shapeのgateはappendTodoExtraction（store書込み）より前に判定する必要がある
+  // （拒否時にstoreへ何も書かないため、再考後の再実行がplan_key_already_existsで
+  // 詰まらない）。unresolved/空集合の2つの早期gateは、compileTodoExtraction内部の
+  // 同名gateをここでも先に通しておくことで、既存のエラー優先順位
+  // （unresolved・空集合を直列度より先に報告する）を変えない。
+  const unresolvedTaskIds = extraction.tasks
+    .filter(({ disposition }) => disposition === 'unknown_requires_evidence')
+    .map(({ task_id: taskId }) => taskId);
+  if (unresolvedTaskIds.length > 0) {
+    throw new TodoStoreError('MIGRATION_UNRESOLVED', 'unknown_requires_evidence', undefined, {
+      task_ids: unresolvedTaskIds,
+    });
+  }
   const registered = extraction.tasks.filter(({ disposition }) => disposition.startsWith('register_'));
+  if (registered.length === 0) throw new TodoStoreError('MIGRATION_EMPTY', 'no_registered_tasks');
+
+  const dispatchShape = computeTodoDispatchShapeForPlan({
+    projectId: extraction.project_id,
+    planKey: extraction.plan_key,
+    taskIds: registered.map(({ task_id: taskId }) => taskId),
+    hardDependencies: extraction.hard_dependencies,
+    joins: extraction.joins,
+  });
+  assertTodoDispatchShapeReviewed({ shape: dispatchShape, reviewed: serializationReviewed });
+
+  const imported = await appendTodoExtraction({ repoRoot, extraction });
   const result = {
     schema: 'lattice.todo_migrate_result.v1',
     project_id: imported.plan.project_id,
@@ -586,6 +756,16 @@ async function migrate({ repoRoot, inputRef }) {
     snapshot_ref: imported.descriptor.snapshot_ref,
     topology_digest: imported.plan.topology_digest,
     journal_head_digest: imported.events.at(-1).event_digest,
+    dispatch_shape: {
+      task_count: dispatchShape.task_count,
+      critical_path_length: dispatchShape.critical_path_length,
+      max_frontier_width: dispatchShape.max_frontier_width,
+      serialization_ratio: dispatchShape.serialization_ratio,
+    },
+    // ADR 0147裁定3: phase無しplanの作成は拒否せず、終端監査が要ることを結果へ明示するに
+    // 留める。extraction経由のmigrateは常にphase無しplan(todo_plan.v2)を作るが、将来の
+    // 拡張に備えisPhaselessTodoPlanSchemaで動的に判定する。
+    terminal_audit_required: isPhaselessTodoPlanSchema(imported.plan.schema),
     result_digest: '',
   };
   result.result_digest = todoSelfDigest(result, 'result_digest');
@@ -608,6 +788,7 @@ async function reviseSet({ repoRoot, env, inputRef }) {
     validate: validateTodoRevisionSet,
     invalidCode: 'REVISION_SET_INVALID',
     invalidReason: 'revision_set_schema_invalid',
+    explain: explainTodoRevisionSet,
   });
   return applyTodoRevisionSet({
     repoRoot, writer: createTodoStoreWriter({ caller: 'g5-authoring' }), revisionSet,
@@ -619,6 +800,7 @@ async function revisePhase({ repoRoot, env, planKey, inputRef }) {
   const revision = await readRevisionInput(repoRoot, inputRef, {
     validate: validatePhaseTodoRevision, invalidCode: 'REVISION_INVALID',
     invalidReason: 'phase_revision_schema_or_digest_invalid',
+    explain: explainPhaseTodoRevision,
   });
   if (revision.plan_key !== planKey) throw new TodoStoreError('REVISION_INVALID', 'requested_plan_mismatch');
   return applyPhaseTodoRevision({ repoRoot, writer: createTodoStoreWriter({ caller: 'g5-authoring' }),
@@ -1819,6 +2001,20 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     throw new TypeError('runTodoCli optionsが不正');
   }
 
+  // `--schema --json`はstoreを読まない決定的な出力（`plan create --schema`と同じ規律）。
+  // 通常dispatchより前に処理し、repoRoot解決やdashboard daemon起動を経由させない。
+  if (argv.length === 3 && argv[1] === '--schema' && argv[2] === '--json'
+    && Object.hasOwn(TODO_SCHEMA_COMMANDS, argv[0])) {
+    try {
+      await runTodoSchemaCommand(argv[0], stdout);
+      return 0;
+    } catch (error) {
+      return typedFailure(stderr, {
+        code: 'INTERNAL_FAILURE', message: error?.constructor?.name ?? 'Error',
+      });
+    }
+  }
+
   let action = null;
   if ((argv.length === 1 && argv[0] === 'status')
     || (argv.length === 2 && argv[0] === 'status' && argv[1] === '--json')) {
@@ -1913,9 +2109,11 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     action = (repoRoot) => serveGantt({
       repoRoot, port: Number(argv[3]), stdout, env, scope: argv[5],
     });
-  } else if (argv.length === 3 && argv[0] === 'migrate' && argv[1] === '--input'
-    && isTodoRef(argv[2])) {
-    action = (repoRoot) => migrate({ repoRoot, inputRef: argv[2] });
+  } else if ((argv.length === 3 || argv.length === 4) && argv[0] === 'migrate' && argv[1] === '--input'
+    && isTodoRef(argv[2]) && (argv.length === 3 || argv[3] === '--serialization-reviewed')) {
+    action = (repoRoot) => migrate({
+      repoRoot, inputRef: argv[2], serializationReviewed: argv.length === 4,
+    });
   } else if (argv.length === 5 && argv[0] === 'revise'
     && argv[1] === '--plan' && isTodoIdentifier(argv[2])
     && argv[3] === '--input' && isTodoRef(argv[4])) {
@@ -1950,14 +2148,18 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     && (argv.length === 8 || (argv[8] === '--override-reason' && argv[9].length > 0))) {
     action = (repoRoot) => phaseMutation({ repoRoot, env, planKey: argv[3], phaseId: argv[5],
       kind: 'phase_reopen', payload: { reason: argv[7], override_reason: argv[9] ?? null } });
-  } else if ((argv.length === 5 || argv.length === 6 || argv.length === 7) && argv[0] === 'start'
+  } else if ((argv.length === 5 || argv.length === 6 || argv.length === 7 || argv.length === 8)
+    && argv[0] === 'start'
     && argv[1] === '--plan' && isTodoIdentifier(argv[2])
     && argv[3] === '--task' && isTodoIdentifier(argv[4])
     && (argv.length === 5 || (argv.length === 6 && argv[5] === '--parallel-frontier')
-      || (argv.length === 7 && argv[5] === '--override-reason' && argv[6].length > 0))) {
-    const overrideReason = argv.length === 7 ? argv[6] : null;
+      || ((argv.length === 7 || argv.length === 8)
+        && argv[5] === '--override-reason' && argv[6].length > 0
+        && (argv.length === 7 || argv[7] === '--serial-confirmed')))) {
+    const overrideReason = argv.length >= 7 ? argv[6] : null;
     action = (repoRoot) => startTask({ repoRoot, env, planKey: argv[2], taskId: argv[4],
-      overrideReason, parallelFrontier: argv.length === 6 });
+      overrideReason, parallelFrontier: argv.length === 6,
+      serialConfirmed: argv.length === 8 });
   } else if (argv.length === 7 && argv[0] === 'block'
     && argv[1] === '--plan' && isTodoIdentifier(argv[2])
     && argv[3] === '--task' && isTodoIdentifier(argv[4])

package/src/todo-contracts.mjs

@@ -375,8 +375,8 @@ function validStateMigration(value) {
       'from_task_id', 'to_task_id', 'state_policy', 'state',
     ]) && isTodoIdentifier(entry.from_task_id)
       && (entry.to_task_id === 'removed' || isTodoIdentifier(entry.to_task_id))
-      && ['carry', 'carry_reconciled_metadata', 'reset_pending', 'removed'].includes(entry.state_policy)
-      && ((['carry', 'carry_reconciled_metadata'].includes(entry.state_policy)
+      && ['carry', 'carry_reconciled_metadata', 'reset_pending', 'removed', 'acquire_phase'].includes(entry.state_policy)
+      && ((['carry', 'carry_reconciled_metadata', 'acquire_phase'].includes(entry.state_policy)
         && entry.to_task_id !== 'removed' && validCarriedState(entry.state))
         || (entry.state_policy === 'reset_pending' && entry.to_task_id !== 'removed' && entry.state === null)
         || (entry.state_policy === 'removed' && entry.to_task_id === 'removed' && entry.state === null)))

package/src/todo-dispatch-shape.mjs

@@ -0,0 +1,190 @@
+import { TodoStoreError } from './todo-store.mjs';
+
+/**
+ * 依存グラフの「直列度」を判定する既定閾値。
+ *
+ * `serialization_ratio = critical_path_length / task_count` がこれを超えると、
+ * 依存連鎖が全task数の半分を超えて連なっている＝大半のtaskが並列候補ではなく
+ * 一本の鎖に押し込まれていることを意味する。`todo start`側が既に持つ
+ * `all_ready_parallel_by_default`方針をplan作成時点まで前倒しする出発点として
+ * 0.5を採る。実測（parent-child-repair: task 26, critical path約20,
+ * ratio≈0.77）を確実に超える一方、緩やかな分岐を持つ通常のplanまでは拾わない
+ * 水準として選んだ。
+ */
+export const DISPATCH_SHAPE_SERIALIZATION_THRESHOLD = 0.5;
+
+/**
+ * 閾値判定の対象にする最小task数。
+ * 3〜5 task程度の一直線planを毎回突き返しても再考の余地がなく
+ * （並列化する意味のある規模でない）機構がノイズになるだけなので、
+ * 6 task未満は常に素通りさせる。
+ */
+export const DISPATCH_SHAPE_MIN_TASK_COUNT_FOR_GATE = 6;
+
+export const DISPATCH_SHAPE_SERIALIZATION_REVIEWED_FLAG = '--serialization-reviewed';
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/**
+ * task_id集合と（既にこの集合の内側だけへ絞り込まれた）依存辺から、
+ * dispatch形状を計算する。
+ *
+ * 呼び出し側の責務: `edges`は「このtask集合の内側だけ」の task_id 対で渡すこと
+ * （cross-plan／既存planへの依存や、joinの`after→before`展開は呼び出し側で
+ * 行い、範囲外の参照はここへ渡さない）。範囲外の参照が混入した場合は
+ * 呼び出し側の実装誤りとして typed error で止める。
+ *
+ * 循環検出は専用のロジックを別途書き足すのではなく、最長path計算
+ * （Kahn法によるtopological order）が全nodeを消化できないことの自然な帰結
+ * として行う。この関数はplan作成／migrateがstoreへ書き込む前（拒否時に
+ * 何も書かない設計）に呼ばれるため、store側の`validateMergedGraph`による
+ * cycle拒否より前に走る——結果として、循環を含む入力はここで先に
+ * `DISPATCH_SHAPE_INVALID`として止まる（従来store書込み時に出ていた
+ * `STORE_INCONSISTENT`/`merged_cycle`より手前で検出されるようになるという、
+ * 観測可能だが意図した違いがある）。
+ */
+export function computeTodoDispatchShape({ taskIds, edges }) {
+  if (!Array.isArray(taskIds) || taskIds.length === 0
+    || !taskIds.every((id) => typeof id === 'string' && id.length > 0)) {
+    throw new TodoStoreError('DISPATCH_SHAPE_INVALID', 'dispatch_shape_task_ids_invalid');
+  }
+  const idSet = new Set(taskIds);
+  if (idSet.size !== taskIds.length) {
+    throw new TodoStoreError('DISPATCH_SHAPE_INVALID', 'dispatch_shape_task_ids_duplicate');
+  }
+  if (!Array.isArray(edges) || edges.some((edge) => edge === null || typeof edge !== 'object'
+    || typeof edge.from !== 'string' || typeof edge.to !== 'string'
+    || !idSet.has(edge.from) || !idSet.has(edge.to))) {
+    throw new TodoStoreError('DISPATCH_SHAPE_INVALID', 'dispatch_shape_edge_out_of_scope');
+  }
+  if (edges.some((edge) => edge.from === edge.to)) {
+    throw new TodoStoreError('DISPATCH_SHAPE_INVALID', 'dispatch_shape_self_edge');
+  }
+
+  const successors = new Map([...idSet].map((id) => [id, []]));
+  const indegree = new Map([...idSet].map((id) => [id, 0]));
+  const edgeKeys = new Set();
+  for (const { from, to } of edges) {
+    const key = `${from}\0${to}`;
+    if (edgeKeys.has(key)) continue; // hard_dependenciesとjoin由来で同じ辺が重複しても一度だけ数える
+    edgeKeys.add(key);
+    successors.get(from).push(to);
+    indegree.set(to, indegree.get(to) + 1);
+  }
+  for (const list of successors.values()) list.sort(compareText);
+
+  // Kahn法によるtopological order。dist[node] = nodeで終わる最長path長（辺数）は、
+  // 「nodeを、その全先行taskが処理済みになった時点で処理する」という不変条件から
+  // 標準的なlongest-path-in-DAG漸化式（dist[v] = max(dist[v], dist[u]+1)）として導かれる。
+  const dist = new Map([...idSet].map((id) => [id, 0]));
+  const predecessor = new Map();
+  const queue = [...idSet].filter((id) => indegree.get(id) === 0).sort(compareText);
+  const order = [];
+  while (queue.length > 0) {
+    queue.sort(compareText);
+    const node = queue.shift();
+    order.push(node);
+    for (const successor of successors.get(node)) {
+      if (dist.get(node) + 1 > dist.get(successor)) {
+        dist.set(successor, dist.get(node) + 1);
+        predecessor.set(successor, node);
+      }
+      indegree.set(successor, indegree.get(successor) - 1);
+      if (indegree.get(successor) === 0) queue.push(successor);
+    }
+  }
+  if (order.length !== idSet.size) {
+    throw new TodoStoreError('DISPATCH_SHAPE_INVALID', 'dispatch_shape_dependency_cycle');
+  }
+
+  const taskCount = idSet.size;
+  const maxDist = Math.max(...order.map((id) => dist.get(id)));
+  const criticalPathLength = maxDist + 1;
+  const widthByDist = new Map();
+  for (const id of idSet) widthByDist.set(dist.get(id), (widthByDist.get(dist.get(id)) ?? 0) + 1);
+  const maxFrontierWidth = Math.max(...widthByDist.values());
+
+  // critical path（人向けヒント）の復元: distが最大のnodeから、決定的に選んだpredecessorを
+  // 遡って根まで辿る。表示専用でありdigest対象ではないため、決定性は再現性のためだけに要る。
+  const deepest = [...idSet].filter((id) => dist.get(id) === maxDist).sort(compareText)[0];
+  const criticalPathTaskIds = [];
+  for (let cursor = deepest; cursor !== undefined; cursor = predecessor.get(cursor)) {
+    criticalPathTaskIds.push(cursor);
+  }
+  criticalPathTaskIds.reverse();
+
+  return {
+    task_count: taskCount,
+    critical_path_length: criticalPathLength,
+    max_frontier_width: maxFrontierWidth,
+    // canonical digest（todoSelfDigest→digestTodoArtifact）はsafe integer以外の数値を
+    // TypeErrorで拒否する（todo-contracts.mjsのcanonicalPart）。dispatch_shapeは
+    // plan create/migrateの結果にそのまま埋め込まれ digest対象になるため、比率は
+    // 固定小数のstringで持つ（判定側はNumber()で復元する）。
+    serialization_ratio: (criticalPathLength / taskCount).toFixed(4),
+    critical_path_task_ids: criticalPathTaskIds,
+  };
+}
+
+/** dispatch_shapeが、再考なしで直列のまま通してよい規模・度合いかを判定する。 */
+export function isTodoDispatchShapeSerializationExcessive(shape) {
+  return shape.task_count >= DISPATCH_SHAPE_MIN_TASK_COUNT_FOR_GATE
+    && Number(shape.serialization_ratio) > DISPATCH_SHAPE_SERIALIZATION_THRESHOLD;
+}
+
+/**
+ * dispatch_shapeが直列に寄りすぎているplanを、再考なしでは通さない。
+ *
+ * `todo start`の`PARALLEL_DISPATCH_RECONSIDER`と同じ二段階（一度突き返し、
+ * 再考を経たflagが無ければ通さない）をplan作成時点へ前倒しする。ここで
+ * 拒否する場合、呼び出し側はまだstoreへ何も書いていないこと（初期化／追加を
+ * この呼び出しより後で行うこと）。
+ */
+export function assertTodoDispatchShapeReviewed({ shape, reviewed }) {
+  if (!isTodoDispatchShapeSerializationExcessive(shape) || reviewed) return;
+  throw new TodoStoreError('PARALLEL_DISPATCH_RECONSIDER', 'plan_shape_too_serial', undefined, {
+    task_count: shape.task_count,
+    critical_path_length: shape.critical_path_length,
+    max_frontier_width: shape.max_frontier_width,
+    serialization_ratio: shape.serialization_ratio,
+    critical_path_task_ids: shape.critical_path_task_ids,
+    default_policy: 'all_ready_parallel_by_default',
+    serialization_reviewed_flag: DISPATCH_SHAPE_SERIALIZATION_REVIEWED_FLAG,
+    guidance: `並列を検討しなさい。task ${shape.task_count}件のうちcritical pathが`
+      + `${shape.critical_path_length}段（serialization_ratio ${shape.serialization_ratio}）で、`
+      + '大半のtaskが並列候補ではなく一本の依存鎖に押し込まれている。'
+      + 'critical_path_task_idsに沿った依存のうち、実際には干渉しない組を'
+      + 'hard_dependencies/joinsから外せないか見直す'
+      + '（実行主体が足りないなら増やす。増やせないことは直列化の理由にならない）。'
+      + `検討した上でなお直列でよいなら ${DISPATCH_SHAPE_SERIALIZATION_REVIEWED_FLAG} を付けて再実行する。`,
+  });
+}
+
+/**
+ * plan/extractionの`tasks`・`hard_dependencies`・`joins`（nodeRef形式）から、
+ * 「このproject_id/plan_keyの内側だけ」に絞ったdispatch形状を計算する高レベル入口。
+ *
+ * cross-plan参照やdanglingな参照はここで検証しない（既存のstore書込み経路が
+ * 別途検証する）。単に形状計算の対象から外すだけであり、それらの妥当性判断は
+ * 呼び出し側の後続処理（実際のstore書込み）に委ねる。
+ */
+export function computeTodoDispatchShapeForPlan({
+  projectId, planKey, taskIds, hardDependencies, joins,
+}) {
+  const idSet = new Set(taskIds);
+  const isLocal = (ref) => ref?.project_id === projectId && ref?.plan_key === planKey
+    && idSet.has(ref?.task_id);
+  const edges = [];
+  for (const edge of hardDependencies ?? []) {
+    if (isLocal(edge.from) && isLocal(edge.to)) edges.push({ from: edge.from.task_id, to: edge.to.task_id });
+  }
+  for (const join of joins ?? []) {
+    if (!isLocal(join.before)) continue;
+    for (const after of join.after) {
+      if (isLocal(after)) edges.push({ from: after.task_id, to: join.before.task_id });
+    }
+  }
+  return computeTodoDispatchShape({ taskIds, edges });
+}

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

@@ -117,7 +117,8 @@ export function renderPhaseProgress(readModel) {
   const settledRows = [];
   for (const member of readModel.members) {
     if (!['lattice.todo_plan.v4', 'lattice.todo_plan.v5'].includes(member.plan.schema)) continue;
-    const phases = new Map(member.snapshot.phases.map((phase) => [phase.phase_id, phase]));
+    // snapshot artifactの形式には縛られない導出ビュー(member.phases)を読む(ADR 0147)。
+    const phases = new Map(member.phases.map((phase) => [phase.phase_id, phase]));
     for (const phase of member.plan.phases) {
       const tasks = member.plan.tasks.filter((task) => task.phase_id === phase.phase_id);
       const states = new Map(member.tasks.map((task) => [task.task_id, task.status]));