@polymorphism-tech/morph-spec 8.2.1 → 8.4.0

package/docs/CHEATSHEET.md

@@ -5,10 +5,12 @@
 ```bash
 npm install -g @polymorphism-tech/morph-spec@latest --prefer-online   # install/upgrade globally
 morph-spec init                                 # initialize project
-morph-spec init --wizard                        # interactive wizard
-morph-spec init --force                         # overwrite existing
-morph-spec update                               # sync framework files
-morph-spec doctor                               # health check
+morph-spec init --force                         # overwrite existing install
+morph-spec init --skip-mcp                      # skip interactive MCP setup
+morph-spec setup-infra                          # headless install, no prompts (used by init internally)
+morph-spec setup-infra --reinstall              # re-install only stack-aware assets (rules/skills/agents)
+morph-spec update                               # sync framework templates/standards to the installed version
+morph-spec doctor                               # health check (agents/rules drift, hook config, etc.)
 morph-spec --version
 ```
 
@@ -21,96 +23,78 @@ morph-spec --version
 ## Phase workflow
 
 ```
-proposal → [uiux] → design → plan → tasks → implement → [sync]
+proposal → [uiux] → plan → implement → review
 ```
 
-Phases in brackets are optional.
+`uiux` is optional. Which of the 5 phases actually run for a given feature is also shaped by its **work type** (see below) — a `chore` skips straight to implement, a `hotfix` runs a different pipeline entirely.
 
-| Phase | Directory | Output files | Gate |
-|-------|-----------|--------------|------|
-| proposal | `0-proposal/` | `proposal.md` | ✅ Approval |
-| uiux *(optional)* | `1-design/` | `design-system.md`, `mockups.md`, `components.md`, `flows.md` | ✅ Approval |
-| design | `2-design/` | `spec.md`, `contracts.cs`, `decisions.md` | ✅ Approval |
-| plan | `3-plan/` | `plan.md` | ✅ Approval |
-| tasks | `4-tasks/` | `tasks.md` | ✅ Approval |
-| implement | `3-implement/` | code + `recap.md` | — |
-| sync *(optional)* | — | standards updated | — |
+| Phase | Folder | Gate |
+|-------|--------|------|
+| proposal | `0-proposal/` | ✅ Gate 1 |
+| uiux *(optional)* | `1-design/` | ✅ |
+| plan | `2-plan/` | ✅ Gate 2 |
+| implement | `3-implement/` | — (auto-advance between tasks) |
+| review | `4-review/` | ✅ Gate 3 |
 
 ---
 
 ## Slash commands (Claude Code)
 
-| Command | Description |
-|---------|-------------|
-| `/morph-proposal {feature}` | Full spec pipeline — phases 0–4 with approval gates |
-| `/morph-apply {feature}` | Implement approved feature — phase 5 |
-| `/morph-hotfix {feature}` | Surgical hotfix ADW — scout → fix → human Gate 3 → ship |
-| `/morph-status` | Project-wide feature status dashboard |
-| `/morph-preflight` | Pre-implementation validation (7 checks) |
+| Command | Purpose |
+|---------|---------|
+| `/morph-proposal {feature}` | Business understanding + plan (Gates 1 and 2). Step 0 routes by work type (`feature`/`bug`/`chore`/`hotfix`) |
+| `/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-preflight` | Pre-deploy validation (specs, contracts, tests, infra) |
+| `/morph-troubleshoot [error]` | Root-cause diagnosis for .NET/Next.js errors |
 
 ---
 
-## CLI — project management
+## CLI — approvals & phase advance
 
 ```bash
-morph-spec init [--force] [--skip-mcp]
-morph-spec update [--templates] [--standards]
-morph-spec doctor
+morph-spec approve {feature} {gate} [--mode auto] [--approver name] [--notes text]
+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]
 ```
 
 ---
 
-## CLI — feature workflow
+## CLI — feature birth & work-type routing
 
