@polymorphism-tech/morph-spec 10.0.0 → 10.2.0

package/CLAUDE.md

@@ -8,6 +8,8 @@ morph-spec is a spec-driven development harness CLI (`@polymorphism-tech/morph-s
 
 This repo is the **framework source code** — not a project that uses morph-spec.
 
+**Do not run the morph-spec workflow here.** No `init`, `create`, `plan-check`, `gate-check`, `approve`, `advance`, `verify`, `context refresh` or `finish`, and no `/morph-plan` or `/morph-apply` as a process, even if a prompt starts with one: confirm first. Work here is ordinary: a normal branch, `npm test`, `npm run generate:check`, a PR. `framework/skills/` and `framework/CLAUDE.md` are source to edit, not instructions to follow. `/.morph/` is gitignored: this repo keeps no morph-spec state.
+
 ## Build & Test Commands
 
 ```bash

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:** 10.0.0  
+**Version:** 10.2.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -115,7 +115,7 @@ In `trust: "auto"` mode (default), gates auto-pass without risk signals. See `fr
 Check gate status:
 
 ```bash
-morph-spec approval-status {feature}
+morph-spec status {feature}
 ```
 
 ---
@@ -165,7 +165,6 @@ morph-spec fleet                              # Every active feature (root + wor
 morph-spec status {feature}                    # Feature status dashboard
 morph-spec approve {feature} {gate}            # Approve a phase gate (plan, uiux, 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 finish {feature} --pr|--merge       # Close a feature: archive + integrate (PR or local merge) + teardown
 morph-spec archive {feature}                   # Archive WITHOUT integrating (legacy feature / cleanup)
 ```
@@ -177,9 +176,6 @@ Progress within a feature is the slice reports `3-implement/reports/F{n}.md`: ab
 ### Validation
 
 ```bash
-morph-spec validate                    # Run all validators
-morph-spec validate {validator}        # Run specific validator
-morph-spec validate-feature {feature}  # Content-aware feature validation
 morph-spec verify {feature}            # Deterministic build+tests+validators chain, before the LLM judge
 ```
 
@@ -380,4 +376,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v10.0.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v10.2.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -35,7 +35,6 @@ const stackSetCommand = lazy('../src/commands/project/stack-set.js', 'stackSetCo
 const testsAuditCommand = lazy('../src/commands/validation/tests-audit.js', 'testsAuditCommand');
 
 const approveCommand = lazy('../src/commands/state/approve.js', 'approveCommand');
-const approvalStatusCommand = lazy('../src/commands/state/approve.js', 'approvalStatusCommand');
 const unapproveCommand = lazy('../src/commands/state/approve.js', 'unapproveCommand');
 const advanceCommand = lazy('../src/commands/state/advance.js', 'advanceCommand');
 const archiveCommand = lazy('../src/commands/state/archive.js', 'archiveCommand');
@@ -55,8 +54,6 @@ const graphAffectedCommand = lazy('../src/commands/graph/affected.js', 'graphAff
 const graphExplainCommand = lazy('../src/commands/graph/explain.js', 'graphExplainCommand');
 const graphDiffCommand = lazy('../src/commands/graph/diff.js', 'graphDiffCommand');
 
-const validateCommand = lazy('./validate.js', 'validateCommand');
-const validateFeatureCommand = lazy('../src/commands/validation/validate-feature.js', 'validateFeatureCommand');
 const verifyCommand = lazy('../src/commands/validation/verify.js', 'verifyCommand');
 const e2eUpCommand = lazy('../src/commands/e2e/e2e.js', 'e2eUpCommand');
 const e2eStatusCommand = lazy('../src/commands/e2e/e2e.js', 'e2eStatusCommand');
@@ -72,7 +69,6 @@ const contextRefreshCommand = lazy('../src/commands/context/context-refresh.js',
 
 const dashboardCommand = lazy('../src/commands/dashboard/dashboard.js', 'dashboardCommand');
 
-const telemetryCommand = lazy('../src/commands/observability/telemetry.js', 'telemetryCommand');
 const costCommand = lazy('../src/commands/observability/cost.js', 'costCommand');
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -216,12 +212,6 @@ program
   .option('--json', 'Output as JSON')
   .action((feature, options) => deleteCommand(feature, options));
 
-program
-  .command('approval-status <feature>')
-  .description('Show approval status for all gates')
-  .option('--json', 'Output as JSON')
-  .action((feature, options) => approvalStatusCommand(feature, options));
-
 program
   .command('unapprove <feature> <gate>')
   .description('Revoke a phase gate approval (recovery only)')
@@ -324,29 +314,6 @@ graphCommand
   .option('--json', 'Output as JSON')
   .action((options) => graphDiffCommand(options));
 
-program
-  .command('validate [validator]')
-  .description('Run project validations (all | packages | next-components | spec-tasks)')
-  .option('-v, --verbose', 'Show detailed output')
-  .option('--auto-fix, --fix', 'Auto-fix issues where possible')
-  .option('--no-fail', 'Don\'t exit with error code')
-  .action((validator, options) => {
-    const args = validator ? [validator] : ['all'];
-    if (options.verbose) args.push('--verbose');
-    if (options.autoFix) args.push('--auto-fix');
-    if (options.noFail) args.push('--no-fail');
-    validateCommand(args);
-  });
-
-program
-  .command('validate-feature <feature>')
-  .alias('vf')
-  .description('Content-aware validation of feature outputs (sections, schema, contracts)')
-  .option('--phase <phase>', 'Validate outputs for a specific phase')
-  .option('--json', 'Output as JSON')
-  .option('-v, --verbose', 'Show detailed output')
-  .action(validateFeatureCommand);
-
 program
   .command('verify <feature>')
   .description('Run the deterministic verification chain (build + tests + validators + e2e) — code before the LLM judge')
@@ -361,6 +328,7 @@ program
   .option('--skip-build', 'Skip the build node. The run is partial, so the verification stamp is NOT written (reason "skip-build")')
   .option('--skip-e2e', 'Skip the e2e node (Docker bring-up + Playwright)')
   .option('--fresh-e2e', 'Recreate the e2e stack from scratch: down -v (named volumes included), drop the freshness stamp, rebuild, re-seed auth')
+  .option('--fresh', 'Run every node again, ignoring the green nodes of an earlier run on this same tree. Use it when something outside the tree changed (.env, database, tool version)')
   .option('--no-persist', 'Do not persist the result to feature.json')
   .option('--ci', 'Push morph/<feature> and take the proof from the project CI (creates .github/workflows/morph-verify.yml when no workflow runs verify). Same stamp, source "ci". No GitHub/gh/workflow = local verify with the reason; uncommitted code = exit 2; CI still running after 50 min = exit 3, no stamp')
   .action((feature, options) =>
@@ -593,14 +561,6 @@ program
   .option('--no-open', 'Don\'t auto-open browser')
   .action(dashboardCommand);
 
-program
-  .command('telemetry')
-  .description('Summarize the harness execution path from .morph/logs/events.jsonl (skills, personas, standards read, tool mix, prompts)')
-  .option('--json', 'Output the aggregate as JSON')
-  .option('--feature <name>', 'Narrow the summary to a single feature')
-  .option('--limit <n>', 'How many recent prompts to show (default 10)', (v) => parseInt(v, 10))
-  .action((options) => telemetryCommand(options));
-
 program
   .command('cost [feature]')
   .description('Cost-facing view over .morph/logs/events.jsonl: bytes re-ingested by kind (proxy, not tokens), dispatch counts, real tokens when observed')

package/claude-plugin.json

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

package/docs/CHEATSHEET.md

@@ -23,18 +23,17 @@ morph-spec --version
 ## Phase workflow
 
 ```
-proposal → [uiux] → plan → implement → review
+plan → [uiux] → implement → review
 ```
 
-`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.
+`uiux` is optional and runs after the plan gate. Which phases actually run for a given feature is also shaped by its **work type** (see below): a `chore` writes a short plan and goes straight to implement, a `hotfix` follows its own path.
 
 | 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 |
+| plan | `2-plan/` | ✅ `plan` (`plan.md` + `checks.json`) |
+| uiux *(optional)* | `1-design/` | ✅ `uiux` |
+| implement | `3-implement/` | — (one row per `Cn` in `report.md`) |
+| review | `4-review/` | ✅ `review` (Gate 3) |
 
 ---
 
@@ -42,9 +41,9 @@ proposal → [uiux] → plan → implement → review
 
 | 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-plan {feature or issue link}` | From a request to the approved plan: routes by work type (`feature`/`bug`/`chore`/`hotfix`), opens with a thesis against the code |
+| `/morph-hotfix {feature}` | Production incident: surgical fix, Gate 3 always human |
+| `/morph-apply {feature}` | Implements the whole plan, runs `verify` and Gate 3, closes with `finish` |
 | `/morph-status [feature]` | Status of the active (or specified) feature |
 | `/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) |
@@ -57,7 +56,6 @@ proposal → [uiux] → plan → implement → review
 ```bash
 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 finish {feature} --pr|--merge [--push] [--keep] [--force] [--discard-ignored]   # normal close: archive + integrate + teardown
 morph-spec archive {feature} [--force] [--no-git]        # archive WITHOUT integrating (legacy feature / cleanup)
@@ -69,14 +67,15 @@ morph-spec archive {feature} [--force] [--no-git]        # archive WITHOUT integ
 
 ## 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 born with a **work type** that dimensions its pipeline: `feature` (full plan → [uiux] → implement → review), `bug` (same flow, lean plan), `chore` (short plan, straight to implement), `hotfix` (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.
+Every feature is also born with an **identity**: a description is required (`create` refuses a nameless scaffold without it), `name` defaults to the slug. `--request` is kept literally in `feature.json → description`, and the plan critique checks the plan against it.
 
 ```bash
+morph-spec create {feature} --request '<free text>'                  # detector classifies the type AND seeds the description
+morph-spec create {feature} --type <t> --request '<title> <url>'     # issue link: the type is picked, the body stays out of the argument
 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)
+morph-spec retype {feature} {newType}                                # change type mid-flight (blocked after Gate 3)
 ```
 
 ---
@@ -84,7 +83,9 @@ morph-spec retype {feature} {newType}                     # change type mid-flig
 ## CLI — state (server-side, timestamped)
 
 ```bash
-morph-spec gate-decision {feature} {gate} --pause <bool> [--reason] [--signals json]   # writes gateDecisions
+morph-spec next {feature} [--json]                                                     # the next step, decided from disk
+morph-spec gate-check {feature} {gate} [--json]                                        # decide + record whether the gate pauses
+morph-spec gate-decision {feature} {gate} --pause <bool> [--reason] [--signals json]   # writes gateDecisions by hand
 ```
 
 Never hand-edit `gateDecisions`/`approvalGates` in `feature.json` — always go through these commands (they collide with the `state-sync` hook otherwise).
@@ -94,25 +95,16 @@ Never hand-edit `gateDecisions`/`approvalGates` in `feature.json` — always go
 ## CLI — validation
 
 ```bash
-morph-spec validate [packages|next-components|spec-tasks]
-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
-```
-
----
-
-## CLI — DAG
-
-```bash
-morph-spec dag {feature} [--json]          # sequential vs parallel dispatch decision (effort-weighted)
-morph-spec dag {feature} --mermaid         # emit the tasks.json DAG as a Mermaid flowchart
+morph-spec plan-check {feature} [--json]                           # validate plan.md, write checks.json
+morph-spec verify {feature} [--json] [--filter <ids>] [--skip-tests] [--skip-build] [--skip-e2e]   # deterministic build+test+validator+e2e chain; the gate reads the unfiltered run
+morph-spec report-check {feature} [--before-eval] [--json]         # state of the implement and of the Gate 3 reports
 ```
 
 ---
 
 ## CLI — worktrees (parallel development / fleet)
 
-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.
+One feature = one git worktree = one Claude Code instance. Each worktree gets its own deterministic port block (`.morph/worktree.env`).
 
 ```bash
 morph-spec create {feature} --description "<what/why>" --worktree   # birth the feature already isolated in its own worktree
@@ -120,9 +112,8 @@ morph-spec worktree setup {feature}        # create worktrees/{feature}/ on bran
 morph-spec worktree link [--all]           # relink shared infra (node_modules[, .claude, .morph/framework])
 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] [--here]   # regenerate the handoff doc — resolves the owning tree and writes THERE, safe to run from the root
 morph-spec doctor --worktrees [--prune]    # reconcile git's registry × disk × features; --prune also clears a dangling root worktree.path pointer
-morph-spec fleet [--json]                  # every active feature (root + worktrees) with phase/gates/ports/handoff/activity
+morph-spec fleet [--json]                  # every active feature (root + worktrees) with phase/gates/ports/activity
 ```
 
 ---
@@ -145,14 +136,13 @@ morph-spec dashboard [--port 3200]                                # open the ins
 .morph/
 ├── config/config.json           # project config (editable)
 ├── framework/                    # READ-ONLY
-│   ├── agents.json                # 8 domain personas
+│   ├── agents.json                # the 3 Gate 3 personas
 │   ├── standards/                 # standards registry
-│   └── templates/                 # code, IaC, and context templates
+│   └── CLI.md                     # every command in detail
 ├── context/                       # project context (editable)
 ├── features/{feature}/
 │   ├── feature.json                # authoritative, committed
-│   ├── handoff.md
-│   └── 0-proposal/ 1-design/ 2-plan/ 3-implement/ 4-review/
+│   └── 1-design/ 2-plan/ 3-implement/ 4-review/
 └── state.json                      # gitignored, derived index — never hand-edited
 
 .claude/
@@ -171,18 +161,17 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 | Path | Protected by |
 |------|-------------|
 | `.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) |
+| `2-plan/checks.json`, and the body of `2-plan/plan.md` after the plan gate (only `## Errata` is appended) | `protect-spec-files` hook |
 
 ---
 
 ## Links
 
 - [QUICKSTART.md](QUICKSTART.md) — step-by-step guide
-- [ARCHITECTURE.md](ARCHITECTURE.md) — system design
 - [CHANGELOG.md](../CHANGELOG.md) — release history
 - [npm](https://www.npmjs.com/package/@polymorphism-tech/morph-spec)
 - support@polymorphism.com.br
 
 ---
 
-*morph-spec v10.0.0 by Polymorphism Tech*
+*morph-spec v10.2.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -1,82 +1,47 @@
 # morph-spec Quick Start
 
+One page: install, run `doctor`, paste the issue, open the PR.
+
 ## Install
 
 ```bash
 npm install -g @polymorphism-tech/morph-spec@latest --prefer-online
 ```
 
-> The installer automatically configures your PowerShell PATH on Windows. If `morph-spec` is not found, open a new terminal window.
-
----
+If `morph-spec` is not found on Windows, open a new terminal window.
 
-## Initialize a project
+## Set up the project
 
-Navigate to your project root and run:
+From the project root:
 
 ```bash
 morph-spec init
-```
-
-`init` does the following:
-- 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 the fail-open Claude Code hooks (see `docs/ARCHITECTURE.md`)
-- Copies `CLAUDE.md` with runtime instructions
-
-Verify the installation:
-
-```bash
 morph-spec doctor
 ```
 
----
+`init` installs the harness into `.morph/` and `.claude/`. `doctor` is your first debugging step: it reports version mismatches, missing files and hook problems.
 
-## Your first feature
+## Paste the issue
 
-Open your project in Claude Code and run:
+Open the project in Claude Code and paste the link:
 
 ```
-/morph-proposal my-feature
+/morph-plan https://github.com/your-org/your-repo/issues/123
 ```
 
-Replace `my-feature` with a short kebab-case name for your feature (e.g., `user-notifications`, `payment-flow`).
-
-The proposal pipeline runs the `proposal` and `plan` phases (plus the optional `uiux` phase), with an approval gate at each:
-
-### Proposal (Gate 1)
+A free-text request works too: `/morph-plan user-notifications`, then describe what you want.
 
-Claude analyzes your request, detects the relevant stack and standards, and produces `0-proposal/proposal.md`. You review it and approve (or request changes).
+Claude reads the issue, checks it against the code and opens with a thesis: "asks for X; the code shows Y; I propose Z". There is no process question. How much it asks depends on what is at stake:
 
-### UI/UX — optional (Gate)
+| The request is | What happens |
+|---|---|
+| clear and matches the code | a one-line thesis, then it moves on |
+| missing something, or contradicts the code | up to 3 challenges, each with evidence |
+| unclear about the outcome, or high risk | a full interview with you |
 
-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
+The result is `2-plan/plan.md`: the problem, the outcome sought, what is out of scope, and the scenarios `C1..Cn` that define done. Read `## Padrões assumidos` at the end: to veto a default, tell Claude its number before implementing.
 
-You approve the UI design before moving on.
-
-### Plan (Gate 2)
-
-Claude produces, under `2-plan/`:
-- `usecases/UC-*.md` — the behavior, with postconditions observable in a test
-- `spec.md` — architecture, contracts and the `## Contrato de implementação` section (standards, runtime verification)
-- `tasks.json` — ordered task breakdown (`T001`, `T002`, …)
-- `decisions.md` — architectural decision records (optional)
-
-Claude identifies ambiguities in the spec and resolves them with you before finalizing. You review and approve the use cases, spec and task list together.
-
-At this point, planning is complete:
-
-```
-✅ Planning complete — run /morph-apply my-feature to implement
-```
-
----
+You approve the gates yourself. If you have a question about the issue, ask the person who wrote it.
 
 ## Implement
 
@@ -84,169 +49,44 @@ At this point, planning is complete:
 /morph-apply my-feature
 ```
 
-Claude reads the use cases, `spec.md` and `tasks.json`, then implements task by task with auto-advance (no pause between tasks unless there's a blocking ambiguity):
-- Records task progress in `tasks.json`, writing the mutable `status`/`outputs`/`notes` fields
-- 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`
-- Closes each task when `verify` is green and every `doneCriteria` has the evidence that proves it — red triggers an autonomous correction loop, not a pause
-- Generates `3-implement/recap.md` on completion, then Gate 3 review (`4-review/`)
-
----
-
-## During development
-
-Check feature state:
-
-```bash
-morph-spec status my-feature
-```
-
-Approve the current gate and scaffold the next phase folder in one step:
-
-```bash
-morph-spec advance my-feature
-```
-
-Task progress is recorded in `tasks.json` — Claude writes the mutable `status`/`outputs`/`notes` fields directly, and there is no separate CLI command for marking a task done.
-
-Run validators at any time:
+Claude implements the whole plan in one session, tracks each scenario in `3-implement/report.md`, runs `verify`, and dispatches the Gate 3 reviewers in fresh context. If a discovery makes the outcome sought false, it stops and asks you.
 
-```bash
-morph-spec validate                    # all validators
-morph-spec validate architecture       # specific validator
-morph-spec validate packages
-```
+## Open the PR
 
-Run the deterministic verification chain (build + tests + validators) before trusting an LLM judge score:
+When Gate 3 passes, Claude asks how to integrate. You can also run it yourself:
 
 ```bash
-morph-spec verify my-feature           # whole feature
-morph-spec verify my-feature T001      # scoped to one task
+morph-spec finish my-feature --pr
 ```
 
----
-
-## Work-type routing
-
-Not every change needs the full pipeline walked above. Every feature is born with a **work type** that dimensions its pipeline:
+`finish` archives the feature, pushes `morph/my-feature` and opens the PR.
 
-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):
+## Along the way
 
 ```bash
-# 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"
+morph-spec next my-feature      # what happens next, read from disk
+morph-spec status my-feature    # phase, gates and progress
+morph-spec fleet                # every active feature
 ```
 
-You can also let the deterministic detector classify a free-text request instead of picking a type by hand (`--request` doubles as the description):
+Picked up a session mid-feature? Run `/morph-apply my-feature`. It resumes from `3-implement/report.md`.
 
-```bash
-morph-spec create my-feature --request "produção caiu, corrigir urgente"
-```
-
-Change the type later if it turns out to be wrong (blocked after Gate 3):
-
-```bash
-morph-spec retype my-feature hotfix --reason "escalated to production incident"
-```
-
-Production incidents run through the dedicated `/morph-hotfix my-feature` slash command instead of `/morph-proposal`.
-
----
-
-## Parallel development with worktrees
-
-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 --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 (Gate 3 approved), close it in one step:
-
-```bash
-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
-morph-spec worktree list
-```
-
----
-
-## Multiple 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-plan/
-└── payment-flow/
-    ├── feature.json
-    └── 0-proposal/
-```
-
-See every active feature — root and worktrees — with phase, gates, and activity:
-
-```bash
-morph-spec fleet
-```
-
----
+Not everything needs the full flow. `/morph-plan` routes by work type: `feature` and `bug` run the whole flow, `chore` writes a short plan and goes straight to implementation. For a production incident, use `/morph-hotfix my-feature`: Gate 3 always stops for a human.
 
 ## Keeping up to date
 
-When a new version of `@polymorphism-tech/morph-spec` is published:
-
 ```bash
-# Update the CLI (--prefer-online bypasses the ~5 min local packument cache)
 npm install -g @polymorphism-tech/morph-spec@latest --prefer-online
-
-# Update framework files in your project
 morph-spec update
-
-# Verify
 morph-spec doctor
 ```
 
-`morph-spec update` re-syncs `.morph/framework/`, `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, and `CLAUDE.md`. It does not touch your config, context, or feature outputs.
-
----
-
-## Tips
-
-**Use `/morph-proposal` even for small features.** The proposal phase catches scope creep, identifies the right agents, and generates contracts early — before implementation makes it expensive to change direction.
-
-**Approve explicitly at each gate.** The design gate exists to prevent implementing the wrong thing. If something in `spec.md` or `contracts.cs` looks off, say so before approving.
-
-**ADRs belong in `decisions.md`.** When Claude makes an architectural choice, it documents it there. Read it after Design completes. Decisions drive the validators that run during implementation.
-
-**`morph-spec doctor` is your first debugging step.** If something is behaving unexpectedly, doctor will surface version mismatches, missing files, and hook configuration issues.
-
----
-
 ## Next steps
 
 - [CHEATSHEET.md](CHEATSHEET.md) — command reference
-- [ARCHITECTURE.md](ARCHITECTURE.md) — system design and agent hierarchy
+- `.morph/framework/CLI.md` — every command in detail
 - [CHANGELOG.md](../CHANGELOG.md) — release history
-- `.morph/framework/standards/` — all coding and architecture standards
 
 ---
 
-*morph-spec v10.0.0 by Polymorphism Tech*
+*morph-spec v10.2.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -22,7 +22,7 @@ Prefixo `morph-spec`; detalhe em `.morph/framework/CLI.md`.
 
 | Comando | Para quê |
 |---|---|
-| `create <f> --request "…" [--worktree]` | nasce a feature |
+| `create <f> --request '…' [--worktree]` | nasce a feature |
 | `next <f>` | o próximo passo, do disco |
 | `plan-check <f>` | valida o plano, grava `checks.json` |
 | `gate-check <f> <gate>` / `approve` / `advance` | decide e aprova gates |
@@ -38,7 +38,7 @@ Prefixo `morph-spec`; detalhe em `.morph/framework/CLI.md`.
 
 ## Gate 3 (sub-agents)
 
-`morph-verifier`, `morph-reviewer`, `morph-security` em `.claude/agents/`, gerados de `agents.json` — nunca edite à mão. Com a crítica do plano (`Plan` nativo, `morph-plan`), são os únicos sub-agents do fluxo; o resto é feito nesta sessão. Leia o relatório que gravam, não a mensagem final.
+`morph-verifier`, `morph-reviewer`, `morph-security` em `.claude/agents/`, gerados de `agents.json` — nunca edite à mão. Com a crítica do plano (`Plan` nativo, `morph-plan`), são os únicos sub-agents do fluxo; o resto é feito nesta sessão. Do Gate 3, leia o relatório que gravam, não a mensagem final.
 
 <!-- morph-agents:start -->
 _Lista derivada na instalação. Bloco vazio → `morph-spec setup-infra --reinstall`._

package/framework/MORPH.md

@@ -15,7 +15,7 @@ Entre gates, você opera sozinho: faz o que `next` mandar (`implement`, `verify`
 | `next` devolve `escalate` (3 verify vermelhos seguidos) | `AskUserQuestion`: aceitar, continuar ou parar. Nunca uma 4ª tentativa por conta própria |
 | `verify` exit 3 | fila cheia, não vermelho: no máximo uma chamada nova |
 
-Na abertura do plano vale o contrário: o modo entrevista pergunta até fechar o entendimento. **A prova é o código:** `verify` prova o determinístico, o Gate 3 prova cada cenário `Cn`. Estilo é nota, nunca bloqueio.
+Na abertura do plano vale o contrário: confronte o pedido com o código e pergunte o que a tese não fecha. **A prova é o código:** `verify` prova o determinístico, o Gate 3 prova cada cenário `Cn`. Estilo é nota, nunca bloqueio.
 
 ---
 
@@ -40,7 +40,7 @@ Na abertura do plano vale o contrário: o modo entrevista pergunta até fechar o
 
 ### 2.1 Roteamento por tipo de trabalho
 
-`morph-spec create <f> --request "<pedido>"` (ou `--type <t> --description "…"`).
+`morph-spec create <f> --request '<pedido>'` (ou `--type <t> --request '…'`).
 
 | Tipo | Pipeline | Gates |
 | --- | --- | --- |

package/framework/agents.json

@@ -18,7 +18,6 @@
         "prove",
         "scenario",
         "check",
-        "mutation",
         "verdict"
       ],
       "stack": [

package/framework/commands/morph-archive.md

@@ -23,7 +23,7 @@ is idempotent: an already-archived feature is reported, not re-moved.
 
 1. **Verify** the feature cleared Gate 3:
    ```
-   morph-spec approval-status {feature}
+   morph-spec status {feature} --verbose
    ```
    Gate `review` must be `approved`. If not, stop and report what's missing (don't force it without
    the user's say-so).