@polymorphism-tech/morph-spec 8.1.2 → 8.2.1

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.1.2"
+cliVersion: "8.2.1"
 ---
 
 # 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.1.2"
+cliVersion: "8.2.1"
 ---
 
 # morph-standards

package/package.json

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

package/src/commands/project/fleet.js

@@ -0,0 +1,54 @@
+/**
+ * `morph-spec fleet [--json]` — the fleet view.
+ *
+ * One line per active feature across the primary root and every morph/*
+ * worktree: phase, pending gates, task progress, port block, handoff
+ * freshness, last commit and dirtiness. This is the terminal surface the
+ * operator scans between sessions ("what is each instance doing, what is
+ * waiting on me") — `worktree list` remains the lean per-worktree view.
+ *
+ * Read-only, always exits 0 (fail-open — an empty fleet is an answer).
+ */
+
+import chalk from 'chalk';
+import { scanFleet } from '../../lib/worktree/fleet-scanner.js';
+
+/**
+ * @param {{ json?: boolean, cwd?: string }} [options]
+ */
+export function fleetCommand(options = {}) {
+  const fleet = scanFleet(options.cwd || process.cwd());
+
+  if (options.json) {
+    console.log(JSON.stringify(fleet));
+    process.exit(0);
+  }
+
+  if (!fleet.entries.length) {
+    console.log(chalk.gray('Frota vazia — nenhuma feature ativa (raiz ou worktrees).'));
+    process.exit(0);
+  }
+
+  const col = (s, w) => String(s ?? '-').padEnd(w);
+  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',
+  ));
+  for (const e of fleet.entries) {
+    const tasks = e.tasks ? `${e.tasks.done}/${e.tasks.total}` : '-';
+    const gates = e.pendingGates.length ? e.pendingGates.join(',') : '-';
+    const where = e.location === 'worktree' ? e.branch : 'raiz';
+    const ports = e.env ? `${e.env.range[0]}-${e.env.range[1]}` : '-';
+    const handoff = e.handoff?.exists ? 'sim' : '-';
+    const activity = [
+      e.lastCommit ? `commit ${e.lastCommit}` : null,
+      Number.isInteger(e.dirty) && e.dirty > 0 ? chalk.yellow(`${e.dirty} dirty`) : null,
+    ].filter(Boolean).join(' · ') || '-';
+    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,
+    );
+  }
+  console.log(chalk.gray(`\nRaiz primária: ${fleet.root}`));
+  process.exit(0);
+}

package/src/commands/project/worktree.js

@@ -35,7 +35,7 @@
  */
 
 import { execSync, execFileSync } from 'child_process';
-import { existsSync, mkdirSync, symlinkSync, readFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, readdirSync, cpSync } from 'fs';
+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';
 
