@polymorphism-tech/morph-spec 8.1.2 → 8.2.0

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 8.1.2  
+**Version:** 8.2.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -394,4 +394,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.1.2 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.2.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -24,6 +24,7 @@ import { updateCommand } from '../src/commands/project/update.js';
 import { doctorCommand } from '../src/commands/project/doctor.js';
 import { statusCommand } from '../src/commands/project/status.js';
 import { worktreeSetupCommand, worktreeLinkCommand, worktreeFinishCommand, worktreeListCommand } from '../src/commands/project/worktree.js';
+import { fleetCommand } from '../src/commands/project/fleet.js';
 
 // === Approval gates (human-only) ===
 import { approveCommand, approvalStatusCommand, unapproveCommand } from '../src/commands/state/approve.js';
@@ -33,6 +34,7 @@ import { scoreCommand } from '../src/commands/state/score.js';
 import { gateDecisionCommand } from '../src/commands/state/gate-decision.js';
 import { createCommand } from '../src/commands/state/create.js';
 import { retypeCommand } from '../src/commands/state/retype.js';
+import { handoffCommand } from '../src/commands/state/handoff.js';
 
 // === Tasks ===
 import { dagCommand } from '../src/commands/tasks/dag.js';
@@ -195,6 +197,12 @@ program
   .option('--json', 'Output as JSON')
   .action((feature, newType, options) => retypeCommand(feature, newType, options));
 
+program
+  .command('handoff <feature>')
+  .description('Generate the compressed session-handoff document (.morph/features/{f}/handoff.md) — pointers, not copies')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => handoffCommand(feature, options));
+
 // ─── Tasks ────────────────────────────────────────────────────────────────
 program
   .command('dag <feature>')
@@ -321,6 +329,13 @@ worktreeCommand
   .option('--json', 'Output as JSON')
   .action((options) => worktreeListCommand(options));
 
+// ─── Fleet ────────────────────────────────────────────────────────────────
+program
+  .command('fleet')
+  .description('Fleet view — every active feature across primary root and worktrees (phase, gates, tasks, ports, handoff, activity)')
+  .option('--json', 'Output as JSON')
+  .action((options) => fleetCommand(options));
+
 // ─── Dashboard ────────────────────────────────────────────────────────────
 program
   .command('dashboard')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.1.2",
+  "version": "8.2.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -99,16 +99,18 @@ morph-spec retype {feature} {newType}                    # change type mid-fligh
 
 ---
 
-## CLI — worktrees (parallel development)
+## CLI — worktrees (parallel development / fleet)
 
-One feature = one git worktree = one Claude Code instance. Independent features run side by side without stepping on each other's state; a SessionStart hook injects each worktree's feature identity into context.
+One feature = one git worktree = one Claude Code instance. Independent features run side by side without stepping on each other's state; a SessionStart hook injects each worktree's feature identity, allocated ports and handoff pointer into context. Each worktree gets a deterministic port block (`.morph/worktree.env`) and a regenerable handoff document.
 
 ```bash
 morph-spec create {feature} --worktree     # birth the feature already isolated in its own worktree
 morph-spec worktree setup {feature}        # create .worktrees/{feature}/ on branch morph/{feature}
 morph-spec worktree link [--all]           # relink shared infra (node_modules, .claude, .morph/framework)
-morph-spec worktree finish {feature}       # merge --no-ff back to the primary root, clean up (requires Gate 3)
+morph-spec worktree finish {feature}       # merge --no-ff back to the primary root, clean up + release ports (requires Gate 3)
 morph-spec worktree list [--json]          # active feature worktrees with phase/gate status
+morph-spec handoff {feature} [--json]      # regenerate the compressed session-handoff doc (pointers, not copies)
+morph-spec fleet [--json]                  # fleet view: every active feature (root + worktrees) with phase/gates/ports/handoff/activity
 ```
 
 ---
