@ngockhoale/ukit 3.3.2 → 3.4.0

package/template_project/.claude/ukit/index/verification-map.mjs

@@ -0,0 +1,403 @@
+// verification-map.mjs — verification-map table + recipe resolution
+// (C85 TASK-014, BL-014 / SPEC FR-002 / ARCH §Verification Map).
+//
+// Installed mirror of src/index/verificationMap.js. The map is DATA:
+// template_user/playbooks/verification-map.json carries one
+// launch/doctor/drive/expected/evidence/cleanup row per playbook work group
+// (verbatim from ARCH §Verification Map) plus a per-artifact-class recipe table
+// (ui|cli|docs|config). This module is the single query surface for both shell
+// consumers (verification-guard.sh imports this file and resolves recipes
+// without parsing prose) and node consumers (stop-coordinator.mjs completion
+// policy, ukit doctor's recipe-vs-package.json check).
+//
+// Resolution order mirrors the playbook registry:
+//   <projectRoot>/.ukit/playbooks/verification-map.json
+//   <homeDir>/.ukit/playbooks/verification-map.json
+//   packaged template_user/playbooks/verification-map.json (builtin)
+// The first file that parses AND validates wins; a malformed higher tier cannot
+// shadow a valid lower tier. Every miss/malformed case fails closed to
+// map=null — consumers fall back to pre-map behavior, never fabricated checks.
+//
+// Parity is locked by tests/consistency/verificationMapParity.test.js.
+
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MAP_FILENAME = 'verification-map.json';
+// The mirror is four dirs below the project root — '../../../..' lands on
+// the checkout root so the repo resolves the same template_user tree; on a
+// real installed project the walk lands outside the project (no
+// template_user dir), ENOENT skips the tier, and the ~/.ukit seed is the
+// effective builtin. The canonical twin (src/index/) walks two dirs.
+// Install-aware callers may pass `builtinPath` explicitly.
+const PACKAGE_BUILTIN_MAP_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..', '..', '..', '..',
+  'template_user', 'playbooks', MAP_FILENAME,
+);
+
+export const ARTIFACT_CLASSES = Object.freeze(['ui', 'cli', 'docs', 'config']);
+const ARTIFACT_CLASS_SET = new Set(ARTIFACT_CLASSES);
+
+const PLAYBOOK_ROW_KEYS = ['launch', 'doctor', 'drive', 'expected', 'evidence', 'cleanup'];
+
+// ─── Artifact classification ────────────────────────────────────────────────
+// The artifact class comes from the files a change actually touched — the same
+// git --porcelain path list verification-guard.sh already computes. Priority is
+// deliberate: any UI file makes the diff `ui` (the ARCH falsifying bar blocks an
+// unverified UI change), explicit CLI surfaces next, and docs/config only when
+// the whole diff is docs/config. A diff with no signal classifies `null` —
+// `recipeForArtifact` then returns null and every consumer keeps the pre-map
+// behavior (SPEC §10: unknown class → no recipe → unchanged).
+
+const UI_PATH_RE = /(^|\/)(components?|pages?|views?|screens?|layouts?|widgets?)\//i;
+const UI_EXT_RE = /\.(jsx|tsx|vue|svelte|css|scss|sass|less|html|styl)$/i;
+const DOCS_PATH_RE = /(^|\/)(docs?|wiki)\//i;
+const DOCS_EXT_RE = /\.(md|mdx|rst|adoc|txt)$/i;
+const CONFIG_BASENAME_RE = /^(?:[^/]*\.(json|ya?ml|toml|ini|env|cfg|conf)|\.?[A-Za-z][\w.-]*(rc|file|config|ignore|rc\.js|rc\.cjs|rc\.mjs|rc\.json|rc\.ya?ml)|dockerfile|compose[^/]*\.ya?ml|makefile|justfile)$/i;
+const CLI_PATH_RE = /(^|\/)(bin|cli|cmd|commands)\//i;
+const CLI_EXT_RE = /\.(sh|bash|zsh|ps1|bat|cmd)$/i;
+const LOCKFILE_RE = /(^|\/)(?:package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|composer\.lock|gemfile\.lock|poetry\.lock|cargo\.lock|go\.sum)$/i;
+// Runtime-produced files are never the artifact being verified: UKit internal
+// storage (.ukit/**) and the router's own state files appear in every real
+// diff, and counting them would poison the whole-set docs/config rules.
+const INTERNAL_STATE_RE = /(^|\/)\.ukit\/|(^|\/)(?:skill-router-state|route-cache|verification-progress|decisions)\.json$|(^|\/)decisions\.tsv$/i;
+/**
+ * Classify a change's artifact class from the set of paths it touched.
+ * `changedPaths` are repo-relative paths (git --porcelain entries already have
+ * their status prefix stripped by the caller). Returns one of ARTIFACT_CLASSES
+ * or null for "no classifiable signal" (pre-map behavior everywhere downstream).
+ */
+
+// `git status --porcelain` C-quotes paths containing spaces/non-ASCII
+// ("src/My Widget.jsx") — the trailing quote must go before the class regexes
+// run or the entry silently misclassifies to null and the recipe lane skips
+// (fail-open). `-z` callers never produce quotes; this is a defensive net for
+// the porcelain form. Octal escapes (\303\244) are not valid JSON — the
+// fallback keeps the inner text, still classified by extension/dir, never
+// dropped.
+function unquotePorcelainPath(entry) {
+  if (entry.length >= 2 && entry.startsWith('"') && entry.endsWith('"')) {
+    const inner = entry.slice(1, -1);
+    try {
+      const parsed = JSON.parse(entry);
+      if (typeof parsed === 'string') return parsed;
+    } catch { /* octal escapes are not valid JSON — keep the inner text */ }
+    return inner;
+  }
+  return entry;
+}
+
+export function classifyArtifactClass(changedPaths = []) {
+  const paths = (Array.isArray(changedPaths) ? changedPaths : [])
+    .map((entry) => String(entry || '').trim())
+    .filter(Boolean)
+    // Rename entries carry "old -> new"; the destination is the changed artifact.
+    .map((entry) => entry.split(' -> ').pop())
+    .map(unquotePorcelainPath)
+    .filter((entry) => !INTERNAL_STATE_RE.test(entry));
+  if (paths.length === 0) return null;
+  // Lockfile-only diffs carry no verification recipe — they are dependency
+  // bookkeeping, verified by the next real change that runs the project.
+  if (paths.every((entry) => LOCKFILE_RE.test(entry))) return null;
+  if (paths.some((entry) => UI_PATH_RE.test(entry) || UI_EXT_RE.test(entry))) return 'ui';
+  if (paths.some((entry) => CLI_PATH_RE.test(entry) || CLI_EXT_RE.test(entry))) return 'cli';
+  if (paths.every((entry) => DOCS_PATH_RE.test(entry) || DOCS_EXT_RE.test(entry))) return 'docs';
+  if (paths.every((entry) => CONFIG_BASENAME_RE.test(path.basename(entry)))) return 'config';
+  return null;
+}
+
+// ─── Map loading ────────────────────────────────────────────────────────────
+
+export function verificationMapCandidatePaths({ projectRoot = null, homeDir = null, builtinPath = null } = {}) {
+  const candidates = [];
+  if (projectRoot) {
+    candidates.push({ path: path.join(projectRoot, '.ukit', 'playbooks', MAP_FILENAME), source: 'project' });
+  }
+  if (homeDir !== null) {
+    const base = homeDir || os.homedir();
+    candidates.push({ path: path.join(base, '.ukit', 'playbooks', MAP_FILENAME), source: 'user' });
+  }
+  candidates.push({ path: builtinPath ?? PACKAGE_BUILTIN_MAP_PATH, source: 'builtin' });
+  return candidates;
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Shape check. A valid map needs `version: 1`, at least one playbook row
+ * carrying every required recipe column, and an `artifactClasses` table whose
+ * rows are objects. Returns { ok, reason } — `reason` is a bounded code the
+// doctor check prints verbatim (never the raw parse text on the report line).
+ */
+export function validateVerificationMap(map) {
+  if (!isPlainObject(map)) return { ok: false, reason: 'not-an-object' };
+  if (map.version !== 1) return { ok: false, reason: 'unsupported-version' };
+  if (!isPlainObject(map.playbooks) || Object.keys(map.playbooks).length === 0) {
+    return { ok: false, reason: 'missing-playbooks' };
+  }
+  for (const [id, row] of Object.entries(map.playbooks)) {
+    if (!isPlainObject(row)) return { ok: false, reason: `playbook-row-not-object:${id}` };
+    for (const key of PLAYBOOK_ROW_KEYS) {
+      if (key === 'evidence') {
+        if (!Array.isArray(row.evidence) || row.evidence.length === 0
+          || !row.evidence.every((entry) => typeof entry === 'string' && entry.trim())) {
+          return { ok: false, reason: `playbook-row-missing-evidence:${id}` };
+        }
+      } else if (typeof row[key] !== 'string' || !row[key].trim()) {
+        return { ok: false, reason: `playbook-row-missing-key:${id}.${key}` };
+      }
+    }
+  }
+  if (!isPlainObject(map.artifactClasses)) return { ok: false, reason: 'missing-artifact-classes' };
+  for (const [name, row] of Object.entries(map.artifactClasses)) {
+    if (!ARTIFACT_CLASS_SET.has(name)) return { ok: false, reason: `unknown-artifact-class:${name}` };
+    if (!isPlainObject(row)) return { ok: false, reason: `artifact-row-not-object:${name}` };
+    if (row.evidenceRequired !== undefined
+      && (!Array.isArray(row.evidenceRequired)
+        || !row.evidenceRequired.every((entry) => typeof entry === 'string' && entry.trim()))) {
+      return { ok: false, reason: `artifact-row-bad-evidence:${name}` };
+    }
+  }
+  return { ok: true, reason: null };
+}
+
+/**
+ * Inspect (never throws): walk the candidate tiers, return the first valid map
+ * plus its provenance. On total failure `map` is null and `reason` says why —
+ * `no-map` (nothing readable at any tier) or a validation reason from the
+ * last readable-but-invalid candidate. Consumers treat map===null as
+// "pre-map behavior", the fail-closed contract of ARCH §Failure Modes.
+ */
+export async function inspectVerificationMap({ projectRoot = null, homeDir = null, builtinPath = null } = {}) {
+  let lastInvalidReason = 'no-map';
+  for (const candidate of verificationMapCandidatePaths({ projectRoot, homeDir, builtinPath })) {
+    let raw;
+    try {
+      raw = await fs.readFile(candidate.path, 'utf8');
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      lastInvalidReason = `invalid-json:${candidate.source}`;
+      continue;
+    }
+    const verdict = validateVerificationMap(parsed);
+    if (!verdict.ok) {
+      lastInvalidReason = `${verdict.reason}@${candidate.source}`;
+      continue;
+    }
+    return { map: parsed, path: candidate.path, source: candidate.source, reason: null };
+  }
+  return { map: null, path: null, source: null, reason: lastInvalidReason };
+}
+
+/**
+ * loadVerificationMap(root?) → VerificationMap|null.
+ * `root` is the project root (project-tier map lookup); pass an options object
+ * `{projectRoot, homeDir, builtinPath}` to control every tier. Fails closed:
+ * missing/malformed map → null.
+ */
+export async function loadVerificationMap(rootOrOptions = null) {
+  const options = isPlainObject(rootOrOptions)
+    ? rootOrOptions
+    : { projectRoot: rootOrOptions || null };
+  const { map } = await inspectVerificationMap(options);
+  return map;
+}
+
+// ─── Recipe resolution ──────────────────────────────────────────────────────
+
+function normalizeArtifactClass(artifactClass) {
+  const normalized = String(artifactClass || '').trim().toLowerCase();
+  return ARTIFACT_CLASS_SET.has(normalized) ? normalized : null;
+}
+
+/**
+ * recipeForArtifact({playbookId, artifactClass, map?}) → recipe | null.
+ *
+ * The resolved recipe is the artifact-class row merged with the routed
+ * playbook row (for observability — the class row is what gates):
+ *   { playbookId, artifactClass, check, harness?, fallback?, evidenceRequired[],
+ *     playbook: {launch,doctor,drive,expected,evidence[],cleanup}|null }
+ *
+ * - unknown/missing `artifactClass` → null (pre-map behavior, SPEC §10);
+ * - `map` omitted → loaded on demand (project tier under `projectRoot`);
+ * - map===null / missing class row → null;
+ * - unknown/absent `playbookId` → `playbook: null`, the class row still resolves
+ *   (recipes key on the artifact, not the route).
+ */
+export async function recipeForArtifact({
+  playbookId = null,
+  artifactClass = null,
+  map: mapOption,
+  projectRoot = null,
+} = {}) {
+  const cls = normalizeArtifactClass(artifactClass);
+  if (!cls) return null;
+  const map = mapOption !== undefined ? mapOption : await loadVerificationMap(projectRoot);
+  if (!isPlainObject(map)) return null;
+  const classRow = map.artifactClasses?.[cls];
+  if (!isPlainObject(classRow)) return null;
+
+  const playbookRow = (() => {
+    const id = String(playbookId || '').trim();
+    if (!id) return null;
+    const row = map.playbooks?.[id];
+    if (!isPlainObject(row)) return null;
+    const shaped = {};
+    for (const key of PLAYBOOK_ROW_KEYS) {
+      shaped[key] = key === 'evidence'
+        ? (Array.isArray(row.evidence) ? [...row.evidence] : [])
+        : (typeof row[key] === 'string' ? row[key] : '');
+    }
+    return shaped;
+  })();
+
+  const harness = isPlainObject(classRow.harness) && typeof classRow.harness.packageScript === 'string'
+    ? { packageScript: classRow.harness.packageScript }
+    : null;
+
+  return {
+    playbookId: playbookRow ? String(playbookId).trim() : null,
+    artifactClass: cls,
+    name: typeof classRow.name === 'string' ? classRow.name : cls,
+    check: typeof classRow.check === 'string' && classRow.check.trim() ? classRow.check : null,
+    harness,
+    fallback: typeof classRow.fallback === 'string' && classRow.fallback.trim() ? classRow.fallback.trim() : null,
+    evidenceRequired: Array.isArray(classRow.evidenceRequired)
+      ? classRow.evidenceRequired.filter((entry) => typeof entry === 'string' && entry.trim())
+      : [],
+    playbook: playbookRow,
+  };
+}
+
+// ─── Receipt satisfaction ───────────────────────────────────────────────────
+// Shared by the stop gate (execution-ledger.mjs requires evidence) and the
+// guard's advisory findings — the ledger carries the same semantics pinned by
+// tests/consistency/receiptSatisfactionParity.test.js (runtime/ cannot import
+// index/ — partial installs break — so parity is enforced by test, not a
+// shared import). A required class token may carry `|` alternatives
+// (`render-observation|io-case` — the ARCH evidence cell verbatim): any ONE
+// alternative satisfies it. A class is satisfied when the ledger carries a
+// receipt whose attested `evidence.class` matches an alternative
+// (UKIT_EVIDENCE=class=…;surface=… — direct proof the guard may not have
+// observed), or when the playbook-finding bank records the class — whole
+// token or one alternative — as status 'satisfied'. Findings are latest-wins:
+// ledger.playbookFindings (latest per class, banked outside the evictable
+// receipt window) governs — a later 'missing' finding revokes an earlier
+// 'satisfied' one, and a satisfied class survives receipt eviction via the
+// bank. A failed attestation never satisfies — a failed run that happened to
+// attest a class is not proof of the class.
+
+export function receiptEvidenceSatisfied(requiredClass, ledger = {}) {
+  const token = String(requiredClass || '').trim();
+  const alternatives = token
+    .split('|')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (alternatives.length === 0) return false;
+  const matchesClass = (value) => {
+    const cls = typeof value === 'string' ? value.trim() : '';
+    return cls === token || alternatives.includes(cls);
+  };
+  // The banked latest-per-class status governs the receipt window; several
+  // banked keys can match one anyOf token, so the newest entry wins. A
+  // playbook-finding receipt folds into the bank regardless of its success
+  // flag — the receipt scan below mirrors that.
+  let bankedTs = -1;
+  let bankedStatus = null;
+  const bank = ledger?.playbookFindings;
+  if (bank && typeof bank === 'object') {
+    for (const [key, entry] of Object.entries(bank)) {
+      if (!matchesClass(key)) continue;
+      const ts = typeof entry?.ts === 'number' ? entry.ts : 0;
+      if (ts >= bankedTs) {
+        bankedTs = ts;
+        bankedStatus = typeof entry?.status === 'string' ? entry.status : null;
+      }
+    }
+  }
+  const receipts = Array.isArray(ledger?.receipts) ? ledger.receipts : [];
+  let attested = false;
+  let scannedStatus = null;
+  for (const receipt of receipts) {
+    if (!receipt || typeof receipt !== 'object') continue;
+    if (receipt.kind === 'playbook-finding') {
+      if (matchesClass(receipt.class) && typeof receipt.status === 'string') {
+        scannedStatus = receipt.status; // chronological — last write wins
+      }
+      continue;
+    }
+    if (receipt.success === false) continue;
+    const cls = receipt?.evidence?.class;
+    if (typeof cls === 'string' && alternatives.includes(cls.trim())) attested = true;
+  }
+  if (attested) return true;
+  const findingStatus = bankedTs >= 0 ? bankedStatus : scannedStatus;
+  return findingStatus === 'satisfied';
+}
+
+// ─── Doctor recipe check ────────────────────────────────────────────────────
+/**
+ * doctorRecipeCheck({map, packageJsonScripts}) → { checked, missing[], mapAbsent }.
+ *
+ * ARCH §Failure Modes "verification recipe demands absent harness": a recipe
+ * whose named package.json script is absent degrades to a capability-negotiated
+ * FALLBACK RECEIPT — the returned `fallback` text is the receipt spec to print,
+ * never a fabricated command. `map===null` (absent/malformed) reports
+ * mapAbsent with zero missing entries — a broken map is itself a doctor warning
+// (the caller composes the row), not silent data.
+ */
+export function doctorRecipeCheck({ map = null, packageJsonScripts = {} } = {}) {
+  if (!isPlainObject(map)) {
+    return { checked: 0, missing: [], mapAbsent: true };
+  }
+  const scripts = isPlainObject(packageJsonScripts) ? packageJsonScripts : {};
+  const missing = [];
+  let checked = 0;
+  for (const [className, row] of Object.entries(map.artifactClasses || {})) {
+    const script = row?.harness?.packageScript;
+    if (typeof script !== 'string' || !script.trim()) continue;
+    checked += 1;
+    if (!Object.hasOwn(scripts, script)) {
+      missing.push({
+        artifactClass: className,
+        script,
+        check: typeof row.check === 'string' ? row.check : null,
+        fallback: typeof row.fallback === 'string' ? row.fallback : null,
+      });
+    }
+  }
+  return { checked, missing, mapAbsent: false };
+}
+
+// Sync layer for hook runtimes that evaluate inside a deadline (the guard's
+// git-porcelain path is already synchronous there). Same fail-closed contract.
+export function loadVerificationMapSync(rootOrOptions = null) {
+  const options = isPlainObject(rootOrOptions)
+    ? rootOrOptions
+    : { projectRoot: rootOrOptions || null };
+  const { projectRoot = null, homeDir = null, builtinPath = null } = options;
+  for (const candidate of verificationMapCandidatePaths({ projectRoot, homeDir, builtinPath })) {
+    let raw;
+    try {
+      raw = fsSync.readFileSync(candidate.path, 'utf8');
+    } catch {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (validateVerificationMap(parsed).ok) return parsed;
+    } catch {}
+  }
+  return null;
+}

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

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * worktree-sweep.mjs — safety-gated worktree cleanup (C88 TASK-C88-007,
+ * CENSUS PB-U22, SPEC FR-007).
+ *
+ * Enumerate → classify → gate → remove only classified-safe entries. Dry-run
+ * is the default and mutates nothing; `--apply` runs `git worktree remove`
+ * exclusively on entries classified `safe`. Never a blanket sweep — every
+ * skipped entry keeps a named verdict.
+ *
+ * Classification (in priority order, first match wins):
+ *   safe   — prunable/stale worktree (missing dir or unborn branch) that is
+ *            clean, OR branch fully merged into the default branch with zero
+ *            commits ahead, no uncommitted work, no active run
+ *   skip-locked        — porcelain `locked` flag (a human locked it)
+ *   skip-detached-head — detached HEAD (nothing merges into anything)
+ *   skip-dirty         — `git -C <wt> status --porcelain` non-empty or
+ *                        unreadable (unknown state is never removable)
+ *   skip-active        — resumable-run records present (.ukit/storage/runs/)
+ *                        OR docs/AI_HANDOFF/RUN.md phase not done/blocked,
+ *                        OR the branch has commits not merged into default
+ *
+ * CLI: node worktree-sweep.mjs [--apply] [--root <dir>]
+ * exit 0 on a successful report/apply (even when nothing is removable);
+ * non-zero only on invocation error (bad flag, not-a-repo, git spawn
+ * failure). A failed `worktree remove` is reported per-entry, not fatal.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// Same discipline as provision-worktree.mjs (BUG-C21-08): every git call
+// carries a bounded timeout — a wedged git must never block forever.
+const GIT_CALL_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.UKIT_SWEEP_GIT_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 15000;
+})();
+
+function fail(msg) {
+  process.stderr.write(`worktree-sweep: ${msg}\n`);
+  process.exit(1);
+}
+
+function git(root, args) {
+  const res = spawnSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    timeout: GIT_CALL_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+  });
+  if (res.error) {
+    fail(`git ${args[0]} failed to run: ${res.error.message ?? res.error}`);
+  }
+  return res;
+}
+
+// --- args ------------------------------------------------------------------
+const args = process.argv.slice(2);
+let apply = false;
+let root = null;
+for (let i = 0; i < args.length; i += 1) {
+  const a = args[i];
+  if (a === '--apply') apply = true;
+  else if (a === '--root') { root = args[++i]; if (root === undefined) fail('missing value for --root'); }
+  else fail(`unknown flag: ${a}`);
+}
+root = path.resolve(root ?? process.cwd());
+
+// --- enumerate --------------------------------------------------------------
+const inside = git(root, ['rev-parse', '--is-inside-work-tree']);
+if (inside.status !== 0 || !/^true\b/.test(inside.stdout.trim())) {
+  fail(`not a git repository: ${root}`);
+}
+
+const list = git(root, ['worktree', 'list', '--porcelain']);
+if (list.status !== 0) fail(`git worktree list failed: ${list.stderr.trim()}`);
+
+// Parse porcelain records: `worktree <path>` starts a block; `HEAD`, `branch`,
+// `locked`, `prunable`, `detached`, `bare` follow.
+const worktrees = [];
+let cur = null;
+for (const line of list.stdout.split('\n')) {
+  if (line.startsWith('worktree ')) {
+    if (cur) worktrees.push(cur);
+    cur = { path: line.slice('worktree '.length), branch: null, detached: false, locked: false, prunable: false, bare: false };
+  } else if (cur) {
+    if (line.startsWith('branch ')) cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+    else if (line === 'detached') cur.detached = true;
+    else if (line.startsWith('locked')) cur.locked = true;
+    else if (line.startsWith('prunable')) cur.prunable = true;
+    else if (line === 'bare') cur.bare = true;
+  }
+}
+if (cur) worktrees.push(cur);
+
+// The main worktree is always the first record — it is the checkout running
+// this sweep and is never a removal candidate.
+const main = worktrees.shift();
+const candidates = worktrees;
+
+// Default branch: prefer remote HEAD, then local main/master, then the main
+// worktree's own checked-out branch.
+function resolveDefaultBranch() {
+  const symref = git(root, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']);
+  if (symref.status === 0 && symref.stdout.trim()) {
+    return symref.stdout.trim().replace(/^origin\//, '');
+  }
+  for (const name of ['main', 'master']) {
+    if (git(root, ['rev-parse', '--verify', '--quiet', `refs/heads/${name}`]).status === 0) return name;
+  }
+  return main && main.branch ? main.branch : null;
+}
+const defaultBranch = resolveDefaultBranch();
+const mergedSet = new Set();
+if (defaultBranch) {
+  const merged = git(root, ['branch', '--merged', defaultBranch, '--format=%(refname:short)']);
+  if (merged.status === 0) {
+    for (const b of merged.stdout.split('\n').map((s) => s.trim()).filter(Boolean)) mergedSet.add(b);
+  }
+}
+
+// --- classify ---------------------------------------------------------------
+function isDirty(wtPath) {
+  const res = git(wtPath, ['status', '--porcelain']);
+  // Unreadable status → treat as dirty: unknown state is never removable.
+  if (res.status !== 0) return true;
+  return res.stdout.trim().length > 0;
+}
+
+function hasActiveRun(wtPath) {
+  // A suspended/in-flight resumable record (any .ukit/storage/runs/*.json)
+  // marks the worktree as carrying an active run.
+  try {
+    const runsDir = path.join(wtPath, '.ukit', 'storage', 'runs');
+    if (fs.statSync(runsDir).isDirectory()
+      && fs.readdirSync(runsDir).some((f) => f.endsWith('.json'))) {
+      return true;
+    }
+  } catch { /* absent */ }
+  // An AI_HANDOFF cursor whose phase is not done/blocked marks an in-flight
+  // handoff run in that worktree.
+  try {
+    const raw = fs.readFileSync(path.join(wtPath, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    const m = raw.match(/^Phase:\s*(\S+)/m);
+    if (m && m[1] !== 'done' && m[1] !== 'blocked') return true;
+  } catch { /* no cursor */ }
+  return false;
+}
+
+function classify(wt) {
+  if (wt.locked) return 'skip-locked';
+  if (wt.prunable || !fs.existsSync(wt.path)) {
+    // Stale: the checkout directory is already gone — clean by definition.
+    return 'safe';
+  }
+  if (wt.detached || !wt.branch) return 'skip-detached-head';
+  if (isDirty(wt.path)) return 'skip-dirty';
+  if (hasActiveRun(wt.path)) return 'skip-active';
+  const branchExists = git(root, ['rev-parse', '--verify', '--quiet', `refs/heads/${wt.branch}`]).status === 0;
+  if (!branchExists) return 'safe'; // stale: branch gone/unborn, and clean
+  if (mergedSet.has(wt.branch)) {
+    // `git branch --merged` lists tip-merged branches; zero commits ahead is
+    // implied — a merged tip IS zero-ahead. Double-check cheaply.
+    const ahead = git(root, ['rev-list', '--count', `${defaultBranch}..${wt.branch}`]);
+    if (ahead.status === 0 && Number(ahead.stdout.trim()) === 0) return 'safe';
+  }
+  return 'skip-active'; // branch carries unmerged work — a run may resume it
+}
+
+// --- report + apply ---------------------------------------------------------
+const results = candidates.map((wt) => ({ ...wt, verdict: classify(wt) }));
+
+const mode = apply ? 'apply' : 'dry-run';
+console.log(`worktree-sweep (${mode}) — root: ${root}`);
+console.log(`default branch: ${defaultBranch ?? '(unresolved)'}`);
+if (results.length === 0) {
+  console.log('no removable worktrees: nothing to do');
+}
+for (const r of results) {
+  let line = `${r.path}  branch=${r.branch ?? '(none)'}  verdict=${r.verdict}`;
+  if (apply && r.verdict === 'safe') {
+    const rm = spawnSync('git', ['-C', root, 'worktree', 'remove', r.path], {
+      encoding: 'utf8',
+      timeout: GIT_CALL_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
+    });
+    if (rm.status === 0) line += '  removed';
+    else line += `  remove-failed: ${(rm.stderr || rm.error?.message || '').trim() || 'unknown error'}`;
+  }
+  console.log(line);
+}
+if (!apply && results.some((r) => r.verdict === 'safe')) {
+  console.log('dry-run: no removal performed — re-run with --apply to remove safe entries');
+}
+process.exit(0);