@@ -145,6 +145,38 @@ function getDateSuffix() {
 
 // ── Infrastructure linking ───────────────────────────────────────────────────
 
+/**
+ * The infra directories morph itself links into a worktree — the ONLY ones
+ * `setupInfraLinks`/`worktreeLinkCommand --all`/`unlinkWorktreeInfraLinks` treat
+ * as KNOWN, and therefore the only ones `finish` may auto-remove via the
+ * already-proven-safe unlink mechanism (never by widening the reparse-point
+ * scan — see `findReparsePoints`).
+ *
+ * Always: `node_modules`, `.claude`. Conditionally: `.morph/framework` (client
+ * projects only) and `{project.frontendPath}/node_modules` — a monorepo
+ * frontend (e.g. a Next.js app under `apps/catalog-admin`) commonly has its OWN
+ * node_modules, a separate `npm install` from the root's, invisible to a static
+ * list. Fail-open: a missing/unreadable config.json just means no frontendPath.
+ *
+ * @param {string} mainCwd - Absolute path to the main project root
+ * @returns {string[]} relative paths, root-first
+ */
+function resolveInfraLinkDirs(mainCwd) {
+  const dirs = ['node_modules', '.claude'];
+  if (existsSync(join(mainCwd, '.morph', 'framework'))) {
+    dirs.push(join('.morph', 'framework'));
+  }
+  try {
+    const configPath = join(mainCwd, '.morph', 'config', 'config.json');
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, 'utf8'));
+      const frontendPath = config?.project?.frontendPath;
+      if (frontendPath) dirs.push(join(frontendPath, 'node_modules'));
+    }
+  } catch { /* fail-open — no frontendPath to add */ }
+  return dirs;
+}
+
 /**
  * Create junctions in the worktree for shared infrastructure directories
  * (node_modules/, .claude/, .morph/framework/).
@@ -169,16 +201,9 @@ export function setupInfraLinks(worktreePath, mainCwd, opts = {}) {
   const mainAbs = resolve(mainCwd);
   const wtAbs = resolve(worktreePath);
 
-  let dirLinks;
-  if (Array.isArray(opts.dirs) && opts.dirs.length) {
-    dirLinks = opts.dirs;
-  } else {
-    dirLinks = ['node_modules', '.claude'];
-    // .morph/framework/ — client projects (in framework repo, framework/ is tracked)
-    if (existsSync(join(mainAbs, '.morph', 'framework'))) {
-      dirLinks.push(join('.morph', 'framework'));
-    }
-  }
+  const dirLinks = (Array.isArray(opts.dirs) && opts.dirs.length)
+    ? opts.dirs
+    : resolveInfraLinkDirs(mainAbs);
 
   for (const rel of dirLinks) {
     const target = join(mainAbs, rel);
@@ -196,7 +221,7 @@ export function setupInfraLinks(worktreePath, mainCwd, opts = {}) {
   // already speak for it. `lstat` reports a POSIX symlink and a Windows
   // junction alike as a symbolic link, so the exclude lands identically on
   // both platforms — as does the bug it prevents (see excludeInfraLinks).
-  excludeInfraLinks(mainAbs, dirLinks.filter((rel) => {
+  excludeWorktreePaths(mainAbs, dirLinks.filter((rel) => {
     try {
       return lstatSync(join(wtAbs, rel)).isSymbolicLink();
     } catch {
@@ -205,11 +230,13 @@ export function setupInfraLinks(worktreePath, mainCwd, opts = {}) {
   }));
 }
 
-/** Marks the block `excludeInfraLinks` owns in `.git/info/exclude`. */
+/** Marks the block `excludeWorktreePaths` owns in `.git/info/exclude`. */
 const EXCLUDE_MARKER = '# morph-spec: infra links inside worktrees (managed — see setupInfraLinks)';
 
 /**
- * Teach the repo's git to ignore the infra links a worktree carries.
+ * Teach the repo's git to ignore worktree-carried paths morph itself creates —
+ * the infra links from `setupInfraLinks` and the fleet env manifest
+ * (`.morph/worktree.env`). Same mechanism, same reasons, for both.
  *
  * CRITICAL — without this, `worktree finish` is unusable on POSIX and
  * destructive at worst, because git never sees a link as a link: it sees what
@@ -247,9 +274,9 @@ const EXCLUDE_MARKER = '# morph-spec: infra links inside worktrees (managed —
  * not write costs a refused finish, never a wrong one.
  *
  * @param {string} mainCwd - Absolute path to the main project root
- * @param {string[]} rels - worktree-relative link paths to exclude
+ * @param {string[]} rels - worktree-relative paths to exclude
  */
