@polymorphism-tech/morph-spec 5.0.1 → 7.0.0

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

@@ -0,0 +1,137 @@
+---
+name: morph-proposal
+description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encadeia morph-brainstorming (Gate 1) e morph-plan (Gate 2). Em trust:auto pula gates sem sinais de risco.
+version: core
+when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
+user-invokable: true
+---
+
+# morph-proposal
+
+## Objetivo
+
+Conduzir uma feature do request inicial até o plano aprovado (Gate 2), sem intervenção do usuário entre os gates quando `trust: "auto"` e sem sinais de risco.
+
+## Quando invocar
+
+- Usuário pede "use /morph-proposal {feature}" ou "vamos planejar {feature}".
+- Início de qualquer feature nova num projeto morph-spec.
+- Em sessões retomadas, antes de continuar uma feature em progresso, verificar via `.morph/state.json` se a feature já passou pelos Gates.
+
+## Argumentos
+
+- `{feature-name}` — nome em kebab-case da feature. Se ausente, perguntar via `AskUserQuestion`.
+
+## Pré-condições
+
+- `.morph/config/config.json` existe (rode `morph-spec init` antes).
+- Stack está definido (padrão: VSA + .NET 10 + MAF + Next.js + Neon).
+
+## Fluxo
+
+### 1. Determinar feature name e estado
+
+- Se argumento ausente: perguntar via `AskUserQuestion` (1 pergunta, header "Feature").
+- Verificar `.morph/features/{feature-name}/`:
+  - Se `0-proposal/proposal.md` existe e tem conteúdo: pular para passo 3.
+  - Caso contrário: criar a estrutura e seguir o passo 2.
+
+### 2. Invocar `Skill(morph-brainstorming)`
+
+Passa o nome da feature. A skill:
+- Faz até 4 perguntas de negócio via `AskUserQuestion`.
+- Invoca `Skill(morph-stack-scan)` para detectar contexto (greenfield curto-circuita).
+- Detecta divergência entre fontes de design-system e marca `signals.designSystemDivergence`.
+- Produz `proposal.md` em `.morph/features/{feature}/0-proposal/`.
+
+### 3. Gate 1 (trust-aware)
+
+Ler `.morph/config/config.json → trust` (default `"auto"`). Calcular sinais de risco:
+
+- `designSystemDivergence` — detectado pela morph-brainstorming.
+- `standardsViolations` — violações de mandate listadas na proposal (não deveria, mas verifica).
+
+Usar `src/lib/risk-detector.js`:
+
+```js
+import { shouldPauseGate } from '../../../src/lib/risk-detector.js';
+const { pause, reason } = shouldPauseGate(config, signals);
+```
+
+**Se `pause === true`**, apresentar via `AskUserQuestion`:
+
+```
+question: "Gate 1 — Proposta de {feature} aprovada? Sinal de risco: {reason}"
+options:
+  - { label: "aprovado, prosseguir", description: "Aceitar a proposta e avançar para o planejamento" }
+  - { label: "preciso ajustar", description: "Apontar mudanças necessárias na proposta" }
+  - { label: "cancelar feature", description: "Abortar — feature não vai avançar" }
+header: "Gate 1"
+```
+
+Aguardar resposta. Se "preciso ajustar", aplicar ajustes e reapresentar o gate.
+
+**Se `pause === false`**, exibir summary curto e prosseguir:
+
+```
+## Gate 1 (auto-aprovado)
+Feature: {nome}
+Problema: {1 frase}
+Escopo: {incluído} | Excluído: {exclusões}
+Stack: {compliance}
+```
+
+O hook `state-sync.js` registra a aprovação automaticamente via PostToolUse em AskUserQuestion. Quando auto-aprovado, marcar manualmente:
+
+```js
+// auto-aprovação: o hook detecta "aprovado" no answer label, mas em auto-mode
+// não há AskUserQuestion. Skill atualiza .morph/state.json via Edit fallback.
+```
+
+### 4. Verificar retomada antes de morph-plan
+
+- Se `.morph/features/{feature}/2-plan/spec.md` já existe: pular para passo 6 (Gate 2).
+
+### 5. Invocar `Skill(morph-plan)`
+
+A skill lê `proposal.md` e produz:
+- `spec.md` — especificação técnica detalhada
+- `mandate.md` — contrato de implementação (stack defaults + padrões proibidos)
+- `tasks.json` — task breakdown estruturado validado contra `framework/schemas/tasks.schema.json`
+- `decisions.md` — apenas se houver decisões não triviais
+
+### 6. Gate 2 (trust-aware)
+
+Sinais de risco para Gate 2 incluem **mais** do que Gate 1:
+
+- Todos os do Gate 1.
+- `taskCount` — count(tasks.json.tasks). Threshold: 20.
+- `standardsViolations` detectadas no mandate (improvável, mas verificar).
+
+Lógica idêntica ao passo 3 (`shouldPauseGate` + AskUserQuestion ou auto-aprovação).
+
+### 7. Conclusão
+
+- Sinalizar ao usuário: "Plano aprovado. Rode `/morph-apply {feature}` (ou peça 'implementar {feature}') para iniciar a execução."
+- Não dispachar `morph-apply` automaticamente — usuário decide quando começar.
+
+## Anti-padrões
+
+- Não pular o Gate 1 mesmo em trust:auto se houver divergência detectada.
+- Não escrever código nesta fase — apenas artefatos de planejamento.
+- Não perguntar sobre stack — o stack padrão está em MORPH.md / mandate.
+
+## Output esperado
+
+- `.morph/features/{feature}/0-proposal/proposal.md`
+- `.morph/features/{feature}/2-plan/spec.md`
+- `.morph/features/{feature}/2-plan/mandate.md`
+- `.morph/features/{feature}/2-plan/tasks.json`
+- Gates 1 e 2 marcados aprovados em `.morph/state.json` (via hook state-sync).
+
+## Referências
+
+- `.morph/framework/MORPH.md` — charter NLH completo
+- `framework/skills/core/morph-brainstorming/SKILL.md`
+- `framework/skills/core/morph-plan/SKILL.md`
+- `src/lib/risk-detector.js` — `shouldPauseGate`, `getRiskSignals`

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

