@polymorphism-tech/morph-spec 8.3.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.3.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
@@ -184,8 +187,8 @@ morph-spec verify {feature} [task]     # Deterministic build+tests+validators ch
 ### Work-type routing
 
 ```bash
-morph-spec create {feature} --type feature|bug|chore|hotfix   # Explicit birth: type dimensions the pipeline
-morph-spec create {feature} --request "<free text>"           # Deterministic detector classifies the type
+morph-spec create {feature} --type feature|bug|chore|hotfix --description "<what/why>"   # Explicit birth: type dimensions the pipeline, description is required
+morph-spec create {feature} --request "<free text>"           # Detector classifies the type AND seeds the description
 morph-spec retype {feature} {newType}                          # Change work type mid-flight (blocked after Gate 3)
 morph-spec dag {feature} [--mermaid]                            # DAG dispatch decision; --mermaid emits a flowchart
 ```
@@ -193,11 +196,11 @@ morph-spec dag {feature} [--mermaid]                            # DAG dispatch d
 ### Worktrees (parallel development)
 
 ```bash
-morph-spec create {feature} --worktree   # Birth the feature already isolated in its own worktree
+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.3.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.5.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -23,18 +23,21 @@ 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';
 import { retypeCommand } from '../src/commands/state/retype.js';
 import { handoffCommand } from '../src/commands/state/handoff.js';
+import { listCommand } from '../src/commands/state/list.js';
+import { deleteCommand } from '../src/commands/state/delete.js';
 
 // === Tasks ===
 import { dagCommand } from '../src/commands/tasks/dag.js';
@@ -126,13 +129,22 @@ program
   .option('-v, --verbose', 'Show detailed output')
   .action(statusCommand);
 
+program
+  .command('list')
+  .description('List every feature × status × gates (G1/G2/G3) × workType — the audit board')
+  .option('--all', 'Include archived features (.morph/archive)')
+  .option('--archived', 'Include archived features (alias of --all)')
+  .option('--json', 'Output as JSON')
+  .action((options) => listCommand(options));
+
 // ─── Approval gates (dev-only) ────────────────────────────────────────────
 program
   .command('approve <feature> <gate>')
-  .description('Approve a phase gate (proposal, plan, review)')
+  .description('Approve a phase gate (proposal, plan, review). Enforces gate order (N requires N-1)')
   .option('--approver <name>', 'Name of approver (default: current user when interactive, "auto" otherwise)')
   .option('--mode <mode>', 'Approval mode: "user" or "auto" (default: detected from TTY)')
   .option('--notes <notes>', 'Approval notes')
+  .option('--force', 'Approve out of order (bypass the gate-monotonicity check)')
   .action((feature, gate, options) => approveCommand(feature, gate, options));
 
 program
@@ -142,15 +154,35 @@ program
   .option('--mode <mode>', 'Approval mode: "user" or "auto" (default: detected from TTY)')
   .option('--design', 'From proposal, advance into the optional design (uiux) phase instead of plan')
   .option('--notes <notes>', 'Approval notes')
+  .option('--force', 'Advance even if a prerequisite gate is unapproved (out-of-order recovery)')
   .action((feature, options) => advanceCommand(feature, options));
 
 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')
+  .option('--archive', 'Soft delete: move to .morph/archive with status "abandoned" instead of removing')
+  .option('--force', 'Delete even when a gate is approved')
+  .option('--no-git', 'Skip git staging of the removal')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => deleteCommand(feature, options));
+
 program
   .command('approval-status <feature>')
   .description('Show approval status for all gates')
@@ -178,6 +210,8 @@ program
 program
   .command('create <feature>')
   .description('Classify work type (--type/--request), scaffold + stamp policy gates, and create the canonical feature.json (explicit birth — see framework/schemas/feature.schema.json)')
+  .option('--name <name>', 'Human-readable feature name (default: the slug)')
+  .option('--description <text>', 'What/why of the feature — required at birth unless --request is given (it seeds the description)')
   .option('--status <status>', 'Initial feature status (default: in_progress)')
   .option('--type <type>', 'Work type: feature|bug|chore|hotfix (default: feature) — see src/core/work-types.js')
   .option('--request <text>', 'Free-text request classified by the deterministic detector; tie/none exits 2 with candidates for an LLM/user decision (feature NOT created)')
@@ -318,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.3.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,18 +59,23 @@ 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
 
 Every feature is born with a **work type** that dimensions its pipeline: `feature` (full proposal → [uiux] → plan → implement → review), `bug` (lean), `chore` (fast-track straight to implement), `hotfix` (scout → surgical fix → human Gate 3 always, even under `trust: auto`).
 
+Every feature is also born with an **identity**: `--description` is required (`create` refuses a nameless scaffold without it), `name` defaults to the slug.
+
 ```bash
