@polymorphism-tech/morph-spec 8.4.0 → 8.5.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.4.0  
+**Version:** 8.5.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -140,7 +140,7 @@ These commands are available inside Claude Code after init.
 | `/morph-apply {feature}`       | Autonomous execution + review (Gate 3)                        |
 | `/morph-hotfix {feature}`      | Surgical hotfix ADW — scout → fix → human Gate 3 → ship         |
 | `/morph-status [feature]`      | Status of the active (or specified) feature                      |
-| `/morph-archive {feature}`     | Archive a completed feature (after Gate 3)                          |
+| `/morph-archive {feature}`     | Archive **without integrating** (legacy feature / cleanup); normal close is `morph-spec finish --pr\|--merge` |
 | `/morph-preflight`             | Pre-deploy validation (specs, contracts, tests, infra)                |
 | `/morph-troubleshoot [error]`  | Root-cause diagnosis for .NET/Next.js errors                            |
 
@@ -167,9 +167,12 @@ morph-spec status {feature}                    # Feature status dashboard
 morph-spec approve {feature} {gate}            # Approve a phase gate (proposal, plan, review)
 morph-spec advance {feature}                   # Approve the current gate and scaffold the next phase folder
 morph-spec approval-status {feature}           # Show approval status for all gates
-morph-spec archive {feature}                   # Archive a completed feature (after Gate 3)
+morph-spec finish {feature} --pr|--merge       # Close a feature: archive + integrate (PR or local merge) + teardown
+morph-spec archive {feature}                   # Archive WITHOUT integrating (legacy feature / cleanup)
 ```
 
+`finish` is the normal close for both flows: it archives (committing the move inside `morph/{feature}`), then integrates — `--merge` merges `--no-ff` into the default branch locally; `--pr` pushes the branch and runs `gh pr create` (needs `origin` + authenticated `gh`) — and tears down the worktree if there is one. Plain `archive` is reserved for legacy features (born before every feature had a `morph/{feature}` branch) and cleanup.
+
 Task progress within a feature is tracked with the native `TaskCreate`/`TaskUpdate` tools, persisted to `tasks.json` — there is no separate CLI command for starting or completing a task.
 
 ### Validation
@@ -196,8 +199,8 @@ morph-spec dag {feature} [--mermaid]                            # DAG dispatch d
 morph-spec create {feature} --description "<what/why>" --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 list [--json]        # List active feature worktrees with phase/gate status
+# Close a worktree feature with `morph-spec finish {feature} --pr|--merge` (see Feature workflow) — it absorbed `worktree finish`.
 ```
 
 ---