@@ -2,7 +2,7 @@
 name: morph-review
 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 tarefas de implementação serem concluídas
+when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
 ---
 
@@ -13,8 +13,8 @@ Verificar se a implementação atende ao mandate.md e produzir um review-report.
 claro o suficiente para que o usuário tome a decisão de aprovação ou rejeição.
 
 ## Quando invocar
-Ao iniciar a fase review — após todas as tarefas do tasks.md estarem com status Done
-e o recap.md estar atualizado.
+Ao iniciar a fase review — após todas as tasks de `tasks.json` estarem com status `done`
+e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `morph-apply`.
 
 ## O que fazer
 
@@ -47,16 +47,52 @@ e o recap.md estar atualizado.
    - Preencha `sub_agents_dispatched` com a contagem de tasks onde `sub_agent_dispatched: true`
    - Preencha `completed_at` com o timestamp atual
 
-8. Apresente o relatório ao usuário e aguarde o Gate 3.
+8. Apresente o Gate 3 segundo trust mode.
+
+   Ler `.morph/config/config.json → trust` (default `"auto"`). Calcular sinais de risco:
+
+   ```js
+   import { shouldPauseGate } from '../../../src/lib/risk-detector.js';
+   const signals = {
+     evalScore: phaseScores.composite,
+     standardsViolations: blockingItems.filter(b => b.kind === 'standard').map(b => b.id),
+   };
+   const { pause, reason } = shouldPauseGate(config, signals);
+   ```
+
+   **Se `pause === true`**, use `AskUserQuestion`:
+
+   ```
+   question: "Gate 3 — Review de {feature} aprovado?{ reason ? ' Sinal: ' + reason : '' }"
+   header: "Gate 3"
+   options:
+     - { label: "aprovado, fechar feature", description: "Marcar feature como completed, habilitar /morph-archive" }
+     - { label: "preciso ajustar", description: "Apontar correções necessárias antes de fechar" }
+     - { label: "rollback", description: "Desfazer e voltar para implement" }
+   ```
+
+   **Se `pause === false`**, exibir summary curto e prosseguir:
+
+   ```
+   ## Gate 3 (auto-aprovado)
+
+   **Composite score:** {score}/10
+   **Dimensões:** arquitetura={X} contratos={Y} qualidade={Z} cobertura={W}
+   **Bloqueantes:** {N (zero esperado em auto-aprovação)}
+   **Recomendação:** Aprovado
+   ```
+
+   O hook state-sync detecta a aprovação em answers de AskUserQuestion e marca `features[X].approvalGates.review = true`. Em auto sem AskUserQuestion, a skill atualiza state.json direto.
 
 ## Output esperado
 - `.morph/features/{feature}/4-review/review-report.md` com scores e recomendação
 - Trace da fase com `phase_summary` preenchido
