@polymorphism-tech/morph-spec 8.6.0 → 8.7.0

package/framework/rules/morph-task-tracking.md

@@ -33,11 +33,18 @@ TaskUpdate(taskId, subject="Round 3 — score 82/100")
 
 ## Persisting Progress to `tasks.json`
 
+> **Dois sistemas, dois vocabulários.** Tudo acima desta linha é sobre as *session
+> tasks* nativas do Claude Code (`TaskCreate`/`TaskUpdate`), cujo status terminal é
+> `completed`. Tudo abaixo é sobre o `tasks.json` do morph-spec, governado por
+> `.morph/framework/schemas/tasks.schema.json`, cujo status terminal é `done` —
+> **`completed` não existe nesse enum** e o hook `protect-spec-files` rejeita a
+> gravação. Não misture os dois.
+
 Native session tasks (`TaskCreate`/`TaskUpdate`) track your live work. To persist
 task progress for the feature, write `.morph/features/{feature}/2-plan/tasks.json`,
 touching ONLY the mutable fields:
 
-- `status` — `pending` → `in_progress` → `completed`
+- `status` — `pending` → `in_progress` → `done` (também: `skipped`, `blocked`)
 - `outputs` — the files the task produced
 - `notes` — free-text record (deviations, context, resolved blockers)
 
@@ -53,17 +60,16 @@ output.
 ## Deviation Tracking
 
 When completing a task differently than originally planned, record the reason in the
-task's `notes` field. Use the `notes` array to capture deviations, added context, or
-resolved blockers — for example:
+task's `notes` field. `notes` is **uma única string** (o schema declara
+`"notes": { "type": "string" }`) — para registrar mais de um desvio, separe-os com
+`;` ou `\n` dentro da mesma string. Um array é **rejeitado** pelo validador, com a
+mensagem `'notes' must be a string`.
 
 ```json
 {
   "id": "T3",
-  "status": "completed",
+  "status": "done",
   "outputs": ["Features/User/Update/Handler.cs"],
-  "notes": [
-    "deviation: split validation into a separate validator for testability",
-    "blocker-resolved: EF migration conflict fixed by regenerating the snapshot"
-  ]
+  "notes": "deviation: split validation into a separate validator for testability; blocker-resolved: EF migration conflict fixed by regenerating the snapshot"
 }
 ```

package/framework/rules/morph-workflow.md

@@ -72,6 +72,39 @@ All outputs go in `.morph/features/{feature}/`:
 
 ---
 
+## Formato obrigatório do `3-implement/recap.md`
+
+> Esta exigência é **cobrada por hook** (`validate-completion`, no Stop). Ela está aqui, na regra
+> sempre-ativa, e não só na skill `morph-implement`: descobrir o formato quando o hook dispara
+> significa reescrever o recap depois de a fase já estar dada por encerrada.
+
+**Para CADA task com `status: "done"` em `tasks.json`**, o recap precisa de um bloco próprio:
+
+1. um heading `## T{N}` (o hook casa `^## T\d+` — uma linha de tabela `| T1 | … | done |` conta
+   como menção, **não** como bloco);
+2. uma linha `**Standard:** {standard-id}` **dentro de 12 linhas** do heading. Sem standard que
+   cubra o caso, registre a decisão em `decisions.md` e cite
+   `**Standard:** ad-hoc (see decisions.md ADR-{N})`.
+
+```markdown
+## T{N} — {title}
+
+**Standard:** {standard-id} (`.morph/framework/standards/{path}.md`)
+**Persona:** {mecanismo real usado}
+**Files:**
+- `{path}`
+
+{2-3 frases sobre o que foi feito}
+
+**Issues encontrados:** {breve descrição ou "nenhum"}
+```
+
+O `validate-completion` também acusa **drift**: uma task que aparece como concluída no recap mas
+ainda está `pending`/`in_progress` no `tasks.json`. Template completo e regras de exceção em
+`morph-implement` §6.
+
+---
+
 ## Checkpoints
 
 Run a checkpoint every 3 completed tasks:
@@ -158,7 +191,7 @@ During implementation, these skills MUST be invoked at the specified triggers:
 | Trigger | Skill | When |
 |---------|-------|------|
 | Before each task | `superpowers:test-driven-development` | Invoke BEFORE writing any code for a task |
