@polymorphism-tech/morph-spec 7.4.0 → 7.5.0

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:** 7.4.0  
+**Version:** 7.5.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -365,4 +365,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v7.4.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v7.5.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -26,6 +26,8 @@ import { worktreeSetupCommand } from '../src/commands/project/worktree.js';
 
 // === Approval gates (human-only) ===
 import { approveCommand, approvalStatusCommand, unapproveCommand } from '../src/commands/state/approve.js';
+import { advanceCommand } from '../src/commands/state/advance.js';
+import { archiveCommand } from '../src/commands/state/archive.js';
 
 // === Validation ===
 import { validateCommand } from './validate.js';
@@ -117,6 +119,22 @@ program
   .option('--notes <notes>', 'Approval notes')
   .action((feature, gate, options) => approveCommand(feature, gate, options));
 
+program
+  .command('advance <feature>')
+  .description('Approve the current phase gate and scaffold the next phase folder (one step)')
+  .option('--approver <name>', 'Name of approver (default: current user when interactive, "auto" otherwise)')
+  .option('--mode <mode>', 'Approval mode: "user" or "auto" (default: detected from TTY)')
+  .option('--design', 'From proposal, advance into the optional design (uiux) phase instead of plan')
+  .option('--notes <notes>', 'Approval notes')
+  .action((feature, options) => advanceCommand(feature, options));
+
+program
+  .command('archive <feature>')
+  .description('Archive a completed feature (atomic, git-aware): move folder + update state')
+  .option('--no-git', 'Skip git staging of the move')
+  .option('--force', 'Archive even if Gate 3 (review) is not approved')
+  .action((feature, options) => archiveCommand(feature, options));
+
 program
   .command('approval-status <feature>')
   .description('Show approval status for all gates')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "7.4.0",
+  "version": "7.5.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

@@ -196,4 +196,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v7.4.0 by Polymorphism Tech*
+*morph-spec v7.5.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -197,4 +197,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v7.4.0 by Polymorphism Tech*
+*morph-spec v7.5.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -5,7 +5,7 @@
 ## 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` — identifique a feature `in_progress` e a fase atual.
+2. Leia `.morph/state.json` — índice fino e gitignored (só status + updatedAt por feature) — para identificar a feature `in_progress` e a fase atual. **Não o edite à mão:** é reconstruído a partir dos `feature.json` a cada load. O estado autoritativo e commitado de cada feature vive em `.morph/features/{feature}/feature.json`.
 3. 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.
@@ -15,13 +15,13 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 **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`, `mandate.md`, e os campos de plano de `tasks.json` (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) estão congelados.
-- Usar `Edit` em `tasks.json` após o Gate 2 — o arquivo é gravado inteiro via `writeTasksJson` (Write). O hook `protect-spec-files` bloqueia `Edit`.
+- Tocar os campos de contrato do plano em `tasks.json` após o Gate 2 (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) — o hook `protect-spec-files` faz diff semântico e bloqueia mudanças neles, seja via `Write` ou `Edit`. (Os campos mutáveis `status`/`outputs`/`notes` continuam graváveis por `Write` ou `Edit` — ver SEMPRE.)
 - Listar perguntas em texto simples — sempre use a tool `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, ou SQL cru sem justificativa.
 
 **SEMPRE:**
 - Auto-advance entre tarefas durante a fase implement — não pause sem ambiguidade bloqueante.
-- Atualizar o progresso em `tasks.json` via `writeTasksJson` ao concluir cada task — apenas os campos `status`, `outputs` e `notes` mudam; o contrato do plano permanece congelado.
+- Atualizar o progresso em `tasks.json` ao concluir cada task gravando apenas os campos mutáveis `status`, `outputs` e `notes` — via `Write` OU `Edit` (o hook `protect-spec-files` faz diff semântico e permite qualquer um dos dois desde que o contrato do plano permaneça congelado).
 - Apresentar gates com o template fixo definido em MORPH.md / morph-plan.
 - Registrar decisões não triviais em `decisions.md`.
 - Aplicar `morph-eval` após cada tarefa; silêncio em score ≥ 9 é o sinal correto. Score < 9 dispara o loop de correção autônomo (re-implementa, sem pausa), não escala ao humano entre tarefas.