-function excludeInfraLinks(mainCwd, rels) {
+function excludeWorktreePaths(mainCwd, rels) {
   if (!rels.length) return;
   try {
     // `--git-common-dir`, never `join(mainCwd, '.git')`: the primary root may
@@ -416,10 +443,47 @@ export async function runWorktreeSetup(feature, options = {}) {
     // Set up infrastructure junctions (node_modules, .claude, .morph/framework).
     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 */ }
+
     // 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);
 
+    // Fleet handoff: the fresh instance that opens this worktree reads
+    // handoff.md before anything else (SessionStart hook points at it). The doc
+    // is derived and git-invisible (see handoff-generator). Fail-open — and a
+    // no-op in the create --worktree flow, where the feature dir only lands in
+    // the worktree after create's copy (create regenerates it then).
+    try {
+      if (existsSync(join(worktreePath, '.morph', 'features', feature, 'feature.json'))) {
+        const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
+        writeHandoff(feature, worktreePath);
+      }
+    } catch { /* fail-open */ }
+
     // Persist in state (non-blocking — feature may not be in state yet).
     // NOTE: imports from core/ (the lib/ path was a latent bug that silently
     // no-op'd this whole block); loadState/saveState operate on the cwd's state.
@@ -442,6 +506,7 @@ export async function runWorktreeSetup(feature, options = {}) {
       branch,
       feature,
       materialized: materialized.materialized,
+      ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
       nextStep: `Abra o Claude Code em ${worktreePath} para trabalhar nesta feature`,
     };
   } catch (err) {
@@ -490,7 +555,7 @@ export function worktreeLinkCommand(options = {}) {
   }
 
   const dirs = options.all
-    ? ['node_modules', '.claude', join('.morph', 'framework')]
+    ? resolveInfraLinkDirs(root)
     : ['node_modules'];
 
   const alreadyPresent = {};
@@ -524,7 +589,7 @@ export function worktreeLinkCommand(options = {}) {
  * @param {string} cwd
  * @returns {Array<{ path: string, branch: string|null, head: string|null }>}
  */
-function parseWorktreeList(cwd) {
+export function parseWorktreeList(cwd) {
   let output;
   try {
     output = execSync('git worktree list --porcelain', { cwd, stdio: 'pipe' }).toString();
@@ -584,12 +649,10 @@ function findWorktreeForFeature(feature, root) {
   return { path: match.path, branch: actual, expectedBranch };
 }
 
-/** The infra paths `setupInfraLinks` junctions into a worktree. */
-const INFRA_LINK_RELS = ['node_modules', '.claude', join('.morph', 'framework')];
-
 /**
  * Drop the infra junctions a worktree carries (`node_modules`, `.claude`,
- * `.morph/framework`) WITHOUT following them.
+ * `.morph/framework`, and the `project.frontendPath` node_modules if
+ * configured) WITHOUT following them.
  *
  * CRITICAL — this is what keeps `worktree finish` from destroying the project.
  * `git worktree remove` refuses a worktree still holding these ("contains
@@ -606,12 +669,19 @@ const INFRA_LINK_RELS = ['node_modules', '.claude', join('.morph', 'framework')]
  * target's contents, and `rmdirSync` fails on a real non-empty directory — the
  * safety that stops this from ever deleting genuine files.
  *
+ * This is deliberately narrow to the KNOWN inventory from `resolveInfraLinkDirs`
+ * — never widened to auto-remove any reparse point `findReparsePoints` might
+ * discover elsewhere. An unknown/nested link (npm link, npm workspaces) must
+ * still decline the removal; see the CANARY tests pinning that in worktree.test.js.
+ *
  * @param {string} worktreePath
+ * @param {string} mainCwd - Absolute path to the main project root, to resolve
+ *   `project.frontendPath` from config.json
  * @returns {string[]} relative paths actually unlinked
  */
-export function unlinkWorktreeInfraLinks(worktreePath) {
+export function unlinkWorktreeInfraLinks(worktreePath, mainCwd) {
   const removed = [];
-  for (const rel of INFRA_LINK_RELS) {
+  for (const rel of resolveInfraLinkDirs(mainCwd)) {
     const p = join(worktreePath, rel);
     let st;
     try {
@@ -706,9 +776,60 @@ function findReparsePoints(dir, base = dir, acc = { points: [], unprovable: [] }
  */
 const IGNORED_SHIELDABLE_PREFIXES = ['.morph/'];
 
+/**
+ * Well-known, regenerable build artifacts — `bin/`, `obj/` (dotnet), a real
+ * `node_modules` left behind outside the setup-created junction, and
+ * `*.tsbuildinfo` (tsc incremental cache). These are the everyday leftovers of
+ * running a build/test cycle inside a worktree, not user data: they are fully
+ * reproducible from source, and requiring `--discard-ignored` for every finish
+ * that ever ran a build turns the flag from "explicit consent for a real risk"
+ * into a rubber stamp nobody reads anymore. Auto-discarding them (like any
+ * `discarded` entry, WITHOUT a backup — see the note below) is safe precisely
+ * because "regenerable" is a stronger guarantee than "backed up".
+ *
+ * Deliberately narrow — do NOT add speculative patterns (`dist/`, `.next/`)
+ * beyond what's proven to be pure noise; anything else stays in `blocking` by
+ * default, requiring the explicit `--discard-ignored` consent.
+ *
+ * @param {string} p - forward-slash relative path from `git status --ignored`
+ */
+/**
+ * Whether a dirty root-side path is EXACTLY a sibling feature's live worktree
+ * registration — see the call site (Validation 3 in worktreeFinishCommand)
+ * for why this is safe to exempt from the whole-root clean gate rather than a
+ * widened hole.
+ *
+ * PROVES it rather than assuming: the path must be exactly that sibling's
+ * `feature.json`, must parse, and its `worktree.path` must point at a
+ * currently-existing directory. A parse failure, a missing registration, or a
+ * STALE pointer (worktree already removed) is NOT exempted.
+ *
+ * @param {string} relPath - forward-slash path relative to `root`
+ * @param {string} root - absolute path to the primary root
+ * @param {string} feature - the feature THIS finish is acting on (never exempted — its own scope is the shed's job)
+ */
+function isLiveSiblingWorktreeRegistration(relPath, root, feature) {
+  const m = relPath.match(/^\.morph\/features\/([^/]+)\/feature\.json$/);
+  if (!m || m[1] === feature) return false;
+  try {
+    const fj = JSON.parse(readFileSync(join(root, relPath), 'utf8'));
+    const wtPath = fj?.worktree?.path;
+    return typeof wtPath === 'string' && wtPath.length > 0 && existsSync(wtPath);
+  } catch {
+    return false;
+  }
+}
+
+function isDisposableBuildArtifact(p) {
+  if (/\.tsbuildinfo$/.test(p)) return true;
+  const segments = p.split('/').filter(Boolean);
+  return segments.some((s) => s === 'bin' || s === 'obj' || s === 'node_modules');
+}
+
 /**
  * Split the worktree's GITIGNORED leftovers into what this command may remove
- * (morph's own, after a backup) and what it must refuse to destroy.
+ * (morph's own, after a backup, or a known disposable build artifact, without
+ * one) and what it must refuse to destroy.
  *
  * Why this exists: `git worktree remove` deletes gitignored files outright, and
  * the clean-check that gates it uses `git status --porcelain`, which omits them
@@ -722,34 +843,46 @@ const IGNORED_SHIELDABLE_PREFIXES = ['.morph/'];
  *
  * @param {string} worktreePath
  * @param {{ discardIgnored?: boolean }} options
- * @returns {{ shieldable: string[], blocking: string[] }}
+ * @returns {{ shieldable: string[], blocking: string[], discarded: string[] }}
  */
 function classifyIgnoredLeftovers(worktreePath, options = {}) {
   let out;
   try {
     // `-z` + execFile: NUL-delimited, no shell, no C-style quoting to undo —
     // paths with spaces or non-ASCII (a pt-BR codebase has both) stay intact.
-    out = execFileSync('git', ['status', '--porcelain', '--ignored', '-z'], { cwd: worktreePath, stdio: 'pipe' }).toString();
+    // `=matching` (not the traditional default): an ignored directory whose own
+    // name matches no pattern — e.g. `MyProj/`, ignored only because EVERYTHING
+    // inside it (`bin/`, `obj/`) does — otherwise collapses into one opaque
+    // `MyProj/` entry, hiding the actual disposable-artifact names from
+    // isDisposableBuildArtifact. A directory that IS itself the matched pattern
+    // (`node_modules/`) still reports as one entry either way — verified
+    // empirically, not assumed.
+    out = execFileSync('git', ['status', '--porcelain', '--ignored=matching', '-z'], { cwd: worktreePath, stdio: 'pipe' }).toString();
   } catch {
-    return { shieldable: [], blocking: ['<git status --ignored falhou — não foi possível enumerar o que seria destruído>'] };
+    return { shieldable: [], blocking: ['<git status --ignored falhou — não foi possível enumerar o que seria destruído>'], discarded: [] };
   }
 
   const shieldable = [];
-  const blocking = [];
+  const blockingRest = [];
+  const disposable = [];
   for (const record of out.split('\0')) {
     if (!record || record.length < 4) continue;
     if (record.slice(0, 2) !== '!!') continue; // only ignored entries; the rest is the clean-check's job
     const p = record.slice(3).replace(/\\/g, '/');
     if (IGNORED_SHIELDABLE_PREFIXES.some((prefix) => p.startsWith(prefix))) shieldable.push(p);
-    else blocking.push(p);
+    else if (isDisposableBuildArtifact(p)) disposable.push(p);
+    else blockingRest.push(p);
   }
-  // Explicit consent clears the block — but the list is NOT thrown away. These
-  // are the files that exist nowhere else, and they are the ones about to die;
-  // reporting them is the least this can do. (Backing them up instead is not an
-  // option: this bucket is where `node_modules`/`dist`/`.next` land, so a copy
-  // is unbounded. The user declared them disposable — they still get told.)
-  if (options.discardIgnored) return { shieldable, blocking: [], discarded: blocking };
-  return { shieldable, blocking, discarded: [] };
+  // Explicit consent clears the rest of the block too — but the list is NOT
+  // thrown away. These are the files that exist nowhere else, and they are the
+  // ones about to die; reporting them is the least this can do. (Backing them
+  // up instead is not an option: this bucket is where arbitrarily large
+  // leftovers land, so a copy is unbounded. The user declared them
+  // disposable — they still get told.)
+  if (options.discardIgnored) return { shieldable, blocking: [], discarded: [...disposable, ...blockingRest] };
+  // Known build artifacts are discarded by default, no flag required — they
+  // are reproducible from source, unlike anything else in `blockingRest`.
+  return { shieldable, blocking: blockingRest, discarded: disposable };
 }
 
 /**
@@ -975,15 +1108,34 @@ export async function worktreeFinishCommand(feature, options = {}) {
     }
     : {};
 
-  // Validation 3: primary root must be clean.
-  let rootStatus;
+  // Validation 3: primary root must be clean — except a SIBLING feature's own
+  // LIVE worktree registration (see isLiveSiblingWorktreeRegistration). That
+  // artifact is how `runWorktreeSetup`/`create --worktree` are DESIGNED to
+  // leave the root for that sibling's entire life (decidePersistence in
+  // verify.js and the anti-dupe guard above both read the root's copy for
+  // `.worktree.path`), so refusing THIS feature's finish over it would block
+  // every OTHER feature for as long as any sibling stays open in its own
+  // worktree — the exact "orphaned scaffold collides with finish" friction
+  // from real multi-feature use. Anything else is still unexplained dirt and
+  // still blocks, fail-closed, exactly as before.
+  let rootStatusRaw;
   try {
-    rootStatus = execFileSync('git', ['status', '--porcelain'], { cwd: root, stdio: 'pipe' }).toString();
+    // `--untracked-files=all`, not the default `normal`: the default collapses
+    // an entirely-untracked directory into one entry (e.g. `.morph/features/
+    // sibling-feat/`, verified empirically) — which would never match the
+    // exact `.../feature.json` path isLiveSiblingWorktreeRegistration expects,
+    // silently defeating the exemption for the very shape it exists to allow.
+    rootStatusRaw = execFileSync('git', ['status', '--porcelain', '--untracked-files=all', '-z'], { cwd: root, stdio: 'pipe' }).toString();
   } catch (err) {
     console.log(JSON.stringify({ finished: false, error: 'primary-root-status-failed', detail: (err.message || '').slice(0, 200), feature, ...backupNote }));
     process.exit(1);
   }
-  if (rootStatus.trim() !== '') {
+  const unexplainedDirt = rootStatusRaw.split('\0').filter((record) => {
+    if (!record || record.length < 4) return false;
+    const p = record.slice(3).replace(/\\/g, '/');
+    return !isLiveSiblingWorktreeRegistration(p, root, feature);
+  });
+  if (unexplainedDirt.length) {
     console.log(JSON.stringify({
       finished: false,
       error: 'primary-root-dirty',
@@ -1035,7 +1187,7 @@ export async function worktreeFinishCommand(feature, options = {}) {
   // Both gates below therefore PROVE-or-DECLINE. Declining costs a stale
   // directory the user can delete in one command; being wrong costs data that
   // exists nowhere else.
-  unlinkWorktreeInfraLinks(worktreePath);
+  unlinkWorktreeInfraLinks(worktreePath, root);
 
   const scan = findReparsePoints(worktreePath);
   const ignored = classifyIgnoredLeftovers(worktreePath, options);
@@ -1084,6 +1236,15 @@ export async function worktreeFinishCommand(feature, options = {}) {
     try {
       execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
     } catch { /* fail-open */ }
+
+    // Fleet env: the worktree is gone, so no server can be running on its
+    // block — release it for the next feature. ONLY here: a kept/declined
+    // worktree may still be serving on those ports. Fail-open metadata cleanup.
+    try {
+      const { releaseEnvBlock } = await import('../../lib/worktree/env-allocator.js');
+      const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
+      if (common) releaseEnvBlock(feature, { gitCommonDir: resolve(root, common) });
+    } catch { /* fail-open */ }
   }
 
   // The feature is now merged into the primary root — clear the `worktree`
@@ -1153,7 +1314,9 @@ export async function worktreeFinishCommand(feature, options = {}) {
     ...(worktreeRemoved && ignored.discarded.length
       ? {
         discardedIgnored: ignored.discarded,
-        discardedNote: `--discard-ignored: os caminhos acima eram gitignored, existiam só no worktree e foram DESTRUÍDOS sem backup (não são copiados por poderem ser arbitrariamente grandes)`,
+        discardedNote: options.discardIgnored
+          ? `--discard-ignored: os caminhos acima eram gitignored, existiam só no worktree e foram DESTRUÍDOS sem backup (não são copiados por poderem ser arbitrariamente grandes)`
+          : `artefatos de build reconhecidos (bin/, obj/, node_modules/, *.tsbuildinfo) — descartados por padrão, sem backup (regeneráveis a partir do source)`,
       }
       : {}),
     ...(worktreeRemoved

package/src/commands/state/advance.js

@@ -86,6 +86,14 @@ export async function advanceCommand(featureName, options = {}) {
       if (!existsSync(nextPath)) mkdirSync(nextPath, { recursive: true });
     }
 
+    // Fleet handoff: a phase transition is exactly when a session hands the
+    // feature over (to a new instance, or to itself after /compact) — refresh
+    // the derived handoff.md so the next reader starts from the new phase.
+    try {
+      const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
+      writeHandoff(featureName, process.cwd());
+    } catch { /* fail-open */ }
+
     console.log(chalk.green(`\n✅ Advanced "${featureName}" past the ${phase} phase.`));
     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`));

package/src/commands/state/create.js

@@ -155,6 +155,12 @@ export async function createCommand(featureName, options = {}) {
             // the copy (no features yet), so its `materialized:false` was stale.
             const remat = await materializeState(worktreeResult.path);
             worktreeResult.materialized = remat.materialized;
+            // Same reason the setup path generates one: the new instance's first
+            // read. Regenerated here because setup ran before the copy above.
+            try {
+              const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
+              writeHandoff(featureName, worktreeResult.path);
+            } catch { /* fail-open */ }
           } catch { /* fail-open — the feature already exists in root */ }
         }
       }

package/src/commands/state/handoff.js

@@ -0,0 +1,49 @@
+/**
+ * `morph-spec handoff <feature>` — generate the compressed session-handoff
+ * document (`.morph/features/{f}/handoff.md`).
+ *
+ * The fleet workflow hands a feature between Claude Code instances (a new
+ * worktree session, a resumed session after a phase transition). The handoff
+ * is the sanctioned way to carry context across: derived, regenerable, and
+ * pointer-based (see handoff-generator.js). This command is also called
+ * in-process by `worktree setup`, `create --worktree` and `advance` — the CLI
+ * surface exists for the LLM/user to refresh the document on demand.
+ */
+
+import chalk from 'chalk';
+import { buildHandoff, writeHandoff } from '../../lib/generators/handoff-generator.js';
+
+/**
+ * @param {string} featureName
+ * @param {{ json?: boolean }} [options]
+ */
+export function handoffCommand(featureName, options = {}) {
+  const result = buildHandoff(featureName, process.cwd());
+  if (!result) {
+    if (options.json) {
+      console.log(JSON.stringify({ error: 'feature-not-found', feature: featureName }));
+    } else {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+    }
+    process.exit(1);
+  }
+
+  const path = writeHandoff(featureName, process.cwd());
+  if (!path) {
+    if (options.json) {
+      console.log(JSON.stringify({ error: 'write-failed', feature: featureName }));
+    } else {
+      console.error(chalk.red(`\n❌ Could not write handoff.md for ${featureName}\n`));
+    }
+    process.exit(1);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ path, feature: featureName, ...result.meta }));
+    return;
+  }
+
+  console.log(chalk.green(`\n✅ Handoff gerado: ${path}`));
+  console.log(chalk.gray(`   fase ${result.meta.phase} · tasks ${result.meta.tasksDone}/${result.meta.tasksTotal} · ${result.meta.generatedAt}`));
+  console.log(chalk.gray('   A próxima sessão lê este documento antes de continuar (ponteiros, não cópias).\n'));
+}

package/src/commands/state/score.js

@@ -39,9 +39,20 @@ export async function scoreCommand(featureName, taskId, scoreArg, options = {})
 
     let dimensions;
     if (options.dims) {
-      const parts = String(options.dims).split(',').map(s => s.trim());
+      // Commander captures --dims as variadic (`<dims...>`), so an UNQUOTED
+      // comma list typed in PowerShell — `--dims 9.5,9,9,9` — that arrives as
+      // 4 separate argv tokens (confirmed: Commander binds only the first
+      // token to a non-variadic option and silently drops the rest) is not
+      // lost. Accept either shape: one comma-joined string (the documented,
+      // quoted form) or N separate tokens — split on both separators so a
+      // mix of the two never matters either.
+      const raw = Array.isArray(options.dims) ? options.dims.join(' ') : String(options.dims);
+      const parts = raw.split(/[,\s]+/).filter(Boolean);
       if (parts.length !== DIM_KEYS.length) {
-        console.error(chalk.red(`\n❌ --dims expects ${DIM_KEYS.length} comma-separated values in order a,c,q,t (architecture,contracts,code-quality,test-coverage)\n`));
+        console.error(chalk.red(
+          `\n❌ --dims expects ${DIM_KEYS.length} values in order a,c,q,t (architecture,contracts,code-quality,test-coverage) — got ${parts.length} (${JSON.stringify(parts)}).\n` +
+          `   Quote the value under PowerShell to keep it as one argument: --dims "9.5,9,9,9"\n`
+        ));
         process.exit(1);
       }
       dimensions = {};

package/src/commands/tasks/dag.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { parseTasksJson } from '../../lib/tasks/tasks-json-parser.js';
+import { parseTasksJsonLenient } from '../../lib/tasks/tasks-json-parser.js';
 import { planDispatch } from '../../lib/tasks/dispatch-planner.js';
 import { renderMermaidFlowchart } from '../../lib/tasks/mermaid-renderer.js';
 
@@ -24,8 +24,16 @@ export async function dagCommand(featureName, options = {}) {
       process.exit(1);
     }
 
-    // parseTasksJson validates the schema and throws with the error list.
-    const data = await parseTasksJson(tasksPath);
+    // parseTasksJsonLenient validates the schema and throws with the error
+    // list, but defaults a missing `version` (legacy plans predating the
+    // field) instead of failing — the DAG analysis doesn't depend on it.
+    const { data, versionDefaulted } = await parseTasksJsonLenient(tasksPath);
+    if (versionDefaulted) {
+      console.error(chalk.yellow(
+        `⚠ tasks.json has no 'version' field — defaulting to "1.0" for this analysis.\n` +
+        `  Consider adding it back explicitly (safe: protect-spec-files allows backfilling it).`
+      ));
+    }
 
     // --mermaid short-circuits before the dispatch analysis: visualizing the
     // plan's DAG doesn't need a sequential-vs-parallel decision.