@polymorphism-tech/morph-spec 8.27.0 → 8.28.0

package/src/lib/worktree/feature-truth.js

@@ -0,0 +1,248 @@
+/**
+ * feature-truth.js — where a feature's authoritative `feature.json` actually
+ * lives, and how to read it from a place that isn't the feature's own tree.
+ *
+ * `create --worktree` writes a COMPLETE feature.json into the primary root
+ * (status, approvalGates, tasks, gateDecisions) and only then copies it into
+ * the worktree. From that instant the branch-committed copy (`morph/{f}`) is
+ * the truth and the root's copy never changes again — the root sees the
+ * feature exactly as it was at birth, forever, unless someone reads through.
+ *
+ * `branchToReadFrom`/`branchView` are moved verbatim from fleet-scanner.js —
+ * they already solved this (comments B3/B3b there), fleet just never shared
+ * them. `resolveFeatureTree` is the missing piece for CONSUMERS OTHER than
+ * fleet: "which tree/branch actually owns this feature's state", used by
+ * `list`, `handoff`, and the mutator guard (assertOwnerTree).
+ *
+ * Fail-open throughout: no repo, no branch, no blob, unparseable JSON never
+ * throws — callers get null/false and fall back to reading the disk.
+ */
+
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { isGitRepo, resolvePrimaryRoot, findWorktreeForFeature, buildBranchName } from '../../commands/project/worktree.js';
+
+/**
+ * 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"
+ */
+export 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}
+ */
+export 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 };
+}
+
+/** All local `morph/*` branches, as bare feature names — one spawn, a pre-filter. */
+export function morphBranches(root) {
+  try {
+    const out = execFileSync('git', ['for-each-ref', '--format=%(refname:short)', 'refs/heads/morph/'], {
+      cwd: root, stdio: 'pipe',
+    }).toString();
+    const names = new Set();
+    for (const line of out.split('\n')) {
+      const b = line.trim();
+      if (b) names.add(b.slice('morph/'.length));
+    }
+    return names;
+  } catch {
+    return new Set();
+  }
+}
+
+/** The tree's current branch, or null (detached HEAD / no repo / no commits yet). */
+export function currentBranch(cwd) {
+  try {
+    const out = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
+    return out === 'HEAD' ? null : out || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read a feature's local feature.json from `dir`, or null if missing/corrupt. */
+function readLocalFeatureJson(dir, feature) {
+  const p = join(dir, '.morph', 'features', feature, 'feature.json');
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve which TREE (or, failing that, which BRANCH) actually owns a
+ * feature's state — "follow the pointer" for any consumer, not just fleet.
+ *
+ * Six-step search, each step justified by what it's immune to:
+ *
+ *  1. cwd holds the feature AND cwd is that feature's registered worktree
+ *     (git's own record, via findWorktreeForFeature) → running inside the
+ *     owner never counts as a jump.
+ *  2. `findWorktreeForFeature` finds a live worktree elsewhere → the tree the
+ *     GIT REGISTRY says is the owner, not the feature.json pointer — immune
+ *     to a dangling/stale `feature.worktree` field.
+ *  3. the local feature.json's own `worktree.path` field, if it still exists
+ *     on disk → covers a worktree living outside the conventional path or a
+ *     registry `git worktree list` can't see for some reason.
+ *  4. cwd holds the feature with no worktree registered anywhere → the common
+ *     case (no `--worktree`, or the worktree was already torn down).
+ *  5. no local copy, but `morph/{feature}` has the file committed → the truth
+ *     exists, just not materialized into any tree right now.
+ *  6. nothing anywhere.
+ *
+ * @param {string} feature
+ * @param {string} [cwd]
+ * @returns {{
+ *   source: 'cwd'|'registry'|'pointer'|'branch-only'|'none',
+ *   tree: string|null,
+ *   branch: string|null,
+ *   worktree: {path:string, branch:string}|null,
+ *   pointerDangling: boolean,
+ * }}
+ */
+export function resolveFeatureTree(feature, cwd = process.cwd()) {
+  const localFj = readLocalFeatureJson(cwd, feature);
+  const pointerPath = localFj?.worktree?.path || null;
+  const pointerDangling = Boolean(pointerPath) && !existsSync(pointerPath);
+
+  const inGit = isGitRepo(cwd);
+  const root = inGit ? resolvePrimaryRoot(cwd) : null;
+
+  // Step 1 + 2: git's own worktree registry is the source of truth for "is
+  // there a live worktree for this feature, and where".
+  if (inGit && root) {
+    const registered = findWorktreeForFeature(feature, root);
+    if (registered && existsSync(registered.path)) {
+      const branch = registered.branch || buildBranchName(feature);
+      if (registered.path.replace(/\\/g, '/') === cwd.replace(/\\/g, '/')) {
+        return { source: 'cwd', tree: cwd, branch, worktree: { path: registered.path, branch }, pointerDangling };
+      }
+      return { source: 'registry', tree: registered.path, branch, worktree: { path: registered.path, branch }, pointerDangling };
+    }
+  }
+
+  // Step 3: the local pointer names a worktree the registry didn't surface
+  // (unconventional location, or registry unreadable) but that still exists.
+  if (pointerPath && !pointerDangling) {
+    const branch = localFj?.worktree?.branch || buildBranchName(feature);
+    return { source: 'pointer', tree: pointerPath, branch, worktree: { path: pointerPath, branch }, pointerDangling };
+  }
+
+  // Step 4: this tree holds the feature and nothing else claims to own it.
+  if (localFj) {
+    return { source: 'cwd', tree: cwd, branch: null, worktree: null, pointerDangling };
+  }
+
+  // Step 5: no local copy anywhere in this tree, but the branch has one.
+  if (inGit && root) {
+    const branch = buildBranchName(feature);
+    const view = branchView(root, feature, branch);
+    if (view) {
+      return { source: 'branch-only', tree: null, branch, worktree: null, pointerDangling: false };
+    }
+  }
+
+  // Step 6.
+  return { source: 'none', tree: null, branch: null, worktree: null, pointerDangling: false };
+}
+
+/**
+ * Should a mutator (approve/advance/score/gate-decision/gate-check) refuse to
+ * write this feature's `feature.json` from `cwd`?
+ *
+ * Blocked ONLY when a live worktree owns the feature and it is NOT cwd —
+ * `resolveFeatureTree` sources `'registry'`/`'pointer'`. `'cwd'` (cwd IS the
+ * owner, or no worktree exists at all) always passes. This is what stops
+ * `morph-spec approve <f> plan` run from the root, with the worktree still
+ * alive, from silently stamping the gate onto the root's birth-instant
+ * skeleton — branch-drift CREATED by a command, not merely left behind by one.
+ *
+ * @param {string} feature
+ * @param {string} [cwd]
+ * @returns {{ blocked: boolean, tree: string|null, branch: string|null }}
+ */
+export function assertOwnerTree(feature, cwd = process.cwd()) {
+  const owner = resolveFeatureTree(feature, cwd);
+  const blocked = owner.source === 'registry' || owner.source === 'pointer';
+  return { blocked, tree: owner.tree, branch: owner.branch };
+}
+
+/**
+ * The refusal text every mutator prints on an owner-tree block — one place so
+ * `approve`/`advance`/`score`/`gate-decision`/`gate-check` can never drift
+ * into five different wordings for the same defect. `commandLine` is the
+ * exact command the caller should re-run inside the owner tree.
+ *
+ * @param {string} feature
+ * @param {string} tree
+ * @param {string|null} branch
+ * @param {string} commandLine
+ * @returns {Array<{tone: 'red'|'gray'|'cyan'|'yellow', text: string}>}
+ */
+export function ownerTreeRefusalLines(feature, tree, branch, commandLine) {
+  return [
+    { tone: 'red', text: `\n❌ A feature "${feature}" não pode ser mutada A PARTIR DESTA ÁRVORE.` },
+    { tone: 'gray', text: `   O worktree dono está vivo em: ${tree}${branch ? ` (branch ${branch})` : ''}` },
+    { tone: 'gray', text: '   Rode o comando LÁ — a mutação é gravada no feature.json daquela árvore:' },
+    { tone: 'cyan', text: `     cd "${tree}" && ${commandLine}` },
+    { tone: 'yellow', text: '\n   NÃO use --force aqui: ele carimbaria a mutação na cópia da raiz, duplicando' },
+    { tone: 'yellow', text: '   uma escrita que a outra árvore já tem e desalinhando os dois feature.json.\n' },
+  ];
+}

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

@@ -19,6 +19,7 @@ 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 { branchToReadFrom, branchView } from './feature-truth.js';
 import {
   getFeature,
   derivePhaseForFeature,
@@ -34,71 +35,6 @@ function countFrom(raw) {
   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.
  *

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

@@ -22,13 +22,14 @@
  */
 
 import { execFileSync } from 'child_process';
-import { existsSync, readdirSync, statSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join, resolve } from 'path';
 import {
   isGitRepo,
   resolvePrimaryRoot,
   parseWorktreeList,
   WORKTREE_DIR_NAMES,
+  clearDanglingWorktreeRegistration,
 } from '../../commands/project/worktree.js';
 
 const norm = (p) => resolve(p).replace(/\\/g, '/');
@@ -65,6 +66,36 @@ function featureCommittedOnBranch(root, feature) {
   }
 }
 
+/**
+ * Every feature's `worktree` registration in the primary root — the OTHER
+ * direction from `knownFeatures`/`dirsOnDisk`: not "does git/disk know about
+ * this worktree", but "does the ROOT's feature.json still point somewhere
+ * real". `create --worktree` writes this pointer once at birth
+ * (`{path, branch, createdAt}`) and nothing updates it afterwards except
+ * `finish`'s own teardown — so a directory removed any other way (by hand,
+ * `git worktree prune` run directly, a failed teardown that still cleared the
+ * field, an unrelated script) leaves it dangling with nothing to notice.
+ *
+ * @param {string} root
+ * @returns {Array<{ feature: string, path: string, branch: string|null }>}
+ */
+function featureRegistrations(root) {
+  const out = [];
+  try {
+    const dir = join(root, '.morph', 'features');
+    if (!existsSync(dir)) return out;
+    for (const feature of readdirSync(dir)) {
+      const fjPath = join(dir, feature, 'feature.json');
+      if (!existsSync(fjPath)) continue;
+      try {
+        const fj = JSON.parse(readFileSync(fjPath, 'utf8'));
+        if (fj?.worktree?.path) out.push({ feature, path: fj.worktree.path, branch: fj.worktree.branch || null });
+      } catch { /* corrupt feature.json — nothing to register */ }
+    }
+  } catch { /* fail-open */ }
+  return out;
+}
+
 /** Directories physically present under either worktree root. */
 function dirsOnDisk(root) {
   const found = [];
@@ -87,14 +118,25 @@ function dirsOnDisk(root) {
  * 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
+ *   • 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
+ *   • dangling-registration     — a feature's ROOT feature.json still points
+ *                                 at a `worktree.path` that no longer exists
+ *                                 (the symmetric OTHER direction from
+ *                                 `no-feature`: the worktree is gone, but the
+ *                                 root's pointer to it survived)
+ *   • unregistered-registration — a feature's `worktree.path` names a
+ *                                 directory that exists but git's own
+ *                                 registry does not know as a worktree
  *
  * @param {string} [cwd]
- * @returns {Array<{ type: string, detail: string, path?: string, fix: string }>}
+ * @returns {Array<{ type: string, detail: string, path?: string, feature?: string, fix: string }>}
  */
 export function auditWorktrees(cwd = process.cwd()) {
   if (!isGitRepo(cwd)) return [];
@@ -161,25 +203,69 @@ export function auditWorktrees(cwd = process.cwd()) {
     });
   }
 
+  // The other direction: does the ROOT's own bookkeeping still point at a
+  // live worktree? `git worktree list`/disk only see what's PHYSICALLY
+  // there; a registration surviving past its worktree's removal is invisible
+  // to every check above.
+  for (const reg of featureRegistrations(root)) {
+    const path = norm(reg.path);
+    if (!existsSync(reg.path)) {
+      issues.push({
+        type: 'dangling-registration',
+        feature: reg.feature,
+        path,
+        detail: `"${reg.feature}" registra worktree.path=${path} na raiz, mas o diretório não existe`,
+        fix: `morph-spec doctor --worktrees --prune`,
+      });
+    } else if (!registeredPaths.has(path)) {
+      issues.push({
+        type: 'unregistered-registration',
+        feature: reg.feature,
+        path,
+        detail: `"${reg.feature}" registra worktree.path=${path}, mas o git não o conhece como worktree — a próxima \`worktree setup\` recusará com exit 3`,
+        fix: `inspecione o diretório; se não serve mais, apague-o e rode morph-spec doctor --worktrees --prune`,
+      });
+    }
+  }
+
   return issues;
 }
 
 /**
- * Drop git's admin records for worktrees whose directory is already gone.
+ * Drop git's admin records for worktrees whose directory is already gone, AND
+ * clear any feature's `worktree` registration that names one of those same
+ * gone directories.
  *
- * 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.
+ * Both halves are the ONLY prune offered, on purpose: neither can destroy
+ * anything, because everything they touch is already absent from disk.
+ * Removing a directory that still exists is exactly the operation that needs
+ * a human looking at it.
+ *
+ * `clearDanglingWorktreeRegistration` re-checks the dangling predicate itself
+ * (path unset, or still exists → no-op) rather than trusting a pre-computed
+ * list, so this stays correct even called against a stale audit snapshot.
  *
  * @param {string} [cwd]
- * @returns {{ pruned: boolean, error?: string }}
+ * @returns {Promise<{ pruned: boolean, error?: string, clearedRegistrations: Array<{feature: string, cleared: boolean}> }>}
  */
-export function pruneWorktrees(cwd = process.cwd()) {
-  if (!isGitRepo(cwd)) return { pruned: false, error: 'not-a-git-repo' };
+export async function pruneWorktrees(cwd = process.cwd()) {
+  if (!isGitRepo(cwd)) return { pruned: false, error: 'not-a-git-repo', clearedRegistrations: [] };
+  const root = resolvePrimaryRoot(cwd);
+
+  let pruned = false;
+  let error;
   try {
-    execFileSync('git', ['worktree', 'prune'], { cwd: resolvePrimaryRoot(cwd), stdio: 'pipe' });
-    return { pruned: true };
+    execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
+    pruned = true;
   } catch (err) {
-    return { pruned: false, error: (err.message || 'unknown').slice(0, 200) };
+    error = (err.message || 'unknown').slice(0, 200);
   }
+
+  const clearedRegistrations = [];
+  for (const reg of featureRegistrations(root)) {
+    const { cleared } = await clearDanglingWorktreeRegistration(root, reg.feature);
+    if (cleared) clearedRegistrations.push({ feature: reg.feature, cleared: true });
+  }
+
+  return { pruned, ...(error ? { error } : {}), clearedRegistrations };
 }