@quolu/lattice 0.63.0 → 0.63.2

package/sensor/dist/mcp/server-instructions.js

@@ -18,79 +18,79 @@ exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0
  * burn tokens. ADR 0049 / 0059 require the eight compatibility tools to remain
  * visible by default; provider identity is Lattice regardless of their names.
  */
-exports.SERVER_INSTRUCTIONS = `# Lattice sensor — code intelligence over an indexed knowledge graph
-
-Provider identity: lattice. The lattice_sensor_* names below are compatibility tool names served by Lattice's own bundled sensor; they do not call or require the independent Lattice sensor product.
-
-Lattice sensor is a SQLite knowledge graph of every symbol, edge, and file in
-the workspace — pre-computed structure you would otherwise re-derive by
-reading files (cached intelligence: thousands of parse/trace decisions you
-don't pay to re-reason each run). Reads are sub-millisecond; the index lags
-writes by ~1s through the file watcher. Reach for it BEFORE *and* while
-writing or editing code — not just for questions: one call returns the
-verbatim source PLUS who calls it and what it affects, so you edit with the
-blast radius in view. More accurate context, in far fewer tokens and
-round-trips than reading files yourself.
-
-## One tool: lattice_sensor_explore — use it instead of reading files
-
-There is a single tool, \`lattice_sensor_explore\`, and it is Read-equivalent. It
-takes either a natural-language question or a bag of symbol/file names and
-returns the **verbatim, line-numbered source** of the relevant symbols
-grouped by file — the same \`<n>\\t<line>\` shape \`Read\` gives you, safe to
-\`Edit\` from — PLUS the call path among them (including dynamic-dispatch hops
-like callbacks, React re-render, and JSX children that grep can't follow) and
-a blast-radius summary of what depends on them.
-
-Whether you're answering "how does X work" or implementing a change (fixing a
-bug, adding a feature), call \`lattice_sensor_explore\` before you Read. ONE call
-usually answers the whole question. Lattice sensor IS the pre-built search index —
-so running your own grep + read loop, or delegating the lookup to a separate
-file-reading sub-task/agent, repeats work lattice sensor already did and costs more
-for the same answer. A direct lattice sensor answer is typically one to a few
-calls; a grep/read exploration is dozens.
-
-## How to query
-
-- **Almost any question — "how does X work", architecture, a bug, "what/where is X", or surveying an area** → \`lattice_sensor_explore\` with a natural-language question or the relevant names. ONE capped call returns the verbatim source grouped by file; most often the ONLY call you need.
-- **"How does X reach/become Y? / the flow / the path from X to Y"** → \`lattice_sensor_explore\`, naming the symbols that span the flow (e.g. \`mutateElement renderScene\`) — it surfaces the call path among them, riding dynamic-dispatch hops, and returns their source.
-- **Reading or editing a file/symbol you can name** → put its name or file path in the \`lattice_sensor_explore\` query — it returns that current line-numbered source (safe to \`Edit\` from) with the call path and blast radius attached, so you don't Read it separately. For an overloaded name it returns every matching definition's body in one call.
-- **Need more?** Call \`lattice_sensor_explore\` again with more specific names — treat the source it returns as already Read.
-
-## Anti-patterns
-
-- **Trust lattice sensor's results — don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.
-- **Don't grep or Read first** to find or understand indexed code — ONE \`lattice_sensor_explore\` returns the relevant symbols' source together in a single round-trip. Reach for raw \`Read\`/\`Grep\` only to confirm a specific detail lattice sensor didn't cover, or for what lattice sensor doesn't index (configs, docs).
-- **Don't reconstruct a flow by hand** — name the endpoints in one \`lattice_sensor_explore\` and it surfaces the path between them, dynamic-dispatch hops included.
-- **After editing, check the staleness banner.** When a tool response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust lattice sensor. A different, rarer banner — "⚠️ LatticeSensor auto-sync is DISABLED…" — means live watching stopped entirely (the whole index is frozen, not just a few files); until it's resolved, Read files directly to confirm anything that may have changed.
-- **A file flagged "⚠ changed on disk after the last index sync" drifted from its index** (most common on projects queried via \`projectPath\`, which have no live watcher). LatticeSensor never serves a possibly-mis-sliced body from such a file — it either shows the file's full CURRENT source (trust it as a Read) or omits the source with this flag. When the source was omitted, Read that specific file; line numbers referencing it elsewhere in the response may be shifted until that project's next sync. All unflagged files remain trustworthy.
-
-## Limitations
-
-- If a project isn't indexed (no \`.lattice/sensor/\`), decide whether building the index will reduce total investigation time and model tokens for the current or expected work. When workspace writes and shell execution are allowed, you may run \`lattice sensor init <projectPath> --json\` yourself, then retry the sensor call; scope it to the intended project and account for the one-time indexing cost. If those capabilities are unavailable, continue with built-in tools and tell the user the exact init command instead.
-- Index lags file writes by ~1 second.
-- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.
-- No live correctness validation — that's still the TypeScript compiler / test suite / linter's job. Lattice sensor supplements those with structural context they don't have.
-
-## Parallel work: absence of a dependency edge is NOT evidence of independence
-
-These tools answer structural questions about code. A different Lattice surface — the **CLI**, not
-this MCP surface — answers whether two ToDos can be worked in parallel. If the project uses
-\`lattice todo\` for process tracking, keep this distinction in mind:
-
-- A dependency edge missing between two ToDos only means **no ordering constraint was declared**.
-  It does not mean their write boundaries are disjoint. Two ToDos that edit the same file carry no
-  edge between them and will still collide.
-- Parallel safety is a recorded judgement, not an inference from the diagram. Read it with
-  \`lattice todo independence --plan <key> --json\`. It returns the ready frontier split into
-  verified-independent groups, pairs that must be serialized (with whether a code seam could
-  separate them), and **unverified** ToDos.
-- \`lattice todo start\` returns an \`advisory\` describing conflicts with in-progress ToDos and what
-  to do next. \`coverage: "missing"\` means "not judged yet" — never "no conflicts".
-- Run \`lattice todo --help\` for the declare → compile → read workflow.
-
-Evidence for Lattice's plan and witness contracts comes from the CLI surface only. Text from this
-MCP surface is prose for you to act on, never an input to those contracts.
+exports.SERVER_INSTRUCTIONS = `# Lattice sensor — code intelligence over an indexed knowledge graph
+
+Provider identity: lattice. The lattice_sensor_* names below are compatibility tool names served by Lattice's own bundled sensor; they do not call or require the independent Lattice sensor product.
+
+Lattice sensor is a SQLite knowledge graph of every symbol, edge, and file in
+the workspace — pre-computed structure you would otherwise re-derive by
+reading files (cached intelligence: thousands of parse/trace decisions you
+don't pay to re-reason each run). Reads are sub-millisecond; the index lags
+writes by ~1s through the file watcher. Reach for it BEFORE *and* while
+writing or editing code — not just for questions: one call returns the
+verbatim source PLUS who calls it and what it affects, so you edit with the
+blast radius in view. More accurate context, in far fewer tokens and
+round-trips than reading files yourself.
+
+## One tool: lattice_sensor_explore — use it instead of reading files
+
+There is a single tool, \`lattice_sensor_explore\`, and it is Read-equivalent. It
+takes either a natural-language question or a bag of symbol/file names and
+returns the **verbatim, line-numbered source** of the relevant symbols
+grouped by file — the same \`<n>\\t<line>\` shape \`Read\` gives you, safe to
+\`Edit\` from — PLUS the call path among them (including dynamic-dispatch hops
+like callbacks, React re-render, and JSX children that grep can't follow) and
+a blast-radius summary of what depends on them.
+
+Whether you're answering "how does X work" or implementing a change (fixing a
+bug, adding a feature), call \`lattice_sensor_explore\` before you Read. ONE call
+usually answers the whole question. Lattice sensor IS the pre-built search index —
+so running your own grep + read loop, or delegating the lookup to a separate
+file-reading sub-task/agent, repeats work lattice sensor already did and costs more
+for the same answer. A direct lattice sensor answer is typically one to a few
+calls; a grep/read exploration is dozens.
+
+## How to query
+
+- **Almost any question — "how does X work", architecture, a bug, "what/where is X", or surveying an area** → \`lattice_sensor_explore\` with a natural-language question or the relevant names. ONE capped call returns the verbatim source grouped by file; most often the ONLY call you need.
+- **"How does X reach/become Y? / the flow / the path from X to Y"** → \`lattice_sensor_explore\`, naming the symbols that span the flow (e.g. \`mutateElement renderScene\`) — it surfaces the call path among them, riding dynamic-dispatch hops, and returns their source.
+- **Reading or editing a file/symbol you can name** → put its name or file path in the \`lattice_sensor_explore\` query — it returns that current line-numbered source (safe to \`Edit\` from) with the call path and blast radius attached, so you don't Read it separately. For an overloaded name it returns every matching definition's body in one call.
+- **Need more?** Call \`lattice_sensor_explore\` again with more specific names — treat the source it returns as already Read.
+
+## Anti-patterns
+
+- **Trust lattice sensor's results — don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.
+- **Don't grep or Read first** to find or understand indexed code — ONE \`lattice_sensor_explore\` returns the relevant symbols' source together in a single round-trip. Reach for raw \`Read\`/\`Grep\` only to confirm a specific detail lattice sensor didn't cover, or for what lattice sensor doesn't index (configs, docs).
+- **Don't reconstruct a flow by hand** — name the endpoints in one \`lattice_sensor_explore\` and it surfaces the path between them, dynamic-dispatch hops included.
+- **After editing, check the staleness banner.** When a tool response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust lattice sensor. A different, rarer banner — "⚠️ LatticeSensor auto-sync is DISABLED…" — means live watching stopped entirely (the whole index is frozen, not just a few files); until it's resolved, Read files directly to confirm anything that may have changed.
+- **A file flagged "⚠ changed on disk after the last index sync" drifted from its index** (most common on projects queried via \`projectPath\`, which have no live watcher). LatticeSensor never serves a possibly-mis-sliced body from such a file — it either shows the file's full CURRENT source (trust it as a Read) or omits the source with this flag. When the source was omitted, Read that specific file; line numbers referencing it elsewhere in the response may be shifted until that project's next sync. All unflagged files remain trustworthy.
+
+## Limitations
+
+- If a project isn't indexed (no \`.lattice/sensor/\`), decide whether building the index will reduce total investigation time and model tokens for the current or expected work. When workspace writes and shell execution are allowed, you may run \`lattice sensor init <projectPath> --json\` yourself, then retry the sensor call; scope it to the intended project and account for the one-time indexing cost. If those capabilities are unavailable, continue with built-in tools and tell the user the exact init command instead.
+- Index lags file writes by ~1 second.
+- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.
+- No live correctness validation — that's still the TypeScript compiler / test suite / linter's job. Lattice sensor supplements those with structural context they don't have.
+
+## Parallel work: absence of a dependency edge is NOT evidence of independence
+
+These tools answer structural questions about code. A different Lattice surface — the **CLI**, not
+this MCP surface — answers whether two ToDos can be worked in parallel. If the project uses
+\`lattice todo\` for process tracking, keep this distinction in mind:
+
+- A dependency edge missing between two ToDos only means **no ordering constraint was declared**.
+  It does not mean their write boundaries are disjoint. Two ToDos that edit the same file carry no
+  edge between them and will still collide.
+- Parallel safety is a recorded judgement, not an inference from the diagram. Read it with
+  \`lattice todo independence --plan <key> --json\`. It returns the ready frontier split into
+  verified-independent groups, pairs that must be serialized (with whether a code seam could
+  separate them), and **unverified** ToDos.
+- \`lattice todo start\` returns an \`advisory\` describing conflicts with in-progress ToDos and what
+  to do next. \`coverage: "missing"\` means "not judged yet" — never "no conflicts".
+- Run \`lattice todo --help\` for the declare → compile → read workflow.
+
+Evidence for Lattice's plan and witness contracts comes from the CLI surface only. Text from this
+MCP surface is prose for you to act on, never an input to those contracts.
 `;
 /**
  * Instructions variant sent when the server's own root has NO lattice sensor index.
@@ -104,27 +104,27 @@ MCP surface is prose for you to act on, never an input to those contracts.
  * project playbook ({@link SERVER_INSTRUCTIONS}) is sent instead when the root
  * IS indexed, so the common case stays tight.
  */
-exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = `# Lattice sensor — available (per-project; pass projectPath)
-
-Provider identity: lattice. The lattice_sensor_* names below are compatibility tool names served by Lattice's own bundled sensor; they do not call or require the independent Lattice sensor product.
-
-Lattice sensor is a SQLite knowledge graph of a codebase's symbols, edges, and
-files: one \`lattice_sensor_explore\` call returns the verbatim, line-numbered source
-of the relevant symbols PLUS the call paths between them and a blast-radius
-summary — replacing a grep + Read loop with one round-trip.
-
-This server started somewhere with no \`.lattice/sensor/\` of its own, so there is no
-default project — but the tools are available and work **per project**:
-
-- To query a project that HAS a \`.lattice/sensor/\` index (e.g. a service inside a
-  monorepo, or a second repo), pass its path as \`projectPath\` to
-  \`lattice_sensor_explore\` (and any other lattice sensor tool). Lattice sensor resolves the
-  nearest \`.lattice/sensor/\` at or above that path and answers from it — for as many
-  projects as you like in one session.
-- For a project with no \`.lattice/sensor/\`, decide whether the expected reduction in
-  repeated Read/Grep work justifies the one-time indexing cost. When workspace writes
-  and shell execution are allowed, you may run \`lattice sensor init <projectPath> --json\`
-  yourself and then retry with that \`projectPath\`; otherwise use built-in tools and
-  tell the user the exact init command. A new index is picked up live, with no restart.
+exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = `# Lattice sensor — available (per-project; pass projectPath)
+
+Provider identity: lattice. The lattice_sensor_* names below are compatibility tool names served by Lattice's own bundled sensor; they do not call or require the independent Lattice sensor product.
+
+Lattice sensor is a SQLite knowledge graph of a codebase's symbols, edges, and
+files: one \`lattice_sensor_explore\` call returns the verbatim, line-numbered source
+of the relevant symbols PLUS the call paths between them and a blast-radius
+summary — replacing a grep + Read loop with one round-trip.
+
+This server started somewhere with no \`.lattice/sensor/\` of its own, so there is no
+default project — but the tools are available and work **per project**:
+
+- To query a project that HAS a \`.lattice/sensor/\` index (e.g. a service inside a
+  monorepo, or a second repo), pass its path as \`projectPath\` to
+  \`lattice_sensor_explore\` (and any other lattice sensor tool). Lattice sensor resolves the
+  nearest \`.lattice/sensor/\` at or above that path and answers from it — for as many
+  projects as you like in one session.
+- For a project with no \`.lattice/sensor/\`, decide whether the expected reduction in
+  repeated Read/Grep work justifies the one-time indexing cost. When workspace writes
+  and shell execution are allowed, you may run \`lattice sensor init <projectPath> --json\`
+  yourself and then retry with that \`projectPath\`; otherwise use built-in tools and
+  tell the user the exact init command. A new index is picked up live, with no restart.
 `;
 //# sourceMappingURL=server-instructions.js.map

package/sensor/package.json

@@ -1,56 +1,56 @@
-{
-  "name": "@quolu/lattice-sensor",
-  "version": "0.7.3-lattice.1",
-  "private": true,
-  "description": "Lattice-owned local structural sensor.",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kitepon/Lattice.git"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "npm run clean && tsc && npm run copy-assets",
-    "copy-assets": "node -e \"const fs=require('fs');fs.mkdirSync('dist/db',{recursive:true});fs.copyFileSync('src/db/schema.sql','dist/db/schema.sql');fs.mkdirSync('dist/extraction/wasm',{recursive:true});fs.readdirSync('src/extraction/wasm').filter(f=>f.endsWith('.wasm')).forEach(f=>fs.copyFileSync('src/extraction/wasm/'+f,'dist/extraction/wasm/'+f))\"",
-    "dev": "tsc --watch",
-    "build:kernel": "bash scripts/build-kernel.sh",
-    "test": "vitest run --maxWorkers=4 --minWorkers=1",
-    "test:watch": "vitest",
-    "test:eval": "vitest run __tests__/evaluation/",
-    "eval": "npm run build && npx tsx __tests__/evaluation/runner.ts",
-    "clean": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true})\""
-  },
-  "keywords": [
-    "code-intelligence",
-    "knowledge-graph",
-    "static-analysis"
-  ],
-  "author": "",
-  "license": "MIT",
-  "dependencies": {
-    "@clack/prompts": "^1.3.0",
-    "commander": "^14.0.2",
-    "fast-string-width": "^3.0.2",
-    "fast-wrap-ansi": "^0.2.0",
-    "ignore": "^7.0.5",
-    "jsonc-parser": "^3.3.1",
-    "picomatch": "^4.0.4",
-    "sisteransi": "^1.0.5",
-    "tree-sitter-wasms": "^0.1.11",
-    "web-tree-sitter": "^0.25.3"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.0",
-    "@types/node": "^20.19.30",
-    "@types/picomatch": "^4.0.2",
-    "typescript": "^5.0.0",
-    "vitest": "^2.1.9"
-  },
-  "engines": {
-    "node": ">=20.0.0 <25.0.0 || >=26.0.0"
-  }
-}
+{
+  "name": "@quolu/lattice-sensor",
+  "version": "0.7.3-lattice.1",
+  "private": true,
+  "description": "Lattice-owned local structural sensor.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitepon/Lattice.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "npm run clean && tsc && npm run copy-assets",
+    "copy-assets": "node -e \"const fs=require('fs');fs.mkdirSync('dist/db',{recursive:true});fs.copyFileSync('src/db/schema.sql','dist/db/schema.sql');fs.mkdirSync('dist/extraction/wasm',{recursive:true});fs.readdirSync('src/extraction/wasm').filter(f=>f.endsWith('.wasm')).forEach(f=>fs.copyFileSync('src/extraction/wasm/'+f,'dist/extraction/wasm/'+f))\"",
+    "dev": "tsc --watch",
+    "build:kernel": "bash scripts/build-kernel.sh",
+    "test": "vitest run --maxWorkers=4 --minWorkers=1",
+    "test:watch": "vitest",
+    "test:eval": "vitest run __tests__/evaluation/",
+    "eval": "npm run build && npx tsx __tests__/evaluation/runner.ts",
+    "clean": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true})\""
+  },
+  "keywords": [
+    "code-intelligence",
+    "knowledge-graph",
+    "static-analysis"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.3.0",
+    "commander": "^14.0.2",
+    "fast-string-width": "^3.0.2",
+    "fast-wrap-ansi": "^0.2.0",
+    "ignore": "^7.0.5",
+    "jsonc-parser": "^3.3.1",
+    "picomatch": "^4.0.4",
+    "sisteransi": "^1.0.5",
+    "tree-sitter-wasms": "^0.1.11",
+    "web-tree-sitter": "^0.25.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^20.19.30",
+    "@types/picomatch": "^4.0.2",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=20.0.0 <25.0.0 || >=26.0.0"
+  }
+}

