@ngockhoale/ukit 3.4.22 → 3.4.24

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

@@ -0,0 +1,543 @@
+#!/usr/bin/env node
+/**
+ * land-worktree.mjs — task-scoped, base-relative worktree landing
+ * (C97 TASK-C97-009 · MODULE04-SPEC FR-M4-001/002/004 · §7–§14).
+ *
+ * The shipped 3c samples in handoff-fullstack.md / handoff-implement.md landed
+ * executor work with `git -C "$WORKTREE" diff --name-only | ... cp ...`. That
+ * enumerates only UNSTAGED tracked changes, so a committed milestone and a
+ * staged change never arrived, a deletion could not be propagated by copying a
+ * missing file, and whitespace/newline paths split on `read`. This helper
+ * replaces that loop with one complete, deterministic contract:
+ *
+ *   node .claude/ukit/index/land-worktree.mjs --scope <json> --receipt <json>
+ *
+ * It snapshots the source worktree's FINAL content relative to an explicit,
+ * immutable base commit — committed + staged + unstaged + nonignored untracked,
+ * with deletions, rename origins (`--no-renames` → delete + add) and binary /
+ * executable / symlink semantics — then applies that exact delta to a distinct
+ * destination worktree in the same Git common repository. Nothing is landed
+ * until the whole patch preflights; a receipt is written only after the landed
+ * result is re-verified byte-exact. The source HEAD and index are never
+ * modified, and no cleanup is performed here (that is TASK-C97-010).
+ *
+ * Safety posture (fail-closed, no mutation on any refusal):
+ *   - one schema for scope + receipt (schemaVersion 1), fixed by SPEC §7;
+ *   - explicit identities (base/heads/roots) — no cwd inference;
+ *   - same Git common repository, distinct roots, base an ancestor of both heads;
+ *   - tracked-clean destination; untracked files colliding with a target path
+ *     (or under a target directory) refuse; unrelated untracked files tolerated;
+ *   - every old/new delta path must be an approved target (no scope drift);
+ *   - no symlink ancestor traversal for a target path;
+ *   - receipt path must exist outside the source worktree and outside the target
+ *     set, and must not already exist (exclusive creation);
+ *   - all Git calls are bounded (timeout + kill), arguments are arrays — never
+ *     shell interpolation; the isolated index is a task-owned temp file.
+ *
+ * CLI: node land-worktree.mjs --scope <json> --receipt <json> | --help
+ * exit 0 landed/no-op; exit 2 validation/preflight/refusal; exit 1 runtime /
+ * apply / receipt failure (never claimed as success). stdout is one JSON object:
+ *   { status: "landed" | "refused" | "error", taskId, reason, changedPaths, receiptPath }
+ * stderr is a bounded diagnostic that never includes file contents.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+const GIT_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.UKIT_LAND_GIT_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 20000;
+})();
+const MAX_BUFFER = 256 * 1024 * 1024;
+
+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 --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.`;
+
+// --- bounded process helpers ------------------------------------------------
+
+function gitText(dir, args, extraEnv) {
+  const res = spawnSync('git', ['-C', dir, ...args], {
+    encoding: 'utf8',
+    timeout: GIT_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+    maxBuffer: MAX_BUFFER,
+    ...(extraEnv ? { env: { ...process.env, ...extraEnv } } : {}),
+  });
+  return res;
+}
+
+function gitBytes(dir, args, extraEnv) {
+  return spawnSync('git', ['-C', dir, ...args], {
+    encoding: 'buffer',
+    timeout: GIT_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+    maxBuffer: MAX_BUFFER,
+    ...(extraEnv ? { env: { ...process.env, ...extraEnv } } : {}),
+  });
+}
+
+// --- exit contract -----------------------------------------------------------
+
+class Refusal extends Error {} // exit 2 — validation / preflight / refusal
+class RuntimeFailure extends Error {} // exit 1 — apply / receipt / verify failure
+
+function emit(status, taskId, reason, changedPaths, receiptPath) {
+  process.stdout.write(`${JSON.stringify({
+    status,
+    taskId: taskId ?? null,
+    reason,
+    changedPaths: changedPaths ?? [],
+    receiptPath: receiptPath ?? null,
+  })}\n`);
+}
+
+function refuse(taskId, reason, diagnostic) {
+  if (diagnostic) process.stderr.write(`land-worktree: ${reason}: ${diagnostic}\n`);
+  emit('refused', taskId, reason, [], null);
+  process.exit(2);
+}
+
+function runtimeError(taskId, reason, diagnostic) {
+  if (diagnostic) process.stderr.write(`land-worktree: ${reason}: ${diagnostic}\n`);
+  emit('error', taskId, reason, [], null);
+  process.exit(1);
+}
+
+// --- args --------------------------------------------------------------------
+
+const argv = process.argv.slice(2);
+let scopePath = null;
+let receiptPath = null;
+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 === '--scope') {
+    scopePath = argv[++i];
+    if (scopePath === undefined) { process.stderr.write('land-worktree: missing value for --scope\n'); process.exit(2); }
+  } else if (a === '--receipt') {
+    receiptPath = argv[++i];
+    if (receiptPath === undefined) { process.stderr.write('land-worktree: missing value for --receipt\n'); process.exit(2); }
+  } else {
+    process.stderr.write(`land-worktree: unknown argument: ${a}\n${USAGE}\n`);
+    process.exit(2);
+  }
+}
+if (!scopePath || !receiptPath) {
+  process.stderr.write(`land-worktree: --scope and --receipt are both required\n${USAGE}\n`);
+  process.exit(2);
+}
+
+// --- scope validation --------------------------------------------------------
+
+const SCOPE_KEYS = [
+  'schemaVersion', 'taskId', 'baseCommit', 'sourceRoot', 'destinationRoot',
+  'sourceHead', 'destinationHead', 'targetPaths',
+];
+
+function readScope() {
+  let raw;
+  try {
+    raw = fs.readFileSync(scopePath, 'utf8');
+  } catch (e) {
+    refuse(null, 'invalid-scope', 'scope file unreadable');
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    refuse(null, 'invalid-scope', 'scope is not valid JSON');
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    refuse(null, 'invalid-scope', 'scope must be a JSON object');
+  }
+  for (const key of Object.keys(parsed)) {
+    if (!SCOPE_KEYS.includes(key)) refuse(parsed.taskId, 'invalid-scope', `unknown key: ${key}`);
+  }
+  if (parsed.schemaVersion !== 1) refuse(parsed.taskId, 'invalid-scope', 'schemaVersion must be 1');
+  const { taskId, baseCommit, sourceRoot, destinationRoot, sourceHead, destinationHead, targetPaths } = parsed;
+  if (typeof taskId !== 'string' || !/^TASK-C97-\d{3}$/.test(taskId)) {
+    refuse(taskId, 'invalid-scope', 'taskId must be an exact TASK-C97-009-style token');
+  }
+  for (const [k, v] of Object.entries({ baseCommit, sourceRoot, destinationRoot, sourceHead, destinationHead })) {
+    if (typeof v !== 'string' || v.length === 0) refuse(taskId, 'invalid-scope', `${k} must be a nonempty string`);
+  }
+  if (!Array.isArray(targetPaths) || targetPaths.length === 0) {
+    refuse(taskId, 'invalid-scope', 'targetPaths must be a nonempty array');
+  }
+  const seen = new Set();
+  for (const p of targetPaths) {
+    if (typeof p !== 'string' || p.length === 0) refuse(taskId, 'invalid-scope', 'targetPaths entries must be nonempty strings');
+    if (p.includes('\0')) refuse(taskId, 'invalid-scope', 'targetPaths entries must not contain NUL');
+    if (p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p)) refuse(taskId, 'invalid-scope', 'targetPaths must be repo-relative');
+    const parts = p.split('/');
+    if (parts.some((seg) => seg === '..' || seg === '.git' || seg === '')) {
+      refuse(taskId, 'invalid-scope', `target path has a disallowed component: ${JSON.stringify(p)}`);
+    }
+    if (seen.has(p)) refuse(taskId, 'invalid-scope', `duplicate target path: ${JSON.stringify(p)}`);
+    seen.add(p);
+  }
+  return { taskId, baseCommit, sourceRoot, destinationRoot, sourceHead, destinationHead, targetPaths };
+}
+
+// --- path helpers ------------------------------------------------------------
+
+const realPath = (p) => {
+  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+};
+// Resolve symlinks in the LONGEST EXISTING ancestor of a not-yet-created path,
+// then append the remaining segments. macOS `os.tmpdir()` (/var → /private/var)
+// makes a naive resolve() a different string from the realpath'd roots, which
+// would silently defeat the containment checks below.
+function resolveReal(p) {
+  const abs = path.resolve(p);
+  const root = path.parse(abs).root;
+  const parts = abs.slice(root.length).split(path.sep).filter(Boolean);
+  let cur = root;
+  let i = 0;
+  for (; i < parts.length; i += 1) {
+    const next = path.join(cur, parts[i]);
+    if (fs.existsSync(next)) cur = next; else break;
+  }
+  return path.join(realPath(cur), ...parts.slice(i));
+}
+const isInsideOrEqual = (child, parent) => {
+  const c = resolveReal(child);
+  const p = realPath(parent);
+  return c === p || c.startsWith(p + path.sep);
+};
+
+// --- main --------------------------------------------------------------------
+
+function main() {
+  const scope = readScope();
+  const { taskId, targetPaths } = scope;
+  const targets = new Set(targetPaths);
+
+  // Receipt authority (SPEC §7): outside the source worktree and outside the
+  // target set, and never an existing file (exclusive creation).
+  const receiptAbs = resolveReal(receiptPath);
+  if (fs.existsSync(receiptAbs)) refuse(taskId, 'receipt-exists', 'receipt path already exists');
+  // Resolve the source root early so the receipt containment check is exact.
+  const sourceRoot = realPath(scope.sourceRoot);
+  if (isInsideOrEqual(receiptAbs, sourceRoot)) {
+    refuse(taskId, 'receipt-in-source', 'receipt path is inside the source worktree');
+  }
+
+  // Roots must be real, registered, and distinct.
+  if (!fs.existsSync(sourceRoot)) refuse(taskId, 'invalid-scope', 'sourceRoot does not exist');
+  const destinationRoot = realPath(scope.destinationRoot);
+  if (!fs.existsSync(destinationRoot)) refuse(taskId, 'invalid-scope', 'destinationRoot does not exist');
+  if (sourceRoot === destinationRoot) refuse(taskId, 'same-root', 'source and destination roots are the same');
+
+  // Receipt must not be equal to, inside, or a directory-ancestor of any target
+  // path — nor share a target's directory, where landing writes (SPEC §7:
+  // "equal to/inside any scope target path"; a receipt dropped in a directory
+  // landing creates files in is not an authority location and could be
+  // clobbered). The recommended location is coordinator-owned, outside both.
+  const receiptRel = path.relative(destinationRoot, receiptAbs);
+  if (receiptRel && !receiptRel.startsWith('..') && !path.isAbsolute(receiptRel)) {
+    const relPosix = receiptRel.split(path.sep).join('/');
+    const receiptDir = path.posix.dirname(relPosix);
+    for (const t of targetPaths) {
+      if (relPosix === t
+        || relPosix.startsWith(`${t}/`)
+        || t.startsWith(`${relPosix}/`)
+        || path.posix.dirname(t) === receiptDir) {
+        refuse(taskId, 'receipt-in-target', 'receipt path is inside the target set');
+      }
+    }
+  }
+
+  // Same Git common repository (linked worktrees of one repo), distinct roots.
+  const commonSrc = gitText(sourceRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  const commonDst = gitText(destinationRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (commonSrc.status !== 0 || commonDst.status !== 0) {
+    refuse(taskId, 'not-a-repo', 'a root is not a Git worktree');
+  }
+  if (realPath(commonSrc.stdout.trim()) !== realPath(commonDst.stdout.trim())) {
+    refuse(taskId, 'other-repo', 'source and destination are not in the same Git common repository');
+  }
+
+  // Base commit must resolve and be an ancestor of BOTH worktree heads.
+  const baseResolved = gitText(sourceRoot, ['rev-parse', '--verify', '--quiet', `${scope.baseCommit}^{commit}`]);
+  if (baseResolved.status !== 0 || !baseResolved.stdout.trim()) {
+    refuse(taskId, 'invalid-base', 'baseCommit does not resolve to a commit');
+  }
+  const base = baseResolved.stdout.trim();
+  if (base !== scope.baseCommit) refuse(taskId, 'invalid-base', 'baseCommit must be the full resolved commit OID');
+
+  const srcHeadActual = gitText(sourceRoot, ['rev-parse', 'HEAD']);
+  const dstHeadActual = gitText(destinationRoot, ['rev-parse', 'HEAD']);
+  if (srcHeadActual.status !== 0 || dstHeadActual.status !== 0) {
+    refuse(taskId, 'head-drift', 'a worktree HEAD could not be resolved');
+  }
+  const srcHead = srcHeadActual.stdout.trim();
+  const dstHead = dstHeadActual.stdout.trim();
+  if (srcHead !== scope.sourceHead) refuse(taskId, 'head-drift', 'source HEAD does not match the scope');
+  if (dstHead !== scope.destinationHead) refuse(taskId, 'head-drift', 'destination HEAD does not match the scope');
+  for (const head of [srcHead, dstHead]) {
+    if (gitText(sourceRoot, ['merge-base', '--is-ancestor', base, head]).status !== 0) {
+      refuse(taskId, 'base-not-ancestor', 'baseCommit is not an ancestor of a worktree HEAD');
+    }
+  }
+
+  // No unmerged index on either side.
+  for (const root of [sourceRoot, destinationRoot]) {
+    const unmerged = gitText(root, ['ls-files', '-u']);
+    if (unmerged.status === 0 && unmerged.stdout.trim()) {
+      refuse(taskId, 'unmerged-index', 'a worktree has unmerged index entries');
+    }
+  }
+
+  // Snapshot the source's FINAL tree via an isolated, task-owned temp index.
+  // Never the real index; never a source patch command.
+  const tmpIndex = path.join(os.tmpdir(), `ukit-land-${process.pid}-${crypto.randomBytes(6).toString('hex')}.index`);
+  let snapshotTree;
+  try {
+    const env = { GIT_INDEX_FILE: tmpIndex };
+    for (const args of [['read-tree', 'HEAD'], ['add', '-A'], ['write-tree']]) {
+      const r = gitText(sourceRoot, args, env);
+      if (r.status !== 0) runtimeError(taskId, 'snapshot-failed', r.stderr.split('\n')[0]);
+      if (args[0] === 'write-tree') snapshotTree = r.stdout.trim();
+    }
+  } finally {
+    try { fs.rmSync(tmpIndex, { force: true }); } catch { /* absent */ }
+  }
+
+  // Source concurrency detection: the source HEAD/index must still match the
+  // fingerprint taken before the snapshot.
+  if (gitText(sourceRoot, ['rev-parse', 'HEAD']).stdout.trim() !== srcHead) {
+    refuse(taskId, 'source-drift', 'source HEAD changed during preflight');
+  }
+
+  // Deterministic delta: `--no-renames` makes rename = delete + add, so the
+  // changed-path set and the scope-equality check are exact.
+  const nameStatus = gitText(sourceRoot, ['diff', '--name-status', '-z', '--no-renames', base, snapshotTree]);
+  if (nameStatus.status !== 0) runtimeError(taskId, 'diff-failed', nameStatus.stderr.split('\n')[0]);
+  const deltaPaths = parseNameStatusZ(nameStatus.stdout);
+
+  // Authority: every delta path must be an approved target (no scope expansion).
+  for (const p of deltaPaths) {
+    if (!targets.has(p)) refuse(taskId, 'scope-drift', `out-of-scope change: ${JSON.stringify(p)}`);
+  }
+
+  // Symlink-ancestor traversal: no target path may have a symlink parent in the
+  // destination.
+  for (const t of targetPaths) {
+    const parts = t.split('/');
+    let cur = destinationRoot;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+      cur = path.join(cur, parts[i]);
+      try {
+        if (fs.lstatSync(cur).isSymbolicLink()) {
+          refuse(taskId, 'symlink-ancestor', 'a target path has a symlink ancestor in the destination');
+        }
+      } catch { break; /* ancestor does not exist yet — fine */ }
+    }
+  }
+
+  // Destination cleanliness (SPEC FR-M4-002): no tracked modification or staged
+  // change anywhere; no untracked file colliding with an old/new target path or
+  // living under a target directory. Unrelated untracked files are tolerated.
+  const toleratedUntracked = checkDestinationClean(destinationRoot, targetPaths, taskId);
+
+  // Build the exact binary patch and preflight the WHOLE thing before mutation.
+  const patch = gitBytes(sourceRoot, ['diff', '--binary', '--full-index', '--no-renames', base, snapshotTree]);
+  if (patch.status !== 0) runtimeError(taskId, 'diff-failed', String(patch.stderr).split('\n')[0]);
+  const patchBuf = patch.stdout;
+  const patchSha256 = crypto.createHash('sha256').update(patchBuf).digest('hex');
+  const scopeSha256 = crypto.createHash('sha256').update(fs.readFileSync(scopePath)).digest('hex');
+
+  // A verified empty delta is a landed no-op: identity check only, no apply.
+  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);
+  }
+
+  const tmpPatch = path.join(os.tmpdir(), `ukit-land-${process.pid}-${crypto.randomBytes(6).toString('hex')}.patch`);
+  fs.writeFileSync(tmpPatch, patchBuf);
+  try {
+    const check = gitText(destinationRoot, ['apply', '--check', '--binary', tmpPatch]);
+    if (check.status !== 0) {
+      refuse(taskId, 'apply-conflict', check.stderr.split('\n')[0] || 'patch does not apply cleanly');
+    }
+
+    // Apply. A failure here is a runtime error (exit 1) — never a success, and
+    // the source is preserved; only touched preimages are rolled back.
+    const apply = gitText(destinationRoot, ['apply', '--binary', tmpPatch]);
+    if (apply.status !== 0) {
+      rollback(destinationRoot, tmpPatch);
+      runtimeError(taskId, 'apply-failed', apply.stderr.split('\n')[0] || 'git apply failed');
+    }
+  } finally {
+    try { fs.rmSync(tmpPatch, { force: true }); } catch { /* absent */ }
+  }
+
+  // Verify the landed result path-scoped: every delta path's blob in the
+  // destination must equal the source snapshot's, and no unexpected delta path
+  // may appear beyond the approved delta (tolerated untracked files excluded).
+  const dstTree = computeWorktreeTree(destinationRoot);
+  const verified = gitText(destinationRoot, ['diff', '--name-status', '-z', '--no-renames', dstHead, dstTree]);
+  const verifiedPaths = parseNameStatusZ(verified.stdout);
+  const deltaSet = new Set(deltaPaths);
+  const extra = verifiedPaths.filter((p) => !deltaSet.has(p) && !toleratedUntracked.has(p));
+  if (extra.length > 0) {
+    runtimeError(taskId, 'verify-failed', `unexpected landed path: ${JSON.stringify(extra[0])}`);
+  }
+  for (const p of deltaPaths) {
+    const expectedEntry = treeEntry(sourceRoot, snapshotTree, p);
+    const actualEntry = treeEntry(destinationRoot, dstTree, p);
+    if (expectedEntry !== actualEntry) {
+      runtimeError(taskId, 'verify-failed', `blob mismatch at ${JSON.stringify(p)}`);
+    }
+  }
+
+  writeReceipt(receiptAbs, taskId, base, sourceRoot, destinationRoot, srcHead, dstHead, snapshotTree, dstTree, patchSha256, scopeSha256, deltaPaths);
+  emit('landed', taskId, 'ok', deltaPaths, receiptAbs);
+  process.exit(0);
+}
+
+// --- helpers -----------------------------------------------------------------
+
+function parseNameStatusZ(raw) {
+  const parts = raw.split('\0');
+  const out = [];
+  for (let i = 0; i < parts.length; i += 1) {
+    const status = parts[i];
+    if (!status) continue;
+    const p = parts[i + 1];
+    if (p === undefined) break;
+    out.push(p);
+    i += 1;
+  }
+  return out;
+}
+
+function branchOf(root) {
+  const r = gitText(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+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']]) {
+      const r = gitText(root, args, env);
+      if (r.status !== 0) runtimeError(null, 'verify-failed', r.stderr.split('\n')[0]);
+    }
+    const t = gitText(root, ['write-tree'], env);
+    if (t.status !== 0) runtimeError(null, 'verify-failed', t.stderr.split('\n')[0]);
+    return t.stdout.trim();
+  } finally {
+    try { fs.rmSync(idx, { force: true }); } catch { /* absent */ }
+  }
+}
+
+function rollback(root, patchPath) {
+  // Restore only the preimages this patch touched; unrelated destination
+  // content is never discarded.
+  gitText(root, ['apply', '--reverse', '--binary', patchPath]);
+}
+
+// blob+mode of `path` in `treeish` — null when the path is absent (a deletion).
+function treeEntry(root, treeish, p) {
+  const r = gitText(root, ['ls-tree', '-z', treeish, '--', p]);
+  if (r.status !== 0 || !r.stdout) return null;
+  // Format: "<mode> <type> <object>\t<path>\0"
+  const row = r.stdout.split('\0').find((x) => x.length > 0);
+  if (!row) return null;
+  const [meta] = row.split('\t');
+  const [mode, , object] = meta.split(' ');
+  return `${mode}:${object}`;
+}
+
+function writeReceipt(absPath, taskId, base, sourceRoot, destinationRoot, srcHead, dstHead, snapshotTree, resultTree, patchSha256, scopeSha256, changedPaths) {
+  const receipt = {
+    schemaVersion: 1,
+    taskId,
+    baseCommit: base,
+    sourceRoot,
+    destinationRoot,
+    sourceBranch: branchOf(sourceRoot),
+    sourceHead: srcHead,
+    destinationHeadBefore: dstHead,
+    sourceSnapshotTree: snapshotTree,
+    resultTree,
+    patchSha256,
+    scopeSha256,
+    changedPaths: changedPaths.slice(),
+    createdAt: new Date().toISOString(),
+    status: 'landed',
+  };
+  try {
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx' });
+  } catch (e) {
+    // Apply succeeded but the receipt could not be written: report error, keep
+    // the source, identify landed-but-unreceipted recovery. No cleanup.
+    runtimeError(taskId, 'receipt-write-failed', e.code ?? e.message);
+  }
+}
+
+function checkDestinationClean(destinationRoot, targetPaths, taskId) {
+  const st = gitText(destinationRoot, ['status', '--porcelain', '-z']);
+  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}/`));
+  const tolerated = new Set();
+
+  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);
+    } else {
+      // Any tracked modification or staged change anywhere refuses.
+      refuse(taskId, 'destination-dirty', `tracked modification at ${JSON.stringify(p)}`);
+    }
+  }
+  return tolerated;
+}
+
+// Parse `git status --porcelain -z`: NUL-separated entries, each "XY <path>".
+// A rename/copy entry is followed by a second NUL-separated origin path.
+function parsePorcelainZ(raw) {
+  const parts = raw.split('\0');
+  const out = [];
+  for (let i = 0; i < parts.length; i += 1) {
+    const entry = parts[i];
+    if (!entry) continue;
+    const xy = entry.slice(0, 2);
+    let p = entry.slice(3);
+    // `-z` disables quoting, so paths are raw bytes — newline/space/backslash preserved.
+    if (xy[0] === 'R' || xy[0] === 'C') i += 1; // skip the rename origin
+    out.push({ xy, path: p });
+  }
+  return out;
+}
+
+main();

package/template_project/.claude/ukit/index/stale-spec-check.mjs

@@ -99,7 +99,54 @@ export async function checkStaleSpec({ projectRoot = process.cwd(), payload = {}
   const toolName = getToolName(payload);
   const filePath = getFilePath(payload);
   if (!filePath) return { status: 'skipped', reason: 'no-file' };
-  const resolved = resolveProjectFile(projectRoot, filePath);
+  // C97 (FR-001): classify target containment at the checker boundary. The
+  // shared resolver THROWS "Path escapes project root" on containment misses
+  // and its contract must not change, so classify lexically here — before any
+  // fs probe of the target. An absolute path strictly outside the project is
+  // out of scope for this project-only check: scoped skip, NOT permission to
+  // write (other gates keep ownership, and the target is never read). Relative
+  // escapes and root-as-file get a structured block instead of an unhandled
+  // crash that killed the whole fail-closed chain. Lexical only — symlink
+  // expansion must never widen authority.
+  // Fix1 (review round 1): containment is SEGMENT-aware. String prefix
+  // matching (`startsWith('..')`) also caught internal dot-prefixed names
+  // whose first path segment starts with `..` (e.g. a project-root-level
+  // `..internal.mjs`), scoping real in-project files out of the check. An
+  // escape is a `..` PATH SEGMENT — the whole relative path or its first
+  // segment — never a leading-dot filename.
+  const root = path.resolve(projectRoot || process.cwd());
+  const rawPath = String(filePath).trim();
+  const candidate = path.isAbsolute(rawPath) ? path.resolve(rawPath) : path.resolve(root, rawPath);
+  const candidateRelative = path.relative(root, candidate);
+  const escapesRoot = candidateRelative === '..'
+    || candidateRelative.startsWith(`..${path.sep}`)
+    || path.isAbsolute(candidateRelative);
+  if (!candidateRelative || escapesRoot) {
+    if (!path.isAbsolute(rawPath) || !candidateRelative) {
+      return {
+        status: 'blocked',
+        code: 'invalid-project-target',
+        message: `BLOCKED: target path '${filePath}' resolves outside the project root (invalid-project-target) — relative traversal and the project root itself are refused. Choose a path inside the project.`,
+        file: rawPath,
+      };
+    }
+    return { status: 'skipped', reason: 'outside-project', file: rawPath };
+  }
+  // The unchanged strict resolver still refuses first-segment dot-names
+  // (its own `startsWith('..')` contract). Keep that refusal — it is the
+  // resolver's safety contract — but surface it as the structured block
+  // instead of the unhandled-crash class this checker used to die from.
+  let resolved;
+  try {
+    resolved = resolveProjectFile(projectRoot, filePath);
+  } catch (error) {
+    return {
+      status: 'blocked',
+      code: 'invalid-project-target',
+      message: `BLOCKED: project resolver refused target '${filePath}' (invalid-project-target): ${error?.message || error}. Use a normal in-project path whose segments do not start with '..'.`,
+      file: rawPath,
+    };
+  }
   const exists = await withTransientFsRetry(
     () => probeExists(resolved.absolute),
     { deadlineMs: TRANSIENT_READ_DEADLINE_MS },