@quolu/lattice 0.51.0 → 0.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Schedulability compiler for multi-agent development: observe real code boundaries, refactor the conflicting seam, recompile the plan for parallel execution",
   "author": {
     "name": "Quo / クオ at kitepon.dev",

package/src/cli-help.mjs

@@ -99,6 +99,8 @@ Write commands:
   done --plan <key> --task <id> --evidence <file>
   reopen --plan <key> --task <id> --reason <text> [--override-reason <text>]
   evidence promote --plan <key> --task <id> --evidence <file>
+  dependency connect --from-plan <key> --from-task <id> --to-plan <key> --to-task <id> --reason <text>
+      # 開発中に発見したplan跨ぎ依存を明示接続する。依存の自動推定は行わない
   independence compile --plan <key> --input <file>  # witness setとsensorから並列可否を記録する
   independence witness migrate --plan <key>  # revision後の宣言をtask migrationで写す
   independence witness scaffold --plan <key> --input <draft>  # 下書きとfresh観測から宣言を書き出す
@@ -247,6 +249,8 @@ const SUBCOMMAND_USAGE = Object.freeze({
   'todo reopen': 'todo reopen --plan <key> --task <id> --reason <text> [--override-reason <text>]',
   'todo evidence': 'todo evidence promote --plan <key> --task <id> --evidence <file>',
   'todo evidence promote': 'todo evidence promote --plan <key> --task <id> --evidence <file>',
+  'todo dependency': 'todo dependency connect --from-plan <key> --from-task <id> --to-plan <key> --to-task <id> --reason <text>',
+  'todo dependency connect': 'todo dependency connect --from-plan <key> --from-task <id> --to-plan <key> --to-task <id> --reason <text>',
   'todo split': 'todo split --plan <key> --input <file>',
   'todo revise': 'todo revise --plan <key> --input <file> | --schema --json',
   'todo revise-phase': 'todo revise-phase --plan <key> --input <file> | --schema --json',

package/src/todo-cli.mjs

@@ -46,6 +46,7 @@ import {
   createTodoStoreWriter,
   TodoStoreError,
   isPhaselessTodoPlanSchema,
+  projectTodoCrossPlanDependencies,
   TERMINAL_AUDIT_PHASE_ID,
   readTodoIndependenceArtifact,
   readTodoSeamProposalArtifact,
@@ -96,6 +97,7 @@ import {
   selectIndependenceGuidance,
   selectWitnessScaffoldGuidance,
   selectSeamProposalGuidance,
+  scopeExpansionRecommendations,
 } from './todo-independence-guidance.mjs';
 import {
   buildSeamProposalQuerySet,
@@ -280,9 +282,13 @@ function taskRef(plan, taskId) {
 }
 
 function mergedTopology(store) {
+  const crossPlanDependencies = projectTodoCrossPlanDependencies(store.members);
   return {
     nodes: store.members.flatMap(({ plan }) => plan.tasks.map(({ task_id: taskId }) => taskRef(plan, taskId))),
-    hard_edges: store.members.flatMap(({ plan }) => plan.hard_dependencies),
+    hard_edges: [
+      ...store.members.flatMap(({ plan }) => plan.hard_dependencies),
+      ...crossPlanDependencies.map(({ from, to }) => ({ from, to })),
+    ],
     joins: store.members.flatMap(({ plan }) => plan.joins),
   };
 }
@@ -640,6 +646,7 @@ async function startAdvisory({ repoRoot, store, projection, planKey, taskId }) {
       coverage: 'missing',
       drift_intersecting: null,
       conflicts_with_active: [],
+      scope_expansion_recommendations: [],
       uncovered_active_task_ids: projection.active_set
         .filter((task) => task.plan_key === planKey).map(({ task_id: id }) => id),
       self_unknowns: [{ kind: 'witness_missing', ref: 'no_independence_record' }],
@@ -683,6 +690,9 @@ async function startAdvisory({ repoRoot, store, projection, planKey, taskId }) {
     drift_intersecting: projected.drift === null
       ? null : projected.drift.intersecting_task_ids.includes(taskId),
     conflicts_with_active: conflictsWithActive,
+    scope_expansion_recommendations: scopeExpansionRecommendations(
+      Array.isArray(artifact.scope_expanded) ? artifact.scope_expanded : [],
+    ).filter(({ task_id: expandedTaskId }) => expandedTaskId === taskId),
     uncovered_active_task_ids: projected.uncovered_active_task_ids,
     self_unknowns: selfUnknowns,
     guidance: selectIndependenceGuidance({
@@ -912,6 +922,57 @@ async function independenceMode({ repoRoot, env, planKey, mode, reason }) {
   return result;
 }
 
+/** 開発中に発見したplan跨ぎ依存を、consumer planのplan-scoped chainへ接続する。 */
+async function dependencyConnect({
+  repoRoot, env, fromPlanKey, fromTaskId, toPlanKey, toTaskId, reason,
+}) {
+  const store = await readTodoStore({ repoRoot });
+  const dependencyMember = (planKey) => {
+    const member = store.members.find(({ plan }) => plan.plan_key === planKey);
+    if (member === undefined) {
+      throw new TodoStoreError('DEPENDENCY_INVALID', 'dependency_plan_not_found', undefined, {
+        plan_key: planKey,
+      });
+    }
+    return member;
+  };
+  const source = dependencyMember(fromPlanKey);
+  const target = dependencyMember(toPlanKey);
+  if (!source.plan.tasks.some(({ task_id: taskId }) => taskId === fromTaskId)) {
+    throw new TodoStoreError('DEPENDENCY_INVALID', 'dependency_task_not_found', undefined, {
+      plan_key: fromPlanKey, task_id: fromTaskId,
+    });
+  }
+  if (!target.plan.tasks.some(({ task_id: taskId }) => taskId === toTaskId)) {
+    throw new TodoStoreError('DEPENDENCY_INVALID', 'dependency_task_not_found', undefined, {
+      plan_key: toPlanKey, task_id: toTaskId,
+    });
+  }
+  const from = {
+    project_id: store.project_id, plan_key: fromPlanKey, task_id: fromTaskId,
+    expected_topology_digest: source.plan.topology_digest,
+  };
+  const to = {
+    project_id: store.project_id, plan_key: toPlanKey, task_id: toTaskId,
+    expected_topology_digest: target.plan.topology_digest,
+  };
+  const { event } = await appendTodoEvent({
+    repoRoot, writer: createTodoStoreWriter({ caller: 'g5-authoring' }), planKey: toPlanKey,
+    event: {
+      kind: 'cross_plan_dependency', actor: mutationActor(env), payload: { from, to, reason },
+    },
+  });
+  const result = {
+    schema: 'lattice.todo_dependency_connect_result.v1', project_id: store.project_id,
+    from: event.payload.from, to: event.payload.to, reason: event.payload.reason,
+    connected_by: event.actor, connected_at: event.recorded_at,
+    event_digest: event.event_digest, plan_scoped_head_digest: event.event_digest,
+    result_digest: '',
+  };
+  result.result_digest = todoSelfDigest(result, 'result_digest');
+  return result;
+}
+
 async function phaseStatus({ repoRoot, planKey }) {
   const store = await readTodoStore({ repoRoot });
   const [member] = selectMembers(store, planKey);
@@ -1657,7 +1718,7 @@ async function independenceCompile({ repoRoot, planKey, inputRef }) {
   const { ref } = await writeTodoIndependenceArtifact({ repoRoot, artifact });
 
   const result = {
-    schema: 'lattice.todo_independence_compile_result.v1',
+    schema: 'lattice.todo_independence_compile_result.v2',
     project_id: artifact.project_id,
     plan_key: artifact.plan_key,
     plan_version: artifact.plan_version,
@@ -1667,6 +1728,7 @@ async function independenceCompile({ repoRoot, planKey, inputRef }) {
     task_count: artifact.task_ids.length,
     conflict_count: artifact.conflicts.length,
     unknown_count: artifact.unknowns.length,
+    scope_expansion_recommendations: scopeExpansionRecommendations(artifact.scope_expanded),
     result_digest: '',
   };
   result.result_digest = todoSelfDigest(result, 'result_digest');
@@ -2823,6 +2885,16 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env
     action = (repoRoot) => independenceMode({
       repoRoot, env, planKey: argv[3], mode: argv[5], reason: argv[7],
     });
+  } else if (argv.length === 12 && argv[0] === 'dependency' && argv[1] === 'connect'
+    && argv[2] === '--from-plan' && isTodoIdentifier(argv[3])
+    && argv[4] === '--from-task' && isTodoIdentifier(argv[5])
+    && argv[6] === '--to-plan' && isTodoIdentifier(argv[7])
+    && argv[8] === '--to-task' && isTodoIdentifier(argv[9])
+    && argv[10] === '--reason' && argv[11].length > 0) {
+    action = (repoRoot) => dependencyConnect({
+      repoRoot, env, fromPlanKey: argv[3], fromTaskId: argv[5],
+      toPlanKey: argv[7], toTaskId: argv[9], reason: argv[11],
+    });
   } else if (argv.length === 6 && argv[0] === 'independence' && argv[1] === 'compile'
     && argv[2] === '--plan' && isTodoIdentifier(argv[3]) && argv[4] === '--input') {
     action = (repoRoot) => independenceCompile({

package/src/todo-contracts.mjs

@@ -13,10 +13,15 @@ export const TODO_EVENT_KINDS = Object.freeze([
   // 「誰が選んだか」の帰属を持つ——witnessが全planの暗黙義務だった時に帰属が無く、正確な
   // 案内が素通りされたことへの是正である(オーナー裁定C①)。
   'coordination_mode',
+  // 開発中に発見したplan跨ぎの依存を、active plan topologyの追記改変ではなく
+  // version-boundなplan-scoped eventとして接続する。推定はせず、AIが発見した時だけ積む。
+  'cross_plan_dependency',
 ]);
 
 /** planへ帰属し、taskにもPhaseにも属さないevent kind。 */
-export const TODO_PLAN_SCOPED_EVENT_KINDS = Object.freeze(['coordination_mode']);
+export const TODO_PLAN_SCOPED_EVENT_KINDS = Object.freeze([
+  'coordination_mode', 'cross_plan_dependency',
+]);
 
 /** 調整方式。witness=独立性を宣言し検証して並列する／conversation=会話で調整する。 */
 export const TODO_COORDINATION_MODES = Object.freeze(['witness', 'conversation']);
@@ -506,6 +511,15 @@ function validPayload(event) {
       && TODO_COORDINATION_MODES.includes(payload.mode)
       && nullableText(payload.reason) && payload.reason !== null;
   }
+  if (event.kind === 'cross_plan_dependency') {
+    const dependencyRef = (value) => exactRecord(value, [
+      'project_id', 'plan_key', 'task_id', 'expected_topology_digest',
+    ]) && isTodoIdentifier(value.project_id) && isTodoIdentifier(value.plan_key)
+      && isTodoIdentifier(value.task_id) && isTodoDigest(value.expected_topology_digest);
+    return exactRecord(payload, ['from', 'to', 'reason'])
+      && dependencyRef(payload.from) && dependencyRef(payload.to)
+      && nullableText(payload.reason) && payload.reason !== null;
+  }
   if (event.kind === 'start') return exactRecord(payload, ['override_reason']) && nullableText(payload.override_reason);
   if (event.kind === 'start_retracted') return exactRecord(payload, ['reason', 'target_start_digest'])
     && nullableText(payload.reason) && payload.reason !== null

package/src/todo-gantt-layout.mjs

@@ -1,5 +1,6 @@
 import { TODO_GANTT_SCOPES, projectTodoGanttScope } from './todo-gantt-scope.mjs';
 import { buildTodoGanttHierarchy } from './todo-gantt-nested.mjs';
+import { projectTodoCrossPlanDependencies } from './todo-store.mjs';
 
 const TASK_LIMIT = 2_000;
 const EDGE_LIMIT = 8_000;
@@ -230,6 +231,9 @@ function normalizeInput(readModel, chainProjection) {
       for (const after of join.after) addEdge(after, join.before, 'join', identity);
     }
   }
+  for (const dependency of projectTodoCrossPlanDependencies(members)) {
+    addEdge(dependency.from, dependency.to, 'cross_plan');
+  }
   if (edgeMap.size > EDGE_LIMIT) {
     fail('TODO_SCALE_EXCEEDED', 'todo gantt edge limit exceeded', {
       task_count: nodesByKey.size, task_limit: TASK_LIMIT,

package/src/todo-gantt-nested.mjs

@@ -1,4 +1,5 @@
 import { projectTodoChainV1 } from './todo-chain.mjs';
+import { projectTodoCrossPlanDependencies } from './todo-store.mjs';
 
 const ROOT = Symbol('todo-gantt-root');
 
@@ -131,6 +132,18 @@ function projectMember(member, hierarchy, containerKey, selectedKeys) {
     phaseAcceptDependencies.push({ ...dependency, to });
   }
 
+  // plan-scopedのcross-plan edgeも階層levelのtaskへ射影する。子task同士の接続を
+  // root levelで捨てると、nested表示だけ依存線とwaveが消えるため、hard edgeと同じく
+  // 各endpointをそのlevel直下のbranchへ束縛し直す。
+  const planScopedEvents = (member.plan_scoped?.events ?? []).flatMap((event) => {
+    if (event.kind !== 'cross_plan_dependency') return [event];
+    const from = projectRef(hierarchy, containerKey, event.payload.from);
+    const to = projectRef(hierarchy, containerKey, event.payload.to);
+    if (from === null || to === null || !selectedKeys.has(refKey(from))
+      || !selectedKeys.has(refKey(to)) || refKey(from) === refKey(to)) return [];
+    return [{ ...event, payload: { ...event.payload, from, to } }];
+  });
+
   return {
     ...member,
     plan: {
@@ -140,6 +153,9 @@ function projectMember(member, hierarchy, containerKey, selectedKeys) {
       joins,
       phase_accept_dependencies: phaseAcceptDependencies,
     },
+    ...(member.plan_scoped === undefined ? {} : {
+      plan_scoped: { ...member.plan_scoped, events: planScopedEvents },
+    }),
     tasks: member.tasks.filter(({ task_id: taskId }) => tasks.some((task) => task.task_id === taskId)),
   };
 }
@@ -174,10 +190,14 @@ function filterIndependence(independence, selectedKeys) {
 }
 
 function topologyOf(readModel) {
+  const crossPlanDependencies = projectTodoCrossPlanDependencies(readModel.members);
   return {
     nodes: readModel.members.flatMap((member) => member.plan.tasks
       .map(({ task_id: taskId }) => taskRef(member, taskId))),
-    hard_edges: readModel.members.flatMap((member) => member.plan.hard_dependencies),
+    hard_edges: [
+      ...readModel.members.flatMap((member) => member.plan.hard_dependencies),
+      ...crossPlanDependencies.map(({ from, to }) => ({ from, to })),
+    ],
     joins: readModel.members.flatMap((member) => member.plan.joins),
   };
 }

package/src/todo-status.mjs

@@ -15,7 +15,11 @@ import {
 } 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';
+import {
+  isPhaselessTodoPlanSchema,
+  projectTodoCrossPlanDependencies,
+  todoPhaseDefinitions,
+} from './todo-store.mjs';
 
 /**
  * v6で`plan_notes`を足す。ADR 0054・0063の前例どおり既存versionへのin-place追加はしない。
@@ -474,6 +478,11 @@ function buildTodoGraph(readModel) {
       }
     }
   }
+  // active plan topologyは追記改変しない。開発中に接続したplan-scoped edgeを同じincomingへ
+  // 合成することで、projectTodoStatusとcomputeReadyFrontierが同じ待機判定を即座に読む。
+  for (const dependency of projectTodoCrossPlanDependencies(members)) {
+    addPredecessor(dependency.from, dependency.to);
+  }
 
   auditPending.sort((left, right) => (
     left.plan_key < right.plan_key ? -1 : left.plan_key > right.plan_key ? 1

package/src/todo-store.mjs

@@ -363,6 +363,32 @@ export function projectTodoCoordination(events) {
   };
 }
 
+/**
+ * active plan群へ接続済みのplan跨ぎ依存線を投影する。
+ *
+ * eventはconsumer（to）planのplan-scoped chainへ積まれる。自動発見も暗黙補完もせず、
+ * 記録された線だけを返す。順序はtask identityで固定し、status/Ganttが同じ入力を見る。
+ */
+export function projectTodoCrossPlanDependencies(members) {
+  const dependencies = [];
+  for (const member of members) for (const event of member.plan_scoped?.events ?? []) {
+    if (event.kind !== 'cross_plan_dependency') continue;
+    dependencies.push({
+      from: event.payload.from,
+      to: event.payload.to,
+      reason: event.payload.reason,
+      connected_by: event.actor,
+      connected_at: event.recorded_at,
+      event_digest: event.event_digest,
+    });
+  }
+  return dependencies.sort((left, right) => {
+    const key = (entry) => `${entry.from.project_id}\0${entry.from.plan_key}\0${entry.from.task_id}`
+      + `\0${entry.to.project_id}\0${entry.to.plan_key}\0${entry.to.task_id}\0${entry.event_digest}`;
+    return key(left) < key(right) ? -1 : key(left) > key(right) ? 1 : 0;
+  });
+}
+
 function derivedPhaseStatus(plan, taskStates, phaseStates, phaseId) {
   const state = phaseStates.get(phaseId);
   // ADR 0148: closed_unauditedも他の終端状態と同じく確定済みとして扱う。ここへ足さないと、
@@ -748,7 +774,7 @@ function snapshotFor(plan, events, tasks) {
   return snapshot;
 }
 
-function validateMergedGraph(members) {
+function validateMergedGraph(members, crossPlanDependencies = []) {
   const tasks = new Map();
   for (const member of members) for (const task of member.plan.tasks) {
     tasks.set(`${member.plan.project_id}\0${member.plan.plan_key}\0${task.task_id}`, member.plan.topology_digest);
@@ -816,6 +842,15 @@ function validateMergedGraph(members) {
       }
     }
   }
+  for (const dependency of crossPlanDependencies) {
+    const owner = members.find(({ plan }) => plan.project_id === dependency.to.project_id
+      && plan.plan_key === dependency.to.plan_key);
+    if (owner === undefined) fail('STORE_INCONSISTENT', 'cross_plan_dependency_owner_missing');
+    const from = bind(dependency.from, owner.plan);
+    const to = bind(dependency.to, owner.plan);
+    if (from === to) fail('STORE_INCONSISTENT', 'self_edge');
+    adjacency.get(from).push(to);
+  }
   const colors = new Map();
   const visit = (node) => {
     if (colors.get(node) === 1) fail('STORE_INCONSISTENT', 'merged_cycle');
@@ -825,6 +860,48 @@ function validateMergedGraph(members) {
   for (const node of adjacency.keys()) visit(node);
 }
 
+function crossPlanDependencyTask(store, ref) {
+  const member = store.members.find(({ plan }) => plan.project_id === ref.project_id
+    && plan.plan_key === ref.plan_key);
+  if (member === undefined) fail('DEPENDENCY_INVALID', 'dependency_plan_not_found', { ref });
+  if (member.plan.topology_digest !== ref.expected_topology_digest) {
+    fail('DEPENDENCY_STALE', 'dependency_topology_stale', {
+      ref, actual_topology_digest: member.plan.topology_digest,
+    });
+  }
+  const task = member.tasks.find(({ task_id: taskId }) => taskId === ref.task_id);
+  if (task === undefined) fail('DEPENDENCY_INVALID', 'dependency_task_not_found', { ref });
+  return { member, task };
+}
+
+function validateCrossPlanDependencyTransition(store, owner, input) {
+  const { from, to } = input.payload;
+  if (from.project_id !== store.project_id || to.project_id !== store.project_id) {
+    fail('DEPENDENCY_INVALID', 'dependency_project_mismatch');
+  }
+  if (from.plan_key === to.plan_key) fail('DEPENDENCY_INVALID', 'dependency_must_cross_plans');
+  if (to.plan_key !== owner.plan.plan_key || to.project_id !== owner.plan.project_id) {
+    fail('DEPENDENCY_INVALID', 'dependency_owner_mismatch');
+  }
+  const source = crossPlanDependencyTask(store, from);
+  const target = crossPlanDependencyTask(store, to);
+  if (source.task.status === 'done') fail('DEPENDENCY_INVALID', 'dependency_source_terminal');
+  if (target.task.status === 'done') fail('DEPENDENCY_INVALID', 'dependency_target_terminal');
+  const existing = projectTodoCrossPlanDependencies(store.members);
+  if (existing.some((dependency) => mergedTaskKey(dependency.from) === mergedTaskKey(from)
+    && mergedTaskKey(dependency.to) === mergedTaskKey(to))) {
+    fail('DEPENDENCY_EXISTS', 'cross_plan_dependency_duplicate', { from, to });
+  }
+  try {
+    validateMergedGraph(store.members, [...existing, { from, to }]);
+  } catch (error) {
+    if (error instanceof TodoStoreError && error.detail?.reason === 'merged_cycle') {
+      fail('DEPENDENCY_CYCLE', 'cross_plan_dependency_cycle', { from, to });
+    }
+    throw error;
+  }
+}
+
 function mergedTaskKey(refValue) {
   return `${refValue.project_id}\0${refValue.plan_key}\0${refValue.task_id}`;
 }
@@ -889,6 +966,9 @@ function mergedPredecessorKeys(store, targetKey) {
       }
     }
   }
+  for (const dependency of projectTodoCrossPlanDependencies(store.members)) {
+    if (mergedTaskKey(dependency.to) === targetKey) result.push(mergedTaskKey(dependency.from));
+  }
   return [...new Set(result)];
 }
 
@@ -904,6 +984,9 @@ function mergedSuccessorKeys(store, targetKey) {
       }
     }
   }
+  for (const dependency of projectTodoCrossPlanDependencies(store.members)) {
+    if (mergedTaskKey(dependency.from) === targetKey) result.push(mergedTaskKey(dependency.to));
+  }
   return [...new Set(result)];
 }
 
@@ -1275,7 +1358,7 @@ export async function readTodoStore(options = {}) {
       snapshot: snapshotStale ? expectedSnapshot : snapshot,
       tasks, phases, coordination, snapshot_stale: snapshotStale });
   }
-  validateMergedGraph(loaded);
+  validateMergedGraph(loaded, projectTodoCrossPlanDependencies(loaded));
   return {
     schema: 'lattice.todo_store_read.v1', project_id: manifest.project_id, manifest,
     members: loaded, snapshot_stale: loaded.some((member) => member.snapshot_stale),
@@ -1491,10 +1574,13 @@ 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状態も動かさないので、
+    // planへ帰属するeventは別chainへ積む。task状態もPhase状態も直接は動かさないので、
     // replay・snapshot・manifestへは触れない——lifecycle journalのheadを進めるのは
-    // 「作業が進んだ」の意味であり、方式を選んだだけでそこを動かすと意味がずれる。
+    // 「作業が進んだ」の意味であり、方式選択や依存接続でそこを動かすと意味がずれる。
     if (TODO_PLAN_SCOPED_EVENT_KINDS.includes(options.event.kind)) {
+      if (options.event.kind === 'cross_plan_dependency') {
+        validateCrossPlanDependencyTransition(store, member, options.event);
+      }
       return appendPlanScopedEvent({
         repoRoot, member,
         input: { ...options.event, recorded_at: options.event.recorded_at ?? new Date().toISOString() },