-| Before marking a task complete | `morph-verification-before-completion` | Invoke BEFORE setting a task's `status` to `completed` in `tasks.json` |
+| Before marking a task complete | `morph-verification-before-completion` | Invoke BEFORE setting a task's `status` to `done` in `tasks.json` |
 | On bug/unexpected | `superpowers:systematic-debugging` | Invoke IF a bug or unexpected behavior is encountered |
 | After all tasks | `morph-post-implementation` | Invoke AFTER all tasks completed |
 | Before PR | `morph-checklist` | Invoke BEFORE creating pull request |

package/framework/schemas/feature.schema.json

@@ -222,7 +222,8 @@
       "properties": {
         "approved": { "type": "boolean" },
         "timestamp": { "type": ["string", "null"], "description": "ISO timestamp of the approval/revocation, null while never evaluated." },
-        "approvedBy": { "type": ["string", "null"], "description": "\"auto\" (approve/advance --mode auto), \"manual\" (human in the loop), \"policy:{workType}\" (gate stamped at birth by `morph-spec create` per the work type's skippedGates — see src/core/work-types.js; the gate-guard hook only special-cases \"auto\", so policy-stamped gates stay silent to it), a --approver name, or null while never evaluated." }
+        "approvedBy": { "type": ["string", "null"], "description": "\"auto\" (approve/advance --mode auto), \"manual\" (human in the loop), \"policy:{workType}\" (gate stamped at birth by `morph-spec create` per the work type's skippedGates — see src/core/work-types.js; the gate-guard hook only special-cases \"auto\", so policy-stamped gates stay silent to it), a --approver name, or null while never evaluated." },
+        "selfAssessed": { "type": "boolean", "description": "Gate `review` SOMENTE. `true` quando o Gate 3 foi aprovado sem `4-review/evaluator-report.md`, via `morph-spec approve <f> review --self-assessed`. O score composto deveria vir do avaliador independente; esta flag registra a degradação em vez de deixá-la silenciosa, e aparece no `morph-spec list`." }
       },
       "additionalProperties": true
     }

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # create-umbraco-lp

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # migrate-lp-to-umbraco

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-apply

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-brainstorming

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-hotfix

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-implement

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-plan

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-proposal

package/framework/skills/core/morph-review/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-review
@@ -74,6 +74,12 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    - **Leia primeiro** `.morph/features/{feature}/4-review/evaluator-report.md` — é o valor de retorno autoritativo, não a mensagem de texto do dispatch (que é cortesia, útil só quando chega inteira). Os scores por dimensão e o composto do review-report vêm **desse arquivo**, não da sua auto-avaliação. Se o arquivo vier ausente, oco, ou sem os scores por dimensão, registre a falha de protocolo na seção de método do review-report e re-despache.
 
 5. Produza `review-report.md` em `.morph/features/{feature}/4-review/` com:
+   - **`**Reviewed-SHA:** {git rev-parse HEAD}`** — o commit que você revisou, **obrigatório**.
+     Um review revisa uma ÁRVORE, e a árvore anda: sem esse carimbo, um relatório escrito antes
+     da última task fica no repo afirmando números e cobertura que já não valem. O
+     `morph-spec approve {feature} review` compara o carimbo com o HEAD e **recusa** se divergirem
+     (aconteceu de verdade: relatório de `b30ac6e` sobrevivendo à T3, que inverteu o default de
+     uma regra de negócio, e ainda dizendo `976/976` quando eram 982).
    - Scores por dimensão (arquitetura, contratos, qualidade, cobertura)
    - Score composto final
    - Lista de itens bloqueantes (se houver) — com descrição e critério de resolução

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-stack-scan

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.6.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-standards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.6.0",
+  "version": "8.7.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/project/claim.js