-- Gate 3 apresentado ao usuário para aprovação
+- Gate 3 marcado aprovado em state.json (auto ou manual)
 
 ## Referências
-- `framework/MORPH.md` — seção 5 (Gate 3) e seção 1 (papel Evaluator)
+- `.morph/framework/MORPH.md` — seção 5 (Gate 3), seção 1 (papel Evaluator), Trust Mode
 - `framework/skills/core/morph-eval/SKILL.md` — para calcular scores por dimensão
-- `framework/evals/trace-schema.md` — formato canônico do trace
+- `.morph/framework/evals/trace-schema.md` — formato canônico do trace
 - `.morph/features/{feature}/2-plan/mandate.md` — critérios de done da feature
 - `.morph/features/{feature}/3-implement/recap.md` — registro de execução
+- `src/lib/risk-detector.js` — `shouldPauseGate` para Gate 3

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

@@ -30,7 +30,46 @@ Quando o projeto já tem código existente e você precisa entender o estado atu
 
 **Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, Repository pattern, `IRepository<T>`.
 
-## O que fazer
+## Greenfield short-circuit
+
+Antes de despachar Explore, verifique se o projeto é greenfield:
+
+1. Use `Glob` para detectar presença de qualquer um destes:
+   - `**/*.csproj`
+   - `**/*.sln`
+   - `package.json` (na raiz)
+   - `src/**/*.cs` ou `src/**/*.ts` ou `src/**/*.tsx`
+   - `migrations/**/*`
+
+2. Se **nenhum** for encontrado, o projeto é greenfield. Produza este `stack-scan.md` em `.morph/features/{feature}/0-proposal/` e retorne sem chamar Explore:
+
+   ```markdown
+   # Stack Scan — {feature}
+
+   **Status:** GREENFIELD (sem código source detectado)
+
+   ## Stack
+   Project empty. Aplicar stack padrão de MORPH.md:
+   - Backend: .NET 10 + VSA + EF Core + Neon
+   - Frontend: Next.js App Router + Tailwind + Shadcn + Framer Motion
+   - IA: MAF (quando aplicável à feature)
+   - Jobs: Hangfire (apenas se necessário)
+
+   ## Padrões obrigatórios
+   - IDs: `Guid.CreateVersion7()`
+   - Classes: `sealed` por padrão
+   - Erros: Result pattern (`result.Match()`)
+
+   ## Padrões proibidos
+   `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, Repository pattern, `IRepository<T>`.
+
+   ## Recomendação
+   Compliance trivial (greenfield). Prosseguir para morph-brainstorming.
+   ```
+
+3. Se algum dos arquivos foi encontrado, o projeto é brownfield — siga para o passo seguinte.
+
+## O que fazer (brownfield)
 
 1. Despache um `Explore` subagent para varrer o codebase:
 

package/framework/standards/STANDARDS.json

@@ -182,9 +182,9 @@
       },
       "digest": "Chunk documents with 512 token size and 50 token overlap for RAG. Embed with text-embedding-3-small. Store embedding + metadata (source, chunk index). Retrieve top-k=5 by cosine similarity. Re-rank before injecting into LLM context. Use pgvector HNSW index for performance at scale.",
       "stacks": [
-        "dotnet-vsa",
-        "dotnet-vsa",
-        "nextjs-neon"
+        "dotnet",
+        "nextjs",
+        "neon"
       ]
     },
     {
@@ -1126,8 +1126,7 @@
       },
       "digest": "Guidelines for generating project images with Gemini Image MCP — prompt patterns, aspect ratios, design-system-aware prompts, iterative editing, and assets.md format.",
       "stacks": [
-        "nextjs",
-        "next"
+        "nextjs"
       ]
     }
   ]

package/framework/templates/docs/onboarding.md

@@ -94,10 +94,10 @@ morph-spec doctor
 │   ├── context/                   # Project context & overrides
 │   └── features/{feature}/        # Feature outputs
 │       ├── 0-proposal/
-│       ├── 1-ui/
-│       ├── 2-design/
-│       ├── 4-tasks/
-│       └── 5-implement/
+│       ├── 1-design/              # optional (UI-heavy features)
+│       ├── 2-plan/
+│       ├── 3-implement/
+│       └── 4-review/
 └── .claude/
     ├── commands/                  # Slash commands
     ├── skills/                    # Workflow skills

package/framework/templates/tasks.template.json

@@ -0,0 +1,17 @@
+{
+  "version": "1.0",
+  "feature": "{{featureName}}",
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "Example task title",
+      "description": "What this task accomplishes and why",
+      "dependencies": [],
+      "effort": "M",
+      "doneCriteria": "Verifiable acceptance condition stated in one sentence",
+      "status": "pending",
+      "outputs": [],
+      "group": "backend"
+    }
+  ]
+}

package/package.json

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

package/src/commands/project/init.js

@@ -483,6 +483,19 @@ export async function initCommand(options) {
 
     logger.blank();
 
+    // Populate Claude Code persistent memory so future sessions enter contextualized
+    try {
+      const { installProjectMemory } = await import('../../lib/installers/memory-installer.js');
+      const memResult = await installProjectMemory(targetPath, {
+        projectName: config.project?.name ?? targetPath.split(/[\\/]/).pop(),
+        frameworkVersion: config.frameworkVersion ?? cliVersion,
+        stack: config.project?.stack,
+      });
+      logger.dim(`  ✓ Claude Code memory populated (${memResult.projectMemoryPath})`);
+    } catch (err) {
+      logger.dim(`  ⚠ Memory install skipped: ${err.message}`);
+    }
+
     // Suggest tutorial for first-time users
     if (integrationsCreated) {
       logger.blank();
@@ -490,6 +503,9 @@ export async function initCommand(options) {
     }
 
     logger.blank();
+    logger.warn('IMPORTANT: Restart your Claude Code session for morph-* skills to be available.');
+    logger.dim('Skills installed in .claude/skills/ are only registered at session start.');
+    logger.blank();
 
   } catch (error) {
     spinner.fail('Installation failed');

package/src/commands/validation/validate-feature.js

@@ -69,7 +69,7 @@ const PHASE_OUTPUTS = {
  */
 const PHASE_FOLDERS = {
   proposal: '0-proposal',
-  uiux: '1-ui',
+  uiux: '1-design',
   plan: '2-plan',
   implement: '3-implement',
   review: '4-review',

package/src/core/paths/output-schema.js

@@ -27,16 +27,16 @@ export const OUTPUT_SCHEMA = {
   stackScan:      { filename: 'stack-scan.md',         phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
   migrationPlan:  { filename: 'migration-plan.md',     phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
 
-  // 1-ui/ (optional)
-  uiDesignSystem: { filename: 'design-system.md',      phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiMockups:      { filename: 'mockups.md',            phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiComponents:   { filename: 'components.md',         phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiFlows:        { filename: 'flows.md',              phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  // 1-design/ (optional)
+  uiDesignSystem: { filename: 'design-system.md',      phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiMockups:      { filename: 'mockups.md',            phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiComponents:   { filename: 'components.md',         phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiFlows:        { filename: 'flows.md',              phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
 
   // 2-plan/
   spec:           { filename: 'spec.md',               phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   mandate:        { filename: 'mandate.md',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
-  tasks:          { filename: 'tasks.md',              phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
+  tasks:          { filename: 'tasks.json',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   decisions:      { filename: 'decisions.md',          phaseDir: '2-plan',      phase: 'plan',      protected: false },
 
   // 3-implement/

package/src/core/state/state-manager.js

@@ -34,7 +34,7 @@ export function derivePhase(featurePath) {
     ['4-review', 'review'],
     ['3-implement', 'implement'],
     ['2-plan', 'plan'],
-    ['1-ui', 'uiux'],
+    ['1-design', 'uiux'],
     ['0-proposal', 'proposal'],
   ];
   for (const [folder, phase] of phaseMap) {

package/src/lib/detectors/design-system-detector.js

@@ -64,7 +64,7 @@ export function detectDesignSystem(projectPath, featureName = null) {
       projectPath,
       '.morph/features',
       featureName,
-      '1-ui',
+      '1-design',
       'design-system.md'
     );
 

package/src/lib/installers/memory-installer.js

@@ -0,0 +1,138 @@
+/**
+ * Memory Installer — populates Claude Code persistent memory during morph-init.
+ *
+ * Writes two memory files (project + reference) plus an entry in MEMORY.md
+ * so future Claude Code sessions enter pre-contextualized about the
+ * morph-spec setup of this project.
+ *
+ * Memory location: ~/.claude/projects/<encoded-project-path>/memory/
+ *
+ * The path encoding mirrors Claude Code's own scheme: replace slashes and
+ * colons with dashes. Tests can override via MORPH_MEMORY_ROOT env var.
+ */
+
+import fs from 'fs-extra';
+import { join } from 'path';
+import { homedir } from 'os';
+
+function getMemoryRoot(projectPath) {
+  if (process.env.MORPH_MEMORY_ROOT) return process.env.MORPH_MEMORY_ROOT;
+
+  const encoded = projectPath.replace(/[:\\/]/g, '-').replace(/^-+/, '');
+  return join(homedir(), '.claude', 'projects', encoded, 'memory');
+}
+
+function projectMemoryContent(info) {
+  return `---
+name: project-morph-spec
+description: morph-spec project configuration, paths, slash commands, and trust mode
+metadata:
+  type: project
+---
+
+# ${info.projectName} — morph-spec project
+
+**Framework version:** ${info.frameworkVersion}
+**Stack:** ${info.stack ?? 'default (nextjs + dotnet + VSA + MAF + Neon)'}
+**Trust mode:** auto (gates auto-pass without risk signals)
+
+## Key paths
+
+- \`.morph/framework/MORPH.md\` — NLH charter (read once per session)
+- \`.morph/framework/agents.json\` — 7 domain personas
+- \`.morph/framework/standards/STANDARDS.json\` — standards index (load on demand)
+- \`.morph/framework/schemas/tasks.schema.json\` — JSON Schema for tasks.json
+- \`.morph/features/{feature}/\` — feature artifacts: 0-proposal / 1-design / 2-plan / 3-implement / 4-review
+- \`.morph/context/\` — long-lived architectural context (design-system, decisions)
+- \`.morph/state.json\` — feature state (managed by state-sync hook; Edit fallback allowed)
+
+## Slash commands
+
+| Command | Skill invoked |
+|---------|---------------|
+| \`/morph-proposal {feature}\` | \`Skill(morph-proposal)\` — brainstorming → Gate 1 → plan → Gate 2 |
+| \`/morph-apply {feature}\` | \`Skill(morph-apply)\` — DAG-adaptive implement loop → review → Gate 3 |
+| \`/morph-status [feature]\` | inspect state.json |
+| \`/morph-archive {feature}\` | move completed feature to .morph/archive/ |
+| \`/morph-preflight\` | pre-deploy validation |
+| \`/morph-troubleshoot [erro]\` | diagnose .NET/Next.js errors |
+
+## Core skills
+
+\`morph-proposal\`, \`morph-apply\`, \`morph-brainstorming\`, \`morph-plan\`, \`morph-implement\`, \`morph-eval\`, \`morph-review\`, \`morph-stack-scan\`, \`morph-standards\`
+
+**Why:** This project is managed by morph-spec — spec-driven autonomous development with trust-aware gates.
+
+**How to apply:**
+- When user mentions a feature, check \`.morph/features/\` first.
+- When user types \`/morph-proposal\`, invoke \`Skill(morph-proposal)\` directly.
+- In \`trust: "auto"\`, gates auto-pass; only AskUserQuestion on risk signals.
+- Prefer morph-* skills over superpowers:* equivalents in this project.
+`;
+}
+
+const REFERENCE_MEMORY_CONTENT = `---
+name: reference-morph-context
+description: where to find long-lived morph-spec project context and schema files
+metadata:
+  type: reference
+---
+
+# morph-spec context locations
+
+- \`.morph/context/README.md\` — generated architecture overview
+- \`.morph/context/design-system.md\` — design tokens and components (source of truth)
+- \`.morph/framework/MORPH.md\` — NLH charter, Trust Mode rules, gates, skills table
+- \`.morph/framework/standards/STANDARDS.json\` — index; load specific standard via \`path\` field
+- \`.morph/framework/schemas/tasks.schema.json\` — tasks.json schema reference
+- \`.morph/framework/phases.json\` — phase folder mapping and skill associations
+- \`.morph/framework/agents.json\` — domain persona definitions (dotnet-senior, ef-modeler, etc.)
+- \`.morph/framework/rubrics/\` — eval rubrics for morph-eval scoring
+`;
+
+/**
+ * Populate Claude Code persistent memory for a morph-spec project.
+ *
+ * Idempotent: re-running overwrites the memory files with current info
+ * but appends MEMORY.md index entries only if missing.
+ *
+ * @param {string} projectPath - Absolute path of the project root
+ * @param {object} info - Project facts to embed in the memory
+ * @param {string} info.projectName
+ * @param {string} info.frameworkVersion
+ * @param {string} [info.stack]
+ * @returns {Promise<{ projectMemoryPath: string, referenceMemoryPath: string, indexPath: string }>}
+ */
+export async function installProjectMemory(projectPath, info) {
+  const memoryRoot = getMemoryRoot(projectPath);
+  await fs.ensureDir(memoryRoot);
+
+  const projectMemoryPath = join(memoryRoot, 'project_morph_spec.md');
+  await fs.writeFile(projectMemoryPath, projectMemoryContent(info), 'utf8');
+
+  const referenceMemoryPath = join(memoryRoot, 'reference_morph_context.md');
+  await fs.writeFile(referenceMemoryPath, REFERENCE_MEMORY_CONTENT, 'utf8');
+
+  const indexPath = join(memoryRoot, 'MEMORY.md');
+  let indexContent = '';
+  if (await fs.pathExists(indexPath)) {
+    indexContent = await fs.readFile(indexPath, 'utf8');
+  } else {
+    indexContent = '# Memory Index\n';
+  }
+
+  const projectLine = '- [morph-spec project](project_morph_spec.md) — stack, trust mode, slash commands, key paths';
+  const refLine = '- [morph-spec context](reference_morph_context.md) — where to find long-lived context';
+
+  if (!indexContent.includes('project_morph_spec.md')) {
+    if (!indexContent.endsWith('\n')) indexContent += '\n';
+    indexContent += projectLine + '\n';
+  }
+  if (!indexContent.includes('reference_morph_context.md')) {
+    indexContent += refLine + '\n';
+  }
+
+  await fs.writeFile(indexPath, indexContent, 'utf8');
+
+  return { projectMemoryPath, referenceMemoryPath, indexPath };
+}

