@quolu/lattice 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Lattice — phase-aware TODO graph compiler and conflict-aware orchestration runtime",
   "type": "module",
   "license": "MIT",
@@ -60,8 +60,10 @@
     "test": "node scripts/run-product-tests.mjs",
     "test:sensor": "npm --prefix sensor test",
     "check": "node scripts/check-syntax.mjs",
-    "ci": "npm run test && npm run test:sensor && npm run check && npm run check:cli-surface && npm run verify:todo-store",
+    "ci": "npm run test && npm run test:sensor && npm run check && npm run check:cli-surface && npm run check:open-questions && npm run check:reachability && npm run verify:todo-store",
     "verify:todo-store": "node bin/lattice.mjs todo verify --json",
-    "check:cli-surface": "node scripts/verify-cli-surface.mjs"
+    "check:cli-surface": "node scripts/verify-cli-surface.mjs",
+    "check:open-questions": "node scripts/verify-open-questions.mjs",
+    "check:reachability": "node scripts/verify-product-reachability.mjs"
   }
 }

package/src/isolation-runner.mjs

@@ -311,7 +311,15 @@ export async function runIsolatedTransform({ repoRoot, baseRef, allowedPaths, tr
   const mountedEntries = mounts.map(({ entry }) => entry);
 
   const sourceState = await captureSourceState(repoRoot);
-  if (sourceState.visibleStatus.length > 0) throw new Error('source repository must be clean');
+  if (sourceState.visibleStatus.length > 0) {
+    // どのpathが汚しているかを言わないと、呼び出したAIは何を片付ければよいか分からない。
+    // 実運用で、このコマンドへ渡す入力fileそのものが木を汚して詰まった。
+    // visibleStatusはNUL区切りのBufferである。行として扱うと空文字が並ぶ。
+    const entries = statusPaths(sourceState.visibleStatus).slice(0, 20);
+    throw new Error('source repository must be clean :: '
+      + `${entries.join(' | ')} :: 変換は既知のbaseに対して測る。commitするか、`
+      + 'gitが無視するpathへ退避してから再実行する');
+  }
   const baseSha = (await run('git', ['rev-parse', '--verify', `${baseRef}^{commit}`], { cwd: repoRoot })).stdout.toString('utf8').trim();
   const worktreePath = await mkdtemp(path.join(os.tmpdir(), 'lattice-isolated-transform-'));
   let added = false;
@@ -349,7 +357,18 @@ export async function runIsolatedTransform({ repoRoot, baseRef, allowedPaths, tr
         verifications.push(verificationReceipt(verifier, verification, 'passed'));
       } catch (error) {
         verifications.push(verificationReceipt(verifier, error, 'failed'));
-        throw new Error(`verifier failed (${error.signal ?? error.code}): ${verifier.command}`);
+        // どのverifierがなぜ落ちたかを載せる。commandだけ返すと、五条件の棄却理由が
+        // 「focused testが落ちた」で止まり、原因を追う手段が無くなる。
+        // stdout/stderrはBufferで、空でもtruthyになる。`||`で繋ぐとstdoutへ落ちない。
+        // node --testは失敗をstdoutへ書くので、それを取り落とすと理由が消える。
+        const streams = [error?.stderr, error?.stdout]
+          .map((value) => (value === undefined ? '' : String(value)))
+          .filter((value) => value.trim().length > 0);
+        const detail = (streams[0] ?? '')
+          .split('\n').filter((line) => line.trim().length > 0).slice(-6).join(' | ').slice(0, 600);
+        throw new Error(`verifier failed (${error.signal ?? error.code}):`
+          + ` ${[verifier.command, ...verifier.args].join(' ')}`
+          + (detail.length > 0 ? ` :: ${detail}` : ''));
       }
       await assertSnapshotUnchanged(worktreePath, baseSha, allowedPaths, snapshot, 'verifier', mountedEntries);
     }

package/src/seam-apply.mjs

@@ -5,13 +5,14 @@
  * その理由である。採用された変換を本ツリーへ着地させるのは別工程が持つ。
  */
 
-import { execFile } from 'node:child_process';
+import { execFile, spawnSync } from 'node:child_process';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 
 import { runIsolatedTransform } from './isolation-runner.mjs';
 import { collectSensorEvidence } from './sensor-adapter.mjs';
+import { invokeSensorCli } from './sensor-runtime.mjs';
 import { buildSeamDerivationQuerySet, deriveBoundedSeamCandidate } from './seam-derivation.mjs';
 import { planSeamRewrite } from './seam-rewrite.mjs';
 import {
@@ -68,27 +69,54 @@ async function deriveWithClosure({ cwd, deriveOnce }) {
 }
 
 /** 宣言symbolの行範囲。移す範囲を決めるので、原path上のexact一致だけを採る。 */
+const SYMBOL_LOOKUP_LIMIT = 500;
+
+/** gitに載らないbuild成果物のうち、focused testが要るものを実在する時だけ張る。 */
+async function buildOutputMounts(repoRoot) {
+  const { access } = await import('node:fs/promises');
+  const mounts = [];
+  for (const entry of ['sensor/dist']) {
+    try {
+      await access(path.join(repoRoot, entry));
+      mounts.push({ entry, target: path.join(repoRoot, entry) });
+    } catch { /* 無ければ張らない。無い環境ではそのtestも同梱sensorを要求しない。 */ }
+  }
+  return mounts;
+}
+
+/**
+ * 変換対象symbolの行範囲を、対象file限定で読む。
+ *
+ * witness evidenceの共通経路（`collectSensorEvidence`）で名前を引くと、sensor CLIの既定
+ * `--limit 10`で打ち切られる。同名symbolが多いprojectでは対象fileの定義が窓の外へ落ち、
+ * **実在するsymbolを「範囲なし」と誤報して正当な変換を棄却する**。実測では`GIT_SHA1`が
+ * 17 fileにあり、名前順で先頭10件に入らなかった`src/seam-commit.mjs`の定義が返らなかった。
+ *
+ * よってここは共通経路を使わず、明示limitで引く。limitに達した結果は打ち切りの疑いがある
+ * ので、`missing`ではなく`truncated`として区別して返す——観測の欠落を「無い」へ丸めない。
+ */
 export async function readSymbolExtents({ cwd, sourcePath, symbols }) {
-  const querySet = {
-    queries: [
-      { id: 'seam-extent-status', operation: 'status' },
-      ...symbols.map((symbol, index) => ({
-        id: `seam-extent-${String(index).padStart(3, '0')}`, operation: 'query', target: symbol,
-      })),
-    ],
-  };
-  const collected = await collectSensorEvidence({ cwd, querySet });
   const extents = {};
-  querySet.queries.forEach((query, index) => {
-    if (query.operation !== 'query') return;
-    for (const entry of collected.outcomes[index]?.data ?? []) {
+  const truncated = [];
+  for (const symbol of [...new Set(symbols)]) {
+    const result = invokeSensorCli(
+      (command, args, options) => spawnSync(command, args, options),
+      ['query', symbol, '--path', '.', '--limit', String(SYMBOL_LOOKUP_LIMIT), '--json'],
+      { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
+    );
+    if (result.status !== 0) continue;
+    let parsed;
+    try { parsed = JSON.parse(result.stdout); } catch { continue; }
+    const entries = Array.isArray(parsed) ? parsed : parsed?.data ?? parsed?.results ?? [];
+    for (const entry of entries) {
       const node = nodeOf(entry);
-      if (node === null || node.name !== query.target || node.filePath !== sourcePath) continue;
+      if (node === null || node.name !== symbol || node.filePath !== sourcePath) continue;
       if (!Number.isSafeInteger(node.startLine) || !Number.isSafeInteger(node.endLine)) continue;
-      extents[query.target] = { startLine: node.startLine, endLine: node.endLine };
+      extents[symbol] = { startLine: node.startLine, endLine: node.endLine };
     }
-  });
-  return extents;
+    if (extents[symbol] === undefined && entries.length >= SYMBOL_LOOKUP_LIMIT) truncated.push(symbol);
+  }
+  return { extents, truncated: [...new Set(truncated)].sort(compareText) };
 }
 
 async function runIn(worktreePath, command, args) {
@@ -272,11 +300,21 @@ export async function applySeamConflict({
 
   const { readFile } = await import('node:fs/promises');
   const beforeText = await readFile(path.join(repoRoot, sourcePath), 'utf8');
-  const extents = await readSymbolExtents({
+  const lookup = await readSymbolExtents({
     cwd: repoRoot, sourcePath,
     symbols: candidate.surfaces.flatMap(({ symbols }) => symbols),
   });
-  const rewritten = planSeamRewrite({ sourceText: beforeText, candidate, symbolExtents: extents });
+  if (lookup.truncated.length > 0) {
+    // 打ち切りは「範囲が無い」ではない。誤った理由で棄却して原因を隠さない。
+    return {
+      outcome: outcome({ planKey, decision: 'rejected', candidate,
+        reasons: lookup.truncated.map((symbol) => `symbol_lookup_truncated:${symbol}`) }),
+      files: null,
+    };
+  }
+  const rewritten = planSeamRewrite({
+    sourceText: beforeText, candidate, symbolExtents: lookup.extents,
+  });
   if (rewritten.files === null) {
     return { outcome: outcome({ planKey, decision: 'rejected', reasons: rewritten.reasons, candidate }), files: null };
   }
@@ -308,6 +346,11 @@ export async function applySeamConflict({
         // 索引の書き先を使い捨てへ向ける。verifierも再indexもここへ書くので、本repoの
         // 索引を触らせない。src／testへはrunnerがmountを拒否する。
         { entry: '.lattice/sensor', target: scratchLattice },
+        // build成果物はgitignoreされているので、どのcommitのworktreeにも存在しない。
+        // 張らないと、同梱sensorを起動するfocused testがすべてENOENTで落ち、
+        // focused_tests_passedが原理的に満たせなくなる（実測でこれに当たった）。
+        // 存在する時だけ張る——Latticeを依存として使うprojectはnode_modules側に持つ。
+        ...await buildOutputMounts(repoRoot),
       ],
       // 書き先を隠すのでなく、書かせない。verifierが常駐面を起こすとworktreeへ索引が
       // 生まれ、変更を残さない規律に当たる。

package/src/seam-commit-shared.mjs

@@ -0,0 +1,22 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+export const execFileAsync = promisify(execFile);
+
+export const GIT_SHA1 = /^[0-9a-f]{40}$/u;
+
+export const SEAM_REF_PREFIX = 'refs/lattice/seam';
+
+export async function git(args, cwd) {
+  const { stdout } = await execFileAsync('git', args, {
+    cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+  });
+  return stdout;
+}
+
+export function safeRelative(target) {
+  return typeof target === 'string' && target.length > 0 && !target.includes('\0')
+    && !path.posix.isAbsolute(target) && target === path.posix.normalize(target)
+    && !target.split('/').includes('..');
+}

package/src/seam-commit-transform.mjs

@@ -0,0 +1,81 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { GIT_SHA1, execFileAsync, git, safeRelative } from './seam-commit-shared.mjs';
+import { seamRefFor } from './seam-ref.mjs';
+
+/**
+ * 採用された変換をcommitへ確定し、そのshaを返す。
+ *
+ * 本repositoryの作業ツリーは触らない。使い捨てworktreeをbaseへ張り、変換後のfileを書き、
+ * detached HEADでcommitし、refへ繋いでからworktreeを畳む。commit objectはobject DBを共有する
+ * ので、worktreeを消してもshaは生き残る——refはそれをGCから守るためである。
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot 本repository
+ * @param {string} options.baseSha 変換前のbase
+ * @param {object} options.files pathごとの変換後text
+ * @param {string} options.candidateId ref名に使う識別子
+ * @param {string} options.message commit message
+ * @returns {Promise<{commitSha: string, ref: string}>}
+ */
+export async function commitSeamTransform({
+  repoRoot, baseSha, files, candidateId, message,
+} = {}) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) throw new TypeError('repoRootが不正');
+  if (!GIT_SHA1.test(baseSha ?? '')) throw new TypeError('baseShaが不正');
+  if (files === null || typeof files !== 'object' || Array.isArray(files)
+    || Object.keys(files).length === 0) throw new TypeError('filesが不正');
+  const targets = Object.keys(files);
+  if (!targets.every(safeRelative)) throw new TypeError('変換後pathがrepo相対規律を満たさない');
+  if (typeof candidateId !== 'string' || !/^[0-9A-Za-z][\w.-]{0,127}$/u.test(candidateId)) {
+    throw new TypeError('candidateIdが不正');
+  }
+
+  const worktreeRoot = await mkdtemp(path.join(tmpdir(), 'lattice-seam-commit-'));
+  const worktreePath = path.join(worktreeRoot, 'tree');
+  let commitSha;
+  try {
+    await git(['worktree', 'add', '--detach', '--quiet', worktreePath, baseSha], repoRoot);
+    for (const [target, text] of Object.entries(files)) {
+      const absolute = path.join(worktreePath, target);
+      await mkdir(path.dirname(absolute), { recursive: true });
+      await writeFile(absolute, text);
+    }
+    await git(['add', '--', ...targets], worktreePath);
+    // 変換で1 byteも変わらなかったなら、確定すべき成果が無い。空commitで
+    // 「進んだ」ように見せない。
+    const staged = await git(['diff', '--cached', '--name-only'], worktreePath);
+    if (staged.trim() === '') throw new TypeError('変換後の差分が無い');
+    await git([
+      '-c', 'user.email=lattice@localhost', '-c', 'user.name=lattice',
+      'commit', '--quiet', '-m', message ?? `seam transform ${candidateId}`,
+    ], worktreePath);
+    commitSha = (await git(['rev-parse', 'HEAD'], worktreePath)).trim();
+    if (!GIT_SHA1.test(commitSha)) throw new TypeError('commit shaが不正');
+  } finally {
+    await git(['worktree', 'remove', '--force', worktreePath], repoRoot).catch(() => {});
+    await rm(worktreeRoot, { recursive: true, force: true });
+  }
+
+  // worktreeを畳んだ後にrefを張る。object DBは共有なのでshaは生きているが、
+  // refが無いとGCの対象になる。
+  const ref = seamRefFor(candidateId);
+  // 同じcandidateへ2回目の変換が来た時、黙って上書きすると1回目の証跡が消える。
+  // 連鎖は「前の変換を含むbaseの上で次を確定する」形でしか正しくならないので、
+  // 既存refが今回のbaseの祖先を指していなければ拒む（ADR 0142 / ADR 0141 OQ2）。
+  const existing = await git(['for-each-ref', '--format=%(objectname)', ref], repoRoot)
+    .then((stdout) => stdout.trim())
+    .catch(() => '');
+  if (GIT_SHA1.test(existing) && existing !== commitSha) {
+    const chained = await execFileAsync('git', ['merge-base', '--is-ancestor', existing, baseSha], {
+      cwd: repoRoot, encoding: 'utf8',
+    }).then(() => true).catch(() => false);
+    if (!chained) {
+      throw new Error(`seam ref ${ref} は既に ${existing} を指しており、今回のbaseはその子孫でない`
+        + '。前の変換を含むbaseの上で確定するか、別のcandidate idを使う');
+    }
+  }
+  await git(['update-ref', ref, commitSha], repoRoot);
+  return { commitSha, ref };
+}

package/src/seam-commit.mjs

@@ -13,86 +13,6 @@ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
+export { commitSeamTransform } from './seam-commit-transform.mjs';
+export { seamRefFor } from './seam-ref.mjs';
 
-const execFileAsync = promisify(execFile);
-const GIT_SHA1 = /^[0-9a-f]{40}$/u;
-const SEAM_REF_PREFIX = 'refs/lattice/seam';
-
-async function git(args, cwd) {
-  const { stdout } = await execFileAsync('git', args, {
-    cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
-  });
-  return stdout;
-}
-
-/** 変換の成果を指すref。branch名前空間へ置かないので、通常のbranch一覧には現れない。 */
-export function seamRefFor(candidateId) {
-  return `${SEAM_REF_PREFIX}/${candidateId}`;
-}
-
-function safeRelative(target) {
-  return typeof target === 'string' && target.length > 0 && !target.includes('\0')
-    && !path.posix.isAbsolute(target) && target === path.posix.normalize(target)
-    && !target.split('/').includes('..');
-}
-
-/**
- * 採用された変換をcommitへ確定し、そのshaを返す。
- *
- * 本repositoryの作業ツリーは触らない。使い捨てworktreeをbaseへ張り、変換後のfileを書き、
- * detached HEADでcommitし、refへ繋いでからworktreeを畳む。commit objectはobject DBを共有する
- * ので、worktreeを消してもshaは生き残る——refはそれをGCから守るためである。
- *
- * @param {object} options
- * @param {string} options.repoRoot 本repository
- * @param {string} options.baseSha 変換前のbase
- * @param {object} options.files pathごとの変換後text
- * @param {string} options.candidateId ref名に使う識別子
- * @param {string} options.message commit message
- * @returns {Promise<{commitSha: string, ref: string}>}
- */
-export async function commitSeamTransform({
-  repoRoot, baseSha, files, candidateId, message,
-} = {}) {
-  if (typeof repoRoot !== 'string' || repoRoot.length === 0) throw new TypeError('repoRootが不正');
-  if (!GIT_SHA1.test(baseSha ?? '')) throw new TypeError('baseShaが不正');
-  if (files === null || typeof files !== 'object' || Array.isArray(files)
-    || Object.keys(files).length === 0) throw new TypeError('filesが不正');
-  const targets = Object.keys(files);
-  if (!targets.every(safeRelative)) throw new TypeError('変換後pathがrepo相対規律を満たさない');
-  if (typeof candidateId !== 'string' || !/^[0-9A-Za-z][\w.-]{0,127}$/u.test(candidateId)) {
-    throw new TypeError('candidateIdが不正');
-  }
-
-  const worktreeRoot = await mkdtemp(path.join(tmpdir(), 'lattice-seam-commit-'));
-  const worktreePath = path.join(worktreeRoot, 'tree');
-  let commitSha;
-  try {
-    await git(['worktree', 'add', '--detach', '--quiet', worktreePath, baseSha], repoRoot);
-    for (const [target, text] of Object.entries(files)) {
-      const absolute = path.join(worktreePath, target);
-      await mkdir(path.dirname(absolute), { recursive: true });
-      await writeFile(absolute, text);
-    }
-    await git(['add', '--', ...targets], worktreePath);
-    // 変換で1 byteも変わらなかったなら、確定すべき成果が無い。空commitで
-    // 「進んだ」ように見せない。
-    const staged = await git(['diff', '--cached', '--name-only'], worktreePath);
-    if (staged.trim() === '') throw new TypeError('変換後の差分が無い');
-    await git([
-      '-c', 'user.email=lattice@localhost', '-c', 'user.name=lattice',
-      'commit', '--quiet', '-m', message ?? `seam transform ${candidateId}`,
-    ], worktreePath);
-    commitSha = (await git(['rev-parse', 'HEAD'], worktreePath)).trim();
-    if (!GIT_SHA1.test(commitSha)) throw new TypeError('commit shaが不正');
-  } finally {
-    await git(['worktree', 'remove', '--force', worktreePath], repoRoot).catch(() => {});
-    await rm(worktreeRoot, { recursive: true, force: true });
-  }
-
-  // worktreeを畳んだ後にrefを張る。object DBは共有なのでshaは生きているが、
-  // refが無いとGCの対象になる。
-  const ref = seamRefFor(candidateId);
-  await git(['update-ref', ref, commitSha], repoRoot);
-  return { commitSha, ref };
-}

package/src/seam-ref.mjs

@@ -0,0 +1,33 @@
+import { SEAM_REF_PREFIX, git } from './seam-commit-shared.mjs';
+
+/** 変換の成果を指すref。branch名前空間へ置かないので、通常のbranch一覧には現れない。 */
+export function seamRefFor(candidateId) {
+  return `${SEAM_REF_PREFIX}/${candidateId}`;
+}
+
+/**
+ * 確定済みseam refを列挙する（ADR 0142 / ADR 0141 OQ1）。
+ *
+ * **自動では消さない。** このrefが指すのは「五条件を通って受理された変換の実体」であり、
+ * どの版がどの競合をどう解いたかを後から辿れる唯一の資源である。runが閉じたら消す設計も
+ * 検討したが、それは証跡を寿命付きにするということで、記録を所有するという製品の役目と
+ * 衝突する。消すかどうかは所有者の裁定に委ね、道具は「何が在るか」を見せる側だけを持つ。
+ *
+ * @returns {Promise<Array<{ref: string, candidate_id: string, commit_sha: string}>>}
+ */
+export async function listSeamRefs({ repoRoot } = {}) {
+  let stdout;
+  try {
+    stdout = await git(['for-each-ref', '--format=%(refname) %(objectname)', SEAM_REF_PREFIX], repoRoot);
+  } catch {
+    return [];
+  }
+  return stdout.split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => {
+      const [ref, commitSha] = line.split(' ');
+      return { ref, candidate_id: ref.slice(`${SEAM_REF_PREFIX}/`.length), commit_sha: commitSha };
+    })
+    .sort((left, right) => (left.ref < right.ref ? -1 : left.ref > right.ref ? 1 : 0));
+}

package/src/seam-rewrite.mjs

@@ -85,6 +85,13 @@ function exportedBlock(raw) {
   return parts.join('\n');
 }
 
+/** 原pathでexport宣言だったか。移動先でexportを足したかではなく、元の姿を見る。 */
+function wasExported(raw) {
+  const declaration = raw.split('\n')
+    .find((line) => !COMMENT_LINE.test(line) && line.trim() !== '');
+  return declaration !== undefined && /^\s*export\s/u.test(declaration);
+}
+
 function relativeSpecifier(fromPath, toPath) {
   const fromDir = fromPath.slice(0, fromPath.lastIndexOf('/') + 1);
   return toPath.startsWith(fromDir) ? `./${toPath.slice(fromDir.length)}` : `./${toPath}`;
@@ -138,10 +145,17 @@ export function planSeamRewrite({ sourceText, candidate, symbolExtents } = {}) {
 
   const bodyByPath = new Map();
   const removal = new Set();
+  // 原pathでexportされていたsymbolは、移した先から残余面が再exportする。
+  // しないと原pathをimportしている全fileが壊れ、外部挙動同等性が原理的に満たせない。
+  const reExportByPath = new Map();
   for (const block of blocks) {
     const raw = lines.slice(block.start - 1, block.end).join('\n');
     if (!bodyByPath.has(block.path)) bodyByPath.set(block.path, []);
     bodyByPath.get(block.path).push(exportedBlock(raw));
+    if (wasExported(raw)) {
+      if (!reExportByPath.has(block.path)) reExportByPath.set(block.path, []);
+      reExportByPath.get(block.path).push(block.symbol);
+    }
     for (let line = block.start; line <= block.end; line += 1) removal.add(line);
   }
 
@@ -175,7 +189,11 @@ export function planSeamRewrite({ sourceText, candidate, symbolExtents } = {}) {
   const residualBody = keptBody.join('\n').replace(/\n{3,}/gu, '\n\n').replace(/\n+$/u, '');
   const residualCross = importsFor(residual.path, residualBody)
     .filter((statement) => !keptHeader.join('\n').includes(statement));
-  files[residual.path] = `${[...keptHeader, ...residualCross].join('\n')}\n${residualBody}\n`
+  const reExports = [...reExportByPath.entries()]
+    .sort(([left], [right]) => compareText(left, right))
+    .map(([targetPath, names]) => `export { ${[...names].sort(compareText).join(', ')} }`
+      + ` from '${relativeSpecifier(residual.path, targetPath)}';`);
+  files[residual.path] = `${[...keptHeader, ...residualCross, ...reExports].join('\n')}\n${residualBody}\n`
     .replace(/^\n+/u, '');
 
   return { files, reasons: [] };

package/src/todo-cli.mjs

@@ -276,7 +276,7 @@ async function readEvidenceInput(repoRoot, inputRef) {
   });
 }
 
-async function readJsonInput(repoRoot, inputRef, { validate, invalidCode }) {
+async function readJsonInput(repoRoot, inputRef, { validate, invalidCode, expected = null }) {
   if (!isTodoRef(inputRef)) {
     throw new TodoStoreError('INPUT_UNREADABLE', 'input_path_outside_repo', undefined, { input_ref: inputRef });
   }
@@ -321,7 +321,10 @@ async function readJsonInput(repoRoot, inputRef, { validate, invalidCode }) {
     throw new TodoStoreError('INVALID_JSON', 'json_parse_failed');
   }
   if (!validate(descriptor)) {
-    throw new TodoStoreError(invalidCode, 'schema_invalid');
+    // 「schema_invalid」だけを返すと、呼び出したAIは何をどう直せばよいか分からない。
+    // 期待する形を渡されている入口は、それをそのまま返す（ADR 0130の案内規律）。
+    throw new TodoStoreError(invalidCode, 'schema_invalid', undefined,
+      expected === null ? undefined : { expected });
   }
   return descriptor;
 }
@@ -961,15 +964,21 @@ async function witnessScaffold({ repoRoot, planKey, inputRef }) {
   }
   const { queries, paths } = buildWitnessObservationQuerySet(draft);
   const collected = await collectSensorEvidence({ cwd: repoRoot, querySet: { queries } });
-  const affectedTestsByPath = {};
+  const observationByPath = {};
   queries.forEach((query, index) => {
     if (query.operation !== 'affected') return;
     const entry = collected.outcomes[index]?.targets?.[0];
     // 観測できていないものを空配列へ丸めない。丸めるとdriftでcompileが落ちる。
-    if (entry?.path_state === 'absent' || !Array.isArray(entry?.data?.affectedTests)) return;
-    affectedTestsByPath[query.target] = [...entry.data.affectedTests];
+    // 不存在（absent）は観測**できている**——fsのlstat結果である。未観測と混ぜると、
+    // 創作境界を宣言したToDoが「まだ確かめていない」側へ落ちる（ADR 0136）。
+    if (!Array.isArray(entry?.data?.affectedTests) || !Array.isArray(entry?.data?.changedFiles)) return;
+    observationByPath[query.target] = {
+      state: entry.path_state === 'absent' ? 'absent' : 'present',
+      affectedTests: [...entry.data.affectedTests],
+      changedFiles: [...entry.data.changedFiles],
+    };
   });
-  const { witnessSet, reasons } = buildWitnessSet({ draft, affectedTestsByPath });
+  const { witnessSet, reasons } = buildWitnessSet({ draft, observationByPath });
   if (witnessSet === null) {
     throw new TodoStoreError('WITNESS_SCAFFOLD_INCOMPLETE', 'witness_scaffold_incomplete', undefined, {
       reasons, next_action: 'resolve_declaration_then_retry',
@@ -1006,6 +1015,11 @@ async function readSeamPathNames(repoRoot, inputRef) {
       && Object.entries(candidate.names)
         .every(([key, target]) => isTodoIdentifier(key) && isTodoRef(target)),
     invalidCode: 'SEAM_PATH_NAMES_INVALID',
+    expected: {
+      schema: 'lattice.seam_path_names.v1',
+      shape: '{ "schema": "lattice.seam_path_names.v1", "names": { "<task_id>": "<repo相対path>" } }',
+      note: '所有面はtask_idごとに、共有面は"shared"というkeyで名前を与える',
+    },
   });
   return value.names;
 }

package/src/witness-scaffold.mjs

@@ -18,6 +18,34 @@ const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 const sortedUnique = (values) => [...new Set(values)].sort(compareText);
 
 export const WITNESS_DRAFT_SCHEMA = 'lattice.todo_witness_draft.v1';
+/** 創作宣言を書ける版。v1はstringのownsだけを受け、`creates`を表現できない。 */
+export const WITNESS_DRAFT_SCHEMA_V2 = 'lattice.todo_witness_draft.v2';
+const DRAFT_SCHEMAS = Object.freeze([WITNESS_DRAFT_SCHEMA, WITNESS_DRAFT_SCHEMA_V2]);
+
+/**
+ * ownsの1件を正規化する。
+ *
+ * v2では`{ path, creates: true }`を書ける。まだ存在しないpathを所有するToDo——新module・
+ * 新doc・新testの追加——は、これが無いと道具で宣言を作れない（ADR 0136）。
+ */
+function ownEntry(value, { allowCreates }) {
+  if (typeof value === 'string') return isTodoRef(value) ? { target: value, creates: false } : null;
+  if (!allowCreates || value === null || typeof value !== 'object' || Array.isArray(value)) return null;
+  const keys = Object.keys(value).sort();
+  if (keys.length !== 2 || keys[0] !== 'creates' || keys[1] !== 'path') return null;
+  if (!isTodoRef(value.path) || value.creates !== true) return null;
+  // prefix形（末尾/）はaffectedがunresolvedを返すので、file単位に限る（ADR 0136）。
+  if (value.path.endsWith('/')) return null;
+  return { target: value.path, creates: true };
+}
+
+/** 下書きの1 taskが宣言する所有を正規化する。1件でも形が壊れていればnull。 */
+export function draftOwnEntries(task, schema) {
+  const allowCreates = schema === WITNESS_DRAFT_SCHEMA_V2;
+  if (!Array.isArray(task?.owns)) return null;
+  const entries = task.owns.map((own) => ownEntry(own, { allowCreates }));
+  return entries.some((entry) => entry === null) ? null : entries;
+}
 
 function reject(reasons) {
   return { witnessSet: null, queries: [], reasons: sortedUnique(reasons) };
@@ -26,7 +54,7 @@ function reject(reasons) {
 /** 下書きの形。AIが書く欄だけを持ち、観測で埋まる欄は持たない。 */
 export function validateWitnessDraft(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
-  if (value.schema !== WITNESS_DRAFT_SCHEMA) return false;
+  if (!DRAFT_SCHEMAS.includes(value.schema)) return false;
   if (!isTodoIdentifier(value.project_id) || !isTodoIdentifier(value.plan_key)) return false;
   if (value.capacity === null || typeof value.capacity !== 'object'
     || !Number.isSafeInteger(value.capacity.executors) || value.capacity.executors < 1) return false;
@@ -35,7 +63,7 @@ export function validateWitnessDraft(value) {
   if (entries.length === 0) return false;
   return entries.every(([taskId, task]) => isTodoIdentifier(taskId)
     && task !== null && typeof task === 'object' && !Array.isArray(task)
-    && Array.isArray(task.owns) && task.owns.every(isTodoRef)
+    && draftOwnEntries(task, value.schema) !== null
     && (task.reads === undefined || (Array.isArray(task.reads) && task.reads.every(isTodoRef)))
     && (task.unknowns === undefined || (Array.isArray(task.unknowns)
       && task.unknowns.every((entry) => entry !== null && typeof entry === 'object'
@@ -52,7 +80,8 @@ function queryIdFor(index) {
 
 /** 下書きから、観測に要るquery setを組む。所有pathごとに1つのaffected queryを引く。 */
 export function buildWitnessObservationQuerySet(draft) {
-  const paths = sortedUnique(Object.values(draft.tasks).flatMap(({ owns }) => owns));
+  const paths = sortedUnique(Object.values(draft.tasks)
+    .flatMap((task) => (draftOwnEntries(task, draft.schema) ?? []).map(({ target }) => target)));
   return {
     queries: [
       { id: 'witness-status', operation: 'status' },
@@ -69,9 +98,11 @@ export function buildWitnessObservationQuerySet(draft) {
  *
  * @param {object} options
  * @param {object} options.draft `lattice.todo_witness_draft.v1`
- * @param {object} options.affectedTestsByPath 所有pathごとのfresh観測
+ * @param {object} options.observationByPath 所有pathごとのfresh観測
+ *   `{ state: 'absent'|'present', affectedTests: string[], changedFiles: string[] }`。
+ *   観測できていないpathは**欄そのものを置かない**——空で置くと不在と区別できない。
  */
-export function buildWitnessSet({ draft, affectedTestsByPath } = {}) {
+export function buildWitnessSet({ draft, observationByPath } = {}) {
   if (!validateWitnessDraft(draft)) return reject(['draft_invalid']);
   const { paths } = buildWitnessObservationQuerySet(draft);
   const queryIdByPath = new Map(paths.map((target, index) => [target, queryIdFor(index)]));
@@ -79,21 +110,39 @@ export function buildWitnessSet({ draft, affectedTestsByPath } = {}) {
   const reasons = [];
   const manualWitness = {};
   for (const [taskId, task] of Object.entries(draft.tasks).sort(([left], [right]) => compareText(left, right))) {
-    const owns = sortedUnique(task.owns);
+    const entries = draftOwnEntries(task, draft.schema) ?? [];
+    const owns = [...new Map(entries.map((entry) => [entry.target, entry])).values()]
+      .sort((left, right) => compareText(left.target, right.target));
     if (owns.length === 0) { reasons.push(`owns_empty:${taskId}`); continue; }
     // affected_testsは宣言とfresh観測をbinding単位でexact比較する。複数pathを所有すると
     // 観測集合が一致しない限り必ず落ちるので、今の契約では表現できない（2026-07-27の実測）。
     if (owns.length > 1) { reasons.push(`multiple_owned_paths_unsupported:${taskId}`); continue; }
-    const [target] = owns;
-    const affected = affectedTestsByPath?.[target];
+    const [own] = owns;
+    const target = own.target;
+    const observed = observationByPath?.[target];
     // 観測できていないことを空配列へ丸めない。丸めるとdriftでcompileが落ちる。
-    if (!Array.isArray(affected)) { reasons.push(`affected_tests_unobserved:${target}`); continue; }
+    if (observed === undefined) { reasons.push(`affected_tests_unobserved:${target}`); continue; }
+    if (own.creates) {
+      // 宣言が実態と合っているかを確かめるのが道具の役目である。front endが要求する形
+      // （fresh absent・blast radiusが空・changedFilesが対象1件）をここで満たしておかないと、
+      // 通る宣言を作ったつもりでcompileで落ちる（ADR 0136）。
+      if (observed.state !== 'absent') { reasons.push(`creates_path_present:${target}`); continue; }
+      if (observed.affectedTests.length !== 0
+        || observed.changedFiles.length !== 1
+        || observed.changedFiles[0] !== target) {
+        reasons.push(`creates_unverified:${target}`); continue;
+      }
+    } else if (observed.state === 'absent') {
+      // 不存在のpathを黙って通さない。作るつもりならそう宣言する、が次の一手である。
+      reasons.push(`path_absent_declare_creates:${target}`); continue;
+    }
+    const affected = own.creates ? [] : observed.affectedTests;
     for (const anchor of task.concern_anchors ?? []) {
       // `within`は自分が所有している資源に限る。所有していない資源の内側に担当を主張させない。
-      if (!owns.includes(anchor.within)) reasons.push(`anchor_outside_owned:${taskId}:${anchor.within}`);
+      if (anchor.within !== target) reasons.push(`anchor_outside_owned:${taskId}:${anchor.within}`);
     }
     manualWitness[taskId] = {
-      owns: [{ kind: 'path', target }],
+      owns: [own.creates ? { kind: 'path', target, creates: true } : { kind: 'path', target }],
       reads: sortedUnique(task.reads ?? []),
       writes: [target],
       resources: [],