@quolu/lattice 0.35.0 → 0.36.1

package/src/todo-cli.mjs

@@ -37,6 +37,8 @@ import {
   applyTodoRevisionSet,
   createTodoStoreWriter,
   TodoStoreError,
+  isPhaselessTodoPlanSchema,
+  TERMINAL_AUDIT_PHASE_ID,
   readTodoIndependenceArtifact,
   readTodoSeamProposalArtifact,
   readTodoStore,
@@ -52,6 +54,7 @@ import {
 } from './todo-store.mjs';
 import {
   appendTodoExtraction,
+  explainTodoExtraction,
   validateTodoExtraction,
 } from './todo-migration.mjs';
 import {
@@ -97,6 +100,7 @@ import {
   validateWitnessDraft,
 } from './witness-scaffold.mjs';
 import {
+  explainPhaseTodoRevision, explainTodoRevision, explainTodoRevisionSet,
   parseTodoSourceRef, todoLegacyReconciliationDigest, validatePhaseTodoRevision,
   validateTodoRevision, validateTodoRevisionSet,
 } from './todo-revision.mjs';
@@ -113,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`);
@@ -223,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;
 }
@@ -232,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);
@@ -268,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');
   }
@@ -373,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,
 }) {
@@ -383,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,
@@ -402,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');
@@ -599,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,
@@ -609,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,
@@ -629,14 +700,16 @@ 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;
@@ -689,6 +762,10 @@ async function migrate({ repoRoot, inputRef, serializationReviewed = false }) {
       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');
@@ -711,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,
@@ -722,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' }),
@@ -1922,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')) {

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-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]));

package/src/todo-gantt-layout.mjs

@@ -153,7 +153,9 @@ function normalizeInput(readModel, chainProjection) {
     }
     const { plan } = member;
     const statusByTask = new Map(member.tasks.map((task) => [task.task_id, task]));
-    const statusByPhase = new Map((member.snapshot?.phases ?? [])
+    // snapshot artifactの形式(v1にはphasesキーが無い)には縛られない導出ビューを読む
+    // (readTodoStoreが常にmember.phasesとして埋める。ADR 0147)。
+    const statusByPhase = new Map((member.phases ?? [])
       .map((phase) => [phase.phase_id, phase.status]));
     for (const task of plan.tasks) {
       if (!plain(task) || typeof task.task_id !== 'string' || typeof task.lane !== 'string') {
@@ -174,7 +176,14 @@ function normalizeInput(readModel, chainProjection) {
         status: state.status,
         plan_schema: plan.schema ?? null,
         phase_id: task.phase_id ?? null,
-        phase_status: task.phase_id === undefined ? null : statusByPhase.get(task.phase_id) ?? null,
+        // ADR 0147: phase無しplan(task.phase_idが無い世代)も、終端に暗黙のterminal-audit
+        // Phaseを1つ持つ(todo-store.mjsのphasesOf/TERMINAL_AUDIT_PHASE_ID)。ここで素通しせず
+        // nullのままにすると、gantt scope側(todo-gantt-scope.mjs)が「監査未了のplanを畳まない」
+        // 判定に使える材料を一切受け取れない。'terminal-audit'はTERMINAL_AUDIT_PHASE_IDと同じ
+        // 予約IDで、phase_readyの判定(v4だけを見る既存分岐)には影響しない。
+        phase_status: task.phase_id === undefined
+          ? statusByPhase.get('terminal-audit') ?? null
+          : statusByPhase.get(task.phase_id) ?? null,
         phase_ready: plan.schema !== 'lattice.todo_plan.v4'
           || statusByPhase.get(task.phase_id) === 'active',
       });
@@ -236,7 +245,8 @@ function readyTaskKeys(readModel, nodes, nodesByKey, incoming) {
   const phaseStatuses = new Map();
   const phaseAcceptIncoming = new Map(nodes.map(({ key }) => [key, new Set()]));
   for (const member of readModel.members) {
-    for (const phase of member.snapshot?.phases ?? []) {
+    // snapshot artifactの形式には縛られない導出ビュー(member.phases)を読む(ADR 0147)。
+    for (const phase of member.phases ?? []) {
       phaseStatuses.set(JSON.stringify([
         member.plan.project_id, member.plan.plan_key, phase.phase_id,
       ]), phase.status);

package/src/todo-gantt-scope.mjs

@@ -38,10 +38,35 @@ function compareText(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
 
+/**
+ * ADR 0147: phase無しplan(v1/v2/v3)は終端の暗黙Phase(terminal-audit)がacceptedになるまで
+ * 「閉じた」ことにならない。全taskがdoneでも監査未了なら、そのplanのToDoは生きた作業と同じ
+ * 扱い(distance 0)にして畳ませない——畳んでしまうと監査待ちであることが図から消え、
+ * ADR 0147が塞ごうとした「一度も重監査を通らず完走した」事故と外形が同じになる。
+ *
+ * v4/v5(phaseを宣言したplan)はこの判定の対象外にする——既存のPhase gateが重監査を担って
+ * おり、ここで同じ規律を足すとPhase単位の既存fold挙動を変えてしまう(非目標)。
+ * `phase_status`はレイアウト層(todo-gantt-layout.mjs)がplanの世代を問わず埋める。
+ * phase無しplanのtaskにはphase_idフィールド自体が無いため、そこでは暗黙Phaseの状態を
+ * 埋める。フィールドが無い/nullの入力(既存test・素のnode)は従来どおり対象外(false)になる。
+ *
+ * 対象は`gate_ready`(全task doneで監査待ち)・`reviewing`(監査中)・`rejected`
+ * (監査が通らず要フォロー)の3状態だけに絞る。`active`(一部taskがまだpending)は、
+ * 他のtaskが図に残っている限りplanが未完了だと分かるので対象にしない——ここまで
+ * 広げると、完走していない枝の通常foldまで止めてしまい既存挙動を変える。
+ */
+const AUDIT_PENDING_PHASE_STATUSES = new Set(['gate_ready', 'reviewing', 'rejected']);
+function auditPending(node) {
+  if (!AUDIT_PENDING_PHASE_STATUSES.has(node.phase_status ?? null)) return false;
+  const schema = node.plan_schema ?? null;
+  return schema !== 'lattice.todo_plan.v4' && schema !== 'lattice.todo_plan.v5';
+}
+
 /**
  * Forward distance from each node to the nearest live (non-done) node, over the
  * dependency DAG. A live node is at distance 0; a node with no live descendant
- * is at Infinity.
+ * is at Infinity. A done node whose plan's terminal audit (ADR 0147) has not
+ * been accepted is also pinned at distance 0 — it must not fold away silently.
  *
  * Edges always increase the wave (`assignWaves` is a longest-path layering), so
  * visiting nodes in descending wave order guarantees every successor is settled
@@ -54,7 +79,7 @@ function distanceToLive(nodes, edges, wave) {
   const ordered = [...nodes].sort((left, right) => wave.get(right.key) - wave.get(left.key)
     || compareText(right.key, left.key));
   for (const node of ordered) {
-    if (node.status !== 'done') {
+    if (node.status !== 'done' || auditPending(node)) {
       distance.set(node.key, 0);
       continue;
     }

package/src/todo-migration.mjs

@@ -126,6 +126,114 @@ function validateJoins(value) {
     && sortedStrictly(value, (join) => join.id);
 }
 
+const reject = (reason, path = '') => ({ valid: false, reason, path });
+
+/** value自体がexactRecordの対象になれる素朴なobjectかどうか（配列・nullを除く）。 */
+function plainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * 期待keyとの過不足を1件ずつ言い当てる。missing/unexpectedのどちらが先に見つかっても
+ * そこで止め、複数の欠落を一度に説明しない——`exactRecord`のbooleanと違い、
+ * 最初に見つかった違反fieldをpathへ刻む。
+ */
+function explainKeys(value, requiredKeys, at) {
+  if (!plainObject(value) || Object.getPrototypeOf(value) !== Object.prototype) {
+    return reject('not_an_object', at);
+  }
+  const actualKeys = new Set(Object.keys(value));
+  for (const key of requiredKeys) {
+    if (!actualKeys.has(key)) return reject('missing_required_key', `${at}/${key}`);
+  }
+  const requiredSet = new Set(requiredKeys);
+  for (const key of actualKeys) {
+    if (!requiredSet.has(key)) return reject('unexpected_key', `${at}/${key}`);
+  }
+  return { valid: true };
+}
+
+function explainSortedStrictly(values, key, at) {
+  for (let index = 1; index < values.length; index += 1) {
+    if (!(key(values[index - 1]) < key(values[index]))) {
+      return reject('unsorted_or_duplicate_collection', `${at}/${index}`);
+    }
+  }
+  return { valid: true };
+}
+
+/**
+ * `lattice.todo_extraction.v1/v2`を、既存の`validateTodoExtraction`の可否は変えずに
+ * 診断する（ADR 0130の案内規律をmigration入口へ拡張）。
+ *
+ * 深いgraph整合（親task解決・edge/join local参照解決）はここでは個別に言い当てず、
+ * 単一のreasonへ丸める——既知の実運用の詰まりどころ（必須key欠落・task/edge/joinの
+ * ソート違反・digest不一致）を優先して解消する。それでも掴めない違反は
+ * `diagnosis_incomplete`として正直に返す。
+ */
+export function explainTodoExtraction(value) {
+  try {
+    if (!plainObject(value)) return reject('not_an_object', '');
+    const schema = value.schema;
+    if (![TODO_EXTRACTION_SCHEMA, TODO_EXTRACTION_SCHEMA_V2].includes(schema)) {
+      return reject('schema_mismatch', '/schema');
+    }
+    const v2 = schema === TODO_EXTRACTION_SCHEMA_V2;
+    const topKeys = [
+      'schema', 'project_id', 'plan_key', 'plan_version', 'actor', 'recorded_at',
+      'tasks', 'hard_dependencies', 'joins', 'extraction_digest',
+    ];
+    const topKeyCheck = explainKeys(value, topKeys, '');
+    if (!topKeyCheck.valid) return topKeyCheck;
+    if (!isTodoIdentifier(value.project_id)) return reject('invalid_identifier', '/project_id');
+    if (!isTodoIdentifier(value.plan_key)) return reject('invalid_identifier', '/plan_key');
+    if (!isTodoIdentifier(value.plan_version)) return reject('invalid_identifier', '/plan_version');
+    if (!actor(value.actor)) return reject('invalid_actor', '/actor');
+    if (!isStrictTodoTimestamp(value.recorded_at)) return reject('invalid_timestamp', '/recorded_at');
+    if (!Array.isArray(value.tasks) || value.tasks.length === 0
+      || value.tasks.length > TODO_LIMITS.tasksPerPlan) {
+      return reject('bounded_collection_violation', '/tasks');
+    }
+    const taskKeys = v2
+      ? ['task_id', 'title', 'lane', 'narrative_ref', 'compile_binding', 'disposition',
+        'start', 'completion', 'source', 'migration_context']
+      : ['task_id', 'title', 'lane', 'narrative_ref', 'compile_binding', 'disposition',
+        'completion', 'source', 'migration_context'];
+    for (const [index, task] of value.tasks.entries()) {
+      const taskKeyCheck = explainKeys(task, taskKeys, `/tasks/${index}`);
+      if (!taskKeyCheck.valid) return taskKeyCheck;
+      if (!extractionTask(task, schema)) {
+        return reject('task_shape_invalid', `/tasks/${index}`);
+      }
+    }
+    const sortCheck = explainSortedStrictly(value.tasks, (task) => task.task_id, '/tasks');
+    if (!sortCheck.valid) return sortCheck;
+    if (new Set(value.tasks.map(({ task_id: taskId }) => taskId)).size !== value.tasks.length) {
+      return reject('duplicate_task_id', '/tasks');
+    }
+    if (!validateEdges(value.hard_dependencies)) return reject('hard_dependencies_invalid', '/hard_dependencies');
+    if (!validateJoins(value.joins)) return reject('joins_invalid', '/joins');
+    if (!isTodoDigest(value.extraction_digest)) return reject('invalid_digest', '/extraction_digest');
+    const expectedDigest = todoSelfDigest(value, 'extraction_digest');
+    if (value.extraction_digest !== expectedDigest) {
+      return reject('extraction_digest_mismatch', '/extraction_digest');
+    }
+    const taskIds = new Set(value.tasks.map(({ task_id: taskId }) => taskId));
+    const badParent = value.tasks.find((task) => task.source.parent_task_id === task.task_id
+      || (task.source.parent_task_id !== null && !taskIds.has(task.source.parent_task_id)));
+    if (badParent !== undefined) {
+      return reject('parent_task_id_unresolved',
+        `/tasks/${value.tasks.indexOf(badParent)}/source/parent_task_id`);
+    }
+    if (!localRefsResolve(value)) return reject('local_ref_unresolved', '');
+    // ここまでの個別検査を全て通過したのに`validateTodoExtraction`がfalseを返す状況は、
+    // このexplainがまだ言い当てられない違反があるということ。捏造せず未特定と申告する。
+    return { valid: true };
+  } catch {
+    return reject('diagnosis_failed', '');
+  }
+}
+
 function registeredTaskIds(value) {
   return new Set(value.tasks
     .filter(({ disposition }) => disposition.startsWith('register_'))