@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/docs/CHEATSHEET.md

@@ -185,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.47.0 by Polymorphism Tech*
+*morph-spec v9.1.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.47.0 by Polymorphism Tech*
+*morph-spec v9.1.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -1,114 +1,54 @@
 # MORPH-SPEC Runtime Instructions
 
-> by Polymorphism Tech — Spec-driven development harness for Claude Code
-
-## Como começar cada sessão
-
-1. Leia `.morph/framework/MORPH.md` — o charter NLH com papéis, fases, gates e skills.
-2. Leia `.morph/state.json` — índice fino e gitignored (status + updatedAt por feature), reconstruído a cada load. **Não o edite à mão.** Estado autoritativo e commitado de cada feature: `.morph/features/{feature}/feature.json`.
-3. Se existir `.morph/features/{feature}/handoff.md` para a feature ativa, **leia-o antes de re-derivar contexto à mão** — documento de retomada comprimido (regenere com `morph-spec handoff <f>` se parecer velho).
-4. Assuma o papel correspondente (Orchestrator/Specialist/Evaluator) e continue o trabalho. Não aguarde instrução do usuário se há trabalho pendente entre gates.
-
-Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
-
-## Regras críticas
-
-**NUNCA:**
-- Pular para código sem proposal aprovado (Gate 1) e plano aprovado (Gate 2).
-- Modificar o contrato do plano depois do Gate 2 — `spec.md` e os campos `title`/`description`/`dependencies`/`effort`/`doneCriteria`/`group`/`agent`/`standards` de `tasks.json` ficam congelados (`protect-spec-files` bloqueia `Write`/`Edit`); mutáveis: `status`/`outputs`/`notes` (ver SEMPRE). **Fato errado sobre o código não exige revogar gate**: bloco `## Errata` append-only no fim, corpo intacto (MORPH.md §3). **Use cases (`2-plan/usecases/UC-*.md`) NÃO congelam** — editáveis por design.
-- Escrever critérios de aceite no `proposal.md` — pertencem aos use cases (pós-condição **observável em teste**, chega **literal** ao `doneCriteria`).
-- Editar `.morph/specs/usecases/` à mão — só o `finish` escreve lá. Mudar um UC existente (`bug`): copie para `2-plan/usecases/` da feature e corrija lá.
-- Listar perguntas em texto simples — sempre `AskUserQuestion` (1-4 perguntas por chamada).
-- Usar `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), ou SQL cru sem justificativa.
-- Comentar o que nome, tipo ou teste já dizem: o padrão é nenhum comentário, mesmo ao lado de código comentado; o elo com a pós-condição vai no nome do teste (`architecture-code-comments`, hook `comment-guard`).
-- Editar `gateDecisions` ou gates de `feature.json` à mão — sempre via `morph-spec gate-check`/`approve` (timestamps server-side; Edit manual colide com o hook `state-sync`).
-
-**SEMPRE:**
-- Auto-advance entre tarefas durante a fase implement — não pause sem ambiguidade bloqueante.
-- Abrir toda feature `feature`/`bug` com a escolha de **modo de descoberta** (entrevista ou automático), depois de varrer o ambiente. **No modo entrevista, uma pergunta por chamada de `AskUserQuestion`** — o "1-4 por chamada" não é licença para agrupar a entrevista. O Gate 1 pausa sempre nesse modo.
-- Atualizar `tasks.json` ao concluir cada task gravando só os campos mutáveis `status`/`outputs`/`notes` — via `Write` OU `Edit`.
-- Apresentar gates com o template fixo (MORPH.md/morph-plan). **A pergunta PRECISA nomear a feature** ("Gate 2 — Plano de {feature} aprovado?") — é por esse nome que `state-sync` atribui a aprovação ao `feature.json` certo. Sem nome, com mais de uma feature na árvore, ele **recusa gravar** — aprove com `morph-spec approve <feature> <gate>`.
-- Registrar decisões não triviais em `decisions.md`.
-- Fechar cada task só com `verify {f} {T}` verde e cada `doneCriteria` com a evidência que o prova; vermelho ou critério sem prova dispara o loop de correção autônomo, sem escalar ao humano entre tarefas. No Gate 3, o veredito (`SHIP`/`FIX`) vem do **avaliador independente** despachado pela `morph-review` — nunca de quem implementou.
-- Em `hotfix`, o Gate 3 pausa **sempre** para um humano, mesmo em `trust: auto` — `approve ... review --mode auto` é recusado; aprove com `--approver`.
-- Confirmar antes de `finish`/`archive`/`delete` se o SessionStart avisar que outra sessão tem claim vivo na mesma feature.
-- **Ao retomar o controle depois de um dispatch, o orquestrador lê o arquivo de relatório, não a mensagem final** — a mensagem pode não chegar ou vir resumida. As cláusulas do prompt vivem só nos templates (`morph-implement` §4, `morph-apply` §3b).
+> by Polymorphism Tech — harness spec-driven para Claude Code
+
+## 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. `.morph/state.json` é índice gitignored, só para achar a feature ativa; o estado autoritativo é `.morph/features/{feature}/feature.json`.
+3. Existe `.morph/features/{feature}/handoff.md`? Leia antes de re-derivar contexto à mão.
+4. Feature em andamento → assuma o papel da fase e continue entre gates sem esperar instrução. Nenhuma ativa → pergunte qual trabalhar.
+
+## 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.
+
+## CLI do loop
+
+Prefixo `morph-spec`; flags e porquês em `.morph/framework/CLI.md` (um `###` por comando).
+
+| Comando | Para quê |
+|---|---|
+| `create <f> --description "…" --type <t> [--worktree]` | nasce a feature; exit 2 = você escolhe o tipo |
+| `stack-scan [f]` | desvios do código contra `project.stack` |
+| `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) |
+| `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 |
 
 ## Slash commands
 