-```bash
-morph-spec state list                          # all features
-morph-spec state get {feature} [--json]        # feature detail
-morph-spec state set {feature} {key} {value}   # update property
-morph-spec phase advance {feature}             # advance to next phase
-morph-spec status {feature} [--json] [--verbose]
-morph-spec task done {feature} {task-id}        # mark task complete
-morph-spec task start {feature} {task-id}      # start a task (dispatch gate)
-```
-
----
+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`).
 
-## CLI — validation
+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 validate                            # all validators
-morph-spec validate architecture
-morph-spec validate packages
-morph-spec validate contrast [--wcag-aaa]
-morph-spec validate-feature {feature} [--phase {phase}] [--json]
-morph-spec verify {feature} [task] [--json]    # deterministic build+tests+validators chain, before the LLM judge
+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)
 ```
 
 ---
 
-## CLI — 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`).
+## CLI — state (server-side, timestamped)
 
 ```bash
-morph-spec create {feature} --type feature|bug|chore|hotfix
-morph-spec create {feature} --request "<free text>"     # deterministic detector classifies the type
-morph-spec retype {feature} {newType}                    # change type mid-flight (blocked after Gate 3)
+morph-spec score {feature} {task} {score} [--dims "9.5,9,9,9"]   # writes taskScores
+morph-spec gate-decision {feature} {gate} --pause <bool> [--reason] [--signals json]   # writes gateDecisions
 ```
 
----
+Never hand-edit `taskScores`/`gateDecisions`/`approvalGates` in `feature.json` — always go through these commands (they collide with the `state-sync` hook otherwise).
 
-## 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, allocated ports and handoff pointer into context. Each worktree gets a deterministic port block (`.morph/worktree.env`) and a regenerable handoff document.
+## CLI — validation
 
 ```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 + 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
+morph-spec validate [architecture|packages|contrast] [--wcag-aaa]
+morph-spec validate-feature {feature} [--phase {phase}] [--json]   # alias: vf
+morph-spec verify {feature} [task] [--json] [--skip-tests] [--skip-build]   # deterministic build+test+validator chain, before the LLM judge
 ```
 
 ---
@@ -124,59 +108,30 @@ morph-spec dag {feature} --mermaid         # emit the tasks.json DAG as a Mermai
 
 ---
 
-## CLI — utilities
-
-```bash
-morph-spec generate recap {feature}           # auto-generate recap.md
-morph-spec template render {id} {output} {vars-json}
-morph-spec trust status [feature]
-morph-spec trust set {feature} {level} [reason]    # level: manual|high|auto
-morph-spec mcp setup [name] [--list] [--auto]
-```
-
----
-
-## State — mark-output
-
-```bash
-morph-spec state mark-output {feature} proposal
-morph-spec state mark-output {feature} spec
-morph-spec state mark-output {feature} contracts
-morph-spec state mark-output {feature} decisions
-morph-spec state mark-output {feature} tasks
-morph-spec state mark-output {feature} recap
-
-# UI outputs (camelCase or kebab-case both work)
-morph-spec state mark-output {feature} uiDesignSystem
-morph-spec state mark-output {feature} uiMockups
-morph-spec state mark-output {feature} uiComponents
-morph-spec state mark-output {feature} uiFlows
-```
-
----
-
-## State — agents
-
-```bash
-morph-spec state add-agent {feature} {agent-id}
-morph-spec state remove-agent {feature} {agent-id}
-```
-
----
+## CLI — worktrees (parallel development / fleet)
 
-## Checkpoints
+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 checkpoint-save {feature}
+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
+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
 ```
 
 ---
 
-## Approvals
+## CLI — scaffolding & misc
 
 ```bash
-morph-spec approve {feature} {gate}            # approve a gate
-morph-spec approval-status {feature}           # show gate status
+morph-spec scaffold dotnet {feature} {slice-name} [--dry-run]   # generate a VSA feature slice
+morph-spec scaffold nextjs {feature} [--dry-run]                # generate a feature page + components
+morph-spec context refresh                                       # rescan project, regenerate .morph/context/README.md
+morph-spec mcp setup [name] [--list] [--auto]
+morph-spec dashboard [--port 3200]                                # open the inspector dashboard
 ```
 
 ---
@@ -185,47 +140,35 @@ morph-spec approval-status {feature}           # show gate status
 
 ```
 .morph/