@@ -0,0 +1,91 @@
+/**
+ * `morph-spec claim [feature] [--release] [--list]` — the manual half of
+ * advisory feature ownership (B1).
+ *
+ * Claims are acquired and heartbeaten AUTOMATICALLY (SessionStart hook +
+ * telemetry hook), so the operator never has to remember anything. This command
+ * exists for the case automation cannot cover: a session that died without
+ * releasing, leaving a claim that keeps warning everyone until its TTL expires.
+ *
+ * Read-only by default (`--list`); the only mutation is `--release`.
+ * Always exits 0 except on a genuine misuse — the claim system is advisory and
+ * must never become a source of hard failures.
+ */
+
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import { resolve } from 'path';
+import { isGitRepo, resolvePrimaryRoot } from './worktree.js';
+import { listClaims, releaseClaim, claimAge } from '../../../framework/hooks/shared/claim-registry.js';
+
+/** Resolve the repo's shared git common dir — where claims live. */
+function gitCommonDirOf(cwd) {
+  const root = resolvePrimaryRoot(cwd);
+  const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
+  return common ? resolve(root, common) : null;
+}
+
+/**
+ * @param {string|undefined} feature
+ * @param {{ release?: boolean, list?: boolean, json?: boolean, cwd?: string }} [options]
+ */
+export function claimCommand(feature, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  if (!isGitRepo(cwd)) {
+    console.log(chalk.gray('Fora de um repositório git — não há registro de claims.'));
+    process.exit(0);
+  }
+
+  let gitCommonDir = null;
+  try {
+    gitCommonDir = gitCommonDirOf(cwd);
+  } catch { gitCommonDir = null; }
+  if (!gitCommonDir) {
+    console.log(chalk.gray('Não foi possível resolver o git common dir — nenhum claim a mostrar.'));
+    process.exit(0);
+  }
+
+  if (options.release) {
+    if (!feature) {
+      console.error(chalk.red('\n❌ --release exige o nome da feature: morph-spec claim <feature> --release\n'));
+      process.exit(1);
+    }
+    const released = releaseClaim(feature, { gitCommonDir });
+    if (options.json) {
+      console.log(JSON.stringify({ feature, released }));
+      process.exit(0);
+    }
+    console.log(released
+      ? chalk.green(`\n✅ Claim de "${feature}" liberado.\n`)
+      : chalk.yellow(`\n⚠️  Nenhum claim registrado para "${feature}" — nada a liberar.\n`));
+    process.exit(0);
+  }
+
+  // Default and --list are the same read: the whole board, or one feature.
+  const all = listClaims(gitCommonDir);
+  const rows = feature ? all.filter((c) => c.feature === feature) : all;
+
+  if (options.json) {
+    console.log(JSON.stringify(rows));
+    process.exit(0);
+  }
+
+  if (!rows.length) {
+    console.log(chalk.gray(feature
+      ? `Nenhum claim para "${feature}".`
+      : 'Nenhuma feature reclamada — nenhuma sessão registrada.'));
+    process.exit(0);
+  }
+
+  const col = (s, w) => String(s ?? '-').padEnd(w);
+  console.log(chalk.white.bold(col('FEATURE', 24) + col('ESTADO', 10) + col('VISTO HÁ', 12) + col('PID', 9) + 'ONDE'));
+  for (const c of rows) {
+    const state = c.live ? chalk.yellow('viva') : chalk.gray('morta');
+    console.log(
+      col(c.feature, 24) + state + ' '.repeat(Math.max(1, 10 - (c.live ? 4 : 5)))
+      + col(claimAge(c), 12) + col(c.pid, 9) + (c.path || '-'),
+    );
+  }
+  console.log(chalk.gray('\nClaims são AVISOS, nunca bloqueios. Claim órfão: `morph-spec claim <f> --release`'));
+  process.exit(0);
+}

package/src/commands/project/doctor.js

@@ -428,7 +428,67 @@ async function doctorMcpCommand(targetPath) {
   logger.blank();
 }
 
