@polymorphism-tech/morph-spec 8.27.0 → 8.28.0

package/src/commands/state/delete.js

@@ -2,7 +2,8 @@ import chalk from 'chalk';
 import { existsSync, rmSync, renameSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, resolve, sep } from 'path';
 import { execSync } from 'child_process';
-import { isValidFeatureName } from '../project/worktree.js';
+import { isValidFeatureName, cwdIsInsideWorktree, teardownWorktree, resolvePrimaryRoot } from '../project/worktree.js';
+import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
 
 /**
  * `morph-spec delete <feature>` — remove a feature. Hard by default (folder is
@@ -111,6 +112,57 @@ export async function deleteCommand(featureName, options = {}) {
       process.exit(1);
     }
 
+    // A live worktree elsewhere owns this feature's REAL state — deleting the
+    // root's registration here would orphan the worktree + branch silently
+    // (no `no-feature` audit hit either: featureCommittedOnBranch stays true).
+    // Distinct consent from --force on purpose: --force answers "approved gate
+    // present, delete anyway" (a STATE risk); a live worktree is a FILESYSTEM
+    // risk (orphan directory, junctions into the primary root) — the same
+    // reasoning that keeps `worktree remove`'s PROVE-or-DECLINE separate from
+    // gate policy.
+    const owner = resolveFeatureTree(featureName, cwd);
+    const liveElsewhere = (owner.source === 'registry' || owner.source === 'pointer') && owner.tree;
+    if (liveElsewhere) {
+      if (!options.withWorktree) {
+        const payload = { error: 'feature-has-worktree', feature: featureName, worktree: { path: owner.tree, branch: owner.branch } };
+        if (options.json) { console.log(JSON.stringify(payload)); process.exit(1); }
+        console.error(chalk.red(`\n❌ "${featureName}" tem um worktree vivo em ${owner.tree}.`));
+        console.error(chalk.gray('   Feche com `morph-spec finish <feature> --pr|--merge` se o trabalho vale,'));
+        console.error(chalk.gray(`   ou \`morph-spec worktree remove ${featureName}\` e rode o delete de novo,`));
+        console.error(chalk.gray(`   ou \`morph-spec delete ${featureName} --with-worktree\` para fazer os dois num passo.\n`));
+        process.exit(1);
+      }
+
+      if (cwdIsInsideWorktree(cwd, owner.tree)) {
+        const payload = { error: 'cwd-inside-worktree', feature: featureName, path: owner.tree };
+        if (options.json) { console.log(JSON.stringify(payload)); process.exit(1); }
+        console.error(chalk.red(`\n❌ Rode fora do worktree antes de removê-lo: ${owner.tree}\n`));
+        process.exit(1);
+      }
+
+      // PROVE-or-DECLINE first — only delete the feature's own copy if the
+      // worktree actually came down. A refusal here must leave EVERYTHING
+      // untouched, same contract as `worktree remove`.
+      const root = resolvePrimaryRoot(cwd);
+      const teardown = await teardownWorktree(owner.tree, {
+        root,
+        feature: featureName,
+        branch: owner.branch,
+        options: { discardIgnored: options.discardIgnored === true },
+        deleteBranch: options.deleteBranch === true, // kept by default — it is the work
+      });
+      if (!teardown.worktreeRemoved) {
+        const payload = { error: 'worktree-removal-failed', feature: featureName, declineReason: teardown.declineReason };
+        if (options.json) { console.log(JSON.stringify(payload)); process.exit(1); }
+        console.error(chalk.red(`\n❌ Não foi possível remover o worktree — nada foi apagado.`));
+        console.error(chalk.gray(`   ${teardown.declineReason || 'motivo desconhecido'}\n`));
+        process.exit(1);
+      }
+      // Fall through: the feature's own .morph/features/{featureName} copy in
+      // `cwd` (the primary root, by construction of `liveElsewhere`) is deleted
+      // by the normal flow below, exactly as if there had never been a worktree.
+    }
+
     const useGit = isGitRepo(cwd) && options.git !== false;
 
     if (options.archive) {
@@ -156,10 +208,17 @@ export async function deleteCommand(featureName, options = {}) {
         execSync(`git rm -r -f --quiet "${featuresPath}"`, { cwd, stdio: 'pipe' });
         staged = true;
       } catch {
-        // Untracked (never committed) — just remove it from disk.
-        rmSync(featuresPath, { recursive: true, force: true });
-        try { execSync(`git add -A "${featuresPath}"`, { cwd, stdio: 'pipe' }); staged = true; } catch { /* not fatal */ }
+        // Untracked (never committed) — nothing for git rm to act on.
       }
