@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

package/src/commands/project/worktree.js

@@ -1006,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 —
@@ -1296,19 +1303,46 @@ function classifyRemovalError(stderr) {
  * @returns {Promise<{ removed: boolean, failure: {kind: string, detail: string}|null }>}
  */
 async function attemptWorktreeRemoval(worktreePath, root) {
-  let lastStderr = '';
+  const stderrs = [];
   for (let round = 0; round < 2; round++) {
     for (const args of [['worktree', 'remove', worktreePath], ['worktree', 'remove', '--force', worktreePath]]) {
       try {
         execFileSync('git', args, { cwd: root, stdio: 'pipe' });
         return { removed: true, failure: null };
       } catch (err) {
-        lastStderr = err?.stderr ? String(err.stderr) : (err?.message || '');
+        stderrs.push(err?.stderr ? String(err.stderr) : (err?.message || ''));
       }
     }
     if (round === 0) await new Promise((r) => setTimeout(r, 200));
   }
-  return { removed: false, failure: classifyRemovalError(lastStderr) };
+  return { removed: false, failure: pickRemovalFailure(stderrs) };
+}
+
+/**
+ * Which of the attempts' errors the user should read.
+ *
+ * The LAST one used to win, and it was the worst choice: when the first
+ * `git worktree remove` deletes the content and de-registers the tree but the
+ * directory itself is held (a session with its cwd there), every later attempt
+ * answers only `'…' is not a working tree` — an echo that hid the real cause
+ * (the lock) and made the hint send the user to a command that can no longer
+ * reach the tree. A lock anywhere wins; otherwise the first REAL error wins.
+ *
+ * @param {string[]} stderrs - one entry per failed attempt, in order
+ * @returns {{ kind: string, detail: string, alreadyDeregistered: boolean }}
+ */
+export function pickRemovalFailure(stderrs) {
+  const list = (stderrs || []).map((s) => String(s || '')).filter((s) => s.trim());
+  const notAWorktree = (s) => /is not a working tree/i.test(s);
+  const classified = list.map(classifyRemovalError);
+  const firstReal = list.findIndex((s) => !notAWorktree(s));
+  const chosen = classified.find((c) => c.kind === 'in-use')
+    || (firstReal >= 0 ? classified[firstReal] : classified[classified.length - 1])
+    || { kind: 'unknown', detail: '' };
+  // Git dropped the registration BETWEEN attempts: a failure for another reason
+  // followed by "is not a working tree". Only the directory is left.
+  const alreadyDeregistered = firstReal >= 0 && list.slice(firstReal + 1).some(notAWorktree);
+  return { ...chosen, alreadyDeregistered };
 }
 
 /**
@@ -1444,6 +1478,10 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
           ? `worktree NÃO removido: o backup falhou. Estes arquivos existem só neste worktree e a remoção os apagaria: ${sample(ignored.shieldable)}. `
             + (ignored.replicable.length ? `(${sample(ignored.replicable)} são idênticos aos da raiz — esses não são o problema.) ` : '')
             + `O backup iria para \`${backupDir}\`; libere espaço/permissão ali e rode \`${removeCmd}\`, ou copie os arquivos você mesmo e rode \`${removeCmd} --discard-ignored\` para pular o backup`
+          : removalFailure?.alreadyDeregistered
+            ? `worktree NÃO removido por inteiro: a 1ª tentativa do git já apagou o conteúdo e desregistrou o worktree, mas o diretório "${worktreePath}" ficou`
+              + (removalFailure.kind === 'in-use' ? ' — EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd nele)' : '')
+              + `${removalFailure.detail ? ` (${removalFailure.detail})` : ''}. \`${removeCmd}\` não o alcança mais — o git não o conhece. Feche o que o usa, confira que está vazio e sem junction, e apague só o diretório (sem recursão)`
           : removalFailure?.kind === 'in-use'
             ? `worktree NÃO removido: o diretório está EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd em "${worktreePath}"). A infra compartilhada ficou DESMONTADA de propósito — feche o que está usando o diretório e rode \`${removeCmd}\`. Se preferir continuar trabalhando nele, restaure a infra com \`morph-spec worktree link --all\``
             : `worktree NÃO removido: a remoção falhou${removalFailure?.detail ? ` (${removalFailure.detail})` : ''}. A infra compartilhada ficou DESMONTADA de propósito — rode \`${removeCmd}\` para tentar de novo, ou \`morph-spec worktree link --all\` para voltar a trabalhar nele`;
@@ -1490,6 +1528,30 @@ export function cwdIsInsideWorktree(cwd, worktreePath) {
   return cwdNorm === wtNorm || cwdNorm.startsWith(`${wtNorm}/`);
 }
 
+/**
+ * Is the Claude Code SESSION that ran this command anchored in the worktree?
+ *
+ * Not the same question as `cwdIsInsideWorktree`. That one sees the PROCESS
+ * cwd, and `cd <root> && morph-spec finish` answers it "no" — while the session
+ * stays anchored in the worktree: its CLAUDE_PROJECT_DIR is the worktree, and
+ * every project hook runs `node "$CLAUDE_PROJECT_DIR/.morph/framework/hooks/…"`.
+ * Tearing that worktree down unlinks the junction those hooks resolve through,
+ * and the directory stays held by the session — so the removal fails half-way
+ * and every hook of every later tool call dies with MODULE_NOT_FOUND.
+ *
+ * The anchor arrives as MORPH_SESSION_PROJECT_DIR, exported by the
+ * `worktree-env-inject` PreToolUse hook (the Bash tool does not export
+ * CLAUDE_PROJECT_DIR itself); CLAUDE_PROJECT_DIR is honoured when present.
+ *
+ * @param {string} worktreePath
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function sessionAnchoredInWorktree(worktreePath, env = process.env) {
+  const anchor = env.MORPH_SESSION_PROJECT_DIR || env.CLAUDE_PROJECT_DIR || '';
+  return anchor ? cwdIsInsideWorktree(anchor, worktreePath) : false;
+}
+
 // ── remove ───────────────────────────────────────────────────────────────
 
 /**
@@ -1573,6 +1635,16 @@ 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);
   }
 
+  // The SESSION's anchor, not the process cwd (see sessionAnchoredInWorktree):
+  // refusing here, before the junctions are touched, leaves the session's hooks
+  // intact. Unlike finish there is nothing else to do in this command, so the
+  // refusal IS the deferral.
+  if (sessionAnchoredInWorktree(worktreePath)) {
+    const again = featureAddressable && feature ? `morph-spec worktree remove ${feature}` : `morph-spec worktree remove --target "${worktreePath}"`;
+    emit({ removed: false, error: 'session-anchored-in-worktree', path: worktreePath, root,
+      hint: `a sessão do Claude Code que rodou este comando está ancorada neste worktree — os hooks dela resolvem \`.morph/framework\` por ele, e desmontá-lo quebraria todo tool call seguinte (e o diretório seguiria travado pela sessão). Feche esta sessão e rode \`${again}\` de uma sessão aberta em "${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

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`));