@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

package/framework/hooks/git/pre-commit/agents.sh

@@ -1,25 +1,25 @@
-#!/bin/bash
-# Scope: universal | Validates agents.json Schema
-# MORPH-SPEC Pre-Commit Hook: Agent Configuration Validation
-# Uses validate-agents.js to check agents.json
-
-echo "🤖 Validating agent configuration..."
-
-# Check if agents.json is being modified
-if git diff --cached --name-only | grep -q 'agents\.json$'; then
-  echo "Detected changes to agents.json"
-
-  # Run validator
-  if ! morph-spec validate-agents-skills; then
-    echo ""
-    echo "❌ COMMIT BLOCKED: agents.json validation failed"
-    echo "   Fix errors above before committing"
-    exit 1
-  fi
-
-  echo "✓ agents.json is valid"
-else
-  echo "✓ No changes to agents.json"
-fi
-
-exit 0
+#!/bin/bash
+# Scope: universal | Validates agents.json Schema
+# MORPH-SPEC Pre-Commit Hook: Agent Configuration Validation
+# Uses validate-agents.js to check agents.json
+
+echo "🤖 Validating agent configuration..."
+
+# Check if agents.json is being modified
+if git diff --cached --name-only | grep -q 'agents\.json$'; then
+  echo "Detected changes to agents.json"
+
+  # Run validator
+  if ! morph-spec validate-agents-skills; then
+    echo ""
+    echo "❌ COMMIT BLOCKED: agents.json validation failed"
+    echo "   Fix errors above before committing"
+    exit 1
+  fi
+
+  echo "✓ agents.json is valid"
+else
+  echo "✓ No changes to agents.json"
+fi
+
+exit 0

package/framework/hooks/git/pre-commit/orchestrator.sh