@@ -237,4 +239,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v8.1.2 by Polymorphism Tech*
+*morph-spec v8.2.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -256,4 +256,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.1.2 by Polymorphism Tech*
+*morph-spec v8.2.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -6,7 +6,8 @@
 
 1. Leia `.morph/framework/MORPH.md` — o charter NLH com papéis, fases, gates e skills.
 2. Leia `.morph/state.json` — índice fino e gitignored (só status + updatedAt por feature) — para identificar a feature `in_progress` e a fase atual. **Não o edite à mão:** é reconstruído a partir dos `feature.json` a cada load. O estado autoritativo e commitado de cada feature vive em `.morph/features/{feature}/feature.json`.
-3. Assuma o papel correspondente (Orchestrator/Specialist/Evaluator) e continue o trabalho. Não aguarde instrução do usuário se há trabalho pendente entre gates.
+3. Se existir `.morph/features/{feature}/handoff.md` para a feature ativa, **leia-o antes de re-derivar contexto à mão** — é o documento de retomada (comprimido, aponta para os artefatos; regenere com `morph-spec handoff <f>` se parecer velho).
+4. Assuma o papel correspondente (Orchestrator/Specialist/Evaluator) e continue o trabalho. Não aguarde instrução do usuário se há trabalho pendente entre gates.
 
 Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
@@ -49,7 +50,9 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - `morph-spec create <feature> --type <feature|bug|chore|hotfix> [--request "<txt>"] [--worktree]` — cria a estrutura da feature + `feature.json` canônico explicitamente (nascimento explícito no início da proposal; o hook state-sync continua cobrindo o caminho implícito como fallback). `--type` classifica direto; `--request "<pedido>"` roda o detector determinístico (empate/sem sinal sai com exit 2 e candidatos — a LLM decide e re-roda com `--type`); `--worktree` já nasce a feature no seu worktree próprio.
 - `morph-spec retype <feature> <newType>` — muda o tipo de trabalho mid-flight; desfaz só os gates carimbados por política, preserva aprovações humanas; bloqueado após o Gate 3.
 - `morph-spec verify <feature> [task] [--json]` — cadeia determinística build+testes+validadores (código antes do juiz LLM); escopo de task quando informado, senão a feature inteira.
-- `morph-spec worktree setup|link|finish|list` — gerencia o ciclo do worktree por feature (`setup` cria `.worktrees/{f}/` na branch `morph/{f}`; `link` religa infra compartilhada; `finish` faz merge `--no-ff` e limpa; `list` mostra fase/gate de cada worktree ativo).
+- `morph-spec worktree setup|link|finish|list` — gerencia o ciclo do worktree por feature (`setup` cria `.worktrees/{f}/` na branch `morph/{f}`, aloca o bloco de portas e escreve `.morph/worktree.env`; `link` religa infra compartilhada; `finish` faz merge `--no-ff`, limpa e libera o bloco; `list` mostra fase/gate de cada worktree ativo).
+- `morph-spec handoff <feature>` — regenera o documento de retomada (`.morph/features/{f}/handoff.md`): comprimido, derivado, aponta para os artefatos em vez de copiá-los. Gerado automaticamente em `setup`/`create --worktree`/`advance`.
+- `morph-spec fleet` — visão da frota: toda feature ativa (raiz + worktrees) com fase, gates pendentes, tasks, portas, handoff e atividade. Use entre sessões para decidir onde atuar.
 
 ## Skills core (em `.claude/skills/`)
 
@@ -68,7 +71,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 Toda feature nasce com um `workType` (`morph-spec create <f> --type <tipo>` ou classificado de `--request "<pedido>"`) que dimensiona o pipeline: `feature` roda o fluxo completo (proposal → [uiux] → plan → implement → review); `bug` roda uma versão enxuta (proposal/plan lean); `chore` pula direto para implement (Gates 1/2 carimbados por política no nascimento); `hotfix` roda scout → fix cirúrgico → test loop → ship. O Gate 3 do `hotfix` **pausa sempre para um humano**, mesmo em `trust: auto` — o CLI recusa `morph-spec approve <f> review --mode auto` nesse tipo. Detalhes em `.morph/framework/MORPH.md` §2.1 e §5.
 
