@quolu/lattice 0.34.2 → 0.36.0

package/README.ja.md

@@ -161,12 +161,35 @@ cross-plan topologyを同時に切り替える場合は
 Phase付きv5 planでは、通常ToDoの開始順はToDo DAGだけで決まり、Phase前後関係は重監査の順序だけを
 制御します。特定ToDoがPhase受理を本当に必要とする場合だけ`phase_accept_dependencies`で明示します。
 `lattice todo status --json`の`dispatch_frontier`はready全件を同時dispatchする既定を示します。
-readyが複数なら最初のstartに`--parallel-frontier`を付け、subsetだけを直列着手する場合は
-`--override-reason <reason>`で理由を残します。
+readyが複数なら最初のstartに`--parallel-frontier`を付けます。subsetだけを直列着手する場合は
+`--override-reason <reason>`で理由を残しますが、**その申告は一度突き返されます**。
 
 ```bash
 lattice todo start --plan <key> --task <id> --parallel-frontier
-lattice todo start --plan <key> --task <id> --override-reason <reason>
+lattice todo start --plan <key> --task <id> --override-reason <reason> --serial-confirmed
+```
+
+直列の申告に対して`PARALLEL_DISPATCH_RECONSIDER`を返し、並列の再検討を促してから、
+同じ理由に`--serial-confirmed`を付けた再実行だけを通します。規則を文書へ書くだけでは
+読み飛ばされるため、再考をコマンドの往復で強制する設計です。**足止めは一度だけで、
+再実行すれば直列で進みます。**
+
+ただし理由が**実際の干渉を述べていない**場合——「単一セッションだから」「逐次実行するので」
+のようにworker数・セッション構成・作業者の都合を述べただけの場合——は
+`PARALLEL_DISPATCH_INVALID`で拒否し、`--serial-confirmed`を付けても通しません。
+実行主体が1つしか無いことは並列にできない理由ではない（必要ならworkerを増やす）ためです。
+「両taskが同一fileへ書き込む」のような干渉を書けば、再確認を経て通ります。
+
+**同じ検査を計画時点にも掛けます。** 着手時だけを締めても、planそのものが直列に組まれていれば
+並列は生まれません。`lattice plan create`と`lattice todo migrate`は依存グラフから
+`dispatch_shape`（`task_count`／`critical_path_length`／`max_frontier_width`／
+`serialization_ratio`）を計算して結果へ載せ、直列度が閾値を超えるplanを一度突き返します。
+再考した上でなお直列でよいなら`--serialization-reviewed`を付けて再実行します
+（6 task未満のplanは対象外）。判定はstore書込みの前に行うので、拒否された時にstoreへは
+何も書かれません。
+
+```bash
+lattice todo migrate --input <extraction.json> --serialization-reviewed
 ```
 
 `--parallel-frontier`はhostへ並列dispatch方針を宣言する開始gateです。Lattice自身がAI hostのagentを
@@ -174,7 +197,34 @@ lattice todo start --plan <key> --task <id> --override-reason <reason>
 `active_set`と`next_ready`で観測できます。
 ToDo完了は軽量確認までで、所属ToDoが全てdoneになったPhaseは`gate_ready`となり、`todo phase review`後に
 required evidenceを束縛した`todo phase accept`で重監査の判断を記録します。監査回数やPhase数を自動追加する