@@ -365,4 +368,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.4.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.5.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -23,13 +23,14 @@ import { installPluginCommand } from '../src/commands/project/install-plugin-cmd
 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 { worktreeSetupCommand, worktreeLinkCommand, 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';
 import { advanceCommand } from '../src/commands/state/advance.js';
 import { archiveCommand } from '../src/commands/state/archive.js';
+import { finishCommand } from '../src/commands/state/finish.js';
 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';
@@ -158,11 +159,21 @@ program
 
 program
   .command('archive <feature>')
-  .description('Archive a completed feature (atomic, git-aware): move folder + update state')
+  .description('Archive a completed feature (atomic, git-aware): move folder + update state. Archive WITHOUT integrating (legacy features, cleanup) — the close path is `finish`')
   .option('--no-git', 'Skip git staging of the move')
   .option('--force', 'Archive even if Gate 3 (review) is not approved')
   .action((feature, options) => archiveCommand(feature, options));
 
+program
+  .command('finish <feature>')
+  .description('Close a feature: archive → integrate. --merge merges morph/{f} into the default (local); --pr pushes it + opens a PR. Works with and without a worktree')
+  .option('--pr', 'Push morph/{feature} and open a PR against the default branch (no local merge)')
+  .option('--merge', 'Merge morph/{feature} into the default branch locally (no push)')
+  .option('--keep', 'Keep the worktree/branch after integrating (worktree flow only)')
+  .option('--force', 'Skip the Gate-3-approved precondition')
+  .option('--discard-ignored', 'Allow removing the worktree even though it holds gitignored files that exist nowhere else (e.g. .env) — they are destroyed')
+  .action((feature, options) => finishCommand(feature, options));
+
 program
   .command('delete <feature>')
   .description('Delete a feature (hard by default; --archive marks it abandoned). Refuses if a gate is approved unless --force')
@@ -341,14 +352,6 @@ worktreeCommand
   .option('--all', 'Link all shared dirs, not just node_modules')
   .action((options) => worktreeLinkCommand(options));
 
-worktreeCommand
-  .command('finish <feature>')
-  .description('Merge the feature branch back into the primary root and clean up the worktree (requires Gate 3 approved)')
-  .option('--keep', 'Keep the worktree and branch after merging')
-  .option('--force', 'Skip the Gate-3-approved precondition')
-  .option('--discard-ignored', 'Allow removing the worktree even though it holds gitignored files that exist nowhere else (e.g. .env) — they are destroyed')
-  .action((feature, options) => worktreeFinishCommand(feature, options));
-
 worktreeCommand
   .command('list')
   .description('List active feature worktrees with their phase and gate status')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.4.0",
+  "version": "8.5.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

@@ -46,7 +46,7 @@ proposal → [uiux] → plan → implement → review
 | `/morph-hotfix {feature}` | Surgical hotfix ADW (scout → fix → human gate → ship) |
 | `/morph-apply {feature}` | Autonomous execution + review (Gate 3) |
 | `/morph-status [feature]` | Status of the active (or specified) feature |
-| `/morph-archive {feature}` | Archive a completed feature (after Gate 3) |
+| `/morph-archive {feature}` | Archive **without integrating** (legacy feature / cleanup) — normal close is `morph-spec finish --pr\|--merge` |
 | `/morph-preflight` | Pre-deploy validation (specs, contracts, tests, infra) |
 | `/morph-troubleshoot [error]` | Root-cause diagnosis for .NET/Next.js errors |
 
@@ -59,9 +59,12 @@ morph-spec approve {feature} {gate} [--mode auto] [--approver name] [--notes tex
 morph-spec advance {feature} [--design]         # approve current gate + scaffold next phase folder in one step
 morph-spec approval-status {feature} [--json]
 morph-spec unapprove {feature} {gate} [--reason text]   # recovery only
-morph-spec archive {feature} [--force] [--no-git]
+morph-spec finish {feature} --pr|--merge [--keep] [--force] [--discard-ignored]   # normal close: archive + integrate + teardown
+morph-spec archive {feature} [--force] [--no-git]        # archive WITHOUT integrating (legacy feature / cleanup)
 ```
 
+`finish` is the normal way to close a feature (both the worktree flow and the common flow): it archives (committing the move inside `morph/{feature}`), then integrates — `--merge` merges `--no-ff` into the default branch locally (no push); `--pr` pushes `morph/{feature}` + `gh pr create` (needs `origin` + authenticated `gh`). It then tears down the worktree and releases the port block. `archive` alone is reserved for legacy features (no `morph/{feature}` branch) and cleanup.
+
 ---
 
 ## CLI — feature birth & work-type routing
@@ -116,8 +119,8 @@ One feature = one git worktree = one Claude Code instance. Each worktree gets it
 morph-spec create {feature} --description "<what/why>" --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 + release ports (requires Gate 3)
 morph-spec worktree list [--json]          # active feature worktrees with phase/gate status
+# Close a worktree feature with `morph-spec finish {feature} --pr|--merge` (see above) — it absorbed `worktree finish`.
 morph-spec handoff {feature} [--json]      # regenerate the compressed session-handoff doc (pointers, not copies)
 morph-spec fleet [--json]                  # every active feature (root + worktrees) with phase/gates/ports/handoff/activity
 ```
@@ -182,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.4.0 by Polymorphism Tech*
+*morph-spec v8.5.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -168,13 +168,16 @@ morph-spec create my-feature --description "what & why" --worktree   # birth the
 morph-spec worktree setup my-feature         # creates .worktrees/my-feature/ on branch morph/my-feature
 ```
 
-Open the new worktree directory in its own Claude Code instance and work normally — a SessionStart hook injects the worktree's feature identity into context automatically. When the feature is done:
+Open the new worktree directory in its own Claude Code instance and work normally — a SessionStart hook injects the worktree's feature identity into context automatically. When the feature is done (Gate 3 approved), close it in one step:
 
 ```bash
-morph-spec worktree finish my-feature        # merges --no-ff back into the primary root, then cleans up
-morph-spec archive my-feature                # run at the primary root afterward
+morph-spec finish my-feature --merge         # archive + merge --no-ff into the default branch (local), tear down the worktree
+# or, to open a PR instead of merging locally:
+morph-spec finish my-feature --pr            # archive + push morph/my-feature + gh pr create (keeps the branch the PR needs)
 ```
 
+`finish` archives the feature (committing the move inside `morph/my-feature`) *and* integrates *and* tears down the worktree in one step — it replaces the old `worktree finish` + separate `archive`. The same command closes features developed **without** a worktree (they're born on `morph/{feature}` too).
+
 List every active worktree with its phase and gate status:
 
 ```bash
@@ -246,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.4.0 by Polymorphism Tech*
+*morph-spec v8.5.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -36,23 +36,24 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 | `/morph-hotfix {feature}` | ADW cirúrgico de hotfix (scout → fix → gate humano → ship) |
 | `/morph-apply {feature}` | Execução autônoma + review (Gate 3) |
 | `/morph-status [feature]` | Status da feature ativa (ou a especificada) |
-| `/morph-archive {feature}` | Arquiva feature concluída (após Gate 3) — wrapper de `morph-spec archive` (atômico, git-aware) |
+| `/morph-archive {feature}` | Arquiva-**sem-integrar** (features legadas/faxina) — wrapper de `morph-spec archive`. Fechamento normal = `morph-spec finish --pr\|--merge` |
 | `/morph-preflight` | Validação pré-deploy (specs, contratos, testes, infra) |
 | `/morph-troubleshoot [erro]` | Diagnóstico de erros .NET/Next.js com root-cause analysis |
 
 **Comandos CLI de gate e de estado** (a LLM os usa em vez de editar o estado à mão):
 - `morph-spec approve <feature> <gate> --mode auto` — aprova um gate (`proposal`/`plan`/`review`) em `trust: auto`.
 - `morph-spec advance <feature>` — aprova o gate da fase corrente **e** cria a pasta da próxima fase num passo só (`--design` toma o ramo opcional de uiux a partir da proposta).
-- `morph-spec archive <feature>` — arquiva a feature (atômico, git-aware); é o que `/morph-archive` chama.
+- `morph-spec archive <feature>` — arquiva-**sem-integrar** (atômico, git-aware, commita o move escopado por pathspec): reservado a features legadas (sem branch `morph/{f}`) e faxina. O fechamento normal (arquiva **e** integra num passo) é `morph-spec finish`. É o que `/morph-archive` chama.
+- `morph-spec finish <feature> --pr|--merge` — o **encerramento único** da feature (worktree ou comum): **arquiva** commitando `features/{f} → archive/{f}` dentro de `morph/{f}`, depois integra. `--merge` faz merge `--no-ff` **local** na default (sem push); `--pr` faz `push` + `gh pr create` (exige `origin` + `gh`, checados **antes** de arquivar — um `--pr` recusado não deixa meio-estado). Desmonta o worktree (PROVE-or-DECLINE) e libera o bloco de portas; no `--pr` **preserva** a branch (o PR precisa dela) e fica em `morph/{f}`. Flags: `--keep` mantém o worktree, `--force` dispensa o Gate 3, `--discard-ignored` consente descartar gitignored no teardown. Substitui o antigo `worktree finish` + `archive` separados.
 - `morph-spec dag <feature>` — análise do DAG de tasks.json com decisão sequencial vs paralelo **ponderada por effort** (raízes S vão inline, nunca ganham agente próprio).
 - `morph-spec score <feature> <task> <score> [--dims a,c,q,t]` — grava `taskScores` no feature.json com timestamp server-side; **nunca edite taskScores à mão**. Em PowerShell, cite o valor de `--dims` entre aspas (`--dims "9.5,9,9,9"`) — sem aspas, a lista pode chegar como tokens separados; o parser aceita ambas as formas, mas citar evita qualquer ambiguidade.
 - `morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]` — grava `gateDecisions` no feature.json com timestamp server-side (shape em `framework/schemas/feature.schema.json`); **nunca edite gateDecisions à mão** — o Edit manual colide com o hook state-sync.
-- `morph-spec create <feature> --description "<o quê/porquê>" --type <feature|bug|chore|hotfix> [--request "<txt>"] [--name "<nome>"] [--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). **Identidade no nascimento:** `name` (default = slug) e `description` são carimbados; a `--description` é **obrigatória** numa feature nova (ou `--request`, que a semeia) — sem nenhuma das duas o `create` recusa (fim dos scaffolds anônimos). `--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` + `--request`/`--description`); `--worktree` já nasce a feature no seu worktree próprio.
+- `morph-spec create <feature> --description "<o quê/porquê>" --type <feature|bug|chore|hotfix> [--request "<txt>"] [--name "<nome>"] [--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). **Identidade no nascimento:** `name` (default = slug) e `description` são carimbados; a `--description` é **obrigatória** numa feature nova (ou `--request`, que a semeia) — sem nenhuma das duas o `create` recusa (fim dos scaffolds anônimos). `--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` + `--request`/`--description`); `--worktree` já nasce a feature no seu worktree próprio. **Toda feature nasce numa branch `morph/{f}`** (ramificada da default) mesmo sem `--worktree` — por isso o fechamento por `morph-spec finish` é idêntico nos dois fluxos.
 - `morph-spec list [--all] [--json]` — o quadro de auditoria: uma linha por feature × workType × status × fase × gates G1/G2/G3 × descrição, com `⚠` para inconsistências (sem descrição, ordem de gate). `--all` inclui as arquivadas; `--json` para scripting. É o complemento do `delete` (enxergar o que está morto antes de remover).
 - `morph-spec delete <feature> [--archive] [--force]` — remove uma feature. Hard por padrão (pasta apagada, git-aware, + entrada podada do índice raiz para não ressuscitar); `--archive` move para `.morph/archive` com status `abandoned` em vez de apagar. Recusa se algum gate estiver aprovado, a menos que `--force`. Use para faxina de scaffolds mortos e drafts abandonados (`archive` é para trabalho concluído; `delete` é para trabalho morto).
 - `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}`, 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 worktree setup|link|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; `list` mostra fase/gate de cada worktree ativo). O fechamento saiu daqui — use `morph-spec finish` (acima).
 - `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.
 - `morph-spec telemetry [--json] [--feature <f>] [--limit <n>]` — reconstrói o caminho de execução da sessão a partir de `.morph/logs/events.jsonl` (skills invocadas, personas despachadas + prompts, standards/base de conhecimento lidos, mix de tools, prompts do usuário). Capturado silenciosamente pelo hook `telemetry-log` em todo tool call e todo UserPromptSubmit.
@@ -74,7 +75,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 Toda feature nasce com um `workType` (`morph-spec create <f> --description "<o quê/porquê>" --type <tipo>` ou classificado de `--request "<pedido>"`, que também semeia a descrição obrigatória) 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> --description "<o quê/porquê>" --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.
+Features independentes podem rodar em paralelo, cada uma isolada num git worktree (`morph-spec create <f> --description "<o quê/porquê>" --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 e rode `morph-spec finish <f> --pr|--merge` (arquiva dentro da branch, integra e desmonta o worktree num passo só). Visão agregada: `morph-spec fleet`. Detalhes em `.morph/framework/MORPH.md` §2.2.
 
 ## Personas (em `.claude/agents/`)
 

