@polymorphism-tech/morph-spec 8.27.0 → 8.29.0

package/src/commands/state/list.js

@@ -1,21 +1,38 @@
 import chalk from 'chalk';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
-import { join } from 'path';
+import { basename, join } from 'path';
 import { derivePhase } from '../../core/state/state-manager.js';
 import { gateOrderViolations } from '../../core/state/gate-order.js';
 import { missingIdentity } from '../../core/state/feature-identity.js';
+import { derivePhaseFrom } from '../../../framework/hooks/shared/state-reader.js';
+import { isGitRepo } from '../project/worktree.js';
+import { morphBranches, currentBranch, branchView } from '../../lib/worktree/feature-truth.js';
 
 /**
- * `morph-spec list [--all] [--json]` — the feature audit board.
+ * `morph-spec list [--all] [--json] [--no-branch]` — the feature audit board.
  *
  * One row per feature: slug × workType × status × phase × gates (G1/G2/G3) ×
  * description, plus a flags column for anomalies (missing description, gate
- * order). Complements `delete`: see what's dead before removing it. Replaces
- * the ad-hoc "loop over every feature.json in python" audit.
+ * order, dangling worktree pointer). Complements `delete`: see what's dead
+ * before removing it. Replaces the ad-hoc "loop over every feature.json in
+ * python" audit.
  *
  * Read-only by construction — reads feature.json straight off disk (never
  * `loadState`, which mutates), so listing can never resurrect or prune state.
  * Always exits 0 (fail-open — an empty board is an answer).
+ *
+ * WORKTREE TRUTH: `create --worktree` writes a COMPLETE feature.json into the
+ * primary root, then the branch-committed copy (`morph/{f}`) becomes the
+ * truth and the root's copy never changes again. By default this command
+ * reads that branch when it disagrees with the disk — same mechanism fleet
+ * already uses (`branchToReadFrom`/`branchView`, moved to feature-truth.js so
+ * both consumers share the one place this condition lives). `--no-branch`
+ * turns that off for a faster, disk-only read.
+ *
+ * NOT AN OBJECTIVE: this command only enumerates what exists IN THIS TREE.
+ * A feature that lives solely on a branch with no local `.morph/features/`
+ * copy in any tree never appears here — aggregating across trees is
+ * `morph-spec fleet`'s job, not this one's.
  */
 
 const G = ['proposal', 'uiux', 'plan', 'review'];
@@ -40,7 +57,20 @@ function readFeaturesIn(baseDir, subdir, location) {
   return rows;
 }
 