+      // `git rm` only ever removes TRACKED files — a scaffolded phase folder
+      // with no artifact in it (0-proposal/ with nothing written yet) has no
+      // tracked blob and survives as an empty directory on disk. This bit
+      // real after --with-worktree: teardownWorktree's own registration-clear
+      // commits the root's feature.json on its way through, so `git rm`
+      // SUCCEEDS on that one file while the sibling empty folders it never
+      // tracked are left behind. Unconditional sweep closes both paths at once.
+      if (existsSync(featuresPath)) rmSync(featuresPath, { recursive: true, force: true });
+      try { execSync(`git add -A "${featuresPath}"`, { cwd, stdio: 'pipe' }); staged = true; } catch { /* not fatal */ }
     } else {
       rmSync(featuresPath, { recursive: true, force: true });
     }

package/src/commands/state/finish.js

@@ -483,7 +483,15 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
 
     if (options.keep) {
       dropFromRootIndex(root, feature);
-      emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false, ...backupNote, ...ucNote });
+      // Worktree preserved on purpose: the root's `worktree` registration stays
+      // VALID (it still names a live directory), so nothing to clean up here —
+      // only report where it lives and how to close it later.
+      emit({
+        finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false,
+        worktree: { path: worktreePath, branch: expectedBranch },
+        hint: `worktree preservado em ${worktreePath} — feche depois com \`morph-spec worktree remove ${feature}\`.`,
+        ...backupNote, ...ucNote,
+      });
       process.exit(0);
     }
 
@@ -574,7 +582,17 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     ...(shedBackup ? { shedBackup } : {}),
     ...(teardown
       ? { worktreeRemoved: teardown.worktreeRemoved, ...teardownExtras(teardown, worktreePath, expectedBranch, false) }
-      : { worktreeRemoved: false }),
+      : {
+        worktreeRemoved: false,
+        // isWorktreeFlow && options.keep is the only way `teardown` stays null
+        // with a worktree still alive — the common flow has none to report.
+        ...(isWorktreeFlow && options.keep
+          ? {
+            worktree: { path: worktreePath, branch: expectedBranch },
+            hint: `worktree preservado em ${worktreePath} — feche depois com \`morph-spec worktree remove ${feature}\`.`,
+          }
+          : {}),
+      }),
   };
   emit(out);
   process.exit(0);

package/src/commands/state/gate-check.js

@@ -6,6 +6,7 @@ import { shouldPauseGate, getRiskSignals } from '../../lib/risk-detector.js';
 import { evaluatorCompositeScore } from '../../lib/evaluator-report.js';
 import { persistGateDecision, VALID_GATES, readTrustFromConfig } from './gate-decision.js';
 import { detectDefaultBranch, getHeadSha, getDiffStat } from '../../lib/git/default-branch.js';
+import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 
 /**
  * `--signals` on `gate-check` is NOT a general override like `gate-decision`'s
@@ -154,6 +155,18 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
+    // Owner-tree guard: gate-check reads workType/tasks/scores/git off cwd
+    // AND writes the resulting decision through persistGateDecision — both
+    // halves are wrong from a tree that isn't this feature's own, so refuse
+    // rather than compute a decision from stale reads and then fail to save it.
+    const owner = assertOwnerTree(featureName, process.cwd());
+    if (owner.blocked) {
+      for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec gate-check ${featureName} ${gateName}`)) {
+        console.error(chalk[tone](text));
+      }
+      process.exit(1);
+    }
+
     let overrides = {};
     if (options.signals !== undefined) {
       let parsed;

package/src/commands/state/gate-decision.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';
 
 export const VALID_GATES = ['proposal', 'uiux', 'plan', 'review'];
 
@@ -96,6 +97,14 @@ export async function gateDecisionCommand(featureName, gateName, 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 gate-decision ${featureName} ${gateName} --pause ${pause}`)) {
+        console.error(chalk[tone](text));
+      }
+      process.exit(1);
+    }
+
     let signals = {};
     if (options.signals !== undefined) {
       try {

package/src/commands/state/handoff.js

@@ -9,18 +9,32 @@
  * in-process by `worktree setup`, `create --worktree`, `advance` and
  * `approve` — the CLI surface exists for the LLM/user to refresh the
  * document on demand.
+ *
+ * WORKTREE-AWARE: `create --worktree` writes a COMPLETE feature.json into the
+ * primary root and the branch-committed copy (`morph/{f}`) becomes the truth
+ * from then on. Building the handoff from `process.cwd()` unconditionally
+ * used to mean: run this from the root while the worktree is alive, and you
+ * either got "Feature not found" (root's copy was already sheded) or a
+ * document silently built from the stale birth skeleton, written INTO the
+ * root (a second, always-defasada copy of a document that's supposed to be
+ * regenerated, not duplicated). This resolves the owning tree first
+ * (`resolveFeatureTree`) and writes THERE, unless `--here` forces the cwd.
  */
 
 import chalk from 'chalk';
 import { buildHandoff, writeHandoff } from '../../lib/generators/handoff-generator.js';
