@quolu/lattice 0.34.2 → 0.35.0

package/README.ja.md

@@ -161,12 +161,35 @@ cross-plan topologyを同時に切り替える場合は
 Phase付きv5 planでは、通常ToDoの開始順はToDo DAGだけで決まり、Phase前後関係は重監査の順序だけを
 制御します。特定ToDoがPhase受理を本当に必要とする場合だけ`phase_accept_dependencies`で明示します。
 `lattice todo status --json`の`dispatch_frontier`はready全件を同時dispatchする既定を示します。
-readyが複数なら最初のstartに`--parallel-frontier`を付け、subsetだけを直列着手する場合は
-`--override-reason <reason>`で理由を残します。
+readyが複数なら最初のstartに`--parallel-frontier`を付けます。subsetだけを直列着手する場合は
+`--override-reason <reason>`で理由を残しますが、**その申告は一度突き返されます**。
 
 ```bash
 lattice todo start --plan <key> --task <id> --parallel-frontier
-lattice todo start --plan <key> --task <id> --override-reason <reason>
+lattice todo start --plan <key> --task <id> --override-reason <reason> --serial-confirmed
+```
+
+直列の申告に対して`PARALLEL_DISPATCH_RECONSIDER`を返し、並列の再検討を促してから、
+同じ理由に`--serial-confirmed`を付けた再実行だけを通します。規則を文書へ書くだけでは
+読み飛ばされるため、再考をコマンドの往復で強制する設計です。**足止めは一度だけで、
+再実行すれば直列で進みます。**
+
+ただし理由が**実際の干渉を述べていない**場合——「単一セッションだから」「逐次実行するので」
+のようにworker数・セッション構成・作業者の都合を述べただけの場合——は
+`PARALLEL_DISPATCH_INVALID`で拒否し、`--serial-confirmed`を付けても通しません。
+実行主体が1つしか無いことは並列にできない理由ではない（必要ならworkerを増やす）ためです。
+「両taskが同一fileへ書き込む」のような干渉を書けば、再確認を経て通ります。
+
+**同じ検査を計画時点にも掛けます。** 着手時だけを締めても、planそのものが直列に組まれていれば
+並列は生まれません。`lattice plan create`と`lattice todo migrate`は依存グラフから
+`dispatch_shape`（`task_count`／`critical_path_length`／`max_frontier_width`／
+`serialization_ratio`）を計算して結果へ載せ、直列度が閾値を超えるplanを一度突き返します。
+再考した上でなお直列でよいなら`--serialization-reviewed`を付けて再実行します
+（6 task未満のplanは対象外）。判定はstore書込みの前に行うので、拒否された時にstoreへは
+何も書かれません。
+
+```bash
+lattice todo migrate --input <extraction.json> --serialization-reviewed
 ```
 
 `--parallel-frontier`はhostへ並列dispatch方針を宣言する開始gateです。Lattice自身がAI hostのagentを

package/bin/lattice.mjs

@@ -30,10 +30,14 @@ if (help !== null) {
       cwd: process.cwd(), stdout: process.stdout, cliVersion: packageJson.version, error,
     });
   }
