@quolu/lattice 0.35.0 → 0.36.1

package/README.ja.md

@@ -197,7 +197,34 @@ lattice todo migrate --input <extraction.json> --serialization-reviewed
 `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

@@ -50,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/docs/schemas/lattice.phase_todo_revision.v3.schema.json

@@ -0,0 +1,312 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/kitepon-rgb/Lattice/blob/main/docs/schemas/lattice.phase_todo_revision.v3.schema.json",
+  "title": "lattice.phase_todo_revision.v3",
+  "description": "`lattice todo revise-phase`が受理する最新契約。v1/v2のphase-audited desired state・task/phase migrationへ、runtime task migration・source inventory・per-ToDo source cutover batchを加えた12 keyの完全契約。",
+  "$comment": "Runtime validation (src/todo-revision.mjs validatePhaseTodoRevision) additionally enforces: canonical JSON+LF bytes; strict sort order on task_migration (by from_task_id), runtime_task_migration.entries (by predecessor_task_id), runtime_task_migration.entries[].successor_task_ids/evidence_digests, and source_inventory.excluded_tombstones/source_cutover_batch.operations (by source_ref); uniqueness constraints across all of those; desired_plan.plan_version === phaseTodoRevisionPlanVersion(...); runtime_task_migration projects onto task_migration exactly (validRuntimeTodoProjection) and its successor_task_ids cover exactly desired_plan.tasks; phase_migration's target phase set equals desired_plan.phases exactly; every reconciliation.*_digest field against its own recomputation; and revision_digest as the canonical self-digest over every other top-level field.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema", "project_id", "plan_key", "predecessor", "desired_plan",
+    "runtime_task_migration", "task_migration", "phase_migration", "source_inventory",
+    "reconciliation", "source_cutover_batch", "revision_digest"
+  ],
+  "properties": {
+    "schema": { "const": "lattice.phase_todo_revision.v3" },
+    "project_id": { "$ref": "#/$defs/identifier" },
+    "plan_key": { "$ref": "#/$defs/identifier" },
+    "predecessor": { "$ref": "#/$defs/predecessor" },
+    "desired_plan": { "$ref": "#/$defs/desiredPlanV5" },
+    "runtime_task_migration": { "$ref": "#/$defs/runtimeTaskMigration" },
+    "task_migration": {
+      "type": "array", "minItems": 1, "maxItems": 512,
+      "items": { "$ref": "#/$defs/taskMigrationEntry" }
+    },
+    "phase_migration": {
+      "type": "array", "minItems": 1, "maxItems": 512,
+      "items": { "$ref": "#/$defs/phaseMigrationEntry" }
+    },
+    "source_inventory": { "$ref": "#/$defs/sourceInventory" },
+    "reconciliation": {
+      "type": "object", "additionalProperties": false,
+      "required": [
+        "predecessor_reconciliation_digest", "source_inventory_digest", "desired_plan_digest",
+        "runtime_task_migration_digest", "task_migration_digest", "phase_migration_digest",
+        "source_cutover_batch_digest", "reconciliation_digest"
+      ],
+      "properties": {
+        "predecessor_reconciliation_digest": { "$ref": "#/$defs/digest" },
+        "source_inventory_digest": { "$ref": "#/$defs/digest" },
+        "desired_plan_digest": { "$ref": "#/$defs/digest" },
+        "runtime_task_migration_digest": { "$ref": "#/$defs/digest" },
+        "task_migration_digest": { "$ref": "#/$defs/digest" },
+        "phase_migration_digest": { "$ref": "#/$defs/digest" },
+        "source_cutover_batch_digest": { "$ref": "#/$defs/digest" },
+        "reconciliation_digest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "source_cutover_batch": { "$ref": "#/$defs/sourceCutoverBatch" },
+    "revision_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}$" },
+    "nullableDigest": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/digest" }] },
+    "gitSha": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "repoRef": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*\\\\)(?!.*[\\u0000-\\u001f\\u007f])[^/]+(?:/[^/]+)*$"
+    },
+    "sourceLineRef": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "$comment": "repoRefと同じ形に加え#L<line>を必須にする。実際の判定はparseTodoSourceRef（src/todo-revision.mjs）。",
+      "pattern": "^(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*\\\\)(?!.*[\\u0000-\\u001f\\u007f])[^/]+(?:/[^/]+)*#L[1-9][0-9]*$"
+    },
+    "nullableRepoRef": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/repoRef" }] },
+    "text": { "type": "string", "minLength": 1, "maxLength": 16384 },
+    "nullableText": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/text" }] },
+    "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" }
+      }
+    },
+    "phaseRef": {
+      "type": "object", "additionalProperties": false,
+      "required": ["project_id", "plan_key", "phase_id"],
+      "properties": {
+        "project_id": { "$ref": "#/$defs/identifier" },
+        "plan_key": { "$ref": "#/$defs/identifier" },
+        "phase_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" } }
+    },
+    "phaseAcceptDependency": {
+      "type": "object", "additionalProperties": false, "required": ["from", "to"],
+      "properties": { "from": { "$ref": "#/$defs/phaseRef" }, "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" }
+      }
+    },
+    "narrativeAnchor": {
+      "type": "object", "additionalProperties": false,
+      "required": ["origin_plan_ref", "origin_line", "source_commit", "source_line_digest"],
+      "properties": {
+        "origin_plan_ref": { "$ref": "#/$defs/repoRef" },
+        "origin_line": { "type": "integer", "minimum": 1 },
+        "source_commit": { "type": "string", "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$" },
+        "source_line_digest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "compileBinding": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["boundary_manifest_digest", "compiled_plan_digest", "topology_digest", "base_sha"],
+          "properties": {
+            "boundary_manifest_digest": { "$ref": "#/$defs/digest" },
+            "compiled_plan_digest": { "$ref": "#/$defs/digest" },
+            "topology_digest": { "$ref": "#/$defs/digest" },
+            "base_sha": { "$ref": "#/$defs/gitSha" }
+          }
+        }
+      ]
+    },
+    "predecessor": {
+      "type": "object", "additionalProperties": false,
+      "required": ["plan_digest", "journal_head_digest", "plan_version"],
+      "properties": {
+        "plan_digest": { "$ref": "#/$defs/digest" },
+        "journal_head_digest": { "$ref": "#/$defs/digest" },
+        "plan_version": { "$ref": "#/$defs/identifier" }
+      }
+    },
+    "taskV4": {
+      "type": "object", "additionalProperties": false,
+      "required": [
+        "task_id", "title", "lane", "narrative_ref", "narrative_anchor", "compile_binding",
+        "parent_task_id", "phase_id"
+      ],
+      "properties": {
+        "task_id": { "$ref": "#/$defs/identifier" },
+        "title": { "$ref": "#/$defs/nullableText" },
+        "lane": { "$ref": "#/$defs/identifier" },
+        "narrative_ref": { "$ref": "#/$defs/nullableRepoRef" },
+        "narrative_anchor": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/narrativeAnchor" }] },
+        "compile_binding": { "$ref": "#/$defs/compileBinding" },
+        "parent_task_id": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/identifier" }] },
+        "phase_id": { "$ref": "#/$defs/identifier" }
+      }
+    },
+    "phase": {
+      "type": "object", "additionalProperties": false,
+      "required": ["phase_id", "title", "gate_policy", "predecessor_phase_ids", "required_evidence_slots"],
+      "properties": {
+        "phase_id": { "$ref": "#/$defs/identifier" },
+        "title": { "$ref": "#/$defs/nullableText" },
+        "gate_policy": { "$ref": "#/$defs/identifier" },
+        "predecessor_phase_ids": {
+          "type": "array", "items": { "$ref": "#/$defs/identifier" }, "uniqueItems": true
+        },
+        "required_evidence_slots": {
+          "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/identifier" }, "uniqueItems": true
+        }
+      }
+    },
+    "desiredPlanV5": {
+      "type": "object", "additionalProperties": false,
+      "required": [
+        "schema", "project_id", "plan_key", "plan_version", "predecessor_plan_digest",
+        "tasks", "hard_dependencies", "joins", "phases", "phase_accept_dependencies",
+        "topology_digest", "plan_digest"
+      ],
+      "properties": {
+        "schema": { "const": "lattice.todo_plan.v5" },
+        "project_id": { "$ref": "#/$defs/identifier" },
+        "plan_key": { "$ref": "#/$defs/identifier" },
+        "plan_version": { "$ref": "#/$defs/identifier" },
+        "predecessor_plan_digest": { "$ref": "#/$defs/nullableDigest" },
+        "tasks": { "type": "array", "minItems": 1, "maxItems": 512, "items": { "$ref": "#/$defs/taskV4" } },
+        "hard_dependencies": { "type": "array", "maxItems": 2048, "items": { "$ref": "#/$defs/edge" } },
+        "joins": { "type": "array", "maxItems": 128, "items": { "$ref": "#/$defs/join" } },
+        "phases": { "type": "array", "minItems": 1, "maxItems": 512, "items": { "$ref": "#/$defs/phase" } },
+        "phase_accept_dependencies": {
+          "type": "array", "maxItems": 2048, "items": { "$ref": "#/$defs/phaseAcceptDependency" }
+        },
+        "topology_digest": { "$ref": "#/$defs/digest" },
+        "plan_digest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "taskMigrationEntry": {
+      "type": "object", "additionalProperties": false,
+      "required": ["from_task_id", "to_task_id", "state_policy"],
+      "properties": {
+        "from_task_id": { "$ref": "#/$defs/identifier" },
+        "to_task_id": { "oneOf": [{ "const": "removed" }, { "$ref": "#/$defs/identifier" }] },
+        "state_policy": {
+          "enum": ["carry", "carry_reconciled_metadata", "reset_pending", "removed"],
+          "$comment": "'removed'はto_task_id==='removed'の時だけ、他の3値はto_task_idがidentifierの時だけ許される（runtime cross-check）。runtime_task_migrationのdisposition投影とも一致していなければならない（validRuntimeTodoProjection）。"
+        }
+      }
+    },
+    "phaseMigrationEntry": {
+      "type": "object", "additionalProperties": false,
+      "required": ["from_phase_id", "to_phase_id", "state_policy"],
+      "properties": {
+        "from_phase_id": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/identifier" }] },
+        "to_phase_id": { "oneOf": [{ "const": "removed" }, { "$ref": "#/$defs/identifier" }] },
+        "state_policy": {
+          "enum": ["carry", "reset", "removed"],
+          "$comment": "carryはfrom_phase_id!=null かつ to_phase_id!=='removed'の時だけ、removedはfrom_phase_id!=null かつ to_phase_id==='removed'の時だけ、resetはto_phase_id!=='removed'の時だけ許される（runtime cross-check）。"
+        }
+      }
+    },
+    "runtimeTaskMigrationEntry": {
+      "type": "object", "additionalProperties": false,
+      "required": ["predecessor_task_id", "disposition", "successor_task_ids", "reason", "evidence_digests"],
+      "properties": {
+        "predecessor_task_id": { "$ref": "#/$defs/identifier" },
+        "disposition": { "enum": ["carry", "stay", "replace", "split", "retire"] },
+        "successor_task_ids": {
+          "type": "array", "maxItems": 512, "items": { "$ref": "#/$defs/identifier" }, "uniqueItems": true,
+          "$comment": "carry/stayは要素1つでpredecessor_task_idと同一、retireは空、replace/splitは1つ以上（runtime cross-check）。全entry合算で重複禁止。"
+        },
+        "reason": { "$ref": "#/$defs/text" },
+        "evidence_digests": {
+          "type": "array", "minItems": 1, "maxItems": 512, "items": { "$ref": "#/$defs/digest" },
+          "uniqueItems": true
+        }
+      }
+    },
+    "runtimeTaskMigration": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schema", "entries", "migration_digest"],
+      "properties": {
+        "schema": { "const": "lattice.runtime_task_migration.v1" },
+        "entries": {
+          "type": "array", "minItems": 1, "maxItems": 512,
+          "items": { "$ref": "#/$defs/runtimeTaskMigrationEntry" }
+        },
+        "migration_digest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "sourceInventoryActiveEntry": {
+      "type": "object", "additionalProperties": false,
+      "required": ["task_id", "source_ref", "source_digest"],
+      "properties": {
+        "task_id": { "$ref": "#/$defs/identifier" },
+        "source_ref": { "$ref": "#/$defs/sourceLineRef" },
+        "source_digest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "sourceInventoryTombstone": {
+      "type": "object", "additionalProperties": false,
+      "required": ["source_ref", "source_digest", "exclusion_reason"],
+      "properties": {
+        "source_ref": { "$ref": "#/$defs/sourceLineRef" },
+        "source_digest": { "$ref": "#/$defs/digest" },
+        "exclusion_reason": { "$ref": "#/$defs/text" }
+      }
+    },
+    "sourceInventory": {
+      "type": "object", "additionalProperties": false,
+      "required": ["active", "excluded_tombstones"],
+      "$comment": "activeはdesired_plan.tasksと同じ順序・同じtask_id集合でなければならず、各entryのsource_refはそのtaskのnarrative_refと一致する必要がある（revise-phase v3固有のrequireNarrativeRef、runtime cross-check）。",
+      "properties": {
+        "active": {
+          "type": "array", "maxItems": 512, "items": { "$ref": "#/$defs/sourceInventoryActiveEntry" }
+        },
+        "excluded_tombstones": {
+          "type": "array", "maxItems": 2048, "items": { "$ref": "#/$defs/sourceInventoryTombstone" }
+        }
+      }
+    },
+    "sourceCutoverOperation": {
+      "type": "object", "additionalProperties": false,
+      "required": ["task_id", "disposition", "source_ref", "source_digest", "live_replacement"],
+      "properties": {
+        "task_id": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/identifier" }] },
+        "disposition": { "enum": ["active", "excluded"] },
+        "source_ref": { "$ref": "#/$defs/sourceLineRef" },
+        "source_digest": { "$ref": "#/$defs/digest" },
+        "live_replacement": {
+          "type": "string", "minLength": 1, "maxLength": 4096,
+          "$comment": "改行・制御文字禁止に加え、Markdownチェックボックス行に見える文字列は拒否される（validLiveReplacement）。"
+        }
+      }
+    },
+    "sourceCutoverBatch": {
+      "type": "object", "additionalProperties": false,
+      "required": ["batch_id", "archive_ref", "operations", "batch_digest"],
+      "properties": {
+        "batch_id": { "$ref": "#/$defs/identifier" },
+        "archive_ref": {
+          "allOf": [{ "$ref": "#/$defs/repoRef" }, { "pattern": "\\.md$" }],
+          "$comment": "#L<line>付きのsourceLineRef形にはなり得ない（runtime cross-check）。"
+        },
+        "operations": {
+          "type": "array", "minItems": 1, "maxItems": 512, "items": { "$ref": "#/$defs/sourceCutoverOperation" }
+        },
+        "batch_digest": { "$ref": "#/$defs/digest" }
+      }
+    }
+  }
+}