-| Comando | Propósito |
-|---------|-----------|
-| `/morph-proposal {feature}` | Entendimento de negócio + plano (Gates 1 e 2). Passo 0 roteia por tipo de trabalho (`feature`/`bug`/`chore`/`hotfix`) |
-| `/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-**sem-integrar** (legadas/faxina) — wrapper de `archive`. Fechamento normal = `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):
-
-| Comando | Propósito |
-|---------|-----------|
-| `approve <f> <gate> --mode auto` | Aprova gate em `trust:auto`. Gate 3 exige `evaluator-report.md` (ou `--self-assessed`); `hotfix` nunca aceita `--mode auto` — use `--approver` |
-| `advance <f>` | Aprova o gate corrente + já cria a pasta da próxima fase |
-| `gate-check <f> <gate> [--json]` | Default: decide via sinais do disco (`shouldPauseGate`) |
-| `gate-decision <f> <gate> --pause <bool>` | Escape manual: risco que o disco não vê |
-| `create <f> --description "..." --type <t>` | Nasce a feature + `feature.json`; `--worktree` já isola |
-| `list [--all] [--json]` | Quadro de auditoria: feature × workType × status × gates |
-| `delete <f> [--archive] [--force]` | Remove feature; recusa se gate aprovado sem `--force` |
-| `retype <f> <tipo>` | Muda o workType mid-flight; bloqueado após o Gate 3 |
-| `finish <f> --pr\|--merge` | Encerramento único: arquiva, promove use cases, desmonta worktree. Integra só no `--merge`; `--pr` abre PR e fica `aguardando-merge` até alguém mergear |
-| `archive <f>` | Arquiva sem integrar (legadas/faxina) |
-| `worktree setup\|provision\|link\|remove\|list\|reap` | Ciclo do worktree; `provision` = isolamento de task; `remove` é a única remoção segura |
-| `branch prune [--dry-run]` | Apaga branch já integrada, inclusive squash-merge; nunca a com PR aberto |
-| `handoff <f>` | Regenera o documento de retomada da feature |
-| `fleet` | Visão agregada de toda feature ativa (raiz + worktrees) |
-| `claim [f] [--release] [--list]` | Posse advisory — confirme antes de `finish`/`archive`/`delete` se outra sessão tiver claim vivo |
-| `dag <f>` | DAG de `tasks.json`: sequencial/paralelo, recomenda isolamento |
-| `graph status\|build\|refresh` | Grafo de codebase. `status` reporta frescor e se há refresh em background |
-| `graph affected\|explain <sym>` | Blast radius e vizinhança saneados. Sem grafo, caia para grep — nunca é erro |
-| `verify <f> [task] [--ci]` | Build+testes+validadores+e2e — prova da task; a do Gate 3 com `--ci` (no CI) |
-| `e2e up\|status\|down <f>` | Stack de verificação (docker compose) |
-| `doctor --worktrees [--prune]` | Reconcilia git × disco × features; só `--prune` remove algo |
-| `report-check <f> [task...] [--json]` | Audita relatório de sub-agent vs. trabalho entregue |
-| `telemetry [--feature] [--limit]` | Caminho de execução da sessão a partir de `events.jsonl` |
-| `cost [f] [--by task\|phase] [--metrics]` | Custo (bytes/duração) e medições do loop (turnos, rerun, releitura) do mesmo log |
-
-Prefixo de todo comando: `morph-spec`. Flags/exemplos: `.morph/framework/CLI.md`.
-
-## Skills core (em `.claude/skills/`)
-
-| Skill | Quando usar |
-|-------|-------------|
-| `morph-brainstorming` | Entender negócio, escanear stack, produzir proposal.md |
-| `morph-stack-scan` | Desvios de stack em projeto brownfield |
-| `morph-uiux` | Ramo opcional de UI/UX — design system e mockups |
-| `morph-plan` | Destilar use cases e produzir spec.md + tasks.json |
-| `morph-implement` | Executar uma tarefa com auto-advance entre tasks |
-| `morph-review` | Produzir review-report.md (Gate 3) |
-| `morph-hotfix` | Hotfix cirúrgico (`/morph-hotfix`) |
-| `morph-standards` | Localizar standard sob demanda |
-| `morph-machine` | RAM/CPU: fila pesada, órfãos, worktrees sobrando |
-
-## Roteamento por tipo de trabalho
-
-`workType` (`create --type <tipo>` ou classificado de `--request`) dimensiona o pipeline: `feature` completo (+ ramo uiux quando há superfície de UI), `bug` enxuto, `chore` fast-track (Gates 1/2 por política), `hotfix` scout→fix→gate humano→ship. Canônico: `MORPH.md` §2.1/§5.
-
-Features independentes rodam em paralelo, uma por git worktree (`create --worktree`/`worktree setup`), bloco de portas próprio + handoff.md. Fechamento: `finish <f> --pr|--merge`; agregado: `fleet`. Canônico: `MORPH.md` §2.2.
+`/morph-plan {f}` (plano), `/morph-apply {f}` (execução + Gate 3), `/morph-hotfix {f}`, `/morph-status [f]`.
 
 ## Personas (em `.claude/agents/`)
 
-Despache tasks de domínio com `subagent_type: "morph-{id}"` — a persona é o **system prompt** do subagent registrado (gerado de `agents.json`, a fonte única). Tipo não registrado (stack não instalado): fallback `general-purpose` + campo `persona` colado no prompt, **registrando nas `notes` da task** (detalhe: `morph-apply` §3b).
+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-agents:start -->
-_Lista derivada na instalação (`morph-spec setup-infra`). Se este bloco está vazio, rode `morph-spec setup-infra --reinstall`._
+_Lista derivada na instalação. Bloco vazio → `morph-spec setup-infra --reinstall`._
 <!-- morph-agents:end -->
 
-Drift entre `agents.json` e os `.md` gerados é detectado por `morph-spec doctor` — nunca edite `.claude/agents/morph-*.md` à mão.
-
-## Regra de precedência de skills
-
-Com o plugin superpowers ativo, `morph-*` vence o equivalente genérico (aplica Gates e paths de `.morph/`), e `using-git-worktrees`→`morph-spec worktree setup|provision`.
+## Precedência de skills
 
-*MORPH-SPEC v5 by Polymorphism Tech*
+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`.