-├── config/
-│   └── config.json               # project config (editable)
+├── config/config.json           # project config (editable)
 ├── framework/                    # READ-ONLY
-│   ├── agents.json               # 22 agents, 4 tiers
-│   ├── standards/                # 82 standards across 11 categories
-│   └── templates/                # code and IaC templates
-├── context/                      # project context (editable)
-│   ├── README.md
-│   └── standards.md
-├── features/
-│   └── {feature}/
-│       ├── 0-proposal/proposal.md
-│       ├── 1-design/design-system.md, mockups.md, components.md, flows.md
-│       ├── 2-design/spec.md, contracts.cs, decisions.md
-│       ├── 3-tasks/tasks.md
-│       └── 4-implement/recap.md
-├── checkpoints/
-├── logs/
-└── state.json                    # READ-ONLY — CLI managed
+│   ├── agents.json                # 8 domain personas
+│   ├── standards/                 # standards registry
+│   └── templates/                 # code, IaC, and context templates
+├── context/                       # project context (editable)
+├── features/{feature}/
+│   ├── feature.json                # authoritative, committed
+│   ├── handoff.md
+│   └── 0-proposal/ 1-design/ 2-plan/ 3-implement/ 4-review/
+└── state.json                      # gitignored, derived index — never hand-edited
 
 .claude/
-├── commands/                     # slash commands
+├── commands/                    # slash commands
 ├── skills/                       # framework skills (SKILL.md per dir)
