@quolu/lattice 0.36.0 → 0.37.0

package/src/todo-cli.mjs

@@ -416,6 +416,26 @@ function mutationActor(env) {
   return { host: entries[0].value, session: entries[1].value, agent: entries[2].value };
 }
 
+/**
+ * gate_readyの札が出た理由と次の一歩をtypedに言う(ADR 0148裁定8)。
+ *
+ * 0.36.0で入れた終端監査gate(ADR 0147)は、これから終わる工程だけでなく過去に完了した
+ * 工程まで監査待ちにしてしまっていた——原因を言わないgateは、なぜ止まっているかを
+ * 説明しないのと同じなので、ここでその経緯を明示する。次の一歩は2択で書く:
+ * 今から監査する(review→accept)か、監査せず歴史として閉じる(close-unaudited、
+ * 複数plan一括ならbaseline)か。
+ */
+function auditGateGuidance(planKey, phaseId) {
+  return '全ToDoがdoneになり監査待ち(gate_ready)。0.36.0で入れた終端監査gateは、'
+    + 'これから終わる工程だけでなく過去に完了した工程まで監査待ちにしてしまっていた'
+    + '(ADR 0148で修正)。今から監査するなら: '
+    + `todo phase review --plan ${planKey} --phase ${phaseId} --reason <text> → `
+    + `todo phase accept --plan ${planKey} --phase ${phaseId} --input <file>。`
+    + '監査せず歴史として閉じるなら: '
+    + `todo phase close-unaudited --plan ${planKey} --phase ${phaseId} --reason <text>`
+    + '（複数planをまとめて畳むなら todo phase baseline --reason <text> [--except <plan_key>]...）。';
+}
+
 /**
  * phase無しplanで、この変異の結果terminal-audit Phaseがgate_ready(全task done・未監査)に
  * なっていれば助言を返す(ADR 0147)。doneの結果だけを見て機械的に判定するので、既にreview
@@ -429,9 +449,7 @@ function terminalAuditDoneAdvisory(plan, phases) {
   if (phase?.status !== 'gate_ready') return null;
   return {
     terminal_audit_required: true, phase_id: TERMINAL_AUDIT_PHASE_ID, status: phase.status,
-    guidance: '全taskがdoneになった。このplanはphaseを持たないため、終端の重監査'
-      + '(todo phase review --plan <key> --phase terminal-audit → todo phase accept)を'
-      + '経るまで「閉じた」ことにはならない。',
+    guidance: auditGateGuidance(plan.plan_key, TERMINAL_AUDIT_PHASE_ID),
   };
 }
 
@@ -705,11 +723,110 @@ async function phaseStatus({ repoRoot, planKey }) {
   // 無いのでsnapshot.phasesは直接読まない)。ここでPHASE_UNAVAILABLEへ拒否せず、その暗黙Phase
   // をそのまま返す——`implicit`で機械可読に「宣言されたPhaseではない」ことを示す。
   const implicit = isPhaselessTodoPlanSchema(member.plan.schema);
+  // ADR 0148裁定8: gate_readyのPhaseには、なぜ監査待ちになったかと次の一歩をここでも言う
+  // (todo doneのadvisoryと同じ文言)。implicit(暗黙のterminal-audit Phase)に限らず、
+  // v4/v5の実Phaseがgate_readyになった場合も同じ理由で同じ案内が要る。
+  const phases = member.phases.map((phase) => ({
+    ...phase,
+    guidance: phase.status === 'gate_ready'
+      ? auditGateGuidance(member.plan.plan_key, phase.phase_id) : null,
+  }));
   const result = {
     schema: 'lattice.phase_status_result.v1', project_id: store.project_id,
     plan_key: member.plan.plan_key, plan_version: member.plan.plan_version,
     journal_head_digest: member.journal.events.at(-1).event_digest,
-    implicit, phases: member.phases, result_digest: '',
+    implicit, phases, result_digest: '',
+  };
+  result.result_digest = todoSelfDigest(result, 'result_digest');
+  return result;
+}
+
+/**
+ * `phase baseline --reason <text> [--except <plan_key>]...`の可変長`--except`を解析する。
+ * 他のargvはすべて固定位置(argv.length + 位置一致)で判定しているが、0回以上繰り返せる
+ * flagだけは固定位置で表現できないため、並び全体を見る専用ヘルパへ切り出す
+ * (bridge-cliの`parseOptions`と同じ発想)。不正な並びはnullを返し、呼び出し側の
+ * 分岐条件がそのままusageFailureへ落ちる。
+ */
+function parseBaselineExceptFlags(rest) {
+  if (rest.length % 2 !== 0) return null;
+  const planKeys = [];
+  for (let index = 0; index < rest.length; index += 2) {
+    if (rest[index] !== '--except' || !isTodoIdentifier(rest[index + 1])) return null;
+    planKeys.push(rest[index + 1]);
+  }
+  return planKeys;
+}
+
+/**
+ * `phase baseline`——現在gate_readyかつphase eventを1つも持たないPhaseを一括で
+ * closed_unauditedへ宣言する(ADR 0148裁定6)。「phase eventを1つも持たない」は
+ * derivedStatusだけでは判定できない——一度reviewしてからreopenしたPhaseは、構造的には
+ * また`gate_ready`に戻り得るが、既に監査に触れている以上は対象外である。journalの実event
+ * 履歴(phase_id別に`phase_`で始まるkindがあるか)を直接見て区別する。
+ *
+ * `--except`はplan単位の除外(ADR 0148裁定7)。ServerManagerの26 ToDoのような
+ * 「最近の作業でコードも生きている」campaignを基準線で流さないための口であり、
+ * Phase単位では絞れない(そのplanのPhaseは丸ごと対象外になる)。
+ */
+async function phaseBaseline({ repoRoot, env, reason, exceptPlanKeys }) {
+  const store = await readTodoStore({ repoRoot });
+  const knownPlanKeys = new Set(store.members.map(({ descriptor }) => descriptor.plan_key));
+  const unknownExcept = exceptPlanKeys.filter((planKey) => !knownPlanKeys.has(planKey));
+  if (unknownExcept.length > 0) {
+    throw new TodoStoreError('PHASE_BASELINE_INVALID', 'except_plan_key_unknown', undefined, {
+      unknown_plan_keys: unknownExcept,
+    });
+  }
+  const exceptSet = new Set(exceptPlanKeys);
+  const applied = [];
+  const excluded = [];
+  const notApplicable = [];
+  const failed = [];
+  for (const member of store.members) {
+    const planKey = member.descriptor.plan_key;
+    const touchedPhaseIds = new Set(member.journal.events
+      .filter((event) => event.kind.startsWith('phase_'))
+      .map((event) => event.phase_id));
+    for (const phase of member.phases) {
+      const entry = { plan_key: planKey, phase_id: phase.phase_id, status: phase.status };
+      // 「対象外だったもの(既にaccepted等)も区別して返す」——まだgate_readyに到達していない
+      // (locked/active)のと、既に監査の決着が付いている(accepted/rejected/closed_unaudited)のは
+      // 原因が違うので、causeを分けて機械可読にする。
+      if (['accepted', 'rejected', 'closed_unaudited'].includes(phase.status)) {
+        notApplicable.push({ ...entry, cause: `already_${phase.status}` });
+      } else if (phase.status !== 'gate_ready') {
+        notApplicable.push({ ...entry, cause: 'not_gate_ready' });
+      } else if (touchedPhaseIds.has(phase.phase_id)) {
+        notApplicable.push({ ...entry, cause: 'already_has_phase_event' });
+      } else if (exceptSet.has(planKey)) {
+        excluded.push({ ...entry, cause: 'excepted' });
+      } else {
+        // ADR 0148裁定6の非目標: journalはappend-onlyで、一度書いた宣言を後から取り消す
+        // 手段が無い。1件失敗しても既に書けた他件を無かったことにはできない以上、
+        // 全件一括のtransactionは新設せず、appendTodoEvent単位(1 event = 1排他書込み)の
+        // 独立実行を続ける。各書込みは呼ぶたびにstoreを読み直してgate_ready前提を
+        // 再検証するため、他項目の成否とは無関係に安全である——1件の失敗で残りを
+        // 止めず、続行して全件の結果をtypedで返す。
+        try {
+          const result = await phaseMutation({
+            repoRoot, env, planKey, phaseId: phase.phase_id,
+            kind: 'phase_close_unaudited', payload: { reason },
+          });
+          applied.push({ ...entry, event_digest: result.event_digest,
+            journal_head_digest: result.journal_head_digest });
+        } catch (error) {
+          failed.push({ ...entry, code: error?.code ?? 'INTERNAL_FAILURE',
+            message: typeof error?.message === 'string' ? error.message : null });
+        }
+      }
+    }
+  }
+  const result = {
+    schema: 'lattice.phase_baseline_result.v1',
+    reason, except_plan_keys: [...exceptSet].sort(),
+    applied, excluded, not_applicable: notApplicable, failed,
+    result_digest: '',
   };
   result.result_digest = todoSelfDigest(result, 'result_digest');
   return result;
@@ -2148,6 +2265,17 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     && (argv.length === 8 || (argv[8] === '--override-reason' && argv[9].length > 0))) {
     action = (repoRoot) => phaseMutation({ repoRoot, env, planKey: argv[3], phaseId: argv[5],
       kind: 'phase_reopen', payload: { reason: argv[7], override_reason: argv[9] ?? null } });
+  } else if (argv.length === 8 && argv[0] === 'phase' && argv[1] === 'close-unaudited'
+    && argv[2] === '--plan' && isTodoIdentifier(argv[3])
+    && argv[4] === '--phase' && isTodoIdentifier(argv[5])
+    && argv[6] === '--reason' && argv[7].length > 0) {
+    action = (repoRoot) => phaseMutation({ repoRoot, env, planKey: argv[3], phaseId: argv[5],
+      kind: 'phase_close_unaudited', payload: { reason: argv[7] } });
+  } else if (argv.length >= 4 && argv[0] === 'phase' && argv[1] === 'baseline'
+    && argv[2] === '--reason' && argv[3].length > 0
+    && parseBaselineExceptFlags(argv.slice(4)) !== null) {
+    const exceptPlanKeys = parseBaselineExceptFlags(argv.slice(4));
+    action = (repoRoot) => phaseBaseline({ repoRoot, env, reason: argv[3], exceptPlanKeys });
   } else if ((argv.length === 5 || argv.length === 6 || argv.length === 7 || argv.length === 8)
     && argv[0] === 'start'
     && argv[1] === '--plan' && isTodoIdentifier(argv[2])

package/src/todo-contracts.mjs

@@ -4,6 +4,10 @@ import { isCanonicalUtcTimestamp } from './timestamp-contract.mjs';
 export const TODO_EVENT_KINDS = Object.freeze([
   'plan_genesis', 'start', 'block', 'unblock', 'done', 'reopen',
   'phase_review', 'phase_accept', 'phase_reject', 'phase_reopen',
+  // ADR 0148: 監査していない歴史を「監査なしで閉じた」として明示的に閉じるための専用kind。
+  // phase_review/accept/reject/reopenと同じv3 tail event shape(phase_id持ち)に収め、
+  // 新しいevent schema版は作らない。
+  'phase_close_unaudited',
 ]);
 export const TODO_LIMITS = Object.freeze({
   tasksPerPlan: 512,
@@ -345,6 +349,10 @@ function validPayload(event) {
     'reason', 'target_decision_digest', 'override_reason',
   ]) && nullableText(payload.reason) && payload.reason !== null
     && isTodoDigest(payload.target_decision_digest) && nullableText(payload.override_reason);
+  // ADR 0148裁定1: 監査なしで閉じたことの理由は必須(payload.reason !== null)。証拠は無い
+  // ——監査していないというのが事実であり、evidenceを要求すると「監査した体」を装う経路になる。
+  if (event.kind === 'phase_close_unaudited') return exactRecord(payload, ['reason'])
+    && nullableText(payload.reason) && payload.reason !== null;
   return false;
 }
 
@@ -392,7 +400,8 @@ function validPhaseStateMigration(value) {
       && (entry.state_policy === 'reset' ? entry.state === null
         : exactRecord(entry.state, [
           'status', 'review_event_digest', 'decision_event_digest', 'decision_evidence',
-        ]) && ['locked', 'active', 'gate_ready', 'reviewing', 'accepted', 'rejected'].includes(entry.state.status)
+        ]) && ['locked', 'active', 'gate_ready', 'reviewing', 'accepted', 'rejected', 'closed_unaudited']
+          .includes(entry.state.status)
           && nullableDigest(entry.state.review_event_digest)
           && nullableDigest(entry.state.decision_event_digest)
           && (entry.state.decision_evidence === null || evidence(entry.state.decision_evidence))))
