@quolu/lattice 0.1.0 → 0.12.2

package/README.md

@@ -3,8 +3,14 @@
 Latticeは、codebaseの境界を観測・変換し、multi-agent開発の並列TODO graphを生成する
 schedulability compilerです。
 
-現在はbootstrap段階です。実装状況は[docs/plan_lattice_rc4_dotagents_dogfood.md](docs/plan_lattice_rc4_dotagents_dogfood.md)、製品思想は
-[PLAN.md](PLAN.md)、公開予定contractは[docs/00_product-contract.md](docs/00_product-contract.md)を参照してください。
+現在の工程状態と完了証拠の正本は、このrepoのLattice storeです。文書の役割と現行導線は
+[docs/README.md](docs/README.md)、製品思想は[PLAN.md](PLAN.md)、公開contractは
+[docs/00_product-contract.md](docs/00_product-contract.md)を参照してください。
+
+CLIの全体像は`lattice --help`、各公開namespaceの正規構文は
+`lattice <plan|run|event|todo|sensor|factory-diagnostics|runtime-errors|bridge> --help`で確認できます。
+個別操作は`lattice <namespace> <subcommand> --help`または`lattice help <namespace> <subcommand>`で
+正規optionをstore非依存に確認できます。
 
 ## 開発
 
@@ -12,9 +18,86 @@ schedulability compilerです。
 npm test
 npm run check
 npm run ci
-codegraph status .
+lattice sensor sync . --json
 spotter doctor
 codex-sidecar diagnostics --project . --preset auditor --json
 ```
 
-Node.js 22.13以上を使用します。CodegraphとSpotterはproject単位で初期化し、生成stateの所有境界を守ります。
+未初期化projectで`sensor sync`した場合は`LATTICE_SENSOR_NOT_INITIALIZED`と正規`next_action`を返します。
+その他のsensor失敗もexit code、signal、bounded stderrをtyped detailへ残し、原因を隠しません。
+
+Node.js 22.13以上を使用します。境界観測は配布物に同梱したLattice sensorだけを使い、PATH上の
+廃止済みruntimeや旧cache/dataへfallbackしません。Spotterはproject単位で生成stateの所有境界を守ります。
+
+どのrepoでも、Latticeの導入状態はdirectoryの有無を推測せず、最初に次のtyped discoveryで判定します。
+
+```bash
+lattice status --json
+```
+
+`state`は`uninitialized | ready | active_run | invalid`のいずれかです。`uninitialized`は
+正常な未初期化状態で、`next_action`が正規の初期authoring入口を返します。初回planは
+新規planはPhase監査とToDo schedulingを分離する`lattice.plan_create_input.v3`のcanonical
+JSON+LFを用意し、次で作成します。既存v2/v4は互換契約として維持されます。
+
+```bash
+lattice plan create --schema-version 3 --json
+```
+
+```bash
+lattice plan create --input .lattice/plan-create.json
+```
+
+`invalid`をMarkdown fallbackへ丸めず、`next_action`に従ってstoreを診断してください。
+discoveryと初期transactionの不変条件は
+[ADR 0058](docs/adr/0058-project-discovery-and-initial-authoring.md)が正です。
+
+TODO工程storeの読取は`lattice todo status`、検証は`lattice todo verify`、表示生成は
+`lattice todo gantt`を使います。topology/source reconciliationは
+`lattice todo revise --plan <key> --input <canonical-revision.json>`、Phase付きplanは
+`lattice todo revise-phase --plan <key> --input <canonical-phase-revision.json>`でsuccessor発行します。
+cross-plan topologyを同時に切り替える場合は
+`lattice todo revise-set --input <canonical-revision-set.json>`を使い、Phase revisionを含む集合は
+`lattice.todo_revision_set.v3`で通常revisionと混在できます。
+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>`で理由を残します。
+
+```bash
+lattice todo start --plan <key> --task <id> --parallel-frontier
+lattice todo start --plan <key> --task <id> --override-reason <reason>
+```
+
+`--parallel-frontier`はhostへ並列dispatch方針を宣言する開始gateです。Lattice自身がAI hostのagentを
+起動するものではなく、実際のdispatchはhostが行います。宣言後もready全件が着手されたかは
+`active_set`と`next_ready`で観測できます。
+ToDo完了は軽量確認までで、所属ToDoが全てdoneになったPhaseは`gate_ready`となり、`todo phase review`後に
+required evidenceを束縛した`todo phase accept`で重監査の判断を記録します。監査回数やPhase数を自動追加する
+機能ではありません。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経路で同時表示できます。
+session開始時のtyped discoveryで使う`lattice status --json`と、actor環境変数を持つ通常のTODO操作は
+active projectを自動登録し、一つのloopback dashboard daemonを再利用します。
+`/projects/`の一覧からproject固有の工程図を開け、各projectのSSE更新は互いに分離されます。
+LANや外部reverse proxyから閲覧するoptional bridgeは既定で無効です。明示したIPにだけbindする初回設定、
+再設定、停止方法は[bridge setup](docs/bridge-setup.md)を参照してください。
+静的工程表は`lattice todo gantt status`で`current / stale / missing`を確認でき、HTMLまたは
+digest付きsidecarの欠落・改ざんはtyped failureになります。
+状態を書き込む`start / block / unblock / done / evidence promote / reopen / revise / revise-phase / revise-set`
+では、監査actorとして次の3環境変数をすべて設定してください。
+
+```bash
+export LATTICE_TODO_ACTOR_HOST=<host-id>
+export LATTICE_TODO_ACTOR_SESSION=<session-id>
+export LATTICE_TODO_ACTOR_AGENT=<agent-id>
+```
+
+不足またはidentifierとして不正な値がある場合、mutationはstoreを変更せず`ACTOR_UNRESOLVED`を返します。
+error detailの`missing_environment`／`invalid_environment`と
+`next_action: set_required_actor_environment_and_retry`を確認し、正規値を設定して同じ操作を再試行してください。
+
+正確なargv、evidence descriptor、result wireは
+[ADR 0056](docs/adr/0056-todo-authoring-transitions.md)を参照してください。