@@ -1,64 +1,64 @@
-#!/usr/bin/env bash
-# Scope: universal | Orchestrates framework + stack-specific pre-commit hooks
-# MORPH-SPEC Master Pre-Commit Hook
-# Runs universal framework hooks + stack-specific hooks in sequence
-
-echo "╔════════════════════════════════════════════════╗"
-echo "║     MORPH-SPEC PRE-COMMIT VALIDATION           ║"
-echo "╚════════════════════════════════════════════════╝"
-echo ""
-
-FRAMEWORK_HOOKS_DIR="$(dirname "$0")"
-STACK_HOOKS_DIR=".morph/hooks/pre-commit"
-
-HAS_FAILURES=false
-
-# Run framework hooks (universal - all stacks)
-echo "📦 Running framework hooks (universal)..."
-for hook in "$FRAMEWORK_HOOKS_DIR"/*.sh; do
-  # Skip orchestrator itself
-  if [[ "$hook" == */orchestrator.sh ]]; then
-    continue
-  fi
-
-  if [[ -f "$hook" ]]; then
-    hook_name=$(basename "$hook")
-    echo "─────────────────────────────────────────────────"
-    if ! bash "$hook"; then
-      HAS_FAILURES=true
-      echo "❌ Framework hook failed: $hook_name"
-    fi
-    echo ""
-  fi
-done
-
-# Run stack-specific hooks (if exist)
-if [[ -d "$STACK_HOOKS_DIR" ]]; then
-  echo "🎯 Running stack-specific hooks..."
-  for hook in "$STACK_HOOKS_DIR"/*.sh; do
-    if [[ -f "$hook" ]]; then
-      hook_name=$(basename "$hook")
-      echo "─────────────────────────────────────────────────"
-      if ! bash "$hook"; then
-        HAS_FAILURES=true
-        echo "❌ Stack hook failed: $hook_name"
-      fi
-      echo ""
-    fi
-  done
-else
-  echo "ℹ️  No stack-specific hooks found (optional)"
-  echo ""
-fi
-
-echo "═════════════════════════════════════════════════"
-
-if [[ "$HAS_FAILURES" == "true" ]]; then
-  echo "❌ PRE-COMMIT VALIDATION FAILED"
-  echo "   Fix errors above before committing"
-  echo "   Or use: git commit --no-verify to skip"
-  exit 1
-fi
-
-echo "✅ ALL PRE-COMMIT VALIDATIONS PASSED"
-exit 0
+#!/usr/bin/env bash
+# Scope: universal | Orchestrates framework + stack-specific pre-commit hooks
+# MORPH-SPEC Master Pre-Commit Hook
+# Runs universal framework hooks + stack-specific hooks in sequence
+
+echo "╔════════════════════════════════════════════════╗"
+echo "║     MORPH-SPEC PRE-COMMIT VALIDATION           ║"
+echo "╚════════════════════════════════════════════════╝"
+echo ""
+
+FRAMEWORK_HOOKS_DIR="$(dirname "$0")"
+STACK_HOOKS_DIR=".morph/hooks/pre-commit"
+
+HAS_FAILURES=false
+
+# Run framework hooks (universal - all stacks)
+echo "📦 Running framework hooks (universal)..."
+for hook in "$FRAMEWORK_HOOKS_DIR"/*.sh; do
+  # Skip orchestrator itself
+  if [[ "$hook" == */orchestrator.sh ]]; then
+    continue
+  fi
+
+  if [[ -f "$hook" ]]; then
+    hook_name=$(basename "$hook")
+    echo "─────────────────────────────────────────────────"
+    if ! bash "$hook"; then
+      HAS_FAILURES=true
+      echo "❌ Framework hook failed: $hook_name"
+    fi
+    echo ""
+  fi
+done
+
+# Run stack-specific hooks (if exist)
+if [[ -d "$STACK_HOOKS_DIR" ]]; then
+  echo "🎯 Running stack-specific hooks..."
+  for hook in "$STACK_HOOKS_DIR"/*.sh; do
+    if [[ -f "$hook" ]]; then
+      hook_name=$(basename "$hook")
+      echo "─────────────────────────────────────────────────"
+      if ! bash "$hook"; then
+        HAS_FAILURES=true
+        echo "❌ Stack hook failed: $hook_name"
+      fi
+      echo ""
+    fi
+  done
+else
+  echo "ℹ️  No stack-specific hooks found (optional)"
+  echo ""
+fi
+
+echo "═════════════════════════════════════════════════"
+
+if [[ "$HAS_FAILURES" == "true" ]]; then
+  echo "❌ PRE-COMMIT VALIDATION FAILED"
+  echo "   Fix errors above before committing"
+  echo "   Or use: git commit --no-verify to skip"
+  exit 1
+fi
+
+echo "✅ ALL PRE-COMMIT VALIDATIONS PASSED"
+exit 0

package/framework/hooks/git/pre-commit/specs.sh

@@ -1,50 +1,50 @@
-#!/bin/bash
-# Scope: universal | Validates spec.md required sections
-# MORPH-SPEC Pre-Commit Hook: Spec Validation
-# Validates that spec.md files have required sections
-
-echo "🔍 Validating spec files..."
-
-# Find modified spec.md files
-SPEC_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep 'spec\.md$')
-
-if [ -z "$SPEC_FILES" ]; then
-  echo "✓ No spec files modified"
-  exit 0
-fi
-
-HAS_ERRORS=false
-
-for spec_file in $SPEC_FILES; do
-  echo "Checking: $spec_file"
-
-  # Required sections
-  REQUIRED_SECTIONS=(
-    "## 📋 Metadata"
-    "## 🎯 Overview"
-    "## 🏗️ Technical Design"
-    "## ✅ Acceptance Criteria"
-  )
-
-  for section in "${REQUIRED_SECTIONS[@]}"; do
-    if ! grep -q "$section" "$spec_file"; then
-      echo "  ❌ Missing section: $section"
-      HAS_ERRORS=true
-    fi
-  done
-
-  # Check if has at least one user story or requirement
-  if ! grep -qi "user story\|requirement\|acceptance criteria" "$spec_file"; then
-    echo "  ⚠️  Warning: No user stories or requirements found"
-  fi
-done
-
-if [ "$HAS_ERRORS" = true ]; then
-  echo ""
-  echo "❌ COMMIT BLOCKED: spec.md files are incomplete"
-  echo "   Add missing sections before committing"
-  exit 1
-fi
-
-echo "✓ All spec files are valid"
-exit 0
+#!/bin/bash
+# Scope: universal | Validates spec.md required sections
+# MORPH-SPEC Pre-Commit Hook: Spec Validation
+# Validates that spec.md files have required sections
+
+echo "🔍 Validating spec files..."
+
+# Find modified spec.md files
+SPEC_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep 'spec\.md$')
+
+if [ -z "$SPEC_FILES" ]; then
+  echo "✓ No spec files modified"
+  exit 0
+fi
+
+HAS_ERRORS=false
+
+for spec_file in $SPEC_FILES; do
+  echo "Checking: $spec_file"
+
+  # Required sections
+  REQUIRED_SECTIONS=(
+    "## 📋 Metadata"
+    "## 🎯 Overview"
+    "## 🏗️ Technical Design"
+    "## ✅ Acceptance Criteria"
+  )
+
+  for section in "${REQUIRED_SECTIONS[@]}"; do
+    if ! grep -q "$section" "$spec_file"; then
+      echo "  ❌ Missing section: $section"
+      HAS_ERRORS=true
+    fi
+  done
+
+  # Check if has at least one user story or requirement
+  if ! grep -qi "user story\|requirement\|acceptance criteria" "$spec_file"; then
+    echo "  ⚠️  Warning: No user stories or requirements found"
+  fi
+done
+
+if [ "$HAS_ERRORS" = true ]; then
+  echo ""
+  echo "❌ COMMIT BLOCKED: spec.md files are incomplete"
+  echo "   Add missing sections before committing"
+  exit 1
+fi
+
+echo "✓ All spec files are valid"
+exit 0

package/framework/hooks/git/pre-push/run-tests.sh

@@ -1,44 +1,44 @@
-#!/usr/bin/env bash
-# Scope: universal | Runs test suite before push
-# MORPH-SPEC Pre-Push Hook
-# Ensures all tests pass before pushing to remote
-
-echo "🧪 Running test suite before push..."
-echo ""
-
-# Detect project type and run appropriate tests
-if [[ -f *.csproj ]] || find . -maxdepth 2 -name "*.csproj" 2>/dev/null | grep -q .; then
-  # .NET project detected
-  echo "📦 Detected .NET project"
-
-  if ! dotnet test --verbosity minimal --no-build --no-restore 2>/dev/null; then
-    echo ""
-    echo "❌ .NET tests failed!"
-    echo ""
-    echo "Fix failing tests before pushing."
-    echo "Override with: git push --no-verify"
-    exit 1
-  fi
-
-elif [[ -f package.json ]]; then
-  # Node.js project detected
-  echo "📦 Detected Node.js project"
-
-  if ! npm test 2>/dev/null; then
-    echo ""
-    echo "❌ Node.js tests failed!"
-    echo ""
-    echo "Fix failing tests before pushing."
-    echo "Override with: git push --no-verify"
-    exit 1
-  fi
-
-else
-  echo "⚠️  No recognized test framework found"
-  echo "   Skipping test execution"
-  exit 0
-fi
-
-echo ""
-echo "✅ All tests passed - safe to push"
-exit 0
+#!/usr/bin/env bash
+# Scope: universal | Runs test suite before push
+# MORPH-SPEC Pre-Push Hook
+# Ensures all tests pass before pushing to remote
+
+echo "🧪 Running test suite before push..."
+echo ""
+
+# Detect project type and run appropriate tests
+if [[ -f *.csproj ]] || find . -maxdepth 2 -name "*.csproj" 2>/dev/null | grep -q .; then
+  # .NET project detected
+  echo "📦 Detected .NET project"
+
+  if ! dotnet test --verbosity minimal --no-build --no-restore 2>/dev/null; then
+    echo ""
+    echo "❌ .NET tests failed!"
+    echo ""
+    echo "Fix failing tests before pushing."
+    echo "Override with: git push --no-verify"
+    exit 1
+  fi
+
+elif [[ -f package.json ]]; then
+  # Node.js project detected
+  echo "📦 Detected Node.js project"
+
+  if ! npm test 2>/dev/null; then
+    echo ""
+    echo "❌ Node.js tests failed!"
+    echo ""
+    echo "Fix failing tests before pushing."
+    echo "Override with: git push --no-verify"
+    exit 1
+  fi
+
+else
+  echo "⚠️  No recognized test framework found"
+  echo "   Skipping test execution"
+  exit 0
+fi
+
+echo ""
+echo "✅ All tests passed - safe to push"
+exit 0

package/framework/hooks/shared/phase-utils.js

@@ -32,6 +32,7 @@ export const OUTPUT_PHASE_MAP = {
   mandate: 'plan',
   tasks: 'plan',
   decisions: 'plan',
+  reuseMap: 'plan',
   usecases: 'plan',
   recap: 'implement',
   reviewReport: 'review',
@@ -50,6 +51,7 @@ export const FILENAME_TO_OUTPUT = {
   'mandate.md': 'mandate',
   'tasks.json': 'tasks',
   'decisions.md': 'decisions',
+  'reuse-map.md': 'reuseMap',
   'recap.md': 'recap',
   'review-report.md': 'reviewReport',
   'evaluator-report.md': 'evaluatorReport',

package/framework/hooks/shared/stdin-reader.js

@@ -1,26 +1,26 @@
-/**
- * Shared stdin reader for Claude Code hooks.
- *
- * Reads JSON payload from stdin (provided by Claude Code to hooks).
- * Returns parsed object or null on failure.
- */
-
-/**
- * Read and parse JSON from stdin
- * @returns {Promise<Object|null>} Parsed JSON or null
- */
-export function readStdin() {
-  return new Promise((resolve) => {
-    let input = '';
-    process.stdin.setEncoding('utf-8');
-    process.stdin.on('data', (chunk) => { input += chunk; });
-    process.stdin.on('end', () => {
-      try {
-        resolve(JSON.parse(input || '{}'));
-      } catch {
-        resolve(null);
-      }
-    });
-    process.stdin.on('error', () => resolve(null));
-  });
-}
+/**
+ * Shared stdin reader for Claude Code hooks.
+ *
+ * Reads JSON payload from stdin (provided by Claude Code to hooks).
+ * Returns parsed object or null on failure.
+ */
+
+/**
+ * Read and parse JSON from stdin
+ * @returns {Promise<Object|null>} Parsed JSON or null
+ */
+export function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input || '{}'));
+      } catch {
+        resolve(null);
+      }
+    });
+    process.stdin.on('error', () => resolve(null));
+  });
+}

