@quolu/lattice 0.58.3 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.58.3",
+  "version": "0.59.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

@@ -113,8 +113,10 @@ Write commands:
       # 検査済みplanned sourceをcanonical refへ保存する。compile成功までは有効化しない
   structure compile --plan <key> --input <file>
       # source graph・Git provenance・ToDo DAGを結合する。consistent時だけplanへimmutableに有効化する
+  structure realize --plan <key> --task <id> (--planned|--realized <actual-structure.json>) [--commit <HEAD|sha>]...
+      # AIはplannedどおりか実体構造だけを判断する。identity・HEAD・履歴鎖・digest・actor・時刻は機械生成する
   structure realize --plan <key> --task <id> --input <file>
-      # 実装後の構造をappend-onlyで記録してからtodo doneへ進む
+      # 完全なrealization envelopeを移送・再生する互換入口
   structure finalize --plan <key> --json
       # 全対象task完了後、最終HEADと全realizationを再結合する。fresh consistentだけterminal受理へ進む
   seam-proposal compile --plan <key>  # 並列可否記録と実sensorからseam提案を記録する
@@ -236,7 +238,7 @@ const SUBCOMMAND_USAGE = Object.freeze({
   'todo note list': 'todo note list --plan <key> [--task <id>] --json',
   'todo bindings': 'todo bindings [--plan <key>] [--json]',
   'todo independence': 'todo independence [--plan <key>] [--json] | compile --plan <key> --input <file> | witness migrate --plan <key>',
-  'todo structure': 'todo structure --schema --json | [--plan <key>] --json | input --plan <key> --input <file> [--dry-run --json] | compile --plan <key> --input <file> | realize --plan <key> --task <id> --input <file> | finalize --plan <key> --json',
+  'todo structure': 'todo structure --schema --json | [--plan <key>] --json | input --plan <key> --input <file> [--dry-run --json] | compile --plan <key> --input <file> | realize --plan <key> --task <id> (--planned|--realized <actual-structure.json>) [--commit <HEAD|sha>]... | realize --plan <key> --task <id> --input <full-realization.json> | finalize --plan <key> --json',
   'todo seam-profile': 'todo seam-profile --plan <key> --file <path> [--json]',
   'todo seam-proposal': 'todo seam-proposal [--plan <key>] [--json] | compile --plan <key>',
   'todo verify': 'todo verify [--plan <key>] [--json]',
@@ -260,7 +262,7 @@ const SUBCOMMAND_USAGE = Object.freeze({
   'todo retract': 'todo retract --plan <key> --task <id> --reason <text>',
   'todo block': 'todo block --plan <key> --task <id> --reason <text>',
   'todo unblock': 'todo unblock --plan <key> --task <id>',
-  'todo done': 'todo done --plan <key> --task <id> --evidence <file>',
+  'todo done': 'todo done --plan <key> --task <id> --evidence <file> [--test-result <markdown-file>]',
   'todo reopen': 'todo reopen --plan <key> --task <id> --reason <text> [--override-reason <text>]',
   'todo evidence': 'todo evidence promote --plan <key> --task <id> --evidence <file>',
   'todo evidence promote': 'todo evidence promote --plan <key> --task <id> --evidence <file>',

package/src/todo-cli.mjs

@@ -10,6 +10,7 @@ import { parseTree } from 'jsonc-parser';
 import {
   TODO_COORDINATION_MODES,
   TODO_DESIGN_MEMO_PROMPT,
+  TODO_TEST_RESULT_CONTRACT_ID,
   canonicalizeTodoArtifact,
   digestTodoArtifact,
   exactRecord,
@@ -18,6 +19,7 @@ import {
   isTodoDesignMemo,
   isTodoIdentifier,
   isTodoRef,
+  isTodoTestResult,
   todoSelfDigest,
   validateEvidenceDescriptor,
 } from './todo-contracts.mjs';
@@ -74,6 +76,10 @@ import {
 } from './todo-store.mjs';
 import {
   TODO_STRUCTURE_BINDING_SCHEMA,
+  TODO_STRUCTURE_LIMITS,
+  TODO_STRUCTURE_REALIZATION_SCHEMA,
+  digestTodoStructureTransform,
+  explainTodoStructureTransform,
   explainTodoStructureRealization,
   explainTodoStructureSet,
 } from './todo-structure-contracts.mjs';
@@ -329,6 +335,16 @@ async function readNoteTextInput(repoRoot, inputRef) {
   catch { throw new TodoStoreError('INPUT_UNREADABLE', 'note_input_invalid_utf8'); }
 }
 
+async function readTestResultInput(repoRoot, inputRef) {
+  const result = await readNoteTextInput(repoRoot, inputRef);
+  if (!isTodoTestResult(result)) {
+    throw new TodoStoreError('INVALID_TEST_RESULT', 'test_result_must_be_non_empty_markdown', undefined, {
+      contract_id: TODO_TEST_RESULT_CONTRACT_ID,
+    });
+  }
+  return result;
+}
+
 function taskRef(plan, taskId) {
   return { project_id: plan.project_id, plan_key: plan.plan_key, task_id: taskId };
 }
@@ -646,12 +662,15 @@ function terminalAuditDoneAdvisory(plan, phases) {
 
 async function mutate({
   repoRoot, env, planKey, taskId, kind, payload, evidenceRef, advisory = null,
-  noteContext = null, structureContext = null,
+  noteContext = null, structureContext = null, testResultRef = null,
 }) {
   const actor = mutationActor(env);
   const evidence = evidenceRef === null ? null : await readEvidenceInput(repoRoot, evidenceRef);
+  const testResult = testResultRef === null ? null : await readTestResultInput(repoRoot, testResultRef);
   let eventPayload = payload;
-  if (kind === 'done' && payload === 'authored') eventPayload = { evidence };
+  if (kind === 'done' && payload === 'authored') {
+    eventPayload = { evidence, ...(testResult === null ? {} : { test_result: testResult }) };
+  }
   if (kind === 'done' && payload === 'evidence_promotion') {
     eventPayload = { done_mode: 'evidence_promotion', imported: true, evidence };
   }
@@ -724,7 +743,10 @@ async function startStructureContext({ repoRoot, store, planKey, taskId }) {
     structure_set_digest: source.structure_set_digest,
     task: structuredClone(task),
     next_actions: task.applicability === 'graph'
-      ? [`lattice todo structure realize --plan ${planKey} --task ${taskId} --input <realization.json>`]
+      ? [
+        `lattice todo structure realize --plan ${planKey} --task ${taskId} --planned`,
+        `lattice todo structure realize --plan ${planKey} --task ${taskId} --realized <actual-structure.json>`,
+      ]
       : [],
   };
 }
@@ -1665,7 +1687,7 @@ async function todoDetail({ repoRoot, planKey, taskId }) {
     repoRoot, store, planKey, taskId: task.task_id,
   });
   const result = {
-    schema: 'lattice.todo_detail_result.v2',
+    schema: 'lattice.todo_detail_result.v3',
     project_id: store.project_id,
     plan_key: planKey,
     plan_version: member.plan.plan_version,
@@ -1998,6 +2020,31 @@ function structurePlanMember(store, requestedPlanKey) {
   return store.members[0];
 }
 
+function parseAutomatedStructureRealizeArgs(argv) {
+  if (argv[0] !== 'structure' || argv[1] !== 'realize'
+    || argv[2] !== '--plan' || !isTodoIdentifier(argv[3])
+    || argv[4] !== '--task' || !isTodoIdentifier(argv[5])) return null;
+  let cursor;
+  let usePlanned;
+  let realizedRef = null;
+  if (argv[6] === '--planned') {
+    cursor = 7; usePlanned = true;
+  } else if (argv[6] === '--realized' && isTodoRef(argv[7])) {
+    cursor = 8; usePlanned = false; realizedRef = argv[7];
+  } else {
+    return null;
+  }
+  const commitRefs = [];
+  while (cursor < argv.length) {
+    if (argv[cursor] !== '--commit' || typeof argv[cursor + 1] !== 'string') return null;
+    commitRefs.push(argv[cursor + 1]);
+    cursor += 2;
+  }
+  return {
+    planKey: argv[3], taskId: argv[5], usePlanned, realizedRef, commitRefs,
+  };
+}
+
 function structureNextActions({ coverage, planKey, findings = [], staleReasons = [] }) {
   const actions = [];
   const add = (value) => { if (!actions.includes(value)) actions.push(value); };
@@ -2013,14 +2060,16 @@ function structureNextActions({ coverage, planKey, findings = [], staleReasons =
     if (staleReasons.includes('realization_head_digest')) {
       add(`lattice todo structure --plan ${planKey} --json`);
     } else {
-      add(`lattice todo structure realize --plan ${planKey} --task <task-id> --input <realization.json>`);
+      add(`lattice todo structure realize --plan ${planKey} --task <task-id> --planned`);
+      add(`lattice todo structure realize --plan ${planKey} --task <task-id> --realized <actual-structure.json>`);
     }
     add(`lattice todo structure finalize --plan ${planKey} --json`);
   } else if (coverage === 'superseded') {
     add(`lattice todo structure input --plan ${planKey} --input <migrated-structure-set.json> --dry-run --json`);
   } else if (coverage === 'consistent') {
     add(`lattice todo structure --plan ${planKey} --json`);
-    add(`lattice todo structure realize --plan ${planKey} --task <task-id> --input <realization.json>`);
+    add(`lattice todo structure realize --plan ${planKey} --task <task-id> --planned`);
+    add(`lattice todo structure realize --plan ${planKey} --task <task-id> --realized <actual-structure.json>`);
     add(`lattice todo structure finalize --plan ${planKey} --json`);
   }
   return actions;
@@ -2134,6 +2183,24 @@ async function readStructureRealizationInput(repoRoot, inputRef) {
   });
 }
 
+async function readStructureRealizedTransformInput(repoRoot, inputRef) {
+  let explained = null;
+  return readJsonInput(repoRoot, inputRef, {
+    validate: (value) => {
+      explained = explainTodoStructureTransform(value);
+      return explained.valid;
+    },
+    invalidCode: 'INVALID_TODO_STRUCTURE_TRANSFORM',
+  }).catch((error) => {
+    if (error?.code === 'INVALID_TODO_STRUCTURE_TRANSFORM' && explained !== null) {
+      throw new TodoStoreError(error.code, explained.reason, undefined, {
+        input_ref: inputRef, path: explained.path,
+      });
+    }
+    throw error;
+  });
+}
+
 async function readCurrentStructureEffective(repoRoot, structureSet) {
   const realizations = [];
   for (const task of structureSet.tasks.filter(({ applicability }) => applicability === 'graph')) {
@@ -2144,22 +2211,7 @@ async function readCurrentStructureEffective(repoRoot, structureSet) {
   return projectTodoStructureEffective({ structureSet, realizations });
 }
 
-async function structureRealize({ repoRoot, env, planKey, taskId, inputRef }) {
-  const realization = await readStructureRealizationInput(repoRoot, inputRef);
-  const actor = mutationActor(env);
-  if (realization.plan_key !== planKey || realization.task_id !== taskId) {
-    throw new TodoStoreError('STRUCTURE_REALIZATION_BINDING_MISMATCH',
-      'cli_target_mismatch', undefined, {
-        expected: { plan_key: planKey, task_id: taskId },
-        actual: { plan_key: realization.plan_key, task_id: realization.task_id },
-      });
-  }
-  if (canonicalizeTodoArtifact(realization.actor) !== canonicalizeTodoArtifact(actor)) {
-    throw new TodoStoreError('STRUCTURE_REALIZATION_BINDING_MISMATCH',
-      'actor_environment_mismatch', undefined, {
-        expected_actor: actor, actual_actor: realization.actor,
-      });
-  }
+async function recordStructureRealization({ repoRoot, planKey, taskId, realization }) {
   const appended = await appendTodoStructureRealization({ repoRoot, realization });
   const structureSet = await readTodoStructureSource({ repoRoot, planKey });
   const effective = await readCurrentStructureEffective(repoRoot, structureSet);
@@ -2180,6 +2232,103 @@ async function structureRealize({ repoRoot, env, planKey, taskId, inputRef }) {
   return result;
 }
 
+async function structureRealize({ repoRoot, env, planKey, taskId, inputRef }) {
+  const realization = await readStructureRealizationInput(repoRoot, inputRef);
+  const actor = mutationActor(env);
+  if (realization.plan_key !== planKey || realization.task_id !== taskId) {
+    throw new TodoStoreError('STRUCTURE_REALIZATION_BINDING_MISMATCH',
+      'cli_target_mismatch', undefined, {
+        expected: { plan_key: planKey, task_id: taskId },
+        actual: { plan_key: realization.plan_key, task_id: realization.task_id },
+      });
+  }
+  if (canonicalizeTodoArtifact(realization.actor) !== canonicalizeTodoArtifact(actor)) {
+    throw new TodoStoreError('STRUCTURE_REALIZATION_BINDING_MISMATCH',
+      'actor_environment_mismatch', undefined, {
+      expected_actor: actor, actual_actor: realization.actor,
+    });
+  }
+  return recordStructureRealization({ repoRoot, planKey, taskId, realization });
+}
+
+function resolveStructureRealizationCommits(repoRoot, refs) {
+  const requested = refs.length === 0 ? ['HEAD'] : refs;
+  if (requested.length > TODO_STRUCTURE_LIMITS.commitsPerRealization) {
+    throw new TodoStoreError('STRUCTURE_REALIZATION_COMMIT_REF_INVALID',
+      'commit_ref_count_exceeds_limit', undefined, {
+        actual: requested.length, limit: TODO_STRUCTURE_LIMITS.commitsPerRealization,
+      });
+  }
+  const resolved = [];
+  for (const ref of requested) {
+    if (!(ref === 'HEAD' || /^[0-9a-f]{40}$/u.test(ref))) {
+      throw new TodoStoreError('STRUCTURE_REALIZATION_COMMIT_REF_INVALID',
+        'commit_ref_must_be_head_or_full_sha', undefined, { commit_ref: ref });
+    }
+    let oid;
+    try {
+      oid = gitSync(['rev-parse', '--verify', `${ref}^{commit}`], {
+        cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      throw new TodoStoreError('STRUCTURE_REALIZATION_COMMIT_REF_INVALID',
+        'commit_ref_unresolved', undefined, { commit_ref: ref });
+    }
+    if (!/^[0-9a-f]{40}$/u.test(oid)) {
+      throw new TodoStoreError('STRUCTURE_REALIZATION_COMMIT_REF_INVALID',
+        'commit_ref_resolved_invalid_oid', undefined, { commit_ref: ref });
+    }
+    if (resolved.includes(oid)) {
+      throw new TodoStoreError('STRUCTURE_REALIZATION_COMMIT_REF_INVALID',
+        'duplicate_commit_ref', undefined, { commit_ref: ref, commit_oid: oid });
+    }
+    resolved.push(oid);
+  }
+  return resolved.sort();
+}
+
+async function structureRealizeActual({
+  repoRoot, env, planKey, taskId, realizedRef, usePlanned, commitRefs,
+}) {
+  const structureSet = await readTodoStructureSource({ repoRoot, planKey });
+  if (structureSet === null) {
+    throw new TodoStoreError('STRUCTURE_REALIZATION_BINDING_MISMATCH',
+      'planned_structure_source_missing', undefined, { plan_key: planKey });
+  }
+  const task = structureSet.tasks.find(({ task_id: id }) => id === taskId);
+  if (task?.applicability !== 'graph') {
+    throw new TodoStoreError('STRUCTURE_REALIZATION_BINDING_MISMATCH',
+      'task_not_graph_applicable', undefined, { plan_key: planKey, task_id: taskId });
+  }
+  const realized = usePlanned
+    ? structuredClone(task.planned)
+    : await readStructureRealizedTransformInput(repoRoot, realizedRef);
+  const chain = await readTodoStructureRealizationChain({
+    repoRoot, structureSet, taskId,
+  });
+  const previous = chain.at(-1) ?? null;
+  const realization = {
+    schema: TODO_STRUCTURE_REALIZATION_SCHEMA,
+    project_id: structureSet.project_id,
+    plan_key: structureSet.plan_key,
+    plan_version: structureSet.plan_version,
+    task_id: taskId,
+    sequence: (previous?.sequence ?? 0) + 1,
+    previous_digest: previous?.realization_digest ?? null,
+    structure_set_digest: structureSet.structure_set_digest,
+    planned_digest: digestTodoStructureTransform(task.planned),
+    head_sha: currentHeadSha(repoRoot),
+    commit_oids: resolveStructureRealizationCommits(repoRoot, commitRefs),
+    realized,
+    supersedes: previous?.realization_digest ?? null,
+    actor: mutationActor(env),
+    recorded_at: new Date().toISOString(),
+    realization_digest: '',
+  };
+  realization.realization_digest = todoSelfDigest(realization, 'realization_digest');
+  return recordStructureRealization({ repoRoot, planKey, taskId, realization });
+}
+
 async function structureFinalize({ repoRoot, env, planKey }) {
   const store = await readTodoStore({ repoRoot });
   const member = structurePlanMember(store, planKey);
@@ -2215,7 +2364,7 @@ async function structureFinalize({ repoRoot, env, planKey }) {
       throw new TodoStoreError('STRUCTURE_FINALIZATION_UNAVAILABLE',
         'realization_missing', undefined, {
           plan_key: planKey, task_id: task.task_id,
-          next_action: `lattice todo structure realize --plan ${planKey} --task ${task.task_id} --input <realization.json>`,
+          next_action: `lattice todo structure realize --plan ${planKey} --task ${task.task_id} --realized <actual-structure.json>`,
         });
     }
     realizations.push(...chain);
@@ -3479,6 +3628,14 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     });
   }
 
+  if (argv[0] === 'structure' && argv[1] === 'realize'
+    && argv[6] === '--realized' && typeof argv[7] === 'string' && path.isAbsolute(argv[7])) {
+    return typedArgumentFailure(stderr, 'INPUT_OUTSIDE_REPOSITORY', 'absolute_input_path_rejected', {
+      argument: '--realized', expected: 'repo-relative path', actual: 'absolute path',
+      next_action: 'place_the_input_inside_the_repository_and_pass_a_repo_relative_path',
+    });
+  }
+
   // `--schema --json`はstoreを読まない決定的な出力（`plan create --schema`と同じ規律）。
   // 通常dispatchより前に処理し、repoRoot解決やdashboard daemon起動を経由させない。
   if (argv.length === 3 && argv[1] === '--schema' && argv[2] === '--json'
@@ -3513,6 +3670,7 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     }
   }
 
+  const automatedStructureRealize = parseAutomatedStructureRealizeArgs(argv);
   let action = null;
   if ((argv.length === 1 && argv[0] === 'status')
     || (argv.length === 2 && argv[0] === 'status' && argv[1] === '--json')) {
@@ -3615,6 +3773,10 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     action = (repoRoot) => structureRealize({
       repoRoot, env, planKey: argv[3], taskId: argv[5], inputRef: argv[7],
     });
+  } else if (automatedStructureRealize !== null) {
+    action = (repoRoot) => structureRealizeActual({
+      repoRoot, env, ...automatedStructureRealize,
+    });
   } else if (argv.length === 5 && argv[0] === 'structure' && argv[1] === 'finalize'
     && argv[2] === '--plan' && isTodoIdentifier(argv[3]) && argv[4] === '--json') {
     action = (repoRoot) => structureFinalize({ repoRoot, env, planKey: argv[3] });
@@ -3779,12 +3941,13 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     && argv[3] === '--task' && isTodoIdentifier(argv[4])) {
     action = (repoRoot) => mutate({ repoRoot, env, planKey: argv[2], taskId: argv[4],
       kind: 'unblock', payload: {}, evidenceRef: null });
-  } else if (argv.length === 7 && argv[0] === 'done'
+  } else if ((argv.length === 7 || argv.length === 9) && argv[0] === 'done'
     && argv[1] === '--plan' && isTodoIdentifier(argv[2])
     && argv[3] === '--task' && isTodoIdentifier(argv[4])
-    && argv[5] === '--evidence' && isTodoRef(argv[6])) {
+    && argv[5] === '--evidence' && isTodoRef(argv[6])
+    && (argv.length === 7 || (argv[7] === '--test-result' && isTodoRef(argv[8])))) {
     action = (repoRoot) => mutate({ repoRoot, env, planKey: argv[2], taskId: argv[4],
-      kind: 'done', payload: 'authored', evidenceRef: argv[6] });
+      kind: 'done', payload: 'authored', evidenceRef: argv[6], testResultRef: argv[8] ?? null });
   } else if (argv.length === 8 && argv[0] === 'evidence' && argv[1] === 'promote'
     && argv[2] === '--plan' && isTodoIdentifier(argv[3])
     && argv[4] === '--task' && isTodoIdentifier(argv[5])

package/src/todo-contracts.mjs

@@ -62,10 +62,14 @@ const CONTROL = /[\u0000-\u001f\u007f]/u;
 const NOTE_FORBIDDEN_CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u;
 
 export const TODO_DESIGN_MEMO_PROMPT = 'あなたがこのToDoに対して、何も考えていないならば、設計メモに `NO_PLAN` と書いてください';
+export const TODO_TEST_RESULT_CONTRACT_ID = 'lattice.todo_test_result.v1';
 
 export const isTodoDigest = (value) => typeof value === 'string' && DIGEST.test(value);
 export const isTodoIdentifier = (value) => typeof value === 'string' && IDENTIFIER.test(value);
 export const isNonNegativeSafeInteger = (value) => Number.isSafeInteger(value) && value >= 0;
+export const isTodoTestResult = (value) => typeof value === 'string' && value.trim().length > 0
+  && Buffer.byteLength(value, 'utf8') <= TODO_LIMITS.noteBodyBytes
+  && !NOTE_FORBIDDEN_CONTROL.test(value);
 
 export function isStrictTodoTimestamp(value) {
   return isCanonicalUtcTimestamp(value);
@@ -527,8 +531,10 @@ function validPayload(event) {
   if (event.kind === 'block') return exactRecord(payload, ['reason']) && nullableText(payload.reason) && payload.reason !== null;
   if (event.kind === 'unblock') return exactRecord(payload, []);
   if (event.kind === 'done' && payload?.done_mode === 'authored') {
-    return exactRecord(payload, ['done_mode', 'imported', 'evidence'])
-      && payload.imported === false && evidence(payload.evidence);
+    return (exactRecord(payload, ['done_mode', 'imported', 'evidence'])
+      || exactRecord(payload, ['done_mode', 'imported', 'evidence', 'test_result']))
+      && payload.imported === false && evidence(payload.evidence)
+      && (payload.test_result === undefined || isTodoTestResult(payload.test_result));
   }
   if (event.kind === 'done' && payload?.done_mode === 'historical_import') {
     return exactRecord(payload, ['done_mode', 'imported', 'status', 'completed_at', 'evidence'])
@@ -569,22 +575,29 @@ function validPayload(event) {
 }
 
 function validCarriedState(value) {
-  if (!exactRecord(value, [
+  const legacy = exactRecord(value, [
     'status', 'started_at', 'done_at', 'blocked_reason', 'evidence', 'imported',
-  ]) || !['pending', 'in-progress', 'blocked', 'done'].includes(value.status)
+  ]);
+  const resultAware = exactRecord(value, [
+    'status', 'started_at', 'done_at', 'blocked_reason', 'evidence', 'imported', 'test_result',
+  ]);
+  if ((!legacy && !resultAware) || !['pending', 'in-progress', 'blocked', 'done'].includes(value.status)
     || (value.started_at !== null && !isStrictTodoTimestamp(value.started_at))
     || (value.done_at !== null && !isStrictTodoTimestamp(value.done_at))
     || (value.blocked_reason !== null && !nullableText(value.blocked_reason))
     || typeof value.imported !== 'boolean') return false;
+  const testResult = resultAware ? value.test_result : null;
+  if (testResult !== null && !isTodoTestResult(testResult)) return false;
   if (value.status === 'pending') return value.started_at === null && value.done_at === null
-    && value.blocked_reason === null && value.evidence === null && value.imported === false;
+    && value.blocked_reason === null && value.evidence === null && value.imported === false
+    && testResult === null;
   const activeEvidenceValid = value.imported
     ? value.evidence === null || validateTodoImportSource(value.evidence)
     : value.evidence === null;
   if (value.status === 'in-progress') return value.done_at === null && value.blocked_reason === null
-    && activeEvidenceValid;
+    && activeEvidenceValid && testResult === null;
   if (value.status === 'blocked') return value.done_at === null && value.blocked_reason !== null
-    && activeEvidenceValid;
+    && activeEvidenceValid && testResult === null;
   return value.blocked_reason === null && value.evidence !== null
     && (value.imported ? validateTodoImportSource(value.evidence) : evidence(value.evidence));
 }
@@ -700,20 +713,35 @@ export function validateTodoSnapshot(value) {
       'schema', 'project_id', 'plan_key', 'plan_version', 'projection_version', 'through_sequence',
       'journal_head_digest', 'tasks', 'phases', 'snapshot_digest',
     ]);
-    return (v1 || v2) && isTodoIdentifier(value.project_id)
+    const v3 = value?.schema === 'lattice.todo_snapshot.v3' && exactRecord(value, [
+      'schema', 'project_id', 'plan_key', 'plan_version', 'projection_version', 'through_sequence',
+      'journal_head_digest', 'tasks', 'snapshot_digest',
+    ]);
+    const v4 = value?.schema === 'lattice.todo_snapshot.v4' && exactRecord(value, [
+      'schema', 'project_id', 'plan_key', 'plan_version', 'projection_version', 'through_sequence',
+      'journal_head_digest', 'tasks', 'phases', 'snapshot_digest',
+    ]);
+    const resultAware = v3 || v4;
+    const phaseAware = v2 || v4;
+    return (v1 || v2 || v3 || v4) && isTodoIdentifier(value.project_id)
       && isTodoIdentifier(value.plan_key) && isTodoIdentifier(value.plan_version)
-      && value.projection_version === (v1 ? 1 : 2) && isNonNegativeSafeInteger(value.through_sequence)
+      && value.projection_version === (v1 ? 1 : v2 ? 2 : v3 ? 3 : 4)
+      && isNonNegativeSafeInteger(value.through_sequence)
       && isTodoDigest(value.journal_head_digest) && Array.isArray(value.tasks)
       && value.tasks.length > 0 && value.tasks.length <= TODO_LIMITS.tasksPerPlan
       && value.tasks.every((entry) => exactRecord(entry, [
         'task_id', 'status', 'started_at', 'done_at', 'blocked_reason', 'evidence', 'evidence_unverified', 'imported',
+        ...(resultAware ? ['test_result'] : []),
       ]) && isTodoIdentifier(entry.task_id) && ['pending', 'in-progress', 'blocked', 'done'].includes(entry.status)
         && (entry.started_at === null || isStrictTodoTimestamp(entry.started_at))
         && (entry.done_at === null || isStrictTodoTimestamp(entry.done_at)) && nullableText(entry.blocked_reason)
         && (entry.evidence === null || evidence(entry.evidence) || validateTodoImportSource(entry.evidence))
-        && typeof entry.evidence_unverified === 'boolean' && typeof entry.imported === 'boolean')
+        && typeof entry.evidence_unverified === 'boolean' && typeof entry.imported === 'boolean'
+        && (!resultAware || (entry.status === 'done'
+          ? entry.test_result === null || isTodoTestResult(entry.test_result)
+          : entry.test_result === null)))
       && value.tasks.every((entry, index) => index === 0 || value.tasks[index - 1].task_id < entry.task_id)
-      && (!v2 || (Array.isArray(value.phases) && value.phases.length > 0
+      && (!phaseAware || (Array.isArray(value.phases) && value.phases.length > 0
         && value.phases.every((entry) => exactRecord(entry, [
           'phase_id', 'status', 'review_event_digest', 'decision_event_digest', 'decision_evidence',
         ]) && isTodoIdentifier(entry.phase_id)

package/src/todo-store.mjs

@@ -302,7 +302,7 @@ async function readPlanScopedJournal(repoRoot, journalRef) {
 
 function taskState(taskId) {
   return { task_id: taskId, status: 'pending', started_at: null, done_at: null, blocked_reason: null,
-    evidence: null, evidence_unverified: false, imported: false };
+    evidence: null, evidence_unverified: false, imported: false, test_result: null };
 }
 
 function emptyPhaseState(phaseId) {
@@ -685,6 +685,7 @@ function replay(plan, events, { now = new Date(), verifyEvidence, verifyImportSo
           plan_key: plan.plan_key, task_id: event.task_id,
         });
         state.status = 'done'; state.done_at = event.recorded_at; state.evidence = event.payload.evidence;
+        state.test_result = event.payload.test_result ?? null;
         state.imported = false;
         completion.set(event.task_id, { mode: 'authored', completed_at: event.recorded_at });
       } else if (event.payload.done_mode === 'historical_import') {
@@ -731,7 +732,7 @@ function replay(plan, events, { now = new Date(), verifyEvidence, verifyImportSo
       }
       const startedSuccessor = localSuccessors(plan, event.task_id).some((id) => states.get(id).status !== 'pending');
       if (startedSuccessor && event.payload.override_reason === null) fail('STORE_INCONSISTENT', 'reopen_has_started_successor');
-      state.status = 'in-progress'; state.done_at = null; state.evidence = null;
+      state.status = 'in-progress'; state.done_at = null; state.evidence = null; state.test_result = null;
       completion.delete(event.task_id);
     }
   }
@@ -774,11 +775,21 @@ function snapshotFor(plan, events, tasks) {
   // ——ADR 0147以降の暗黙terminal-audit Phaseの状態は、この関数の外(readTodoStore/
   // appendTodoEventが返す`phases`という導出ビュー)で供給する。
   const phasePlan = isPhaseTodoPlanSchema(plan.schema);
+  const resultAware = events.some((event) => event.kind === 'done'
+    && typeof event.payload?.test_result === 'string')
+    || events.some((event) => event.kind === 'plan_genesis'
+      && event.state_migration?.some(({ state }) => typeof state?.test_result === 'string'));
+  const snapshotTasks = resultAware ? tasks.map((task) => ({ ...task, test_result: task.test_result ?? null }))
+    : tasks.map(({ test_result: _testResult, ...task }) => task);
   const snapshot = {
-    schema: phasePlan ? 'lattice.todo_snapshot.v2' : 'lattice.todo_snapshot.v1',
+    schema: resultAware
+      ? (phasePlan ? 'lattice.todo_snapshot.v4' : 'lattice.todo_snapshot.v3')
+      : (phasePlan ? 'lattice.todo_snapshot.v2' : 'lattice.todo_snapshot.v1'),
     project_id: plan.project_id, plan_key: plan.plan_key,
-    plan_version: plan.plan_version, projection_version: phasePlan ? 2 : 1, through_sequence: head.sequence,
-    journal_head_digest: head.event_digest, tasks, snapshot_digest: '',
+    plan_version: plan.plan_version,
+    projection_version: resultAware ? (phasePlan ? 4 : 3) : (phasePlan ? 2 : 1),
+    through_sequence: head.sequence,
+    journal_head_digest: head.event_digest, tasks: snapshotTasks, snapshot_digest: '',
     ...(phasePlan ? { phases: projectPhaseStates(plan, events,
       new Map(tasks.map((task) => [task.task_id, task]))) } : {}),
   };
@@ -1515,9 +1526,14 @@ export async function rebuildTodoSnapshot(options = {}) {
 
 function nextEvent(input, storeMember) {
   const previous = storeMember.journal.events.at(-1);
-  const payload = input.kind === 'done' && exactRecord(input.payload, ['evidence'])
-    ? { done_mode: 'authored', imported: false, evidence: input.payload.evidence }
-    : input.payload;
+  let payload = input.payload;
+  if (input.kind === 'done' && (exactRecord(input.payload, ['evidence'])
+    || exactRecord(input.payload, ['evidence', 'test_result']))) {
+    payload = {
+      done_mode: 'authored', imported: false, evidence: input.payload.evidence,
+      ...(input.payload.test_result === undefined ? {} : { test_result: input.payload.test_result }),
+    };
+  }
   const phaseCapablePlan = isPhaseTodoPlanSchema(storeMember.plan.schema);
   const phaseKind = ['phase_review', 'phase_accept', 'phase_reject', 'phase_reopen', 'phase_close_unaudited']
     .includes(input.kind);
@@ -1640,7 +1656,7 @@ async function enforceTodoStructureLifecycleGate(repoRoot, member, eventInput) {
     if (latest === undefined) {
       fail('STRUCTURE_REALIZATION_REQUIRED', 'fresh_realization_missing', {
         plan_key: member.plan.plan_key, task_id: eventInput.task_id,
-        next_action: `lattice todo structure realize --plan ${member.plan.plan_key} --task ${eventInput.task_id} --input <realization.json>`,
+        next_action: `lattice todo structure realize --plan ${member.plan.plan_key} --task ${eventInput.task_id} --realized <actual-structure.json>`,
       });
     }
     let currentHead;
@@ -1655,7 +1671,7 @@ async function enforceTodoStructureLifecycleGate(repoRoot, member, eventInput) {
       fail('STRUCTURE_REALIZATION_REQUIRED', 'realization_head_stale', {
         plan_key: member.plan.plan_key, task_id: eventInput.task_id,
         realization_head_sha: latest.head_sha, current_head_sha: currentHead,
-        next_action: `lattice todo structure realize --plan ${member.plan.plan_key} --task ${eventInput.task_id} --input <realization.json>`,
+        next_action: `lattice todo structure realize --plan ${member.plan.plan_key} --task ${eventInput.task_id} --realized <actual-structure.json>`,
       });
     }
   }
@@ -2613,6 +2629,7 @@ function stateMigrationFor(previous, revision) {
     return { ...migration, state: {
       status: state.status, started_at: state.started_at, done_at: state.done_at,
       blocked_reason: state.blocked_reason, evidence: state.evidence, imported: state.imported,
+      ...(typeof state.test_result === 'string' ? { test_result: state.test_result } : {}),
     } };
   });
 }

package/src/todo-structure-contracts.mjs

@@ -467,6 +467,11 @@ export const digestTodoStructureTransform = (value) => todoSelfDigest(
   { schema: 'lattice.todo_structure_transform.v1', transform: value, digest: '' }, 'digest',
 );
 
+/** AIが判断して渡す実体構造だけを、realization envelopeとは独立に検証する。 */
+export function explainTodoStructureTransform(value) {
+  return transform(value, '');
+}
+
 export function explainTodoStructureRealization(value, { structureSet = null, previous = null,
   priorDigests = null } = {}) {
   try {