@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/src/commands/project/worktree.js

@@ -13,7 +13,11 @@
  *
  * Subcommands:
  *   morph-spec worktree setup <feature> [--fresh]   — create + materialize state
+ *   morph-spec worktree provision <name> [--base <ref>]  — task-isolation tree
+ *     (branch morph-task/{name}, same infra, NO feature identity) — what the
+ *     WorktreeCreate hook calls for `claude -w` / EnterWorktree / Agent isolation
  *   morph-spec worktree link [--target <path>] [--all]  — (re)link shared infra
+ *   morph-spec worktree remove [<feature>|--target <path>] [--if-clean]  — safe teardown
  *   morph-spec worktree list [--json]  — list active feature worktrees
  *
  * Closing the lifecycle (integrate + teardown) lives in `morph-spec finish`
@@ -32,7 +36,7 @@
 
 import { execSync, execFileSync } from 'child_process';
 import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, cpSync } from 'fs';
-import { join, resolve, dirname } from 'path';
+import { join, resolve, dirname, basename } from 'path';
 import chalk from 'chalk';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
 import { triageIgnoredPaths } from '../../lib/worktree/ignored-triage.js';
@@ -40,29 +44,11 @@ import { triageIgnoredPaths } from '../../lib/worktree/ignored-triage.js';
 // the SAME answer this file does, and hooks can never import from `src/`.
 import { findReparsePoints } from '../../../framework/hooks/shared/reparse-scan.js';
 
-/**
- * The directory new worktrees are created under, relative to the primary root.
- *
- * NO leading dot, deliberately (C1). Jest escapes the `.` when it interpolates
- * an absolute `rootDir` into the `testMatch` glob, so `<root>/.worktrees/...`
- * stops matching and an entire frontend suite reports **0 tests without an
- * error** — the suite "passes" having tested nothing. The dot bought nothing:
- * the directory is gitignored either way.
- */
-export const WORKTREES_DIR = 'worktrees';
-
-/**
- * The pre-C1 directory name. New worktrees never land here, but every reader
- * that resolves worktrees BY CONVENTION must still accept it, so a machine
- * that already had `.worktrees/{f}` keeps working with no manual migration.
- *
- * Readers that go through `git worktree list` (fleet, finish, worktree list)
- * were never affected — git records absolute paths, not this convention.
- */
-export const LEGACY_WORKTREES_DIR = '.worktrees';
-
-/** Both names, new first — the read order for convention-based lookups. */
-export const WORKTREE_DIR_NAMES = [WORKTREES_DIR, LEGACY_WORKTREES_DIR];
+// The container name lives in lib/worktree/dirs.js (single source, C1
+// rationale documented there); re-exported here so existing importers and the
+// dependency-matrix row keep pointing at this file.
+import { WORKTREES_DIR, LEGACY_WORKTREES_DIR, WORKTREE_DIR_NAMES } from '../../lib/worktree/dirs.js';
+export { WORKTREES_DIR, LEGACY_WORKTREES_DIR, WORKTREE_DIR_NAMES };
 
 // ── Pure helpers (exported for tests) ──────────────────────────────────────
 