package/bin/lattice-bridge.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import { readBridgeConfig } from '../src/bridge-config.mjs';
+import {
+  readBridgeStopRequest, removeBridgeDaemonActiveMarker, removeBridgeDaemonDescriptor,
+  writeBridgeDaemonDescriptor, writeBridgeStopReceipt,
+} from '../src/bridge-daemon.mjs';
+import { bridgeRuntimeController } from '../src/bridge-server.mjs';
+
+const env = process.env;
+const instanceToken = env.LATTICE_BRIDGE_INSTANCE_TOKEN;
+if (typeof instanceToken !== 'string' || !/^[0-9a-f]{64}$/u.test(instanceToken)) {
+  process.stderr.write(`${JSON.stringify({ schema: 'lattice.bridge_daemon_error.v1',
+    code: 'BRIDGE_INSTANCE_TOKEN_INVALID', message: 'bridge instance token is invalid' })}\n`);
+  process.exit(1);
+}
+const controller = bridgeRuntimeController({ env, instanceToken });
+let timer;
+let closing = false;
+let descriptorFingerprint = null;
+let checking = false;
+let failClosedError = null;
+const close = async () => {
+  if (closing) return;
+  closing = true;
+  clearInterval(timer);
+  await controller.close();
+};
+
+try {
+  const stopRequest = await readBridgeStopRequest({ env });
+  if (stopRequest !== null) {
+    await writeBridgeStopReceipt({ nonce: stopRequest.nonce, env });
+    await removeBridgeDaemonDescriptor({ env });
+    await removeBridgeDaemonActiveMarker({ env });
+    process.exit(0);
+  }
+  const config = await readBridgeConfig({ env });
+  if (config === null || !config.enabled) throw Object.assign(new Error('bridge disabled'), { code: 'BRIDGE_DISABLED' });
+  await controller.reconcile();
+  await writeBridgeDaemonDescriptor({ config, env });
+  descriptorFingerprint = config.updated_at;
+} catch (error) {
+  process.stderr.write(`${JSON.stringify({ schema: 'lattice.bridge_daemon_error.v1',
+    code: error?.code ?? 'BRIDGE_DAEMON_FAILED', message: error?.message ?? 'bridge daemon failed' })}\n`);
+  process.exit(1);
+}
+
+timer = setInterval(async () => {
+  if (checking || closing) return;
+  checking = true;
+  try {
+    const stopRequest = await readBridgeStopRequest({ env });
+    if (stopRequest !== null) {
+      await close();
+      await writeBridgeStopReceipt({ nonce: stopRequest.nonce, env });
+      await removeBridgeDaemonDescriptor({ env });
+      await removeBridgeDaemonActiveMarker({ env });
+      process.exit(0);
+    }
+    const config = await readBridgeConfig({ env });
+    if (config === null || !config.enabled) {
+      await close();
+      await removeBridgeDaemonDescriptor({ env });
+      await removeBridgeDaemonActiveMarker({ env });
+      process.exit(0);
+    }
+    await controller.reconcile();
+    failClosedError = null;
+    if (descriptorFingerprint !== config.updated_at) {
+      await writeBridgeDaemonDescriptor({ config, env });
+      descriptorFingerprint = config.updated_at;
+    }
+  } catch (error) {
+    const failure = { schema: 'lattice.bridge_daemon_error.v1',
+      code: error?.code ?? 'BRIDGE_RECONCILE_FAILED',
+      message: error?.message ?? 'bridge reconcile failed' };
+    const fingerprint = JSON.stringify(failure);
+    if (fingerprint !== failClosedError) process.stderr.write(`${fingerprint}\n`);
+    failClosedError = fingerprint;
+    // Public traffic fails closed immediately. Keep only the local control loop alive so an
+    // authenticated nonce stop request can still receive a socket-closed receipt.
+    await controller.close();
+  } finally { checking = false; }
+}, 250);
+process.once('SIGINT', () => close().finally(() => process.exit(0)));
+process.once('SIGTERM', () => close().finally(() => process.exit(0)));