package/src/lib/phase-chain/phase-validator.js

@@ -66,10 +66,10 @@ const OUTPUT_PHASE_MAP = {
   'spec.md': '2-plan',
   'mandate.md': '2-plan',
   'decisions.md': '2-plan',
-  'design-system.md': '1-ui',
-  'mockups.md': '1-ui',
-  'components.md': '1-ui',
-  'flows.md': '1-ui',
+  'design-system.md': '1-design',
+  'mockups.md': '1-design',
+  'components.md': '1-design',
+  'flows.md': '1-design',
   'tasks.md': '2-plan',
   'recap.md': '3-implement',
   'review-report.md': '4-review'

package/src/lib/risk-detector.js

@@ -0,0 +1,80 @@
+/**
+ * Risk Detector — decides whether a gate should pause execution.
+ *
+ * In `trust: "auto"` mode (default), gates auto-pass UNLESS one of these
+ * risk signals triggers a forced pause. In `trust: "manual"` mode, gates
+ * always pause via AskUserQuestion.
+ *
+ * Signals checked (in order):
+ *   - designSystemDivergence: boolean — conflicting design sources detected
+ *   - standardsViolations: string[]   — violations of mandate.md proibições
+ *   - evalScore: number               — morph-eval score (pause if < 8)
+ *   - taskCount: number               — total tasks (pause if > 20)
+ */
+
+const SCOPE_TASK_THRESHOLD = 20;
+const MIN_EVAL_SCORE = 8;
+
+/**
+ * @param {object} config - .morph/config/config.json contents (uses `trust`)
+ * @param {object} signals
+ * @returns {{ pause: boolean, reason: string }}
+ */
+export function shouldPauseGate(config, signals) {
+  const trust = config?.trust ?? 'auto';
+
+  if (trust === 'manual') {
+    return { pause: true, reason: 'trust mode is manual' };
+  }
+
+  if (signals.designSystemDivergence) {
+    return { pause: true, reason: 'design-system divergence detected' };
+  }
+
+  if (Array.isArray(signals.standardsViolations) && signals.standardsViolations.length > 0) {
+    return {
+      pause: true,
+      reason: `standards violations detected: ${signals.standardsViolations.join(', ')}`,
+    };
+  }
+
+  if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
+    return {
+      pause: true,
+      reason: `eval score ${signals.evalScore} below threshold ${MIN_EVAL_SCORE}`,
+    };
+  }
+
+  if (typeof signals.taskCount === 'number' && signals.taskCount > SCOPE_TASK_THRESHOLD) {
+    return {
+      pause: true,
+      reason: `scope of ${signals.taskCount} tasks exceeds threshold ${SCOPE_TASK_THRESHOLD}`,
+    };
+  }
+
+  return { pause: false, reason: '' };
+}
+
+/**
+ * Human-readable list of risk signals present (for logging/Gate summary).
+ * @returns {string[]}
+ */
+export function getRiskSignals(signals) {
+  const out = [];
+  if (signals.designSystemDivergence) out.push('design-system divergence');
+  if (Array.isArray(signals.standardsViolations) && signals.standardsViolations.length > 0) {
+    out.push(`standards violations: ${signals.standardsViolations.join(', ')}`);
+  }
+  if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
+    out.push(`eval score ${signals.evalScore}/10`);
+  }
+  if (typeof signals.taskCount === 'number' && signals.taskCount > SCOPE_TASK_THRESHOLD) {
+    out.push(`${signals.taskCount} tasks (over threshold)`);
+  }
+  return out;
+}
+
+export const RISK_CONSTANTS = {
+  SCOPE_TASK_THRESHOLD,
+  MIN_EVAL_SCORE,
+};