package/framework/MORPH.md

@@ -112,6 +112,8 @@ Nem todo trabalho merece o pipeline completo. Cada feature nasce com **identidad
 
 **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).
 
+**Nascimento numa branch:** toda feature — **com ou sem `--worktree`** — nasce numa branch `morph/{f}` ramificada da default. O fluxo comum (sem worktree) desenvolve direto em `morph/{f}` na raiz; o fluxo worktree isola em `.worktrees/{f}`. Por construção o fechamento é simétrico: `morph-spec finish <f> --pr|--merge` (§2.2) fecha os dois do mesmo jeito. Features criadas **antes** deste modelo (sem branch `morph/{f}`) fecham por `morph-spec archive <f>` (arquivar-sem-integrar), não por `finish`.
+
 ### 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> --description "<o quê/porquê>" --worktree` (ou `morph-spec worktree setup <f>`) cria `.worktrees/{f}/` na branch `morph/{f}`. Contrato:
@@ -125,7 +127,7 @@ Features independentes podem ser desenvolvidas **em paralelo, cada uma no seu gi
 - **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.
+- **Fechamento:** aprove o Gate 3, depois **`morph-spec finish <f> --pr|--merge`** — o encerramento único e simétrico (mesmo comando nos dois fluxos, worktree e comum). Ele **arquiva** a feature commitando o move `features/{f} → archive/{f}` **dentro da branch `morph/{f}`** (o estado arquivado viaja na própria integração, não num commit à parte) e então integra: `--merge` faz o merge `--no-ff` **local** na branch default (sem push; recusa se worktree/raiz estiverem sujos; aborta em conflito) e `--pr` faz `push` de `morph/{f}` + `gh pr create` (sem merge local; exige `origin` + `gh` autenticado — as pré-condições rodam **antes** de arquivar, então um `--pr` recusado não deixa meio-estado). Em ambos o worktree é desmontado (PROVE-or-DECLINE) e o bloco de portas liberado; no `--pr` a branch é **preservada** (o PR aberto precisa dela) e a sessão permanece em `morph/{f}`. Não há mais `worktree finish` nem `archive` separado no caminho feliz — `morph-spec archive` fica reservado a arquivar-sem-integrar (features legadas, faxina).
 
 ---
 