package/bin/lattice-dashboard.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { readTodoStoreStable } from '../src/todo-store.mjs';
+import { renderTodoGanttForProject } from '../src/todo-cli.mjs';
+import {
+  readActiveTodoDashboardProjects,
+  writeTodoDashboardDaemonDescriptor,
+} from '../src/todo-dashboard-registry.mjs';
+import {
+  createTodoGanttProjectRegistry,
+  startTodoGanttDashboardServer,
+} from '../src/todo-gantt-live.mjs';
+
+const args = process.argv.slice(2);
+if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+  process.stdout.write('Usage: lattice-dashboard\n');
+  process.exit(0);
+}
+if (args.length > 0) {
+  process.stderr.write('Usage: lattice-dashboard\n');
+  process.exit(2);
+}
+
+const env = process.env;
+const configured = env.LATTICE_DASHBOARD_PORT;
+const port = typeof configured === 'string' && /^(?:0|[1-9][0-9]{0,4})$/u.test(configured)
+  && Number(configured) <= 65_535 ? Number(configured) : 0;
+const registry = createTodoGanttProjectRegistry();
+const roots = new Map();
+
+async function synchronize() {
+  const active = await readActiveTodoDashboardProjects({ env });
+  const activeIds = new Set(active.map(({ project_id: projectId }) => projectId));
+  for (const projectId of roots.keys()) {
+    if (!activeIds.has(projectId)) {
+      registry.unregister(projectId);
+      roots.delete(projectId);
+    }
+  }
+  for (const entry of active) {
+    const binding = `${entry.repo_root}\0${entry.display_name}`;
+    if (roots.get(entry.project_id) === binding) continue;
+    registry.unregister(entry.project_id);
+    registry.register({
+      projectId: entry.project_id,
+      displayName: entry.display_name,
+      render: async ({ displayName }) => {
+        const result = await renderTodoGanttForProject({ repoRoot: entry.repo_root,
+          stable: true, displayName });
+        return { html: result.rendered.html, head_digest: result.metadata.manifest_digest };
+      },
+      readHead: async () => (await readTodoStoreStable({ repoRoot: entry.repo_root })).manifest.manifest_digest,
+    });
+    roots.set(entry.project_id, binding);
+  }
+  return active.length;
+}
+
+await synchronize();
+const dashboard = await startTodoGanttDashboardServer({ registry, port });
+await writeTodoDashboardDaemonDescriptor({ port: dashboard.port, env });
+const timer = setInterval(() => synchronize().then((count) => {
+  if (count === 0) process.exit(0);
+}).catch(() => process.exit(1)), 1_000);
+const close = async () => {
+  clearInterval(timer);
+  await dashboard.close();
+};
+process.once('SIGINT', () => close().finally(() => process.exit(0)));
+process.once('SIGTERM', () => close().finally(() => process.exit(0)));

