@polymorphism-tech/morph-spec 8.6.0 → 8.7.0

package/src/core/state/lifecycle-audit.js

@@ -10,14 +10,68 @@
  *   • orphan-folder — a feature folder with no feature.json
  *   • stale-index   — a root-index entry with no feature folder (auto-heals on
  *                     the next loadState, but surfaced so it's not a mystery)
+ *   • branch-drift  — the root's copy of a feature.json disagrees with the copy
+ *                     committed on `morph/{f}` (B5 — the root's view lags)
  *   • corrupt       — a feature.json that won't parse
  */
 
+import { execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
 import { gateOrderViolations } from './gate-order.js';
 import { missingIdentity } from './feature-identity.js';
 
+/** The operational truth of a feature.json: its status and which gates are approved. */
+function operationalShape(fj) {
+  const gates = {};
+  for (const [g, v] of Object.entries(fj?.approvalGates || {})) gates[g] = v?.approved === true;
+  return JSON.stringify({ status: fj?.status ?? null, gates });
+}
+
+/**
+ * Does the root's working-tree copy of a feature.json disagree with the copy
+ * COMMITTED on that feature's own branch?
+ *
+ * `.morph/state.json` is gitignored and derived, and every worktree keeps its
+ * own — so "the index diverges between worktrees" is by design, not a defect to
+ * fix by making the index authoritative (that would undo the whole per-feature
+ * state model). The defect is that the divergence was INVISIBLE: since v8.4 the
+ * authoritative feature.json travels committed on `morph/{f}`, so a primary root
+ * parked on the default holds a copy that silently lags, and everything derived
+ * from it (status, gates, and the index rebuilt from it) lags with it.
+ *
+ * Comparison is on the OPERATIONAL fields only — status and approved-gate flags
+ * — not on bytes: reformatting or a timestamp bump is not a divergence anyone
+ * needs to hear about.
+ *
+ * Fail-open at every step: no repo, no branch, no blob, unparseable JSON → no
+ * issue. A diagnostic that invents problems is worse than one that misses some.
+ *
+ * @returns {string|null} the issue detail, or null when the copies agree
+ */
+function branchDrift(baseDir, feature, rootFj) {
+  const branch = `morph/${feature}`;
+  try {
+    const current = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: baseDir, stdio: 'pipe' })
+      .toString().trim();
+    // On the feature's own branch the working tree IS the branch — nothing to compare.
+    if (current === branch) return null;
+
+    execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: baseDir, stdio: 'pipe' });
+
+    const raw = execFileSync('git', ['show', `${branch}:.morph/features/${feature}/feature.json`], {
+      cwd: baseDir, stdio: 'pipe',
+    }).toString();
+    const branchFj = JSON.parse(raw);
+
+    if (operationalShape(branchFj) === operationalShape(rootFj)) return null;
+    return `root copy disagrees with ${branch} (status/gates) — the branch is authoritative; `
+      + `rode \`git show ${branch}:.morph/features/${feature}/feature.json\` para ver`;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * @param {string} [baseDir] - project root (defaults to cwd)
  * @returns {Array<{ feature: string, type: string, detail: string }>} issues
@@ -49,6 +103,9 @@ export function auditFeatureLifecycle(baseDir = process.cwd()) {
         continue;
       }
 
+      const drift = branchDrift(baseDir, name, fj);
+      if (drift) issues.push({ feature: name, type: 'branch-drift', detail: drift });
+
       const miss = missingIdentity(fj);
       if (miss.length) {
         issues.push({ feature: name, type: 'identity', detail: `missing ${miss.join(', ')}` });

package/src/dashboard/scanner/state-scanner.js

@@ -1,5 +1,6 @@
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { WORKTREE_DIR_NAMES } from '../../commands/project/worktree.js';
 
 export function scanState(projectDir) {
   const statePath = join(projectDir, '.morph', 'state.json');
@@ -32,15 +33,22 @@ export function scanState(projectDir) {
   }
 
   // Aggregate in-progress features that only exist inside a feature worktree
-  // (.worktrees/{wt}/.morph/features/*/feature.json). In the v8 multi-instance
+  // (worktrees/{wt}/.morph/features/*/feature.json). In the v8 multi-instance
   // model a feature's authoritative feature.json is committed on its
   // `morph/{feature}` branch and only lands in the root .morph/features/ after
   // `morph-spec finish`. This is read-only visibility for the dashboard — root
   // features (the merged, authoritative state) always take precedence, and
   // worktree-sourced entries are tagged with `_worktree` so the UI can
   // distinguish them.
-  const worktreesDir = join(projectDir, '.worktrees');
-  if (existsSync(worktreesDir)) {
+  //
+  // BOTH directory names are scanned: this scanner resolves worktrees by
+  // CONVENTION (unlike fleet/finish, which read `git worktree list`), so it is
+  // the one that would otherwise go blind to pre-C1 `.worktrees/` checkouts.
+  const worktreeDirs = WORKTREE_DIR_NAMES
+    .map((name) => join(projectDir, name))
+    .filter((dir) => existsSync(dir));
+
+  for (const worktreesDir of worktreeDirs) {
     let worktreeNames = [];
     try {
       worktreeNames = readdirSync(worktreesDir, { withFileTypes: true })

package/src/lib/generators/architecture-scanner.js

@@ -19,7 +19,7 @@ import path from 'path';
 import { existsSync, readFileSync } from 'fs';
 import { renderTemplate } from '../../core/templates/template-renderer.js';
 
-const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', '.git', '.morph', '.next', 'dist', 'out', '.worktrees']);
+const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', '.git', '.morph', '.next', 'dist', 'out', 'worktrees', '.worktrees']);
 const MAX_FILES_PER_SCANNER = 200;
 
 /**

package/src/lib/tasks/tasks-json-parser.js

@@ -201,6 +201,14 @@ export function groupTasks(data) {
  * Convert tasks.json to the legacy taskList shape used in state.json.
  * Lets the rest of the codebase keep using feature.taskList while migration
  * is in progress.
+ *
+ * BOUNDARY — this is the ONE place `done` becomes `completed`, and it is a
+ * one-way translation OUT of the tasks.json vocabulary. In tasks.json the
+ * terminal status is `done` (tasks.schema.json's enum has no `completed`);
+ * `completed` belongs to the legacy taskList and to Claude Code's native
+ * session tasks. Leaking `completed` back into a tasks.json write is rejected
+ * by `protect-spec-files` — see framework/rules/morph-task-tracking.md, which
+ * spells the split out for the author.
  */
 export function toTaskList(data) {
   return data.tasks.map(t => ({

package/src/lib/worktree/fleet-scanner.js

@@ -17,18 +17,118 @@ import { execSync, execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { isGitRepo, resolvePrimaryRoot, parseWorktreeList } from '../../commands/project/worktree.js';
+import { hasOriginRemote } from '../git/default-branch.js';
 import { registryPath, resolveFleetConfig } from './env-allocator.js';
 import {
   getFeature,
   derivePhaseForFeature,
+  derivePhaseFrom,
   getPendingGates,
+  pendingGatesFrom,
 } from '../../../framework/hooks/shared/state-reader.js';
+import { listClaims } from '../../../framework/hooks/shared/claim-registry.js';
+
+function countFrom(raw) {
+  const data = JSON.parse(raw);
+  if (!Array.isArray(data.tasks)) return null;
+  return { done: data.tasks.filter((t) => t.status === 'done').length, total: data.tasks.length };
+}
+
+/**
+ * Which branch holds this feature's truth, when the working tree at `path` does
+ * NOT — or `null` when the working tree IS the feature's own checkout.
+ *
+ * The ONE place this condition lives. `tasks` (B3) and `phase`/`pendingGates`
+ * (B3b) are the same defect read through different files, so they must agree on
+ * when to look at the branch; two drifting copies of this test would resurrect
+ * the bug on one field while the other stayed fixed.
+ *
+ * A worktree entry is the feature's checkout by construction. A root entry is
+ * only the feature's checkout when the root happens to be ON `morph/{f}`.
+ *
+ * @returns {string|null} branch name to read from, or null for "read the disk"
+ */
+function branchToReadFrom(root, feature, location, branch) {
+  if (location === 'worktree' || !root || !feature) return null;
+  const featureBranch = branch || `morph/${feature}`;
+  try {
+    const current = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: root, stdio: 'pipe' })
+      .toString().trim();
+    return current === featureBranch ? null : featureBranch;
+  } catch {
+    return null; // no HEAD to compare against — trust the disk
+  }
+}
+
+/**
+ * The feature's committed state on its own branch: the feature.json blob plus
+ * the set of files under its feature dir.
+ *
+ * `git ls-tree -z` is deliberate: without it git QUOTES paths containing
+ * non-ASCII bytes (`"a\303\247/…"`), which would silently fail the prefix strip
+ * and leave the artifact set empty — a predicate that is always false looks
+ * exactly like "this feature has no artifacts".
+ *
+ * Fail-open in layers: no blob → null (caller reads the disk); no tree → the
+ * gates alone still beat a stale working tree.
+ *
+ * @returns {{ fj: Object, files: Set<string> }|null}
+ */
+function branchView(root, feature, featureBranch) {
+  const prefix = `.morph/features/${feature}/`;
+  let fj;
+  try {
+    fj = JSON.parse(execFileSync('git', ['show', `${featureBranch}:${prefix}feature.json`], {
+      cwd: root, stdio: 'pipe',
+    }).toString());
+  } catch {
+    return null;
+  }
+
+  const files = new Set();
+  try {
+    const out = execFileSync('git', ['ls-tree', '-r', '--name-only', '-z', featureBranch, '--', prefix], {
+      cwd: root, stdio: 'pipe',
+    }).toString();
+    for (const raw of out.split('\0')) {
+      const p = raw.trim();
+      if (p.startsWith(prefix)) files.add(p.slice(prefix.length));
+    }
+  } catch { /* no tree — gates alone still beat the stale working tree */ }
+
+  return { fj, files };
+}
+
+/**
+ * Task progress for one feature.
+ *
+ * DIVERGENCE from the bug report, which blamed "a cached state.json/feature.json
+ * snapshot": this never read either — it always read `2-plan/tasks.json`
+ * directly. The real mechanism is which COPY of that file is on disk. Since
+ * v8.4 every feature is born on `morph/{f}` and its tasks.json is COMMITTED
+ * there; the primary root's working tree only ever holds the copy of the
+ * CHECKED-OUT branch. An operator sitting on the default therefore read the
+ * pre-work copy — the reported `2/2` for a feature whose branch already had
+ * T1..T3 all done.
+ *
+ * @param {string} featureDir - the feature dir inside `path`
+ * @param {{ root: string, feature: string, featureBranch: string|null }} ctx
+ */
+function taskCounts(featureDir, { root, feature, featureBranch } = {}) {
+  if (featureBranch && root && feature) {
+    try {
+      const raw = execFileSync(
+        'git',
+        ['show', `${featureBranch}:.morph/features/${feature}/2-plan/tasks.json`],
+        { cwd: root, stdio: 'pipe' },
+      ).toString();
+      const counted = countFrom(raw);
+      if (counted) return counted;
+    } catch { /* no such branch/blob — fall through to the working tree */ }
+  }
 
-function taskCounts(featureDir) {
   try {
-    const data = JSON.parse(readFileSync(join(featureDir, '2-plan', 'tasks.json'), 'utf8'));
-    if (!Array.isArray(data.tasks)) return null;
-    return { done: data.tasks.filter((t) => t.status === 'done').length, total: data.tasks.length };
+    return countFrom(readFileSync(join(featureDir, '2-plan', 'tasks.json'), 'utf8'));
   } catch {
     return null;
   }
@@ -63,17 +163,108 @@ function dirtyCount(worktreePath) {
   }
 }
 
-function buildEntry(feature, { location, path, branch, root, allocations, blockSize }) {
+/**
+ * One `git ls-remote --heads origin` for the WHOLE scan → Map<branch, sha>.
+ *
+ * The fleet used to read only local state, so a feature whose branch (and PR)
+ * already lived on origin still showed up as "pending, nothing pushed" — that
+ * reading is what made a second session redo finished work. Resolved once per
+ * scan, never per entry.
+ *
+ * Returns `null` when there is no origin, or the probe fails/times out: the
+ * entries then carry `remote: null` ("unknown"), never a false `pushed: false`.
+ *
+ * @param {string} root
+ * @returns {Map<string,string>|null}
+ */
+function remoteHeads(root) {
+  if (!hasOriginRemote(root)) return null;
+  try {
+    const out = execFileSync('git', ['ls-remote', '--heads', 'origin'], {
+      cwd: root, stdio: 'pipe', timeout: 5000,
+    }).toString();
+    const map = new Map();
+    for (const line of out.split('\n')) {
+      const m = line.match(/^([0-9a-f]{7,64})\s+refs\/heads\/(.+)$/);
+      if (m) map.set(m[2].trim(), m[1]);
+    }
+    return map;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One `gh pr list` for the whole scan → Map<headRefName, {number, state}>.
+ *
+ * Gated on the origin URL actually pointing at github.com — `gh` against any
+ * other host is a guaranteed error, and paying its start-up cost to learn that
+ * on every `fleet` call is pure latency. Fail-open: no `gh`, not authenticated,
+ * or a timeout all yield `null`, which just leaves the PR half of the column
+ * empty while `pushed` still works.
+ *
+ * @param {string} root
+ * @returns {Map<string,{number:number,state:string}>|null}
+ */
+function remotePrs(root) {
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: root, stdio: 'pipe' }).toString();
+    if (!/github\.com/i.test(url)) return null;
+    const out = execFileSync('gh', ['pr', 'list', '--state', 'all', '--limit', '100', '--json', 'number,state,headRefName'], {
+      cwd: root, stdio: 'pipe', timeout: 8000,
+    }).toString();
+    const map = new Map();
+    for (const pr of JSON.parse(out)) {
+      // First wins: `gh` lists newest-first, so an OPEN PR shadows an older
+      // closed one on the same branch.
+      if (pr?.headRefName && !map.has(pr.headRefName)) map.set(pr.headRefName, { number: pr.number, state: pr.state });
+    }
+    return map;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The remote fact for one feature. Worktree entries know their real branch
+ * (which may carry a `--fresh` date suffix); root-resident features fall back
+ * to the canonical `morph/{feature}` every feature is born on.
+ */
+function buildRemote(feature, branch, heads, prs) {
+  if (!heads) return null;
+  const remoteBranch = branch || `morph/${feature}`;
+  const sha = heads.get(remoteBranch) || null;
+  return { branch: remoteBranch, pushed: sha !== null, sha, pr: prs?.get(remoteBranch) || null };
+}
+
+function buildEntry(feature, { location, path, branch, root, allocations, blockSize, heads, prs, claims }) {
   let workType = null;
   let status = 'unknown';
   let phase = 'proposal';
   let pendingGates = [];
+
+  // Resolved once and shared with taskCounts — see branchToReadFrom.
+  const featureBranch = branchToReadFrom(root, feature, location, branch);
+
   try {
-    const fj = getFeature(feature, path);
-    workType = fj?.workType || null;
-    status = fj?.status || 'unknown';
-    phase = derivePhaseForFeature(feature, path);
-    pendingGates = getPendingGates(feature, path);
+    // B3b: phase and gates suffered the same branch-staleness B3 fixed for
+    // tasks. They read `.morph/features/{f}/` through the working tree, so a
+    // root parked on the default reported the PRE-WORK phase for a feature
+    // whose branch was already at implement — and re-asked for a gate the
+    // feature branch had already approved.
+    const view = featureBranch ? branchView(root, feature, featureBranch) : null;
+    if (view) {
+      workType = view.fj?.workType || null;
+      status = view.fj?.status || 'unknown';
+      phase = derivePhaseFrom(view.fj, (rel) => view.files.has(rel));
+      pendingGates = pendingGatesFrom(view.fj);
+    } else {
+      const fj = getFeature(feature, path);
+      workType = fj?.workType || null;
+      status = fj?.status || 'unknown';
+      phase = derivePhaseForFeature(feature, path);
+      pendingGates = getPendingGates(feature, path);
+    }
   } catch { /* field-level fail-open */ }
 
   const featureDir = join(path, '.morph', 'features', feature);
@@ -87,13 +278,19 @@ function buildEntry(feature, { location, path, branch, root, allocations, blockS
     location,
     path,
     branch,
-    tasks: taskCounts(featureDir),
+    tasks: taskCounts(featureDir, { root, feature, featureBranch }),
     env: alloc && Number.isInteger(alloc.base)
       ? { base: alloc.base, range: [alloc.base, alloc.base + blockSize - 1] }
       : null,
     handoff: handoffInfo(featureDir),
     lastCommit: location === 'worktree' && branch ? lastCommitRelative(root, branch) : null,
     dirty: location === 'worktree' ? dirtyCount(path) : null,
+    remote: buildRemote(feature, branch, heads, prs),
+    // Advisory ownership (B1): which session is on this feature right now.
+    // `live` is what matters for the operator — a stale claim is reported as
+    // stale rather than hidden, so "nobody is here" and "somebody died here"
+    // stay distinguishable.
+    claim: claims?.[feature] || null,
   };
 }
 
@@ -110,15 +307,24 @@ export function scanFleet(cwd = process.cwd()) {
   const root = resolvePrimaryRoot(cwd);
 
   let allocations = {};
+  const claims = {};
   try {
     const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
     if (common) {
-      const reg = JSON.parse(readFileSync(registryPath(resolve(root, common)), 'utf8'));
-      if (reg && typeof reg.allocations === 'object' && reg.allocations !== null) allocations = reg.allocations;
+      const gitCommonDir = resolve(root, common);
+      try {
+        const reg = JSON.parse(readFileSync(registryPath(gitCommonDir), 'utf8'));
+        if (reg && typeof reg.allocations === 'object' && reg.allocations !== null) allocations = reg.allocations;
+      } catch { /* no env registry yet — env stays null per entry */ }
+      for (const c of listClaims(gitCommonDir)) claims[c.feature] = c;
     }
-  } catch { /* no registry yet — env stays null per entry */ }
+  } catch { /* no common dir — env and claim both stay null per entry */ }
   const { blockSize } = resolveFleetConfig(root);
 
+  // Remote awareness, resolved ONCE for the whole scan (see remoteHeads/remotePrs).
+  const heads = remoteHeads(root);
+  const prs = heads ? remotePrs(root) : null;
+
   const entries = [];
   const inWorktree = new Set();
 
@@ -133,6 +339,9 @@ export function scanFleet(cwd = process.cwd()) {
       root,
       allocations,
       blockSize,
+      heads,
+      prs,
+      claims,
     }));
   }
 
@@ -146,7 +355,7 @@ export function scanFleet(cwd = process.cwd()) {
         .filter((name) => !inWorktree.has(name) && existsSync(join(featuresDir, name, 'feature.json')));
       for (const name of names) {
         entries.push(buildEntry(name, {
-          location: 'root', path: root, branch: null, root, allocations, blockSize,
+          location: 'root', path: root, branch: null, root, allocations, blockSize, heads, prs, claims,
         }));
       }
     }

package/src/lib/worktree/worktree-audit.js

@@ -0,0 +1,181 @@
+/**
+ * worktree-audit.js — reconcile the three views of "which worktrees exist".
+ *
+ * Orphan worktrees accumulate silently. In the observed session,
+ * `.worktrees/verify-tables-ui` and `.worktrees/tmp-cleanup` were registered in
+ * `git worktree list` yet ABSENT from `morph-spec fleet` — fleet only reports
+ * worktrees whose branch matches `refs/heads/morph/*`, so anything else is
+ * invisible by construction and therefore never cleaned up (C2).
+ *
+ * Nothing compared the three sources that must agree:
+ *
+ *   1. git's registry   — `git worktree list --porcelain`
+ *   2. the disk         — directories under `worktrees/` (and legacy `.worktrees/`)
+ *   3. morph's features — `.morph/features/{f}/feature.json`
+ *
+ * Read-only and fail-open: anything unresolvable yields no issue rather than a
+ * throw. A diagnostic that invents problems is worse than one that misses some.
+ * The one mutation lives in `pruneWorktrees`, and it is deliberately the safest
+ * possible: `git worktree prune` drops ADMIN RECORDS for directories that are
+ * already gone. Deleting a directory that still exists stays a human decision —
+ * the same PROVE-or-DECLINE discipline `teardownWorktree` follows.
+ */
+
+import { execFileSync } from 'child_process';
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import {
+  isGitRepo,
+  resolvePrimaryRoot,
+  parseWorktreeList,
+  WORKTREE_DIR_NAMES,
+} from '../../commands/project/worktree.js';
+
+const norm = (p) => resolve(p).replace(/\\/g, '/');
+
+/** Feature names morph knows about in the primary root. */
+function knownFeatures(root) {
+  const names = new Set();
+  try {
+    const dir = join(root, '.morph', 'features');
+    if (!existsSync(dir)) return names;
+    for (const name of readdirSync(dir)) {
+      if (existsSync(join(dir, name, 'feature.json'))) names.add(name);
+    }
+  } catch { /* fail-open */ }
+  return names;
+}
+
+/**
+ * Is the feature's authoritative feature.json COMMITTED on its own branch?
+ *
+ * Not "does the branch exist": `git worktree add -b morph/{f}` creates the
+ * branch as a side effect, so branch-existence is true for every registered
+ * worktree and proves nothing. The blob is the real evidence — it is where the
+ * per-feature state model says the truth lives.
+ */
+function featureCommittedOnBranch(root, feature) {
+  try {
+    execFileSync('git', ['cat-file', '-e', `morph/${feature}:.morph/features/${feature}/feature.json`], {
+      cwd: root, stdio: 'pipe',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Directories physically present under either worktree root. */
+function dirsOnDisk(root) {
+  const found = [];
+  for (const dirName of WORKTREE_DIR_NAMES) {
+    const base = join(root, dirName);
+    if (!existsSync(base)) continue;
+    try {
+      for (const name of readdirSync(base)) {
+        const full = join(base, name);
+        try {
+          if (statSync(full).isDirectory()) found.push({ name, path: norm(full), container: dirName });
+        } catch { /* unreadable entry — skip */ }
+      }
+    } catch { /* fail-open */ }
+  }
+  return found;
+}
+
+/**
+ * Reconcile git's registry, the disk and morph's features.
+ *
+ * Issue types:
+ *   • registered-missing — git has a worktree whose directory is gone
+ *   • non-morph-branch   — a registered worktree under worktrees/ on a branch
+ *                          that is not `morph/*`, so `fleet` cannot see it
+ *   • unregistered-dir   — a directory under worktrees/ git never registered
+ *   • no-feature         — a `morph/{f}` worktree for a feature morph does not know
+ *
+ * @param {string} [cwd]
+ * @returns {Array<{ type: string, detail: string, path?: string, fix: string }>}
+ */
+export function auditWorktrees(cwd = process.cwd()) {
+  if (!isGitRepo(cwd)) return [];
+  const root = resolvePrimaryRoot(cwd);
+  const rootNorm = norm(root);
+  const issues = [];
+
+  const registered = parseWorktreeList(root);
+  const registeredPaths = new Set();
+  const features = knownFeatures(root);
+
+  for (const entry of registered) {
+    const path = norm(entry.path);
+    registeredPaths.add(path);
+    if (path === rootNorm) continue; // the primary root is not a worktree orphan
+
+    if (!existsSync(path)) {
+      issues.push({
+        type: 'registered-missing',
+        path,
+        detail: `git registra um worktree em ${path}, mas o diretório não existe`,
+        fix: `git worktree prune  (ou \`morph-spec doctor --worktrees --prune\`)`,
+      });
+      continue;
+    }
+
+    const feature = entry.branch?.match(/^refs\/heads\/morph\/(.+)$/)?.[1] || null;
+    if (!feature) {
+      // Only worth reporting when it sits in morph's own worktree container —
+      // a worktree the user keeps elsewhere is none of morph's business.
+      const inContainer = WORKTREE_DIR_NAMES.some((d) => path.startsWith(`${rootNorm}/${d}/`));
+      if (inContainer) {
+        issues.push({
+          type: 'non-morph-branch',
+          path,
+          detail: `${path} está em ${entry.branch || 'HEAD destacado'}, não numa branch morph/* — o \`fleet\` não o enxerga`,
+          fix: `git worktree remove "${path}"  (se já não serve)`,
+        });
+      }
+      continue;
+    }
+
+    if (!features.has(feature) && !featureCommittedOnBranch(root, feature)) {
+      issues.push({
+        type: 'no-feature',
+        path,
+        detail: `worktree de "${feature}" sem feature conhecida (nem em .morph/features/, nem na branch)`,
+        fix: `git worktree remove "${path}"`,
+      });
+    }
+  }
+
+  for (const d of dirsOnDisk(root)) {
+    if (registeredPaths.has(d.path)) continue;
+    issues.push({
+      type: 'unregistered-dir',
+      path: d.path,
+      detail: `${d.container}/${d.name} existe no disco mas o git não o registra — resíduo de um finish anterior`,
+      fix: `apague o diretório à mão depois de conferir que nada importante ficou nele`,
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Drop git's admin records for worktrees whose directory is already gone.
+ *
+ * The ONLY prune offered, on purpose: it cannot destroy anything, because
+ * everything it touches is already absent from disk. Removing a directory that
+ * still exists is exactly the operation that needs a human looking at it.
+ *
+ * @param {string} [cwd]
+ * @returns {{ pruned: boolean, error?: string }}
+ */
+export function pruneWorktrees(cwd = process.cwd()) {
+  if (!isGitRepo(cwd)) return { pruned: false, error: 'not-a-git-repo' };
+  try {
+    execFileSync('git', ['worktree', 'prune'], { cwd: resolvePrimaryRoot(cwd), stdio: 'pipe' });
+    return { pruned: true };
+  } catch (err) {
+    return { pruned: false, error: (err.message || 'unknown').slice(0, 200) };
+  }
+}

package/src/utils/file-copier.js

@@ -165,7 +165,11 @@ export async function updateGitignore(projectPath) {
     '.claude/agents/',
     '.claude/CLAUDE.md',
     '.claude/settings.local.json',
-    '.worktrees/',
+    '/worktrees/',
+    // Legacy name (pre-C1). Kept so a project that already has `.worktrees/`
+    // on disk does not suddenly see it as untracked dirt — which would also
+    // make `finish`'s clean-root check refuse.
+    '/.worktrees/',
     '.playwright-mcp/',
     'docs/superpowers/',
     ''