package/src/project-cli.mjs

@@ -397,7 +397,100 @@ async function readCanonicalInput(repoRoot, inputRef) {
   }
 }
 
-function validateCreateInput(value) {
+/**
+ * buildTodoPlanは通ったか否かしか返さない。authorが実際に書くtasks・phasesについて、
+ * 落ちた最初の条件をpointer付きで名指しする。ここで拾えない違反だけ総称へ落とす。
+ * 整列要求（task_id昇順など）はJSON Schemaに書けないので、ここが唯一の案内面になる。
+ */
+function describePlanShapeViolation(value, { phaseInput }) {
+  const TASK_KEYS = ['task_id', 'title', 'lane', 'design_memo', 'narrative_ref',
+    'narrative_anchor', 'compile_binding', 'parent_task_id', 'phase_id'];
+  const PHASE_KEYS = ['phase_id', 'title', 'gate_policy', 'predecessor_phase_ids',
+    'required_evidence_slots'];
+
+  if (value.tasks.length === 0) {
+    return { violation_kind: 'empty', pointer: '/tasks',
+      expected: { min_items: 1 }, actual: { length: 0 } };
+  }
+  for (const [index, task] of value.tasks.entries()) {
+    if (!exactRecord(task, TASK_KEYS)) {
+      return { violation_kind: 'unexpected_or_missing_keys', pointer: `/tasks/${index}`,
+        expected: { keys: [...TASK_KEYS].sort() },
+        actual: (task === null || typeof task !== 'object')
+          ? { type: task === null ? 'null' : typeof task }
+          : { keys: Object.keys(task).sort() } };
+    }
+    for (const field of ['task_id', 'lane', 'phase_id']) {
+      if (!isTodoIdentifier(task[field])) {
+        return { violation_kind: 'identifier_invalid', pointer: `/tasks/${index}/${field}`,
+          expected: { format: 'todo_identifier' }, actual: task[field] };
+      }
+    }
+    if (index > 0 && !(value.tasks[index - 1].task_id < task.task_id)) {
+      return { violation_kind: 'unsorted', pointer: `/tasks/${index}/task_id`,
+        expected: { greater_than: value.tasks[index - 1].task_id, order: 'ascending_unique' },
+        actual: task.task_id };
+    }
+  }
+  if (!phaseInput) return null;
+
+  if (!Array.isArray(value.phases) || value.phases.length === 0) {
+    return { violation_kind: 'empty', pointer: '/phases', expected: { min_items: 1 },
+      actual: Array.isArray(value.phases) ? { length: 0 } : { type: typeof value.phases } };
+  }
+  for (const [index, phase] of value.phases.entries()) {
+    if (!exactRecord(phase, PHASE_KEYS)) {
+      return { violation_kind: 'unexpected_or_missing_keys', pointer: `/phases/${index}`,
+        expected: { keys: [...PHASE_KEYS].sort() },
+        actual: (phase === null || typeof phase !== 'object')
+          ? { type: phase === null ? 'null' : typeof phase }
+          : { keys: Object.keys(phase).sort() } };
+    }
+    for (const field of ['phase_id', 'gate_policy']) {
+      if (!isTodoIdentifier(phase[field])) {
+        return { violation_kind: 'identifier_invalid', pointer: `/phases/${index}/${field}`,
+          expected: { format: 'todo_identifier' }, actual: phase[field] };
+      }
+    }
+    if (!Array.isArray(phase.required_evidence_slots) || phase.required_evidence_slots.length === 0) {
+      return { violation_kind: 'empty',
+        pointer: `/phases/${index}/required_evidence_slots`,
+        expected: { min_items: 1, note: 'Phase gateが要求する証跡slotを1つ以上挙げる' },
+        actual: Array.isArray(phase.required_evidence_slots)
+          ? { length: 0 } : { type: typeof phase.required_evidence_slots } };
+    }
+    for (const field of ['predecessor_phase_ids', 'required_evidence_slots']) {
+      const list = phase[field];
+      const unsorted = list.findIndex((entry, i) => i > 0 && !(list[i - 1] < entry));
+      if (unsorted > 0) {
+        return { violation_kind: 'unsorted', pointer: `/phases/${index}/${field}/${unsorted}`,
+          expected: { greater_than: list[unsorted - 1], order: 'ascending_unique' },
+          actual: list[unsorted] };
+      }
+    }
+    if (index > 0 && !(value.phases[index - 1].phase_id < phase.phase_id)) {
+      return { violation_kind: 'unsorted', pointer: `/phases/${index}/phase_id`,
+        expected: { greater_than: value.phases[index - 1].phase_id, order: 'ascending_unique' },
+        actual: phase.phase_id };
+    }
+  }
+  const phaseIds = new Set(value.phases.map(({ phase_id }) => phase_id));
+  const orphan = value.tasks.findIndex(({ phase_id }) => !phaseIds.has(phase_id));
+  if (orphan >= 0) {
+    return { violation_kind: 'unknown_reference', pointer: `/tasks/${orphan}/phase_id`,
+      expected: { one_of: [...phaseIds].sort() }, actual: value.tasks[orphan].phase_id };
+  }
+  return null;
+}
+
+/**
+ * plan create入力の違反を、通ったか否かでなく「どこがどう違うか」で返す。
+ * 以前は巨大な `||` 連鎖と `catch { return false }` で理由を捨てており、
+ * 呼び手には pointer `/` と `validation: failed` しか届かなかった。
+ * 直せない指摘は指摘ではないので、最初に落ちた条件をpointer付きで返す。
+ * 違反が無ければ null。
+ */
+function describeCreateInputViolation(value) {
   const phaseInput = [PHASE_CREATE_INPUT_SCHEMA, DECOUPLED_PHASE_CREATE_INPUT_SCHEMA,
     MEMO_PHASE_CREATE_INPUT_SCHEMA].includes(value?.schema);
   const decoupledPhaseInput = [DECOUPLED_PHASE_CREATE_INPUT_SCHEMA,
@@ -408,18 +501,61 @@ function validateCreateInput(value) {
   ];
   if (phaseInput) keys.push('phases');
   if (decoupledPhaseInput) keys.push('phase_accept_dependencies');
-  if (!exactRecord(value, keys) || ![
-    CREATE_INPUT_SCHEMA, PHASE_CREATE_INPUT_SCHEMA, DECOUPLED_PHASE_CREATE_INPUT_SCHEMA,
-    MEMO_PHASE_CREATE_INPUT_SCHEMA,
-  ].includes(value.schema)
-    || !isTodoIdentifier(value.project_id)
-    || !isTodoIdentifier(value.plan_key) || !isTodoIdentifier(value.plan_version)
-    || !exactRecord(value.actor, ['host', 'session', 'agent'])
-    || ![value.actor.host, value.actor.session, value.actor.agent].every(isTodoIdentifier)
-    || !isStrictTodoTimestamp(value.recorded_at) || !isTodoDigest(value.input_digest)
-    || value.input_digest !== todoSelfDigest(value, 'input_digest')
-    || !Array.isArray(value.tasks)
-    || value.tasks.some((task) => task?.narrative_anchor !== null || task?.compile_binding !== null)) return false;
+
+  if (!exactRecord(value, keys)) {
+    const actual = (value === null || typeof value !== 'object' || Array.isArray(value))
+      ? { type: value === null ? 'null' : typeof value }
+      : { keys: Object.keys(value).sort() };
+    return { violation_kind: 'unexpected_or_missing_keys', pointer: '/',
+      expected: { keys: [...keys].sort() }, actual };
+  }
+  const schemas = [CREATE_INPUT_SCHEMA, PHASE_CREATE_INPUT_SCHEMA,
+    DECOUPLED_PHASE_CREATE_INPUT_SCHEMA, MEMO_PHASE_CREATE_INPUT_SCHEMA];
+  if (!schemas.includes(value.schema)) {
+    return { violation_kind: 'const_mismatch', pointer: '/schema',
+      expected: { one_of: schemas }, actual: value.schema };
+  }
+  for (const field of ['project_id', 'plan_key', 'plan_version']) {
+    if (!isTodoIdentifier(value[field])) {
+      return { violation_kind: 'identifier_invalid', pointer: `/${field}`,
+        expected: { format: 'todo_identifier' }, actual: value[field] };
+    }
+  }
+  if (!exactRecord(value.actor, ['host', 'session', 'agent'])) {
+    return { violation_kind: 'unexpected_or_missing_keys', pointer: '/actor',
+      expected: { keys: ['agent', 'host', 'session'] },
+      actual: (value.actor === null || typeof value.actor !== 'object')
+        ? { type: value.actor === null ? 'null' : typeof value.actor }
+        : { keys: Object.keys(value.actor).sort() } };
+  }
+  for (const field of ['host', 'session', 'agent']) {
+    if (!isTodoIdentifier(value.actor[field])) {
+      return { violation_kind: 'identifier_invalid', pointer: `/actor/${field}`,
+        expected: { format: 'todo_identifier' }, actual: value.actor[field] };
+    }
+  }
+  if (!isStrictTodoTimestamp(value.recorded_at)) {
+    return { violation_kind: 'timestamp_invalid', pointer: '/recorded_at',
+      expected: { format: 'strict_iso8601_utc_milliseconds' }, actual: value.recorded_at };
+  }
+  if (!isTodoDigest(value.input_digest)
+    || value.input_digest !== todoSelfDigest(value, 'input_digest')) {
+    return { violation_kind: 'input_digest_mismatch', pointer: '/input_digest',
+      expected: todoSelfDigest(value, 'input_digest'),
+      actual: { type: typeof value.input_digest, matches_canonical_input: false } };
+  }
+  if (!Array.isArray(value.tasks)) {
+    return { violation_kind: 'type', pointer: '/tasks', expected: { type: 'array' },
+      actual: { type: value.tasks === null ? 'null' : typeof value.tasks } };
+  }
+  for (const [index, task] of value.tasks.entries()) {
+    for (const field of ['narrative_anchor', 'compile_binding']) {
+      if (task?.[field] !== null) {
+        return { violation_kind: 'not_authorable_at_create', pointer: `/tasks/${index}/${field}`,
+          expected: null, actual: task?.[field] };
+      }
+    }
+  }
   try {
     buildTodoPlan({
       schema: value.schema === MEMO_PHASE_CREATE_INPUT_SCHEMA ? 'lattice.todo_plan.v7'
@@ -431,8 +567,18 @@ function validateCreateInput(value) {
       ...(phaseInput ? { phases: value.phases } : {}),
       ...(decoupledPhaseInput ? { phase_accept_dependencies: value.phase_accept_dependencies } : {}),
     });
-    return true;
-  } catch { return false; }
+  } catch (error) {
+    // buildTodoPlanは通否しか返さない。authorが書いた形を自分で診てpointerを出す。
+    const shape = describePlanShapeViolation(value, { phaseInput });
+    if (shape !== null) return shape;
+    return {
+      violation_kind: error?.reason ?? error?.code ?? 'topology_invalid',
+      pointer: error?.detail?.pointer ?? '/',
+      expected: error?.detail?.expected ?? { schema: value.schema },
+      actual: error?.detail?.actual ?? { message: String(error?.message ?? error) },
+    };
+  }
+  return null;
 }
 
 export async function runPlanCreate({ cwd, inputRef, stdout }) {
@@ -463,16 +609,10 @@ export async function runPlanCreate({ cwd, inputRef, stdout }) {
       prompt: TODO_DESIGN_MEMO_PROMPT, next_action: CURRENT_CREATE_SCHEMA_COMMAND,
     });
   }
-  if (!validateCreateInput(input)) {
-    const digestValid = isTodoDigest(input.input_digest)
-      && input.input_digest === todoSelfDigest(input, 'input_digest');
+  const violation = describeCreateInputViolation(input);
+  if (violation !== null) {
     throw new TodoStoreError('INPUT_INVALID', 'plan_create_schema_invalid', undefined, {
-      violation_kind: digestValid ? 'schema_or_topology_invalid' : 'input_digest_mismatch',
-      pointer: digestValid ? '/' : '/input_digest',
-      expected: digestValid ? { schema: MEMO_PHASE_CREATE_INPUT_SCHEMA }
-        : todoSelfDigest(input, 'input_digest'),
-      actual: digestValid ? { validation: 'failed' }
-        : { type: typeof input.input_digest, matches_canonical_input: false },
+      ...violation,
       next_action: 'correct_the_reported_pointer_then_rerun_plan_create',
     });
   }

package/src/todo-authoring-input.mjs

@@ -91,7 +91,20 @@ export function repairAuthoringArtifact(value) {
   return next;
 }
 
-export async function resolveAuthoringInputPath(repoRoot, inputRef) {
+/**
+ * 渡された値がpathでなく本文そのものに見えるか。
+ * `--input`/`--evidence`はfileを取るが、AIも人もインラインの文章を渡して詰まる。
+ * 詰まった時に「fileを取る／文章なら--message」と言えるように判定する。
+ */
+function looksLikeProse(value) {
+  if (typeof value !== 'string') return false;
+  return value.length > 160
+    || /[\n\r]/u.test(value)
+    || /[、。「」（）]/u.test(value)
+    || (/\s/u.test(value) && !/[/\\]/u.test(value));
+}
+
+export async function resolveAuthoringInputPath(repoRoot, inputRef, { inlineFlag = null } = {}) {
   if (typeof inputRef !== 'string' || inputRef.length === 0) {
     fail('INPUT_UNREADABLE', 'input_ref_invalid', { input_ref: inputRef });
   }
@@ -101,19 +114,35 @@ export async function resolveAuthoringInputPath(repoRoot, inputRef) {
     : path.resolve(canonicalRoot, inputRef);
   let stats;
   try { stats = await lstat(candidate); } catch {
-    fail('INPUT_UNREADABLE', 'input_missing', { input_ref: inputRef });
+    fail('INPUT_UNREADABLE', 'input_missing', {
+      input_ref: inputRef,
+      repo_root: canonicalRoot,
+      next_action: looksLikeProse(inputRef)
+        ? (inlineFlag
+          ? `この引数はrepo内のfile pathを取る。文章をそのまま渡すなら ${inlineFlag} <text> を使う`
+          : 'この引数はrepo内のfile pathを取る。渡された値は本文に見える——先にfileへ書いてからそのpathを渡す')
+        : `repo内に存在するfile pathを渡す（repo_root: ${canonicalRoot}）`,
+    });
   }
   if (stats.isSymbolicLink() || !stats.isFile()) {
     fail('INPUT_UNREADABLE', 'unsafe_input_path', { input_ref: inputRef });
   }
   const resolved = await realpath(candidate);
   if (!within(canonicalRoot, resolved) || resolved === canonicalRoot) {
-    fail('INPUT_UNREADABLE', 'input_path_outside_repo', { input_ref: inputRef });
+    fail('INPUT_UNREADABLE', 'input_path_outside_repo', {
+      input_ref: inputRef,
+      repo_root: canonicalRoot,
+      next_action: `repo内のfileだけ受理する。repo外(/tmp等)にあるならrepo内へ写してから渡す（repo_root: ${canonicalRoot}）`,
+    });
   }
   if (stats.size > MAX_AUTHORING_INPUT_BYTES) fail('INPUT_TOO_LARGE', 'input_size_limit_exceeded');
   const relative = path.relative(canonicalRoot, resolved);
   if (relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) {
-    fail('INPUT_UNREADABLE', 'input_path_outside_repo', { input_ref: inputRef });
+    fail('INPUT_UNREADABLE', 'input_path_outside_repo', {
+      input_ref: inputRef,
+      repo_root: canonicalRoot,
+      next_action: `repo内のfileだけ受理する。repo外(/tmp等)にあるならrepo内へ写してから渡す（repo_root: ${canonicalRoot}）`,
+    });
   }
   return {
     absolute: resolved,
@@ -124,8 +153,9 @@ export async function resolveAuthoringInputPath(repoRoot, inputRef) {
 
 export async function readAuthoringJsonFile(repoRoot, inputRef, {
   invalidCode = 'INVALID_JSON',
+  inlineFlag = null,
 } = {}) {
-  const located = await resolveAuthoringInputPath(repoRoot, inputRef);
+  const located = await resolveAuthoringInputPath(repoRoot, inputRef, { inlineFlag });
   const bytes = await readFile(located.absolute);
   if (bytes.length > located.maxBytes) fail('INPUT_TOO_LARGE', 'input_size_limit_exceeded');
   let text;

package/src/todo-cli.mjs

@@ -325,7 +325,7 @@ function selectNoteTask(member, requestedTaskId) {
 }
 
 async function readNoteTextInput(repoRoot, inputRef) {
-  const located = await resolveAuthoringInputPath(repoRoot, inputRef);
+  const located = await resolveAuthoringInputPath(repoRoot, inputRef, { inlineFlag: '--message' });
   const bytes = await readFile(located.absolute);
   if (bytes.length > MAX_NOTE_INPUT_BYTES) {
     throw new TodoStoreError('INPUT_TOO_LARGE', 'note_input_too_large');
@@ -463,7 +463,7 @@ async function resolveDoneEvidence({ repoRoot, evidenceRef, evidenceMessage, pla
     }
     return descriptor;
   }
-  const located = await resolveAuthoringInputPath(repoRoot, evidenceRef);
+  const located = await resolveAuthoringInputPath(repoRoot, evidenceRef, { inlineFlag: '--message' });
   const bytes = await readFile(located.absolute);
   let text;
   try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); }