+/**
+ * `morph-spec doctor --worktrees [--prune]` — reconcile git's worktree registry
+ * with the directories on disk and the features morph knows (C2).
+ *
+ * Orphan worktrees used to accumulate invisibly: `fleet` only reports worktrees
+ * on a `morph/*` branch, so anything else never showed up anywhere.
+ *
+ * `--prune` runs the one safe repair (`git worktree prune`: admin records for
+ * directories that are already gone). Deleting a directory that still exists is
+ * reported with the exact command, never performed — same PROVE-or-DECLINE
+ * discipline as the finish teardown.
+ */
+export async function doctorWorktreesCommand(targetPath, options = {}) {
+  const { auditWorktrees, pruneWorktrees } = await import('../../lib/worktree/worktree-audit.js');
+
+  if (options.prune) {
+    const before = auditWorktrees(targetPath).filter((i) => i.type === 'registered-missing').length;
+    const result = pruneWorktrees(targetPath);
+    if (result.pruned) logger.success(`git worktree prune: ${before} registro(s) órfão(s) removido(s).`);
+    else logger.warn(`prune falhou: ${result.error}`);
+  }
+
+  const issues = auditWorktrees(targetPath);
+
+  if (options.json) {
+    console.log(JSON.stringify({ issues }, null, 2));
+    return issues.length === 0;
+  }
+
+  logger.header('MORPH-SPEC Worktrees');
+  if (issues.length === 0) {
+    logger.success('Worktrees reconciliados — git, disco e features batem.');
+    return true;
+  }
+
+  logger.warn(`${issues.length} inconsistência(s):`);
+  for (const i of issues) {
+    console.log(`  ⚠ ${i.type}`);
+    console.log(`     ${i.detail}`);
+    console.log(`     → ${i.fix}`);
+  }
+  if (issues.some((i) => i.type === 'registered-missing') && !options.prune) {
+    logger.dim('\n  Rode `morph-spec doctor --worktrees --prune` para limpar os registros órfãos.');
+  }
+  return false;
+}
+
 export async function doctorCommand(options = {}) {
+  // `--json` and `--prune` only mean something under `--worktrees`. Falling
+  // through to the human health check would hand a script a banner and a table
+  // where it asked for JSON — a caller has no way to notice a flag that was
+  // dropped in silence, so refuse instead of pretending.
+  const scoped = ['json', 'prune'].filter((f) => options[f]);
+  if (scoped.length && !options.worktrees) {
+    const flags = scoped.map((f) => `--${f}`).join(' e ');
+    logger.error(`${flags} só se aplica${scoped.length > 1 ? 'm' : ''} a \`morph-spec doctor --worktrees\`.`);
+    logger.dim(`  Rode: morph-spec doctor --worktrees ${scoped.map((f) => `--${f}`).join(' ')}`);
+    process.exitCode = 1;
+    return false;
+  }
+
   // Reset mode: remove morph-managed settings entries
   if (options.reset) {
     const targetPath = process.cwd();
@@ -465,6 +525,11 @@ export async function doctorCommand(options = {}) {
     return doctorMcpCommand(process.cwd());
   }
 
+  // Worktree reconciliation mode (C2)
+  if (options.worktrees) {
+    return doctorWorktreesCommand(process.cwd(), options);
+  }
+
   const targetPath = process.cwd();
 
   logger.header('MORPH-SPEC Health Check');

package/src/commands/project/fleet.js

@@ -12,6 +12,7 @@
 
 import chalk from 'chalk';
 import { scanFleet } from '../../lib/worktree/fleet-scanner.js';
+import { claimAge } from '../../../framework/hooks/shared/claim-registry.js';
 
 /**
  * @param {{ json?: boolean, cwd?: string }} [options]
@@ -30,9 +31,33 @@ export function fleetCommand(options = {}) {
   }
 
   const col = (s, w) => String(s ?? '-').padEnd(w);
+
+  /**
+   * The REMOTO cell. `-` means "unknown" (no origin, or the probe failed) —
+   * deliberately the same glyph as "nothing there", because both mean "do not
+   * trust the local view alone". `local` is the confident negative.
+   */
+  const remoteCell = (r) => {
+    if (!r) return '-';
+    if (r.pr) return `PR #${r.pr.number}${r.pr.state && r.pr.state !== 'OPEN' ? ` (${r.pr.state.toLowerCase()})` : ''}`;
+    return r.pushed ? 'pushed' : 'local';
+  };
+
+  /**
+   * The CLAIM cell — who is on this feature right now (B1). A stale claim is
+   * shown as stale, not hidden: "nobody here" and "somebody died here" are
+   * different facts for the operator.
+   */
+  const claimCell = (c) => {
+    if (!c) return '-';
+    const age = claimAge(c);
+    return c.live ? chalk.yellow(`sessão (${age})`) : chalk.gray(`morta (${age})`);
+  };
+
   console.log(chalk.white.bold(
     col('FEATURE', 20) + col('TYPE', 9) + col('PHASE', 11) + col('TASKS', 8)
-    + col('GATES PEND.', 20) + col('WHERE', 24) + col('PORTS', 12) + col('HANDOFF', 9) + 'ATIVIDADE',
+    + col('GATES PEND.', 20) + col('WHERE', 24) + col('REMOTO', 16) + col('CLAIM', 16)
+    + col('PORTS', 12) + col('HANDOFF', 9) + 'ATIVIDADE',
   ));
   for (const e of fleet.entries) {
     const tasks = e.tasks ? `${e.tasks.done}/${e.tasks.total}` : '-';
@@ -44,11 +69,21 @@ export function fleetCommand(options = {}) {
       e.lastCommit ? `commit ${e.lastCommit}` : null,
       Number.isInteger(e.dirty) && e.dirty > 0 ? chalk.yellow(`${e.dirty} dirty`) : null,
     ].filter(Boolean).join(' · ') || '-';
+    // padEnd counts invisible color codes, so pad the claim cell on its plain
+    // length and append the padding by hand.
+    const claimPlain = e.claim ? `${e.claim.live ? 'sessão' : 'morta'} (${claimAge(e.claim)})` : '-';
     console.log(
       col(e.feature, 20) + col(e.workType || '-', 9) + col(e.phase, 11) + col(tasks, 8)
-      + col(gates, 20) + col(where, 24) + col(ports, 12) + col(handoff, 9) + activity,
+      + col(gates, 20) + col(where, 24) + col(remoteCell(e.remote), 16)
+      + claimCell(e.claim) + ' '.repeat(Math.max(1, 16 - claimPlain.length))
+      + col(ports, 12) + col(handoff, 9) + activity,
     );
   }
+  const claimed = fleet.entries.filter((e) => e.claim?.live);
+  if (claimed.length) {
+    console.log(chalk.yellow(`\n⚠ ${claimed.length} feature(s) com sessão ativa — confirme antes de finish/archive/delete.`));
+    console.log(chalk.gray("   Claim órfão de sessão morta: `morph-spec claim <f> --release`"));
+  }
   console.log(chalk.gray(`\nRaiz primária: ${fleet.root}`));
   process.exit(0);
 }

package/src/commands/project/worktree.js

@@ -1,7 +1,7 @@
 /**
  * MORPH-SPEC Worktree Command Suite
  *
- * Isolates feature work into per-feature git worktrees at .worktrees/{feature}/
+ * Isolates feature work into per-feature git worktrees at worktrees/{feature}/
  * on branch morph/{feature}, so each feature can run its own Claude Code
  * instance (v8 multi-instance, parallel-feature-development flow).
  *
@@ -34,6 +34,31 @@ import { execSync, execFileSync } from 'child_process';
 import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, readdirSync, cpSync } from 'fs';
 import { join, resolve, dirname, relative } from 'path';
 import chalk from 'chalk';
+import { detectDefaultBranch } from '../../lib/git/default-branch.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];
 
 // ── Pure helpers (exported for tests) ──────────────────────────────────────
 
@@ -47,7 +72,7 @@ import chalk from 'chalk';
  *
  * Mirrors the validation `morph-spec create` applies, and every worktree
  * subcommand enforces it for the same reason plus a sharper one: a feature name
- * flows into `.worktrees/{name}`, the branch `morph/{name}`, and from there into
+ * flows into `worktrees/{name}`, the branch `morph/{name}`, and from there into
  * git invocations. Characters like `& | ; > ^` are legal in a git refname but
  * are cmd.exe metacharacters — on Windows an unvalidated name turns any
  * string-interpolated git call into command injection, and makes a `finish`
@@ -121,7 +146,7 @@ export function worktreeExists(worktreePath, cwd = process.cwd()) {
 export function buildWorktreePath(feature, cwd = process.cwd(), options = {}) {
   const suffix = options.fresh ? `-${getDateSuffix()}` : '';
   const normalizedCwd = cwd.replace(/\\/g, '/');
-  return `${normalizedCwd}/.worktrees/${feature}${suffix}`;
+  return `${normalizedCwd}/${WORKTREES_DIR}/${feature}${suffix}`;
 }
 
 /**
@@ -421,14 +446,29 @@ export async function runWorktreeSetup(feature, options = {}) {
     }
   } catch { /* fail-open — malformed feature.json must never block setup */ }
 