-} else if (args.length === 4 && args[0] === 'plan' && args[1] === 'create' && args[2] === '--input') {
+} else if ((args.length === 4 || args.length === 5) && args[0] === 'plan' && args[1] === 'create'
+  && args[2] === '--input' && (args.length === 4 || args[4] === '--serialization-reviewed')) {
   const { projectCliFailure, runPlanCreate } = await import('../src/project-cli.mjs');
   try {
-    process.exitCode = await runPlanCreate({ cwd: process.cwd(), inputRef: args[3], stdout: process.stdout });
+    process.exitCode = await runPlanCreate({
+      cwd: process.cwd(), inputRef: args[3], stdout: process.stdout,
+      serializationReviewed: args.length === 5,
+    });
   } catch (error) {
     process.exitCode = projectCliFailure(process.stderr, error);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.34.2",
+  "version": "0.35.0",
   "description": "Schedulability compiler for multi-agent development: observe real code boundaries, refactor the conflicting seam, recompile the plan for parallel execution",
   "author": {
     "name": "Quo / クオ at kitepon.dev",

package/src/cli-help.mjs

@@ -23,7 +23,9 @@ const NAMESPACE_HELP = Object.freeze({
   plan: `Usage: lattice plan <command> [options]
 
 Commands:
-  create --input <file>
+  create --input <file> [--serialization-reviewed]
+      # 依存グラフがほぼ一直線（serialization_ratioが閾値超）なら一度突き返す。
+      # 再考した上でなお直列でよいなら --serialization-reviewed を付けて再実行する
   create --schema --json
   create --schema-version <2|3> --json
   compile --request <request.json>
@@ -70,7 +72,11 @@ Read commands:
   phase status --plan <key>
 
 Write commands:
-  start --plan <key> --task <id> [--parallel-frontier|--override-reason <text>]
+  migrate --input <extraction.json> [--serialization-reviewed]
+      # 既存storeへplanを追加する（plan createは空store初期化専用）。
+      # 依存グラフがほぼ一直線なら一度突き返し、再考後の --serialization-reviewed で通す
+  start --plan <key> --task <id> [--parallel-frontier|--override-reason <text> [--serial-confirmed]]
+        # 既定は全ready同時dispatch。直列にするには理由の申告後、再考を経て --serial-confirmed が要る
   block --plan <key> --task <id> --reason <text>
   unblock --plan <key> --task <id>
   done --plan <key> --task <id> --evidence <file>
@@ -129,7 +135,7 @@ registerはLATTICE_BRIDGE_REGISTRAR_SSH_HOSTとLATTICE_BRIDGE_REGISTRAR_SCRIPT
 const SUBCOMMAND_USAGE = Object.freeze({
   status: 'status --json',
   'session-context': 'session-context --json',
-  'plan create': 'plan create --input <file> | --schema --json | --schema-version <2|3> --json',
+  'plan create': 'plan create --input <file> [--serialization-reviewed] | --schema --json | --schema-version <2|3> --json',
   'plan compile': 'plan compile --request <request.json> | --schema --json',
   'plan verify': 'plan verify --request <request.json> --plan <plan.json>',
   'run start': 'run start --request <request.json> --executor <adapter> | --schema --json',
@@ -174,7 +180,7 @@ const SUBCOMMAND_USAGE = Object.freeze({
   'todo revise': 'todo revise --plan <key> --input <file>',
   'todo revise-phase': 'todo revise-phase --plan <key> --input <file>',
   'todo revise-set': 'todo revise-set --input <file>',
-  'todo migrate': 'todo migrate --input <extraction.json>',
+  'todo migrate': 'todo migrate --input <extraction.json> [--serialization-reviewed]',
   'sensor init': 'sensor init [path] --json',
   'sensor sync': 'sensor sync [path] --json',
   'runtime-errors snapshot': 'runtime-errors snapshot [--after-cursor <n>] [--limit <n>] --json',

package/src/project-cli.mjs

@@ -26,6 +26,10 @@ import {
   readTodoStore,
   TodoStoreError,
 } from './todo-store.mjs';
+import {
+  assertTodoDispatchShapeReviewed,
+  computeTodoDispatchShapeForPlan,
+} from './todo-dispatch-shape.mjs';
 
 const STORE_REF = '.lattice/todo';
 const MANIFEST_REF = `${STORE_REF}/manifest.json`;
@@ -432,11 +436,21 @@ function validateCreateInput(value) {
   } catch { return false; }
 }
 
-export async function runPlanCreate({ cwd, inputRef, stdout }) {
+export async function runPlanCreate({ cwd, inputRef, stdout, serializationReviewed = false }) {
   const repoRoot = resolveRepoRoot(cwd);
   if (repoRoot === null) throw new TodoStoreError('REPO_UNRESOLVED', 'git_toplevel_unresolved');
   const input = await readCanonicalInput(repoRoot, inputRef);
   if (!validateCreateInput(input)) throw new TodoStoreError('INPUT_INVALID', 'plan_create_schema_invalid');
+  // dispatch_shapeのgateはstore初期化より前に判定する（拒否時にstoreへ何も書かないため、
+  // 再考後の再実行がplan_key_already_existsで詰まらない）。
+  const dispatchShape = computeTodoDispatchShapeForPlan({
+    projectId: input.project_id,
+    planKey: input.plan_key,
+    taskIds: input.tasks.map(({ task_id: taskId }) => taskId),
+    hardDependencies: input.hard_dependencies,
+    joins: input.joins,
+  });
+  assertTodoDispatchShapeReviewed({ shape: dispatchShape, reviewed: serializationReviewed });
   const store = await initializeAuthoredTodoStore({
     repoRoot, writer: createTodoStoreWriter({ caller: 'g5-authoring' }),
     projectId: input.project_id, repositories: [{ repo_id: 'self', path: '.' }],
@@ -460,7 +474,14 @@ export async function runPlanCreate({ cwd, inputRef, stdout }) {
     plan_key: member.plan.plan_key, plan_version: member.plan.plan_version,
     store_ref: STORE_REF, plan_ref: member.descriptor.plan_ref,
     journal_ref: member.descriptor.journal_ref, snapshot_ref: member.descriptor.snapshot_ref,
-    plan_digest: member.plan.plan_digest, result_digest: '',
+    plan_digest: member.plan.plan_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,
+    },
+    result_digest: '',
   };
   result.result_digest = resultDigest(result);
   stdout.write(`${JSON.stringify(result)}\n`);

package/src/todo-cli.mjs

@@ -54,6 +54,10 @@ import {
   appendTodoExtraction,
   validateTodoExtraction,
 } from './todo-migration.mjs';
+import {
+  assertTodoDispatchShapeReviewed,
+  computeTodoDispatchShapeForPlan,
+} from './todo-dispatch-shape.mjs';
 import {
   computeReadyFrontier,
   projectTodoBindings,
@@ -477,7 +481,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 +516,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({
@@ -569,10 +642,34 @@ async function phaseStatus({ repoRoot, planKey }) {
   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 +683,12 @@ 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,
+    },
     result_digest: '',
   };
   result.result_digest = todoSelfDigest(result, 'result_digest');
@@ -1913,9 +2016,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 +2055,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-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-live.mjs

@@ -40,6 +40,13 @@ function dashboardHtml(projects) {
   return `<!doctype html><html lang="ja"><head><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="description" content="Latticeが管理している公開中の工程と現在地を確認できます。"><meta name="robots" content="noindex, nofollow"><meta property="og:title" content="公開中の工程表 — Lattice"><meta property="og:description" content="Latticeが管理している公開中の工程と現在地を確認できます。"><meta name="theme-color" content="#f7f3ea"><title>公開中の工程表 — Lattice</title><style>:root{color-scheme:light;--paper:#f7f3ea;--panel:#fffdf8;--ink:#201d19;--soft:#6c655d;--line:#d8d0c5;--cobalt:#315cbe;--orange:#e85f2a}*{box-sizing:border-box}body{min-height:100vh;margin:0;color:var(--ink);background:var(--paper);font:16px/1.7 system-ui,-apple-system,sans-serif}.shell{max-width:880px;margin:0 auto;padding:28px 22px 40px}.brand{display:flex;align-items:center;gap:9px;padding-bottom:24px;border-bottom:1px solid var(--line);font-size:.88rem}.brand a,.footer a{color:var(--ink);font-weight:800;text-decoration:none}.brand a:hover,.footer a:hover{color:var(--cobalt)}.brand span{color:var(--soft)}main{padding:64px 0 72px}.eyebrow{margin:0 0 8px;color:var(--orange);font-size:.76rem;font-weight:800;letter-spacing:.14em}.lead{max-width:620px;margin:0 0 34px;color:var(--soft)}h1{margin:0 0 14px;font-size:clamp(2rem,6vw,3.4rem);line-height:1.12;letter-spacing:-.04em}ul{display:grid;gap:12px;margin:0;padding:0;list-style:none}li a{display:grid;grid-template-columns:minmax(0,1fr) auto auto;align-items:center;gap:20px;padding:18px 20px;border:1px solid var(--line);border-radius:12px;color:inherit;background:var(--panel);text-decoration:none;box-shadow:0 8px 28px rgba(48,39,27,.04)}li a:hover{border-color:var(--cobalt);transform:translateY(-1px)}li strong{font-size:1.04rem}li code{color:var(--soft);font-size:.78rem}li span{color:var(--cobalt);font-weight:800}.note{margin:28px 0 0;padding:16px 18px;border-left:3px solid var(--orange);color:var(--soft);background:rgba(255,253,248,.72);font-size:.88rem}.footer{display:flex;flex-wrap:wrap;justify-content:space-between;gap:16px;padding-top:20px;border-top:1px solid var(--line);color:var(--soft);font-size:.82rem}.footer nav{display:flex;gap:18px}@media(max-width:560px){.shell{padding:20px 16px 32px}main{padding:44px 0 56px}li a{grid-template-columns:minmax(0,1fr) auto;padding:16px}li code{grid-column:1/-1;grid-row:2}.footer{display:block}.footer nav{margin-top:10px}}</style></head><body><div class="shell"><header class="brand"><a href="https://kitepon.dev/">kitepon.dev</a><span aria-hidden="true">/</span><strong>Lattice</strong></header><main><p class="eyebrow">LIVE DEVELOPMENT</p><h1>公開中の工程表</h1><p class="lead">Latticeが管理しているプロジェクトの工程と、いまどこまで進んでいるかを公開データから確認できます。</p>${content}<p class="note">表示内容はLatticeの記録から自動生成されます。製品の紹介や使い方はGitHubをご覧ください。</p></main><footer class="footer"><span>kitepon.dev の開発工程を、Latticeで可視化しています。</span><nav aria-label="関連リンク"><a href="https://kitepon.dev/">kitepon.dev</a><a href="https://github.com/kitepon-rgb/Lattice">GitHub</a></nav></footer></div></body></html>`;
 }
 
+function notFoundHtml(code, path) {
+  const reason = code === 'PROJECT_NOT_FOUND'
+    ? '指定された工程表は、公開を終了したかURLが変わった可能性があります。'
+    : '指定されたページは、この公開工程表にはありません。';
+  return `<!doctype html><html lang="ja"><head><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="robots" content="noindex, nofollow"><meta name="theme-color" content="#f7f3ea"><title>ページが見つかりません — Lattice</title><style>:root{color-scheme:light;--paper:#f7f3ea;--panel:#fffdf8;--ink:#201d19;--soft:#6c655d;--line:#d8d0c5;--cobalt:#315cbe;--orange:#e85f2a}*{box-sizing:border-box}body{min-height:100vh;margin:0;color:var(--ink);background:var(--paper);font:16px/1.7 system-ui,-apple-system,"Hiragino Sans","Yu Gothic UI",sans-serif}.shell{width:min(720px,calc(100% - 32px));margin:0 auto;padding:28px 0 40px}.brand{display:flex;align-items:center;gap:9px;padding-bottom:24px;border-bottom:1px solid var(--line);font-size:.88rem}.brand a{color:var(--ink);font-weight:800;text-decoration:none}.brand a:hover{color:var(--cobalt)}.brand span{color:var(--soft)}main{padding:clamp(64px,12vw,112px) 0}.eyebrow{margin:0 0 10px;color:var(--orange);font-size:.76rem;font-weight:800;letter-spacing:.14em}h1{margin:0 0 16px;font-size:clamp(2.1rem,7vw,4rem);line-height:1.1;letter-spacing:-.045em}p{max-width:620px;margin:0;color:var(--soft)}code{display:block;margin-top:22px;padding:12px 14px;overflow-wrap:anywhere;border:1px solid var(--line);border-radius:8px;background:var(--panel);color:var(--soft);font-size:.78rem}.actions{display:flex;flex-wrap:wrap;gap:10px;margin-top:28px}.actions a{display:inline-flex;align-items:center;min-height:44px;padding:0 16px;border:1px solid var(--line);border-radius:8px;color:var(--ink);background:var(--panel);font-weight:750;text-decoration:none}.actions a:first-child{border-color:var(--cobalt);color:#fff;background:var(--cobalt)}.actions a:hover{transform:translateY(-1px)}</style></head><body><div class="shell"><header class="brand"><a href="https://kitepon.dev/">kitepon.dev</a><span aria-hidden="true">/</span><strong>Lattice</strong></header><main><p class="eyebrow">404 · ${escapeHtml(code)}</p><h1>ページが見つかりません</h1><p>${reason}</p><code>${escapeHtml(path)}</code><nav class="actions" aria-label="戻り先"><a href="/projects/">公開工程表の一覧へ</a><a href="https://kitepon.dev/">kitepon.devへ</a></nav></main></div></body></html>`;
+}
+
 function validateProject(project) {
   if (project === null || typeof project !== 'object' || Array.isArray(project)
     || typeof project.projectId !== 'string' || !PROJECT_ID.test(project.projectId)
@@ -105,6 +112,18 @@ function sendHttpError(response, status, code, path) {
   response.end(`${JSON.stringify({ schema: HTTP_ERROR_SCHEMA, code, path })}\n`);
 }
 
+function sendNotFound(request, response, code, path) {
+  if (!String(request.headers.accept ?? '').toLowerCase().includes('text/html')) {
+    sendHttpError(response, 404, code, path);
+    return;
+  }
+  const html = notFoundHtml(code, path);
+  response.writeHead(404, { 'content-type': 'text/html; charset=utf-8',
+    'content-length': Buffer.byteLength(html), 'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff' });
+  response.end(html);
+}
+
 function finishRequestFailure(response, code, path) {
   try {
     if (!response.headersSent) sendHttpError(response, 500, code, path);
@@ -167,7 +186,7 @@ export async function startTodoGanttDashboardServer({ registry, port = 0, redire
       }
       const match = /^\/projects\/([^/]+)\/(events)?$/u.exec(url.pathname);
       if (match === null) {
-        sendHttpError(response, 404, 'ROUTE_NOT_FOUND', url.pathname);
+        sendNotFound(request, response, 'ROUTE_NOT_FOUND', url.pathname);
         return;
       }
       let requestedId;
@@ -177,7 +196,7 @@ export async function startTodoGanttDashboardServer({ registry, port = 0, redire
       }
       const project = registry.get(requestedId);
       if (project === null) {
-        sendHttpError(response, 404, 'PROJECT_NOT_FOUND', url.pathname);
+        sendNotFound(request, response, 'PROJECT_NOT_FOUND', url.pathname);
         return;
       }
       if (match[2] === 'events') {