package/framework/mcp/registry.json

@@ -250,14 +250,49 @@
         ],
         "setupGuide": "1. Get a token at https://replicate.com/account/api-tokens\n2. Build the MCP: cd $MORPH_HUB/mcps/seedance && npm install && npm run build\n3. Run: claude mcp add seedance -e REPLICATE_API_TOKEN=<token> -- node $MORPH_HUB/mcps/seedance/dist/index.js\n4. Verify with list_videos (reads local history, spends no credits)"
       }
+    },
+    "graphify": {
+      "phases": ["proposal", "plan", "implement", "review"],
+      "tools": ["query_graph", "get_node", "get_neighbors", "get_community", "god_nodes", "graph_stats", "shortest_path", "list_prs", "get_pr_impact", "triage_prs"],
+      "detection": "graphify-out/graph.json exists in the project root (written by morph-spec graph build, or by the graphify post-commit hook)",
+      "fallback": "Comportamento atual: Grep/Glob/Read. O grafo é um subconjunto estrito do grep — no eval não encontrou um único arquivo que o grep perderia — então cair para grep não perde recall, só devolve mais ruído",
+      "usage": "Blast radius, vizinhança de símbolo e god nodes sem gastar token de leitura. PREFIRA `morph-spec graph explain|affected`, que aplica o saneamento da ADR-003 (coalesce de stub, classificação de órfão) que este servidor NÃO aplica — em C# o grafo cru produz falso negativo silencioso. O MCP serve para exploração interativa e para consulta cross-repo: as 10 tools aceitam project_path, então uma instância serve vários repositórios",
+      "healthCheck": {
+        "toolPattern": "graphify",
+        "testCall": "Call graph_stats with no arguments (uses the current project)",
+        "testParams": {},
+        "successIndicator": "Returns node and edge counts for the project graph",
+        "failureHint": "graphify-mcp não respondeu. Confirme com `graphify --version` (pinado: 0.9.50) e com `morph-spec graph status`. Se o graph.json não existir, rode `morph-spec graph build` — sem grafo o servidor não tem o que servir."
+      },
+      "install": {
+        "autoInstall": false,
+        "transport": "stdio",
+        "config": {
+          "type": "stdio",
+          "command": "graphify-mcp",
+          "args": []
+        },
+        "credentials": [],
+        "prerequisites": [
+          "graphify 0.9.50 instalado (o step 18b do setup-infra faz isso via uv/pipx/pip)",
+          "graphify-out/graph.json gerado — morph-spec graph build"
+        ],
+        "stackRelevance": ["*"],
+        "warnings": [
+          "O binário é `graphify-mcp`. `python -m graphify.serve`, que é o comando do README oficial, FALHA com `uv tool install`: o pacote vive num venv isolado e o Python do sistema não o enxerga.",
+          "Quem instala e pina o graphify é o step 18b do setup-infra, não este registro — por isso autoInstall é false.",
+          "As respostas deste servidor são o grafo CRU, sem o saneamento do `morph-spec graph`. Em C#, blast radius cru pode devolver zero consumidores onde existem dois."
+        ],
+        "setupGuide": null
+      }
     }
   },
   "_phaseMatrixNote": "Keys must be the v5 phases from framework/phases.json. The v4 keys 'design' and 'tasks' both collapsed into 'plan'; 'review' was absent entirely, so a project in review resolved to undefined. Stack-scoped MCPs (asaas) stay out of this matrix on purpose — only universal ones are listed.",
   "phaseMatrix": {
-    "proposal": ["context7"],
+    "proposal": ["context7", "graphify"],
     "uiux": ["playwright", "context7", "stitch", "gemini-image", "seedance"],
-    "plan": ["context7"],
-    "implement": ["context7", "playwright", "vercel", "gemini-image", "seedance"],
-    "review": ["playwright", "context7"]
+    "plan": ["context7", "graphify"],
+    "implement": ["context7", "playwright", "vercel", "gemini-image", "seedance", "graphify"],
+    "review": ["playwright", "context7", "graphify"]
   }
 }