-function buildRow(name, fj, fdir, location) {
+/** The feature's `worktree` pointer, normalized with a computed `exists`. */
+function readWorktreePointer(fj) {
+  const w = fj?.worktree;
+  if (!w?.path) return null;
+  return { path: w.path, branch: w.branch || null, exists: existsSync(w.path) };
+}
+
+/**
+ * Build a row's flags/gates/identity shape from a `feature.json` object, given
+ * an already-resolved phase and provenance. Shared by the disk read
+ * (`buildRow`) and the branch read (`resolveBranchTruth`) so the two never
+ * drift on what counts as an anomaly.
+ */
+function shapeRow(name, fj, location, phase, { corruptDisk = false, worktree = null, source = 'disk', branch = null } = {}) {
   const gates = {};
   for (const g of G) gates[g] = fj.approvalGates?.[g]?.approved === true;
 
@@ -50,13 +80,14 @@ function buildRow(name, fj, fdir, location) {
   const selfAssessed = fj.approvalGates?.review?.selfAssessed === true;
 
   const flags = [];
-  if (fj.__corrupt) flags.push('corrupt');
+  if (corruptDisk) flags.push('corrupt');
   if (selfAssessed) flags.push('self-assessed-g3');
   // Identity + gate-order anomalies come from the shared rules
   // (core/state/feature-identity.js, core/state/gate-order.js) — same source
   // doctor reports from.
   for (const field of missingIdentity(fj)) flags.push(`missing-${field}`);
   for (const v of gateOrderViolations(fj.approvalGates)) flags.push(`gate-order:${v.gate}`);
+  if (worktree && !worktree.exists) flags.push('worktree-missing');
 
   return {
     feature: name,
@@ -64,23 +95,106 @@ function buildRow(name, fj, fdir, location) {
     description: fj.description || null,
     workType: fj.workType || 'feature',
     status: fj.status || 'unknown',
-    phase: location === 'archived' ? 'archived' : derivePhase(fdir),
+    phase: location === 'archived' ? 'archived' : phase,
     gates,
     selfAssessed,
     flags,
     location,
     createdAt: fj.createdAt || null,
     updatedAt: fj.updatedAt || null,
+    // Provenance — added for worktree-truth awareness. `worktree` is always
+    // read from the LOCAL disk copy (root-owned bookkeeping, stripped from
+    // branch-committed copies at birth) regardless of where `source` reads
+    // status/phase/gates from.
+    source,
+    branch,
+    worktree,
   };
 }
 
+function buildRow(name, fj, fdir, location) {
+  const phase = location === 'archived' ? 'archived' : derivePhase(fdir);
+  return shapeRow(name, fj, location, phase, {
+    corruptDisk: Boolean(fj.__corrupt),
+    worktree: readWorktreePointer(fj),
+    source: 'disk',
+    branch: null,
+  });
+}
+
+/**
+ * Refresh active rows from the branch that owns their truth, when the disk
+ * copy in THIS tree is not that owner. Never throws — a git hiccup or a
+ * corrupt blob just leaves the disk-read row in place.
+ *
+ * @param {string} cwd
+ * @param {object[]} rows - mutated in place (active rows only)
+ */
+function resolveBranchTruth(cwd, rows) {
+  if (!isGitRepo(cwd)) return;
+  let head;
+  let branches;
+  try {
+    head = currentBranch(cwd);
+    branches = morphBranches(cwd);
+  } catch { return; }
+  if (!branches || branches.size === 0) return;
+
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    if (row.location === 'archived') continue;
+    if (!branches.has(row.feature)) continue;
+    const featureBranch = `morph/${row.feature}`;
+    if (head === featureBranch) continue; // cwd IS the checkout — disk is freshest, never go backwards
+    const view = branchView(cwd, row.feature, featureBranch);
+    if (!view?.fj) continue;
+    const phase = derivePhaseFrom(view.fj, (rel) => view.files.has(rel));
+    rows[i] = shapeRow(row.feature, view.fj, row.location, phase, {
+      corruptDisk: row.flags.includes('corrupt'),
+      worktree: row.worktree, // root-owned — never trust the branch copy for this
+      source: 'branch',
+      branch: featureBranch,
+    });
+  }
+}
+
+/**
+ * Flag an active row whose feature ALSO has an archived copy in this tree —
+ * the signature left behind when a feature is merged and archived on its
+ * branch (or via GitHub) without `morph-spec finish` ever running here:
+ * the untracked root skeleton from `create` survives `git pull` (it was
+ * never tracked, so pull has nothing to remove) while `.morph/archive/{f}`
+ * arrives for real. Flagging beats suppressing the row — a read-only board
+ * that resurrects or prunes nothing must not silently hide the anomaly either.
+ */
+function flagArchivedElsewhere(cwd, rows) {
+  for (const row of rows) {
+    if (row.location !== 'active') continue;
+    if (existsSync(join(cwd, '.morph', 'archive', row.feature, 'feature.json'))) {
+      row.flags.push('archived-elsewhere');
+    }
+  }
+}
+
 const mark = (on) => (on ? chalk.green('✓') : chalk.gray('·'));
 const truncate = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
 
+function whereLabel(row) {
+  if (row.location === 'archived') return '-';
+  if (row.worktree) return row.worktree.exists ? `worktree ${basename(row.worktree.path)}` : '⚠ worktree ausente';
+  if (row.source === 'branch') return `branch ${row.branch}`;
+  return 'raiz';
+}
+
 export function listCommand(options = {}) {
   const cwd = options.cwd || process.cwd();
   const rows = readFeaturesIn(cwd, 'features', 'active');
   if (options.all || options.archived) rows.push(...readFeaturesIn(cwd, 'archive', 'archived'));
+
+  flagArchivedElsewhere(cwd, rows);
+  // Commander's `--no-branch` sets options.branch = false; anything else (undefined/true) reads the branch.
+  if (options.branch !== false) resolveBranchTruth(cwd, rows);
+
   rows.sort((a, b) => a.feature.localeCompare(b.feature));
 
   if (options.json) {
@@ -95,16 +209,16 @@ export function listCommand(options = {}) {
 
   const col = (s, w) => String(s ?? '-').padEnd(w);
   console.log(chalk.white.bold(
-    col('FEATURE', 22) + col('TYPE', 9) + col('STATUS', 13) + col('PHASE', 11)
+    col('FEATURE', 22) + col('TYPE', 9) + col('STATUS', 13) + col('PHASE', 11) + col('WHERE', 22)
     + col('G1', 4) + col('G2', 4) + col('G3', 4) + col('', 3) + 'DESCRIPTION',
   ));
   for (const r of rows) {
     const flag = r.flags.length ? chalk.yellow('⚠') : ' ';
     const desc = (r.selfAssessed ? chalk.yellow('[G3 self-assessed] ') : '')
-      + (r.description ? truncate(r.description, 44) : chalk.yellow('(sem descrição)'));
+      + (r.description ? truncate(r.description, 34) : chalk.yellow('(sem descrição)'));
     // padEnd counts the invisible color codes; pad the plain marks manually.
     console.log(
-      col(r.feature, 22) + col(r.workType, 9) + col(r.status, 13) + col(r.phase, 11)
+      col(r.feature, 22) + col(r.workType, 9) + col(r.status, 13) + col(r.phase, 11) + col(whereLabel(r), 22)
       + mark(r.gates.proposal) + '   ' + mark(r.gates.plan) + '   ' + mark(r.gates.review) + '   '
       + flag + ' ' + desc,
     );

package/src/commands/state/score.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { getFeature, updateFeature } from '../../core/state/state-manager.js';
+import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 
 /** Fixed --dims order: a,c,q,t (mirrors the morph-eval dimension weights). */
 const DIM_KEYS = ['architecture', 'contracts', 'codeQuality', 'testCoverage'];
@@ -33,6 +34,14 @@ export async function scoreCommand(featureName, taskId, scoreArg, options = {})
       process.exit(1);
     }
 
+    const owner = assertOwnerTree(featureName, process.cwd());
+    if (owner.blocked) {
+      for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec score ${featureName} ${taskId} ${scoreArg}`)) {
+        console.error(chalk[tone](text));
+      }
+      process.exit(1);
+    }
+
     if (feature.taskVerifications?.[taskId]?.status === 'fail') {
       console.error(chalk.yellow(`⚠️  Último verify de ${taskId} está VERMELHO — score sendo gravado sobre código que não passou no verify determinístico`));
     }

package/src/lib/generators/handoff-generator.js

@@ -126,9 +126,15 @@ function nextAction(feature, phase, tasks, featureName) {
  *
  * @param {string} featureName
  * @param {string} [cwd]
+ * @param {{ worktree?: {path:string, branch:string}|null }} [opts] - override
+ *   the `worktree` bookkeeping instead of reading `feature.worktree`. Needed
+ *   because that field is ROOT-OWNED and stripped from every branch-local
+ *   copy at birth (create.js) — a handoff built FROM the worktree's own copy
+ *   would otherwise always say "no worktree registered", even while sitting
+ *   inside one. Pass `undefined` (the default) to fall back to `feature.worktree`.
  * @returns {{ markdown: string, meta: { generatedAt: string, phase: string, tasksDone: number, tasksTotal: number } } | null}
  */
-export function buildHandoff(featureName, cwd = process.cwd()) {
+export function buildHandoff(featureName, cwd = process.cwd(), opts = {}) {
   const featureDir = join(cwd, '.morph', 'features', featureName);
   if (!existsSync(join(featureDir, 'feature.json'))) return null;
 
@@ -150,7 +156,7 @@ export function buildHandoff(featureName, cwd = process.cwd()) {
   const tasks = taskSummary(featureDir);
   const env = readWorktreeEnv(cwd);
   const decisions = decisionTitles(featureDir);
-  const worktree = feature.worktree || null;
+  const worktree = opts.worktree !== undefined ? opts.worktree : (feature.worktree || null);
 
   const gates = feature.approvals || feature.approvalGates || {};
   const gateLine = Object.entries(gates)
@@ -253,10 +259,11 @@ function ensureHandoffExcluded(cwd) {
  *
  * @param {string} featureName
  * @param {string} [cwd]
+ * @param {{ worktree?: {path:string, branch:string}|null }} [opts] - see buildHandoff
  * @returns {string|null}
  */
-export function writeHandoff(featureName, cwd = process.cwd()) {
-  const result = buildHandoff(featureName, cwd);
+export function writeHandoff(featureName, cwd = process.cwd(), opts = {}) {
+  const result = buildHandoff(featureName, cwd, opts);
   if (!result) return null;
   const path = join(cwd, '.morph', 'features', featureName, 'handoff.md');
   try {

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.
  *