+  let branchedFrom = null;
   try {
-    // Create branch if needed (based off current HEAD)
+    // Create branch if needed — off the DEFAULT branch, never the current HEAD.
+    // Branching from HEAD meant a root parked on some other `morph/{other}`
+    // gave the new feature that feature's commits, and every PR opened from
+    // this worktree carried the sibling's diff (A1). Symmetric with the common
+    // flow in create.js → branchCommonFlow.
+    //
+    // Fail-open, same as create: with no resolvable default (a repo whose
+    // default is neither `main`/`master` nor declared via origin/HEAD) the
+    // branch is still created — off HEAD — and `branchedFrom: null` reports it.
     if (!branchExists(branch, cwd)) {
-      execSync(`git branch ${branch}`, { cwd, stdio: 'pipe' });
+      const defaultBranch = detectDefaultBranch(cwd);
+      if (defaultBranch) {
+        execFileSync('git', ['branch', branch, defaultBranch], { cwd, stdio: 'pipe' });
+        branchedFrom = defaultBranch;
+      } else {
+        execFileSync('git', ['branch', branch], { cwd, stdio: 'pipe' });
+      }
     }
 
     // Create worktree directory parent if needed
-    const parentDir = join(cwd, '.worktrees');
+    const parentDir = join(cwd, WORKTREES_DIR);
     if (!existsSync(parentDir)) {
       mkdirSync(parentDir, { recursive: true });
     }
@@ -500,6 +540,7 @@ export async function runWorktreeSetup(feature, options = {}) {
       created: true,
       path: worktreePath,
       branch,
+      branchedFrom,
       feature,
       materialized: materialized.materialized,
       ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
@@ -1065,7 +1106,13 @@ async function clearRootWorktreeRegistration(root, feature) {
 export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true }) {
   // Drop the infra junctions FIRST, without following them — this is what makes
   // a removal survivable (see unlinkWorktreeInfraLinks). Runs unconditionally.
-  unlinkWorktreeInfraLinks(worktreePath, root);
+  //
+  // The ORDER IS LOAD-BEARING and must not be flipped: `git worktree remove`
+  // (and its --force fallback) follows reparse points OUT of the worktree and
+  // deletes the primary root's real `.claude/` and `.morph/framework/`.
+  // Whatever this unlink costs on a declined path is repaired by the rollback
+  // below — the reverse ordering has no repair, it destroys the installation.
+  const unlinked = unlinkWorktreeInfraLinks(worktreePath, root);
 
   const scan = findReparsePoints(worktreePath);
   const ignored = classifyIgnoredLeftovers(worktreePath, options);
@@ -1114,6 +1161,21 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     await clearRootWorktreeRegistration(root, feature);
   }
 
+  // Rollback (A4): the removal was refused or failed, so the worktree is still
+  // there — but without the junctions this function dropped up front, which is
+  // strictly worse than never having tried (the observed complaint: "um estado
+  // pior que não ter tentado"). Put them back so the worktree stays usable and
+  // the user can just re-run finish from the primary root. Fail-open: a failed
+  // re-link reports `relinked: false` and the caller falls back to telling the
+  // user to run `morph-spec worktree link --all`.
+  let relinked = false;
+  if (!worktreeRemoved && unlinked.length && existsSync(worktreePath)) {
+    try {
+      setupInfraLinks(worktreePath, root);
+      relinked = true;
+    } catch { relinked = false; }
+  }
+
   const declineReason = worktreeRemoved
     ? null
     : ignored.blocking.length
@@ -1132,6 +1194,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     ignoredBlocking: ignored.blocking,
     shieldable: ignored.shieldable,
     declineReason,
+    relinked,
   };
 }