-morph-spec create {feature} --type feature|bug|chore|hotfix
-morph-spec create {feature} --request "<free text>"      # deterministic detector classifies the type
+morph-spec create {feature} --type feature|bug|chore|hotfix --description "<what/why>"
+morph-spec create {feature} --request "<free text>"       # detector classifies the type AND seeds the description
 morph-spec retype {feature} {newType}                     # change type mid-flight (blocked after Gate 3)
 ```
 
@@ -111,11 +116,11 @@ morph-spec dag {feature} --mermaid         # emit the tasks.json DAG as a Mermai
 One feature = one git worktree = one Claude Code instance. Each worktree gets its own 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 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
 ```
@@ -180,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.3.0 by Polymorphism Tech*
+*morph-spec v8.5.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -129,14 +129,20 @@ morph-spec verify my-feature T001      # scoped to one task
 
 Not every change needs the full pipeline walked above. Every feature is born with a **work type** that dimensions its pipeline:
 
+Every feature is also born with an **identity** — a `--description` (the one field a human must supply; `create` refuses a nameless scaffold without it) and a `name` (defaults to the slug):
+
 ```bash
-morph-spec create my-feature --type feature   # default: full proposal → [uiux] → plan → implement → review
-morph-spec create my-fix --type bug           # lean proposal/plan
-morph-spec create my-chore --type chore       # skips straight to implement (Gates 1/2 stamped by policy)
-morph-spec create my-hotfix --type hotfix     # scout → surgical fix → test loop; Gate 3 always pauses for a human
+# full: proposal → [uiux] → plan → implement → review
+morph-spec create my-feature --type feature --description "what & why"
+# bug: lean proposal/plan
+morph-spec create my-fix --type bug --description "what broke"
+# chore: skips straight to implement (Gates 1/2 stamped by policy)
+morph-spec create my-chore --type chore --description "the tidy-up"
+# hotfix: scout → surgical fix → test loop; Gate 3 always pauses for a human
+morph-spec create my-hotfix --type hotfix --description "the incident"
 ```
 
-You can also let the deterministic detector classify a free-text request instead of picking a type by hand:
+You can also let the deterministic detector classify a free-text request instead of picking a type by hand (`--request` doubles as the description):
 
 ```bash
 morph-spec create my-feature --request "produção caiu, corrigir urgente"
@@ -157,18 +163,21 @@ Production incidents run through the dedicated `/morph-hotfix my-feature` slash
 Independent features can be developed in parallel, each isolated in its own git worktree — one feature, one worktree, one Claude Code instance:
 
 ```bash
-morph-spec create my-feature --worktree      # birth the feature already isolated
+morph-spec create my-feature --description "what & why" --worktree   # birth the feature already isolated
 # or, for an existing feature:
 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
@@ -240,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.3.0 by Polymorphism Tech*
+*morph-spec v8.5.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -36,21 +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> --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 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.
@@ -70,9 +73,9 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 ## Roteamento por tipo de trabalho
 
-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.
+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> --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

@@ -97,7 +97,7 @@ Não avance de fase sem o gate correspondente ter sido confirmado.
 
 ### 2.1 Roteamento por tipo de trabalho
 
-Nem todo trabalho merece o pipeline completo. Cada feature nasce com um **workType** (`morph-spec create <f> --type <tipo>` ou classificado de `--request "<pedido>"`), e o tipo dimensiona o pipeline:
+Nem todo trabalho merece o pipeline completo. Cada feature nasce com **identidade** (`name` = slug por padrão + `description` obrigatória) e um **workType** (`morph-spec create <f> --description "<o quê/porquê>" --type <tipo>`, ou classificado de `--request "<pedido>"` — que também semeia a descrição), e o tipo dimensiona o pipeline:
 
 | Tipo | Pipeline | Gates |
 |------|----------|-------|
@@ -112,9 +112,11 @@ 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).
 