-機能ではありません。Phase状態は
+機能ではありません。
+
+**監査の既定は「有り」です。** phaseを持たないplanも終端に重監査が要ります（予約Phase
+`terminal-audit`を暗黙に1つ持ちます）。全taskがdoneになった状態は「完走」ではなく`gate_ready`＝
+**監査待ち**であり、工程図のlive scopeはそのplanのToDoを畳みません——完走扱いで図から消えることが
+「閉じた」の可視表現なので、監査の記録なしにそこへ行かせません。作成時に拒否はせず、
+`todo migrate`／`plan create`の結果と最後のdoneのadvisoryで`terminal_audit_required`を通知します。
+**終端監査はToDoのdispatch可否へ影響しません**（Phaseは重監査の順序だけを制御し、開始順はToDo DAGが決めます）。
+規約は[ADR 0147](docs/adr/0147-audit-is-on-by-default.md)が正です。
+
+```bash
+lattice todo phase status --plan <key>   # phase無しplanでも暗黙Phaseを返す（implicit: true）
+lattice todo phase review --plan <key> --phase terminal-audit --reason <text>
+lattice todo phase accept --plan <key> --phase terminal-audit --input <file>
+```
+
+誤ってphase無しで作ったplanへ後からPhaseを被せる場合は、`revise-phase`の
+`state_policy: acquire_phase`でdone状態を保ったまま獲得できます（未割当→割当の向きだけを許し、
+既にphaseを持つtaskの付け替えは拒否します）。
+
+契約のJSON Schemaは各入口から取れます。入力が合わないときは、違反フィールドのpathが
+error detailの`violation_path`へ載ります（配列のソート違反は`/tasks/1`のようにindexまで名指しします）。
+
+```bash
+lattice plan create --schema --json            # 既定は最新v3
+lattice todo revise-phase --schema --json
+lattice plan show <plan_key> --json            # planのtask・依存・phase・状態を1コマンドで読む
+```Phase状態は
 `lattice todo phase status --plan <key>`、閲覧中に進捗が更新される工程表は
 `lattice todo gantt serve --port 0`で確認できます。live viewerはloopback-only、read-onlyで、
 `/projects/<project_id>/`というproject固有URLを返します。別projectからそれぞれ起動すれば、独立port・独立SSE経路で同時表示できます。

package/README.md

@@ -150,6 +150,14 @@ point of use.
 transform that cannot be verified is not adopted. A finding that cannot be independently
 re-derived is not recorded.
 
+**Heavy audit is on by default.** A plan without explicit phases still carries an implicit
+terminal audit: every task being done means `gate_ready` — *awaiting audit* — not finished. The
+live dependency diagram refuses to fold such a plan away, because folding is how the product
+says "closed", and nothing gets there without an evidence-bound `phase accept`. Creation is never
+rejected over it; the requirement is reported instead. And the audit gate never touches dispatch:
+phases order reviews, the ToDo DAG orders work
+([ADR 0147](docs/adr/0147-audit-is-on-by-default.md)).
+
 ## Patent
 
 The design in this repository is the subject of a Japanese patent application:

package/bin/lattice.mjs

@@ -30,10 +30,14 @@ if (help !== null) {
       cwd: process.cwd(), stdout: process.stdout, cliVersion: packageJson.version, error,
     });
   }