package/framework/commands/morph-archive.md

@@ -6,12 +6,18 @@ allowed-tools: Read, Bash
 
 # Archive MORPH Feature
 
-Archive a feature that has cleared Gate 3 (review). Use when the work is shipped and you want the
-feature out of the active set in `.morph/features/`.
+Archive-**without-integrate**: move a feature out of the active set in `.morph/features/` without
+merging or opening a PR. This is the **reserved** path — for **legacy** features (born before the
+"every feature is born on a `morph/{f}` branch" model, so there's no branch to integrate) and for
+**cleanup**. The **normal close** of a feature is `morph-spec finish {feature} --pr|--merge`, which
+archives *and* integrates *and* tears down the worktree in one step (see `MORPH.md` §2.2 and
+`morph-apply` §6). Reach for `/morph-archive` only when integration is not wanted.
 
 This is a thin wrapper over the atomic, git-aware CLI command — do **not** move folders or edit state
 by hand. The command moves the folder, stamps the feature `completed` + `archivedAt` in its
-`feature.json`, stages the move in git, and cleans the derivable root index, all-or-nothing.
+`feature.json`, **commits the move scoped to the feature's own pathspec** (`.morph/features/{f}` +
+`.morph/archive/{f}`, never `commit -a`), and cleans the derivable root index, all-or-nothing. Re-running
+is idempotent: an already-archived feature is reported, not re-moved.
 
 ## Workflow
 