+import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
 
 /**
  * @param {string} featureName
- * @param {{ json?: boolean }} [options]
+ * @param {{ json?: boolean, here?: boolean }} [options]
  */
 export function handoffCommand(featureName, options = {}) {
-  const result = buildHandoff(featureName, process.cwd());
-  if (!result) {
+  const cwd = process.cwd();
+
+  const owner = options.here ? { source: 'cwd', tree: cwd, branch: null, worktree: null } : resolveFeatureTree(featureName, cwd);
+
+  if (owner.source === 'none') {
     if (options.json) {
       console.log(JSON.stringify({ error: 'feature-not-found', feature: featureName }));
     } else {
@@ -29,10 +43,35 @@ export function handoffCommand(featureName, options = {}) {
     process.exit(1);
   }
 
-  const path = writeHandoff(featureName, process.cwd());
+  if (owner.source === 'branch-only') {
+    // The truth exists, committed on morph/{feature}, but is not materialized
+    // into ANY tree right now. A handoff points at files on disk — pointing
+    // at files that exist nowhere is worse than recusing outright.
+    const hint = `morph-spec worktree setup ${featureName}  (ou: git checkout ${owner.branch})`;
+    if (options.json) {
+      console.log(JSON.stringify({ error: 'feature-not-in-tree', feature: featureName, branch: owner.branch, hint }));
+    } else {
+      console.error(chalk.red(`\n❌ "${featureName}" está commitada em \`${owner.branch}\`, mas não está materializada em árvore nenhuma.`));
+      console.error(chalk.gray(`   ${hint}\n`));
+    }
+    process.exit(1);
+  }
+
+  const tree = owner.tree;
+  const result = buildHandoff(featureName, tree, { worktree: owner.worktree });
+  if (!result) {
+    if (options.json) {
+      console.log(JSON.stringify({ error: 'feature-not-found', feature: featureName, tree }));
+    } else {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+    }
+    process.exit(1);
+  }
+
+  const path = writeHandoff(featureName, tree, { worktree: owner.worktree });
   if (!path) {
     if (options.json) {
-      console.log(JSON.stringify({ error: 'write-failed', feature: featureName }));
+      console.log(JSON.stringify({ error: 'write-failed', feature: featureName, tree }));
     } else {
       console.error(chalk.red(`\n❌ Could not write handoff.md for ${featureName}\n`));
     }
@@ -40,11 +79,14 @@ export function handoffCommand(featureName, options = {}) {
   }
 
   if (options.json) {
-    console.log(JSON.stringify({ path, feature: featureName, ...result.meta }));
+    console.log(JSON.stringify({ path, feature: featureName, tree, source: owner.source, ...result.meta }));
     return;
   }
 
   console.log(chalk.green(`\n✅ Handoff gerado: ${path}`));
+  if (tree !== cwd) {
+    console.log(chalk.yellow(`   resolvido para ${tree} — a cópia da raiz é esqueleto de nascimento, não a verdade.`));
+  }
   console.log(chalk.gray(`   fase ${result.meta.phase} · tasks ${result.meta.tasksDone}/${result.meta.tasksTotal} · ${result.meta.generatedAt}`));
   console.log(chalk.gray('   A próxima sessão lê este documento antes de continuar (ponteiros, não cópias).\n'));
 }

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 {