package/framework/rubrics/backend.json

@@ -10,8 +10,8 @@
     },
     "code_quality": {
       "weight": 0.25,
-      "validators": ["architecture"],
-      "description": "Architecture patterns, dependency direction, and code structure"
+      "validators": ["architecture", "reuse"],
+      "description": "Architecture patterns, dependency direction, code structure, and reuse of what the codebase already has"
     },
     "design_ui": {
       "weight": 0.05,

package/framework/rubrics/default.json

@@ -10,8 +10,8 @@
     },
     "code_quality": {
       "weight": 0.25,
-      "validators": ["architecture"],
-      "description": "Architecture patterns and code structure"
+      "validators": ["architecture", "reuse"],
+      "description": "Architecture patterns, code structure, and reuse of what the codebase already has"
     },
     "design_ui": {
       "weight": 0.15,

package/framework/rubrics/frontend.json

@@ -10,8 +10,8 @@
     },
     "code_quality": {
       "weight": 0.15,
-      "validators": ["architecture"],
-      "description": "Architecture patterns and code structure"
+      "validators": ["architecture", "reuse"],
+      "description": "Architecture patterns, code structure, and reuse of what the codebase already has"
     },
     "design_ui": {
       "weight": 0.35,

package/framework/schemas/tasks.schema.json

@@ -36,6 +36,31 @@
             "minLength": 1,
             "description": "Persona id assigned by morph-plan for this task — the bare framework/agents.json id, no 'morph-' prefix (e.g. \"dotnet-senior\"). Optional. Part of the plan contract: frozen after Gate 2."
           },