@@ -33,10 +33,15 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 | `/morph-proposal {feature}` | Entendimento de negócio + plano (Gates 1 e 2) |
 | `/morph-apply {feature}` | Execução autônoma + review (Gate 3) |
 | `/morph-status [feature]` | Status da feature ativa (ou a especificada) |
-| `/morph-archive {feature}` | Arquiva feature concluída (após Gate 3) |
+| `/morph-archive {feature}` | Arquiva feature concluída (após Gate 3) — wrapper de `morph-spec archive` (atômico, git-aware) |
 | `/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** (a LLM os usa em vez de editar o estado à mão para aprovar/avançar):
+- `morph-spec approve <feature> <gate> --mode auto` — aprova um gate (`proposal`/`plan`/`review`) em `trust: auto`.
+- `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 archive <feature>` — arquiva a feature (atômico, git-aware); é o que `/morph-archive` chama.
+
 ## Skills core (em `.claude/skills/`)
 
 | Skill | Quando usar |

package/framework/MORPH.md

@@ -4,7 +4,7 @@
 > Ele define papéis, fases, outputs, standards, gates e skills do morph-spec.
 > Não procure instruções em hooks — o harness vive aqui.
 >
-> **Depois de ler:** leia `.morph/state.json` para identificar a feature ativa e a fase atual. Se o arquivo existir e houver uma feature `in_progress`, assuma o papel correspondente à fase e continue o trabalho sem esperar instrução. Se não houver feature ativa, pergunte ao usuário qual feature trabalhar ou se é uma feature nova.
+> **Depois de ler:** leia `.morph/state.json` para identificar a feature ativa e a fase atual. `state.json` é um **índice fino e gitignored** (só status + updatedAt por feature, reconstruído a partir dos `feature.json` a cada load) — use-o apenas para descobrir a feature ativa, **nunca o edite à mão** (a edição é perdida no próximo load). O estado autoritativo e commitado de cada feature vive em `.morph/features/{feature}/feature.json`. Se houver uma feature `in_progress`, assuma o papel correspondente à fase e continue o trabalho sem esperar instrução. Se não houver feature ativa, pergunte ao usuário qual feature trabalhar ou se é uma feature nova.
 
 ---
 
@@ -77,7 +77,7 @@ Os papéis não são exclusivos — numa sessão longa você transita entre Orch
 
 ## 2. Fases
 
-O fluxo padrão de uma feature tem quatro fases. Cada fase tem uma pasta dedicada em `.morph/features/{feature}/`.
+O fluxo padrão de uma feature tem quatro fases. Cada fase tem uma pasta dedicada em `.morph/features/{feature}/`. O estado autoritativo e commitado da feature mora em `.morph/features/{feature}/feature.json` (status, approvalGates, outputs, tasks, gateDecisions, taskScores, archivedAt); a raiz `.morph/state.json` é só um índice fino e gitignored derivado dele, e a identidade do projeto fica no `.morph/config/config.json` (commitado).
 
 | Fase        | Pasta          | Gate                  | O que termina a fase                            |
 |-------------|----------------|-----------------------|-------------------------------------------------|
@@ -186,7 +186,7 @@ Para alterar o modo: editar `.morph/config/config.json → trust` (`"auto"` ou `
 
 **Comportamento padrão fora de gate:** trabalhe com autonomia total. Gates só existem nestes três pontos. Não pause para confirmação no meio de implementação a menos que encontre uma ambiguidade de escopo que o mandate não cobre — nesse caso, registre a ambiguidade no decisions.md, resolva da forma mais conservadora possível, e sinalize na entrega da task.
 
-**O hook state-sync.js** detecta as respostas dos Gates automaticamente: quando uma `AskUserQuestion` é respondida com label começando em "aprovado", marca o gate correspondente em `.morph/state.json` com `approvedBy: "manual"` (um humano aprovou no loop). Em modo auto sem AskUserQuestion, a skill atualiza state.json diretamente (allowlist permite Edit em `.morph/state.json`).
+**A aprovação de gate é unificada nos comandos da CLI — a LLM nunca edita o estado à mão para aprovar um gate.** Em `trust: "auto"` (sem `AskUserQuestion`), a skill aprova o gate via `morph-spec approve <feature> <gate> --mode auto`; para aprovar o gate da fase corrente **e** já criar a pasta da próxima fase num passo só, use `morph-spec advance <feature>` (adicione `--design` para tomar o ramo opcional de uiux a partir da proposta) — isso substitui o Edit manual de state.json + `mkdir` da pasta de fase. **O hook state-sync.js** cobre o caminho manual: quando uma `AskUserQuestion` é respondida com label começando em "aprovado", ele registra o gate correspondente no `feature.json` autoritativo da feature com `approvedBy: "manual"` (um humano aprovou no loop), na forma canônica. Nos dois caminhos o gate acaba gravado em `.morph/features/{feature}/feature.json` — nunca via Edit à mão de `state.json`.
 
 **Registre quem aprovou cada gate (`approvedBy`):** o gate é um objeto `{ approved, timestamp, approvedBy }`.
 - `approvedBy: "auto"` — gate avançado por política `trust: auto` sem decisão humana.
