@ngockhoale/ukit 3.4.67 → 3.4.68

package/template_project/.claude/skills/advisor-plan/REFERENCE.md

@@ -22,6 +22,8 @@ Dispositions (exactly one per row):
 
 Prohibitions are confirmed exclusions: a source "must not" / "never" rule is recorded as a confirmed exclusion with its rationale. If it is enforceable in scope, it is a `feasible` or `adapted` row whose acceptance includes a referenced negative test (a test that proves the forbidden behaviour is absent). No new taxonomy is needed for this.
 
+`deferred` is never a catch-all: material the source itself marks as proposal, example, or rejected (and explicit non-goals) is recorded as `NOTES.md` entries with that kind (`proposal`/`example`/`rejected` — see Source-only notes), never squeezed into `deferred`. `deferred` means intentionally-later work and always names a queue entry; forcing non-work into it queues backlog that no cycle should ever drain.
+
 The `10` limit is a dispatch and context window, not a classification. Queued drafts carry no runnable rows; their INDEX rows are `queued_blueprint`.
 
 Footer (required, last lines of the file):
@@ -86,6 +88,14 @@ A blueprint without the line keeps the legacy fold-in behaviour. The contract is
 
 Before chunking, persist the original verbatim: `${OUTPUT_ROOT}SOURCE.md` holds the original path, the `sha256` of the original file's bytes (not of this wrapper or any metadata header), and an unmodified copy of those bytes. For chat or pasted input with no file, record the durable verbatim message origin (message id or transcript path plus the exact text) in place of the path. Gatherers and planners cite `SOURCE.md` lines; no model paraphrase replaces it. The reviewer starts its chain from `SOURCE.md` and re-hashes the original bytes.
 
