@quolu/lattice 0.57.3 → 0.58.1

package/src/todo-cli.mjs

@@ -31,6 +31,7 @@ import { readProjectExternalPane, resolveProjectIdentity } from './project-ident
 import { layoutTodoGantt } from './todo-gantt-layout.mjs';
 import { TODO_GANTT_SCOPES } from './todo-gantt-scope.mjs';
 import { loadTodoGanttPresentation } from './todo-gantt-presentation.mjs';
+import { loadTodoStructurePresentation } from './todo-structure-presentation.mjs';
 import { startTodoGanttLiveServer } from './todo-gantt-live.mjs';
 import {
   renderTodoGanttHtml,
@@ -39,6 +40,7 @@ import {
 import { verifyNarrativeAnchors } from './todo-narrative-anchor.mjs';
 import {
   appendTodoEvent,
+  appendTodoStructureRealization,
   applyPhaseTodoRevision,
   applyTodoRevision,
   applyTodoRevisionSet,
@@ -51,6 +53,10 @@ import {
   readTodoIndependenceArtifact,
   readTodoSeamProposalArtifact,
   readTodoStore,
+  readTodoStructureBinding,
+  readTodoStructureRealizationChain,
+  readTodoStructureSource,
+  todoStructureSourceRef,
   resolveTodoStartRetractionBinding,
   readTodoWitnessSet,
   todoWitnessRef,
@@ -59,9 +65,27 @@ import {
   rebuildTodoSnapshot,
   writeTodoIndependenceArtifact,
   writeTodoSeamProposalArtifact,
+  writeTodoStructureBinding,
+  writeTodoStructureCompileArtifact,
+  writeTodoStructureFinalization,
+  writeTodoStructureSource,
   verifyEffectivePhaseTodoRevisionSources,
   verifyTodoRevisionSources,
 } from './todo-store.mjs';
+import {
+  TODO_STRUCTURE_BINDING_SCHEMA,
+  explainTodoStructureRealization,
+  explainTodoStructureSet,
+} from './todo-structure-contracts.mjs';
+import { collectTodoStructureAuthoritativeObservation } from './todo-structure-authoritative-observation.mjs';
+import { compileTodoStructureOverlay } from './todo-structure-overlay.mjs';
+import {
+  buildTodoStructureCompileArtifact,
+  projectTodoStructureEffective,
+  readTodoStructureFinalizationState,
+  readTodoStructureFinalizationsForStatus,
+  readTodoStructureState,
+} from './todo-structure-store.mjs';
 import { withStartRetractionGuard } from './runtime-pull-intake.mjs';
 import {
   appendTodoExtraction,
@@ -159,6 +183,9 @@ const TODO_SCHEMA_COMMANDS = Object.freeze({
     title: 'lattice.phase_todo_revision.v3', file: 'lattice.phase_todo_revision.v3.schema.json',
   },
   migrate: { title: 'lattice.todo_extraction.v3', file: 'lattice.todo_extraction.v3.schema.json' },
+  structure: {
+    title: 'lattice.todo_structure_set.v1', file: 'lattice.todo_structure_set.v1.schema.json',
+  },
 });
 
 async function runTodoSchemaCommand(command, stdout) {
@@ -207,7 +234,7 @@ function internalFailure(stderr, error) {
 }
 
 const TODO_COMMAND_NAMES = Object.freeze([
-  'status', 'show', 'note', 'bindings', 'independence', 'seam-profile', 'seam-proposal',
+  'status', 'show', 'note', 'bindings', 'independence', 'structure', 'seam-profile', 'seam-proposal',
   'verify', 'snapshot', 'gantt', 'dashboard', 'phase', 'migrate', 'start', 'block',
   'unblock', 'done', 'reopen', 'evidence', 'split', 'revise', 'revise-phase', 'revise-set',
 ]);
@@ -553,6 +580,14 @@ async function readWitnessSetInput(repoRoot, inputRef) {
   return witnessSet;
 }
 
+/** structure draftはpointer診断のためcontract違反でもparseし、判定はdry-runへ返す。 */
+async function readStructureSetDraft(repoRoot, inputRef) {
+  return readJsonInput(repoRoot, inputRef, {
+    validate: () => true,
+    invalidCode: 'INVALID_TODO_STRUCTURE_SET',
+  });
+}
+
 function mutationActor(env) {
   const entries = ACTOR_ENV_KEYS.map((key) => ({ key, value: env[key] }));
   const missingEnvironment = entries
@@ -1016,6 +1051,9 @@ async function dependencyConnect({
 async function phaseStatus({ repoRoot, planKey }) {
   const store = await readTodoStore({ repoRoot });
   const [member] = selectMembers(store, planKey);
+  const structureFinalization = await readTodoStructureFinalizationState({
+    repoRoot, store, planKey: member.plan.plan_key,
+  });
   // ADR 0147以降、phase無しplan(v1/v2/v3)もreadTodoStoreが導出済みの暗黙terminal-audit
   // Phaseをmember.phasesへ積んでいる(snapshot artifactの形式は変えない・v1にはphasesキーが
   // 無いのでsnapshot.phasesは直接読まない)。ここでPHASE_UNAVAILABLEへ拒否せず、その暗黙Phase
@@ -1027,13 +1065,26 @@ async function phaseStatus({ repoRoot, planKey }) {
   const phases = member.phases.map((phase) => ({
     ...phase,
     guidance: phase.status === 'gate_ready'
-      ? auditGateGuidance(member.plan.plan_key, phase.phase_id) : null,
+      ? [
+        auditGateGuidance(member.plan.plan_key, phase.phase_id),
+        ...(structureFinalization.required && structureFinalization.status !== 'fresh'
+          ? [`構造finalizationが${structureFinalization.status}です。先に lattice todo structure finalize --plan ${member.plan.plan_key} --json を実行してください。`]
+          : []),
+      ].join('\n') : null,
   }));
   const result = {
-    schema: 'lattice.phase_status_result.v1', project_id: store.project_id,
+    schema: 'lattice.phase_status_result.v2', 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,
-    implicit, phases, result_digest: '',
+    implicit, phases,
+    structure_finalization: {
+      enabled: structureFinalization.enabled, required: structureFinalization.required,
+      status: structureFinalization.status, reason: structureFinalization.reason,
+      stale_reasons: structureFinalization.stale_reasons,
+      next_command: structureFinalization.required && structureFinalization.status !== 'fresh'
+        ? `lattice todo structure finalize --plan ${member.plan.plan_key} --json` : null,
+    },
+    result_digest: '',
   };
   result.result_digest = todoSelfDigest(result, 'result_digest');
   return result;
@@ -1544,6 +1595,7 @@ async function status({ repoRoot }) {
     parallelCandidates: await readTodoParallelCandidatesForStatus({
       repoRoot, store, gitHead: currentHeadSha, changedPathsSince,
     }),
+    structureFinalizations: await readTodoStructureFinalizationsForStatus({ repoRoot, store }),
   });
 }
 
@@ -1737,6 +1789,500 @@ function requireCleanWorktree(repoRoot) {
   }
 }
 
+function structureGitIdentity(repoRoot, baselineSha, violations) {
+  let currentHeadSha = null;
+  try {
+    currentHeadSha = gitSync(['rev-parse', 'HEAD'], {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).replace(/\r?\n$/u, '');
+  } catch {
+    violations.push({
+      code: 'git_head_unresolved', path: '/baseline_sha',
+      expected: 'current repository HEAD commit', actual: null,
+      next_action: 'repair_git_head_then_rerun_structure_input_dry_run',
+    });
+    return { currentHeadSha: null };
+  }
+  if (!/^[0-9a-f]{40}$/u.test(currentHeadSha)) {
+    violations.push({
+      code: 'git_head_invalid', path: '/baseline_sha',
+      expected: '40 lowercase hex commit OID', actual: currentHeadSha,
+      next_action: 'repair_git_head_then_rerun_structure_input_dry_run',
+    });
+    return { currentHeadSha: null };
+  }
+  try {
+    gitSync(['cat-file', '-e', `${baselineSha}^{commit}`], {
+      cwd: repoRoot, stdio: ['ignore', 'ignore', 'ignore'],
+    });
+  } catch {
+    violations.push({
+      code: 'baseline_commit_unresolved', path: '/baseline_sha',
+      expected: 'commit object reachable in this repository', actual: baselineSha,
+      next_action: 'fetch_the_baseline_or_correct_baseline_sha',
+    });
+    return { currentHeadSha };
+  }
+  try {
+    gitSync(['merge-base', '--is-ancestor', baselineSha, currentHeadSha], {
+      cwd: repoRoot, stdio: ['ignore', 'ignore', 'ignore'],
+    });
+  } catch {
+    violations.push({
+      code: 'baseline_not_ancestor', path: '/baseline_sha',
+      expected: { ancestor_of: currentHeadSha }, actual: baselineSha,
+      next_action: 'select_an_ancestor_baseline_or_rebase_the_structure_input',
+    });
+  }
+  return { currentHeadSha };
+}
+
+async function analyzeStructureInput({ repoRoot, planKey, inputRef }) {
+  const structureSet = await readStructureSetDraft(repoRoot, inputRef);
+  const violations = [];
+  const explained = explainTodoStructureSet(structureSet);
+  if (!explained.valid) {
+    violations.push({
+      code: explained.reason,
+      path: explained.path,
+      ...(explained.detail === undefined ? {} : { actual: explained.detail }),
+      next_action: 'correct_the_reported_pointer_then_rerun_structure_input_dry_run',
+    });
+  }
+
+  const store = await readTodoStore({ repoRoot });
+  const member = store.members.find(({ descriptor }) => descriptor.plan_key === planKey) ?? null;
+  if (member === null) {
+    violations.push({
+      code: 'plan_not_active', path: '/plan_key', expected: planKey,
+      actual: typeof structureSet?.plan_key === 'string' ? structureSet.plan_key : null,
+      next_action: 'define_the_plan_before_adding_structure_input',
+    });
+  }
+
+  let currentHeadSha = null;
+  if (explained.valid && member !== null) {
+    const identities = [
+      ['project_id', store.project_id, structureSet.project_id],
+      ['plan_key', planKey, structureSet.plan_key],
+      ['plan_version', member.plan.plan_version, structureSet.plan_version],
+      ['topology_digest', member.plan.topology_digest, structureSet.topology_digest],
+    ];
+    for (const [field, expected, actual] of identities) {
+      if (actual !== expected) {
+        violations.push({
+          code: `${field}_mismatch`, path: `/${field}`, expected, actual,
+          next_action: 'regenerate_structure_input_for_the_active_plan_identity',
+        });
+      }
+    }
+    const expectedTaskIds = member.tasks.filter(({ status }) => status !== 'done')
+      .map(({ task_id: taskId }) => taskId);
+    const coverage = explainTodoStructureSet(structureSet, { expectedTaskIds });
+    if (!coverage.valid && ['coverage_missing', 'coverage_extra'].includes(coverage.reason)) {
+      violations.push({
+        code: coverage.reason, path: coverage.path,
+        expected: { task_ids: [...expectedTaskIds].sort() },
+        actual: coverage.detail,
+        next_action: 'list_every_unfinished_task_as_graph_or_excluded',
+      });
+    }
+    ({ currentHeadSha } = structureGitIdentity(repoRoot, structureSet.baseline_sha, violations));
+  }
+
+  const bounded = violations.slice(0, 64);
+  const result = {
+    schema: 'lattice.todo_structure_input_dry_run_result.v1',
+    valid: bounded.length === 0,
+    project_id: member?.plan.project_id ?? null,
+    plan_key: member?.plan.plan_key ?? planKey,
+    plan_version: member?.plan.plan_version ?? null,
+    input_ref: inputRef,
+    source_ref: todoStructureSourceRef(planKey),
+    current_head_sha: currentHeadSha,
+    violations: bounded,
+    overflow_count: Math.max(0, violations.length - bounded.length),
+    next_action: bounded.length === 0
+      ? `lattice todo structure input --plan ${planKey} --input ${inputRef}`
+      : 'correct_the_reported_violations_then_rerun_structure_input_dry_run',
+    result_digest: '',
+  };
+  result.result_digest = todoSelfDigest(result, 'result_digest');
+  return { result, structureSet };
+}
+
+async function structureInputDryRun({ repoRoot, planKey, inputRef }) {
+  return (await analyzeStructureInput({ repoRoot, planKey, inputRef })).result;
+}
+
+async function structureInput({ repoRoot, planKey, inputRef }) {
+  const analyzed = await analyzeStructureInput({ repoRoot, planKey, inputRef });
+  if (!analyzed.result.valid) {
+    throw new TodoStoreError('INVALID_TODO_STRUCTURE_SET', 'structure_input_dry_run_failed', undefined, {
+      violations: analyzed.result.violations,
+      overflow_count: analyzed.result.overflow_count,
+      next_action: `lattice todo structure input --plan ${planKey} --input ${inputRef} --dry-run --json`,
+    });
+  }
+  const written = await writeTodoStructureSource({ repoRoot, structureSet: analyzed.structureSet });
+  const result = {
+    schema: 'lattice.todo_structure_input_result.v1',
+    project_id: analyzed.structureSet.project_id,
+    plan_key: analyzed.structureSet.plan_key,
+    plan_version: analyzed.structureSet.plan_version,
+    topology_digest: analyzed.structureSet.topology_digest,
+    baseline_sha: analyzed.structureSet.baseline_sha,
+    structure_set_digest: analyzed.structureSet.structure_set_digest,
+    source_ref: written.ref,
+    enabled: false,
+    next_action: `commit ${written.ref}, then run lattice todo structure compile --plan ${planKey} --input ${written.ref}`,
+    result_digest: '',
+  };
+  result.result_digest = todoSelfDigest(result, 'result_digest');
+  return result;
+}
+
+function structurePlanMember(store, requestedPlanKey) {
+  if (requestedPlanKey !== null) {
+    const member = store.members.find(({ plan }) => plan.plan_key === requestedPlanKey);
+    if (member === undefined) {
+      throw new TodoStoreError('STRUCTURE_PLAN_NOT_FOUND', 'plan_not_active', undefined, {
+        plan_key: requestedPlanKey,
+      });
+    }
+    return member;
+  }
+  if (store.members.length !== 1) {
+    throw new TodoStoreError('STRUCTURE_PLAN_AMBIGUOUS', 'plan_selection_ambiguous', undefined, {
+      plan_keys: store.members.map(({ plan }) => plan.plan_key).sort(),
+      next_action: 'rerun_with_plan_flag',
+    });
+  }
+  return store.members[0];
+}
+
+function structureNextActions({ coverage, planKey, findings = [], staleReasons = [] }) {
+  const actions = [];
+  const add = (value) => { if (!actions.includes(value)) actions.push(value); };
+  if (coverage === 'missing') {
+    add(`lattice todo structure input --plan ${planKey} --input <structure-set.json> --dry-run --json`);
+    add(`lattice todo structure input --plan ${planKey} --input <structure-set.json>`);
+    add(`lattice todo structure compile --plan ${planKey} --input .lattice/todo/structure/${planKey}.json`);
+  } else if (['inconsistent', 'unknown'].includes(coverage)) {
+    findings.forEach(({ next_action: nextAction }) => add(nextAction));
+    add(`lattice todo structure input --plan ${planKey} --input <corrected-structure-set.json> --dry-run --json`);
+    add(`lattice todo structure compile --plan ${planKey} --input .lattice/todo/structure/${planKey}.json`);
+  } else if (coverage === 'stale') {
+    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 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 finalize --plan ${planKey} --json`);
+  }
+  return actions;
+}
+
+async function structureCompile({ repoRoot, env, planKey, inputRef }) {
+  const structureSet = await readStructureSetDraft(repoRoot, inputRef);
+  const explained = explainTodoStructureSet(structureSet);
+  if (!explained.valid) {
+    throw new TodoStoreError('INVALID_TODO_STRUCTURE_SET', explained.reason, undefined, {
+      input_ref: inputRef, path: explained.path,
+      next_action: `lattice todo structure input --plan ${planKey} --input ${inputRef} --dry-run --json`,
+    });
+  }
+  const store = await readTodoStore({ repoRoot });
+  const member = structurePlanMember(store, planKey);
+  const source = await readTodoStructureSource({ repoRoot, planKey });
+  if (source === null) {
+    throw new TodoStoreError('STRUCTURE_SOURCE_MISSING', 'planned_source_missing', undefined, {
+      plan_key: planKey,
+      next_action: `lattice todo structure input --plan ${planKey} --input ${inputRef}`,
+    });
+  }
+  if (canonicalizeTodoArtifact(source) !== canonicalizeTodoArtifact(structureSet)) {
+    throw new TodoStoreError('STRUCTURE_SOURCE_MISMATCH', 'compile_input_is_not_saved_source', undefined, {
+      input_ref: inputRef, source_ref: todoStructureSourceRef(planKey),
+      next_action: `lattice todo structure input --plan ${planKey} --input ${inputRef}`,
+    });
+  }
+  const existingBinding = await readTodoStructureBinding({
+    repoRoot, planKey, planVersion: member.plan.plan_version,
+  });
+  if (existingBinding !== null) {
+    throw new TodoStoreError('STRUCTURE_ALREADY_ENABLED', 'immutable_binding_exists', undefined, {
+      plan_key: planKey, plan_version: member.plan.plan_version,
+      next_action: `lattice todo structure --plan ${planKey} --json`,
+    });
+  }
+  const actor = mutationActor(env);
+  const observation = await collectTodoStructureAuthoritativeObservation({ repoRoot, structureSet });
+  const sourceEvidence = observation.source_evidence;
+  const gitProvenance = observation.git_provenance;
+  const realizations = [];
+  for (const task of structureSet.tasks.filter(({ applicability }) => applicability === 'graph')) {
+    realizations.push(...await readTodoStructureRealizationChain({
+      repoRoot, structureSet, taskId: task.task_id,
+    }));
+  }
+  const overlay = compileTodoStructureOverlay({
+    structureSet,
+    topology: mergedTopology(store),
+    taskStates: structureSet.tasks.map(({ task_id: taskId }) => ({
+      task_id: taskId,
+      status: member.tasks.find(({ task_id: id }) => id === taskId)?.status ?? 'pending',
+    })),
+    sourceProjection: sourceEvidence.projection,
+    gitProvenance,
+    realizations,
+  });
+  const compiledAt = new Date().toISOString();
+  const artifact = buildTodoStructureCompileArtifact({
+    structureSet, sourceProjection: sourceEvidence.projection, gitProvenance, overlay,
+    realizations, compiledAt, actor,
+  });
+  const written = await writeTodoStructureCompileArtifact({ repoRoot, artifact });
+  let bindingRef = null;
+  if (overlay.verdict === 'consistent') {
+    const binding = {
+      schema: TODO_STRUCTURE_BINDING_SCHEMA,
+      project_id: structureSet.project_id, plan_key: structureSet.plan_key,
+      plan_version: structureSet.plan_version, topology_digest: structureSet.topology_digest,
+      profile: structureSet.profile, baseline_sha: structureSet.baseline_sha,
+      structure_set_digest: structureSet.structure_set_digest,
+      compiled_head_sha: artifact.current_head_sha,
+      compile_artifact_digest: artifact.artifact_digest,
+      activated_at: compiledAt, actor, binding_digest: '',
+    };
+    binding.binding_digest = todoSelfDigest(binding, 'binding_digest');
+    bindingRef = (await writeTodoStructureBinding({ repoRoot, binding })).ref;
+  }
+  const nextActions = structureNextActions({
+    coverage: overlay.verdict, planKey, findings: overlay.findings,
+  });
+  const result = {
+    schema: 'lattice.todo_structure_compile_result.v1',
+    project_id: structureSet.project_id, plan_key: planKey,
+    plan_version: structureSet.plan_version, topology_digest: structureSet.topology_digest,
+    structure_set_digest: structureSet.structure_set_digest,
+    current_head_sha: artifact.current_head_sha,
+    verdict: overlay.verdict, enabled: bindingRef !== null,
+    artifact_ref: written.ref, binding_ref: bindingRef,
+    finding_summary: overlay.finding_summary, findings: overlay.findings,
+    next_actions: nextActions, result_digest: '',
+  };
+  result.result_digest = todoSelfDigest(result, 'result_digest');
+  return result;
+}
+
+async function readStructureRealizationInput(repoRoot, inputRef) {
+  let explained = null;
+  return readJsonInput(repoRoot, inputRef, {
+    validate: (value) => {
+      explained = explainTodoStructureRealization(value);
+      return explained.valid;
+    },
+    invalidCode: 'INVALID_TODO_STRUCTURE_REALIZATION',
+  }).catch((error) => {
+    if (error?.code === 'INVALID_TODO_STRUCTURE_REALIZATION' && 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')) {
+    realizations.push(...await readTodoStructureRealizationChain({
+      repoRoot, structureSet, taskId: task.task_id,
+    }));
+  }
+  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,
+      });
+  }
+  const appended = await appendTodoStructureRealization({ repoRoot, realization });
+  const structureSet = await readTodoStructureSource({ repoRoot, planKey });
+  const effective = await readCurrentStructureEffective(repoRoot, structureSet);
+  const taskProjection = effective.tasks.find(({ task_id: id }) => id === taskId);
+  const result = {
+    schema: 'lattice.todo_structure_realize_result.v1',
+    project_id: realization.project_id, plan_key: planKey,
+    plan_version: realization.plan_version, task_id: taskId,
+    realization_ref: appended.ref,
+    realization_digest: realization.realization_digest,
+    previous_realization_digest: appended.previous_realization_digest,
+    history_length: appended.history_length,
+    effective: taskProjection,
+    next_action: `lattice todo done --plan ${planKey} --task ${taskId} --evidence <file>`,
+    result_digest: '',
+  };
+  result.result_digest = todoSelfDigest(result, 'result_digest');
+  return result;
+}
+
+async function structureFinalize({ repoRoot, env, planKey }) {
+  const store = await readTodoStore({ repoRoot });
+  const member = structurePlanMember(store, planKey);
+  const source = await readTodoStructureSource({ repoRoot, planKey });
+  const binding = await readTodoStructureBinding({
+    repoRoot, planKey, planVersion: member.plan.plan_version,
+  });
+  if (source === null || binding === null
+    || source.structure_set_digest !== binding.structure_set_digest) {
+    throw new TodoStoreError('STRUCTURE_FINALIZATION_UNAVAILABLE',
+      'structure_not_enabled_or_stale', undefined, {
+        plan_key: planKey,
+        next_action: `lattice todo structure compile --plan ${planKey} --input .lattice/todo/structure/${planKey}.json`,
+      });
+  }
+  const incompleteTaskIds = member.tasks
+    .filter(({ status }) => status !== 'done')
+    .map(({ task_id: taskId }) => taskId).sort();
+  if (incompleteTaskIds.length > 0) {
+    throw new TodoStoreError('STRUCTURE_FINALIZATION_UNAVAILABLE',
+      'plan_not_fully_done', undefined, {
+        plan_key: planKey, incomplete_task_ids: incompleteTaskIds,
+      });
+  }
+  const realizations = [];
+  const effectiveTransforms = new Map();
+  for (const task of source.tasks.filter(({ applicability }) => applicability === 'graph')) {
+    const chain = await readTodoStructureRealizationChain({
+      repoRoot, structureSet: source, taskId: task.task_id,
+    });
+    const latest = chain.at(-1);
+    if (latest === undefined) {
+      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>`,
+        });
+    }
+    realizations.push(...chain);
+    effectiveTransforms.set(task.task_id, latest.realized);
+  }
+  const actor = mutationActor(env);
+  const observation = await collectTodoStructureAuthoritativeObservation({
+    repoRoot, structureSet: source, effectiveTransforms,
+  });
+  const sourceEvidence = observation.source_evidence;
+  const gitProvenance = observation.git_provenance;
+  const overlay = compileTodoStructureOverlay({
+    structureSet: source,
+    topology: mergedTopology(store),
+    taskStates: source.tasks.map(({ task_id: taskId }) => ({ task_id: taskId, status: 'done' })),
+    sourceProjection: sourceEvidence.projection,
+    gitProvenance,
+    realizations,
+  });
+  const artifact = buildTodoStructureCompileArtifact({
+    structureSet: source, sourceProjection: sourceEvidence.projection,
+    gitProvenance, overlay, realizations,
+    compiledAt: new Date().toISOString(), actor,
+  });
+  let finalizationRef = null;
+  if (overlay.verdict === 'consistent') {
+    finalizationRef = (await writeTodoStructureFinalization({ repoRoot, artifact })).ref;
+  }
+  const finalizationNextActions = [...new Set([
+    ...overlay.findings.map(({ next_action: nextAction }) => nextAction),
+    `lattice todo structure finalize --plan ${planKey} --json`,
+  ])];
+  const result = {
+    schema: 'lattice.todo_structure_finalize_result.v1',
+    project_id: source.project_id, plan_key: source.plan_key,
+    plan_version: source.plan_version, topology_digest: source.topology_digest,
+    structure_set_digest: source.structure_set_digest,
+    current_head_sha: artifact.current_head_sha,
+    realization_head_digest: artifact.realization_head_digest,
+    verdict: overlay.verdict, finalized: finalizationRef !== null,
+    finalization_ref: finalizationRef,
+    finalization_digest: finalizationRef === null ? null : artifact.artifact_digest,
+    finding_summary: overlay.finding_summary, findings: overlay.findings,
+    next_actions: finalizationRef === null
+      ? finalizationNextActions
+      : [`lattice todo phase status --plan ${planKey}`],
+    result_digest: '',
+  };
+  result.result_digest = todoSelfDigest(result, 'result_digest');
+  return result;
+}
+
+async function structure({ repoRoot, requestedPlanKey }) {
+  const store = await readTodoStore({ repoRoot });
+  const member = structurePlanMember(store, requestedPlanKey);
+  const state = await readTodoStructureState({
+    repoRoot, store, planKey: member.plan.plan_key,
+  });
+  const unboundVerdict = state.status === 'missing'
+    && state.reason === 'activation_binding_missing'
+    && ['inconsistent', 'unknown'].includes(state.compiled_verdict)
+    ? state.compiled_verdict : null;
+  const coverage = unboundVerdict
+    ?? (state.status === 'fresh' ? state.effective_verdict : state.status);
+  const findings = state.artifact?.overlay?.findings ?? [];
+  const source = await readTodoStructureSource({ repoRoot, planKey: member.plan.plan_key });
+  const effective = source !== null && source.plan_version === member.plan.plan_version
+    ? await readCurrentStructureEffective(repoRoot, source) : null;
+  const nextActions = structureNextActions({
+    coverage, planKey: member.plan.plan_key, findings, staleReasons: state.stale_reasons,
+  });
+  const finalization = await readTodoStructureFinalizationState({
+    repoRoot, store, planKey: member.plan.plan_key,
+  });
+  const result = {
+    schema: 'lattice.todo_structure_projection.v1',
+    project_id: store.project_id, plan_key: member.plan.plan_key,
+    plan_version: member.plan.plan_version, topology_digest: member.plan.topology_digest,
+    coverage, freshness: state.status,
+    enabled: state.binding_digest !== null,
+    structure_set_digest: state.structure_set_digest,
+    artifact_digest: state.artifact_digest,
+    compiled_verdict: state.compiled_verdict,
+    verdict: unboundVerdict ?? state.effective_verdict,
+    stale_reasons: state.stale_reasons,
+    graph: state.artifact?.overlay?.graph ?? null,
+    finding_summary: state.artifact?.overlay?.finding_summary ?? null,
+    findings,
+    effective,
+    finalization: {
+      required: finalization.required, status: finalization.status,
+      reason: finalization.reason, finalization_digest: finalization.finalization_digest,
+      stale_reasons: finalization.stale_reasons,
+    },
+    next_actions: nextActions,
+    result_digest: '',
+  };
+  result.result_digest = todoSelfDigest(result, 'result_digest');
+  return result;
+}
+
 async function independenceCompile({ repoRoot, planKey, inputRef }) {
   const witnessSet = await readWitnessSetInput(repoRoot, inputRef);
   requireCleanWorktree(repoRoot);
@@ -2378,13 +2924,14 @@ async function loadNarratives(store, repoRoot) {
  * 一つの関数だけが組む。
  */
 export async function ganttLiveHeadDigest({ repoRoot, store }) {
-  const [independence, seamProposals, noteHeads] = await Promise.all([
+  const [independence, seamProposals, noteHeads, structures] = await Promise.all([
     independenceForGantt({ repoRoot, store }),
     seamProposalsForGantt({ repoRoot, store }),
     noteHeadsForGantt({ repoRoot, store }),
+    loadTodoStructurePresentation({ repoRoot, readModel: store }),
   ]);
   return digestTodoArtifact({
-    schema: 'lattice.todo_gantt_live_head.v2',
+    schema: 'lattice.todo_gantt_live_head.v3',
     manifest_digest: store.manifest.manifest_digest,
     independence: independence === null ? null : independence.map((entry) => ({
       plan_key: entry.plan_key,
@@ -2397,6 +2944,7 @@ export async function ganttLiveHeadDigest({ repoRoot, store }) {
       projection_digest: digestTodoArtifact(entry),
     })),
     note_heads: noteHeads,
+    structure_projection_digest: structures.projection_digest,
   });
 }
 
@@ -2588,10 +3136,11 @@ export async function renderTodoGanttForProject({
   const presentation = await loadTodoGanttPresentation({ repoRoot, readModel: store });
   const topology = mergedTopology(store);
   const chain = projectTodoChainV1(topology);
-  const [independence, seamProposals, notes] = await Promise.all([
+  const [independence, seamProposals, notes, structures] = await Promise.all([
     independenceForGantt({ repoRoot, store }),
     seamProposalsForGantt({ repoRoot, store }),
     notesForGantt({ repoRoot, store }),
+    loadTodoStructurePresentation({ repoRoot, readModel: store }),
   ]);
   const layout = layoutTodoGantt(store, chain, { scope, independence, seamProposals });
   // When the diagram hides history, the page also carries the full diagram so
@@ -2626,6 +3175,7 @@ export async function renderTodoGanttForProject({
     chain_digest: digestTodoArtifact(chain),
     layout_digest: digestTodoArtifact(layout),
     note_bindings_digest: digestTodoArtifact(notes.headBindings),
+    structure_projection_digest: structures.projection_digest,
     renderer_version: TODO_GANTT_RENDERER_VERSION,
     project_display_name: identity.displayName,
     folded_task_count: layout.scope.folded_task_count,
@@ -2640,6 +3190,7 @@ export async function renderTodoGanttForProject({
     metadata,
     noteContexts: notes.contexts,
     noteWarnings: notes.warnings,
+    structurePresentation: structures,
   });
   return { store, metadata, memberBindings, rendered };
 }
@@ -2712,6 +3263,8 @@ function writesTodoStore(argv) {
     case 'snapshot': return argv.includes('--rebuild');
     case 'independence': return second === 'compile'
       || (second === 'witness' && ['migrate', 'scaffold'].includes(third));
+    case 'structure': return ['compile', 'realize', 'finalize'].includes(second)
+      || (second === 'input' && !argv.includes('--dry-run'));
     case 'seam-proposal': return ['compile', 'apply', 'land'].includes(second);
     case 'evidence': return second === 'promote';
     case 'dependency': return second === 'connect';
@@ -2876,6 +3429,22 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     });
   }
 
+  if (argv[0] === 'structure' && ['input', 'compile'].includes(argv[1])
+    && argv[4] === '--input' && typeof argv[5] === 'string' && path.isAbsolute(argv[5])) {
+    return typedArgumentFailure(stderr, 'INPUT_OUTSIDE_REPOSITORY', 'absolute_input_path_rejected', {
+      argument: '--input', expected: 'repo-relative path', actual: 'absolute path',
+      next_action: 'place_the_input_inside_the_repository_and_pass_a_repo_relative_path',
+    });
+  }
+
+  if (argv[0] === 'structure' && argv[1] === 'realize'
+    && argv[6] === '--input' && typeof argv[7] === 'string' && path.isAbsolute(argv[7])) {
+    return typedArgumentFailure(stderr, 'INPUT_OUTSIDE_REPOSITORY', 'absolute_input_path_rejected', {
+      argument: '--input', 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'
@@ -2986,6 +3555,40 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     action = (repoRoot) => independenceCompile({
       repoRoot, planKey: argv[3], inputRef: argv[5],
     });
+  } else if (argv.length === 8 && argv[0] === 'structure' && argv[1] === 'input'
+    && argv[2] === '--plan' && isTodoIdentifier(argv[3])
+    && argv[4] === '--input' && isTodoRef(argv[5])
+    && argv[6] === '--dry-run' && argv[7] === '--json') {
+    action = (repoRoot) => structureInputDryRun({
+      repoRoot, planKey: argv[3], inputRef: argv[5],
+    });
+  } else if (argv.length === 6 && argv[0] === 'structure' && argv[1] === 'input'
+    && argv[2] === '--plan' && isTodoIdentifier(argv[3])
+    && argv[4] === '--input' && isTodoRef(argv[5])) {
+    action = (repoRoot) => structureInput({
+      repoRoot, planKey: argv[3], inputRef: argv[5],
+    });
+  } else if (argv.length === 6 && argv[0] === 'structure' && argv[1] === 'compile'
+    && argv[2] === '--plan' && isTodoIdentifier(argv[3])
+    && argv[4] === '--input' && isTodoRef(argv[5])) {
+    action = (repoRoot) => structureCompile({
+      repoRoot, env, planKey: argv[3], inputRef: argv[5],
+    });
+  } else if (argv.length === 8 && argv[0] === 'structure' && argv[1] === 'realize'
+    && argv[2] === '--plan' && isTodoIdentifier(argv[3])
+    && argv[4] === '--task' && isTodoIdentifier(argv[5])
+    && argv[6] === '--input' && isTodoRef(argv[7])) {
+    action = (repoRoot) => structureRealize({
+      repoRoot, env, planKey: argv[3], taskId: argv[5], inputRef: argv[7],
+    });
+  } 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] });
+  } else if (argv.length === 2 && argv[0] === 'structure' && argv[1] === '--json') {
+    action = (repoRoot) => structure({ repoRoot, requestedPlanKey: null });
+  } else if (argv.length === 4 && argv[0] === 'structure'
+    && argv[1] === '--plan' && isTodoIdentifier(argv[2]) && argv[3] === '--json') {
+    action = (repoRoot) => structure({ repoRoot, requestedPlanKey: argv[2] });
   } else if ((argv.length === 1 && argv[0] === 'independence')
     || (argv.length === 2 && argv[0] === 'independence' && argv[1] === '--json')) {
     action = (repoRoot) => independence({ repoRoot, requestedPlanKey: null });