@quolu/lattice 0.47.0 → 0.49.0

package/src/todo-status.mjs

@@ -4,16 +4,26 @@ import {
   isAuditPendingPhaseStatus,
 } from './todo-audit-pending.mjs';
 import {
+  TODO_COORDINATION_MODES,
+  TODO_LIMITS,
   exactRecord,
   isNonNegativeSafeInteger,
+  isStrictTodoTimestamp,
   isTodoDigest,
   isTodoIdentifier,
   todoSelfDigest,
 } from './todo-contracts.mjs';
+import { TODO_INDEPENDENCE_COVERAGE } from './todo-independence-contracts.mjs';
 import { todoLegacyReconciliationDigest } from './todo-revision.mjs';
 import { isPhaselessTodoPlanSchema, todoPhaseDefinitions } from './todo-store.mjs';
 
-export const TODO_STATUS_SCHEMA = 'lattice.todo_status_result.v5';
+/**
+ * v6で`plan_notes`を足す。ADR 0054・0063の前例どおり既存versionへのin-place追加はしない。
+ *
+ * plan単位noteは工程に属する義務で、taskへ着手した人のcontextには届くが、**まだ誰も
+ * 着手していない工程の義務は、この欄が無いとどこにも出ない**。
+ */
+export const TODO_STATUS_SCHEMA = 'lattice.todo_status_result.v6';
 export const TODO_DISPATCH_FRONTIER_SCHEMA = 'lattice.todo_dispatch_frontier.v1';
 export const TODO_STATUS_LIST_LIMIT = 2_000;
 export const TODO_STATUS_LABEL_LIMIT = 160;
@@ -122,6 +132,104 @@ function auditPendingEntry(value) {
     && boundedList(value.next_commands, (command) => isTodoStatusBoundedText(command, TODO_STATUS_REASON_LIMIT));
 }
 