@@ -362,6 +348,43 @@ export function resolvePrimaryRoot(cwd = process.cwd()) {
  * @param {string} worktreePath - Absolute path to the worktree
  * @returns {Promise<{ materialized: boolean, reason?: string }>}
  */
+/**
+ * Guarantee the worktree owns a local `.morph/state.json`, hydrated from its
+ * committed features when there are any, and an EMPTY index otherwise.
+ *
+ * Why the empty index matters: every core hook fail-opens on `stateExists()`,
+ * which is true only with a `state.json` or a feature dir in the tree. A
+ * task-isolation worktree of a project with no committed features (measured
+ * in the sandbox e2e) had neither — so the env-inject hook, the removal guard
+ * and every other guardrail were silently dark inside it. `state.json` is
+ * gitignored and derivable, so an empty one costs nothing and can never dirty
+ * the tree the finish gates read.
+ *
+ * @param {string} worktreePath
+ * @returns {Promise<{ materialized: boolean, reason?: string, seeded?: boolean }>}
+ */
+export async function ensureLocalState(worktreePath) {
+  const result = await materializeState(worktreePath);
+  if (result.materialized) return result;
+  const statePath = join(worktreePath, '.morph', 'state.json');
+  if (existsSync(statePath)) return { ...result, materialized: true };
+  try {
+    const { atomicWriteJson } = await import('../../core/state/state-manager.js');
+    const now = new Date().toISOString();
+    mkdirSync(join(worktreePath, '.morph'), { recursive: true });
+    atomicWriteJson(statePath, {
+      version: '5.0.0',
+      project: { name: basename(worktreePath), type: 'unknown', createdAt: now, updatedAt: now },
+      features: {},
+      threads: {},
+      metadata: { totalFeatures: 0, completedFeatures: 0, totalTimeSpent: 0, lastUpdated: now },
+    });
+    return { materialized: true, seeded: true, reason: result.reason };
+  } catch (err) {
+    return { materialized: false, reason: (err && err.message) || result.reason };
+  }
+}
+
 export async function materializeState(worktreePath) {
   const featuresDir = join(worktreePath, '.morph', 'features');
   if (!existsSync(featuresDir)) {
@@ -490,33 +513,13 @@ export async function runWorktreeSetup(feature, options = {}) {
     setupInfraLinks(worktreePath, cwd);
 
     // Fleet env: allocate this feature's deterministic port block and write the
-    // worktree-local manifest (.morph/worktree.env), excluded from git via the
-    // same common-dir mechanism as the infra links (it must be invisible to the
-    // finish clean-checks). Under `.morph/` on purpose: that prefix is already
-    // shieldable at finish (backed up, never a removal blocker). Fail-open — a
-    // worktree without ports is degraded, never broken.
-    let envBlock = null;
-    try {
-      const { allocateEnvBlock, resolveFleetConfig, buildEnvFileContent } =
-        await import('../../lib/worktree/env-allocator.js');
-      const common = execSync('git rev-parse --git-common-dir', { cwd, stdio: 'pipe' }).toString().trim();
-      if (common) {
-        const gitCommonDir = resolve(cwd, common);
-        envBlock = allocateEnvBlock(feature, { gitCommonDir, ...resolveFleetConfig(cwd) });
-        let stack = '';
-        try {
-          const cfg = JSON.parse(readFileSync(join(cwd, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, ''));
-          stack = cfg?.project?.stack || '';
-        } catch { /* fail-open — stackless env still carries PORT */ }
-        mkdirSync(join(worktreePath, '.morph'), { recursive: true });
-        writeFileSync(join(worktreePath, '.morph', 'worktree.env'), buildEnvFileContent(feature, envBlock, stack), 'utf8');
-        excludeWorktreePaths(cwd, [join('.morph', 'worktree.env')]);
-      }
-    } catch { envBlock = null; /* fail-open */ }
+    // worktree-local manifest (.morph/worktree.env). Fail-open — a worktree
+    // without ports is degraded, never broken.
+    const envBlock = await allocateWorktreeEnv(worktreePath, cwd, feature);
 
     // Materialize a local, real state.json in the worktree (self-heal from the
     // committed feature.json files) so hooks work from the very first session.
-    const materialized = await materializeState(worktreePath);
+    const materialized = await ensureLocalState(worktreePath);
 
     // Fleet handoff: the fresh instance that opens this worktree reads
     // handoff.md before anything else (SessionStart hook points at it). The doc
@@ -578,6 +581,109 @@ export async function worktreeSetupCommand(feature, options = {}) {
   process.exit(exitCode);
 }
 
+// ── provision (task isolation — a worktree that is NOT a feature) ──────────
+
+/**
+ * Branch name for a task-isolation worktree: `morph-task/<name>`. A separate
+ * namespace from `morph/<feature>` on purpose — `worktree list`, `fleet`,
+ * `finish` and the SessionStart hook all read `morph/<f>` as "this IS feature
+ * f", and a scratch tree named after a feature must never impersonate it.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function buildTaskBranchName(name) {
+  return `morph-task/${name}`;
+}
+
+/**
+ * Non-exiting core of `worktree provision` — the tree `claude -w`,
+ * `EnterWorktree` and `Agent isolation:"worktree"` ask for when the name is
+ * not a feature. Everything `setup` gives a feature worktree EXCEPT the
+ * feature identity: it lands under `<primary root>/worktrees/<name>` (never
+ * nested under a secondary worktree, whatever the cwd), on `morph-task/<name>`
+ * off the default branch (or `--base`), with the infra junctions, a git-
+ * invisible `.morph/worktree.env` keyed `task/<name>`, and a materialized
+ * local state.json. No feature registration, no handoff.
+ *
+ * Exit codes mirror `setup`: 0 created (or fail-open), 1 refused (bad name),
+ * 2 already exists at this exact path.
+ *
+ * @param {string} name
+ * @param {{ base?: string, cwd?: string }} [options]
+ * @returns {Promise<{ ok: boolean, exitCode: 0|1|2, created: boolean, alreadyExists?: boolean, path?: string, branch?: string, branchedFrom?: string|null, kind?: 'task-isolation', name: string, env?: object, error?: string }>}
+ */
+export async function runWorktreeProvision(name, options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  if (!isValidFeatureName(name)) {
+    return { ok: false, exitCode: 1, created: false, error: 'invalid-name', name };
+  }
+  if (!isGitRepo(cwd)) {
+    return { ok: true, exitCode: 0, created: false, error: 'not-a-git-repo', name };
+  }
+
+  // Always the PRIMARY root: a provision issued from inside a feature worktree
+  // must not nest a worktree under it — that tree would be invisible to the
+  // fleet and to doctor, which enumerate `<root>/worktrees/`.
+  const root = resolvePrimaryRoot(cwd);
+  const branch = buildTaskBranchName(name);
+  const worktreePath = buildWorktreePath(name, root);
+
+  if (worktreeExists(worktreePath, root)) {
+    return { ok: true, exitCode: 2, created: false, alreadyExists: true, path: worktreePath, branch, kind: 'task-isolation', name };
+  }
+
+  let branchedFrom = null;
+  try {
+    if (!branchExists(branch, root)) {
+      const base = options.base || detectDefaultBranch(root);
+      if (base) {
+        execFileSync('git', ['branch', branch, base], { cwd: root, stdio: 'pipe' });
+        branchedFrom = base;
+      } else {
+        execFileSync('git', ['branch', branch], { cwd: root, stdio: 'pipe' });
+      }
+    }
+
+    const parentDir = join(root, WORKTREES_DIR);
+    if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
+
+    execFileSync('git', ['worktree', 'add', worktreePath, branch], { cwd: root, stdio: 'pipe' });
+
+    setupInfraLinks(worktreePath, root);
+    const envBlock = await allocateWorktreeEnv(worktreePath, root, `task/${name}`);
+    const materialized = await ensureLocalState(worktreePath);
+
+    return {
+      ok: true,
+      exitCode: 0,
+      created: true,
+      path: worktreePath,
+      branch,
+      branchedFrom,
+      kind: 'task-isolation',
+      name,
+      materialized: materialized.materialized,
+      ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
+    };
+  } catch (err) {
+    return { ok: true, exitCode: 0, created: false, error: (err.message || 'unknown').slice(0, 200), name };
+  }
+}
+
+/**
+ * `morph-spec worktree provision <name> [--base <ref>]` — thin wrapper around
+ * `runWorktreeProvision`, same JSON-and-exit contract as `setup`.
+ * @param {string} name
+ * @param {{ base?: string, cwd?: string }} [options]
+ */
+export async function worktreeProvisionCommand(name, options = {}) {
+  const { ok, exitCode, ...result } = await runWorktreeProvision(name, options);
+  console.log(JSON.stringify(result));
+  process.exit(exitCode);
+}
+
 /**
  * Command handler for `morph-spec worktree link [--target <path>] [--all]`.
  *
@@ -588,7 +694,7 @@ export async function worktreeSetupCommand(feature, options = {}) {
  *
  * @param {{ target?: string, all?: boolean, cwd?: string }} [options]
  */
-export function worktreeLinkCommand(options = {}) {
+export async function worktreeLinkCommand(options = {}) {
   const cwdArg = options.cwd || process.cwd();
   const root = resolvePrimaryRoot(cwdArg);
   const target = resolve(options.target || options.cwd || process.cwd()).replace(/\\/g, '/');
@@ -627,10 +733,79 @@ export function worktreeLinkCommand(options = {}) {
     }
   }
 
-  console.log(JSON.stringify({ linked, skipped, root, target }));
+  // `link --all` is the documented repair for a worktree missing its infra —
+  // that includes a `.morph/worktree.env` written by an older layout. The
+  // allocation is idempotent (same key → same block), so regenerating the
+  // manifest never moves a worktree's ports; it only adds the keys it lacks.
+  let env = null;
+  if (options.all) {
+    const key = envKeyForWorktree(target, root);
+    const block = key ? await allocateWorktreeEnv(target, root, key) : null;
+    if (block) env = { key, base: block.base, range: block.range };
+  }
+
+  console.log(JSON.stringify({ linked, skipped, root, target, ...(env ? { env } : {}) }));
   process.exit(0);
 }
 
+/**
+ * The env-registry key of a worktree, derived from its branch: `morph/<f>` →
+ * `<f>` (feature), `morph-task/<n>` → `task/<n>` (task isolation). `null` for
+ * a branch morph does not own — no block is allocated for those.
+ *
+ * @param {string} worktreePath
+ * @param {string} root
+ * @returns {string|null}
+ */
+export function envKeyForWorktree(worktreePath, root) {
+  const norm = resolve(worktreePath).replace(/\\/g, '/');
+  const entry = parseWorktreeList(root).find((e) => e.path === norm);
+  const branch = entry?.branch?.replace(/^refs\/heads\//, '') ?? null;
+  if (!branch) return null;
+  const feature = branch.match(/^morph\/(.+)$/)?.[1];
+  if (feature) return feature;
+  const task = branch.match(/^morph-task\/(.+)$/)?.[1];
+  return task ? `task/${task}` : null;
+}
+
+/**
+ * Allocate (idempotently) the port block for `envKey` and write the worktree's
+ * `.morph/worktree.env`, excluded from git via the same common-dir mechanism as
+ * the infra links (it must be invisible to the finish clean-checks). Under
+ * `.morph/` on purpose: that prefix is already shieldable at finish (backed up,
+ * never a removal blocker). Fail-open: returns `null` when no block could be
+ * written — a worktree without ports is degraded, never broken.
+ *
+ * Shared by `setup` (feature key), `provision` (task key) and `link --all`
+ * (regeneration), so the manifest has exactly one writer.
+ *
+ * @param {string} worktreePath
+ * @param {string} root - primary root
+ * @param {string} envKey - `<feature>` or `task/<name>`
+ * @returns {Promise<{ index: number, base: number, range: [number, number] }|null>}
+ */
+export async function allocateWorktreeEnv(worktreePath, root, envKey) {
+  try {
+    const { allocateEnvBlock, resolveFleetConfig, buildEnvFileContent } =
+      await import('../../lib/worktree/env-allocator.js');
+    const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
+    if (!common) return null;
+    const gitCommonDir = resolve(root, common);
+    const block = allocateEnvBlock(envKey, { gitCommonDir, ...resolveFleetConfig(root) });
+    let stack = '';
+    try {
+      const cfg = JSON.parse(readFileSync(join(root, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, ''));
+      stack = cfg?.project?.stack || '';
+    } catch { /* fail-open — stackless env still carries PORT */ }
+    mkdirSync(join(worktreePath, '.morph'), { recursive: true });
+    writeFileSync(join(worktreePath, '.morph', 'worktree.env'), buildEnvFileContent(envKey, block, stack), 'utf8');
+    excludeWorktreePaths(root, [join('.morph', 'worktree.env')]);
+    return block;
+  } catch {
+    return null;
+  }
+}
+
 // ── finish / list shared helpers ────────────────────────────────────────────
 
 /**
@@ -831,8 +1006,15 @@ function isLiveSiblingWorktreeRegistration(relPath, root, feature) {
  * @param {string} rootPath - the primary root, for the replica comparison
  * @param {{ discardIgnored?: boolean }} options
  * @returns {{ shieldable: string[], blocking: string[], discarded: string[], replicable: string[] }}
+ *
+ * EXPORTADA para que o `finish --dry-run` (pré-voo) responda EXATAMENTE a
+ * mesma pergunta que o teardown real vai responder. Uma segunda enumeração de
+ * `git status --ignored` no finish.js — com a sua própria cópia de
+ * IGNORED_SHIELDABLE_PREFIXES — faria o pré-voo prometer uma coisa e o
+ * comando fazer outra, que é a única maneira de um dry-run ser pior que
+ * nenhum. Consumida read-only: o pré-voo não copia, não apaga, não decide.
  */
-function classifyIgnoredLeftovers(worktreePath, rootPath, options = {}) {
+export function classifyIgnoredLeftovers(worktreePath, rootPath, options = {}) {
   let out;
   try {
     // `-z` + execFile: NUL-delimited, no shell, no C-style quoting to undo —
@@ -1338,7 +1520,7 @@ export function cwdIsInsideWorktree(cwd, worktreePath) {
  * closing a feature is still `morph-spec finish`.
  *
  * @param {string|undefined} featureArg
- * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, cwd?: string }} [options]
+ * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, ifClean?: boolean, cwd?: string }} [options]
  */
 export async function worktreeRemoveCommand(featureArg, options = {}) {
   const cwdArg = options.cwd || process.cwd();
@@ -1398,9 +1580,47 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
       hint: `saia do worktree antes de removê-lo — o processo trava o próprio diretório de trabalho. Rode de novo a partir de "${root}"` }, 1);
   }
 
+  // `--if-clean` — the WorktreeRemove hook's contract: Claude Code fires it
+  // when it believes the tree is disposable, but "disposable" is the user's
+  // call, not the harness's. Any uncommitted or untracked file refuses the
+  // removal BEFORE the junctions are touched, so a refusal leaves the tree
+  // exactly as it was (no rollback needed, nothing to relink). The infra
+  // links and the env manifest are excluded from git, so they never count.
+  if (options.ifClean) {
+    let status;
+    try {
+      status = execFileSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd: worktreePath, stdio: 'pipe' }).toString();
+    } catch {
+      emit({ removed: false, error: 'status-failed', path: worktreePath, root,
+        hint: 'não foi possível provar que o worktree está limpo — nada foi removido' }, 1);
+    }
+    const dirt = status.split(/\r?\n/).filter((l) => l.trim());
+    if (dirt.length) {
+      emit({ removed: false, error: 'worktree-dirty', path: worktreePath, root, dirt: dirt.slice(0, 20),
+        hint: `o worktree tem trabalho não commitado — commit ou descarte antes, ou rode \`morph-spec worktree remove --target "${worktreePath}"\` sem --if-clean para remover com backup` }, 1);
+    }
+  }
+
+  // The env-registry key this tree allocated under: `<f>` for morph/<f>,
+  // `task/<n>` for morph-task/<n>. Read BEFORE the teardown (the entry is gone
+  // from `git worktree list` afterwards). The old `'worktree'` placeholder
+  // meant every --target removal released a slot nobody held and leaked the
+  // one the tree actually used.
+  const envKey = envKeyForWorktree(worktreePath, root);
+
+  // The tree's compose stack goes down BEFORE the tree: a running bind-mounted
+  // container holds the directory (Windows) and turns a clean removal into a
+  // removalFailure. Volumes survive — removing a worktree is not closing the
+  // feature, and a re-`setup` should find its seeded database intact.
+  let e2e = null;
+  try {
+    const { tearDownFeatureStack } = await import('../../lib/e2e/stack-teardown.js');
+    e2e = tearDownFeatureStack(envKey || feature || basename(worktreePath), { root, worktreePath, volumes: false });
+  } catch { e2e = null; /* fail-open */ }
+
   const teardown = await teardownWorktree(worktreePath, {
     root,
-    feature: feature || 'worktree',
+    feature: feature || envKey || 'worktree',
     branch,
     options: { discardIgnored: options.discardIgnored === true },
     // Removing a worktree is not closing a feature: the branch is the work, and
@@ -1421,6 +1641,7 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
   // real `.claude/`/`.morph/framework/` were unlinked rather than followed; on
   // a refusal it is what `relinked` did or did not put back.
   if (teardown.unlinked.length) out.unlinked = teardown.unlinked;
+  if (e2e?.attempted) out.e2e = { status: e2e.status, cwd: e2e.cwd, volumes: false };
   if (teardown.worktreeRemoved) {
     if (teardown.discarded.length) out.discardedIgnored = teardown.discarded;
     // Broken out of `discardedIgnored` on purpose: "deleted" and "deleted

package/src/commands/state/advance.js

@@ -198,7 +198,23 @@ export async function advanceCommand(featureName, options = {}) {
       process.exit(1);
     }
 
-    if (gate) {
+    // Gate idempotency (F15): `setApprovalGate` REPLACES the gate object whole
+    // (state-manager.js), so re-writing an already-approved gate does not
+    // refresh it — it destroys `approvedBy`, `timestamp`, `notes` and
+    // `selfAssessed` in one assignment. And `resolveApprovedBy` above answers
+    // "auto" in every headless context, so `approve f proposal --approver
+    // lucas` followed by `advance f` used to rewrite a human's signature as
+    // "auto" — the one stamp the charter forbids on a human-approved gate.
+    // The state-sync hook already carries exactly this guard; `advance`, the
+    // other gate write-path, simply never got it.
+    //
+    // It skips ONLY the write. The scaffold and the handoff below still run,
+    // so re-running `advance` after a failed scaffold keeps working — the
+    // reason this is a guard and not an abort.
+    const priorGate = gate ? feature.approvalGates?.[gate] : null;
+    const alreadyApproved = priorGate?.approved === true;
+
+    if (gate && !alreadyApproved) {
       await setApprovalGate(featureName, gate, true, {
         approvedBy,
         approvedAt: new Date().toISOString(),
@@ -226,7 +242,13 @@ export async function advanceCommand(featureName, options = {}) {
     if (missingArtifacts.length) {
       console.log(chalk.yellow(`   ⚠️  --force: avançou SEM ${missingArtifacts.join(', ')}.`));
     }
-    if (gate) console.log(chalk.gray(`   Gate "${gate}" approved (${approvedBy}).`));
+    // Report what actually happened: claiming "approved (auto)" when nothing
+    // was written is how the destroyed signature stayed invisible.
+    if (gate && alreadyApproved) {
+      console.log(chalk.gray(`   Gate "${gate}" was already approved (${priorGate.approvedBy || 'unknown'}) — approval preserved, nothing re-written.`));
+    } else if (gate) {
+      console.log(chalk.gray(`   Gate "${gate}" approved (${approvedBy}).`));
+    }
     if (nextDir) console.log(chalk.gray(`   Scaffolded ${nextDir}/ — ready for the next phase's first artifact.\n`));
     else console.log('');
   } catch (error) {

package/src/commands/state/approve.js

@@ -180,7 +180,13 @@ export async function approveCommand(featureName, gateName, options = {}) {
     if (currentStatus?.approved) {
       console.log(chalk.yellow(`\n⚠️  Gate "${gateName}" is already approved`));
       console.log(chalk.gray(`Approved at: ${currentStatus.timestamp}`));
-      console.log(chalk.gray(`Approved by: ${currentStatus.approvedBy || 'Unknown'}\n`));
+      console.log(chalk.gray(`Approved by: ${currentStatus.approvedBy || 'Unknown'}`));
+      // This early-out is a no-op that still exits 0 — deliberate, and
+      // `--force` does NOT cover it (that flag only covers gate ORDER). A
+      // caller who meant to re-approve therefore reads success and is left
+      // with nowhere to go. The way out already exists as `unapprove`; the
+      // message just never named it. Naming it is the whole fix (no new flag).
+      console.log(chalk.gray(`To approve it again, revoke it first: morph-spec unapprove ${featureName} ${gateName}\n`));
       return;
     }
 
@@ -349,6 +355,32 @@ export async function approveCommand(featureName, gateName, options = {}) {
           }
           selfAssessed = true;
         }
+
+        // REAVALIAÇÃO VISÍVEL. O `evaluator-report.md` é append-only, então uma
+        // segunda rodada acrescenta um `**Composite-Score:**` ao fim e o arquivo
+        // passa a carregar mais de um veredito. O gate decide pelo ÚLTIMO (o
+        // vigente) — mas aprovar em silêncio um relatório com notas superadas
+        // esconde do humano exatamente o fato que ele precisa ver: a nota MUDOU,
+        // e numa das rodadas medidas em campo ela CAIU (8.9 → 8.3, quando uma
+        // correção abriu um bloqueante).
+        //
+        // Aqui é o lugar: `approve` é a precondição humana do Gate 3 e a única
+        // superfície onde uma pessoa lê o veredito antes de carimbá-lo. Sem este
+        // bloco, `scoreTokens`/`superseded` seriam mitigação inerte — campo que
+        // ninguém lê não mitiga nada.
+        if (report.status === 'ok' && report.scoreTokens > 1) {
+          console.log(chalk.yellow(
+            `
+⚠️  O relatório do avaliador tem ${report.scoreTokens} vereditos (o arquivo é append-only).`
+          ));
+          console.log(chalk.gray(`   Vigente (o que o gate usa): ${report.score}`));
+          console.log(chalk.gray(`   Superado(s), na ordem do arquivo: ${report.superseded.join(', ')}`));
+          if (report.superseded.some((n) => n > report.score)) {
+            console.log(chalk.yellow('   A nota CAIU em relação a uma rodada anterior — confira o que a correção'));
+            console.log(chalk.yellow('   abriu antes de aprovar; o relatório mantém a análise das duas rodadas.'));
+          }
+          console.log('');
+        }
       }
     }
 

package/src/commands/state/create.js

@@ -15,32 +15,61 @@ import { detectDefaultBranch } from '../../lib/git/default-branch.js';
  * `morph-spec finish` can later merge/PR it back. Symmetric with the worktree
  * flow, which gets its branch from `runWorktreeSetup`.
  *
+ * That checkout moves the dev's PRIMARY working tree, and `stdio: 'pipe'`
+ * swallows even git's own message — so the move is reported by the caller
+ * (`branchMoveWarning`), never silent. `checkout: false` (`--no-checkout`)
+ * still CREATES the branch — `finish --pr|--merge` depends on it existing in
+ * both flows — and only skips moving the tree.
+ *
  * Fail-open: outside a git repo, with no resolvable default, or on any git
  * error, the feature is simply left on the current branch — never a failed birth.
  *
  * @param {string} featureName
- * @returns {{ branched: boolean, branch?: string, from?: string, reason?: string }}
+ * @param {{ checkout?: boolean }} [opts] - `checkout: false` keeps the tree put
+ * @returns {{ branched: boolean, checkedOut: boolean, branch?: string, from?: string,
+ *             movedFrom?: string, stayedOn?: string, reason?: string }}
+ *   `movedFrom` is present ONLY when the working tree actually moved (it names
+ *   the branch left behind); `stayedOn` only when the move was declined.
  */
-function branchCommonFlow(featureName) {
+function branchCommonFlow(featureName, { checkout = true } = {}) {
   const cwd = process.cwd();
   try {
-    if (!isGitRepo(cwd)) return { branched: false, reason: 'not-a-git-repo' };
+    if (!isGitRepo(cwd)) return { branched: false, checkedOut: false, reason: 'not-a-git-repo' };
     const branch = buildBranchName(featureName);
     const defaultBranch = detectDefaultBranch(cwd);
-    if (!defaultBranch) return { branched: false, reason: 'no-default-branch' };
+    if (!defaultBranch) return { branched: false, checkedOut: false, reason: 'no-default-branch' };
     if (!branchExists(branch, cwd)) {
       execFileSync('git', ['branch', branch, defaultBranch], { cwd, stdio: 'pipe' });
     }
     const current = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
-    if (current !== branch) {
-      execFileSync('git', ['checkout', branch], { cwd, stdio: 'pipe' });
-    }
-    return { branched: true, branch, from: defaultBranch };
+    // Already there: nothing moved, so nothing to warn about.
+    if (current === branch) return { branched: true, checkedOut: true, branch, from: defaultBranch };
+    if (!checkout) return { branched: true, checkedOut: false, branch, from: defaultBranch, stayedOn: current };
+    execFileSync('git', ['checkout', branch], { cwd, stdio: 'pipe' });
+    return { branched: true, checkedOut: true, branch, from: defaultBranch, movedFrom: current };
   } catch {
-    return { branched: false, reason: 'git-error' };
+    return { branched: false, checkedOut: false, reason: 'git-error' };
   }
 }
 
+/**
+ * The alert for a checkout that MOVED. Built once and rendered on both
+ * surfaces — stdout (human) and stderr (under `--json`, so it survives a
+ * stdout redirect) — so the two can never drift apart.
+ *
+ * @param {{ branch: string, movedFrom: string }} branchResult
+ * @returns {string[]} lines, unstyled and unindented
+ */
+function branchMoveWarning({ branch, movedFrom }) {
+  return [
+    `⚠️  Working tree MOVED: ${movedFrom} → ${branch}`,
+    `   This checkout is now ON the feature branch — uncommitted work came along,`,
+    `   and anything committed here from now on lands on ${branch}, not ${movedFrom}.`,
+    `   Use --no-checkout to create the branch without moving the tree, or --worktree`,
+    `   (the recommended route for parallel work) to isolate the feature in its own tree.`,
+  ];
+}
+
 /** Feature names are kebab-case: lowercase alphanumerics and hyphens. */
 const FEATURE_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 
@@ -130,6 +159,24 @@ export async function createCommand(featureName, options = {}) {
       process.exit(1);
     }
 
+    // `--no-checkout` pede que o checkout PRINCIPAL não se mova; `--worktree`
+    // nunca o move — a feature nasce numa árvore separada, e o caminho de
+    // worktree sequer chama `branchCommonFlow`, que é o único leitor do flag.
+    // Aceitar a combinação em silêncio é dizer que o CLI honrou um pedido que
+    // ele ignorou — o mesmo anti-padrão que esta série de fixes tirou do
+    // `finish --pr --push`. Recusa ALTA, e AQUI: junto das outras validações
+    // de forma, ANTES de `createFeature` — a primeira mutação do `create`.
+    // Uma recusa depois dela deixaria a feature nascida por um comando que
+    // falhou, pior que o no-op que ela substitui.
+    if (options.worktree && options.checkout === false) {
+      console.error(chalk.red(`\n❌ no-checkout-with-worktree: --no-checkout não se combina com --worktree`));
+      console.error(chalk.gray(`   O --worktree já não move o checkout desta árvore: a feature nasce em worktrees/${featureName},`));
+      console.error(chalk.gray(`   na branch morph/${featureName}, e o caminho de worktree nem chega a ler o --no-checkout.`));
+      console.error(chalk.gray(`   Para isolar a feature na própria árvore:  morph-spec create ${featureName} --worktree`));
+      console.error(chalk.gray(`   Para criar só a branch morph/${featureName} sem mover esta árvore:  morph-spec create ${featureName} --no-checkout\n`));
+      process.exit(1);
+    }
+
     const now = new Date().toISOString();
     const { workType, workTypeDetection } = resolveWorkType(options, now);
 
@@ -225,7 +272,8 @@ export async function createCommand(featureName, options = {}) {
       } else {
         // Common flow: still isolate the feature on its own branch so `finish`
         // can merge/PR it back. Fail-open (see branchCommonFlow).
-        branchResult = branchCommonFlow(featureName);
+        // Commander's `--no-checkout` sets options.checkout === false.
+        branchResult = branchCommonFlow(featureName, { checkout: options.checkout !== false });
       }
     }
 
@@ -238,6 +286,11 @@ export async function createCommand(featureName, options = {}) {
       const out = { feature: featureName, created, ...finalFeature };
       if (worktreeResult) out.worktree = worktreeResult;
       if (branchResult) out.branch = branchResult;
+      // The move of the PRIMARY checkout is never silent — under --json it goes
+      // to stderr so it survives `... --json > out.json` instead of vanishing.
+      if (branchResult?.movedFrom) {
+        console.error(chalk.yellow(branchMoveWarning(branchResult).join('\n')));
+      }
       console.log(JSON.stringify(out, null, 2));
       return;
     }
@@ -262,7 +315,15 @@ export async function createCommand(featureName, options = {}) {
         }
       } else if (branchResult?.branched) {
         console.log(chalk.green(`   branch: ${branchResult.branch} (from ${branchResult.from})`));
-        console.log(chalk.gray(`   close it with: morph-spec finish ${featureName} --pr | --merge\n`));
+        console.log(chalk.gray(`   close it with: morph-spec finish ${featureName} --pr | --merge`));
+        if (branchResult.movedFrom) {
+          // Alert, not one more success line: the tree the dev is standing in moved.
+          console.log('');
+          for (const line of branchMoveWarning(branchResult)) console.log(chalk.yellow(`   ${line}`));
+        } else if (branchResult.checkedOut === false) {
+          console.log(chalk.gray(`   working tree left on ${branchResult.stayedOn} (--no-checkout)`));
+        }
+        console.log('');
       }
     } else {
       console.log(chalk.yellow(`\n⚠️  Feature "${featureName}" already exists — left untouched`));

package/src/commands/state/delete.js

@@ -4,6 +4,7 @@ import { join, resolve, sep } from 'path';
 import { execSync } from 'child_process';
 import { isValidFeatureName, cwdIsInsideWorktree, teardownWorktree, resolvePrimaryRoot } from '../project/worktree.js';
 import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
+import { tearDownFeatureStack } from '../../lib/e2e/stack-teardown.js';
 
 /**
  * `morph-spec delete <feature>` — remove a feature. Hard by default (folder is
@@ -144,6 +145,13 @@ export async function deleteCommand(featureName, options = {}) {
       // worktree actually came down. A refusal here must leave EVERYTHING
       // untouched, same contract as `worktree remove`.
       const root = resolvePrimaryRoot(cwd);
+      // The feature's verification stack (containers, ports, volumes, stamp)
+      // comes down BEFORE its worktree: the compose file and the bind mount
+      // live there, and a deleted feature has nothing to keep a volume for.
+      // Fail-open by contract — a stubborn container never blocks the delete.
+      try {
+        tearDownFeatureStack(featureName, { root, worktreePath: owner.tree, volumes: true });
+      } catch { /* fail-open */ }
       const teardown = await teardownWorktree(owner.tree, {
         root,
         feature: featureName,