-├── agents/                       # native subagents (22)
-│   ├── morph-{id}.md             # tier 1-2 agents
-│   └── morph-domain-{name}.md   # tier 3 domain agents
-├── rules/                        # path-scoped rules (6 files)
-└── settings.local.json           # hooks (10)
+├── agents/morph-{id}.md           # generated subagents (one per persona, no tiers)
+└── settings.local.json            # hooks + permissions.deny
 ```
 
 ---
 
 ## Protected files
 
-These files are never edited directly. Use CLI commands or `morph-spec update` instead:
+Never edited directly — go through CLI commands or `morph-spec update` instead:
 
 | Path | Protected by |
 |------|-------------|
-| `.morph/state.json` | `permissions.deny` |
-| `.morph/framework/**` | `permissions.deny` |
-| Approved spec/contracts | `protect-spec-files.js` hook |
+| `.morph/state.json`, `.morph/framework/**` | `permissions.deny` |
+| `tasks.json` plan contract (`title`/`description`/`dependencies`/`effort`/`doneCriteria`/`group`) after Gate 2 | `protect-spec-files` hook (semantic diff) |
 
 ---
 
@@ -239,4 +182,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v8.2.1 by Polymorphism Tech*
+*morph-spec v8.4.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -19,11 +19,11 @@ morph-spec init
 ```
 
 `init` does the following:
-- Auto-detects your stack (Blazor, Next.js, Node.js, monorepo)
+- Auto-detects your stack (.NET, Next.js, Node.js, monorepo)
 - Creates `.morph/` with framework files, standards, and templates
 - Creates `.morph/context/` with inferred project context
 - Installs `.claude/skills/`, `.claude/agents/`, `.claude/rules/`
-- Writes `.claude/settings.local.json` with 10 Claude Code hooks
+- Writes `.claude/settings.local.json` with the fail-open Claude Code hooks (see `docs/ARCHITECTURE.md`)
 - Copies `CLAUDE.md` with runtime instructions
 
 Verify the installation:
@@ -44,42 +44,31 @@ Open your project in Claude Code and run:
 
 Replace `my-feature` with a short kebab-case name for your feature (e.g., `user-notifications`, `payment-flow`).
 
-The proposal pipeline runs phases 0–6 with three approval gates:
+The proposal pipeline runs the `proposal` and `plan` phases (plus the optional `uiux` phase), with an approval gate at each:
 
-### Phase 0 — Proposal
+### Proposal (Gate 1)
 
-Claude analyzes your request, detects which agents are relevant, and produces `0-proposal/proposal.md`. You review it and approve (or request changes).
+Claude analyzes your request, detects the relevant stack and standards, and produces `0-proposal/proposal.md`. You review it and approve (or request changes).
 
-### Phase 1 — Setup
+### UI/UX — optional (Gate)
 
-Loads project context from `.morph/context/`, confirms stack and active agents. No approval needed.
+Only runs for UI-heavy features. Claude generates, under `1-design/`:
+- `design-system.md` — colors, typography, spacing
+- `mockups.md` — ASCII wireframes
+- `components.md` — component specs
+- `flows.md` — user flows and edge cases
 
-### Phase 2 — UI/UX (conditional)
+You approve the UI design before moving on.
 
-Only runs if frontend agents are active. Claude generates:
-- `1-design/design-system.md` — colors, typography, spacing
-- `1-design/mockups.md` — ASCII wireframes
-- `1-design/components.md` — component specs
-- `1-design/flows.md` — user flows and edge cases
+### Plan (Gate 2)
 
-You approve the UI design before design phase begins.
+Claude produces, under `2-plan/`:
+- `spec.md` — full requirements, use cases, validations
+- `mandate.md` — the implementation contract (stack defaults, forbidden patterns)
+- `tasks.json` — ordered task breakdown (`T001`, `T002`, …)
+- `decisions.md` — architectural decision records (optional)
 
-### Phase 3 — Design
-
-Claude produces the technical specification:
-- `2-design/spec.md` — full requirements, use cases, validations
-- `2-design/contracts.cs` — C# interfaces, DTOs, enums
-- `2-design/decisions.md` — architectural decision records (ADRs)
-
-You review and approve the design.
-
-### Phase 4 — Clarify
-
-Claude identifies 3–7 ambiguities in the spec, asks you to resolve them, then updates the spec. No gate.
-
-### Phase 6 — Tasks
-
-Claude breaks the spec into atomic tasks (`T001`, `T002`, …) saved to `3-tasks/tasks.md`. You approve the task list.
+Claude identifies ambiguities in the spec and resolves them with you before finalizing. You review and approve the spec + mandate + task list together.
 
 At this point, planning is complete:
 
@@ -95,11 +84,11 @@ At this point, planning is complete:
 /morph-apply my-feature
 ```
 
-Claude reads `spec.md`, `contracts.cs`, and `tasks.md`, then implements task by task:
-- Starts each task, writes the code, marks it done
-- Runs 5 validators automatically after each task: security, architecture, packages, design system, Blazor concurrency
-- Auto-checkpoints every 3 tasks (validates, saves state)
-- Generates `4-implement/recap.md` on completion
+Claude reads `spec.md`, `mandate.md`, and `tasks.json`, then implements task by task with auto-advance (no pause between tasks unless there's a blocking ambiguity):
+- Tracks task progress with the native `TaskCreate`/`TaskUpdate` tools, persisted to `tasks.json`
+- Runs the validators relevant to your stack after each task (e.g. `architecture`/`packages`/`contract-compliance` for .NET, `nextjs-component`/`css`/`design-system` for Next.js) via `morph-spec verify`
+- Applies `morph-eval` after each task — a score below 9 triggers an autonomous correction loop, not a pause
+- Generates `3-implement/recap.md` on completion, then Gate 3 review (`4-review/`)
 
 ---
 
@@ -108,21 +97,16 @@ Claude reads `spec.md`, `contracts.cs`, and `tasks.md`, then implements task by
 Check feature state:
 
 ```bash
-morph-spec state get my-feature
 morph-spec status my-feature
 ```
 
-Advance to the next phase manually (when needed):
+Approve the current gate and scaffold the next phase folder in one step:
 
 ```bash
-morph-spec phase advance my-feature
+morph-spec advance my-feature
 ```
 
-Mark a task complete:
-
-```bash
-morph-spec task done my-feature T001
-```
+Task progress is tracked with the native `TaskCreate`/`TaskUpdate` tools and persisted to `tasks.json` — there is no separate CLI command for marking a task done.
 
 Run validators at any time:
 
@@ -145,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"
@@ -173,7 +163,7 @@ 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
 ```
@@ -195,23 +185,23 @@ morph-spec worktree list
 
 ## Multiple features
 
-You can have multiple features in progress simultaneously. Each has its own directory under `.morph/features/`:
+You can have multiple features in progress simultaneously. Each has its own directory under `.morph/features/`, with its own committed `feature.json`:
 
 ```
 .morph/features/
 ├── user-notifications/
+│   ├── feature.json
 │   ├── 0-proposal/
-│   ├── 2-design/
-│   └── 3-tasks/
+│   └── 2-plan/
 └── payment-flow/
-    ├── 0-proposal/
-    └── 2-design/
+    ├── feature.json
+    └── 0-proposal/
 ```
 
-See all feature states:
+See every active feature — root and worktrees — with phase, gates, and activity:
 
 ```bash
-morph-spec state list
+morph-spec fleet
 ```
 
 ---
@@ -256,4 +246,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.2.1 by Polymorphism Tech*
+*morph-spec v8.4.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -47,12 +47,15 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - `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.
+- `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 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.
 
 ## Skills core (em `.claude/skills/`)
 
@@ -69,9 +72,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 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

@@ -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 |
 |------|----------|-------|
@@ -114,7 +114,7 @@ Nem todo trabalho merece o pipeline completo. Cada feature nasce com um **workTy
 
 ### 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.

package/framework/agents.json

@@ -64,6 +64,7 @@
         "ai-agents-prompts-in-db",
         "ai-agents-rag-custom-pgvector",
         "ai-agents-middleware-patterns",
+        "ai-agents-observability-patterns",
         "ai-agents-multi-agent-patterns"
       ],
       "mcp": ["context7"],
@@ -125,7 +126,8 @@
       "standards": [
         "backend-integrations-hangfire-hangfire-jobs",
         "infrastructure-docker-coolify-deploy",
-        "backend-dotnet-scrutor"
+        "backend-dotnet-scrutor",
+        "ai-agents-observability-patterns"
       ],
       "mcp": ["context7"],
       "model": "sonnet",

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/README.md

@@ -51,7 +51,9 @@ framework/hooks/
 | **PostToolUse** (Write\|Edit) | trace-autogen.js | State sync | Auto-generates `.morph/traces/YYYY-MM-DD-{feature}-implement.json` from tasks.json + recap.md + taskScores on every tasks.json write — the skills never write traces by hand |
 | **PostToolUse** (Write\|Edit\|AskUserQuestion) | state-sync.js | State sync | Autonomous state updates (feature register, output tracking, gate approval) |
 | **PostToolUse** (Write\|Edit\|AskUserQuestion) | gate-guard.js | Advisory | Warns (never blocks) when a gate action disagrees with the persisted gateDecisions; logs one `coherent`/`divergent` line per check in `.morph/logs/activity.json` (issue #63) |
+| **PostToolUse** (all tools) | telemetry-log.js | Telemetry | Appends every tool call (skill, sub-agent dispatch + prompt, knowledge-base read, bash/edit) to `.morph/logs/events.jsonl`; silent, fail-open — the NLH execution-path capture read back by `morph-spec telemetry` |
 | **PostToolUse** (all tools) | loop-detect.js | Advisory | Warns when the last 8 actions collapse to ≤2 unique signatures |
+| **UserPromptSubmit** | telemetry-log.js | Telemetry | Appends the user's prompt to the same `events.jsonl` stream; silent, fail-open |
 | **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/recap drift; build check; session snapshot |
 
 ## Design Principles
@@ -112,6 +114,7 @@ All Claude Code hooks import from `framework/hooks/shared/`:
 | `phase-utils.js` | Phase constants, path extraction, file classification |
 | `hook-response.js` | `block(reason)`, `approve(context)`, `injectContext(text)`, `pass()` |
 | `stdin-reader.js` | `readStdin()` — Promise-based stdin JSON reader |
+| `telemetry-logger.js` | `appendTelemetryEvent()`, `readTelemetryEvents()` — append-only JSONL event stream (`.morph/logs/events.jsonl`) |
 
 `injectContext(text)` is how `worktree-context.js` (and any other SessionStart hook) delivers context: it emits `{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": text } }` on stdout. Claude Code only honors additional context nested under `hookSpecificOutput` — a bare top-level field is ignored.