+function planNoteLatestEntry(value) {
+  return exactRecord(value, ['event_digest', 'actor_agent', 'recorded_at'])
+    && isTodoDigest(value.event_digest) && isTodoIdentifier(value.actor_agent)
+    && isStrictTodoTimestamp(value.recorded_at);
+}
+
+/**
+ * plan単位noteの要約1件。
+ *
+ * **本文を持たない。** 自由記述のMarkdownをここへinlineすると、noteを書くほど
+ * `TODO_STATUS_CAPTURE_LIMIT`へ近づき、健全なstoreが`TODO_SCALE_EXCEEDED`で落ちる
+ * ——「記録すると壊れる」面を作らない。載せるのは件数・帰属・次の一手までで、
+ * 中身は`next_commands`が指す`note list`が持つ。
+ *
+ * `plan_note_head_digest`は`note_context.note_head_digest`（task chain）と**別のchainのhead**なので、
+ * 名前で区別する。同名にすると型が同じdigestなので、取り違えてもexact validatorを通ってしまう。
+ *
+ * `count`は1以上（0件のplanはentryごと出さない）。`next_commands`が非空必須なのは
+ * `audit_pending`と同じ理由で、欄に出るだけで次の一手が無いなら次アクション面として無意味である。
+ */
+function planNoteEntry(value) {
+  return exactRecord(value, ['plan_key', 'plan_note_head_digest', 'count', 'latest', 'next_commands'])
+    && isTodoIdentifier(value.plan_key) && isTodoDigest(value.plan_note_head_digest)
+    && isNonNegativeSafeInteger(value.count) && value.count > 0
+    && Array.isArray(value.latest) && value.latest.length > 0
+    && value.latest.length <= Math.min(value.count, TODO_LIMITS.statusPlanNoteLatest)
+    && value.latest.every(planNoteLatestEntry)
+    && value.latest[0].event_digest === value.plan_note_head_digest
+    && Array.isArray(value.next_commands) && value.next_commands.length > 0
+    && boundedList(value.next_commands,
+      (command) => isTodoStatusBoundedText(command, TODO_STATUS_REASON_LIMIT));
+}
+
+/**
+ * 調整方式を宣言したplan 1件（ob03・オーナー裁定C①）。
+ *
+ * **宣言済みのplanだけを列挙する。** 未宣言を`mode: null`で全plan出すと、plan数ぶん常に
+ * 埋まって読み飛ばされる列になる——前campaignで`audit_pending`の設計時に避けた形と同じ。
+ * 未宣言は「`member_heads`に居て`coordination`に居ない」で引ける。
+ *
+ * `declared_by`が本体である。witnessが全planの暗黙義務だった時に無かったのが帰属で、
+ * ここを落とすとこの欄は「もう1つの督促」に戻る。
+ */
+function coordinationEntry(value) {
+  return exactRecord(value, ['plan_key', 'mode', 'declared_by', 'declared_at', 'reason'])
+    && isTodoIdentifier(value.plan_key)
+    && TODO_COORDINATION_MODES.includes(value.mode)
+    && exactRecord(value.declared_by, ['host', 'session', 'agent'])
+    && ['host', 'session', 'agent'].every((key) => isTodoStatusBoundedText(value.declared_by[key], TODO_STATUS_LABEL_LIMIT))
+    && isStrictTodoTimestamp(value.declared_at)
+    && isTodoStatusBoundedText(value.reason, TODO_STATUS_REASON_LIMIT);
+}
+
+/**
+ * 並列候補1 plan（ob05・オーナー裁定C③）。
+ *
+ * **新しい判定は1つも行わない。** ここに載るのは`projectIndependenceFrontier`が既に出している
+ * 結果を、候補の視点で並べ直したものだけである。並列できそうな組を選ぶのはAIの仕事で、
+ * 機械が持つのは「まだ判定していないreadyはこれ」「判定済みの結果はこれ」だけ
+ * ——推定・判断をLatticeの中へ実装しない（所有境界）。
+ *
+ * **ready taskを1つも持たないplanはentryごと出さない。** 全plan常に1行にすると、plan数ぶん
+ * 埋まって読み飛ばされる列になる（前campaignのwitness `coverage: missing`が実際にそうなった）。
+ *
+ * 逆に`coverage: 'missing'`のplanは**出す**。「まだ誰も判定していない」はこの欄が最も要る状態で、
+ * そこを飛ばすと沈黙が不在に見える。
+ */
+function parallelCandidateEntry(value) {
+  return exactRecord(value, [
+    'plan_key', 'coverage', 'unreadable_reason', 'unjudged_task_ids',
+    'verified_parallel_groups', 'serialize_pairs', 'next_commands',
+  ]) && isTodoIdentifier(value.plan_key)
+    // 読めない記録は`coverage`を名乗らず理由を名乗る（ADR 0131・`summarizeIndependence`と同じ答え方）。
+    // 「壊れている」を「まだ判定していない」へ丸めない。
+    && (value.unreadable_reason === null
+      ? TODO_INDEPENDENCE_COVERAGE.includes(value.coverage)
+      : value.coverage === null
+        && isTodoStatusBoundedText(value.unreadable_reason, TODO_STATUS_REASON_LIMIT))
+    && boundedList(value.unjudged_task_ids, isTodoIdentifier)
+    // 1件の組は並列の情報を持たない（taskは常に自分と並列である）。生産側が落としている以上、
+    // 契約側でも受けない——受けると消費者が「2件以上」を前提にできなくなる。
+    && boundedList(value.verified_parallel_groups, (group) => exactRecord(group, ['task_ids'])
+      && Array.isArray(group.task_ids) && group.task_ids.length > 1
+      && group.task_ids.every(isTodoIdentifier))
+    && boundedList(value.serialize_pairs, (pair) => exactRecord(pair, ['task_ids', 'type', 'detail'])
+      && Array.isArray(pair.task_ids) && pair.task_ids.length === 2
+      && pair.task_ids.every(isTodoIdentifier)
+      && isTodoStatusBoundedText(pair.type, TODO_STATUS_LABEL_LIMIT)
+      && isTodoStatusBoundedText(pair.detail, TODO_STATUS_REASON_LIMIT))
+    // 候補が在るのに次の一手が無い欄は、この工程が直している「欄だけ置いて閉じる」形になる。
+    && Array.isArray(value.next_commands) && value.next_commands.length > 0
+    && boundedList(value.next_commands,
+      (command) => isTodoStatusBoundedText(command, TODO_STATUS_REASON_LIMIT))
+    // 何も無いplanは出さない。空entryは「判定する対象が無い」と「判定が済んだ」を混ぜる。
+    && (value.unjudged_task_ids.length > 0 || value.verified_parallel_groups.length > 0
+      || value.serialize_pairs.length > 0);
+}
+
 function memberHead(value) {
   return exactRecord(value, [
     'plan_key', 'plan_version', 'through_sequence', 'journal_head_digest',
@@ -175,16 +283,20 @@ function dispatchFrontierEntry(value, projectId, nextReady) {
     && value.frontier_digest === expected.frontier_digest;
 }
 
-/** todo status v5 wire shapeを検証し、digestも再計算する。 */
+/** todo status v6 wire shapeを検証し、digestも再計算する。 */
 export function validateTodoStatusResult(value) {
   try {
     return exactRecord(value, [
       'schema', 'project_id', 'active_set', 'next_ready', 'dispatch_frontier',
-      'blocked', 'audit_pending', 'member_heads', 'result_digest',
+      'blocked', 'audit_pending', 'plan_notes', 'coordination', 'parallel_candidates',
+      'member_heads', 'result_digest',
     ]) && value.schema === TODO_STATUS_SCHEMA && isTodoIdentifier(value.project_id)
       && boundedList(value.active_set, activeTaskEntry) && boundedList(value.next_ready, taskEntry)
       && dispatchFrontierEntry(value.dispatch_frontier, value.project_id, value.next_ready)
       && boundedList(value.blocked, blockedEntry) && boundedList(value.audit_pending, auditPendingEntry)
+      && boundedList(value.plan_notes, planNoteEntry)
+      && boundedList(value.coordination, coordinationEntry)
+      && boundedList(value.parallel_candidates, parallelCandidateEntry)
       && boundedList(value.member_heads, memberHead)
       && isTodoDigest(value.result_digest)
       && value.result_digest === todoSelfDigest(value, 'result_digest');
@@ -249,6 +361,7 @@ function buildTodoGraph(readModel) {
   const incoming = new Map();
   const memberHeads = [];
   const auditPending = [];
+  const coordination = [];
   // snapshot artifactの形式(v1にはphasesキーが無い)には縛られない導出ビューを読む
   // (readTodoStoreが常にmember.phasesとして埋める。ADR 0147)。
   const phaseStatuses = new Map(readModel.members.flatMap((member) => (
@@ -296,6 +409,17 @@ function buildTodoGraph(readModel) {
     // snapshot artifactの形式には縛られない導出ビュー(member.phases)を読む(ADR 0147)。
     const phases = new Map((member.phases ?? []).map((state) => [state.phase_id, state]));
     collectAuditPending(member, auditPending);
+    // 調整方式の宣言(ob03)。member.coordinationはstoreがplan-scoped chainから投影した
+    // 導出ビューで、未宣言はnull。宣言済みだけをここへ載せる。
+    if (member.coordination !== null && member.coordination !== undefined) {
+      coordination.push({
+        plan_key: member.plan.plan_key,
+        mode: member.coordination.mode,
+        declared_by: member.coordination.declared_by,
+        declared_at: member.coordination.declared_at,
+        reason: displayText(member.coordination.reason, member.coordination.mode, TODO_STATUS_REASON_LIMIT),
+      });
+    }
     for (const task of member.plan.tasks) {
       const state = states.get(task.task_id);
       if (!plain(state) || !['pending', 'in-progress', 'blocked', 'done'].includes(state.status)) {
@@ -355,7 +479,10 @@ function buildTodoGraph(readModel) {
     left.plan_key < right.plan_key ? -1 : left.plan_key > right.plan_key ? 1
       : left.phase_id < right.phase_id ? -1 : left.phase_id > right.phase_id ? 1 : 0));
 
-  return { nodes, incoming, phaseAcceptIncoming, phaseStatuses, memberHeads, auditPending };
+  coordination.sort((left, right) => (
+    left.plan_key < right.plan_key ? -1 : left.plan_key > right.plan_key ? 1 : 0));
+
+  return { nodes, incoming, phaseAcceptIncoming, phaseStatuses, memberHeads, auditPending, coordination };
 }
 
 /** 先行完了とphase gateを満たしたpending taskだけがreadyになる。 */
@@ -389,10 +516,39 @@ export function computeReadyFrontier(readModel) {
   return ready;
 }
 
-/** Canonical todo read modelからSessionStart向け現在地をread-only投影する。 */
-export function projectTodoStatus(readModel) {
+/**
+ * dispatch面（`next_ready`／`active_set`／`dispatch_frontier`）だけを見る内部呼び出しが渡す明示の空。
+ *
+ * `todo start`のready判定・gantt・dashboardの生存判定は、statusのresultを**外へ出さない**。
+ * そこでnote chainを読むと、noteの破損がdispatch判定やdashboardの可視性を巻き添えに落とす
+ * ——ganttのnote破損は既に警告として表出する契約があり（`notesForGantt`）、二重に落とさない。
+ * この定数を使った結果をwireとして出力しないこと。`plan_notes`が常に空になる。
+ */
+export const TODO_STATUS_DISPATCH_ONLY = Object.freeze({
+  planNotes: Object.freeze([]), parallelCandidates: Object.freeze([]),
+});
+
+/**
+ * Canonical todo read modelからSessionStart向け現在地をread-only投影する。
+ *
+ * `planNotes`は**必須**である。plan単位noteはstore read modelに入っていない別chainなので、
+ * 読むのは呼び出し側の責務になる。省略を空配列へ丸めると「noteが無い」と「読まなかった」が
+ * 同じ形になり、配線を1箇所忘れただけで義務が静かに消える——それはこの欄が塞いでいる穴そのものである。
+ * 素材は`readTodoPlanNotesForStatus`（`src/todo-note-store.mjs`）が作り、resultを出力する
+ * 呼び出し元だけがそれを渡す。dispatch面しか見ない内部呼び出しは`TODO_STATUS_DISPATCH_ONLY`を使う。
+ */
+export function projectTodoStatus(readModel, options = undefined) {
+  if (!exactRecord(options, ['planNotes', 'parallelCandidates'])
+    || !Array.isArray(options.planNotes)) {
+    fail('TODO_STATUS_INVALID_INPUT', 'todo_status_plan_notes_missing');
+  }
+  if (!Array.isArray(options.parallelCandidates)) {
+    fail('TODO_STATUS_INVALID_INPUT', 'todo_status_parallel_candidates_missing');
+  }
   const graph = buildTodoGraph(readModel);
-  const { nodes, incoming, memberHeads, auditPending } = graph;
+  const { nodes, incoming, memberHeads, auditPending, coordination } = graph;
+  const planNotes = [...options.planNotes];
+  const parallelCandidates = [...options.parallelCandidates];
 
   const activeSet = [];
   const nextReady = [];
@@ -425,7 +581,9 @@ export function projectTodoStatus(readModel) {
   memberHeads.sort((left, right) => left.plan_key < right.plan_key ? -1 : left.plan_key > right.plan_key ? 1 : 0);
   for (const [name, value] of [
     ['active_set', activeSet], ['next_ready', nextReady], ['blocked', blocked],
-    ['audit_pending', auditPending], ['member_heads', memberHeads],
+    ['audit_pending', auditPending], ['plan_notes', planNotes],
+    ['coordination', coordination], ['parallel_candidates', parallelCandidates],
+    ['member_heads', memberHeads],
   ]) enforceListLimit(name, value);
 
   const result = {
@@ -438,6 +596,15 @@ export function projectTodoStatus(readModel) {
     // 監査待ちは`member.phases`だけから作った別の列で、dispatch(next_ready/dispatch_frontier)へは
     // 影響しない。監査が進んでもfrontier_digestは動かない。
     audit_pending: auditPending,
+    // plan単位noteも同じく別の列である。noteの有無・件数はdispatchへ影響しないので、
+    // next_ready・dispatch_frontier・frontier_digestはnoteを書いても1バイトも動かない。
+    plan_notes: planNotes,
+    // 調整方式の宣言も同じく別の列である。宣言はdispatchを変えない——未宣言でもready
+    // frontierは通常どおり出る(ADR 0160・ob04のProtected behavior)。
+    coordination,
+    // 並列候補も別の列である。判定が進んでもdispatchは動かない——next_ready・
+    // dispatch_frontier・frontier_digestは判定状態を1バイトも含まない（ADR 0063・ob04）。
+    parallel_candidates: parallelCandidates,
     member_heads: memberHeads,
     result_digest: '',
   };

package/src/todo-store.mjs

@@ -5,7 +5,9 @@ import {
 } from 'node:fs/promises';
 import path from 'node:path';
 import {
+  TODO_COORDINATION_MODES,
   TODO_LIMITS,
+  TODO_PLAN_SCOPED_EVENT_KINDS,
   canonicalizeTodoArtifact,
   digestTodoArtifact,
   exactRecord,
@@ -235,6 +237,57 @@ async function readJournal(repoRoot, journalRef) {
   return { segments, events, activeBytes };
 }
 
+/**
+ * planへ帰属するeventを積む、lifecycle journalとは別のchain（ob03）。
+ *
+ * 同じ`journal/active.jsonl`へ混ぜない。旧CLIの`validateTodoEvent`は`TODO_EVENT_KINDS`を
+ * exactで見るので、未知kindが1件混ざるとその**plan全体**が`STORE_CORRUPT`になる。journalは
+ * `todo status`の正本なので、混ぜると旧CLIから工程が読めなくなり、版を戻してもstoreは戻らない。
+ *
+ * 旧CLIの`readJournal`は`journal/active.jsonl`と`journal/sealed/*`を名指しで開くだけで、
+ * `journal/`自体をreaddirしない。version dir配下のfile一覧を厳密検査する経路も無い
+ * （`independence.json`が同じ性質で既に出荷されている・ADR 0127 Decision 1）。したがって
+ * 兄弟fileを置いても旧CLIは存在に気づかず、互換もrollbackも保たれる。
+ */
+function planScopedJournalRef(journalRef) {
+  return path.posix.join(path.posix.dirname(journalRef), 'plan-scoped.jsonl');
+}
+
+/**
+ * plan-scoped chainを読む。記録が無ければ空（「まだ何も宣言していない」）。
+ *
+ * lifecycle journalと違いgenesisを持たない——planの存在はjournalが証明しており、この
+ * chainはそこへ後から積まれる宣言だけを持つ。壊れている記録はnullや空へ丸めずtyped failにする。
+ */
+async function readPlanScopedJournal(repoRoot, journalRef) {
+  const ref = planScopedJournalRef(journalRef);
+  const absolute = path.resolve(repoRoot, ref);
+  let bytes;
+  try {
+    const state = await lstat(absolute);
+    if (state.isSymbolicLink() || !state.isFile()) fail('STORE_CORRUPT', 'plan_scoped_journal_unsafe');
+    bytes = await readFile(absolute);
+  } catch (error) {
+    if (error instanceof TodoStoreError) throw error;
+    if (error?.code === 'ENOENT') return { ref, events: [], activeBytes: Buffer.alloc(0) };
+    fail('STORE_CORRUPT', 'plan_scoped_journal_read_failed');
+  }
+  const events = parseJournalSegment(bytes);
+  if (!events.every(({ kind }) => TODO_PLAN_SCOPED_EVENT_KINDS.includes(kind))) {
+    fail('STORE_CORRUPT', 'plan_scoped_journal_kind_invalid');
+  }
+  const failures = verifyLinearHashChain({
+    entries: events,
+    canonicalize: canonicalizeTodoArtifact,
+    digestField: 'event_digest',
+    genesisPrevious: null,
+  });
+  if (failures.size > 0) {
+    fail('STORE_CORRUPT', [...failures].sort()[0], { failed_conditions: [...failures].sort() });
+  }
+  return { ref, events, activeBytes: bytes };
+}
+
 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 };
@@ -287,6 +340,29 @@ export function todoPhaseDefinitions(plan) {
   return phasesOf(plan);
 }
 
+/**
+ * planの調整方式の宣言を投影する（ob03・オーナー裁定C①）。
+ *
+ * 最後の`coordination_mode` eventが現在の宣言で、1件も無ければ未宣言（null）である。
+ * 未宣言は「witnessで行くと決めた」でも「会話で行くと決めた」でもなく、**まだ選んでいない**。
+ * 「誰が選んだか」はeventのactorが持つ——witnessが全planの暗黙義務だった時に帰属が無く、
+ * 正確な案内が素通りされたことへの是正なので、帰属を落とすとこの機構の意味が消える。
+ *
+ * 宣言はdispatchを変えない。未宣言でもready frontierは通常どおり出る（ADR 0160・ob04）。
+ */
+export function projectTodoCoordination(events) {
+  const declaration = [...events].reverse()
+    .find((event) => event.kind === 'coordination_mode');
+  if (declaration === undefined) return null;
+  return {
+    mode: declaration.payload.mode,
+    reason: declaration.payload.reason,
+    declared_by: declaration.actor,
+    declared_at: declaration.recorded_at,
+    event_digest: declaration.event_digest,
+  };
+}
+
 function derivedPhaseStatus(plan, taskStates, phaseStates, phaseId) {
   const state = phaseStates.get(phaseId);
   // ADR 0148: closed_unauditedも他の終端状態と同じく確定済みとして扱う。ここへ足さないと、
@@ -433,6 +509,10 @@ function replay(plan, events, { now = new Date(), verifyEvidence, verifyImportSo
       }
       continue;
     }
+    // planへ帰属するkindは別chain(plan-scoped.jsonl)へ積むので、通常はここへ来ない。
+    // 来た場合(旧形式のstoreや将来の移行)でもtask状態へ触れさせない——下の
+    // states.get(event.task_id)がnullを引いてevent_task_missingで落ちるのを防ぐ。
+    if (TODO_PLAN_SCOPED_EVENT_KINDS.includes(event.kind)) continue;
     if (event.kind.startsWith('phase_')) {
       // phaseStatesはphasesOf(plan)から作られる(v4/v5なら実Phase、それ以外なら暗黙の
       // terminal-audit Phaseだけ)。`has`判定だけで両方の場合を賄えるので、schemaでの
@@ -1133,8 +1213,13 @@ export async function readTodoStore(options = {}) {
     // phase無しplanのどちらでも同じ形(暗黙のterminal-audit Phase込み)で常に埋める。
     // 消費者はここを読み、snapshot.phases(v1には存在しない)を直接読まない。
     const phases = projectPhaseStates(plan, journal.events, new Map(tasks.map((task) => [task.task_id, task])));
-    loaded.push({ descriptor, plan, revision, journal, snapshot: snapshotStale ? expectedSnapshot : snapshot,
-      tasks, phases, snapshot_stale: snapshotStale });
+    // 調整方式の宣言(ob03)。lifecycle journalとは別chainから読む。phasesと同じく
+    // snapshot artifactの形式には縛られない導出ビューで、未宣言はnull（「まだ選んでいない」）。
+    const planScoped = await readPlanScopedJournal(repoRoot, descriptor.journal_ref);
+    const coordination = projectTodoCoordination(planScoped.events);
+    loaded.push({ descriptor, plan, revision, journal, plan_scoped: planScoped,
+      snapshot: snapshotStale ? expectedSnapshot : snapshot,
+      tasks, phases, coordination, snapshot_stale: snapshotStale });
   }
   validateMergedGraph(loaded);
   return {
@@ -1352,6 +1437,15 @@ export async function appendTodoEvent(options = {}) {
     const store = await readTodoStore({ repoRoot, forWrite: true, now: options.now });
     const member = store.members.find(({ descriptor }) => descriptor.plan_key === options.planKey);
     if (!member) fail('STORE_INCONSISTENT', 'plan_not_active');
+    // planへ帰属するeventは別chainへ積む(ob03)。task状態もPhase状態も動かさないので、
+    // replay・snapshot・manifestへは触れない——lifecycle journalのheadを進めるのは
+    // 「作業が進んだ」の意味であり、方式を選んだだけでそこを動かすと意味がずれる。
+    if (TODO_PLAN_SCOPED_EVENT_KINDS.includes(options.event.kind)) {
+      return appendPlanScopedEvent({
+        repoRoot, member,
+        input: { ...options.event, recorded_at: options.event.recorded_at ?? new Date().toISOString() },
+      });
+    }
     const input = resolveTargetedEvent({
       ...options.event,
       task_id: resolveCanonicalTaskId(member.plan, options.event.task_id),
@@ -1402,6 +1496,49 @@ export async function appendTodoEvent(options = {}) {
   });
 }
 
+/**
+ * plan-scoped chainへ1件積む（ob03）。
+ *
+ * lifecycle journalとは独立したsequenceとhash chainを持つ。`member_heads`の
+ * `through_sequence`／`journal_head_digest`は**task chainだけ**を指し続ける——
+ * 「この planの lifecycleがどこまで進んだか」という意味を、方式の宣言で動かさない
+ * （合成すると型も値域も同じまま意味だけずれ、消費者はexact検証を通してしまう）。
+ */
+async function appendPlanScopedEvent({ repoRoot, member, input }) {
+  const previous = member.plan_scoped.events.at(-1) ?? null;
+  const event = {
+    schema: 'lattice.todo_event.v3',
+    project_id: member.plan.project_id,
+    plan_key: member.plan.plan_key, plan_version: member.plan.plan_version,
+    // chainの先頭は sequence 0（`verifyLinearHashChain`は sequence 0 ⟺ previous_digest null を
+    // genesis束縛として検証する）。lifecycle journalのsequenceとは独立に数える。
+    sequence: previous === null ? 0 : previous.sequence + 1,
+    previous_digest: previous?.event_digest ?? null,
+    kind: input.kind, task_id: null, phase_id: null,
+    actor: input.actor, recorded_at: input.recorded_at,
+    provenance: input.provenance ?? null, payload: input.payload, event_digest: '',
+  };
+  event.event_digest = todoSelfDigest(event, 'event_digest');
+  if (!validateTodoEvent(event)) throw new TypeError('todo event input violates its declared schema');
+
+  const bytes = canonicalLine(event);
+  if (member.plan_scoped.activeBytes.length + bytes.length > TODO_LIMITS.journalSegmentBytes) {
+    // 宣言は1 planあたり数件の想定なので封緘機構は持たない。上限へ達したら黙って捨てず、
+    // typedに止めて「この設計では足りない」ことを表に出す。
+    fail('STORE_WRITE_REFUSED', 'plan_scoped_journal_segment_limit_exceeded', {
+      ref: member.plan_scoped.ref, limit: TODO_LIMITS.journalSegmentBytes,
+    });
+  }
+  await atomicWrite(path.resolve(repoRoot, member.plan_scoped.ref),
+    Buffer.concat([member.plan_scoped.activeBytes, bytes]));
+  const events = [...member.plan_scoped.events, event];
+  return {
+    event, plan: member.plan, snapshot: member.snapshot,
+    plan_scoped_head_digest: event.event_digest,
+    coordination: projectTodoCoordination(events),
+  };
+}
+
 export function buildTodoPlan(input) {
   const plan = { ...input, topology_digest: '', plan_digest: '' };
   plan.topology_digest = digestTodoArtifact({