+**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> --worktree` (ou `morph-spec worktree setup <f>`) cria `.worktrees/{f}/` na branch `morph/{f}`. Contrato:
+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:
 
 - **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.
@@ -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/commands/morph-hotfix.md

@@ -16,7 +16,7 @@ Resolve uma queda ou bug crítico de produção com prioridade máxima em veloci
 
 ## Fluxo
 
-1. **Nascimento:** `morph-spec create {feature-name} --type hotfix` — carimba os gates `proposal`/`plan` por política e cria `0-proposal/`, `2-plan/`, `3-implement/` num passo só.
+1. **Nascimento:** `morph-spec create {feature-name} --type hotfix --description "<incidente>"` — carimba `name`+`description` (obrigatória) e os gates `proposal`/`plan` por política e cria `0-proposal/`, `2-plan/`, `3-implement/` num passo só.
 2. **Scout obrigatório:** despacha `subagent_type: "morph-scout"` (fallback `general-purpose` + persona colada) para localizar root cause e blast radius antes de qualquer fix.
 3. **Hotfix brief:** escreve `0-proposal/proposal.md` curto (sintoma/root cause/blast radius/plano do fix) e `2-plan/tasks.json` mínimo (T1 fix, T2 verify/regressão).
 4. **Fix cirúrgico:** implementa a mudança mínima que resolve o sintoma — sem refatoração, sem hardening fora de escopo.

package/framework/hooks/claude-code/core/state-sync.js

@@ -66,8 +66,9 @@ function registerFeatureIfMissing(state, featureName) {
   if (!state.features) state.features = {};
   if (state.features[featureName]) return false;
 
-  // Canonical object-form gates (incl. optional uiux) — no boolean drift.
-  state.features[featureName] = createDefaultFeature();
+  // Canonical object-form gates (incl. optional uiux) + stamped identity
+  // (name=slug, workType, createdAt) — no anonymous shell, no boolean drift.
+  state.features[featureName] = createDefaultFeature(featureName);
   return true;
 }
 
@@ -114,6 +115,15 @@ function gateFromQuestion(question) {
   return null;
 }
 
+// Gate monotonicity — mirror of src/core/state/gate-order.js (hooks are
+// installed standalone and cannot import from src/). Keep in sync:
+// proposal → plan → review; uiux requires proposal.
+const GATE_PREREQ = { proposal: [], uiux: ['proposal'], plan: ['proposal'], review: ['plan'] };
+function unmetGatePrereqs(gate, gates) {
+  const isApproved = (g) => gates?.[g]?.approved === true || gates?.[g] === true;
+  return (GATE_PREREQ[gate] || []).filter((p) => !isApproved(p));
+}
+
 function handleWriteEdit(input, cwd) {
   const filePath = input.tool_input?.file_path;
   const featureName = extractFeatureName(filePath);
@@ -139,23 +149,38 @@ function handleWriteEdit(input, cwd) {
 
 function handleAskUserQuestion(input, cwd) {
   const answers = input.tool_response?.answers ?? input.tool_response?.responses ?? {};
-  if (typeof answers !== 'object' || answers === null) return false;
+  if (typeof answers !== 'object' || answers === null) return null;
 
   const state = loadState(cwd);
-  if (!state) return false;
+  if (!state) return null;
 
   const featureName = findActiveFeature(state);
-  if (!featureName) return false;
+  if (!featureName) return null;
 
+  const warnings = [];
   for (const [question, answer] of Object.entries(answers)) {
     if (!isApprovalAnswer(answer)) continue;
     const gate = gateFromQuestion(question);
     if (!gate) continue;
 
-    const existing = state.features[featureName].approvalGates?.[gate];
+    const gates = state.features[featureName].approvalGates;
+    const existing = gates?.[gate];
     const alreadyApproved = existing === true || existing?.approved === true;
     if (alreadyApproved) continue;
 
+    // Gate monotonicity: fail-open. The human said "aprovado", so we DO approve
+    // (never block a human in the loop), but if a predecessor gate is still
+    // pending we surface a non-blocking warning — the CLI `morph-spec approve`
+    // hard-refuses the same shape; here we alert so the operator can reconcile.
+    const unmet = unmetGatePrereqs(gate, gates);
+    if (unmet.length) {
+      warnings.push(
+        `⚠️ [morph-spec] GATE FORA DE ORDEM — o Gate "${gate}" de "${featureName}" foi aprovado, ` +
+        `mas o(s) gate(s) anterior(es) ${unmet.join(', ')} não estão aprovados (ordem: ${unmet.join(' → ')} → ${gate}). ` +
+        `Aprove os gates anteriores ou reveja com 'morph-spec doctor'.`
+      );
+    }
+
     // An "aprovado" answer to AskUserQuestion is a human approving in the loop.
     // Route through the shared canonical gate writer so the hook and the CLI
     // (`morph-spec approve`) produce one consistent shape
@@ -163,7 +188,7 @@ function handleAskUserQuestion(input, cwd) {
     // and a manual approval stays distinguishable from a policy auto-approval.
     setGateApproved(featureName, gate, { approvedBy: 'manual' }, cwd);
   }
-  return true;
+  return warnings.length ? warnings.join('\n') : null;
 }
 
 async function main() {
@@ -176,17 +201,24 @@ async function main() {
   const input = readStdin();
   const toolName = input.tool_name;
 
+  let warning = null;
   try {
     if (toolName === 'Write' || toolName === 'Edit') {
       handleWriteEdit(input, cwd);
     } else if (toolName === 'AskUserQuestion') {
-      handleAskUserQuestion(input, cwd);
+      warning = handleAskUserQuestion(input, cwd);
     }
   } catch {
     // fail-open
   }
 
-  exit();
+  // A non-blocking order-violation warning is surfaced as injected context
+  // (hookSpecificOutput.additionalContext); everything else exits silently.
+  if (warning) {
+    exit({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: warning } });
+  } else {
+    exit();
+  }
 }
 
 main().catch(() => exit());

package/framework/hooks/shared/state-writer.js

@@ -91,7 +91,7 @@ export function persistFeature(featureName, feature, projectPath) {
  */
 export function setGateApproved(featureName, gate, meta = {}, projectPath) {
   try {
-    const feature = readFeatureFile(featureName, projectPath) || createDefaultFeature();
+    const feature = readFeatureFile(featureName, projectPath) || createDefaultFeature(featureName);
     const now = new Date().toISOString();
     feature.approvalGates = feature.approvalGates || {};
     feature.approvalGates[gate] = {
@@ -106,11 +106,22 @@ export function setGateApproved(featureName, gate, meta = {}, projectPath) {
   }
 }
 
-/** Default feature shape (canonical object-form gates, incl. optional uiux). */
-export function createDefaultFeature() {
+/**
+ * Default feature shape (canonical object-form gates, incl. optional uiux).
+ * Stamps identity — name (the slug), workType, createdAt — so the implicit
+ * birth path (state-sync registering a feature on the first Write) never
+ * produces an anonymous {status,updatedAt} shell. `description` stays absent
+ * (a hook can't invent it); `list`/`doctor` flag its absence. Mirrors the CLI
+ * createFeature's stamping.
+ *
+ * @param {string} [featureName] - the feature slug, stamped as `name`
+ */
+export function createDefaultFeature(featureName) {
   const now = new Date().toISOString();
   return {
+    ...(featureName ? { name: featureName } : {}),
     status: 'in_progress',
+    workType: 'feature',
     createdAt: now,
     updatedAt: now,
     approvalGates: {

package/framework/schemas/feature.schema.json

@@ -1,14 +1,22 @@
 {
   "$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": {
+    "name": {
+      "type": "string",
+      "description": "Human-readable feature name, stamped at birth by `morph-spec create` (defaults to the slug) and by the state-sync hook's implicit registration. Kept out of the schema's `required` array — adding it there would invalidate every feature.json that predates identity stamping; instead `create` enforces it at birth and `morph-spec doctor`/`list` flag its absence leniently."
+    },
+    "description": {
+      "type": "string",
+      "description": "What/why of the feature. The one identity field a human must supply — `morph-spec create` refuses a new feature without it (--description, or --request which seeds it). Absent on features born via the implicit hook path; surfaced as a warning by `doctor`/`list`, never a hard read-time rejection (see name)."
+    },
     "status": {
       "type": "string",
-      "enum": ["draft", "in_progress", "completed"],
-      "description": "Feature lifecycle status. `completed` is stamped by `morph-spec archive` together with archivedAt."
+      "enum": ["draft", "in_progress", "completed", "abandoned"],
+      "description": "Feature lifecycle status. `completed` is stamped by `morph-spec archive` together with archivedAt. `abandoned` is stamped by `morph-spec delete --archive` together with abandonedAt (dead scaffold / killed draft, kept in .morph/archive)."
     },
     "createdAt": { "type": "string", "format": "date-time" },
     "updatedAt": {
@@ -21,6 +29,11 @@
       "format": "date-time",
       "description": "Stamped by `morph-spec archive`."
     },
+    "abandonedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Stamped by `morph-spec delete --archive` when a dead/abandoned feature is moved to .morph/archive."
+    },
     "approvalGates": {
       "type": "object",
       "description": "One entry per gate. Written ONLY by `morph-spec approve`/`advance` (approvedBy: \"auto\") or the state-sync hook on a human \"aprovado\" answer (approvedBy: \"manual\").",
@@ -187,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" },