-Features independentes podem rodar em paralelo, cada uma isolada num git worktree (`morph-spec create <f> --worktree` ou `morph-spec worktree setup <f>`) — uma feature por worktree, uma instância de Claude Code por worktree. `feature.json` viaja commitado na branch `morph/{f}`; ao fechar, aprove o Gate 3 dentro do worktree e rode `morph-spec worktree finish <f>` seguido de `morph-spec archive <f>` na raiz. Detalhes em `.morph/framework/MORPH.md` §2.2.
+Features independentes podem rodar em paralelo, cada uma isolada num git worktree (`morph-spec create <f> --worktree` ou `morph-spec worktree setup <f>`) — uma feature por worktree, uma instância de Claude Code por worktree. Cada worktree tem seu **bloco de portas** próprio (`.morph/worktree.env` — suba dev servers SEMPRE nelas, nunca nas portas padrão) e seu **handoff.md** de retomada. `feature.json` viaja commitado na branch `morph/{f}`; ao fechar, aprove o Gate 3 dentro do worktree e rode `morph-spec worktree finish <f>` seguido de `morph-spec archive <f>` na raiz. Visão agregada: `morph-spec fleet`. Detalhes em `.morph/framework/MORPH.md` §2.2.
 
 ## Personas (em `.claude/agents/`)
 

package/framework/MORPH.md

@@ -112,14 +112,20 @@ Nem todo trabalho merece o pipeline completo. Cada feature nasce com um **workTy
 
 **Compat:** uma feature sem `workType` (criada antes do v8) é tratada como `feature`. Mudança de tipo mid-flight: `morph-spec retype <f> <tipo>` (desfaz só carimbos de política, preserva aprovações humanas; bloqueado após o Gate 3).
 
-### 2.2 Desenvolvimento paralelo por worktree
+### 2.2 Desenvolvimento paralelo por worktree (frota)
 
 Features independentes podem ser desenvolvidas **em paralelo, cada uma no seu git worktree**, com uma instância de Claude Code por worktree. `morph-spec create <f> --worktree` (ou `morph-spec worktree setup <f>`) cria `.worktrees/{f}/` na branch `morph/{f}`. Contrato:
 
 - **Uma feature = um worktree = uma instância.** Nunca abra duas instâncias na mesma feature (o setup recusa com exit 3).
 - O estado autoritativo (`feature.json`) viaja **commitado na branch** `morph/{f}`. O `state.json` local do worktree é um índice derivável — materializado por self-heal, nunca sincronizado à mão.
 - Infra compartilhada (`node_modules`, `.claude`, `.morph/framework`) é linkada por junction; `memory/` e `logs/` são locais de cada worktree (isolamento correto). Se faltar infra num worktree (aberto com `git worktree add` puro), rode `morph-spec worktree link --all`.
