@polymorphism-tech/morph-spec 8.17.0 → 8.18.0

package/framework/docs/CLI.md

@@ -0,0 +1,40 @@
+# morph-spec CLI — Referência Completa
+
+> Referência completa (flags, semântica, exemplos) dos comandos `morph-spec` usados pela LLM em vez de editar o estado à mão. Resumo rápido em `.morph/framework/CLAUDE.md`; racional dos gates em `.morph/framework/MORPH.md` §5, dispatch de sub-agents em §6, worktree/fleet em §2.2.
+
+---
+
+## Gates e estado
+
+- **`morph-spec approve <feature> <gate> --mode auto`** — aprova um gate (`proposal`/`plan`/`review`) em `trust: auto`. **O Gate 3 exige `4-review/evaluator-report.md`**: sem o relatório do avaliador independente o comando recusa (exit 1). Se o dispatch do avaliador for impossível nesta sessão, aprove com `--self-assessed` — a degradação é gravada em `approvalGates.review.selfAssessed` e aparece marcada no `morph-spec list`. `--force` **não** dispensa esta regra (é só para ordem de gate). **Exceção `hotfix`:** esse tipo nunca despacha o avaliador (`morph-hotfix` §7); o Gate 3 exige `4-review/review-report.md` no lugar do `evaluator-report.md`, e a assinatura humana continua obrigatória via `--approver` (o backstop de `--mode auto` acima permanece recusando).
+- **`morph-spec advance <feature>`** — aprova o gate da fase corrente **e** cria a pasta da próxima fase num passo só (`--design` toma o ramo opcional de uiux a partir da proposta).
+- **`morph-spec 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.
+
+## Features
+
+- **`morph-spec create <feature> --description "<o quê/porquê>" --type <feature|bug|chore|hotfix> [--request "<txt>"] [--name "<nome>"] [--worktree]`** — cria a estrutura da feature + `feature.json` canônico explicitamente (nascimento explícito no início da proposal; o hook state-sync continua cobrindo o caminho implícito como fallback). **Identidade no nascimento:** `name` (default = slug) e `description` são carimbados; a `--description` é **obrigatória** numa feature nova (ou `--request`, que a semeia) — sem nenhuma das duas o `create` recusa (fim dos scaffolds anônimos). `--type` classifica direto; `--request "<pedido>"` roda o detector determinístico (empate/sem sinal sai com exit 2 e candidatos — a LLM decide e re-roda com `--type` + `--request`/`--description`); `--worktree` já nasce a feature no seu worktree próprio. **Toda feature nasce numa branch `morph/{f}`** (ramificada da default) mesmo sem `--worktree` — por isso o fechamento por `morph-spec finish` é idêntico nos dois fluxos.
+- **`morph-spec list [--all] [--json]`** — o quadro de auditoria: uma linha por feature × workType × status × fase × gates G1/G2/G3 × descrição, com `⚠` para inconsistências (sem descrição, ordem de gate). `--all` inclui as arquivadas; `--json` para scripting. É o complemento do `delete` (enxergar o que está morto antes de remover).
+- **`morph-spec delete <feature> [--archive] [--force]`** — remove uma feature. Hard por padrão (pasta apagada, git-aware, + entrada podada do índice raiz para não ressuscitar); `--archive` move para `.morph/archive` com status `abandoned` em vez de apagar. Recusa se algum gate estiver aprovado, a menos que `--force`. Use para faxina de scaffolds mortos e drafts abandonados (`archive` é para trabalho concluído; `delete` é para trabalho morto).
+- **`morph-spec retype <feature> <newType>`** — muda o tipo de trabalho mid-flight; desfaz só os gates carimbados por política, preserva aprovações humanas; bloqueado após o Gate 3.
+
+## Worktree / Fleet
+
+- **`morph-spec finish <feature> --pr|--merge`** — o **encerramento único** da feature (worktree ou comum): **arquiva** commitando `features/{f} → archive/{f}` dentro de `morph/{f}` — promovendo junto, no mesmo commit, os use cases da feature para o acervo permanente `.morph/specs/usecases/` com `status: implemented` (fail-open: sem `2-plan/usecases/`, no-op silencioso) — depois integra. `--merge` faz merge `--no-ff` **local** na default (sem push); `--pr` faz `push` + `gh pr create` (exige `origin` + `gh`, checados **antes** de arquivar — um `--pr` recusado não deixa meio-estado). Desmonta o worktree (PROVE-or-DECLINE) e libera o bloco de portas; no `--pr` **preserva** a branch (o PR precisa dela) e fica em `morph/{f}`. Flags: `--keep` mantém o worktree, `--force` dispensa o Gate 3, `--discard-ignored` consente descartar gitignored no teardown. Substitui o antigo `worktree finish` + `archive` separados.
+- **`morph-spec archive <feature>`** — arquiva-**sem-integrar** (atômico, git-aware, commita o move escopado por pathspec): reservado a features legadas (sem branch `morph/{f}`) e faxina. O fechamento normal (arquiva **e** integra num passo) é `morph-spec finish`. É o que `/morph-archive` chama.
+- **`morph-spec worktree setup|link|list`** — gerencia o ciclo do worktree por feature (`setup` cria `worktrees/{f}/` na branch `morph/{f}`, aloca o bloco de portas e escreve `.morph/worktree.env`; `link` religa infra compartilhada; `list` mostra fase/gate de cada worktree ativo). O fechamento saiu daqui — use `morph-spec finish` (acima).
+- **`morph-spec handoff <feature>`** — regenera o documento de retomada (`.morph/features/{f}/handoff.md`): comprimido, derivado, aponta para os artefatos em vez de copiá-los. Gerado automaticamente em `setup`/`create --worktree`/`advance`.
+- **`morph-spec fleet`** — visão da frota: toda feature ativa (raiz + worktrees) com fase, gates pendentes, tasks, **remoto** (`local`/`pushed`/`PR #N`), **claim** (que sessão está na feature), portas, handoff e atividade. Use entre sessões para decidir onde atuar.
+- **`morph-spec claim [feature] [--release] [--list] [--json]`** — posse **advisory** de feature. Cada sessão reclama sua feature ativa automaticamente (hook SessionStart) e renova o heartbeat a cada tool call; o registro vive em `<git-common-dir>/morph-spec/claims.json`, compartilhado por todos os worktrees. **`morph-spec claim <feature>` (sem flags) ADQUIRE** — se esta árvore já tinha claim vivo em outra feature, ele é liberado no mesmo passo (o CLI reporta "movido de X para Y"); é o jeito de trocar de feature no meio da tarefa sem a dança de dois passos `--release` + reclamar. `--list` força a leitura sem adquirir mesmo passando uma feature. **Claims avisam, nunca bloqueiam** — mas se o SessionStart avisar que outra sessão tem claim vivo, **confirme antes de `finish`/`archive`/`delete`**: duas sessões na mesma feature já custaram um recap.md inteiro e um sub-agent (o worktree sumiu debaixo dele). Claim órfão de sessão morta: `morph-spec claim <f> --release`.
+
+## Validação
+
+- **`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). Também cruza `tasks.json` com os use cases: `usecase` apontando para um `UC-{nn}` inexistente é **erro** (exit 1, não despacha); pós-condição órfã e `doneCriteria` que parafraseou em vez de copiar são avisos. `--mermaid` nunca é bloqueado.
+- **`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 doctor --worktrees [--prune] [--json]`** — reconcilia o registro do git × as pastas em disco × as features conhecidas. Worktrees órfãos acumulavam **invisíveis**: o `fleet` só reporta worktrees em branch `morph/*`, então um worktree em outra branch (resíduo de finish anterior) não aparecia em lugar nenhum. `--prune` roda o único reparo seguro (`git worktree prune` — registros de pastas que já sumiram); apagar pasta que ainda existe é reportado com o comando exato, nunca executado.
+- **`morph-spec report-check <feature> [task] [--json]`** — audita os relatórios de sub-agent contra o trabalho que realmente entrou. **Relatório ausente NÃO quer dizer que o agente falhou** — ele pode ter feito tudo e perdido o meio de gravar. O comando responde a pergunta certa (`work-landed-report-missing` → aceite degradado, NÃO re-despache; `no-work-no-report` → re-despache uma vez). Protocolo completo em MORPH.md §6.
+
+## Observabilidade
+
+- **`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.
+- **`morph-spec cost [feature] [--by task|phase] [--json]`** — custo da execução a partir do mesmo `events.jsonl`: duração por task (TaskStart→TaskEnd), bytes de contexto re-ingerido por tipo (`rubric`/`standard`/`skill`/`agents`/`plan-artifact`/`code`), dispatches + tamanho de prompt e mix de tools. Bytes re-ingeridos são **proxy determinística** de custo de token (tokens reais não são observáveis por hook). Use antes/depois de mudar skill ou fluxo para medir o efeito.

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,9 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
+stacks:
+  - umbraco
 ---
 
 # create-umbraco-lp

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,9 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
+stacks:
+  - umbraco
 ---
 
 # migrate-lp-to-umbraco

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-apply
@@ -231,12 +231,8 @@ O comando grava `gateDecisions.review = { pause, reason, signals, trust, decided
 
 ### 6. Pós Gate 3 — encerramento
 
-- Aprovar o Gate 3: em auto, `morph-spec approve {feature} review --mode auto`; em manual, o hook state-sync registra a resposta "aprovado" em AskUserQuestion — **desde que a pergunta nomeie a feature** (o template acima nomeia; se você improvisar sem o nome e houver mais de uma feature na árvore, o hook recusa a gravar e avisa, e você aprova por `morph-spec approve`). O gate fica gravado no `feature.json` autoritativo da feature — nunca via Edit à mão de `state.json`.
-- **Fechar a feature** com `morph-spec finish {feature} --pr|--merge` — um passo só: arquiva commitando `features/{f} → archive/{f}` dentro de `morph/{f}`, integra e desmonta o worktree (se houver). Escolha o modo com `AskUserQuestion` (header `"Integração"`):
-  - **Abrir PR** (`--pr`): faz `push` de `morph/{f}` + `gh pr create` com base na default — para review por outro humano/CI antes do merge. Exige `origin` + `gh` autenticado (checados **antes** de arquivar; se faltarem, `finish` recusa sem efeito colateral — caia para `--merge`). A branch é preservada e a sessão fica em `morph/{f}`.
-  - **Merge local** (`--merge`): merge `--no-ff` na default **localmente**, sem push — para o fluxo single-user direto. Remove a branch e o worktree.
-- Não integre automaticamente sem a escolha do modo: `finish` toca o remoto (`--pr`) ou a branch default (`--merge`) — é uma ação de saída que pede confirmação.
-- Feature **legada** (criada antes do modelo "nasce numa branch", sem `morph/{f}`): `finish` recusa e roteia para `morph-spec archive {feature}` (arquivar-sem-integrar); nesse caso, arquive.
+- Aprovar o Gate 3: em auto, `morph-spec approve {feature} review --mode auto`; em manual, o hook state-sync registra a resposta "aprovado" em `AskUserQuestion` — **desde que a pergunta nomeie a feature** (senão aprove via `morph-spec approve`).
+- **Fechar a feature** com `morph-spec finish {feature} --pr|--merge`, modo escolhido via `AskUserQuestion` (header `"Integração"`): `--pr` (push + PR, review antes do merge) vs `--merge` (integra local, single-user direto). Não integre automaticamente sem essa escolha. Mecânica completa (o que cada modo faz, feature legada sem `morph/{f}`): `MORPH.md` §2.1/§2.2.
 
 ## Anti-padrões
 

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-brainstorming
@@ -17,17 +17,7 @@ Ao iniciar uma nova feature — antes de qualquer especificação técnica ou pl
 
 ## Stack padrão (baked in)
 
-O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos que haja ambiguidade real.
-
-| Camada | Stack |
-|--------|-------|
-| Backend | .NET 10, VSA (feature-folder: handler + validator + endpoint + errors + tests) |
-| ORM | EF Core + Neon (Postgres), `Guid.CreateVersion7()`, `sealed` classes, `result.Match()` |
-| IA | Microsoft Agent Framework (MAF) — quando a feature envolve agentes |
-| Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
-| Jobs async | Hangfire — apenas se a feature requer processamento em background |
-
-**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions sem result pattern, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), SQL cru sem justificativa. Acesso a dados em VSA: `ApplicationDbContext` direto no slice (`DbSet<T>` já é repository, `DbContext` já é unit of work); para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
+O harness conhece o stack por padrão (backend .NET 10 + VSA + EF Core/Neon, IA via MAF, frontend Next.js/Tailwind/Shadcn) e a lista de padrões proibidos (`Guid.NewGuid()`, classes não-sealed, Service/Manager layer, repository genérico, SQL cru). **Não pergunte sobre tecnologia a menos que haja ambiguidade real** — stack nunca entra na árvore de decisões. Regra canônica: `MORPH.md` § "Stack baked-in".
 
 ## Modo bug-lean (`workType: bug`)
 

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-hotfix

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-implement

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-plan
@@ -88,13 +88,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 4. Produza `mandate.md` em `.morph/features/{feature}/2-plan/`:
    - Stack exata do projeto (leia de `.morph/config/config.json` → `project.stack` ou do CLAUDE.md).
    - Standards obrigatórios: liste os IDs relevantes de `.morph/framework/standards/STANDARDS.json`.
-   - Patterns proibidos — inclua sempre os defaults abaixo mais qualquer específico da feature:
-     - `Guid.NewGuid()` → usar `Guid.CreateVersion7()`
-     - Classes não-sealed sem justificativa documentada
-     - Exceptions como fluxo de controle → usar result pattern com `result.Match()`
-     - Camada de Service/Manager entre handler e dados → handler usa `ApplicationDbContext` direto no slice
-     - Repository genérico (`IRepository<T>`/`IUnitOfWork`) → redundante sobre EF Core: `DbSet<T>` já é repository, `DbContext` já é unit of work
-     - SQL cru (`FromSqlRaw`, `ExecuteQuery(string)`) sem justificativa em `decisions.md` → usar LINQ
+   - Patterns proibidos — **copie por extenso no mandate.md** a lista canônica de `MORPH.md` § "Stack baked-in" (`Guid.NewGuid()`→`Guid.CreateVersion7()`, 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`, SQL cru sem justificativa) mais qualquer proibição específica da feature. Copie o texto completo — o mandate.md é lido por implementadores em contexto fresco, sem `MORPH.md` carregado, então um ponteiro sozinho não basta aqui.
    - Política de acesso a dados (registre no mandate): `ApplicationDbContext` injetado direto no slice — para CRUD e para queries específicas (joins, projeção, paginação). Para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
    - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via STANDARDS.json. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
    - Checklist de done com critérios verificáveis por tarefa.

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-proposal

package/framework/skills/core/morph-review/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-review

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-stack-scan
@@ -17,19 +17,7 @@ Quando o projeto já tem código existente e você precisa entender o estado atu
 
 ## Stack padrão de referência
 
-| Camada | Esperado |
-|--------|----------|
-| Runtime | .NET 10 |
-| Arquitetura | VSA — feature-folder: `{Feature}/` com Handler, Validator, Endpoint, Errors, Tests |
-| ORM | EF Core + Neon (Postgres) |
-| IDs | `Guid.CreateVersion7()` |
-| Classes | `sealed` por padrão |
-| Erros | Result pattern (`result.Match()`), não exceptions não tratadas |
-| IA | Microsoft Agent Framework (MAF) |
-| Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
-| Jobs | Hangfire (apenas quando necessário) |
-
-**Padrões proibidos:** `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`), SQL cru sem justificativa. Acesso a dados em VSA: `ApplicationDbContext` direto no slice (`DbSet<T>` já é repository, `DbContext` já é unit of work); para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
+O "Esperado" da comparação do passo 2 é o stack baked-in (runtime .NET 10 + VSA, EF Core/Neon, `Guid.CreateVersion7()`, `sealed`, result pattern, MAF, Next.js/Tailwind/Shadcn, Hangfire) e a lista de padrões proibidos (`Guid.NewGuid()`, classes não-sealed, Service/Manager layer, repository genérico, SQL cru sem justificativa) — regra canônica em `MORPH.md` § "Stack baked-in". Os templates de `stack-scan.md` abaixo (greenfield e brownfield) escrevem essa lista por extenso no artefato da feature, para que quem ler o `stack-scan.md` depois não precise reabrir o `MORPH.md`.
 
 ## Greenfield short-circuit
 

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-standards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.17.0",
+  "version": "8.18.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/project/doctor.js

@@ -826,13 +826,20 @@ export async function doctorCommand(options = {}) {
     hasErrors = true;
   }
 
-  // Check templates
+  // Check templates — as of the R3 perf plan (Task 2), setup-infra/update no
+  // longer pre-populate .morph/framework/templates/: template resolution is
+  // layered (template-registry.js / architecture-scanner.js resolveTemplatePath)
+  // and falls back to the npm package's own framework/templates/ when the
+  // project-local copy is absent, which is now the expected default rather
+  // than an error. The project-local copy remains a supported override — if
+  // present, report it as such. The "key templates" check further below
+  // verifies the package copy itself is intact, which is the check that
+  // actually matters now.
   const templatesPath = join(morphPath, 'framework', 'templates');
   if (await pathExists(templatesPath)) {
-    checks.push({ name: 'templates/', status: 'ok' });
+    checks.push({ name: 'templates/', status: 'ok', msg: 'local override present' });
   } else {
-    checks.push({ name: 'templates/', status: 'missing' });
-    hasErrors = true;
+    checks.push({ name: 'templates/', status: 'ok', msg: 'resolved from package (no local override)' });
   }
 
   // Check .claude folder

package/src/commands/project/init.js

@@ -486,7 +486,7 @@ export async function initCommand(options) {
     logger.info('Files installed:');
     logger.dim(`  ✓ CLAUDE.md`);
     logger.dim(`  ✓ .morph/config/ (config.json)`);
-    logger.dim(`  ✓ .morph/framework/ (agents.json, standards/, templates/, hooks/)`);
+    logger.dim(`  ✓ .morph/framework/ (agents.json, standards/, hooks/)`);
     logger.dim(`  ✓ .morph/context/ (project context)`);
     logger.dim(`  ✓ .morph/features/ (feature outputs)`);
     if (commandsCopied) {

package/src/commands/project/update.js

@@ -24,7 +24,8 @@ import {
   checkProjectOutdated,
   saveProjectMorphVersion,
   getUpdateInstructions,
-  detectInstallMethod
+  detectInstallMethod,
+  compareVersions
 } from '../../utils/version-checker.js';
 import { installClaudeHooks, installGlobalStatusline } from '../../utils/claude-settings-manager.js';
 import { installSkills } from '../../utils/skills-installer.js';
@@ -59,7 +60,12 @@ async function backupUserConfig(morphPath) {
 async function cleanFrameworkDirs(morphPath, targetPath) {
   const claudeDir = join(targetPath, '.claude');
   const dirsToClean = [
-    join(morphPath, 'framework', 'templates'),
+    // NOTE: framework/templates is intentionally NOT in this list (R3 perf
+    // plan, Task 2). It's no longer copied/refreshed here — see
+    // reconcileLegacyTemplatesCopy() below, which decides per-run whether a
+    // pre-existing local copy is safe to remove or must be preserved as a
+    // user override. Blindly deleting it here (the old behavior) destroyed
+    // any customization on every single `update` run, override or not.
     join(morphPath, 'framework', 'standards'),
     join(morphPath, 'framework', 'hooks'),
     join(morphPath, 'framework', 'schemas'),
@@ -83,6 +89,67 @@ async function cleanFrameworkDirs(morphPath, targetPath) {
   }
 }
 
+/**
+ * Last CLI version whose `update`/`setup-infra` still wrote
+ * `.morph/framework/templates/` unconditionally, before Task 2 of the R3
+ * perf plan removed that copy. Used as the decision boundary in
+ * `reconcileLegacyTemplatesCopy` below — see its doc comment for why a
+ * version check is used instead of diffing file content.
+ */
+const LAST_VERSION_THAT_COPIED_TEMPLATES = '8.17.0';
+
+/**
+ * Reconcile a pre-existing `.morph/framework/templates/` copy now that
+ * `update` no longer writes it (Task 2, R3 perf plan — resolution falls
+ * back to the npm package's own framework/templates/, see
+ * template-registry.js / architecture-scanner.js's layered resolver).
+ *
+ * Decided from the project's PRIOR recorded CLI version (before THIS
+ * update writes a new one), not by diffing content against the package.
+ * A content diff can't tell "stale copy from an older CLI version" apart
+ * from "deliberate user override" — and staleness is the dominant case for
+ * anyone who actually runs `update`, since template content does change
+ * between releases. The version boundary is unambiguous instead:
+ *
+ *   - No local copy → nothing to do.
+ *   - Prior version is unrecorded, OR <= LAST_VERSION_THAT_COPIED_TEMPLATES
+ *     → the copy could ONLY have been put there by the OLD installer:
+ *     `.morph/framework/**` is Edit-denied to the agent (MORPH_DENY in
+ *     hooks-installer.js — "installer-managed, immutable at runtime"),
+ *     the directory is gitignored, and every `update` before this fix
+ *     unconditionally wiped + recopied it. There is no path by which a
+ *     project on an old version could have a genuine override sitting
+ *     here. Safe to delete unconditionally — it is dead weight, not data.
+ *   - Prior version > LAST_VERSION_THAT_COPIED_TEMPLATES → `update` and
+ *     `setup-infra` have never written this directory for this project.
+ *     Anything found here was placed deliberately (by the user or other
+ *     tooling) — this is the forward-looking override use case the
+ *     layered resolver exists for. Preserve untouched, unconditionally,
+ *     with no diffing.
+ *
+ * @param {string} templatesDest - .morph/framework/templates (may not exist)
+ * @param {string|null} priorProjectVersion - project's recorded morph-spec
+ *   version BEFORE this update run (checkProjectOutdated().current)
+ * @returns {'absent'|'removed-legacy'|'preserved-override'}
+ */
+export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion) {
+  if (!existsSync(templatesDest)) return 'absent';
+
+  const isLegacy = !priorProjectVersion
+    || compareVersions(priorProjectVersion, LAST_VERSION_THAT_COPIED_TEMPLATES) <= 0;
+
+  if (!isLegacy) return 'preserved-override';
+
+  try {
+    fs.removeSync(templatesDest);
+    return 'removed-legacy';
+  } catch {
+    // Couldn't remove — don't risk a half-broken state; leave it and let
+    // the layered resolver's override-first check pick it up as before.
+    return 'preserved-override';
+  }
+}
+
 /**
  * Restore user's config.json after reinstallation
  * @param {string} morphPath - Path to .morph directory
@@ -240,12 +307,14 @@ export async function updateCommand(options) {
     const updateTemplates = !options.standards || options.templates;
     const updateStandards = !options.templates || options.standards;
 
-    // Update templates
+    // Templates are no longer copied to .morph/framework/templates/ (Task 2,
+    // R3 perf plan) — see reconcileLegacyTemplatesCopy()'s doc comment for
+    // why. Only reconcile a leftover copy from a pre-R3 install.
+    let templatesReconcile = 'absent';
     if (updateTemplates) {
-      updateSpinner.text = 'Updating templates...';
-      const templatesSrc = join(contentDir, 'framework', 'templates');
+      updateSpinner.text = 'Checking for a legacy templates copy...';
       const templatesDest = join(morphPath, 'framework', 'templates');
-      await copyDirectory(templatesSrc, templatesDest);
+      templatesReconcile = reconcileLegacyTemplatesCopy(templatesDest, projectCheck.current);
     }
 
     // Update standards
@@ -289,6 +358,13 @@ export async function updateCommand(options) {
         await copyDirectory(src, join(morphPath, 'framework', dir));
       }
     }
+    // CLI.md vive em framework/docs/ na fonte mas instala achatado em
+    // .morph/framework/CLI.md (o CLAUDE.md residente aponta para lá) —
+    // por isso não entra no loop de nomes acima.
+    const cliMdSrc = join(canonicalFrameworkDir, 'docs', 'CLI.md');
+    if (await pathExists(cliMdSrc)) {
+      await copyFile(cliMdSrc, join(morphPath, 'framework', 'CLI.md'));
+    }
 
     // Regenerate derived files (phase-utils.js, skill output tables) from output-schema.js
     // Only runs when the generator script is present (framework dev installs via npm link)
@@ -415,7 +491,15 @@ export async function updateCommand(options) {
 
     logger.blank();
     logger.info('Updated files:');
-    if (updateTemplates) logger.dim('  ✓ .morph/framework/templates/');
+    if (updateTemplates) {
+      if (templatesReconcile === 'removed-legacy') {
+        logger.dim('  ✓ .morph/framework/templates/ (legacy installer copy removed — resolved from package)');
+      } else if (templatesReconcile === 'preserved-override') {
+        logger.dim('  ⚠ .morph/framework/templates/ (local override present — preserved untouched, not updated)');
+      } else {
+        logger.dim('  · .morph/framework/templates/ (not present — resolved from package, no local override)');
+      }
+    }
     if (updateStandards) logger.dim('  ✓ .morph/framework/standards/');
     logger.dim('  ✓ .morph/framework/hooks/');
     logger.dim('  ✓ .morph/framework/agents.json');

package/src/lib/stack-filter.js

@@ -16,10 +16,15 @@ export function parseStacks(content) {
 
   const fm = fmMatch[1];
 
-  // Try inline format: stacks: [dotnet, blazor]
+  // Try inline format: stacks: [dotnet, blazor] — quotes stripped like the
+  // list branch below; `["umbraco"]` sem isso parseava como a string literal
+  // `"umbraco"` (com aspas) e nunca casava tag nenhuma.
   const inlineMatch = fm.match(/^stacks:\s*\[([^\]]*)\]/m);
   if (inlineMatch) {
-    const items = inlineMatch[1].split(',').map(s => s.trim()).filter(Boolean);
+    const items = inlineMatch[1]
+      .split(',')
+      .map(s => s.replace(/["']/g, '').trim())
+      .filter(Boolean);
     return items.length > 0 ? items : ['*'];
   }
 

package/src/scripts/setup-infra.js

@@ -264,14 +264,23 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
     await writeFile(contextReadmePath, readmeContent);
   }
 
-  // --- 5. Copy framework/templates → .morph/framework/templates ---
-  log('Step 5: Copying framework templates...');
-  const frameworkTemplatesSrc = join(FRAMEWORK_DIR, 'templates');
-  const templatesDest = join(frameworkDestDir, 'templates');
-  if (await pathExists(frameworkTemplatesSrc)) {
-    await copyDirectory(frameworkTemplatesSrc, templatesDest);
-  } else {
-    await ensureDir(templatesDest);
+  // --- 5. framework/templates is intentionally NOT copied to
+  // .morph/framework/templates anymore (R3 perf plan, Task 2). Template
+  // resolution is layered (template-registry.js, architecture-scanner.js
+  // resolveTemplatePath): a project-local .morph/framework/templates/{path}
+  // is still checked FIRST as an explicit override, then falls back to the
+  // npm package's own framework/templates/ — which is what every template
+  // actually rendered from until now anyway, since the installed copy was
+  // never read as anything but that override. Pre-populating it was a
+  // byte-for-byte redundant 348KB copy on every install/update.
+  log('Step 5: Skipping framework templates copy (resolved from package; local override still supported)...');
+  // Cópia legada de instalação pré-R3: se existir, ela SOMBREIA os templates
+  // do pacote (override-first). O `morph-spec update` reconcilia (remove cópia
+  // stale por fronteira de versão); aqui só avisamos — init não conhece a
+  // versão anterior do projeto para decidir com segurança.
+  const legacyTemplatesDir = join(frameworkDestDir, 'templates');
+  if (await pathExists(legacyTemplatesDir)) {
+    log('  ⚠ .morph/framework/templates/ existe (instalação antiga) e tem precedência sobre os templates do pacote — rode `morph-spec update` para reconciliar, ou apague se não for customização sua.');
   }
 
   // --- 6. Copy framework/standards → .morph/framework/standards ---
@@ -324,6 +333,16 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
     await copyFile(morphMdSrc, morphMdDest);
   }
 
+  // --- 8b2. Copy framework/docs/CLI.md → .morph/framework/CLI.md ---
+  // Referência completa dos comandos (flags, semântica, exemplos) — o
+  // CLAUDE.md residente carrega só a tabela compacta e aponta para cá.
+  log('Step 8b2: Copying CLI.md (command reference)...');
+  const cliMdSrc = join(FRAMEWORK_DIR, 'docs', 'CLI.md');
+  const cliMdDest = join(frameworkDestDir, 'CLI.md');
+  if (await pathExists(cliMdSrc)) {
+    await copyFile(cliMdSrc, cliMdDest);
+  }
+
   // --- 8c. Copy framework/phases.json → .morph/framework/phases.json ---
   log('Step 8c: Copying phases.json...');
   const phasesSrc = join(FRAMEWORK_DIR, 'phases.json');

package/src/utils/skills-installer.js

@@ -75,8 +75,14 @@ function copyDirectory(src, dest) {
  *
  * @param {string} srcDir - Source directory to walk
  * @param {string} destDir - Destination base directory (.claude/skills/)
+ * @param {string[]} projectTags - Stack tags from config
+ * @param {Set<string>} installedNow - Accumulator: skill names this call
+ *   actually (re)installed. NOT derived by re-scanning destDir afterwards —
+ *   a disk scan can't distinguish "installed this run" from "leftover from a
+ *   previous run with different projectTags", which is exactly the stale
+ *   entry a stack change needs cleaned up.
  */