+          "reuse": {
+            "type": "array",
+            "description": "Veredito de reuso por conceito que ESTA task introduz, carimbado por morph-plan a partir do 2-plan/reuse-map.md. Optional. Part of the plan contract: frozen after Gate 2. A justificativa de um CRIAR mora no reuse-map.md, nunca aqui — duas verdades do mesmo fato divergem.",
+            "items": {
+              "type": "object",
+              "required": ["concept", "verdict"],
+              "properties": {
+                "concept": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Nome do conceito/símbolo, como ele aparecerá no código (ex.: \"SimpleBuilding\")."
+                },
+                "verdict": {
+                  "type": "string",
+                  "enum": ["REUSAR", "ESTENDER", "CRIAR"],
+                  "description": "REUSAR: usar o que existe. ESTENDER: partir do que existe. CRIAR: nada cobre o caso — exige justificativa de uma linha no reuse-map.md."
+                },
+                "target": {
+                  "type": "string",
+                  "description": "Path (ou path:símbolo) do que será reusado/estendido. Vazio ou ausente em CRIAR."
+                }
+              },
+              "additionalProperties": false
+            }
+          },
           "standards": {
             "type": "array",
             "items": { "type": "string", "minLength": 1 },

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

@@ -4,7 +4,7 @@ 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.29.0"
+cliVersion: "8.32.0"
 stacks:
   - umbraco
 ---

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

@@ -4,7 +4,7 @@ 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.29.0"
+cliVersion: "8.32.0"
 stacks:
   - 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.29.0"
+cliVersion: "8.32.0"
 ---
 
 # morph-apply
@@ -143,11 +143,20 @@ while (true):
 
 ```
 dispatch Agent (subagent_type: "morph-{id}") with prompt:
-  contexto: spec.md, mandate.md, task description completa, doneCriteria
+  contexto: spec.md, mandate.md, task description completa, doneCriteria,
+            task.reuse (veredito REUSAR/ESTENDER/CRIAR por conceito) e os paths
+            dos alvos de reuso
   standard: <path(s) .md do(s) standard(s) do domínio — leia-o(s) antes de implementar>
   instrução: |
     Leia o(s) standard(s) indicado(s) antes de escrever código.
-    Implemente esta task (ou cadeia de tasks do fluxo) isoladamente.
+    Implemente esta task (ou cadeia de tasks do fluxo) sem depender do trabalho
+    dos outros agentes deste batch: seu ISOLAMENTO é de ESTADO e de ÁRVORE DE
+    TRABALHO — nunca de conhecimento do codebase. Antes de criar tipo,
+    componente, hook ou serviço NOVO, verifique se já existe: `morph-spec graph
+    explain <nome>` e `graph affected <conceito> --uses-only`; sem grafo
+    (`no-graph`), caia para `grep -rn "<nome>"` e siga — a ausência de grafo
+    nunca bloqueia. Se algo cobre o caso, reuse ou estenda; se criar mesmo
+    assim, diga por que em uma linha no relatório.
     Não modifique spec.md, mandate.md.
 
     Contrato do relatório final:
@@ -219,6 +228,7 @@ re-apresente o gate**: siga direto para o encerramento (§6) conforme a decisão
 
 - 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.
+- **`--pr` não encerra a feature; quem encerra é o merge.** O comando arquiva e termina (`finished: true`) nos dois modos, mas só `--merge` integra na hora (`integrated: true`); `--pr` sai com `integrated: false`, `awaiting: "merge"` e `pr: {number, url}` — o archive viaja no diff do PR e só chega na branch default quando alguém mergeia. Até lá a feature aparece em `morph-spec list`/`fleet` como `aguardando-merge`, sem cópia local. Nunca registre a feature como entregue só porque `finish --pr` retornou `finished: true`.
 
 ## Anti-padrões
 
@@ -236,7 +246,7 @@ re-apresente o gate**: siga direto para o encerramento (§6) conforme a decisão
 - `.morph/features/{feature}/3-implement/recap.md` produzido por morph-implement.
 - `.morph/features/{feature}/4-review/review-report.md` produzido por morph-review.
 - Gate 3 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo) — via `morph-spec approve` em auto, ou pelo hook state-sync no caminho manual.
-- Feature com Gate 3 aprovado e **fechada** por `morph-spec finish --pr|--merge` (arquiva carimbando `status: "completed"` + `archivedAt`, integra e desmonta num passo) — ou, se legada, por `morph-spec archive`.
+- Feature com Gate 3 aprovado e **fechada** por `morph-spec finish --pr|--merge` (arquiva carimbando `status: "completed"` + `archivedAt` e desmonta num passo; `--merge` integra na hora, `--pr` só abre o PR — `aguardando-merge` até o merge) — ou, se legada, por `morph-spec archive`.
 
 ## Referências
 

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.29.0"
+cliVersion: "8.32.0"
 ---
 
 # morph-brainstorming