package/bin/lattice-mcp.mjs

@@ -3,10 +3,10 @@
  * Lattice MCP server entrypoint (ADR 0049 Decision 8).
  *
  * Thin bin that delegates to the sensor's MCP server — the same server
- * `codegraph serve --mcp` starts (see sensor/src/bin/codegraph.ts `serve`
+ * `sensor serve --mcp` starts (see sensor/src/bin/sensor.ts `serve`
  * command and sensor/src/mcp/index.ts `MCPServer`). Deliberately a SEPARATE
  * bin from `bin/lattice.mjs`: the CLI 6 面 axioms (stdout versioned JSON 1
- * 行, exit 0/1/2, `lattice.cli_error.v1`) apply ONLY to lattice.mjs, never
+ * 行, exit 0/1/2, `lattice.cli_error.v2`) apply ONLY to lattice.mjs, never
  * to this MCP surface (ADR 0049 Decision 1/8).
  *
  * Contract (ADR 0049 Decision 8):
@@ -14,7 +14,7 @@
  *      (The sensor's own MCPServer already honors this; nothing here writes
  *      to stdout.)
  *   ② Accepts the INTERNAL daemon re-invoke form (`serve --mcp --path
- *      <root>` + CODEGRAPH_DAEMON_INTERNAL=1 env). The shared daemon
+ *      <root>` + LATTICE_SENSOR_DAEMON_INTERNAL=1 env). The shared daemon
  *      re-execs `process.argv[1]` with exactly this argv shape
  *      (sensor/src/mcp/index.ts `spawnDetachedDaemon`) — when this process
  *      IS `process.argv[1]` (an MCP host launched it directly as
@@ -22,7 +22,7 @@
  *      unable to ever start, silently pinning every session to direct mode
  *      (the exact silent-degradation trap the ADR calls out).
  *   ③ Exit semantics: usage violation before startup = exit 2; startup
- *      scrutiny failure = exit 1 + one `lattice.cli_error.v1` line on
+ *      scrutiny failure = exit 1 + one `lattice.cli_error.v2` line on
  *      stderr; normal session end = exit 0 (delegated entirely to
  *      MCPServer, which calls process.exit on every one of its lifecycle
  *      paths — direct/proxy/daemon alike); session-established failures are
@@ -30,7 +30,7 @@
  *      process alive for those).
  *   ④ Node version guard (wave2レビューでのスコープ外発見の修理): this bin
  *      imports `../sensor/dist/index.js` directly, bypassing the sensor
- *      CLI's own Node-version guard (sensor/src/bin/codegraph.ts, guarding
+ *      CLI's own Node-version guard (sensor/src/bin/sensor.ts, guarding
  *      against a Node 25.x V8 turboshaft WASM JIT Zone allocator OOM during
  *      tree-sitter grammar compilation, and a MIN_NODE_MAJOR floor). This
  *      file re-applies the SAME check — reusing thresholds/banners from
@@ -44,7 +44,7 @@
 
 import { evaluateNodeVersionGuard } from '../src/node-version-guard.mjs';
 
-const CLI_ERROR_SCHEMA = 'lattice.cli_error.v1';
+const CLI_ERROR_SCHEMA = 'lattice.cli_error.v2';
 
 /** Usage violation BEFORE startup — exit 2, plain-text stderr (mirrors bin/lattice.mjs's own usageFailure shape). */
 function usageFailure(message) {
@@ -52,7 +52,7 @@ function usageFailure(message) {
   process.exitCode = 2;
 }
 
-/** Startup-time scrutiny failure — exit 1, one lattice.cli_error.v1 JSON line on stderr. */
+/** Startup-time scrutiny failure — exit 1, one lattice.cli_error.v2 JSON line on stderr. */
 function startupFailure(code, message) {
   const payload = { schema: CLI_ERROR_SCHEMA, code, message };
   process.stderr.write(`${JSON.stringify(payload)}\n`);
@@ -95,12 +95,12 @@ function parseArgs(argv) {
 // Node version guard (④) — runs before anything else, including argv
 // parsing, so it also covers the internal daemon re-invoke form (②) which
 // re-execs this exact file. Same semantics as the sensor CLI: nodeMajor >=
-// 25 or < MIN_NODE_MAJOR blocks unless CODEGRAPH_ALLOW_UNSAFE_NODE is set,
+// 25 or < MIN_NODE_MAJOR blocks unless LATTICE_SENSOR_ALLOW_UNSAFE_NODE is set,
 // in which case the banner is shown for visibility only and startup
 // continues.
 const nodeVersionGuard = evaluateNodeVersionGuard(
   process.versions.node,
-  Boolean(process.env.CODEGRAPH_ALLOW_UNSAFE_NODE),
+  Boolean(process.env.LATTICE_SENSOR_ALLOW_UNSAFE_NODE),
 );
 if (nodeVersionGuard.banner) {
   process.stderr.write(`${nodeVersionGuard.banner}\n`);

package/bin/lattice.mjs

@@ -1,22 +1,75 @@
 #!/usr/bin/env node
 
-import { buildBootstrapDiagnostics } from '../src/bootstrap.mjs';
 import { runRuntimeCli } from '../src/runtime-cli.mjs';
+import { renderCliHelp } from '../src/cli-help.mjs';
 import packageJson from '../package.json' with { type: 'json' };
 
 const args = process.argv.slice(2);
+const help = renderCliHelp(args);
 
-if (args.length === 1 && args[0] === '--version') {
+if (help !== null) {
+  process.stdout.write(help);
+} else if (args.length === 1 && args[0] === '--version') {
   process.stdout.write(`${packageJson.version}\n`);
-} else if (args.length === 2 && args[0] === 'doctor' && args[1] === '--json') {
-  process.stdout.write(`${JSON.stringify(buildBootstrapDiagnostics())}\n`);
+} else if (args.length === 2 && args[0] === 'status' && args[1] === '--json') {
+  const { projectStatusFailure, runProjectStatus } = await import('../src/project-cli.mjs');
+  try {
+    process.exitCode = await runProjectStatus({
+      cwd: process.cwd(), stdout: process.stdout, cliVersion: packageJson.version, env: process.env,
+    });
+  } catch (error) {
+    process.exitCode = projectStatusFailure({
+      cwd: process.cwd(), stdout: process.stdout, cliVersion: packageJson.version, error,
+    });
+  }
+} else if (args.length === 4 && args[0] === 'plan' && args[1] === 'create' && args[2] === '--input') {
+  const { projectCliFailure, runPlanCreate } = await import('../src/project-cli.mjs');
+  try {
+    process.exitCode = await runPlanCreate({ cwd: process.cwd(), inputRef: args[3], stdout: process.stdout });
+  } catch (error) {
+    process.exitCode = projectCliFailure(process.stderr, error);
+  }
+} else if (args.length === 4 && args[0] === 'plan' && args[1] === 'create'
+  && args[2] === '--schema' && args[3] === '--json') {
+  const { projectCliFailure, runPlanCreateSchema } = await import('../src/project-cli.mjs');
+  try {
+    process.exitCode = await runPlanCreateSchema({ stdout: process.stdout });
+  } catch (error) {
+    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') {
+  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 === 2 && args[0] === 'factory-diagnostics' && args[1] === '--json') {
   const { buildFactoryDiagnostics } = await import('../src/factory-diagnostics.mjs');
   const diagnostics = await buildFactoryDiagnostics();
   process.stdout.write(`${JSON.stringify(diagnostics)}\n`);
   process.exitCode = diagnostics.overall === 'ok' ? 0 : 1;
+} else if (args[0] === 'sensor') {
+  const { runSensorCli } = await import('../src/sensor-cli.mjs');
+  process.exitCode = await runSensorCli({
+    argv: args.slice(1), stdout: process.stdout, stderr: process.stderr,
+  });
 } else if (args[0] === 'runtime-errors') {
   process.exitCode = await runRuntimeErrorsCli(args.slice(1));
+} else if (args[0] === 'todo') {
+  const { runTodoCli } = await import('../src/todo-cli.mjs');
+  process.exitCode = await runTodoCli({
+    argv: args.slice(1),
+    cwd: process.cwd(),
+    stdout: process.stdout,
+    stderr: process.stderr,
+  });
+} else if (args[0] === 'bridge') {
+  const { runBridgeCli } = await import('../src/bridge-cli.mjs');
+  process.exitCode = await runBridgeCli({
+    argv: args.slice(1), stdout: process.stdout, stderr: process.stderr, env: process.env,
+  });
 } else {
   try {
     process.exitCode = await runRuntimeCli({
@@ -26,10 +79,10 @@ if (args.length === 1 && args[0] === '--version') {
       stderr: process.stderr,
     });
   } catch (error) {
-    // typed契約（cli_error.v1＋exit 1/2）の外へ漏れた例外＝内部故障。opt-in時のみ観測を残す。
+    // typed契約（cli_error.v2＋exit 1/2）の外へ漏れた例外＝内部故障。opt-in時のみ観測を残す。
     const { observeRuntimeError } = await import('../src/runtime-errors.mjs');
     observeRuntimeError('LATTICE.CLI_INTERNAL_FAILED', { version: packageJson.version });
-    process.stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v1', code: 'INTERNAL_FAILURE', message: error?.constructor?.name ?? 'Error' })}\n`);
+    process.stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2', code: 'INTERNAL_FAILURE', message: error?.constructor?.name ?? 'Error' })}\n`);
     process.exitCode = 1;
   }
 }