@@ -421,7 +430,8 @@ export function validateTodoEvent(value) {
     ]) && value.kind === 'plan_genesis' && value.task_id === null && value.phase_id === null
       && isTodoDigest(value.revision_digest) && validStateMigration(value.state_migration)
       && validPhaseStateMigration(value.phase_state_migration);
-    const phaseKind = ['phase_review', 'phase_accept', 'phase_reject', 'phase_reopen'].includes(value?.kind);
+    const phaseKind = ['phase_review', 'phase_accept', 'phase_reject', 'phase_reopen', 'phase_close_unaudited']
+      .includes(value?.kind);
     return (v1 || v2 || v3 || v4) && isTodoIdentifier(value.project_id)
       && isTodoIdentifier(value.plan_key) && isTodoIdentifier(value.plan_version)
       && isNonNegativeSafeInteger(value.sequence) && nullableDigest(value.previous_digest)
@@ -491,7 +501,8 @@ export function validateTodoSnapshot(value) {
         && value.phases.every((entry) => exactRecord(entry, [
           'phase_id', 'status', 'review_event_digest', 'decision_event_digest', 'decision_evidence',
         ]) && isTodoIdentifier(entry.phase_id)
-          && ['locked', 'active', 'gate_ready', 'reviewing', 'accepted', 'rejected'].includes(entry.status)
+          && ['locked', 'active', 'gate_ready', 'reviewing', 'accepted', 'rejected', 'closed_unaudited']
+            .includes(entry.status)
           && nullableDigest(entry.review_event_digest) && nullableDigest(entry.decision_event_digest)
           && (entry.decision_evidence === null || evidence(entry.decision_evidence)))
         && value.phases.every((entry, index) => index === 0

package/src/todo-store.mjs

@@ -217,12 +217,13 @@ async function readJournal(repoRoot, journalRef) {
   const phaseTail = (event) => event.schema === 'lattice.todo_event.v3';
   const legacyTail = (event) => event.schema === 'lattice.todo_event.v1';
   // ADR 0147: genesisがv1/v2(phase無しplan)でも、暗黙のterminal-audit Phaseへの
-  // phase_review/phase_accept/phase_reject/phase_reopenだけはv3 tail eventとして
-  // 混在を許す。task側のevent(start/done/block/unblock/reopen)は従来どおりv1のまま
+  // phase_review/phase_accept/phase_reject/phase_reopen/phase_close_unaudited(ADR 0148)だけは
+  // v3 tail eventとして混在を許す。task側のevent(start/done/block/unblock/reopen)は従来どおりv1のまま
   // ——既存planの既存event bytesは1つも変わらない。新しく増えるのは、これまで
   // phase無しplanには存在し得なかったphase_*event kindの受け皿だけである。
   const implicitTerminalAuditTail = (event) => phaseTail(event)
-    && ['phase_review', 'phase_accept', 'phase_reject', 'phase_reopen'].includes(event.kind);
+    && ['phase_review', 'phase_accept', 'phase_reject', 'phase_reopen', 'phase_close_unaudited']
+      .includes(event.kind);
   const legacyOrImplicitPhaseTail = (event) => legacyTail(event) || implicitTerminalAuditTail(event);
   if ((phaseSchema && events.some(({ schema }, index) => index === 0
     ? !['lattice.todo_event.v3', 'lattice.todo_event.v4'].includes(schema) : !phaseTail(events[index])))
@@ -271,7 +272,11 @@ function phasesOf(plan) {
 
 function derivedPhaseStatus(plan, taskStates, phaseStates, phaseId) {
   const state = phaseStates.get(phaseId);
-  if (['reviewing', 'accepted', 'rejected'].includes(state.status)) return state.status;
+  // ADR 0148: closed_unauditedも他の終端状態と同じく確定済みとして扱う。ここへ足さないと、
+  // 全taskがdone(＝構造的にgate_ready)のままなので、以後の呼び出しで毎回gate_readyへ
+  // 再導出されてしまい、記録した「監査なしで閉じた」がgantt折り畳み・phase_accept_dependencies
+  // 判定の上で一瞬で消える。
+  if (['reviewing', 'accepted', 'rejected', 'closed_unaudited'].includes(state.status)) return state.status;
   const phase = phasesOf(plan).find((entry) => entry.phase_id === phaseId);
   if (!phase.predecessor_phase_ids.every((id) => phaseStates.get(id)?.status === 'accepted')) return 'locked';
   // 暗黙のterminal-audit Phaseはtask側にphase_idフィールドが無い(v1/v2/v3にはそもそも
@@ -303,6 +308,13 @@ function projectPhaseStates(plan, events, taskStates) {
       const state = states.get(event.phase_id);
       state.status = 'rejected'; state.decision_event_digest = event.event_digest;
       state.decision_evidence = event.payload.decision_evidence;
+    } else if (event.kind === 'phase_close_unaudited') {
+      // ADR 0148: 監査していないので証拠(decision_evidence)は残さない。理由はevent payload
+      // 自身(decision_event_digestで指せるこの event)に記録済みで、accept/rejectと違い
+      // ここに複製しない。
+      const state = states.get(event.phase_id);
+      state.status = 'closed_unaudited'; state.decision_event_digest = event.event_digest;
+      state.decision_evidence = null;
     } else if (event.kind === 'phase_reopen') {
       Object.assign(states.get(event.phase_id), emptyPhaseState(event.phase_id));
     }
@@ -428,8 +440,17 @@ function replay(plan, events, { now = new Date(), verifyEvidence, verifyImportSo
         if (verifyEvidence) verifyEvidence(event.payload.decision_evidence);
         state.status = 'rejected'; state.decision_event_digest = event.event_digest;
         state.decision_evidence = event.payload.decision_evidence;
+      } else if (event.kind === 'phase_close_unaudited') {
+        // ADR 0148裁定3: reviewと同じ前提(gate_ready)を課す——所属ToDoが全てdoneでない段階では
+        // まだ監査の地点に到達していないので、監査なしで閉じることもできない。
+        if (currentStatus !== 'gate_ready') fail('STORE_INCONSISTENT', 'phase_gate_not_ready');
+        state.status = 'closed_unaudited'; state.decision_event_digest = event.event_digest;
+        state.decision_evidence = null;
       } else {
-        if (!['accepted', 'rejected'].includes(currentStatus)
+        // phase_reopen。ADR 0148裁定5: closed_unauditedもaccepted/rejectedと同じく
+        // reopenで初期状態へ戻せる——監査せずに閉じた工程を、後から本当に監査したくなった時に
+        // 永久に締め出さない。
+        if (!['accepted', 'rejected', 'closed_unaudited'].includes(currentStatus)
           || state.decision_event_digest !== event.payload.target_decision_digest) {
           fail('STORE_INCONSISTENT', 'phase_reopen_binding_invalid');
         }
@@ -516,14 +537,16 @@ function replay(plan, events, { now = new Date(), verifyEvidence, verifyImportSo
         fail('STORE_INCONSISTENT', 'invalid_reopen_binding');
       }
       {
-        // 暗黙のterminal-audit Phaseがacceptedの後にtaskだけを無警告でreopenできると、
-        // 監査済みのまま(gantt上も畳まれたまま)裏で作業が再開する抜け道になり、ADR 0147の
-        // 「監査の記録なしに閉じたことにさせない」を潜脱する。v4/v5の既存Phaseと同じ規律を
-        // 暗黙Phaseにも及ぼし、phase_reopenを先に通させる。
+        // 暗黙のterminal-audit Phaseがaccepted/closed_unauditedの後にtaskだけを無警告でreopen
+        // できると、監査済み(または監査なしで閉じた)まま(gantt上も畳まれたまま)裏で作業が
+        // 再開する抜け道になり、ADR 0147/0148の「監査の記録なしに閉じたことにさせない」を
+        // 潜脱する。v4/v5の既存Phaseと同じ規律を暗黙Phaseにも及ぼし、phase_reopenを先に
+        // 通させる。closed_unauditedをここへ足さないと、ADR 0148で新設した状態だけが
+        // このgateを素通りしてしまう。
         const phaseId = isPhaselessTodoPlanSchema(plan.schema)
           ? TERMINAL_AUDIT_PHASE_ID
           : plan.tasks.find(({ task_id }) => task_id === event.task_id).phase_id;
-        if (derivedPhaseStatus(plan, states, phaseStates, phaseId) === 'accepted') {
+        if (['accepted', 'closed_unaudited'].includes(derivedPhaseStatus(plan, states, phaseStates, phaseId))) {
           fail('STORE_INCONSISTENT', 'task_reopen_requires_phase_reopen');
         }
       }
@@ -1174,7 +1197,8 @@ function nextEvent(input, storeMember) {
     ? { done_mode: 'authored', imported: false, evidence: input.payload.evidence }
     : input.payload;
   const phaseCapablePlan = ['lattice.todo_plan.v4', 'lattice.todo_plan.v5'].includes(storeMember.plan.schema);
-  const phaseKind = ['phase_review', 'phase_accept', 'phase_reject', 'phase_reopen'].includes(input.kind);
+  const phaseKind = ['phase_review', 'phase_accept', 'phase_reject', 'phase_reopen', 'phase_close_unaudited']
+    .includes(input.kind);
   // ADR 0147: phase無しplanでも、暗黙のterminal-audit Phaseへのphase_*eventだけは
   // v3 tail eventとして書く(readJournalのlegacyOrImplicitPhaseTailが同じ規則で受理する)。
   // task側のevent(start/done等)はphase無しplanのままv1で書き続ける——既存の
@@ -1246,8 +1270,12 @@ function resolveTargetedEvent(input, storeMember) {
     };
   }
   if (input.kind === 'phase_reopen' && exactRecord(input.payload, ['reason', 'override_reason'])) {
+    // ADR 0148裁定5: closed_unauditedもaccept/rejectと同じ「決定event」なので、reopenの
+    // 結びつけ先として同列に探す。ここへ足し忘れると、監査なしで閉じたPhaseをreopenする
+    // 手段が無くなる(target_decision_digestを解決できずphase_reopen_binding_invalidで拒否される)。
     const target = [...storeMember.journal.events].reverse().find((event) => (
-      ['phase_accept', 'phase_reject'].includes(event.kind) && event.phase_id === input.phase_id
+      ['phase_accept', 'phase_reject', 'phase_close_unaudited'].includes(event.kind)
+      && event.phase_id === input.phase_id
     ));
     if (target === undefined) fail('STORE_INCONSISTENT', 'phase_reopen_binding_invalid');
     return { ...input, payload: { ...input.payload, target_decision_digest: target.event_digest } };