@@ -194,7 +194,7 @@ Para alterar o modo: editar `.morph/config/config.json → trust` (`"auto"` ou `
 
 Isso mantém o audit trail honesto justamente nos contextos headless (CI, `claude -p`) onde ele mais importa.
 
-**O hook gate-guard.js** confere, sem bloquear, se a ação tomada num gate (pausar via `AskUserQuestion` vs auto-aprovar) bateu com a decisão de trust que a skill computou via `shouldPauseGate`. Para isso, a skill **persiste** a decisão em `state.json` antes de agir: `features[feature].gateDecisions[gate] = { pause, reason, signals, trust, decidedAt }`. Se a ação observada divergir do registro (pausou um gate auto-aprovável, ou auto-aprovou um gate que exigia pausa), o guard injeta um aviso no contexto — a LLM corrige. É um guardrail silencioso, nunca um orquestrador: coerente, sem registro, ou erro → silêncio.
+**O hook gate-guard.js** confere, sem bloquear, se a ação tomada num gate (pausar via `AskUserQuestion` vs auto-aprovar) bateu com a decisão de trust que a skill computou via `shouldPauseGate`. Para isso, a skill **persiste** a decisão no `feature.json` autoritativo da feature antes de agir: `gateDecisions[gate] = { pause, reason, signals, trust, decidedAt }` (escrito com a tool `Edit` — a allowlist permite `Edit(.morph/features/**)`). Se a ação observada divergir do registro (pausou um gate auto-aprovável, ou auto-aprovou um gate que exigia pausa), o guard injeta um aviso no contexto — a LLM corrige. É um guardrail silencioso, nunca um orquestrador: coerente, sem registro, ou erro → silêncio.
 
 ---
 

package/framework/commands/create-umbraco-lp.md

@@ -0,0 +1,35 @@
+---
+description: Cria uma nova landing page ponta-a-ponta a partir do template MORPH Umbraco genérico: coleta decisões, scaffolda com new-lp, sobe e valida, customiza branding e módulos.
+argument-hint: [nome-do-projeto]
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
+---
+
+# /create-umbraco-lp — Nova LP Umbraco
+
+Cria um projeto de landing page novo a partir do template canônico `MORPH_Umbraco_LP_Template`.
+
+**Implementação:** este slash command é um atalho. O agente deve invocar `Skill(create-umbraco-lp)` com o nome do projeto (se fornecido). A skill coleta decisões do usuário uma pergunta por vez, scaffolda via `new-lp.ps1` / `new-lp.sh`, valida o boot (Delivery API + Ping de leads) e apresenta o checklist de entrega.
+
+## Argumentos
+
+`[nome-do-projeto]` — nome do projeto/LP (opcional; se não fornecido, a skill pergunta).
+
+## Pré-requisitos
+
+- `gh` autenticado (ou credencial git) com acesso ao repositório **privado** `polymorphism-tech/MORPH_Umbraco_LP_Template` (branch `master`).
+- .NET 10 SDK instalado (`dotnet --version` deve retornar `10.x`).
+- Node.js 20+ e npm instalados.
+- PowerShell 7+ (Windows) ou bash (Linux/macOS) para os scripts.
+
+## Anti-padrões
+
+- Não editar `backend/uSync/v17/` manualmente durante o setup — deixar o uSync importar no primeiro boot.
+- Não commitar `.env` ou `frontend/.env.local` — contêm credenciais e secrets.
+- Não reutilizar `UMBRACO_GLOBAL_ID` de outro projeto — o script gera um UUID único por execução.
+
+## Referências
+
+- `framework/skills/core/create-umbraco-lp/SKILL.md`
+- `docs/umbraco-lp-patterns.md` (em `main`)
+
+**Projeto:** $ARGUMENTS

package/framework/commands/migrate-lp-to-umbraco.md

@@ -0,0 +1,33 @@
+---
+description: Migra uma LP existente (React/Vite, Next.js estático ou HTML) para o template Umbraco-headless MORPH entregando a LP EXATAMENTE igual à origem (mesmo CSS, imagens, fontes e comportamento) + Umbraco — obtenção automática do template, lift-and-rewire verbatim de cada seção para módulo editável, conexão do formulário ao backend de leads e gate de paridade determinístico. Repo-agnóstica.
+argument-hint: <projeto>
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, Skill
+---
+
+# /migrate-lp-to-umbraco — Migração de LP para Umbraco Headless
+
+Migra a LP de origem para o template `MORPH_Umbraco_LP_Template` de forma reproduzível, entregando a LP **exatamente igual** à origem com o Umbraco por cima.
+
+**Implementação:** este slash command é um atalho. O agente deve invocar `Skill(migrate-lp-to-umbraco)` com o nome do projeto como argumento. A skill é **repo-agnóstica** — obtém o template sozinha e funciona mesmo sem template ou origem pré-baixados.
+
+## Argumentos
+
+`{projeto}` — nome do projeto em kebab-case (ex.: `reserva-das-flores`, `lp-imobiliaria`).
+
+## Fluxo resumido
+
+0. **Obter o template** — clone/cache de `polymorphism-tech/MORPH_Umbraco_LP_Template` (privado, branch `master`) via `gh repo clone` (fallback git HTTPS/SSH). Sempre garantido antes de qualquer passo.
+1. **Analisar a origem (capturar para um lift)** — inventariar seções, markup/classes exatos, CSS/tema verbatim, assets byte-a-byte (com `sha256`), fontes e comportamentos. Origem por código-fonte local ou só URL (scrape). Produzir `docs/origem-inventario.md`.
+2. **Mapear para módulos** — cada seção vira um módulo via **lift verbatim** (default) — reuso direto do template só quando o render já bate com a origem. Produzir `docs/mapeamento-modulos.md`.
+3. **Scaffold via new-lp** — cópia fresca do template para o diretório do projeto, `git init`, `scripts/new-lp.sh`/`.ps1` com `--lead-integration`, smoke-boot com `docker compose up --build`.
+4. **Lift verbatim** — copiar markup/CSS/classes/assets de cada seção verbatim para o componente do módulo, trocando só os literais por leitura do backoffice; uSync `.config`, `SeedContentHandler` idempotente, `globals.css` com o tema portado, registro em `moduleRegistry.ts`.
+5. **Conectar formulário** — selecionar sink (`ghl`/`prospectpro`/`webhook`) no backoffice via nó `leadsConfig`; nunca colocar token em código ou env.
+6. **Gate de paridade** — checks determinísticos (DOM+classes, estilo computado, checksum de assets, comportamento) como bloqueio + screenshot diff como corroboração secundária. A skill scaffolda `parity.spec.ts` e `compare-sections.mjs`.
+
+## Referências
+
+- `framework/skills/core/migrate-lp-to-umbraco/SKILL.md` — playbook completo (passos 0-6, gate de paridade)
+- `polymorphism-tech/MORPH_Umbraco_LP_Template` — template canônico (privado, branch `master`), obtido no passo 0
+- `MORPH_Umbraco_LP_Template/scripts/new-lp.sh` / `new-lp.ps1` — scaffold
+
+**Projeto:** $ARGUMENTS

package/framework/commands/morph-archive.md

@@ -1,7 +1,7 @@
 ---
 description: Archive a completed MORPH-SPEC feature after Gate 3 approval
 argument-hint: <feature-name>
-allowed-tools: Read, Write, Edit, Bash
+allowed-tools: Read, Bash
 ---
 
 # Archive MORPH Feature
@@ -9,39 +9,29 @@ allowed-tools: Read, Write, Edit, Bash
 Archive a feature that has cleared Gate 3 (review). Use when the work is shipped and you want the
 feature out of the active set in `.morph/features/`.
 
-## Prerequisites
-
-Before archiving, verify:
-- [ ] Feature folder exists at `.morph/features/{feature}/`
-- [ ] `4-review/review-report.md` exists and Gate 3 is approved in `state.json`
-- [ ] `3-implement/recap.md` is filled in
-- [ ] Code is merged or otherwise shipped
-
-If any precondition fails, stop and report what is missing instead of archiving.
+This is a thin wrapper over the atomic, git-aware CLI command — do **not** move folders or edit state
+by hand. The command moves the folder, stamps the feature `completed` + `archivedAt` in its
+`feature.json`, stages the move in git, and cleans the derivable root index, all-or-nothing.
 
 ## Workflow
 
-1. **Validate completion** by reading `state.json`:
-   - `features[name].phase === 'review'`
-   - `features[name].approvalGates.review.approved === true`
-
-2. **Move the folder** from active to archive:
+1. **Verify** the feature cleared Gate 3:
    ```
-   .morph/features/{feature}/  →  .morph/archive/{feature}/
+   morph-spec approval-status {feature}
    ```
-   Use `Bash` (`mv` on POSIX, `Move-Item` on Windows). Preserve all phase subfolders
-   (`0-proposal/`, `1-design/`, `2-plan/`, `3-implement/`, `4-review/`).
-
-3. **Update state.json**:
-   - Set `features[name].status = 'completed'`
-   - Set `features[name].archivedAt = <ISO timestamp>`
+   Gate `review` must be `approved`. If not, stop and report what's missing (don't force it without
+   the user's say-so).
 
-4. **Confirm with the user** before any destructive step. Show the move plan first.
-
-## Output
+2. **Archive** atomically:
+   ```
+   morph-spec archive {feature}
+   ```
+   The command refuses if Gate 3 isn't approved (override with `--force` only when the user asks).
+   It moves `.morph/features/{feature}/` → `.morph/archive/{feature}/` (via `git mv` when possible),
+   sets `status: "completed"` + `archivedAt`, and drops the feature from the thin index.
 
-Present a short summary of what moved and the new path. Do not invent metrics that are not
-recorded in state.json or recap.md.
+3. **Report** the new path (`.morph/archive/{feature}/`). Do not invent metrics not recorded in
+   `feature.json` or `recap.md`.
 
 ---
 

package/framework/hooks/claude-code/core/enforce-phase-writes.js

@@ -1,90 +1,115 @@
-#!/usr/bin/env node
-
-/**
- * PreToolUse Hook: Enforce Phase-Appropriate File Writes
- *
- * Event: PreToolUse | Matcher: Write|Edit
- *
- * Ensures writes to .morph/features/{feature}/ go to the current phase's subfolder:
- *   proposal → only 0-proposal/
- *   uiux → only 1-design/
- *   plan → only 2-plan/
- *   implement → 3-implement/ + any source code (unrestricted)
- *   review → only 4-review/
- *
- * Files outside .morph/features/ are always allowed.
- *
- * Fail-open: exits 0 on any error.
- */
-
-import { existsSync } from 'fs';
-import { resolve } from 'path';
-import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists, getFeaturePhase } from '../../shared/state-reader.js';
-import {
-  isFeaturePath,
-  extractFeatureName,
-  extractPhaseDir,
-  PHASE_DIRS
-} from '../../shared/phase-utils.js';
-import { block, pass } from '../../shared/hook-response.js';
-import { logHookActivity } from '../../shared/activity-logger.js';
-import { getFilePath } from '../../shared/payload-utils.js';
-
-try {
-  // Amend mode: bypass phase write enforcement for legitimate corrections
-  if (process.env.MORPH_AMEND_PHASE) {
-    console.error(`[morph-spec] AMEND MODE: bypassing phase protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
-    pass();
-  }
-
-  if (!stateExists()) pass();
-
-  const payload = await readStdin();
-  if (!payload) pass();
-
-  const filePath = getFilePath(payload);
-  if (!filePath) pass();
-
-  // Only check files inside .morph/features/
-  if (!isFeaturePath(filePath)) pass();
-
-  const featureName = extractFeatureName(filePath);
-  if (!featureName) pass();
-
-  const phase = getFeaturePhase(featureName);
-  if (!phase) pass();
-
-  // During implement phase, all writes are allowed (source code is unrestricted)
-  if (phase === 'implement' || phase === 'sync') pass();
-
-  const targetDir = extractPhaseDir(filePath);
-  if (!targetDir) pass(); // File directly in feature root — allow
-
-  const allowedDir = PHASE_DIRS[phase];
-  if (!allowedDir) pass(); // Unknown phase — allow
-
-  if (targetDir !== allowedDir) {
-    // Allow editing already-existing files from previous phases
-    const absolutePath = resolve(process.cwd(), filePath);
-    if (existsSync(absolutePath)) {
-      logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
-      pass(); // editing existing file — allow
-    }
-
-    const phaseLabel = phase.toUpperCase();
-    logHookActivity('enforce-phase-writes', 'PreToolUse', 'blocked');
-    block(
-      `MORPH-SPEC: Writing to '${targetDir}/' is not allowed during ${phaseLabel} phase.\n` +
-      `Current phase '${phase}' only permits writes to '${allowedDir}/'.\n\n` +
-      `If you need to write to a different phase folder, ensure the feature\n` +
-      `has advanced to the appropriate phase first (check gates in state.json).`
-    );
-  }
-
-  logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
-  pass();
-} catch {
-  // Fail-open
-  process.exit(0);
-}
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Hook: Enforce Phase-Appropriate File Writes
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ *
+ * Ensures writes to .morph/features/{feature}/ go to the current phase's subfolder:
+ *   proposal → only 0-proposal/
+ *   uiux → only 1-design/
+ *   plan → only 2-plan/
+ *   implement → 3-implement/ + any source code (unrestricted)
+ *   review → only 4-review/
+ *
+ * Files outside .morph/features/ are always allowed.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, getFeaturePhase, isGateApproved } from '../../shared/state-reader.js';
+import {
+  isFeaturePath,
+  extractFeatureName,
+  extractPhaseDir,
+  PHASE_DIRS
+} from '../../shared/phase-utils.js';
+
+/**
+ * The gate that authorizes writing a phase folder's FIRST artifact. Once that
+ * gate is approved, the next phase's canonical file may be created even though
+ * the phase only advances (via derivation) once that file exists — this is the
+ * fix for the forward-transition chicken-and-egg. proposal-approval unlocks both
+ * the optional `1-design/` and `2-plan/` (the uiux fork).
+ */
+const PHASE_DIR_ENTRY_GATE = {
+  '1-design': 'proposal',
+  '2-plan': 'proposal',
+  '3-implement': 'plan',
+  '4-review': 'plan',
+};
+import { block, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+import { getFilePath } from '../../shared/payload-utils.js';
+
+try {
+  // Amend mode: bypass phase write enforcement for legitimate corrections
+  if (process.env.MORPH_AMEND_PHASE) {
+    console.error(`[morph-spec] AMEND MODE: bypassing phase protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
+    pass();
+  }
+
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check files inside .morph/features/
+  if (!isFeaturePath(filePath)) pass();
+
+  const featureName = extractFeatureName(filePath);
+  if (!featureName) pass();
+
+  const phase = getFeaturePhase(featureName);
+  if (!phase) pass();
+
+  // During implement phase, all writes are allowed (source code is unrestricted)
+  if (phase === 'implement' || phase === 'sync') pass();
+
+  const targetDir = extractPhaseDir(filePath);
+  if (!targetDir) pass(); // File directly in feature root — allow
+
+  const allowedDir = PHASE_DIRS[phase];
+  if (!allowedDir) pass(); // Unknown phase — allow
+
+  if (targetDir !== allowedDir) {
+    // Allow editing already-existing files from previous phases
+    const absolutePath = resolve(process.cwd(), filePath);
+    if (existsSync(absolutePath)) {
+      logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
+      pass(); // editing existing file — allow
+    }
+
+    // Gate-aware forward transition: allow creating the NEXT phase's first
+    // artifact as soon as the gate authorizing that phase is approved. Without
+    // this, the first file of a new phase can never be written (the phase only
+    // advances once that file exists) — the deadlock this hook used to create.
+    const entryGate = PHASE_DIR_ENTRY_GATE[targetDir];
+    if (entryGate && isGateApproved(featureName, entryGate)) {
+      logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
+      pass();
+    }
+
+    const phaseLabel = phase.toUpperCase();
+    logHookActivity('enforce-phase-writes', 'PreToolUse', 'blocked');
+    block(
+      `MORPH-SPEC: Writing to '${targetDir}/' is not allowed during ${phaseLabel} phase.\n` +
+      `Current phase '${phase}' only permits writes to '${allowedDir}/'.\n\n` +
+      `To move forward, approve the current gate and scaffold the next phase in\n` +
+      `one step:  morph-spec advance ${featureName}\n` +
+      `(this approves the gate that unlocks the next phase folder).`
+    );
+  }
+
+  logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/claude-code/core/protect-spec-files.js

@@ -11,11 +11,14 @@
  *
  * Semantic exception for files in MUTABLE_SPEC_FIELDS (e.g. tasks.json):
  * the plan contract is frozen, but per-task progress fields (status, outputs,
- * notes) may still change during the implement phase. For those files a Write
- * is allowed only when the semantic diff touches solely the mutable fields;
- * Edit is always blocked because the legitimate progress path is a full Write
- * via writeTasksJson(). This lets the implement phase record task status
- * without unfreezing the plan.
+ * notes) may still change during the implement phase. For those files BOTH a
+ * full Write and a targeted Edit are allowed — but only when the semantic diff
+ * touches solely the mutable fields. The Edit is simulated (old_string →
+ * new_string applied to the current file) and diffed exactly like a Write, so a
+ * one-field status flip via Edit is permitted while any change to the frozen
+ * plan contract (titles, dependencies, doneCriteria, the task set) is blocked.
+ * This is the sanctioned progress path — the agent never has to rewrite the
+ * whole file nor reach for a Node script to record task status.
  *
  * Fail-open: exits 0 on any error.
  */
@@ -129,40 +132,39 @@ try {
   // that touches only those fields. Anything else stays blocked.
   if (mutableFields) {
     const toolName = getToolName(payload);
-    const newContent = payload?.tool_input?.content;
-
-    // Edit is never the legitimate progress path — progress is written as a
-    // full file via writeTasksJson(). Block Edit; fall through to the message.
-    if (toolName !== 'Write' || typeof newContent !== 'string') {
-      logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
-      block(
-        `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
-        `Progress updates (${mutableFields.join(', ')}) must be written as a full-file\n` +
-        `Write, not an Edit. The plan contract (titles, dependencies, doneCriteria…)\n` +
-        `is frozen. To change the plan itself, ask the user to revoke the\n` +
-        `'${requiredGate}' gate in .morph/state.json, then re-present it for approval.`
-      );
-    }
 
-    // Semantic diff: old = current file on disk, new = proposed content.
-    // Any failure to read/parse → fail-open (pass), never a false block.
+    // Build the proposed document from either a full Write or a targeted Edit,
+    // then semantic-diff it against the current file on disk. Any failure to
+    // read / parse / apply → fail-open (pass), never a false block.
+    const absPath = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
     let oldDoc, newDoc;
     try {
-      // filePath may already be absolute (Claude Code usually sends absolute
-      // paths); only join against cwd when it is relative.
-      const absPath = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
-      oldDoc = JSON.parse(readFileSync(absPath, 'utf-8'));
-      newDoc = JSON.parse(newContent);
+      const original = readFileSync(absPath, 'utf-8');
+      oldDoc = JSON.parse(original);
+
+      if (toolName === 'Edit') {
+        // Simulate the edit: apply old_string → new_string to the current file.
+        const oldStr = payload?.tool_input?.old_string;
+        const newStr = payload?.tool_input?.new_string;
+        if (typeof oldStr !== 'string' || typeof newStr !== 'string') throw new Error('no edit strings');
+        const edited = payload?.tool_input?.replace_all
+          ? original.split(oldStr).join(newStr)
+          : original.replace(oldStr, newStr);
+        newDoc = JSON.parse(edited);
+      } else {
+        const newContent = payload?.tool_input?.content;
+        if (typeof newContent !== 'string') throw new Error('no content');
+        newDoc = JSON.parse(newContent);
+      }
     } catch {
-      // Cannot compare — fail-open rather than block a possibly-valid write.
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
       pass();
     }
 
     const violations = diffPlanContract(oldDoc, newDoc, mutableFields);
     if (violations.length === 0) {
-      // Only mutable progress fields changed — this is a legitimate
-      // implement-phase update.
+      // Only mutable progress fields changed — a legitimate implement-phase
+      // update via Write OR Edit.
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
       pass();
     }
@@ -170,7 +172,7 @@ try {
     logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
     block(
       `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
-      `This Write changes the frozen plan contract:\n` +
+      `This ${toolName} changes the frozen plan contract:\n` +
       violations.map(v => `  • ${v}`).join('\n') + '\n\n' +
       `During the implement phase only these fields may change: ${mutableFields.join(', ')}.\n` +
       `To change the plan itself, ask the user to revoke the '${requiredGate}' gate\n` +