-} else if (args.length === 4 && args[0] === 'plan' && args[1] === 'create' && args[2] === '--input') {
+} else if ((args.length === 4 || args.length === 5) && args[0] === 'plan' && args[1] === 'create'
+  && args[2] === '--input' && (args.length === 4 || args[4] === '--serialization-reviewed')) {
   const { projectCliFailure, runPlanCreate } = await import('../src/project-cli.mjs');
   try {
-    process.exitCode = await runPlanCreate({ cwd: process.cwd(), inputRef: args[3], stdout: process.stdout });
+    process.exitCode = await runPlanCreate({
+      cwd: process.cwd(), inputRef: args[3], stdout: process.stdout,
+      serializationReviewed: args.length === 5,
+    });
   } catch (error) {
     process.exitCode = projectCliFailure(process.stderr, error);
   }
@@ -46,13 +50,21 @@ if (help !== null) {
     process.exitCode = projectCliFailure(process.stderr, error);
   }
 } else if (args.length === 5 && args[0] === 'plan' && args[1] === 'create'
-  && args[2] === '--schema-version' && ['2', '3'].includes(args[3]) && args[4] === '--json') {
+  && args[2] === '--schema-version' && ['1', '2', '3'].includes(args[3]) && args[4] === '--json') {
   const { projectCliFailure, runPlanCreateSchema } = await import('../src/project-cli.mjs');
   try {
     process.exitCode = await runPlanCreateSchema({ stdout: process.stdout, version: Number(args[3]) });
   } catch (error) {
     process.exitCode = projectCliFailure(process.stderr, error);
   }
+} else if (args.length === 4 && args[0] === 'plan' && args[1] === 'show'
+  && typeof args[2] === 'string' && args[2].length > 0 && args[3] === '--json') {
+  const { projectCliFailure, runPlanShow } = await import('../src/project-cli.mjs');
+  try {
+    process.exitCode = await runPlanShow({ cwd: process.cwd(), planKey: args[2], stdout: process.stdout });
+  } catch (error) {
+    process.exitCode = projectCliFailure(process.stderr, error);
+  }
 } else if (args.length === 2 && args[0] === 'factory-diagnostics' && args[1] === '--json') {
   const { buildFactoryDiagnostics } = await import('../src/factory-diagnostics.mjs');
   const diagnostics = await buildFactoryDiagnostics();

package/docs/bridge-setup.md

@@ -107,6 +107,19 @@ public hostname `lattice.kitepon.dev` を次のoriginへ対応付ける。
 3. **Cloudflare public HTTPS**: `https://lattice.kitepon.dev/projects/`がredirectなしで200となり、一覧から開いた
    `/projects/<project_id>/`のHTML titleが`Lattice — <project名> 依存工程図`である。
 
+公開viewerの404も、ブラウザとAPIの両契約を別々に確認する。未知URLへ`Accept: text/html`を
+付けたrequestはHTTP 404かつ`Content-Type: text/html`で、`noindex, nofollow`と
+`/projects/`、`https://kitepon.dev/`への戻り先を持つ。`Accept: application/json`では
+HTTP 404かつ`Content-Type: application/json`で、既存の
+`lattice.todo_gantt_http_error.v1`を返す。
+
+```bash
+curl --silent --show-error --include --header 'Accept: text/html' \
+  https://lattice.kitepon.dev/unknown
+curl --silent --show-error --include --header 'Accept: application/json' \
+  https://lattice.kitepon.dev/unknown
+```
+
 外部gateはHTMLだけで閉じず、各projectの
 `https://lattice.kitepon.dev/projects/<project_id>/events`も確認する。応答は200かつ
 `Content-Type: text/event-stream`で、接続直後に`event: state`と現在の`head_digest`を返さなければならない。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.34.2",
+  "version": "0.36.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

@@ -23,9 +23,12 @@ const NAMESPACE_HELP = Object.freeze({
   plan: `Usage: lattice plan <command> [options]
 
 Commands:
-  create --input <file>
-  create --schema --json
-  create --schema-version <2|3> --json
+  create --input <file> [--serialization-reviewed]
+      # 依存グラフがほぼ一直線（serialization_ratioが閾値超）なら一度突き返す。
+      # 再考した上でなお直列でよいなら --serialization-reviewed を付けて再実行する
+  create --schema --json             # 既定は最新版（v3）のJSON Schemaを返す
+  create --schema-version <1|2|3> --json
+  show <plan_key> --json             # task・依存・phase・状態をplan本体から1コマンドで投影する
   compile --request <request.json>
   compile --schema --json            # lattice.run_request.v1 の JSON Schema を出す
   verify --request <request.json> --plan <plan.json>
@@ -70,7 +73,11 @@ Read commands:
   phase status --plan <key>
 
 Write commands:
-  start --plan <key> --task <id> [--parallel-frontier|--override-reason <text>]
+  migrate --input <extraction.json> [--serialization-reviewed]
+      # 既存storeへplanを追加する（plan createは空store初期化専用）。
+      # 依存グラフがほぼ一直線なら一度突き返し、再考後の --serialization-reviewed で通す
+  start --plan <key> --task <id> [--parallel-frontier|--override-reason <text> [--serial-confirmed]]
+        # 既定は全ready同時dispatch。直列にするには理由の申告後、再考を経て --serial-confirmed が要る
   block --plan <key> --task <id> --reason <text>
   unblock --plan <key> --task <id>
   done --plan <key> --task <id> --evidence <file>
@@ -85,6 +92,9 @@ Write commands:
   revise --plan <key> --input <file>
   revise-phase --plan <key> --input <file>
   revise-set --input <file>
+  <revise|revise-phase|revise-set|migrate> --schema --json
+      # 実際に受理する最新契約のJSON Schemaを返す（storeを読まない）。
+      # 入力が契約に合わないときは、違反フィールドのpathがerror detailへ載る
   phase review --plan <key> --phase <id> --reason <text>
   phase <accept|reject> --plan <key> --phase <id> --input <file>
   phase reopen --plan <key> --phase <id> --reason <text> [--override-reason <text>]
@@ -129,7 +139,8 @@ registerはLATTICE_BRIDGE_REGISTRAR_SSH_HOSTとLATTICE_BRIDGE_REGISTRAR_SCRIPT
 const SUBCOMMAND_USAGE = Object.freeze({
   status: 'status --json',
   'session-context': 'session-context --json',
-  'plan create': 'plan create --input <file> | --schema --json | --schema-version <2|3> --json',
+  'plan create': 'plan create --input <file> [--serialization-reviewed] | --schema --json | --schema-version <1|2|3> --json',
+  'plan show': 'plan show <plan_key> --json',
   'plan compile': 'plan compile --request <request.json> | --schema --json',
   'plan verify': 'plan verify --request <request.json> --plan <plan.json>',
   'run start': 'run start --request <request.json> --executor <adapter> | --schema --json',
@@ -171,10 +182,10 @@ 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 revise': 'todo revise --plan <key> --input <file>',
-  'todo revise-phase': 'todo revise-phase --plan <key> --input <file>',
-  'todo revise-set': 'todo revise-set --input <file>',
-  'todo migrate': 'todo migrate --input <extraction.json>',
+  'todo revise': 'todo revise --plan <key> --input <file> | --schema --json',
+  'todo revise-phase': 'todo revise-phase --plan <key> --input <file> | --schema --json',
+  'todo revise-set': 'todo revise-set --input <file> | --schema --json',
+  'todo migrate': 'todo migrate --input <extraction.json> [--serialization-reviewed] | --schema --json',
   'sensor init': 'sensor init [path] --json',
   'sensor sync': 'sensor sync [path] --json',
   'runtime-errors snapshot': 'runtime-errors snapshot [--after-cursor <n>] [--limit <n>] --json',

package/src/project-cli.mjs

@@ -22,10 +22,15 @@ import {
   buildTodoPlan,
   createTodoStoreWriter,
   initializeAuthoredTodoStore,
+  isPhaselessTodoPlanSchema,
   readTodoIndependenceArtifact,
   readTodoStore,
   TodoStoreError,
 } from './todo-store.mjs';
+import {
+  assertTodoDispatchShapeReviewed,
+  computeTodoDispatchShapeForPlan,
+} from './todo-dispatch-shape.mjs';
 
 const STORE_REF = '.lattice/todo';
 const MANIFEST_REF = `${STORE_REF}/manifest.json`;
@@ -432,11 +437,21 @@ function validateCreateInput(value) {
   } catch { return false; }
 }
 
-export async function runPlanCreate({ cwd, inputRef, stdout }) {
+export async function runPlanCreate({ cwd, inputRef, stdout, serializationReviewed = false }) {
   const repoRoot = resolveRepoRoot(cwd);
   if (repoRoot === null) throw new TodoStoreError('REPO_UNRESOLVED', 'git_toplevel_unresolved');
   const input = await readCanonicalInput(repoRoot, inputRef);
   if (!validateCreateInput(input)) throw new TodoStoreError('INPUT_INVALID', 'plan_create_schema_invalid');
+  // dispatch_shapeのgateはstore初期化より前に判定する（拒否時にstoreへ何も書かないため、
+  // 再考後の再実行がplan_key_already_existsで詰まらない）。
+  const dispatchShape = computeTodoDispatchShapeForPlan({
+    projectId: input.project_id,
+    planKey: input.plan_key,
+    taskIds: input.tasks.map(({ task_id: taskId }) => taskId),
+    hardDependencies: input.hard_dependencies,
+    joins: input.joins,
+  });
+  assertTodoDispatchShapeReviewed({ shape: dispatchShape, reviewed: serializationReviewed });
   const store = await initializeAuthoredTodoStore({
     repoRoot, writer: createTodoStoreWriter({ caller: 'g5-authoring' }),
     projectId: input.project_id, repositories: [{ repo_id: 'self', path: '.' }],
@@ -460,14 +475,33 @@ export async function runPlanCreate({ cwd, inputRef, stdout }) {
     plan_key: member.plan.plan_key, plan_version: member.plan.plan_version,
     store_ref: STORE_REF, plan_ref: member.descriptor.plan_ref,
     journal_ref: member.descriptor.journal_ref, snapshot_ref: member.descriptor.snapshot_ref,
-    plan_digest: member.plan.plan_digest, result_digest: '',
+    plan_digest: member.plan.plan_digest,
+    dispatch_shape: {
+      task_count: dispatchShape.task_count,
+      critical_path_length: dispatchShape.critical_path_length,
+      max_frontier_width: dispatchShape.max_frontier_width,
+      serialization_ratio: dispatchShape.serialization_ratio,
+    },
+    // ADR 0147裁定3: phase無し(v3)のplan createは拒否せず、終端監査が要ることを結果へ
+    // 明示するに留める。phase入力(v4/v5)ならfalse——既存のPhase gateがそのまま重監査を担う。
+    terminal_audit_required: isPhaselessTodoPlanSchema(member.plan.schema),
+    result_digest: '',
   };
   result.result_digest = resultDigest(result);
   stdout.write(`${JSON.stringify(result)}\n`);
   return 0;
 }
 
-export async function runPlanCreateSchema({ stdout, version = 1 }) {
+/**
+ * `--schema --json`（版指定なし）の既定はCURRENT_CREATE_INPUT_SCHEMAと同じv3にする。
+ * 既定がv1のままだと、素の`--schema`を叩いたAIが古いv1（Phaseを表現できない）を
+ * 受け取り、実運用で通らない入力を作ってしまう（実際に踏んだ）。
+ * `--schema-version 1`は互換のため引き続き取得できる（bin/lattice.mjs側で許可）。
+ *
+ * 「どの版を返したか」は返すJSON Schema自身の`title`（例: `lattice.plan_create_input.v3`）が
+ * 既に機械可読に持っている。壊さずに追加のkeyを足す理由が無いので足さない。
+ */
+export async function runPlanCreateSchema({ stdout, version = 3 }) {
   if (![1, 2, 3].includes(version)) throw new TypeError('unsupported plan create schema version');
   const expected = version === 3 ? DECOUPLED_PHASE_CREATE_INPUT_SCHEMA
     : version === 2 ? PHASE_CREATE_INPUT_SCHEMA : CREATE_INPUT_SCHEMA;
@@ -483,6 +517,95 @@ export async function runPlanCreateSchema({ stdout, version = 1 }) {
   }
 }
 
+const PLAN_SHOW_RESULT_SCHEMA = 'lattice.plan_show_result.v1';
+
+/**
+ * `todo bindings`はcompile_binding付きtaskだけを投影するので、通常planでは空配列を返す。
+ * それを見て「planが空だ」と誤読された実績があるため、plan本体（task・依存・phase・状態）を
+ * 1コマンドで読める面を別に持つ。読み出しは既存store readerとtodo status projectionの
+ * 再利用に留め、journalを独自に再実装しない。
+ */
+export async function runPlanShow({ cwd, planKey, stdout }) {
+  const repoRoot = resolveRepoRoot(cwd);
+  if (repoRoot === null) throw new TodoStoreError('REPO_UNRESOLVED', 'git_toplevel_unresolved');
+  const store = await readTodoStore({ repoRoot });
+  const member = store.members.find(({ descriptor }) => descriptor.plan_key === planKey);
+  if (member === undefined) {
+    // 既存read commands（independence compile等）と同じcode/reasonを踏襲する。
+    // 未知のplan_keyを「store不整合」と同じ扱いにするのはこのCLI全体の既定であり、
+    // ここだけ別codeへ逸れると呼び出し側の分岐が増える。
+    throw new TodoStoreError('STORE_INCONSISTENT', 'plan_not_active', undefined, {
+      plan_key: planKey, next_action: 'check_active_plans_via_status',
+    });
+  }
+  const { plan, tasks, phases } = member;
+  const phaseInput = ['lattice.todo_plan.v4', 'lattice.todo_plan.v5'].includes(plan.schema);
+  const stateByTaskId = new Map(tasks.map((state) => [state.task_id, state]));
+  // snapshot artifactの形式(v1にはphasesキーが無い)には縛られない導出ビューを読む
+  // (readTodoStoreが常に member.phases として埋める。ADR 0147)。
+  const phaseStatusById = new Map((phases ?? []).map((phase) => [phase.phase_id, phase.status]));
+
+  // 依存の本数: このplanの中でそのtaskへ入ってくるhard_dependencies辺と、joinで
+  // 合流するafter辺の合計。cross-plan参照は数えない（plan showは単一planの投影のため）。
+  const dependsOnCount = new Map(plan.tasks.map((task) => [task.task_id, 0]));
+  for (const edge of plan.hard_dependencies) {
+    if (edge.to.plan_key === planKey && dependsOnCount.has(edge.to.task_id)) {
+      dependsOnCount.set(edge.to.task_id, dependsOnCount.get(edge.to.task_id) + 1);
+    }
+  }
+  for (const join of plan.joins) {
+    if (join.before.plan_key === planKey && dependsOnCount.has(join.before.task_id)) {
+      dependsOnCount.set(join.before.task_id, dependsOnCount.get(join.before.task_id) + join.after.length);
+    }
+  }
+
+  const taskList = plan.tasks.map((task) => ({
+    task_id: task.task_id,
+    title: task.title,
+    lane: task.lane,
+    phase_id: phaseInput ? task.phase_id : null,
+    state: stateByTaskId.get(task.task_id).status,
+    depends_on_count: dependsOnCount.get(task.task_id) ?? 0,
+  }));
+
+  const phaseList = phaseInput ? plan.phases.map((phase) => ({
+    phase_id: phase.phase_id,
+    title: phase.title,
+    gate_policy: phase.gate_policy,
+    predecessor_phase_ids: phase.predecessor_phase_ids,
+    status: phaseStatusById.get(phase.phase_id) ?? null,
+  })) : [];
+
+  // dispatch形状はplan create時に既に計算している同じ関数を再利用する。
+  // critical path長・frontier幅を独自に計算し直さない。
+  const dispatchShape = computeTodoDispatchShapeForPlan({
+    projectId: plan.project_id, planKey,
+    taskIds: plan.tasks.map(({ task_id: taskId }) => taskId),
+    hardDependencies: plan.hard_dependencies, joins: plan.joins,
+  });
+
+  const result = {
+    schema: PLAN_SHOW_RESULT_SCHEMA,
+    project_id: plan.project_id,
+    plan_key: plan.plan_key,
+    plan_version: plan.plan_version,
+    plan_schema: plan.schema,
+    has_phases: phaseInput,
+    phases: phaseList,
+    tasks: taskList,
+    topology: {
+      task_count: dispatchShape.task_count,
+      critical_path_length: dispatchShape.critical_path_length,
+      max_frontier_width: dispatchShape.max_frontier_width,
+      serialization_ratio: dispatchShape.serialization_ratio,
+    },
+    result_digest: '',
+  };
+  result.result_digest = resultDigest(result);
+  stdout.write(`${JSON.stringify(result)}\n`);
+  return 0;
+}
+
 export function projectStatusFailure({ cwd, stdout, cliVersion, error }) {
   const result = invalidStatus({
     cliVersion, repoRoot: resolveRepoRoot(cwd),