@quolu/lattice 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Lattice — phase-aware TODO graph compiler and conflict-aware orchestration runtime",
   "type": "module",
   "license": "MIT",
@@ -62,6 +62,7 @@
     "precheck": "node --check src/bridge-launch-agent.mjs",
     "check": "node --check bin/lattice.mjs && node --check bin/lattice-mcp.mjs && node --check bin/lattice-dashboard.mjs && node --check bin/lattice-bridge.mjs && node --check bin/lattice-scripted-adapter.mjs && node --check src/cli-stdio.mjs && node --check src/bridge-address.mjs && node --check src/bridge-registrar.mjs && node --check src/todo-independence-guidance.mjs && node --check src/todo-independence.mjs && node --check src/todo-independence-contracts.mjs && node --check src/seam-proposal-contracts.mjs && node --check src/seam-proposal-queries.mjs && node --check src/seam-proposal.mjs && node --check src/todo-gantt-layout.mjs && node --check src/todo-gantt-scope.mjs && node --check src/bridge-config.mjs && node --check src/bridge-server.mjs && node --check src/bridge-daemon.mjs && node --check src/bridge-cli.mjs && node --check src/project-cli.mjs && node --check src/sensor-cli.mjs && node --check src/sensor-runtime.mjs && node --check src/sensor-adapter.mjs && node --check src/factory-diagnostics.mjs && node --check src/runtime-errors.mjs && node --check src/runtime-contracts.mjs && node --check src/runtime-event-store.mjs && node --check src/runtime-adapter-registry.mjs && node --check src/runtime-scripted-adapter-controller.mjs && node --check src/hash-chain.mjs && node --check src/dag-chain.mjs && node --check src/todo-contracts.mjs && node --check src/todo-chain.mjs && node --check src/todo-store.mjs && node --check src/todo-migration.mjs && node --check src/todo-revision.mjs && node --check src/todo-status.mjs && node --check src/todo-cli.mjs && node --check src/todo-dashboard-registry.mjs && node --check src/todo-gantt-presentation.mjs && node --check src/todo-gantt-live.mjs && node --check src/bounded-seam.mjs && node --check src/todo-narrative-anchor.mjs && node --check src/todo-markdown-renderer.mjs && node --check src/todo-gantt-svg.mjs && node --check src/todo-gantt-html.mjs && node --check src/runtime-projection.mjs && node --check src/runtime-decision-verifier.mjs && node --check src/runtime-front-end.mjs && node --check src/runtime-cli.mjs && node --check src/rc3-dogfood-scaffold.mjs && node --check src/runtime-engine.mjs && node --check src/runtime-scripted-executor.mjs && node --check src/runtime-diff-observer.mjs && node --check src/runtime-worktree-executor.mjs && node --check src/runtime-hold-recompile.mjs && node --check src/rc3-scripted-campaign.mjs && node --check src/rc3-actual-dogfood.mjs && node --check src/rc4-stage1-dogfood.mjs && node --check research/fixtures/dispatch-record/src/dispatch-record.mjs && node --check test/research-dispatch-record.test.mjs",
     "check:project-identity": "node --check src/project-identity.mjs",
-    "ci": "npm run test && npm run test:sensor && npm run check && npm run check:project-identity"
+    "ci": "npm run test && npm run test:sensor && npm run check && npm run check:project-identity && npm run verify:todo-store",
+    "verify:todo-store": "node bin/lattice.mjs todo verify --json"
   }
 }

package/src/bridge-daemon.mjs

@@ -17,6 +17,9 @@ const STOP_REQUEST_SCHEMA = 'lattice.bridge_stop_request.v1';
 const STOP_RECEIPT_SCHEMA = 'lattice.bridge_stop_receipt.v1';
 const ACTIVE_MARKER_SCHEMA = 'lattice.bridge_daemon_active.v1';
 const CONTROL_MAX_BYTES = 65_536;
