@polymorphism-tech/morph-spec 8.28.0 → 8.31.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

@@ -176,15 +176,15 @@
         "testCall": "Call get_configuration_status to verify API key and server health",
         "testParams": {},
         "successIndicator": "Returns status with valid API key configured",
-        "failureHint": "Gemini Image MCP not responding. Ensure GEMINI_API_KEY is set in MCP server configuration. Install: npx gemini-image-mcp@latest"
+        "failureHint": "Gemini Image MCP not responding. Check that GEMINI_API_KEY is set in the MCP env config and that MORPH_HUB points at a built morph-HUB checkout."
       },
       "install": {
         "autoInstall": false,
         "transport": "stdio",
         "config": {
           "type": "stdio",
-          "command": "cmd",
-          "args": ["/c", "npx", "-y", "gemini-image-mcp@latest"]
+          "command": "node",
+          "args": ["${MORPH_HUB}/mcps/gemini-image/dist/index.js"]
         },
         "credentials": [
           {
@@ -194,19 +194,105 @@
             "helpUrl": "https://aistudio.google.com/apikey"
           }
         ],
-        "prerequisites": ["Google AI Studio API key"],
+        "prerequisites": [
+          "Google AI Studio API key",
+          "Local morph-HUB checkout with mcps/gemini-image built, exposed via the MORPH_HUB env var"
+        ],
         "stackRelevance": ["nextjs", "next"],
-        "warnings": ["Requires GEMINI_API_KEY environment variable. Image generation costs apply per Google AI pricing."],
-        "setupGuide": "1. Get API key from https://aistudio.google.com/apikey\n2. Run: claude mcp add gemini-image-mcp -- npx gemini-image-mcp@latest\n3. Set GEMINI_API_KEY in MCP env config"
+        "warnings": [
+          "Internal Polymorphism MCP, not published to npm. The public gemini-image-mcp package was unpublished in 2025-04, so npx installs no longer work.",
+          "Requires GEMINI_API_KEY environment variable. Image generation costs apply per Google AI pricing."
+        ],
+        "setupGuide": "1. Get an API key at https://aistudio.google.com/apikey\n2. Build the MCP: cd $MORPH_HUB/mcps/gemini-image && npm install && npm run build\n3. Run: claude mcp add gemini-image-mcp -e GEMINI_API_KEY=<key> -- node $MORPH_HUB/mcps/gemini-image/dist/index.js\n4. Verify with get_configuration_status"
+      }
+    },
+    "seedance": {
+      "phases": ["uiux", "implement"],
+      "tools": ["generate_video", "generate_loop_video", "get_video", "list_videos"],
+      "detection": "mcpServers includes seedance",
+      "fallback": "Use client-provided footage or a static poster image; canvas frame-scrub works from any frame sequence, AI-generated or not",
+      "usage": "AI video generation for scroll-driven heroes and ambient backgrounds. generate_video with endImage produces the directional footage that frame-scrub needs (start frame differs from end frame); generate_loop_video is only for seamless ambient loops",
+      "healthCheck": {
+        "toolPattern": "seedance",
+        "testCall": "Call list_videos with limit 1 to verify the server responds (reads local history, spends no credits)",
+        "testParams": {
+          "limit": 1
+        },
+        "successIndicator": "Returns the local job history, or 'No videos in history yet'",
+        "failureHint": "Seedance MCP not responding. Check that REPLICATE_API_TOKEN is set in the MCP env config and that MORPH_HUB points at a built morph-HUB checkout."
+      },
+      "install": {
+        "autoInstall": false,
+        "transport": "stdio",
+        "config": {
+          "type": "stdio",
+          "command": "node",
+          "args": ["${MORPH_HUB}/mcps/seedance/dist/index.js"]
+        },
+        "credentials": [
+          {
+            "name": "Replicate API Token",
+            "envVar": "REPLICATE_API_TOKEN",
+            "secret": true,
+            "helpUrl": "https://replicate.com/account/api-tokens"
+          }
+        ],
+        "prerequisites": [
+          "Replicate account with billing enabled",
+          "Local morph-HUB checkout with mcps/seedance built, exposed via the MORPH_HUB env var",
+          "ffmpeg on PATH to extract frames for scroll-scrubbing"
+        ],
+        "stackRelevance": ["next", "react", "vite", "astro"],
+        "warnings": [
+          "Internal Polymorphism MCP, not published to npm. Requires a local morph-HUB checkout.",
+          "Paid per generation. Draft at fast/480p/4s first, render 1080p only after the take is approved.",
+          "Generation is stochastic and needs a human approval gate. Do not wire it into an unattended phase."
+        ],
+        "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"],
-    "uiux": ["playwright", "context7", "stitch", "gemini-image"],
-    "plan": ["context7"],
-    "implement": ["context7", "playwright", "vercel", "gemini-image"],
-    "review": ["playwright", "context7"]
+    "proposal": ["context7", "graphify"],
+    "uiux": ["playwright", "context7", "stitch", "gemini-image", "seedance"],
+    "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.28.0"
+cliVersion: "8.31.0"
 stacks:
   - umbraco
 ---
@@ -199,6 +199,17 @@ Edite `frontend/src/app/globals.css`. As variáveis CSS de base do tema são def
 
 Para tipografias customizadas, importe via `next/font` em `frontend/src/app/layout.tsx` e exponha como variável CSS.
 
+> **Se a LP nasce cinematográfica (scroll-driven):** o template não traz `gsap` nem `lenis`; adicione ao
+> `frontend/package.json` e monte o runtime de motion como componente `'use client'` montado uma vez na
+> page, com guard de SSR no registro do ScrollTrigger. O conhecimento está nos standards
+> `frontend/scroll-driven/smooth-scroll.md` (wiring Lenis com o ticker do GSAP, `window.__lenis`,
+> armadilha de HMR), `frame-scrub.md` (canvas quadro a quadro, extração ffmpeg, poster no mobile) e
+> `scroll-components.md` (pin, modal, parallax, reveal). Regra de assets que vale desde o primeiro dia:
+> **sequência de frames é asset estrutural em `frontend/public/` com cache-bust `?v=N` manual, e só o
+> poster vira mídia editável no backoffice.** Frames na Media Library perdem o webp (o ImageSharp do
+> Umbraco 17 exige URL assinada por HMAC, não relaxável por config) e viram 145 requests assinadas
+> por visitante.
+
 **4.2 — Módulos disponíveis (Content Types *Section):**
 
 O template já inclui os seguintes módulos versionados em `backend/uSync/v17/ContentTypes/`:
@@ -268,7 +279,7 @@ Antes de fazer deploy ou entregar o projeto ao cliente:
 ## Referências
 
 - `polymorphism-tech/MORPH_Umbraco_LP_Template` (privado, branch `master`) — template canônico: `scripts/new-lp.ps1`, `scripts/new-lp.sh`, `backend/Infrastructure/SeedContentHandler.cs`, `backend/Controllers/LeadController.cs`, `backend/uSync/v17/`.
-- `docs/umbraco-lp-patterns.md` (em `main` neste repo) — padrões e gotchas detalhados: controller público (seção 1), DI multi-sink (seção 2), leitura server-side de config oculta (seção 3), segurança Delivery API (seção 4), uSync config-as-code (seção 5), dropdown gotcha (seção 6), seed idempotente (seção 7), endpoint Ping (seção 10), skip silencioso em dev (seção 11), build Next.js exige backend (seção 12).
+- `references/umbraco-lp-patterns.md` (carregue sob demanda) — padrões e gotchas detalhados: controller público (seção 1), DI multi-sink (seção 2), leitura server-side de config oculta (seção 3), segurança Delivery API (seção 4), uSync config-as-code (seção 5), dropdown gotcha (seção 6), seed idempotente (seção 7), endpoint Ping (seção 10), skip silencioso em dev (seção 11), build Next.js exige backend (seção 12).
 - `backend/appsettings.json` — `Umbraco:CMS:DeliveryApi:DisallowedContentTypeAliases` e `uSync:Settings:ImportAtStartup`.
 - `backend/Properties/launchSettings.json` — portas de dev: HTTP `:19223`, HTTPS `:44324`.
 - `docker-compose.yml` — orquestração de produção (backend porta `5001`, frontend `3000`).