-- **Fechamento:** aprove o Gate 3 dentro do worktree, depois `morph-spec worktree finish <f>` (merge `--no-ff` da branch na raiz primária limpa; recusa se worktree ou raiz estiverem sujos; aborta em conflito) e por fim `morph-spec archive <f>` na raiz. `morph-spec worktree list` mostra os worktrees ativos com fase e gate.
+- **Ambiente separado (portas):** o setup aloca um **bloco de portas determinístico** por feature e escreve `.morph/worktree.env` no worktree (`PORT`, `MORPH_PORT_RANGE`; `ASPNETCORE_URLS` quando o stack tem dotnet). **Suba dev servers SEMPRE nas portas do bloco** — as portas padrão (3000/5000) pertencem à raiz; duas instâncias no default se matam. O arquivo é local e git-invisível; o hook de SessionStart injeta as portas. Overrides em `config.json → fleet.basePort/blockSize`.
+- **Banco de dados:** worktrees compartilham o mesmo banco por padrão. Para isolamento real com o MCP do Neon disponível, crie um branch de DB `morph/{f}` e anote a connection string no `.morph/worktree.env` (a CLI nunca toca em credenciais); sem Neon, prefixe schema/DB local com o nome da feature. Migration destrutiva num worktree compartilhando banco → integre antes de abrir worktrees irmãos.
+- **Limitação conhecida:** `node_modules` é compartilhado (junction) — mudança de dependência feita num worktree afeta os irmãos. Mudou dependência: conclua e integre (`finish`) antes de seguir com worktrees paralelos.
+- **Handoff entre sessões:** `.morph/features/{f}/handoff.md` é o documento de retomada — comprimido, derivado e regenerável (`morph-spec handoff <f>`), ele **aponta** para os artefatos em vez de copiá-los. É regenerado automaticamente no `worktree setup`, `create --worktree` e `advance`; o hook de SessionStart aponta para ele. **Ao abrir uma sessão numa feature em andamento, leia o handoff antes de re-derivar contexto à mão.** Nunca o edite manualmente (é git-invisível e sobrescrito na próxima regeneração).
+- **Visão da frota:** `morph-spec fleet` agrega raiz + worktrees (fase, gates pendentes, tasks, portas, handoff, último commit, sujeira) — use entre sessões para decidir onde atuar. `morph-spec worktree list` continua sendo a visão enxuta por worktree.
+- **Ownership de arquivos:** não há lock em runtime, por design — a colisão de escrita se resolve **em plan-time** (`morph-spec dag` detecta overlap de `outputs` e recomenda `isolation: "worktree"`) e **por construção** (uma feature = um worktree = um escritor). Entre features, arquivos compartilhados convergem no merge do `finish` — conflito ali é o sinal honesto de escopo sobreposto, não um bug.
+- **Fechamento:** aprove o Gate 3 dentro do worktree, depois `morph-spec worktree finish <f>` (merge `--no-ff` da branch na raiz primária limpa; recusa se worktree ou raiz estiverem sujos; aborta em conflito; libera o bloco de portas) e por fim `morph-spec archive <f>` na raiz.
 
 ---
 

package/framework/hooks/claude-code/core/worktree-context.js

@@ -97,11 +97,54 @@ function featureFromSingleDir(dir) {
   }
 }
 