@@ -28,7 +34,8 @@ by hand. The command moves the folder, stamps the feature `completed` + `archive
    ```
    The command refuses if Gate 3 isn't approved (override with `--force` only when the user asks).
    It moves `.morph/features/{feature}/` → `.morph/archive/{feature}/` (via `git mv` when possible),
-   sets `status: "completed"` + `archivedAt`, and drops the feature from the thin index.
+   sets `status: "completed"` + `archivedAt`, commits that move scoped to the feature's pathspec, and
+   drops the feature from the thin index.
 
 3. **Report** the new path (`.morph/archive/{feature}/`). Do not invent metrics not recorded in
    `feature.json` or `recap.md`.

package/framework/schemas/feature.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "MORPH-SPEC feature.json",
-  "description": "Canonical shape of the authoritative, committed per-feature state at .morph/features/{feature}/feature.json (v5 per-feature state model). Born via `morph-spec create` (explicit) or the state-sync hook (implicit fallback). Server-side writers: `morph-spec approve/advance` (approvalGates), `morph-spec score` (taskScores), `morph-spec gate-decision` (gateDecisions), `morph-spec archive` (status/archivedAt). Never hand-edit the CLI-owned fields — manual Edits collide with the state-sync hook. This schema is documentational: additionalProperties stays true so older/newer CLIs interoperate.",
+  "description": "Canonical shape of the authoritative, committed per-feature state at .morph/features/{feature}/feature.json (v5 per-feature state model). Born via `morph-spec create` (explicit) or the state-sync hook (implicit fallback). Server-side writers: `morph-spec approve/advance` (approvalGates), `morph-spec score` (taskScores), `morph-spec gate-decision` (gateDecisions), `morph-spec archive`/`finish` (status/archivedAt — `finish` archives internally before integrating). Never hand-edit the CLI-owned fields — manual Edits collide with the state-sync hook. This schema is documentational: additionalProperties stays true so older/newer CLIs interoperate.",
   "type": "object",
   "required": ["status", "approvalGates"],
   "properties": {
@@ -200,7 +200,7 @@
     },
     "worktree": {
       "type": "object",
-      "description": "Bookkeeping do worktree ativo desta feature no ROOT feature.json, gravado por `morph-spec worktree setup` (via `create --worktree` ou standalone). Removido por `worktree finish`.",
+      "description": "Bookkeeping do worktree ativo desta feature no ROOT feature.json, gravado por `morph-spec worktree setup` (via `create --worktree` ou standalone). Removido no fechamento por `morph-spec finish` (que absorveu o antigo `worktree finish`).",
       "properties": {
         "path": { "type": "string" },
         "branch": { "type": "string" },

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.4.0"
+cliVersion: "8.5.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.4.0"
+cliVersion: "8.5.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.4.0"
+cliVersion: "8.5.0"
 ---
 
 # morph-apply
@@ -218,11 +218,14 @@ O comando grava `gateDecisions.review = { pause, reason, signals, trust, decided
 - Pause: `AskUserQuestion` com options `["aprovado, fechar feature", "preciso ajustar", "rollback"]`.
 - Auto: exibir summary do review-report, aprovar via `morph-spec approve {feature} review --mode auto`, e prosseguir.
 
-### 6. Pós Gate 3
+### 6. Pós Gate 3 — encerramento
 
 - Aprovar o Gate 3: em auto, `morph-spec approve {feature} review --mode auto`; em manual, o hook state-sync registra a resposta "aprovado" em AskUserQuestion. O gate fica gravado no `feature.json` autoritativo da feature — nunca via Edit à mão de `state.json`.
-- Sinalizar: "Feature {nome} concluída. Rode `/morph-archive {feature}` para arquivar."
-- Não arquivar automaticamente.
+- **Fechar a feature** com `morph-spec finish {feature} --pr|--merge` — um passo só: arquiva commitando `features/{f} → archive/{f}` dentro de `morph/{f}`, integra e desmonta o worktree (se houver). Escolha o modo com `AskUserQuestion` (header `"Integração"`):
+  - **Abrir PR** (`--pr`): faz `push` de `morph/{f}` + `gh pr create` com base na default — para review por outro humano/CI antes do merge. Exige `origin` + `gh` autenticado (checados **antes** de arquivar; se faltarem, `finish` recusa sem efeito colateral — caia para `--merge`). A branch é preservada e a sessão fica em `morph/{f}`.
+  - **Merge local** (`--merge`): merge `--no-ff` na default **localmente**, sem push — para o fluxo single-user direto. Remove a branch e o worktree.
+- Não integre automaticamente sem a escolha do modo: `finish` toca o remoto (`--pr`) ou a branch default (`--merge`) — é uma ação de saída que pede confirmação.
+- Feature **legada** (criada antes do modelo "nasce numa branch", sem `morph/{f}`): `finish` recusa e roteia para `morph-spec archive {feature}` (arquivar-sem-integrar); nesse caso, arquive.
 
 ## Anti-padrões
 
@@ -240,7 +243,7 @@ O comando grava `gateDecisions.review = { pause, reason, signals, trust, decided
 - `.morph/features/{feature}/3-implement/recap.md` produzido por morph-implement.
 - `.morph/features/{feature}/4-review/review-report.md` produzido por morph-review.
 - Gate 3 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo) — via `morph-spec approve` em auto, ou pelo hook state-sync no caminho manual.
-- Feature com Gate 3 aprovado e pronta para `morph-spec archive` (que carimba `status: "completed"` + `archivedAt`).
+- Feature com Gate 3 aprovado e **fechada** por `morph-spec finish --pr|--merge` (arquiva carimbando `status: "completed"` + `archivedAt`, integra e desmonta num passo) — ou, se legada, por `morph-spec archive`.
 
 ## Referências
 

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.4.0"
+cliVersion: "8.5.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.4.0"
+cliVersion: "8.5.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.4.0"
+cliVersion: "8.5.0"
 ---
 
 # morph-hotfix
@@ -103,8 +103,8 @@ options:
 ### 8. Pós-gate (o "test loop → ship" de `MORPH.md` §2.1)
 
 - Rode a suíte completa uma vez: `morph-spec verify {feature}` (sem escopo de task — cobertura da feature inteira, agora que o Gate 3 está aprovado).
-- Sinalize ao usuário: commit do fix e `morph-spec archive {feature}` (ou `morph-spec worktree finish {feature}` se a feature nasceu em worktree — ver `MORPH.md` §2.2) estão prontos.
-- Não arquive automaticamente — usuário decide quando.
+- Feche com `morph-spec finish {feature} --pr|--merge` — o mesmo encerramento único das demais features (arquiva commitando dentro de `morph/{f}`, integra, desmonta). Num hotfix urgente o `--merge` (local, direto na default) costuma ser o caminho; use `--pr` quando o fix precisa passar por CI/review antes do merge. Ver `MORPH.md` §2.2.
+- Não integre automaticamente — o usuário decide quando e por qual modo (`finish` toca a default ou o remoto). Feature legada sem `morph/{f}`: `finish` roteia para `morph-spec archive {feature}`.
 
 ## Anti-padrões
 

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.4.0"
+cliVersion: "8.5.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.4.0"
+cliVersion: "8.5.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.4.0"
+cliVersion: "8.5.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.4.0"
+cliVersion: "8.5.0"
 ---
 
 # morph-review
@@ -102,7 +102,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    question: "Gate 3 — Review de {feature} aprovado?{ reason ? ' Sinal: ' + reason : '' }"
    header: "Gate 3"
    options:
-     - { label: "aprovado, fechar feature", description: "Marcar feature como completed, habilitar /morph-archive" }
+     - { label: "aprovado, fechar feature", description: "Marcar review aprovado; próximo passo é fechar com morph-spec finish --pr|--merge (ver morph-apply §6)" }
      - { label: "preciso ajustar", description: "Apontar correções necessárias antes de fechar" }
      - { label: "rollback", description: "Desfazer e voltar para implement" }
    ```
@@ -120,6 +120,8 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
    No caminho manual, o hook state-sync detecta a aprovação em answers de AskUserQuestion e grava `approvalGates.review = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo da feature. Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} review --mode auto` — nunca via Edit à mão de state.json.
 
+   **Próximo passo (não é desta skill):** com o Gate 3 aprovado, a feature fecha por `morph-spec finish {feature} --pr|--merge` — a `morph-apply` §6 conduz a escolha PR vs merge. Não arquive nem integre aqui.
+
 ## Output esperado
 - `.morph/features/{feature}/4-review/evaluator-report.md` — relatório bruto e autoritativo do
   `morph-evaluator` despachado no passo 4 (canal durável, ver MORPH.md §6)

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.4.0"
+cliVersion: "8.5.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.4.0"
+cliVersion: "8.5.0"
 ---
 
 # morph-standards

package/package.json

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