@@ -37,7 +90,7 @@ if (args.length === 1 && args[0] === '--version') {
 async function runRuntimeErrorsCli(rest) {
   const runtimeErrors = await import('../src/runtime-errors.mjs');
   const usage = () => {
-    process.stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v1', code: 'USAGE', message: 'usage: lattice runtime-errors <snapshot [--after-cursor N] [--limit N]|ack <cursor>|diagnostics|resolve <fingerprint>|reopen <fingerprint>|compact> --json' })}\n`);
+    process.stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2', code: 'USAGE', message: 'usage: lattice runtime-errors <snapshot [--after-cursor N] [--limit N]|ack <cursor>|diagnostics|resolve <fingerprint>|reopen <fingerprint>|compact> --json' })}\n`);
     return 2;
   };
   const options = { version: packageJson.version };
@@ -72,7 +125,7 @@ async function runRuntimeErrorsCli(rest) {
     process.stdout.write(`${JSON.stringify(result)}\n`);
     return 0;
   } catch (error) {
-    process.stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v1', code: 'RUNTIME_ERRORS_FAILED', message: error?.message ?? 'unknown' })}\n`);
+    process.stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2', code: 'RUNTIME_ERRORS_FAILED', message: error?.message ?? 'unknown' })}\n`);
     return 1;
   }
 }

package/docs/bridge-setup.md

@@ -0,0 +1,87 @@
+# Optional network bridge
+
+Latticeのproject dashboardは既定でloopbackだけにbindし、bridge用socketや設定を作らない。
+LAN上のreverse proxyなどから閲覧する時だけ、利用者がlisten IPを明示してbridgeを有効化する。
+`postinstall`では質問やnetwork公開を行わない。
+
+TTYでは`lattice bridge setup`で安全側既定の対話wizardを開始できる。最初の公開確認は既定で無効を選び、
+cancelした場合は設定を変更しない。非TTYではhangせず、次の非対話commandを案内する。
+portを省略するか`auto`にすると、49152–65535から候補を重複なく選び、
+実際のexclusive bindとhealth確認に成功したportだけを保存する。
+
+```bash
+lattice bridge setup --listen 192.168.1.102 --port auto --dashboard --allow-host lattice.kitepon.dev --json
+```
+
+`--dashboard`は現在のlocal dashboard descriptorをrequestごとに解決するため、dashboard再起動でportが変わっても
+bridge設定はstaleにならない。固定upstreamを使う場合だけ`--upstream http://127.0.0.1:4318`を指定する。
+listen IPは常に許可Hostへ入り、reverse proxyで公開するhostnameは`--allow-host`を反復して追加する。
+許可されていないHostは421となるため、DNS rebinding originへ工程情報を返さない。
+
+```bash
+lattice bridge status --json
+lattice bridge reconfigure --listen 192.168.1.102 --port auto --dashboard --json
+lattice bridge disable --json
+```
+
+設定は`~/.lattice/bridge.json`へmode 0600でatomic保存する。`setup`／`reconfigure`は実bridge daemonが
+選択socketをexclusive bindしhealthを返すまで成功にしない。起動に失敗した場合は旧設定へ戻す。
+`disable`もbridge socketの停止確認後に成功し、loopbackのlocal dashboardは停止しない。
+configまたはdaemon descriptorが壊れている場合、`disable`は公開socketのfail-closed停止を優先して破損control
+fileを除去し、JSON結果の`recovery`へ処置を明示する。その後は`setup`で再設定できる。
+
+自動化・隔離testではabsoluteな`LATTICE_CONFIG_DIR`で設定rootを変更できる。無効な設定、低いport、
+使用中の明示port、危険なrequest target、到達不能upstreamはsilent fallbackせずtyped errorを返す。
+
+## Docker Caddy／Cloudflare Tunnelへ接続する
+
+bridgeを有効化したMacとreverse proxy hostの間で、まず許可Hostを付けたLAN到達を確認する。
+この段階が失敗している時はDNSやTunnelを追加しない。
+
+```bash
+curl --fail --header 'Host: lattice.example.com' \
+  http://MAC_LAN_IP:BRIDGE_PORT/projects/
+```
+
+Caddyは既存のDocker networkと証明書運用を維持し、Lattice用siteだけを追加する。
+
+```caddyfile
+lattice.example.com {
+	reverse_proxy MAC_LAN_IP:BRIDGE_PORT {
+		flush_interval -1
+	}
+}
+```
+
+本番反映はcontainer内で`caddy validate`を通してから`caddy reload`する。Caddyfileを単一ファイルで
+bind mountしている構成では、atomic renameでhost側fileを置換するとcontainerが旧inodeを参照し続ける。
+更新前backupを残し、inodeを維持するin-place更新を使うか、directory bind mountへ変更する。
+
+remote-managed Cloudflare Tunnelでは、Tunnel実行tokenを設定APIの代用にしない。Cloudflareの正規管理面で
+public hostname `lattice.kitepon.dev` を次のoriginへ対応付ける。
+
+- Service: `https://caddy:443`
+- TLS Origin Server Name: `lattice.kitepon.dev`（管理面に同等の設定がある場合は`Match SNI to Host`でもよい）
+
+`http://caddy:80`は選ばない。CaddyのHTTPからHTTPSへのredirectをTunnelがorigin応答として返す構成は、
+外部requestが同じ公開URLへ戻るredirect loopになり得るためである。外部gateではredirectを追って200にせず、
+最初の応答がHTTPSの200であることを確認する。
+
+受入は次の3 gateを独立して記録し、後段の成功で前段を代用しない。
+
+1. **LAN bridge**: reverse proxy hostから許可Host付きで`http://MAC_LAN_IP:BRIDGE_PORT/projects/`が200。
+2. **Docker Caddy**: Caddyへ`Host: lattice.kitepon.dev`を付けたHTTPS requestが200。証明書検証を省略する
+   内部probeを外部公開成功の証拠にはしない。
+3. **Cloudflare public HTTPS**: `https://lattice.kitepon.dev/projects/`がredirectなしで200となり、一覧から開いた
+   `/projects/<project_id>/`のHTML titleが`Lattice — <project名> 依存工程図`である。
+
+外部gateはHTMLだけで閉じず、各projectの
+`https://lattice.kitepon.dev/projects/<project_id>/events`も確認する。応答は200かつ
+`Content-Type: text/event-stream`で、接続直後に`event: state`と現在の`head_digest`を返さなければならない。
+接続を開いたまま正規のTodo更新を行い、新しい`state`が同じstreamへ届くことを確認する。切断後に再接続しても
+再び初回`state`が届き、そのdigestが最新headと一致することまでを継続・再接続gateとする。
+
+```bash
+curl --fail --show-error --include --no-buffer --max-time 15 \
+  https://lattice.kitepon.dev/projects/PROJECT_ID/events
+```

package/docs/schemas/lattice.plan_create_input.v1.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/kitepon-rgb/Lattice/blob/main/docs/schemas/lattice.plan_create_input.v1.schema.json",
+  "title": "lattice.plan_create_input.v1",
+  "description": "Canonical initial authoring input for lattice plan create.",
+  "$comment": "Runtime validation additionally enforces canonical JSON+LF bytes, strict ordering, unique task ids, graph validity, byte bounds, and input_digest as the canonical self-digest.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "project_id", "plan_key", "plan_version", "actor", "recorded_at", "tasks", "hard_dependencies", "joins", "input_digest"],
+  "properties": {
+    "schema": { "const": "lattice.plan_create_input.v1" },
+    "project_id": { "$ref": "#/$defs/identifier" },
+    "plan_key": { "$ref": "#/$defs/identifier" },
+    "plan_version": { "$ref": "#/$defs/identifier" },
+    "actor": { "$ref": "#/$defs/actor" },
+    "recorded_at": { "$ref": "#/$defs/strictTimestamp" },
+    "tasks": { "type": "array", "minItems": 1, "maxItems": 512, "items": { "$ref": "#/$defs/task" } },
+    "hard_dependencies": { "type": "array", "maxItems": 2048, "items": { "$ref": "#/$defs/edge" } },
+    "joins": { "type": "array", "maxItems": 128, "items": { "$ref": "#/$defs/join" } },
+    "input_digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "identifier": { "type": "string", "pattern": "^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$" },
+    "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "repoRef": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*\\\\)(?!.*[\\u0000-\\u001f\\u007f])[^/]+(?:/[^/]+)*$" },
+    "strictTimestamp": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$" },
+    "nullableRepoRef": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/repoRef" }] },
+    "nullableIdentifier": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/identifier" }] },
+    "actor": {
+      "type": "object", "additionalProperties": false, "required": ["host", "session", "agent"],
+      "properties": { "host": { "$ref": "#/$defs/identifier" }, "session": { "$ref": "#/$defs/identifier" }, "agent": { "$ref": "#/$defs/identifier" } }
+    },
+    "task": {
+      "type": "object", "additionalProperties": false,
+      "required": ["task_id", "title", "lane", "narrative_ref", "narrative_anchor", "compile_binding", "parent_task_id"],
+      "properties": {
+        "task_id": { "$ref": "#/$defs/identifier" }, "title": { "oneOf": [{ "type": "null" }, { "type": "string", "minLength": 1, "maxLength": 16384 }] },
+        "lane": { "$ref": "#/$defs/identifier" }, "narrative_ref": { "$ref": "#/$defs/nullableRepoRef" },
+        "narrative_anchor": { "type": "null" }, "compile_binding": { "type": "null" },
+        "parent_task_id": { "$ref": "#/$defs/nullableIdentifier" }
+      }
+    },
+    "nodeRef": {
+      "type": "object", "additionalProperties": false, "required": ["project_id", "plan_key", "task_id"],
+      "properties": { "project_id": { "$ref": "#/$defs/identifier" }, "plan_key": { "$ref": "#/$defs/identifier" }, "task_id": { "$ref": "#/$defs/identifier" }, "expected_topology_digest": { "$ref": "#/$defs/digest" } }
+    },
+    "edge": {
+      "type": "object", "additionalProperties": false, "required": ["from", "to"],
+      "properties": { "from": { "$ref": "#/$defs/nodeRef" }, "to": { "$ref": "#/$defs/nodeRef" } }
+    },
+    "join": {
+      "type": "object", "additionalProperties": false, "required": ["id", "after", "before"],
+      "properties": { "id": { "$ref": "#/$defs/identifier" }, "after": { "type": "array", "minItems": 1, "maxItems": 512, "items": { "$ref": "#/$defs/nodeRef" } }, "before": { "$ref": "#/$defs/nodeRef" } }
+    }
+  }
+}