@quolu/lattice 0.47.0 → 0.48.0

package/src/todo-note-store.mjs

@@ -8,6 +8,7 @@ import {
   TODO_LIMITS,
   TODO_NOTE_CONTEXT_SCHEMA,
   TODO_NOTE_EVENT_SCHEMA,
+  TODO_NOTE_EVENT_V2_SCHEMA,
   canonicalizeTodoArtifact,
   exactRecord,
   isTodoDigest,
@@ -45,10 +46,37 @@ function canonicalLine(value) {
   return Buffer.from(`${canonicalizeTodoArtifact(value)}\n`, 'utf8');
 }
 
+/**
+ * task noteとplan noteは**別のchain file**へ積む。
+ *
+ * 混ぜると、plan note(`todo_note_event.v2`)を1件書いた時点で、旧CLIにとってその planの
+ * chain全体が壊れたものになる——`parseCanonicalSegment`は1 eventずつbyte完全一致で検証し、
+ * 1件でも通らなければchainごと`NOTE_LOG_CORRUPT`で落とすためである。noteの読みは
+ * `todo start`の前提条件(fail closed)なので、**旧CLIでstartが通らなくなる**。しかも
+ * store��書いたものは戻せないので、rollbackで復旧できない。
+ *
+ * 旧readerが読むのは`active.jsonl`と`sealed/*`だけで、plan直下を列挙しない。別名のfileへ
+ * 積めば存在に気づかず、task noteの読み書きは1バイトも変わらない。旧CLIからplan noteは
+ * 見えないままだが、**旧CLIではplan noteを書けない以上、読めなくても行動が変わらない**。
+ */
 function notePaths(repoRoot, planKey) {
   if (!isTodoIdentifier(planKey)) throw new TypeError('planKey must be a todo identifier');
   const root = path.resolve(repoRoot, NOTE_ROOT_REF, planKey);
-  return { root, active: path.join(root, 'active.jsonl'), sealed: path.join(root, 'sealed') };
+  return {
+    root,
+    active: path.join(root, 'active.jsonl'),
+    sealed: path.join(root, 'sealed'),
+    planActive: path.join(root, 'plan-active.jsonl'),
+    planSealed: path.join(root, 'plan-sealed'),
+  };
+}
+
+/** chainごとのpathと、そのchainが受けるevent schema。 */
+function chainRefs(repoRoot, planKey, scope) {
+  const refs = notePaths(repoRoot, planKey);
+  return scope === 'plan'
+    ? { active: refs.planActive, sealed: refs.planSealed, schema: TODO_NOTE_EVENT_V2_SCHEMA }
+    : { active: refs.active, sealed: refs.sealed, schema: TODO_NOTE_EVENT_SCHEMA };
 }
 
 async function readOptionalBounded(ref, { missing = false } = {}) {
@@ -110,10 +138,15 @@ function validateEventChain(events, { projectId, planKey }) {
   }
 }
 
-/** planに属する独立note chainをbyte-levelで検証して読む。missingだけは空chainである。 */
+/**
+ * planに属する独立note chainをbyte-levelで検証して読む。missingだけは空chainである。
+ * `scope`で読むchainを選ぶ（既定はtask chain＝旧CLIと同じ経路・同じbyte）。
+ */
 export async function readTodoNoteEvents(options = {}) {
   const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
-  const { active, sealed } = notePaths(repoRoot, options.planKey);
+  const scope = options.scope ?? 'task';
+  if (!['plan', 'task'].includes(scope)) throw new TypeError('note chain scope must be plan or task');
+  const { active, sealed, schema } = chainRefs(repoRoot, options.planKey, scope);
   const names = await sealedFiles(sealed);
   const events = [];
   let previousSegmentDigest = ZERO_DIGEST;
@@ -132,6 +165,11 @@ export async function readTodoNoteEvents(options = {}) {
   }
   const activeBytes = await readOptionalBounded(active, { missing: true });
   if (activeBytes !== null) events.push(...parseCanonicalSegment(activeBytes, active));
+  // chainの分離は「そのfileへ何が積まれるか」で守る。混ざったchainは分離の意味を失うので
+  // 黙って受けず、読んだ時点でtypedに落とす。
+  if (events.some((event) => event.schema !== schema)) {
+    fail('NOTE_LOG_CORRUPT', 'note_chain_scope_mixed', { plan_key: options.planKey, scope });
+  }
   if (events.length > 0) {
     validateEventChain(events, { projectId: events[0].project_id, planKey: options.planKey });
   }
@@ -186,22 +224,32 @@ export async function appendTodoNote(options = {}) {
   if (!exactRecord(options, keys)
     || !Array.isArray(options.eligibleSupersedes)
     || !options.eligibleSupersedes.every(isTodoDigest)
-    || ![options.projectId, options.planKey, options.planVersion, options.taskId]
-    .every(isTodoIdentifier)) throw new TypeError('todo note append options invalid');
+    || ![options.projectId, options.planKey, options.planVersion].every(isTodoIdentifier)
+    // taskId nullがplan単位noteの指定。scopeはeventのschemaが持つ。
+    || !(options.taskId === null || isTodoIdentifier(options.taskId))) {
+    throw new TypeError('todo note append options invalid');
+  }
+  const planScoped = options.taskId === null;
+  const scope = planScoped ? 'plan' : 'task';
   const repoRoot = path.resolve(options.repoRoot);
   return withNoteLock(repoRoot, async () => {
-    const chain = await readTodoNoteEvents({ repoRoot, planKey: options.planKey });
+    // sequenceとprevious_digestはchainごとに独立。note系の起点は1（journal系の0ではない）。
+    const chain = await readTodoNoteEvents({ repoRoot, planKey: options.planKey, scope });
     if (options.supersedes !== null) {
       const target = chain.events.find(({ event_digest: digest }) => digest === options.supersedes);
       if (target === undefined || !options.eligibleSupersedes.includes(options.supersedes)) {
-        fail('NOTE_SUPERSEDES_INVALID', 'superseded_note_not_in_same_task', {
+        // plan noteはplan noteだけを、task noteは同じtaskのnoteだけを訂正できる。
+        // scopeを跨ぐ訂正を許すと、届く先が違うものを同じ履歴として畳むことになる。
+        fail('NOTE_SUPERSEDES_INVALID', planScoped
+          ? 'superseded_note_not_plan_scoped' : 'superseded_note_not_in_same_task', {
           plan_key: options.planKey, task_id: options.taskId,
         });
       }
     }
     const previous = chain.events.at(-1) ?? null;
     const event = {
-      schema: TODO_NOTE_EVENT_SCHEMA,
+      schema: planScoped ? TODO_NOTE_EVENT_V2_SCHEMA : TODO_NOTE_EVENT_SCHEMA,
+      ...(planScoped ? { scope: 'plan' } : {}),
       project_id: options.projectId,
       plan_key: options.planKey,
       task_id: options.taskId,
@@ -217,7 +265,7 @@ export async function appendTodoNote(options = {}) {
     event.event_digest = todoSelfDigest(event, 'event_digest');
     if (!validateTodoNoteEvent(event)) throw new TypeError('todo note event input invalid');
 
-    const paths = notePaths(repoRoot, options.planKey);
+    const paths = chainRefs(repoRoot, options.planKey, scope);
     const eventBytes = canonicalLine(event);
     if (chain.active_bytes.length > 0
       && chain.active_bytes.length + eventBytes.length > TODO_LIMITS.journalSegmentBytes) {
@@ -235,10 +283,12 @@ export async function appendTodoNote(options = {}) {
   });
 }
 
+/** v1(task note)とv2(plan note)を、明示`scope`を持つ1つの形へ正規化する。 */
 function noteProjectionEntry(event, supersededBy) {
   return {
     event_digest: event.event_digest,
     origin_plan_version: event.plan_version,
+    scope: event.schema === TODO_NOTE_EVENT_V2_SCHEMA ? 'plan' : 'task',
     origin_task_id: event.task_id,
     actor: event.actor,
     recorded_at: event.recorded_at,
@@ -302,37 +352,52 @@ function resolveNoteTarget(event, { currentPlanVersion, currentTaskIds, migratio
 export function projectTodoNoteContext(options = {}) {
   if (!exactRecord(options, [
     'projectId', 'planKey', 'currentPlanVersion', 'currentTaskId',
-    'currentTaskIds', 'events', 'migrations',
+    'currentTaskIds', 'events', 'planEvents', 'migrations',
   ]) || ![options.projectId, options.planKey, options.currentPlanVersion, options.currentTaskId]
     .every(isTodoIdentifier) || !Array.isArray(options.currentTaskIds)
     || !options.currentTaskIds.every(isTodoIdentifier)
     || !options.currentTaskIds.includes(options.currentTaskId)
-    || !Array.isArray(options.events) || !options.events.every(validateTodoNoteEvent)) {
+    || !Array.isArray(options.events) || !options.events.every(validateTodoNoteEvent)
+    || !Array.isArray(options.planEvents) || !options.planEvents.every(validateTodoNoteEvent)) {
     throw new TypeError('todo note projection options invalid');
   }
   const currentTaskIds = new Set(options.currentTaskIds);
   const migrations = migrationIndex(options.migrations);
+  // 訂正はscopeを跨げないので、supersedeの追跡もchainごとに閉じる。
   const supersededBy = new Map();
-  for (const event of options.events) {
+  for (const event of [...options.events, ...options.planEvents]) {
     if (event.project_id !== options.projectId || event.plan_key !== options.planKey) {
       fail('NOTE_LOG_CORRUPT', 'note_identity_mismatch');
     }
     if (event.supersedes !== null) supersededBy.set(event.supersedes, event.event_digest);
   }
 
-  const current = [];
+  const taskCurrent = [];
   const archived = [];
-  const sequenceByDigest = new Map(options.events.map((event) => [event.event_digest, event.sequence]));
+  const sequenceOf = (events) => new Map(events.map((event) => [event.event_digest, event.sequence]));
+  const taskSequence = sequenceOf(options.events);
+  const planSequence = sequenceOf(options.planEvents);
   for (const event of options.events) {
+    const entry = noteProjectionEntry(event, supersededBy.get(event.event_digest));
     const target = resolveNoteTarget(event, {
       currentPlanVersion: options.currentPlanVersion, currentTaskIds, migrations,
     });
-    const entry = noteProjectionEntry(event, supersededBy.get(event.event_digest));
     if (target.kind === 'archived') archived.push(entry);
-    else if (target.taskId === options.currentTaskId) current.push(entry);
+    else if (target.taskId === options.currentTaskId) taskCurrent.push(entry);
   }
-  current.sort((left, right) => sequenceByDigest.get(right.event_digest)
-    - sequenceByDigest.get(left.event_digest));
+  // plan noteは特定のtaskに属さないので、task migrationで宛先を失うことがない。全taskの
+  // contextへ載せる——工程レベルの義務は「次に着手する誰か」へ届くべきもので、誰が着手するかは
+  // 書いた時点で分からない。
+  const planCurrent = options.planEvents
+    .map((event) => noteProjectionEntry(event, supersededBy.get(event.event_digest)));
+  taskCurrent.sort((left, right) => taskSequence.get(right.event_digest)
+    - taskSequence.get(left.event_digest));
+  planCurrent.sort((left, right) => planSequence.get(right.event_digest)
+    - planSequence.get(left.event_digest));
+  // 2本のsequenceは独立なので、混ぜた全順序は時刻にもsequenceにも作れない（時刻は
+  // future_clock_skewがある以上信用できない）。決定的な規則で並べる: plan単位の申し送りは
+  // task固有のものより文脈が広いので先に読ませる。
+  const current = [...planCurrent, ...taskCurrent];
   archived.reverse();
 
   const notes = [];
@@ -349,10 +414,14 @@ export function projectTodoNoteContext(options = {}) {
     plan_key: options.planKey,
     task_id: options.currentTaskId,
     notes,
-    note_head_digest: current[0]?.event_digest ?? null,
+    // headはchainごとに言う。合成すると「どちらのheadか」と連結順を定義する必要が生まれ、
+    // 順序が決まっていなければ同じ状態から違うdigestが出る。
+    note_head_digest: taskCurrent[0]?.event_digest ?? null,
+    plan_note_head_digest: planCurrent[0]?.event_digest ?? null,
+    // overflowはcontext全体の予算の話でchainの性質ではないので、ここは合成でよい。
     overflow_count: current.length - notes.length,
-    full_history_command: `lattice todo note list --plan ${options.planKey}`
-      + ` --task ${options.currentTaskId} --json`,
+    // plan noteを載せる以上、案内はplan全体を返す形でなければ「full」ではない。
+    full_history_command: `lattice todo note list --plan ${options.planKey} --json`,
     context_digest: '',
   };
   context.context_digest = todoSelfDigest(context, 'context_digest');
@@ -450,6 +519,7 @@ export async function readTodoNoteContext(options = {}) {
     plan_key: options.planKey, task_id: options.taskId,
   });
   const chain = await readTodoNoteEvents({ repoRoot, planKey: options.planKey });
+  const planChain = await readTodoNoteEvents({ repoRoot, planKey: options.planKey, scope: 'plan' });
   const migrations = await readNoteMigrations(repoRoot, options.planKey,
     new Set(chain.events.map(({ plan_version: version }) => version)));
   return projectTodoNoteContext({
@@ -459,10 +529,65 @@ export async function readTodoNoteContext(options = {}) {
     currentTaskId: task.task_id,
     currentTaskIds: member.plan.tasks.map(({ task_id: taskId }) => taskId),
     events: chain.events,
+    planEvents: planChain.events,
     migrations,
   });
 }
 
+/**
+ * status面の`plan_notes`欄の素材を、store内の全planぶん一度に読む。
+ *
+ * plan単位noteは「工程に属する義務」で、着手する誰かのcontextへは届くが、**まだ誰も
+ * 着手していない工程の義務はどこにも出ない**。statusはそれを出す唯一の面なので、
+ * ここでは本文を一切運ばない——載せるのは件数・帰属・次の一手だけで、中身は
+ * `note list`が持つ（`audit_pending`が330字のproseを落としたのと同じ判断・ADR 0159）。
+ *
+ * noteを持たないplanはentryごと出さない。「全plan常に1行」は、前campaignの
+ * witness `coverage: missing`と同じ「満杯で始まるので読み飛ばされる欄」になる。
+ *
+ * chainが壊れているplanが1つでもあれば`readTodoNoteEvents`のtyped errorがそのまま出る
+ * （fail closed）。壊れた義務記録を「義務なし」と同じ空へ丸めない。
+ */
+export async function readTodoPlanNotesForStatus(options = {}) {
+  if (!exactRecord(options, ['repoRoot', 'store'])
+    || options.store === null || typeof options.store !== 'object'
+    || !Array.isArray(options.store.members)) {
+    throw new TypeError('todo plan notes read options invalid');
+  }
+  const repoRoot = path.resolve(options.repoRoot);
+  const summaries = [];
+  for (const member of options.store.members) {
+    const planKey = member.plan.plan_key;
+    // plan noteは専用chainに在る。schemaでの選別は要らない——読む先そのものが分かれている。
+    const chain = await readTodoNoteEvents({ repoRoot, planKey, scope: 'plan' });
+    const superseded = new Set(chain.events
+      .filter(({ supersedes }) => supersedes !== null)
+      .map(({ supersedes }) => supersedes));
+    // 訂正されたnoteは数えない。数えると訂正するほど件数が増える。
+    const current = chain.events
+      .filter((event) => !superseded.has(event.event_digest))
+      .sort((left, right) => right.sequence - left.sequence);
+    if (current.length === 0) continue;
+    summaries.push({
+      plan_key: planKey,
+      // `note_context.note_head_digest`はtask chainのheadを指す。同名で別のchainを指すと
+      // 型が同じdigestなので取り違えてもvalidatorを通る——名前で区別する（room [211]）。
+      plan_note_head_digest: current[0].event_digest,
+      count: current.length,
+      latest: current.slice(0, TODO_LIMITS.statusPlanNoteLatest).map((event) => ({
+        event_digest: event.event_digest,
+        actor_agent: event.actor.agent,
+        recorded_at: event.recorded_at,
+      })),
+      // 欄だけでは読まれない。届いた先で次に何を打てばいいかを名指しする。
+      next_commands: [`lattice todo note list --plan ${planKey} --json`],
+    });
+  }
+  summaries.sort((left, right) => (
+    left.plan_key < right.plan_key ? -1 : left.plan_key > right.plan_key ? 1 : 0));
+  return summaries;
+}
+
 /** Gantt用に1 planのchain/historyを一度だけ読み、全task contextへ投影する。 */
 export async function readTodoNoteContextsForPlan(options = {}) {
   if (!exactRecord(options, ['repoRoot', 'store', 'planKey'])
@@ -478,6 +603,7 @@ export async function readTodoNoteContextsForPlan(options = {}) {
     plan_key: options.planKey,
   });
   const chain = await readTodoNoteEvents({ repoRoot, planKey: options.planKey });
+  const planChain = await readTodoNoteEvents({ repoRoot, planKey: options.planKey, scope: 'plan' });
   const migrations = await readNoteMigrations(repoRoot, options.planKey,
     new Set(chain.events.map(({ plan_version: version }) => version)));
   const currentTaskIds = member.plan.tasks.map(({ task_id: taskId }) => taskId);
@@ -488,6 +614,7 @@ export async function readTodoNoteContextsForPlan(options = {}) {
     currentTaskId: task.task_id,
     currentTaskIds,
     events: chain.events,
+    planEvents: planChain.events,
     migrations,
   }));
   return {

package/src/todo-parallel-candidates.mjs

@@ -0,0 +1,114 @@
+/**
+ * status面の`parallel_candidates`欄の素材（ob05・オーナー裁定C③）。
+ *
+ * **判定は1つも行わない。** ここに載るのは`projectIndependenceFrontier`が既に出している結果を
+ * 候補の視点で並べ直したものだけである。並列できそうな組を選ぶのはAIの仕事で、機械が持つのは
+ * 「まだ判定していないreadyはこれ」「判定済みの結果はこれ」だけ——推定・判断をLatticeの中へ
+ * 実装しない（所有境界）。
+ *
+ * `independenceForGantt`と違い、**記録が無いplanを飛ばさない**。artifactがnullの状態は
+ * 「まだ誰も判定していない」であって、この欄が最も要る場面である。飛ばすと沈黙が不在に見える。
+ *
+ * `todo status`と`lattice status`の両方が使うので、どちらのCLIにも属さない場所へ置く。
+ * gitの読みは呼び出し側から渡す（`gitHead`／`changedPathsSince`）——このmoduleがgitの
+ * 呼び方を決めると、2つのCLIが持つ既存の作法を上書きすることになる。
+ */
+
+import { projectIndependenceFrontier } from './todo-independence.mjs';
+import { readTodoIndependenceArtifact } from './todo-store.mjs';
+import { TODO_STATUS_DISPATCH_ONLY, computeReadyFrontier, projectTodoStatus } from './todo-status.mjs';
+
+/** 記録が無いplanでは鮮度を見ないので、HEADの代わりに使う。project-cliと同じ作法。 */
+const PLACEHOLDER_SHA = '0'.repeat(40);
+
+const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+
+export async function readTodoParallelCandidatesForStatus(options = {}) {
+  const { repoRoot, store, gitHead, changedPathsSince = () => null } = options;
+  const frontier = computeReadyFrontier(store);
+  const status = projectTodoStatus(store, TODO_STATUS_DISPATCH_ONLY);
+  let currentBaseSha = null;
+  const candidates = [];
+  for (const member of store.members) {
+    const planKey = member.plan.plan_key;
+    const readyTaskIds = frontier.filter((task) => task.plan_key === planKey)
+      .map(({ task_id: taskId }) => taskId);
+    let artifact = null;
+    let unreadableReason = null;
+    try {
+      artifact = await readTodoIndependenceArtifact({ repoRoot, store, planKey });
+    } catch (error) {
+      // 読めない記録を「記録なし」へ丸めない（ADR 0131）。丸めると「壊れている」が
+      // 「まだ判定していない」と同じ形になり、沈黙が不在に見える。理由を載せて先へ進む
+      // ——1 planの壊れでstatus面ごと落とすと、他planの候補まで見えなくなる。
+      // `summarizeIndependence`（project-cli）と同じ答え方に揃える。
+      unreadableReason = error?.code
+        ? `${error.code}:${error.detail?.reason ?? error.message}` : 'independence_unreadable';
+    }
+    // ready taskが1つも無く記録も無いplanは、判定する対象そのものが無い。entryごと出さない。
+    if (readyTaskIds.length === 0 && artifact === null && unreadableReason === null) continue;
+    // HEADが要るのは鮮度の判定だけである。記録が1つも無いplanでHEADを引くと、commitの無い
+    // repo（初期化直後・test fixture）で`git_head_unresolved`に落ちる——判定していない
+    // planを見るために、判定に使わない値の解決を要求してはいけない。
+    if (artifact !== null && currentBaseSha === null) {
+      try {
+        currentBaseSha = gitHead(repoRoot);
+      } catch (error) {
+        // HEADが解決できない（commitが1つも無いrepo等）なら鮮度を判定できない。
+        // placeholderで代用すると「判定済みだが古い」と断言することになる——
+        // 知らないことを知っていると言わない。1 planの事情で面ごと落とさないのも同じ理由。
+        unreadableReason = error?.code
+          ? `${error.code}:${error.detail?.reason ?? error.message}` : 'independence_base_unresolved';
+      }
+    }
+    if (unreadableReason !== null) {
+      candidates.push({
+        plan_key: planKey,
+        // 壊れた記録から判定は読めない。coverageは名乗らず、理由を名乗る。
+        coverage: null,
+        unreadable_reason: unreadableReason,
+        unjudged_task_ids: readyTaskIds,
+        verified_parallel_groups: [],
+        serialize_pairs: [],
+        next_commands: [`lattice todo independence compile --plan ${planKey} --input <file>`],
+      });
+      continue;
+    }
+    const baseSha = currentBaseSha ?? PLACEHOLDER_SHA;
+    const changedPaths = artifact !== null && artifact.base_sha !== null
+      && artifact.base_sha !== baseSha
+      ? changedPathsSince(repoRoot, artifact.base_sha) : null;
+    const projected = projectIndependenceFrontier({
+      artifact,
+      readyTaskIds,
+      activeTaskIds: status.active_set.filter((task) => task.plan_key === planKey)
+        .map(({ task_id: taskId }) => taskId),
+      plan: member.plan,
+      currentBaseSha: baseSha,
+      changedPaths,
+    });
+    const unjudged = projected.frontier.unknown.map(({ task_id: taskId }) => taskId);
+    // 1件だけの「並列group」は並列の情報を持たない（1つのtaskは常に自分と並列である）。
+    const groups = projected.frontier.parallel_groups
+      .filter((group) => group.task_ids.length > 1)
+      .map(({ task_ids: taskIds }) => ({ task_ids: taskIds }));
+    const pairs = projected.frontier.serialize_pairs.map((pair) => ({
+      task_ids: pair.task_ids, type: pair.type, detail: pair.detail,
+    }));
+    if (unjudged.length === 0 && groups.length === 0 && pairs.length === 0) continue;
+    candidates.push({
+      plan_key: planKey,
+      coverage: projected.coverage,
+      unreadable_reason: null,
+      unjudged_task_ids: unjudged,
+      verified_parallel_groups: groups,
+      serialize_pairs: pairs,
+      // 欄だけ置いて閉じない。未判定が残るなら宣言してcompile、済んでいるなら読み出し。
+      next_commands: unjudged.length > 0
+        ? [`lattice todo independence compile --plan ${planKey} --input <file>`]
+        : [`lattice todo independence --plan ${planKey} --json`],
+    });
+  }
+  candidates.sort((left, right) => compareText(left.plan_key, right.plan_key));
+  return candidates;
+}