@polymorphism-tech/morph-spec 9.8.0 → 10.1.1

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 v9.8.0 by Polymorphism Tech*
+*morph-spec v10.1.1 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -4,47 +4,41 @@
 
 ## Início de cada sessão
 
-1. Leia `.morph/framework/MORPH.md` uma vez (de novo após `/compact`): papéis, fases, gates, dispatch.
-2. O SessionStart injeta a feature ativa e `▶ próximo:`; sem ele, `morph-spec next <f>`. Estado autoritativo: `.morph/features/{f}/feature.json` (`state.json` é índice — nunca edite).
-3. Feature em andamento → faça o que o `next` manda, entre gates, sem esperar instrução. Nenhuma ativa → pergunte qual trabalhar.
+1. Leia `.morph/framework/MORPH.md` uma vez (de novo após `/compact`).
+2. O SessionStart injeta a feature ativa e `▶ próximo:`; sem ele, `morph-spec next <f>`. Estado autoritativo: `.morph/features/{f}/feature.json` — só pela CLI.
+3. Feature em andamento → faça o que o `next` manda, sem esperar instrução. Nenhuma → pergunte qual.
 
 ## Regras
 
-- Perguntas ao usuário só por `AskUserQuestion` (1-4 por chamada), nunca em texto solto. Na entrevista da `morph-plan`, **uma pergunta por chamada**: lote impede que uma resposta pode os ramos seguintes. Única exceção: ferramenta indisponível ou negada (headless) — texto numerado com a resposta recomendada e gate pausado (`morph-plan` §3).
-- A pergunta de gate nomeia a feature ("Gate do plano — Plano de {feature} aprovado?"): é por esse nome que o hook `state-sync` grava a aprovação no `feature.json` certo; sem nome, com mais de uma feature, ele recusa e você aprova por `morph-spec approve <feature> <gate>`.
-- Estado só pela CLI, nunca à mão: `feature.json`, `gateDecisions`, `checks.json` (escrito só por `plan-check`) e o corpo do `plan.md` depois do gate (fato errado → `## Errata` no fim; escopo mudou → `unapprove`).
-- SessionStart avisou claim vivo de outra sessão na mesma feature → confirme com o usuário antes de `finish`/`archive`/`delete`.
-- Depois de um dispatch, leia o arquivo de relatório da fatia, não a mensagem final, que pode não chegar.
+- Perguntas só por `AskUserQuestion`; na entrevista do plano, uma por chamada. Headless: texto numerado com a recomendada e gate pausado.
+- A pergunta de gate nomeia a feature ("Gate do plano — Plano de {f} aprovado?"): é por ela que o hook `state-sync` grava a aprovação.
+- "Não li" ou "não entendi" depois de uma saída longa → refaça do zero, sem supor que a anterior foi lida: até 5 passos numerados, uma frase cada, o primeiro sendo o que mudou para o usuário.
+- Plano aprovado congela: fato errado → `## Errata` no fim; escopo mudou → `unapprove`.
+- SessionStart avisou claim de outra sessão na feature → confirme antes de `finish`/`archive`/`delete`.
 
 ## CLI do loop
 
-Prefixo `morph-spec`; flags e porquês em `.morph/framework/CLI.md` (um `###` por comando).
+Prefixo `morph-spec`; detalhe em `.morph/framework/CLI.md`.
 
 | Comando | Para quê |
 |---|---|
-| `create <f> --description "…" --type <t> [--worktree]` | nasce a feature; exit 2 = você escolhe o tipo |
-| `next <f>` | o próximo passo, decidido do disco |
-| `stack-scan [f]` | desvios do código contra `project.stack` |
-| `tests-audit` | candidatos a apagar/fundir na suíte (só lê) |
-| `plan-check <f>` | valida `plan.md`, grava `checks.json`, imprime as ondas |
-| `gate-check <f> <gate>` | decide a pausa pelos sinais do disco |
-| `approve <f> <gate> --mode auto` / `advance <f>` | aprova (advance também abre a próxima fase) |
+| `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 |
 | `verify <f> [--ci]` | build + testes + validadores + e2e, sem filtro |
-| `report-check <f> [F1 …]` | audita o relatório de cada fatia e diz a ação |
-| `mutate <f>` | mutação dirigida do Gate 3 (até 3 mutantes) |
-| `finish <f> --pr\|--merge` | encerra; só o `--merge` integra |
-| `standards --find "<tema>"` / `--show <id>#<âncora>` | digest do standard / uma seção |
-| `heavy status\|run -- <cmd>` | fila de build/teste; exit 3 = fila cheia |
-| `worktree setup\|provision\|link\|remove\|list\|reap` | ciclo da worktree; `remove` é a única remoção segura |
-| `graph affected\|explain <sym>` | blast radius; sem grafo, caia para grep |
+| `report-check <f> [--before-eval]` | estado dos relatórios do Gate 3 |
+| `e2e up\|status\|reset\|down <f>` | stack da feature |
+| `finish <f> --pr\|--merge` | encerra; grava o recap animado no archive |
+| `standards --find "<tema>"` | digest do standard |
+| `heavy run -- <cmd>` | build/teste pesado na fila |
+| `worktree setup\|provision\|link\|remove\|list` | ciclo da worktree; `remove` é a única remoção segura |
+| `graph affected\|explain <sym>` | blast radius; sem grafo, grep |
+| `graph diff [--base <ref>]` | árvore de chamadas do que mudou; recusa grafo velho |
 
-## Slash commands
+## Gate 3 (sub-agents)
 
-`/morph-plan {f}` (plano), `/morph-apply {f}` (execução + Gate 3), `/morph-hotfix {f}`, `/morph-status [f]`.
-
-## Personas (em `.claude/agents/`)
-
-Despache fatias com `subagent_type: "morph-{id}"` — a persona, gerada de `agents.json`, é o system prompt. Tipo não registrado: `general-purpose` com o `persona` colado, registrado no relatório da fatia. Nunca edite `.claude/agents/morph-*.md` à mão (`morph-spec doctor` acusa o drift).
+`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`._
@@ -52,4 +46,4 @@ _Lista derivada na instalação. Bloco vazio → `morph-spec setup-infra --reins
 
 ## Precedência de skills
 
-Com o plugin superpowers ativo, `morph-*` vence o equivalente genérico (aplica os gates e os paths de `.morph/`), e `using-git-worktrees`→`morph-spec worktree setup|provision`.
+`morph-*` vence o equivalente genérico; `using-git-worktrees` → `morph-spec worktree setup|provision`.