+/**
+ * Fleet env line: the worktree's allocated port block, read from the manifest
+ * `worktree setup` writes. Fail-open — a missing or malformed manifest just
+ * omits the line (the session then uses project defaults, which is exactly
+ * the pre-fleet behavior).
+ */
+function buildEnvLine(dir) {
+  try {
+    const envPath = join(dir, '.morph', 'worktree.env');
+    if (!existsSync(envPath)) return null;
+    const content = readFileSync(envPath, 'utf8');
+    const port = content.match(/^PORT=(\d+)$/m)?.[1];
+    if (!port) return null;
+    const range = content.match(/^MORPH_PORT_RANGE=([\d-]+)$/m)?.[1];
+    return `🔌 Ambiente desta worktree: PORT=${port}${range ? ` (bloco ${range})` : ''}. ` +
+      `Suba dev servers SEMPRE nessas portas (fonte: .morph/worktree.env) — as portas padrão pertencem à raiz.`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fleet handoff line: point the fresh session at the compressed handoff doc
+ * before it starts re-deriving context by hand. Fail-open.
+ */
+function buildHandoffLine(dir, feature) {
+  try {
+    const handoffPath = join(dir, '.morph', 'features', feature, 'handoff.md');
+    if (!existsSync(handoffPath)) return null;
+    const generatedAt = readFileSync(handoffPath, 'utf8')
+      .match(/gerado em (\d{4}-\d{2}-\d{2}T[\d:.]+Z)/)?.[1];
+    return `📄 Handoff: .morph/features/${feature}/handoff.md${generatedAt ? ` (gerado ${generatedAt})` : ''} — leia antes de continuar.`;
+  } catch {
+    return null;
+  }
+}
+
 function buildWorktreeContext(dir, feature) {
   const phase = getFeaturePhase(feature, dir);
   let text = `🌳 Worktree desta feature: ${feature} (branch morph/${feature}, fase ${phase}). ` +
     `Trabalhe apenas nesta feature nesta sessão; o estado vive no .morph/ deste worktree.`;
 
+  const envLine = buildEnvLine(dir);
+  if (envLine) text += `\n${envLine}`;
+
+  const handoffLine = buildHandoffLine(dir, feature);
+  if (handoffLine) text += `\n${handoffLine}`;
+
   const missingJunctions = !existsSync(join(dir, 'node_modules')) || !existsSync(join(dir, '.claude'));
   if (missingJunctions) {
     text += `\n⚠ Infra compartilhada ausente (node_modules/.claude). Rode: morph-spec worktree link --all`;

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.1.2"
+cliVersion: "8.2.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.1.2"
+cliVersion: "8.2.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.1.2"
+cliVersion: "8.2.0"
 ---
 
 # morph-apply
@@ -177,7 +177,7 @@ Depois do batch paralelo, executar o restante em modo sequencial (passo 3a).
 
 Quando o `morph-spec dag {feature}` reporta `isolation.recommended: "worktree"` (dois fluxos paralelos planejam escrever no mesmo path — colisão de `outputs`), despache cada fluxo com o parâmetro `isolation: "worktree"` do tool Agent. Cada agente trabalha numa working tree própria; build/test rodam lá dentro sem colidir.
 
-1. **Dispatch:** mesmo `subagent_type: "morph-{id}"` e standards de §3b, mais `isolation: "worktree"`. Se a stack for Node e faltar `node_modules` no worktree, o agente roda `morph-spec worktree link` (fail-open) antes de testar; se ainda impossível, reporta "verificação: não executada" (o verify pós-merge cobre). O agente commita na branch do worktree e reporta a branch.
+1. **Dispatch:** mesmo `subagent_type: "morph-{id}"` e standards de §3b, mais `isolation: "worktree"`. Se a stack for Node e faltar `node_modules` no worktree, o agente roda `morph-spec worktree link` (fail-open) antes de testar; se ainda impossível, reporta "verificação: não executada" (o verify pós-merge cobre). Se o agente precisar subir um dev server e existir `.morph/worktree.env` no seu cwd, usa as portas de lá (nunca as padrão — MORPH.md §2.2). O agente commita na branch do worktree e reporta a branch.
 2. **Integração (orquestrador, após todos os relatórios):** faça o merge de cada branch reportada, uma por vez, na ordem de chegada — `git merge --no-ff <branch>`. Conflito → `git merge --abort`, marque a task de volta a `pending` com nota "merge conflict — reexecutar sequencial", siga para a próxima branch. Os paths em conflito são exatamente os de `isolation.collisions` do dag.
 3. **Pós-merge:** rode `morph-spec verify {feature} --json` UMA vez (o merge é o novo ponto de integração — verificação compartilhada obrigatória), depois `morph-eval` + `morph-spec score` por relatório, como em §3b.
 4. **Cleanup:** `git worktree remove` + `git branch -d` das branches integradas + `git worktree prune` (fail-open). Branches não integradas ficam e são registradas no recap com o motivo.

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.1.2"
+cliVersion: "8.2.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.1.2"
+cliVersion: "8.2.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.1.2"
+cliVersion: "8.2.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.1.2"
+cliVersion: "8.2.0"
 ---
 
 # morph-implement

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

@@ -4,7 +4,7 @@ description: Guia a produção dos três artefatos de planejamento de uma featur
 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.1.2"
+cliVersion: "8.2.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.1.2"
+cliVersion: "8.2.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.1.2"
+cliVersion: "8.2.0"
 ---
 
 # morph-review

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.1.2",
+  "version": "8.2.0",
   "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';
 
@@ -196,7 +196,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 +205,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 +249,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 +418,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 +481,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) {
@@ -524,7 +564,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();
@@ -1084,6 +1124,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`

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'));
+}