@polymorphism-tech/morph-spec 8.6.0 → 8.8.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,
   };
 }
 

package/src/commands/state/advance.js

@@ -1,8 +1,12 @@
 import chalk from 'chalk';
-import { existsSync, mkdirSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { fileURLToPath } from 'url';
 import { getFeature, setApprovalGate, derivePhase } from '../../core/state/state-manager.js';
 import { unmetPrereqs } from '../../core/state/gate-order.js';
+import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
+
+const FRAMEWORK_DIR = fileURLToPath(new URL('../../../framework/', import.meta.url));
 
 /**
  * `morph-spec advance <feature>` — approve the current phase's gate AND scaffold
@@ -28,6 +32,41 @@ const NEXT_PHASE_DIR = {
   implement: '4-review',
 };
 
+/**
+ * The canonical artifacts the phase being CLOSED owes, per
+ * `framework/phases.json → phases[phase].requiredOutputs`, resolved to real
+ * filenames through OUTPUT_SCHEMA.
+ *
+ * Data-driven on purpose: adding an artifact to a phase must not need a code
+ * change here, and the list must never drift from the phase definition.
+ * Fail-open — an unreadable phases.json/OUTPUT_SCHEMA yields an empty list, so
+ * a broken install degrades to today's behaviour instead of blocking every
+ * advance.
+ *
+ * @param {string} phase
+ * @param {string} featurePath
+ * @returns {string[]} relative paths of the MISSING required artifacts
+ */
+function missingPhaseArtifacts(phase, featurePath) {
+  try {
+    const phasesPath = join(FRAMEWORK_DIR, 'phases.json');
+    const phases = JSON.parse(readFileSync(phasesPath, 'utf8')).phases || {};
+    const required = phases[phase]?.requiredOutputs || [];
+    const missing = [];
+    for (const outputType of required) {
+      // requiredOutputs already carries OUTPUT_SCHEMA's camelCase keys — an
+      // unknown key is skipped rather than guessed at.
+      const entry = OUTPUT_SCHEMA[outputType];
+      if (!entry?.filename || !entry?.phaseDir) continue;
+      const rel = `${entry.phaseDir}/${entry.filename}`;
+      if (!existsSync(join(featurePath, entry.phaseDir, entry.filename))) missing.push(rel);
+    }
+    return missing;
+  } catch {
+    return [];
+  }
+}
+
 /** Resolve who approved, honestly (mirrors approve.js — no fake human signatures). */
 function resolveApprovedBy(options) {
   if (options.approver) return options.approver;
@@ -54,6 +93,23 @@ export async function advanceCommand(featureName, options = {}) {
       return;
     }
 
+    // Phase-exit artifact check (D3): a phase transition must not step over the
+    // artifact the phase it is CLOSING owes. Observed: a feature reached review
+    // with NO 3-implement/recap.md — the file was written later, by hand, so
+    // the Gate 3 review had nothing to review. `implement` has no gate, which
+    // is precisely why nothing stopped it.
+    //
+    // `--force` bypasses (same deliberate-recovery role it already plays for
+    // gate order) but still names what was skipped — a silent bypass would be
+    // the defect again.
+    const missingArtifacts = missingPhaseArtifacts(phase, featurePath);
+    if (missingArtifacts.length && !options.force) {
+      console.error(chalk.red(`\n❌ A fase "${phase}" não pode ser encerrada — artefato(s) obrigatório(s) ausente(s):`));
+      for (const rel of missingArtifacts) console.error(chalk.gray(`   • ${rel}`));
+      console.error(chalk.gray('\n   Produza o artefato e rode de novo, ou passe --force para avançar assim mesmo.\n'));
+      process.exit(1);
+    }
+
     // 1) Approve the gate that completes the current phase.
     const gate = PHASE_GATE[phase];
     const approvedBy = resolveApprovedBy(options);
@@ -112,6 +168,9 @@ export async function advanceCommand(featureName, options = {}) {
     } catch { /* fail-open */ }
 
     console.log(chalk.green(`\n✅ Advanced "${featureName}" past the ${phase} phase.`));
+    if (missingArtifacts.length) {
+      console.log(chalk.yellow(`   ⚠️  --force: avançou SEM ${missingArtifacts.join(', ')}.`));
+    }
     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('');

package/src/commands/state/approve.js

@@ -1,10 +1,73 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { existsSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { getFeature, setApprovalGate, getApprovalGate, getApprovalHistory, derivePhase } from '../../core/state/state-manager.js';
 import { unmetPrereqs } from '../../core/state/gate-order.js';
 
+/**
+ * The literal token `review-report.md` carries to declare which tree it
+ * reviewed. Kept as one exported constant so the CLI parser, the warning text
+ * and the `morph-review` skill can never drift apart (the A5 lesson).
+ */
+export const REVIEWED_SHA_TOKEN = '**Reviewed-SHA:**';
+
+const REVIEWED_SHA_RE = /\*\*Reviewed-SHA:\*\*\s*([0-9a-f]{7,40})/i;
+
+/**
+ * Is the feature's `review-report.md` still describing the current tree?
+ *
+ * @param {string} featureName
+ * @returns {{ status: 'ok'|'stale'|'unstamped'|'skip', reviewed?: string, head?: string, ahead?: number }}
+ *   `skip` covers every case where the question cannot be answered honestly:
+ *   no report, no git repo, an unresolvable SHA. Never a false refusal.
+ */
+function reviewStaleness(featureName) {
+  const cwd = process.cwd();
+  const reportPath = join(cwd, '.morph', 'features', featureName, '4-review', 'review-report.md');
+  if (!existsSync(reportPath)) return { status: 'skip' };
+
+  let head;
+  try {
+    head = execFileSync('git', ['rev-parse', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
+  } catch {
+    return { status: 'skip' }; // not a git repo (or no commits) — nothing to compare
+  }
+
+  let body = '';
+  try {
+    body = readFileSync(reportPath, 'utf8');
+  } catch {
+    return { status: 'skip' };
+  }
+
+  const stamped = body.match(REVIEWED_SHA_RE)?.[1];
+  if (!stamped) return { status: 'unstamped', head };
+
+  let reviewed;
+  try {
+    reviewed = execFileSync('git', ['rev-parse', '--verify', `${stamped}^{commit}`], { cwd, stdio: 'pipe' })
+      .toString().trim();
+  } catch {
+    // A stamp git cannot resolve (rewritten history, a typo) is not evidence
+    // of staleness — say "unstamped" rather than block on a guess.
+    return { status: 'unstamped', head };
+  }
+  if (reviewed === head) return { status: 'ok', reviewed, head };
+
+  let ahead = 0;
+  try {
+    ahead = execFileSync('git', ['rev-list', '--count', `${reviewed}..${head}`], { cwd, stdio: 'pipe' })
+      .toString().trim();
+    ahead = Number(ahead) || 0;
+  } catch { ahead = 0; }
+
+  // HEAD not descending from the reviewed commit (a rebase, a different branch)
+  // is still "not the tree that was reviewed".
+  return { status: 'stale', reviewed, head, ahead };
+}
+
 /**
  * Unapprove action function - Revoke a previously approved gate
  */
@@ -155,12 +218,72 @@ export async function approveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
+    // Gate 3 evaluator backstop: the composite score of a feature comes from
+    // the INDEPENDENT evaluator (persona `evaluator`, fresh context) dispatched
+    // by morph-review — never from self-assessment by whoever implemented it.
+    // Nothing enforced that. When the dispatch was impossible (observed: a
+    // session instruction forbade sub-agents), the flow still produced a
+    // review-report.md carrying a composite score and a verdict, with a caveat
+    // in prose nobody is obliged to read. A gate that yields a grade without
+    // its evaluator is not a gate.
+    //
+    // The escape hatch is EXPLICIT and RECORDED (`--self-assessed`), never
+    // silent — the silence is the defect. `--force` deliberately does NOT
+    // bypass this: it is the out-of-order recovery flag, a different concern.
+    // Gate 3 staleness backstop (D1): a review reviews a TREE, and the tree
+    // moves. Observed: review-report.md written at b30ac6e, then T3 landed and
+    // inverted the default of a business rule; the report stayed in the repo
+    // claiming 976/976 tests (they were 982) and never mentioning T3. Nothing
+    // detected that the review artifact had fallen behind the code it reviews.
+    //
+    // The report stamps the SHA it reviewed; approval compares it with HEAD.
+    // A stamp that is BEHIND HEAD refuses. A MISSING stamp only warns — reports
+    // written before this existed must not brick a legacy feature — but the
+    // warning names the exact token to add, so it teaches instead of nagging.
+    if (gateName === 'review') {
+      const stale = reviewStaleness(featureName);
+      if (stale.status === 'stale') {
+        console.error(chalk.red('\n❌ O `4-review/review-report.md` está desatualizado em relação ao código.'));
+        console.error(chalk.gray(`   Revisado em: ${stale.reviewed.slice(0, 8)}`));
+        console.error(chalk.gray(`   HEAD atual:  ${stale.head.slice(0, 8)}${stale.ahead ? ` (${stale.ahead} commit(s) depois da revisão)` : ''}`));
+        console.error(chalk.gray('   Um review revisa uma ÁRVORE, e a árvore andou. Re-rode a `morph-review`'));
+        console.error(chalk.gray('   (incluindo o avaliador independente) e atualize o `**Reviewed-SHA:**`.\n'));
+        process.exit(1);
+      }
+      if (stale.status === 'unstamped') {
+        console.log(chalk.yellow('\n⚠️  O `review-report.md` não carrega `**Reviewed-SHA:**` — impossível saber se ele revisa o código atual.'));
+        console.log(chalk.gray(`   Adicione a linha \`**Reviewed-SHA:** ${stale.head}\` ao relatório para que o Gate 3 possa verificar.`));
+      }
+    }
+
+    let selfAssessed = false;
+    if (gateName === 'review') {
+      const evaluatorReport = join(process.cwd(), '.morph', 'features', featureName, '4-review', 'evaluator-report.md');
+      if (!existsSync(evaluatorReport)) {
+        if (!options.selfAssessed) {
+          console.error(chalk.red('\n❌ Gate 3 exige o avaliador independente — `4-review/evaluator-report.md` não existe.'));
+          console.error(chalk.gray('   O score composto da feature vem do avaliador (persona `evaluator`, contexto fresco)'));
+          console.error(chalk.gray('   despachado pela morph-review, nunca de auto-avaliação de quem implementou.'));
+          console.error(chalk.gray('   Se o dispatch for impossível nesta sessão, aprove com --self-assessed —'));
+          console.error(chalk.gray('   a degradação fica registrada no feature.json e aparece no `list`/`fleet`.\n'));
+          process.exit(1);
+        }
+        selfAssessed = true;
+      }
+    }
+
     await setApprovalGate(featureName, gateName, true, {
       approvedBy,
       approvedAt: new Date().toISOString(),
-      notes: options.notes
+      notes: options.notes,
+      ...(selfAssessed ? { selfAssessed: true } : {}),
     });
 
+    if (selfAssessed) {
+      console.log(chalk.yellow('\n⚠️  Gate 3 aprovado SEM avaliador independente (--self-assessed).'));
+      console.log(chalk.gray('   Registrado em feature.json → approvalGates.review.selfAssessed.'));
+    }
+
     console.log(chalk.green(`\n✅ Gate "${gateName}" approved for feature: ${featureName}`));
     console.log(chalk.gray(`Workflow can now proceed past ${gateName} phase\n`));
 

package/src/commands/state/create.js

@@ -186,9 +186,9 @@ export async function createCommand(featureName, options = {}) {
         if (worktreeResult?.created && worktreeResult.path) {
           try {
             // feature.json in the root is NOT committed yet (create just
-            // wrote it), so the branch `runWorktreeSetup` checked out from
-            // HEAD does not have it — copy the freshly-scaffolded folder
-            // into the worktree and re-materialize its local state.json.
+            // wrote it), so the branch `runWorktreeSetup` forked off the
+            // DEFAULT branch cannot have it — copy the freshly-scaffolded
+            // folder into the worktree and re-materialize its local state.json.
             cpSync(featureDir, join(worktreeResult.path, '.morph', 'features', featureName), { recursive: true });
             // The `.worktree` registration is ROOT-OWNED metadata (runWorktreeSetup
             // stamped it onto the root's feature.json, which cpSync just copied in).

package/src/commands/state/finish.js

@@ -12,8 +12,50 @@ import {
   branchExists,
 } from '../project/worktree.js';
 import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
+import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js';
 import { runArchive } from './archive.js';
 
+/** workType → conventional-commit type. `hotfix` IS a fix; anything else is a chore. */
+const PR_TYPE_BY_WORK_TYPE = { feature: 'feat', bug: 'fix', hotfix: 'fix', chore: 'chore' };
+
+/** Git's soft limit for a subject line. */
+const PR_TITLE_MAX = 72;
+
+/**
+ * The PR title for `finish --pr`.
+ *
+ * Was always `morph: {slug}` — so every PR in a repo whose hand-made ones follow
+ * conventional commits (`fix(ui): coluna CRM nos dossiês…`) arrived shapeless
+ * and said nothing about what changed (D4).
+ *
+ * Now: `{type}({slug}): {subject}` — the type from the feature's `workType`, the
+ * slug kept as the scope (it is the traceability the old title at least had),
+ * and the subject from the feature's own identity: `name` first (a human
+ * deliberately titled it), then `description`, first line only. With neither,
+ * degrade to `{type}: {slug}` rather than emit an empty subject.
+ *
+ * @param {string} feature
+ * @param {object|null} fj - the feature.json
+ * @returns {string}
+ */
+export function buildPrTitle(feature, fj) {
+  const type = PR_TYPE_BY_WORK_TYPE[fj?.workType] || 'chore';
+
+  const named = typeof fj?.name === 'string' ? fj.name.trim() : '';
+  // The default `name` IS the slug (create stamps it), which as a subject would
+  // only repeat the scope — treat it as absent.
+  const described = typeof fj?.description === 'string' ? fj.description.trim() : '';
+  const raw = (named && named !== feature ? named : described).split('\n')[0].trim();
+  if (!raw) return `${type}: ${feature}`;
+
+  const prefix = `${type}(${feature}): `;
+  const room = PR_TITLE_MAX - prefix.length;
+  // A scope so long there is no room left for a subject: drop the scope rather
+  // than ship a title that is all prefix.
+  if (room < 12) return `${type}: ${raw}`.slice(0, PR_TITLE_MAX);
+  return prefix + (raw.length <= room ? raw : `${raw.slice(0, room - 1)}…`);
+}
+
 /**
  * `morph-spec finish <feature> --pr|--merge` — the single, symmetric close of a
  * feature's lifecycle, for BOTH the worktree flow and the common flow.
@@ -37,9 +79,22 @@ import { runArchive } from './archive.js';
 export async function finishCommand(feature, options = {}) {
   const cwd = options.cwd || process.cwd();
   const root = resolvePrimaryRoot(cwd);
-  const emit = (obj) => console.log(JSON.stringify(obj));
   const rootNorm = resolve(root).replace(/\\/g, '/');
 
+  // A closed feature must not keep warning other sessions that someone is
+  // working on it (B1). Released on EVERY success path — hooking it into emit
+  // is the single point that covers merge/PR/--keep alike. Fail-open: a claim
+  // that outlives its feature only expires on its own TTL.
+  const emit = (obj) => {
+    if (obj?.finished === true) {
+      try {
+        const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: root, stdio: 'pipe' }).toString().trim();
+        if (common) releaseClaim(feature, { gitCommonDir: resolve(root, common) });
+      } catch { /* fail-open */ }
+    }
+    console.log(JSON.stringify(obj));
+  };
+
   // Gate 0: valid kebab name — anti command-injection (the name flows into every
   // git/gh call below) and the same gate the worktree path always applied.
   if (!isValidFeatureName(feature)) {
@@ -85,6 +140,28 @@ export async function finishCommand(feature, options = {}) {
     }
     worktreePath = found.path;
     featureCwd = worktreePath;
+
+    // Validation 0b: the session's cwd must not be INSIDE the worktree we are
+    // about to tear down (A4). Windows holds a lock on the process's working
+    // directory, so `git worktree remove` fails — and by then the archive is
+    // committed, the branch merged, and the infra junctions already dropped.
+    // The result is a worse state than never having tried: an orphan directory,
+    // a de-registered worktree, and a `relinkHint` telling the user to repair
+    // by hand. Refuse HERE, before the first mutation — the cost is one
+    // `cd`, and it is the exact failure observed in the ProspectPRO session.
+    const cwdNorm = resolve(cwd).replace(/\\/g, '/');
+    const wtNorm = resolve(worktreePath).replace(/\\/g, '/');
+    if (cwdNorm === wtNorm || cwdNorm.startsWith(`${wtNorm}/`)) {
+      emit({
+        finished: false,
+        error: 'cwd-inside-worktree',
+        feature,
+        path: worktreePath,
+        root,
+        hint: `saia do worktree antes do finish — o \`git worktree remove\` não consegue apagar o diretório de trabalho do próprio processo. Rode de novo a partir de "${root}"`,
+      });
+      process.exit(1);
+    }
   } else {
     // COMMON flow: the feature branch must exist and be the ROOT's current
     // branch (so the archive commits on it and we can checkout the default to
@@ -120,7 +197,7 @@ export async function finishCommand(feature, options = {}) {
     emit({ finished: false, error: 'review-not-approved', feature });
     process.exit(1);
   }
-  const prTitle = `morph: ${feature}`;
+  const prTitle = buildPrTitle(feature, fj);
   const prBody = (fj?.description && String(fj.description).trim())
     ? String(fj.description).trim()
     : `Feature ${feature} — integrada via morph-spec finish --pr.`;
@@ -346,7 +423,15 @@ function teardownExtras(teardown, worktreePath, branch, deleteBranch) {
     if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
     if (teardown.ignoredBlocking.length) out.ignoredFiles = teardown.ignoredBlocking;
     out.cleanupHint = teardown.declineReason;
-    out.relinkHint = `as junctions de infra foram soltas antes desta recusa — para continuar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
+    // The unlink runs before the removal by design (it is what keeps `git
+    // worktree remove` from following the junctions out into the primary root),
+    // so a declined removal always passes through a moment with the infra
+    // loose. The teardown now re-links on that path — report which of the two
+    // actually happened instead of always announcing the worse one (A4).
+    out.relinked = teardown.relinked === true;
+    out.relinkHint = teardown.relinked
+      ? 'as junctions de infra foram soltas antes da tentativa e RESTAURADAS após a recusa — o worktree segue utilizável'
+      : `as junctions de infra foram soltas antes desta recusa e não puderam ser restauradas — para continuar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
   }
   return out;
 }