+/** control fileの差し替え競合だけを吸収する再読の上限と間隔（`readStrictJson`が唯一の使用者）。 */
+const CONTROL_READ_RETRY_LIMIT = 5;
+const CONTROL_READ_RETRY_DELAY_MS = 20;
 
 export function bridgeDaemonDescriptorPath(env = process.env) {
   return path.join(bridgeConfigPaths(env).root, 'bridge-daemon.json');
@@ -66,7 +69,16 @@ function isIsoTimestamp(value) {
   try { return new Date(value).toISOString() === value; } catch { return false; }
 }
 
-async function readStrictJson(ref, code, label) {
+/** 読み取り中の差し替え・消失につけるmarker。内容の異常と同じ顔をさせない。 */
+const CONTROL_READ_RACE = Symbol('bridge_control_read_race');
+
+function controlReadRace(message) {
+  const error = new Error(message);
+  error[CONTROL_READ_RACE] = true;
+  return error;
+}
+
+async function readStrictJsonOnce(ref, label) {
   let before;
   let handle;
   try {
@@ -77,12 +89,12 @@ async function readStrictJson(ref, code, label) {
     const opened = await handle.stat();
     if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino
       || opened.size !== before.size || opened.size > CONTROL_MAX_BYTES) {
-      throw new Error(`${label} changed during validation`);
+      throw controlReadRace(`${label} changed during validation`);
     }
     const text = await handle.readFile('utf8');
     const after = await lstat(ref);
     if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size) {
-      throw new Error(`${label} changed during read`);
+      throw controlReadRace(`${label} changed during read`);
     }
     const errors = [];
     const tree = parseTree(text, errors, { allowTrailingComma: false, disallowComments: true });
@@ -91,11 +103,37 @@ async function readStrictJson(ref, code, label) {
     }
     return JSON.parse(text);
   } catch (error) {
-    if (error?.code === 'ENOENT' && before === undefined) return null;
-    throw new BridgeConfigError(code, `${label} invalid`, undefined, error);
+    // 最初のlstatで無い＝未起動。読み始めた後に消えたのは停止との競合で、再読でnullへ落ち着く。
+    if (error?.code === 'ENOENT') {
+      if (before === undefined) return null;
+      throw controlReadRace(`${label} removed during read`);
+    }
+    throw error;
   } finally { await handle?.close(); }
 }
 
+/**
+ * 公開はatomic renameなので、読み手はinodeの差し替えに必ず出会う。差し替えを跨いだ読みは
+ * 内容の異常ではなく再読で解ける競合であり、壊れたcontrol fileと同じerrorにしてはならない。
+ *
+ * 再試行するのは`CONTROL_READ_RACE`が付いた3条件だけである——検証中のinode／size変化、
+ * 読み取り中のinode／size変化、最初のlstat後の消失。最大`CONTROL_READ_RETRY_LIMIT`回、
+ * 間隔`CONTROL_READ_RETRY_DELAY_MS`で再読し、超えたら他と同じtyped errorで落とす。
+ * JSON不正・schema不正・mode不正は競合ではないので一度も再試行せず即fail closedにする。
+ */
+async function readStrictJson(ref, code, label) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await readStrictJsonOnce(ref, label);
+    } catch (error) {
+      if (error?.[CONTROL_READ_RACE] !== true || attempt >= CONTROL_READ_RETRY_LIMIT) {
+        throw new BridgeConfigError(code, `${label} invalid`, undefined, error);
+      }
+      await new Promise((resolve) => setTimeout(resolve, CONTROL_READ_RETRY_DELAY_MS));
+    }
+  }
+}
+
 async function readStrictControl(ref, schema, keys) {
   const value = await readStrictJson(ref, 'BRIDGE_STOP_CONTROL_INVALID', 'bridge stop control');
   if (value === null) return null;

package/src/seam-proposal-contracts.mjs

@@ -15,9 +15,12 @@ import {
   isGitSha,
   severabilityOfConflictKind,
 } from './todo-independence-contracts.mjs';
-import { SEAM_PROPOSAL_GUIDANCE_CODES } from './todo-independence-guidance.mjs';
+import {
+  SEAM_PROPOSAL_GUIDANCE_CODES,
+  seamProposalGuidanceCode,
+} from './todo-independence-guidance.mjs';
 
-export const SEAM_PROPOSAL_SCHEMA = 'lattice.seam_proposal.v1';
+export const SEAM_PROPOSAL_SCHEMA = 'lattice.seam_proposal.v2';
 export const SEAM_PROPOSAL_PROJECTION_SCHEMA = 'lattice.seam_proposal_projection.v1';
 export const SEAM_PROPOSAL_VERDICTS = Object.freeze([
   'seam_candidate',
@@ -139,10 +142,18 @@ function surfaceEntry(value, taskIds, { proposed }) {
     : value.owner_task_ids.length === 1;
 }
 
+/**
+ * `candidate_paths`は、同名symbolが複数fileに居た時だけ埋まる（ADR 0134）。
+ *
+ * 単数の`resolved_path`と併存させるのは、両者が別の事実だからである。前者は「一意に決まった」、
+ * 後者は「決まらず、候補はこれだけあった」。候補を持つ受け皿が無かった頃、後者は`unknown`へ
+ * 潰れ、宣言の`within`で絞れる情報が記録に残らなかった。一意に決まった時に候補を並べない
+ * （空配列に限る）のは、決まった事実と決まらなかった事実を同じ形にしないためである。
+ */
 function queryEntry(value) {
   return exactRecord(value, [
     'query_id', 'operation', 'target', 'outcome', 'resolved_name', 'resolved_path',
-    'result_digest',
+    'candidate_paths', 'result_digest',
   ])
     && isTodoIdentifier(value.query_id)
     && isTodoIdentifier(value.operation)
@@ -150,6 +161,12 @@ function queryEntry(value) {
     && isTodoIdentifier(value.outcome)
     && (value.resolved_name === null || boundedText(value.resolved_name))
     && (value.resolved_path === null || repoRelativePath(value.resolved_path))
+    && boundedList(value.candidate_paths, repoRelativePath)
+    && strictlySorted(value.candidate_paths)
+    && (value.outcome === 'ambiguous'
+      ? value.candidate_paths.length >= 2 && value.resolved_path === null
+        && boundedText(value.resolved_name)
+      : value.candidate_paths.length === 0)
     && isTodoDigest(value.result_digest);
 }
 
@@ -281,7 +298,7 @@ function decisionEntry(value) {
 }
 
 /**
- * Validate the immutable public `lattice.seam_proposal.v1` artifact.
+ * Validate the immutable public `lattice.seam_proposal.v2` artifact.
  *
  * This validates the artifact's closed runtime shape and canonical relations. Binding the
  * recorded conflicts back to the referenced independence bytes is a consumer responsibility.
@@ -309,19 +326,21 @@ export function validateSeamProposal(value) {
   }
 }
 
-const PROJECTION_GUIDANCE_BY_COVERAGE = Object.freeze({
-  missing: 'seam_proposal_unrecorded',
-  stale: 'seam_proposal_stale',
-  superseded: 'seam_proposal_superseded',
-  verified: 'seam_proposal_verified',
-});
-
-function projectionGuidance(value, coverage) {
-  return exactRecord(value, ['code', 'message', 'next_action'])
-    && SEAM_PROPOSAL_GUIDANCE_CODES.includes(value.code)
-    && value.code === PROJECTION_GUIDANCE_BY_COVERAGE[coverage]
-    && boundedText(value.message)
-    && isTodoIdentifier(value.next_action);
+/**
+ * 案内は、鮮度と載っているunknownから一意に決まる。生成側の文言をそのまま載せる規約なので
+ * shapeだけを見ると、投影が状況と噛み合わない案内を載せても通ってしまう。codeは規則正本へ
+ * 引き直して照合する（ADR 0130 Decision 1・2）。
+ */
+function projectionGuidance(value, coverage, components) {
+  if (!exactRecord(value, ['code', 'message', 'next_action'])
+    || !SEAM_PROPOSAL_GUIDANCE_CODES.includes(value.code)
+    || !boundedText(value.message)
+    || !isTodoIdentifier(value.next_action)) return false;
+  const unknownKinds = Array.isArray(components)
+    ? components.flatMap((component) => (Array.isArray(component?.unknowns)
+      ? component.unknowns.map((unknown) => unknown?.kind) : []))
+    : [];
+  return value.code === seamProposalGuidanceCode({ coverage, unknownKinds });
 }
 
 function projectionComponent(value) {
@@ -383,7 +402,7 @@ export function validateSeamProposalProjection(value) {
       || !isTodoIdentifier(value.plan_key)
       || !TODO_INDEPENDENCE_COVERAGE.includes(value.coverage)
       || !isGitSha(value.current_base_sha)
-      || !projectionGuidance(value.guidance, value.coverage)
+      || !projectionGuidance(value.guidance, value.coverage, value.components)
       || !isTodoDigest(value.result_digest)) return false;
 
     if (value.coverage === 'missing') {

package/src/seam-proposal-queries.mjs

@@ -249,12 +249,24 @@ function exactSymbolResolution(outcome, target, operation) {
     return { outcome: 'unknown' };
   }
   const paths = [...new Set(exact.map(({ node }) => node.filePath))].sort(compareText);
-  if (paths.length !== 1) return { outcome: 'unknown' };
-  return { outcome: 'resolved', resolved_name: target, resolved_path: paths[0] };
+  if (paths.length === 1) {
+    return { outcome: 'resolved', resolved_name: target, resolved_path: paths[0] };
+  }
+  // 同名が複数fileにある。`query`は「その名前はどこに居るか」を問う操作なので、候補を
+  // 持ったまま返す——宣言の`within`が指す資源で絞れば一意に決まる場合がある（ADR 0134）。
+  // graph操作（callers／callees／impact）は逆に、展開の起点が一意でなければ意味を持たない。
+  // 同じ曖昧さでも問いが違うので、そちらはunknownのまま潰す。
+  if (operation === 'query') {
+    return { outcome: 'ambiguous', resolved_name: target, candidate_paths: paths };
+  }
+  return { outcome: 'unknown' };
 }
 
 function symbolResolutionForEvidence(local, canonical) {
-  if (canonical.outcome === 'unknown') return { outcome: 'unknown' };
+  // 起点が一意でない名前についてのgraph観測は、どのsymbolについての観測か確定しない。
+  if (canonical.outcome === 'unknown' || canonical.outcome === 'ambiguous') {
+    return { outcome: 'unknown' };
+  }
   if (canonical.outcome === 'absent') {
     return local.outcome === 'absent' ? local : { outcome: 'unknown' };
   }
@@ -294,6 +306,7 @@ function evidenceQuery({ query, outcome, resolution }) {
     outcome: resolution.outcome,
     resolved_name: resolution.resolved_name ?? null,
     resolved_path: resolution.resolved_path ?? null,
+    candidate_paths: resolution.candidate_paths ?? [],
     result_digest: digestArtifact(portableSensorOutcome(outcome)),
   };
 }
@@ -472,7 +485,7 @@ async function collectCalleeClosure({
 /**
  * Collect through the bundled sensor adapter. The normalized evidence remains the only
  * contract-shaped artifact; raw outcomes are returned on a separate, in-memory channel for
- * structural cut enumeration and must not be embedded in lattice.seam_proposal.v1.
+ * structural cut enumeration and must not be embedded in lattice.seam_proposal.v2.
  */
 export async function collectSeamProposalEvidenceBundle({
   cwd,

package/src/seam-proposal.mjs

@@ -774,13 +774,42 @@ function pathContains(resourcePath, symbolPath) {
     : symbolPath === resourcePath;
 }
 
+/**
+ * 宣言symbolのpathを、宣言した資源の内側で解く（ADR 0134）。
+ *
+ * 一意に解決した名前はそのまま返す。同名が複数fileに居た場合だけ、receiptが持つ候補を
+ * 資源で絞る——絞って1つに決まる時だけ束縛根拠になる。0個なら宣言した資源の中には無く、
+ * 2つ以上なら資源の中でも決まらない。どちらも「解けなかった」であって、片方を勝たせない。
+ *
+ * 絞るのは宣言された資源であって、宣言そのものではない。sensorが返した候補集合の外から
+ * pathを持ち込むことはないので、宣言が誤っていても存在しないsymbolへは束縛されない。
+ */
+function resolveConcernSymbolPath(queries, name, resourcePath) {
+  const receipt = queries.find((query) => (
+    query.operation === 'query' && query.target === name && query.resolved_name === name
+      && (query.outcome === 'resolved' || query.outcome === 'ambiguous')
+  ));
+  if (receipt === undefined) return null;
+  if (receipt.outcome === 'resolved') {
+    return typeof receipt.resolved_path === 'string' && receipt.resolved_path.length > 0
+      ? receipt.resolved_path : null;
+  }
+  const inside = (receipt.candidate_paths ?? [])
+    .filter((candidate) => pathContains(resourcePath, candidate));
+  return inside.length === 1 ? inside[0] : null;
+}
+
 /**
  * Resolve declared concern anchors against fresh sensor evidence.
  *
- * A declaration only becomes a binding anchor when the sensor resolves the exact name to exactly
- * one path and that path lies inside the declared resource. Fuzzy resolution to a neighbouring
- * symbol, an absent name, or a symbol living outside the contested resource yields a typed
- * unknown instead — a wrong declaration must never widen what the binder believes it knows.
+ * A declaration only becomes a binding anchor when the sensor resolves the exact name inside the
+ * declared resource to exactly one path. Fuzzy resolution to a neighbouring symbol, an absent
+ * name, or a symbol living outside the contested resource yields a typed unknown instead — a
+ * wrong declaration must never widen what the binder believes it knows.
+ *
+ * A name living in several files is resolved against the declared resource rather than being
+ * dropped (ADR 0134). The resource is one the ToDo already claims under `owns`, so this narrows
+ * the sensor's own candidate set; it never introduces a path the sensor did not report.
  *
  * Two ToDos claiming the same symbol is a contradiction in the declarations themselves, not a cut
  * to be discovered: the anchor is dropped from both and reported, so neither side can be bound by
@@ -808,7 +837,7 @@ export function resolveConcernAnchors({ manualWitness, taskIds, evidence } = {})
         continue;
       }
       for (const symbol of entry.symbols) {
-        const symbolPath = resolvedSymbolPath(queries, symbol);
+        const symbolPath = resolveConcernSymbolPath(queries, symbol, resourcePath);
         if (symbolPath === null) {
           unknowns.push({ kind: 'concern_anchor_unresolved', ref: `${taskId}:${symbol}` });
           continue;
@@ -1894,7 +1923,7 @@ function conflictComponents(independenceArtifact) {
 }
 
 /**
- * Build the immutable lattice.seam_proposal.v1 artifact from one complete independence record.
+ * Build the immutable lattice.seam_proposal.v2 artifact from one complete independence record.
  * Sensor collection stays outside this producer; callers pass the original witness evidence and
  * the seam-specific normalized/raw evidence collected for the same clean HEAD.
  */

package/src/todo-cli.mjs

@@ -1013,7 +1013,10 @@ async function seamProposal({ repoRoot, requestedPlanKey }) {
     topology_digest: artifact?.source_binding.topology_digest ?? null,
     independence_result_digest: artifact?.source_binding.independence_result_digest ?? null,
     compiled_at: artifact?.compiled_at ?? null,
-    guidance: selectSeamProposalGuidance({ coverage }),
+    guidance: selectSeamProposalGuidance({
+      coverage,
+      unknownKinds: components.flatMap(({ unknowns }) => unknowns.map(({ kind }) => kind)),
+    }),
     component_count: artifact === null ? null : components.length,
     conflict_resource_count: artifact === null ? null : components
       .reduce((count, component) => count + component.conflicts.length, 0),

package/src/todo-independence-guidance.mjs

@@ -24,9 +24,39 @@ export const SEAM_PROPOSAL_GUIDANCE_CODES = Object.freeze([
   'seam_proposal_unrecorded',
   'seam_proposal_superseded',
   'seam_proposal_stale',
+  'seam_proposal_binding_overlap',
+  'seam_proposal_binding_outside_resource',
+  'seam_proposal_binding_symbol_unresolved',
+  'seam_proposal_binding_resource_unresolved',
+  'seam_proposal_binding_ambiguous',
+  'seam_proposal_binding_missing',
   'seam_proposal_verified',
 ]);
 
+/**
+ * 束縛失敗のunknown種別から案内codeを引く表。並びは優先順で、先頭ほど次の一歩が具体的である。
+ *
+ * 宣言が壊れている状況を、宣言が無い状況より上に置く。壊れている方は直す対象が
+ * 一意に決まるのに対し、無い方は何をどう宣言するかから決めることになるからである。
+ */
+const SEAM_PROPOSAL_BINDING_GUIDANCE = Object.freeze([
+  Object.freeze(['concern_anchor_overlap', 'seam_proposal_binding_overlap']),
+  Object.freeze(['concern_anchor_outside_resource', 'seam_proposal_binding_outside_resource']),
+  Object.freeze(['concern_anchor_unresolved', 'seam_proposal_binding_symbol_unresolved']),
+  Object.freeze(['concern_anchor_resource_unresolved', 'seam_proposal_binding_resource_unresolved']),
+  Object.freeze(['semantic_owner_binding_ambiguous', 'seam_proposal_binding_ambiguous']),
+  Object.freeze(['semantic_owner_binding_missing', 'seam_proposal_binding_missing']),
+]);
+
+/**
+ * 束縛の案内へ共通で添える、記録が更新される条件。
+ *
+ * concern_anchorsはwitness setにあり、seam提案はindependence記録のwitness_set_digestと
+ * 一致する宣言しか読まない。宣言を直しただけでは提案は変わらないので、そこまで述べないと
+ * 「直したのに同じunknownが出る」で止まる。
+ */
+const BINDING_RECOMPILE_HINT = '宣言はwitness setにあり、independence compileとseam-proposal compileを通し直すまで提案へ写らない。';
+
 const CATALOG = Object.freeze({
   independence_no_ready_frontier: Object.freeze({
     message: '着手候補が無いため、並列可否を述べる対象が無い。',
@@ -76,6 +106,30 @@ const CATALOG = Object.freeze({
     message: 'seam提案の生成後にHEADが進み、記録時点の構造証拠は現在のcodeを指していない。',
     next_action: 'compile_seam_proposal',
   }),
+  seam_proposal_binding_overlap: Object.freeze({
+    message: `同じ資源について、複数のToDoが同じsymbolを自分の担当として宣言している。どちら側へ切るか決まらないため、切断候補を束縛できない。${BINDING_RECOMPILE_HINT}`,
+    next_action: 'split_overlapping_concern_anchors_then_recompile',
+  }),
+  seam_proposal_binding_outside_resource: Object.freeze({
+    message: `concern_anchorsが挙げたsymbolが、withinで指した資源の外にある。その資源の分割を説明しないので束縛へ使えない。${BINDING_RECOMPILE_HINT}`,
+    next_action: 'correct_concern_anchors_then_recompile',
+  }),
+  seam_proposal_binding_symbol_unresolved: Object.freeze({
+    message: `concern_anchorsが挙げたsymbolを、sensorが同名同pathで解決できなかった。近い別symbolへは寄せないため、束縛は成立していない。${BINDING_RECOMPILE_HINT}`,
+    next_action: 'correct_concern_anchors_then_recompile',
+  }),
+  seam_proposal_binding_resource_unresolved: Object.freeze({
+    message: `concern_anchorsのwithinが指す資源をsensorで解決できなかった。宣言がどの資源についてのものか確定しない。${BINDING_RECOMPILE_HINT}`,
+    next_action: 'correct_concern_anchors_then_recompile',
+  }),
+  seam_proposal_binding_ambiguous: Object.freeze({
+    message: `宣言したsymbolが切断候補の複数側へ当たるため、どのToDoがどちらを所有するか一意に決まらない。${BINDING_RECOMPILE_HINT}`,
+    next_action: 'narrow_concern_anchors_then_recompile',
+  }),
+  seam_proposal_binding_missing: Object.freeze({
+    message: `係争資源の中でどのToDoが何を触るかが宣言されていないため、切断候補を所有者へ束縛できない。依存線でも呼び出し辺でも所有は決まらない。${BINDING_RECOMPILE_HINT}`,
+    next_action: 'declare_concern_anchors_then_recompile',
+  }),
   seam_proposal_verified: Object.freeze({
     message: 'seam提案の記録は現在のplan、並列可否記録、HEADと一致している。',
     next_action: 'none',
@@ -135,21 +189,37 @@ export function selectIndependenceGuidance({
   return todoIndependenceGuidance('independence_verified');
 }
 
-export function selectSeamProposalGuidance({ coverage }) {
-  const code = coverage === 'missing' ? 'seam_proposal_unrecorded'
-    : coverage === 'superseded' ? 'seam_proposal_superseded'
-      : coverage === 'stale' ? 'seam_proposal_stale'
-        : coverage === 'verified' ? 'seam_proposal_verified' : null;
-  if (code === null) throw new TypeError(`unknown seam proposal coverage: ${coverage}`);
-  return todoIndependenceGuidance(code);
+/**
+ * seam提案の状況から案内codeを引く。投影の生成側と契約の検査側が同じ規則を読むための正本。
+ *
+ * 鮮度（coverage）を束縛失敗より先に見る。記録が古い・別topologyについてのものである時、
+ * そこに載っているunknownは現在のcodeについての事実ではないため、先に再compileが要る。
+ * 記録が現在と一致している時だけ、束縛失敗が「今直せる状況」になる。
+ */
+export function seamProposalGuidanceCode({ coverage, unknownKinds = [] }) {
+  if (coverage === 'missing') return 'seam_proposal_unrecorded';
+  if (coverage === 'superseded') return 'seam_proposal_superseded';
+  if (coverage === 'stale') return 'seam_proposal_stale';
+  if (coverage !== 'verified') throw new TypeError(`unknown seam proposal coverage: ${coverage}`);
+  const kinds = new Set(unknownKinds);
+  const binding = SEAM_PROPOSAL_BINDING_GUIDANCE.find(([kind]) => kinds.has(kind));
+  return binding === undefined ? 'seam_proposal_verified' : binding[1];
+}
+
+export function selectSeamProposalGuidance({ coverage, unknownKinds = [] }) {
+  return todoIndependenceGuidance(seamProposalGuidanceCode({ coverage, unknownKinds }));
 }
 
 /**
  * 宣言からcompileを経て読むまでの順序。helpとMCP instructionsが同じ手順を語るための正本。
  * 面ごとに手順を書き直すと、片方だけが古くなる。
+ *
+ * 宣言できる欄を挙げる面はここだけなので、witness契約へ欄を足したらここへも足す。
+ * 足さないと、能力はあるのに機械が黙る面が残る（ADR 0130）。
  */
 export const TODO_INDEPENDENCE_WORKFLOW = Object.freeze([
   '1. 宣言する: .lattice/todo/witness/<plan_key>.json へ、ToDoごとのowns／reads／writes／affected_testsを書く',
+  '   係争資源しか所有していないToDoは、その資源の中で自分が触るsymbolをconcern_anchorsへ宣言できる（witness set v2）。並列可否の判定には写らず、切断候補の束縛だけに効く',
   '2. 判定する: lattice todo independence compile --plan <key> --input <ref>（実sensorを引き、clean worktreeが要る）',
   '3. 読む: lattice todo independence --plan <key> --json（sensorを引かず、記録とHEAD照合だけで返る）',
   '4. 追従する: plan改訂後は lattice todo independence witness migrate --plan <key> で宣言を写してから再compileする',