+Write it with the deterministic helper as ONE simple command, literal paths, no `cd`, no compound — never a hand-built wrapper:
+
+```
+node .claude/ukit/index/source-snapshot.mjs <original-path> docs/AI_HANDOFF/SOURCE.md
+```
+
+(under a queued root, pass that root's SOURCE.md path). It records the origin path, the sha256 and a byte-identical copy, refuses to overwrite an existing snapshot, and `--check <snapshot> [original]` re-hashes the copy for the reviewer. If it cannot run (denial, budget), `PLAN.md` and `LEDGER.md` must state `source snapshot MISSING` explicitly — never cite only a mutable path as the source.
+
 ## Source-only notes
 
 File: `${OUTPUT_ROOT}NOTES.md` (the semantic record is mandatory: every classification, exclusion, and rationale is recorded durably, and this file is the default home for the non-task items; an equivalent name is acceptable, and the file is written only when such items exist). Non-requirement material that a ledger row cannot carry. Each entry names its source (`doc §… L…`, or the human's words) and one kind:

package/template_project/.claude/skills/advisor-plan/SKILL.md

@@ -28,7 +28,7 @@ This skill is **planning-only**. A create session that loads it edits docs and t
 ### Phase A — Gather (lite tier)
 
 1. Read the document header and table of contents; unreadable or empty source → write ledger row `R-000 | blocker` naming the missing input, create no tasks, stop.
-1a. **Source snapshot** — before chunking, write `${OUTPUT_ROOT}SOURCE.md` with the original path (or the durable verbatim message origin for chat input), the `sha256` of the original bytes, and a verbatim copy of the full source text (see [REFERENCE.md](./REFERENCE.md#source-snapshot)). Chunks and citations point into this copy, never into a paraphrase.
+1a. **Source snapshot** — before chunking, write `${OUTPUT_ROOT}SOURCE.md` with the original path (or the durable verbatim message origin for chat input), the `sha256` of the original bytes, and a verbatim copy of the full source text (see [REFERENCE.md](./REFERENCE.md#source-snapshot)). Use the helper, ONE simple command, literal paths: `node .claude/ukit/index/source-snapshot.mjs <original-path> docs/AI_HANDOFF/SOURCE.md`; if it cannot run (denial, budget), state `source snapshot MISSING` explicitly in PLAN/LEDGER. Chunks and citations point into this copy, never into a paraphrase.
 2. Split into chunks of at most 800 lines; one bounded gatherer per chunk extracts candidate requirements as `Source` (section/line) + normalized text. Dedupe by normalized text, keep the first source; contradictory requirements become a `blocker` row.
 3. **Feasibility evidence** — per requirement, inspect the CURRENT source index-first (`query-index.mjs` / `resolve-context.mjs`, then read the code that would change) plus `git log`, `git diff` and `git status` of the touched areas. Record each finding in the ledger row as evidence (file:line or commit) using the block in [REFERENCE.md](./REFERENCE.md#feasibility-evidence). Gatherers collect; the smart tier decides.
 4. **Related-project research (default on, bounded)** — per requirement cluster search the internet / GitHub for related projects and prior art (how others solved it, what to adopt or avoid) via `.claude/skills/research/SKILL.md`, under the sanitized-query and untrusted-source rules in [REFERENCE.md](./REFERENCE.md#research-rules). Feed the findings into each row's feasibility evidence. Skip only when no sanitized query is possible or no research tool exists, and record the skip reason in the ledger notes.
@@ -37,7 +37,7 @@ Tier (lite gatherers): on Claude Code start a read-only `general-purpose` subage
 
 ### Phase B — Decide, ledger, plan (smart tier)
 
-1. Use the evidence to assign every extracted requirement exactly one disposition: `feasible`, `adapted`, `deferred`, or `blocker`. `adapted` lists 2-3 alternatives with the chosen one marked; `deferred` names its queue entry and a justification; `blocker` names the missing prerequisite or owner conflict.
+1. Use the evidence to assign every extracted requirement exactly one disposition: `feasible`, `adapted`, `deferred`, or `blocker`. `adapted` lists 2-3 alternatives with the chosen one marked; `deferred` (intentionally later) names its queue entry and a justification; `blocker` names the missing prerequisite or owner conflict. Source-marked proposal/example/rejected items are `NOTES.md` entries with that kind, never `deferred`.
 2. Only `feasible`/`adapted` rows map to executable tasks, and each maps to an executable acceptance criterion and a test or verification command. `deferred` rows need a justification and a queue entry, not a task. `blocker` rows need the missing prerequisite or owner decision named, not a task. Rows the source marks as proposal, example, or rejected are not promoted to tasks: they stay as classified NOTES entries with their rationale.
 3. Write `${OUTPUT_ROOT}LEDGER.md` with the footer `Coverage: N/N rows dispositioned` and the sentence "disposition coverage is not implementation coverage". Never claim "100% implemented".
 4. **Candidate plans** — draft 2-3 candidate whole-plans (different decomposition, risk, ordering), score them on the rubric in [REFERENCE.md](./REFERENCE.md#candidate-plan-rubric), pick the best, and record the choice plus rejected alternatives in `PLAN.md`.

package/template_project/.claude/ukit/index/allocate-task-worktree.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import { allocateTaskWorktree } from '../runtime/worktree-allocation.mjs';
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  const [root, taskId, ...extra] = process.argv.slice(2);
+  if (!root || !taskId || extra.length) {
+    console.error('Usage: node allocate-task-worktree.mjs <project-root> <TASK-id>');
+    process.exitCode = 2;
+  } else {
+    try { console.log(JSON.stringify(await allocateTaskWorktree(root, taskId), null, 2)); }
+    catch (error) { console.error(`Allocation refused: ${error.message}`); process.exitCode = 2; }
+  }
+}

package/template_project/.claude/ukit/index/amend-guard.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// amend-guard.mjs — CR-10: overwriting PLAN.md / SPEC.md / LEDGER.md (or any planned file)
+// requires a preserved copy under `amendments/rev-<NN>/<same relative path>` first.
+//
+// A valid copy must be: a regular, non-empty file at the SAME relative subpath as the file
+// being overwritten (queued/foo/PLAN.md needs amendments/rev-NN/queued/foo/PLAN.md, never a
+// root copy), byte-identical to the current file (the copy is the prior version, taken
+// right before the rewrite), and not a symlink. A brand-new target (absent on disk) needs
+// no copy, but a queued/<slug> directory that already exists is a collision and needs one.
+//
+// Mechanical scope: this checker verifies the COPY exists before a rewrite. It is invoked
+// by the create/planner instructions before composing a revised plan (prose enforcement —
+// hosts have no Write-time hook for docs paths).
+//
+// Usage:
+//   node .claude/ukit/index/amend-guard.mjs <handoff-root> <FILE.md> [FILE.md ...]
+//
+// Output:
+//   `AMEND_GUARD: ok` when every named file is either brand-new or has a valid copy;
+//   otherwise one `overwrite blocked: <FILE> has no amendments/rev-<NN> copy — copy the prior
+//   version to the next unused rev dir first` line per blocked file. Exit 0 = safe, 1 = blocked, 2 = usage.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+function isDirectRun() {
+  try {
+    return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+const GUARDED = new Set(['PLAN.md', 'SPEC.md', 'LEDGER.md', 'INDEX.md', 'NOTES.md', 'SOURCE.md']);
+
+function lstatSafe(file) {
+  try {
+    return fs.lstatSync(file);
+  } catch {
+    return null;
+  }
+}
+
+// A valid preserved copy: same relative subpath under some rev-NN, regular file (no symlink),
+// non-empty, and — when `currentBuf` is given — byte-identical to the file it protects.
+// `currentBuf === null` accepts any valid copy (used for a queued/<slug> collision check).
+function hasValidCopy(root, rel, currentBuf) {
+  const amendmentsDir = path.join(root, 'amendments');
+  let entries;
+  try {
+    entries = fs.readdirSync(amendmentsDir);
+  } catch {
+    return false;
+  }
+  return entries
+    .filter((e) => /^rev-\d+$/.test(e))
+    .some((rev) => {
+      const copy = path.join(amendmentsDir, rev, rel);
+      const st = lstatSafe(copy);
+      if (!st || !st.isFile() || st.size === 0) return false;
+      if (currentBuf === null) return true;
+      try {
+        return fs.readFileSync(copy).equals(currentBuf);
+      } catch {
+        return false;
+      }
+    });
+}
+
+function main() {
+  const root = process.argv[2];
+  const files = process.argv.slice(3);
+  if (!root || files.length === 0) {
+    console.log('AMEND_GUARD: usage error — expected `<root> <FILE.md> [FILE.md ...]`');
+    process.exit(2);
+  }
+  const blocked = [];
+  for (const rel of files) {
+    const base = path.basename(rel);
+    if (!GUARDED.has(base)) {
+      console.log(`AMEND_GUARD: usage error — ${base} is not a guarded planning file (${[...GUARDED].join(', ')})`);
+      process.exit(2);
+    }
+    const target = path.join(root, rel);
+    const st = lstatSafe(target);
+    if (!st) {
+      // Brand-new file: nothing is overwritten — unless its queued/<slug> unit already exists.
+      const unitDir = path.dirname(target);
+      const isQueuedUnit = path.basename(path.dirname(unitDir)) === 'queued';
+      const unitExists = isQueuedUnit && fs.existsSync(unitDir) && fs.readdirSync(unitDir).length > 0;
+      if (unitExists && !hasValidCopy(root, rel, null)) blocked.push(rel);
+      continue;
+    }
+    if (!st.isFile()) {
+      blocked.push(rel);
+      continue;
+    }
+    if (!hasValidCopy(root, rel, fs.readFileSync(target))) {
+      blocked.push(rel);
+    }
+  }
+  if (blocked.length > 0) {
+    for (const rel of blocked) {
+      console.log(`overwrite blocked: ${rel} has no amendments/rev-<NN> copy — copy the prior version to the next unused rev dir first`);
+    }
+    process.exit(1);
+  }
+  console.log('AMEND_GUARD: ok');
+  process.exit(0);
+}
+
+if (isDirectRun()) {
+  main();
+}

package/template_project/.claude/ukit/index/cleanup-task-worktree.mjs

@@ -161,7 +161,7 @@ const sha256File = (p) => crypto.createHash('sha256').update(fs.readFileSync(p))
 const RECEIPT_KEYS = [
   'schemaVersion', 'taskId', 'baseCommit', 'sourceRoot', 'destinationRoot',
   'sourceBranch', 'sourceHead', 'destinationHeadBefore', 'sourceSnapshotTree',
-  'resultTree', 'patchSha256', 'scopeSha256', 'changedPaths', 'createdAt', 'status',
+  'resultTree', 'patchSha256', 'scopeSha256', 'changedPaths', 'createdAt', 'status', 'adoption',
 ];
 const APPROVAL_KEYS = [
   'schemaVersion', 'taskId', 'receiptSha256', 'verdict', 'executorModel',

package/template_project/.claude/ukit/index/land-worktree.mjs

@@ -46,6 +46,8 @@ import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { reconcileTaskRecord } from '../runtime/task-record-reconciliation.mjs';
 
 const GIT_TIMEOUT_MS = (() => {
   const raw = Number(process.env.UKIT_LAND_GIT_TIMEOUT_MS);
@@ -57,12 +59,32 @@ const USAGE = `land-worktree.mjs — task-scoped base-relative worktree landing
 
 Usage:
   node land-worktree.mjs --scope <json-path> --receipt <new-json-path>
+  node land-worktree.mjs --adopt-applied --scope <json-path> --receipt <new-json-path>
+  node land-worktree.mjs --reconcile-metadata <proof-json> --scope <json-path> --receipt <new-json-path>
   node land-worktree.mjs --help
 
 Scope JSON (schemaVersion 1): taskId, baseCommit, sourceRoot, destinationRoot,
 sourceHead, destinationHead, targetPaths[].
 The receipt path must be a NEW file outside the source worktree and outside the
-target set. exit 0 landed/no-op; exit 2 refusal/validation; exit 1 runtime error.`;
+target set. Landing is refused (worker-not-terminated) while any delegated worker claim exists
+for the task in the destination claims store (claims-unreadable if the store cannot be read); the
+check and the landing mutation run under the same claims lock, so no claim transition can interleave.
+
+--adopt-applied reconciles a landing whose bytes are ALREADY committed in the destination HEAD
+without a receipt: nothing is applied; every delta path's blob+mode in the destination HEAD must equal
+the source snapshot (else adopt-mismatch), and the receipt is explicitly marked adoption
+"already-applied". Same worker-claim fence, scope and cleanliness checks as a normal landing.
+
+--reconcile-metadata is a separate, no-apply history comparison. Proof schemaVersion:1 holds
+records[{path,status?,additions[{text,evidence}]}] and evidence[{id,kind:"commit",commit,path,sha256}
+or {id,kind:"file",path,sha256}]. Commit evidence must be retained destination history; file evidence
+is a caller-pinned audit artifact, not independent semantic approval. Only this task record can have
+evidenced blocked-status/append-only review or recovery progression; requirements/AC/dependencies
+and existing verdict bytes remain exact. Audit provenance before supplying proof. Other delta paths
+must be byte-identical. Receipt status is reconciled, NEVER landed, completion or cleanup authority.
+Both modes retain the full scope; do not omit changed paths to make equality pass.
+
+exit 0 landed/no-op/reconciled; exit 2 refusal/validation; exit 1 runtime error.`;
 
 // --- bounded process helpers ------------------------------------------------
 
@@ -105,12 +127,14 @@ function emit(status, taskId, reason, changedPaths, receiptPath) {
 function refuse(taskId, reason, diagnostic) {
   if (diagnostic) process.stderr.write(`land-worktree: ${reason}: ${diagnostic}\n`);
   emit('refused', taskId, reason, [], null);
+  if (inClaimsLock) throw new LandExit(2);
   process.exit(2);
 }
 
 function runtimeError(taskId, reason, diagnostic) {
   if (diagnostic) process.stderr.write(`land-worktree: ${reason}: ${diagnostic}\n`);
   emit('error', taskId, reason, [], null);
+  if (inClaimsLock) throw new LandExit(1);
   process.exit(1);
 }
 
@@ -119,11 +143,21 @@ function runtimeError(taskId, reason, diagnostic) {
 const argv = process.argv.slice(2);
 let scopePath = null;
 let receiptPath = null;
+let adoptApplied = false;
+let reconciliationPath = null;
+let reconciliationPreflight = false;
 for (let i = 0; i < argv.length; i += 1) {
   const a = argv[i];
   if (a === '--help' || a === '-h') {
     process.stdout.write(`${USAGE}\n`);
     process.exit(0);
+  } else if (a === '--preflight') {
+    reconciliationPreflight = true;
+  } else if (a === '--reconcile-metadata') {
+    reconciliationPath = argv[++i];
+    if (!reconciliationPath) { process.stderr.write('land-worktree: missing reconciliation proof\n'); process.exit(2); }
+  } else if (a === '--adopt-applied') {
+    adoptApplied = true;
   } else if (a === '--scope') {
     scopePath = argv[++i];
     if (scopePath === undefined) { process.stderr.write('land-worktree: missing value for --scope\n'); process.exit(2); }
@@ -135,11 +169,45 @@ for (let i = 0; i < argv.length; i += 1) {
     process.exit(2);
   }
 }
+if (reconciliationPreflight && !reconciliationPath) {
+  process.stderr.write('land-worktree: --preflight requires --reconcile-metadata\n');
+  process.exit(2);
+}
 if (!scopePath || !receiptPath) {
   process.stderr.write(`land-worktree: --scope and --receipt are both required\n${USAGE}\n`);
   process.exit(2);
 }
 
+// Stale-worker landing authority. The trusted source is the hook-written claims store in the
+// destination project (never caller-supplied flags): while ANY delegated worker claim for the task
+// exists -- active, or expired (lease expiry is not proof the worker ended) -- landing is refused
+// (worker-not-terminated). An unreadable store or unloadable runtime refuses too (fail closed).
+// The check runs INSIDE the claims lock and the lock is held through apply+verify+receipt, so a
+// claim transition (grant/takeover/release) cannot interleave with the landing mutation.
+let inClaimsLock = false;
+class LandExit extends Error { constructor(code) { super('land-exit'); this.exitCode = code; } }
+const RUNTIME_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'runtime');
+const LAND_LOCK_BUDGET_MS = 5000;
+
+async function barrier(name) {
+  const dir = process.env.UKIT_LAND_BARRIER_DIR; // deterministic race-test hook; inert when unset
+  if (!dir) return;
+  try { fs.writeFileSync(path.join(dir, `${name}.reached`), ''); } catch { return; } // bad dir == unset
+  const go = path.join(dir, `${name}.go`);
+  const end = Date.now() + 30000;
+  while (!fs.existsSync(go) && Date.now() < end) await new Promise((r) => setTimeout(r, 10));
+}
+
+async function workerAuthorityClear(taskId, root) {
+  try {
+    const mod = await import(pathToFileURL(path.join(RUNTIME_DIR, 'resumable-run.mjs')).href);
+    const r = await mod.readTaskClaim(root, taskId);
+    if (r.unreadable) return 'claims-unreadable';
+    if (r.claimed && String(r.claim.owner || '').startsWith('deleg:')) return 'worker-not-terminated';
+    return null;
+  } catch { return 'claims-unreadable'; }
+}
+
 // --- scope validation --------------------------------------------------------
 
 const SCOPE_KEYS = [
@@ -221,7 +289,7 @@ const isInsideOrEqual = (child, parent) => {
 
 // --- main --------------------------------------------------------------------
 
-function main() {
+async function main() {
   const scope = readScope();
   const { taskId, targetPaths } = scope;
   const targets = new Set(targetPaths);
@@ -361,11 +429,142 @@ function main() {
   const patchSha256 = crypto.createHash('sha256').update(patchBuf).digest('hex');
   const scopeSha256 = crypto.createHash('sha256').update(fs.readFileSync(scopePath)).digest('hex');
 
+  // Everything from here to the receipt runs under the claims lock with the authority checked
+  // inside it (fence + mutation are one critical section; see workerAuthorityClear).
+  await barrier('pre-lock');
+  const lockMod = await import(pathToFileURL(path.join(RUNTIME_DIR, 'async-lock.mjs')).href).catch(() => null);
+  const claimsMod = await import(pathToFileURL(path.join(RUNTIME_DIR, 'resumable-run.mjs')).href).catch(() => null);
+  if (!lockMod || !claimsMod) refuse(taskId, 'claims-unreadable', 'claims runtime unavailable');
+  let exitCode = 0;
+  try {
+    fs.mkdirSync(path.dirname(claimsMod.taskClaimsPath(destinationRoot)), { recursive: true });
+    const outcome = await lockMod.withAsyncLock(claimsMod.taskClaimsPath(destinationRoot), { deadlineMs: LAND_LOCK_BUDGET_MS }, async () => {
+      inClaimsLock = true;
+      try {
+        const blocked = await workerAuthorityClear(taskId, destinationRoot);
+        if (blocked) refuse(taskId, blocked, 'a delegated worker claim exists for this task');
+        await barrier('in-lock');
+        landLocked();
+      } finally { inClaimsLock = false; }
+    });
+    if (!outcome.ok) refuse(taskId, 'claims-busy', 'could not take the claims lock');
+  } catch (e) {
+    if (!(e instanceof LandExit)) throw e;
+    exitCode = e.exitCode;
+  }
+  process.exit(exitCode);
+
+  function reconcileLocked() {
+    const stable = () => {
+      if (gitText(sourceRoot, ['rev-parse', 'HEAD']).stdout.trim() !== srcHead
+        || gitText(destinationRoot, ['rev-parse', 'HEAD']).stdout.trim() !== dstHead) refuse(taskId, 'head-drift', 'HEAD moved during reconciliation');
+      checkDestinationClean(destinationRoot, targetPaths, taskId);
+      if (computeWorktreeTree(sourceRoot) !== snapshotTree) refuse(taskId, 'source-drift', 'source snapshot moved during reconciliation');
+    };
+    stable();
+    if (adoptApplied) refuse(taskId, 'invalid-proof', 'reconciliation and adoption are separate operations');
+    let proof;
+    try { proof = JSON.parse(fs.readFileSync(reconciliationPath, 'utf8')); } catch { refuse(taskId, 'invalid-proof', 'proof unreadable'); }
+    if (proof?.schemaVersion !== 1 || !Array.isArray(proof.records) || !Array.isArray(proof.evidence)) refuse(taskId, 'invalid-proof', 'invalid proof schema');
+    const evidence = new Map();
+    const evidenceRefs = [];
+    for (const e of proof.evidence) {
+      if (!e || typeof e.id !== 'string' || evidence.has(e.id) || !/^[a-f0-9]{64}$/.test(e.sha256 || '')) refuse(taskId, 'invalid-proof', 'invalid evidence identity');
+      let bytes;
+      if (e.kind === 'commit') {
+        if (!/^[a-f0-9]{40}$/.test(e.commit || '') || !targetPaths.includes(e.path)
+          || gitText(destinationRoot, ['merge-base', '--is-ancestor', e.commit, dstHead]).status !== 0) refuse(taskId, 'invalid-proof', 'evidence commit is not retained destination history');
+        const r = gitBytes(destinationRoot, ['show', `${e.commit}:${e.path}`]);
+        if (r.status !== 0) refuse(taskId, 'invalid-proof', 'evidence blob unavailable');
+        bytes = r.stdout;
+      } else if (e.kind === 'file') {
+        // File evidence is explicitly scoped to the pinned proof's audit directory.
+        // This authenticates declared bytes, not the narrative's semantic provenance.
+        try {
+          const auditDir = path.dirname(fs.realpathSync(reconciliationPath));
+          const evidencePath = fs.realpathSync(e.path);
+          if (path.dirname(evidencePath) !== auditDir || !fs.statSync(evidencePath).isFile()) refuse(taskId, 'invalid-proof', 'file evidence must be colocated with the proof in its audit directory');
+          bytes = fs.readFileSync(evidencePath);
+        } catch (e) {
+          if (e instanceof LandExit) throw e;
+          refuse(taskId, 'invalid-proof', 'evidence file unavailable');
+        }
+      } else refuse(taskId, 'invalid-proof', 'unknown evidence kind');
+      if (crypto.createHash('sha256').update(bytes).digest('hex') !== e.sha256) refuse(taskId, 'invalid-proof', 'evidence hash mismatch');
+      evidence.set(e.id, bytes.toString('utf8'));
+      evidenceRefs.push(e);
+    }
+    const records = new Map();
+    for (const r of proof.records) {
+      if (r?.path !== `docs/AI_HANDOFF/tasks/${taskId}.md` || records.has(r.path)) refuse(taskId, 'invalid-proof', 'only this exact task record may have a history progression');
+      records.set(r.path, r);
+    }
+    // The scope must describe the WHOLE delta, never omit a mismatching record.
+    if (targetPaths.length !== deltaPaths.length || targetPaths.some((p) => !deltaPaths.includes(p))) refuse(taskId, 'scope-drift', 'reconciliation scope must equal the complete source delta');
+    const rows = [];
+    for (const p of deltaPaths) {
+      const entry = (root, tree) => {
+        const r = gitText(root, ['ls-tree', '-z', tree, '--', p]);
+        if (r.status !== 0) refuse(taskId, 'reconcile-unreadable', 'tree entry unavailable');
+        const m = r.stdout.match(/^(\d+) (\w+) ([a-f0-9]+)\t/);
+        return m ? { mode: m[1], type: m[2], blob: m[3] } : null;
+      };
+      const b = entry(sourceRoot, base), s = entry(sourceRoot, snapshotTree), d = entry(destinationRoot, dstHead);
+      const row = { path: p, base: b, source: s, destination: d, result: d, kind: 'byte-identical' };
+      if (JSON.stringify(s) !== JSON.stringify(d)) {
+        const r = records.get(p);
+        if (!r || !s || !d || s.mode !== '100644' || d.mode !== s.mode || s.type !== 'blob' || d.type !== 'blob') refuse(taskId, 'reconcile-mismatch', `unexplained mismatch at ${JSON.stringify(p)}`);
+        const text = (oid) => {
+          const result = gitBytes(sourceRoot, ['cat-file', 'blob', oid]);
+          if (result.status !== 0) refuse(taskId, 'reconcile-unreadable', 'blob unavailable');
+          const decoded = result.stdout.toString('utf8');
+          if (!Buffer.from(decoded).equals(result.stdout)) refuse(taskId, 'reconcile-unreadable', 'task record is not UTF-8');
+          return decoded;
+        };
+        try { row.progression = reconcileTaskRecord(text(s.blob), text(d.blob), r, evidence); }
+        catch (e) { refuse(taskId, 'reconcile-mismatch', e.message); }
+        row.kind = 'history-progression';
+        records.delete(p);
+      }
+      rows.push(row);
+    }
+    if (records.size) refuse(taskId, 'invalid-proof', 'unused metadata proof');
+    stable();
+    const receipt = { schemaVersion: 1, receiptKind: 'metadata-reconciliation', status: 'reconciled', taskId,
+      baseCommit: base, sourceHead: srcHead, destinationHead: dstHead, sourceSnapshotTree: snapshotTree,
+      sourceRoot, destinationRoot, scopeSha256, proofSha256: crypto.createHash('sha256').update(fs.readFileSync(reconciliationPath)).digest('hex'),
+      paths: rows, evidence: evidenceRefs, completion: false, cleanupEligible: false, createdAt: new Date().toISOString() };
+    if (reconciliationPreflight) {
+      process.stdout.write(`${JSON.stringify({ ...receipt, status: 'reconciliation-preflight', receiptPath: null })}\n`);
+      return;
+    }
+    try {
+      fs.mkdirSync(path.dirname(receiptAbs), { recursive: true });
+      fs.writeFileSync(receiptAbs, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx' });
+    } catch (e) { runtimeError(taskId, 'receipt-write-failed', e.code || e.message); }
+    emit('reconciled', taskId, 'history-preserved', deltaPaths, receiptAbs);
+  }
+
+  function landLocked() {
+  if (reconciliationPath) {
+    reconcileLocked();
+    return;
+  }
   // A verified empty delta is a landed no-op: identity check only, no apply.
+  if (adoptApplied) {
+    for (const p of deltaPaths) {
+      if (treeEntry(sourceRoot, snapshotTree, p) !== treeEntry(destinationRoot, 'HEAD', p)) {
+        refuse(taskId, 'adopt-mismatch', `destination HEAD does not already hold the source snapshot at ${JSON.stringify(p)}`);
+      }
+    }
+    writeReceipt(receiptAbs, taskId, base, sourceRoot, destinationRoot, srcHead, dstHead, snapshotTree, computeWorktreeTree(destinationRoot), patchSha256, scopeSha256, deltaPaths);
+    emit('landed', taskId, 'adopted', deltaPaths, receiptAbs);
+    return;
+  }
   if (deltaPaths.length === 0) {
     writeReceipt(receiptAbs, taskId, base, sourceRoot, destinationRoot, srcHead, dstHead, snapshotTree, snapshotTree, patchSha256, scopeSha256, deltaPaths);
     emit('landed', taskId, 'no-op', deltaPaths, receiptAbs);
-    process.exit(0);
+    return;
   }
 
   const tmpPatch = path.join(os.tmpdir(), `ukit-land-${process.pid}-${crypto.randomBytes(6).toString('hex')}.patch`);
@@ -408,7 +607,7 @@ function main() {
 
   writeReceipt(receiptAbs, taskId, base, sourceRoot, destinationRoot, srcHead, dstHead, snapshotTree, dstTree, patchSha256, scopeSha256, deltaPaths);
   emit('landed', taskId, 'ok', deltaPaths, receiptAbs);
-  process.exit(0);
+  }
 }
 
 // --- helpers -----------------------------------------------------------------
@@ -436,7 +635,9 @@ function computeWorktreeTree(root) {
   const idx = path.join(os.tmpdir(), `ukit-land-${process.pid}-${crypto.randomBytes(6).toString('hex')}.index`);
   try {
     const env = { GIT_INDEX_FILE: idx };
-    for (const args of [['read-tree', 'HEAD'], ['add', '-A']]) {
+    // The claims lock this landing holds lives in the destination; it is never landed content. It is dropped from the temp index afterwards: an exclude pathspec makes `git add` fail when
+    // the destination .gitignore ignores that path.
+    for (const args of [['read-tree', 'HEAD'], ['add', '-A', '--', '.'], ['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', '.ukit/storage/runs/claims.json.lock']]) {
       const r = gitText(root, args, env);
       if (r.status !== 0) runtimeError(null, 'verify-failed', r.stderr.split('\n')[0]);
     }
@@ -483,6 +684,7 @@ function writeReceipt(absPath, taskId, base, sourceRoot, destinationRoot, srcHea
     changedPaths: changedPaths.slice(),
     createdAt: new Date().toISOString(),
     status: 'landed',
+    ...(adoptApplied ? { adoption: 'already-applied' } : {}),
   };
   try {
     fs.mkdirSync(path.dirname(absPath), { recursive: true });
@@ -495,31 +697,51 @@ function writeReceipt(absPath, taskId, base, sourceRoot, destinationRoot, srcHea
 }
 
 function checkDestinationClean(destinationRoot, targetPaths, taskId) {
-  const st = gitText(destinationRoot, ['status', '--porcelain', '-z']);
+  // --untracked-files=all enumerates every untracked file individually (no
+  // whole-directory collapse), so each tolerated entry is an exact path that
+  // verify's delta check can exclude precisely.
+  const st = gitText(destinationRoot, ['status', '--porcelain', '-z', '--untracked-files=all']);
   if (st.status !== 0) refuse(taskId, 'destination-unreadable', 'could not read the destination status');
   const entries = parsePorcelainZ(st.stdout);
-  // Protected set: every target path and every ancestor directory of a target.
-  const protectedPaths = new Set();
-  for (const t of targetPaths) {
-    protectedPaths.add(t);
-    const parts = t.split('/');
-    for (let i = 1; i < parts.length; i += 1) protectedPaths.add(parts.slice(0, i).join('/'));
-  }
-  const collides = (p) => protectedPaths.has(p) || [...protectedPaths].some((d) => p.startsWith(`${d}/`));
+  // Refuse a TRUE overlap with a target only: the target path itself, untracked
+  // content under a target path (a directory occupying the target's name), or
+  // an untracked file occupying a needed ancestor directory of a target. An
+  // entry that merely shares an ancestor directory with a target (e.g.
+  // "docs/AI_HANDOFF/RUN.md" beside "docs/AI_HANDOFF/tasks/TASK-001.md") is
+  // unrelated and tolerated.
+  const collides = (p) => targetPaths.some((t) => t === p || p.startsWith(`${t}/`) || t.startsWith(`${p}/`));
   const tolerated = new Set();
+  const dirty = [];
 
   for (const { xy, path: p } of entries) {
     if (xy === '??') {
-      // Untracked: refuse only a target-path collision; unrelated files tolerated.
       if (collides(p)) refuse(taskId, 'destination-collision', `untracked file collides with a target path: ${JSON.stringify(p)}`);
-      // `-z` disables core.quotePath, but git still prints a directory entry with
-      // a trailing slash — normalize so verify's delta set matches.
-      tolerated.add(p.endsWith('/') ? p.slice(0, -1) : p);
+      // An untracked nested repository / linked worktree (e.g. .worktrees/task-001) is
+      // reported by status as "dir/" but recorded by `git add -A` as the gitlink "dir";
+      // tolerate the gitlink spelling too so verify does not call it an unexpected landing.
+      tolerated.add(p);
+      if (p.length > 1 && p.endsWith('/')) tolerated.add(p.slice(0, -1));
     } else {
-      // Any tracked modification or staged change anywhere refuses.
-      refuse(taskId, 'destination-dirty', `tracked modification at ${JSON.stringify(p)}`);
+      // Any tracked modification or staged change anywhere refuses (FR-M4-002:
+      // "tracked-clean destination" — a patch applied over unrelated tracked
+      // edits would bake them into the verify snapshot and receipt resultTree).
+      dirty.push(p);
     }
   }
+  if (dirty.length > 0) {
+    // Actionable refusal: name every dirty path (bounded) and the supported
+    // recovery — the owner commits or stashes those paths, or the coordinator
+    // lands into a clean destination worktree after checkpointing landed paths.
+    const listed = dirty.slice(0, 8).map((p) => JSON.stringify(p)).join(', ');
+    const more = dirty.length > 8 ? ` (+${dirty.length - 8} more)` : '';
+    refuse(
+      taskId,
+      'destination-dirty',
+      `tracked modification(s) at ${listed}${more} — the destination must be tracked-clean`
+        + ' (no uncommitted or staged tracked change anywhere). Recovery: the owner'
+        + ' commits or stashes these paths, or land into a clean destination worktree.',
+    );
+  }
   return tolerated;
 }
 
@@ -540,4 +762,4 @@ function parsePorcelainZ(raw) {
   return out;
 }
 
-main();
+await main();