-function installSkillsFromDir(srcDir, destDir, projectTags) {
+function installSkillsFromDir(srcDir, destDir, projectTags, installedNow) {
   const entries = readdirSync(srcDir);
   for (const entry of entries) {
     const srcPath = join(srcDir, entry);
@@ -90,9 +96,10 @@ function installSkillsFromDir(srcDir, destDir, projectTags) {
         if (!shouldInstallSkill(content, projectTags)) continue;
         const skillDestDir = join(destDir, entry);
         copyDirectory(srcPath, skillDestDir);
+        installedNow.add(entry);
       } else {
         // Level/category directory — recurse
-        installSkillsFromDir(srcPath, destDir, projectTags);
+        installSkillsFromDir(srcPath, destDir, projectTags, installedNow);
       }
     } else if (entry.endsWith('.md') && entry !== 'README.md') {
       // Legacy flat .md skill — check stack filter before copying
@@ -102,6 +109,7 @@ function installSkillsFromDir(srcDir, destDir, projectTags) {
       const skillDir = join(destDir, skillName);
       mkdirSync(skillDir, { recursive: true });
       copyFileSync(srcPath, join(skillDir, 'SKILL.md'));
+      installedNow.add(skillName);
     }
   }
 }
@@ -147,28 +155,33 @@ export async function installSkills(projectDir, { projectTags = [] } = {}) {
   const claudeSkillsDir = join(projectDir, '.claude', 'skills');
   mkdirSync(claudeSkillsDir, { recursive: true });
 
+  // Skill names this call actually (re)installs, given projectTags. Tracked
+  // as we go (NOT by re-scanning claudeSkillsDir afterwards) — a disk scan
+  // can't tell "installed this run" apart from "leftover from a previous
+  // run with different projectTags", which is exactly the stale entry a
+  // stack change (or a re-run that narrows the stack) needs cleaned up.
+  const installedNow = new Set();
   for (const level of SKILL_LEVELS_TO_INSTALL) {
     const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
     if (!existsSync(levelDir)) continue;
-    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags);
-  }
-
-  // Collect installed morph-* skill names
-  const installed = new Set();
-  for (const entry of readdirSync(claudeSkillsDir)) {
-    if (existsSync(join(claudeSkillsDir, entry, 'SKILL.md'))) {
-      installed.add(entry);
-    }
+    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags, installedNow);
   }
 
-  // Cleanup orphan morph-* skill dirs that exist in source but were filtered out
+  // Clean-slate: remove any skill dir that is a KNOWN framework skill (still
+  // present in framework/skills/core/) but did NOT get (re)installed this
+  // run — i.e. it was filtered out by a `stacks:` mismatch (project.stack
+  // changed, or a re-run narrowed the tags). Previously scoped to `morph-`
+  // prefixed names only, which silently exempted every non-`morph-` skill
+  // (the Umbraco pair) from ever being cleaned up: install once with
+  // `umbraco` in the stack, drop the stack later, and they'd survive every
+  // reinstall/update forever. Names outside allSourceSkills (user-added,
+  // non-framework skills) are never touched.
   const allSourceSkills = collectSourceSkillNames();
   for (const entry of readdirSync(claudeSkillsDir)) {
-    if (!entry.startsWith('morph-')) continue;
-    if (!installed.has(entry) && allSourceSkills.has(entry)) {
+    if (!installedNow.has(entry) && allSourceSkills.has(entry)) {
       rmSync(join(claudeSkillsDir, entry), { recursive: true, force: true });
     }
   }
 
-  return { installed: installed.size };
+  return { installed: installedNow.size };
 }