@polymorphism-tech/morph-spec 4.3.2 → 4.3.4

package/framework/hooks/agent-teams/phase-advanced.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Scope: universal | Validates feature outputs when phase is advanced
+// MORPH-SPEC Agent Teams Hook: PhaseAdvanced Event
+
+import { executeHook, formatHookResults } from '../../../src/lib/hooks/hook-executor.js';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Parse arguments
+const args = process.argv.slice(2);
+const [featureName, fromPhase, toPhase] = args.filter(arg => !arg.startsWith('--'));
+
+if (!featureName || !fromPhase || !toPhase) {
+  console.error('Usage: phase-advanced.js <feature> <from-phase> <to-phase> [--dry-run] [--verbose]');
+  console.error('');
+  console.error('Example:');
+  console.error('  node phase-advanced.js user-auth design clarify');
+  process.exit(2);
+}
+
+const dryRun = args.includes('--dry-run');
+const verbose = args.includes('--verbose');
+
+// Project path is 3 levels up from framework/hooks/agent-teams/
+const projectPath = join(__dirname, '../../..');
+
+async function main() {
+  if (verbose) {
+    console.log(`🔍 PhaseAdvanced Hook triggered:`);
+    console.log(`   Feature: ${featureName}`);
+    console.log(`   Transition: ${fromPhase} → ${toPhase}`);
+    console.log(`   Mode: ${dryRun ? 'DRY RUN' : 'LIVE'}`);
+    console.log('');
+  }
+
+  try {
+    const results = await executeHook(projectPath, featureName, 'PhaseAdvanced', {
+      fromPhase,
+      toPhase,
+      dryRun,
+      verbose
+    });
+
+    const output = formatHookResults(results, 'PhaseAdvanced');
+    console.log(output);
+
+    if (results.blocked) {
+      console.error('');
+      console.error('❌ Cannot advance phase - fix errors above');
+      console.error('');
+      console.error('To override (not recommended):');
+      console.error(`  npx morph-spec advance-phase ${featureName} ${toPhase} --skip-validation`);
+      process.exit(1);
+    }
+
+    if (verbose) {
+      console.log('');
+      console.log('✅ Phase advancement validated successfully');
+    }
+
+    process.exit(0);
+  } catch (error) {
+    console.error('');
+    console.error('❌ Hook execution failed:');
+    console.error(`   ${error.message}`);
+
+    if (verbose && error.stack) {
+      console.error('');
+      console.error('Stack trace:');
+      console.error(error.stack);
+    }
+
+    process.exit(1);
+  }
+}
+
+main();

package/framework/hooks/agent-teams/task-completed.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+// Scope: universal | Task completion validation
+
+/**
+ * TaskCompleted Hook - Claude Code Agent Teams
+ *
+ * Triggered when a task is marked as completed.
+ * Validates the task deliverables before allowing the task to be marked done.
+ *
+ * Usage (from Claude Code hooks):
+ *   task-completed.js <feature-name> <task-id> [--dry-run] [--verbose]
+ *
+ * Exit codes:
+ *   0 - All validators passed
+ *   1 - Validation failed and blocked
+ *   2 - Configuration error
+ */
+
+import { executeHook, formatHookResults } from '../../../src/lib/hooks/hook-executor.js';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Get project root (3 levels up from framework/hooks/agent-teams/)
+const projectPath = join(__dirname, '../../..');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    console.error('Usage: task-completed.js <feature-name> <task-id> [--dry-run] [--verbose]');
+    process.exit(2);
+  }
+
+  const featureName = args[0];
+  const taskId = args[1];
+  const dryRun = args.includes('--dry-run');
+  const verbose = args.includes('--verbose');
+
+  console.log('🔔 TaskCompleted Hook Triggered');
+  console.log(`   Feature: ${featureName}`);
+  console.log(`   Task: ${taskId}`);
+  console.log(`   Event: Task marked complete, validating deliverables...\n`);
+
+  try {
+    const results = await executeHook(projectPath, featureName, 'TaskCompleted', {
+      dryRun,
+      verbose,
+      taskId
+    });
+
+    const output = formatHookResults(results, 'TaskCompleted');
+    console.log(output);
+
+    if (results.blocked) {
+      console.log('\n💡 TIP: Fix the errors above before the task can be marked complete.');
+      console.log(`   Run: morph-spec task done ${featureName} ${taskId} --skip-validation`);
+      console.log('   (Not recommended - only use if you know what you\'re doing)');
+      process.exit(1);
+    }
+
+    console.log('\n✅ Task deliverables validated successfully.');
+    process.exit(0);
+  } catch (err) {
+    console.error(`\n❌ Hook execution error: ${err.message}`);
+    if (verbose) {
+      console.error(err.stack);
+    }
+    process.exit(2);
+  }
+}
+
+main();

package/framework/hooks/agent-teams/teammate-idle.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+// Scope: universal | Agent Teams idle event validation
+
+/**
+ * TeammateIdle Hook - Claude Code Agent Teams
+ *
+ * Triggered when a teammate is idle and waiting for next instructions.
+ * Validates the teammate's recent work before allowing them to proceed.
+ *
+ * Usage (from Claude Code hooks):
+ *   teammate-idle.js <feature-name> [--dry-run] [--verbose]
+ *
+ * Exit codes:
+ *   0 - All validators passed
+ *   1 - Validation failed and blocked
+ *   2 - Configuration error
+ */
+
+import { executeHook, formatHookResults } from '../../../src/lib/hooks/hook-executor.js';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Get project root (3 levels up from framework/hooks/agent-teams/)
+const projectPath = join(__dirname, '../../..');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error('Usage: teammate-idle.js <feature-name> [--dry-run] [--verbose]');
+    process.exit(2);
+  }
+
+  const featureName = args[0];
+  const dryRun = args.includes('--dry-run');
+  const verbose = args.includes('--verbose');
+
+  console.log('🔔 TeammateIdle Hook Triggered');
+  console.log(`   Feature: ${featureName}`);
+  console.log(`   Event: Teammate is idle, validating recent work...\n`);
+
+  try {
+    const results = await executeHook(projectPath, featureName, 'TeammateIdle', {
+      dryRun,
+      verbose
+    });
+
+    const output = formatHookResults(results, 'TeammateIdle');
+    console.log(output);
+
+    if (results.blocked) {
+      console.log('\n💡 TIP: Fix the errors above before the teammate can proceed.');
+      process.exit(1);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    console.error(`\n❌ Hook execution error: ${err.message}`);
+    if (verbose) {
+      console.error(err.stack);
+    }
+    process.exit(2);
+  }
+}
+
+main();

package/framework/hooks/commit-msg/conventional-commits.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Scope: universal | Validates commit message format (Conventional Commits)
+# MORPH-SPEC Commit Message Hook
+# Enforces Conventional Commits specification
+
+COMMIT_MSG_FILE="$1"
+COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+
+# Conventional Commits pattern: type(scope): description
+# Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert
+PATTERN="^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\(.+\))?: .{1,100}"
+
+if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
+  echo "❌ Invalid commit message format!"
+  echo ""
+  echo "Required format: <type>(<scope>): <description>"
+  echo ""
+  echo "Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert"
+  echo ""
+  echo "Examples:"
+  echo "  feat(auth): add JWT refresh token rotation"
+  echo "  fix(api): resolve null reference in UserService"
+  echo "  docs(readme): update installation instructions"
+  echo ""
+  echo "Your message:"
+  echo "  $COMMIT_MSG"
+  echo ""
+  echo "Override with: git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Commit message format valid"
+exit 0

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

@@ -0,0 +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 ! npx 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/pre-commit/orchestrator.sh

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +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

package/framework/index/troubleshooting-index.json

@@ -0,0 +1,184 @@
+{
+  "version": "1.0.0",
+  "lastUpdated": "2025-01-25",
+  "problems": [
+    {
+      "id": "efcore-pending-changes",
+      "title": "PendingModelChangesWarning no EF Core 10",
+      "keywords": ["PendingModelChanges", "migration", "EF Core", "database update", "pending", "model changed"],
+      "errorPattern": "PendingModelChangesException|pending changes|model.*has pending changes",
+      "file": "framework/standards/backend/database/ef-core.md",
+      "section": "Migrations - .NET 10 PendingModelChangesWarning",
+      "severity": "critical",
+      "scope": "blazor-azure,nextjs-supabase",
+      "category": "efcore",
+      "cause": "EF Core 10 lança exceção se modelo mudou desde última migration.",
+      "solution": "dotnet ef migrations add <Name> antes de database update"
+    },
+    {
+      "id": "dbcontext-concurrent",
+      "title": "DbContext Concurrency Error",
+      "keywords": ["DbContext", "concurrent", "second operation", "Task.Run", "background", "thread"],
+      "errorPattern": "A second operation was started|concurrently using the same instance",
+      "file": "framework/standards/backend/database/ef-core.md",
+      "section": "The Problem: DbContext Concurrency",
+      "severity": "critical",
+      "scope": "blazor-azure,nextjs-supabase",
+      "category": "efcore",
+      "cause": "DbContext scoped está sendo usado em operações paralelas/background.",
+      "solution": "Usar IDbContextFactory para operações em background"
+    },
+    {
+      "id": "navigation-include-empty",
+      "title": "Include() retorna coleção vazia",
+      "keywords": ["Include", "HasMany", "navigation", "empty", "vazia", "collection", "ICollection"],
+      "errorPattern": "Items\\.Count == 0|collection.*empty|Include.*not working",
+      "file": "framework/standards/backend/database/ef-core.md",
+      "section": "Navigation Properties - Correct Configuration",
+      "severity": "high",
+      "scope": "blazor-azure,nextjs-supabase",
+      "category": "efcore",
+      "cause": "HasMany<T>() sem navigation property causa Include() falhar silenciosamente.",
+      "solution": "Usar HasMany(x => x.Property) em vez de HasMany<T>()"
+    },
+    {
+      "id": "azure-identity-conflict",
+      "title": "Azure.Identity Version Conflict",
+      "keywords": ["Azure.Identity", "NU1605", "downgrade", "version", "conflict", "package"],
+      "errorPattern": "NU1605.*Azure\\.Identity|package downgrade.*Azure\\.Identity",
+      "file": "framework/standards/infrastructure/azure/azure.md",
+      "section": "Package Version Conflicts",
+      "severity": "high",
+      "scope": "blazor-azure",
+      "category": "azure",
+      "cause": "Dependências transitivas puxam versões diferentes do Azure.Identity.",
+      "solution": "<PackageReference Include=\"Azure.Identity\" Version=\"1.14.2\" />"
+    },
+    {
+      "id": "keyvault-di-fail",
+      "title": "Key Vault não carrega em Development",
+      "keywords": ["KeyVault", "IsDevelopment", "DI", "secrets", "not registered", "service"],
+      "errorPattern": "IBlobStorageService.*not registered|IPaymentService.*not registered|service.*not registered",
+      "file": "framework/standards/infrastructure/azure/azure.md",
+      "section": "Key Vault Configuration",
+      "severity": "critical",
+      "scope": "blazor-azure",
+      "category": "azure",
+      "cause": "Key Vault condicionado ao ambiente (!IsDevelopment) não carrega secrets.",
+      "solution": "Não condicionar Key Vault ao ambiente - carregar sempre que URI existir"
+    },
+    {
+      "id": "credential-slow",
+      "title": "DefaultAzureCredential lento no container",
+      "keywords": ["DefaultAzureCredential", "slow", "timeout", "container", "startup", "30 seconds"],
+      "errorPattern": "timeout|30 seconds|startup.*slow|credential.*timeout",
+      "file": "framework/standards/infrastructure/azure/azure.md",
+      "section": "DefaultAzureCredential Optimization",
+      "severity": "medium",
+      "scope": "blazor-azure",
+      "category": "azure",
+      "cause": "DefaultAzureCredential tenta múltiplos métodos de autenticação sequencialmente.",
+      "solution": "Desabilitar credenciais não usadas com ExcludeXxxCredential = true"
+    },
+    {
+      "id": "containerapp-not-updating",
+      "title": "Container App não atualiza após push",
+      "keywords": ["Container App", "revision", "not updating", "old version", "push", "deploy"],
+      "errorPattern": "old version|not updating|same image",
+      "file": "framework/standards/infrastructure/azure/azure.md",
+      "section": "Container App Deployment Issues",
+      "severity": "medium",
+      "scope": "blazor-azure",
+      "category": "azure",
+      "cause": "Mesmo digest de imagem não triggera nova revisão.",
+      "solution": "Usar DEPLOY_TIMESTAMP=$(date +%s) para forçar nova revisão"
+    },
+    {
+      "id": "migrations-not-applied",
+      "title": "Invalid object name - Tabela não existe",
+      "keywords": ["Invalid object name", "table", "migration", "not applied", "database"],
+      "errorPattern": "Invalid object name|table.*does not exist|object.*not found",
+      "file": "framework/standards/backend/database/ef-core.md",
+      "section": "Auto-Migration on Startup",
+      "severity": "high",
+      "scope": "blazor-azure,nextjs-supabase",
+      "category": "efcore",
+      "cause": "Migrations não foram aplicadas ao banco de dados.",
+      "solution": "Rodar dotnet ef database update ou adicionar auto-migration no startup"
+    },
+    {
+      "id": "di-httpcontext",
+      "title": "HttpContext null em background thread",
+      "keywords": ["HttpContext", "null", "background", "Task.Run", "accessor"],
+      "errorPattern": "HttpContext.*null|IHttpContextAccessor.*null",
+      "file": "framework/standards/frontend/blazor/pitfalls.md",
+      "section": "Dependency Injection Pattern",
+      "severity": "critical",
+      "scope": "blazor-azure",
+      "category": "blazor",
+      "cause": "HttpContext não está disponível em threads background.",
+      "solution": "Capturar dados do HttpContext antes de iniciar Task.Run"
+    },
+    {
+      "id": "jsruntime-prerender",
+      "title": "JSRuntime error during prerendering",
+      "keywords": ["JSRuntime", "prerender", "JavaScript", "interop", "OnInitializedAsync"],
+      "errorPattern": "JavaScript interop.*prerendering|JSRuntime.*not available",
+      "file": "framework/standards/frontend/blazor/pitfalls.md",
+      "section": "JSRuntime Lifecycle",
+      "severity": "high",
+      "scope": "blazor-azure",
+      "category": "blazor",
+      "cause": "JSRuntime não disponível durante prerendering.",
+      "solution": "Usar OnAfterRenderAsync com firstRender check"
+    },
+    {
+      "id": "static-files-404",
+      "title": "Static files retornando 404",
+      "keywords": ["static files", "wwwroot", "CSS", "JS", "404", "assets"],
+      "errorPattern": "static.*404|wwwroot.*not found|css.*404|js.*404",
+      "file": "framework/standards/frontend/blazor/pitfalls.md",
+      "section": "Static Files",
+      "severity": "high",
+      "scope": "blazor-azure",
+      "category": "blazor",
+      "cause": "UseStaticFiles() não configurado ou arquivos não em wwwroot.",
+      "solution": "Adicionar app.UseStaticFiles() e verificar caminho dos arquivos"
+    },
+    {
+      "id": "rendermode-mismatch",
+      "title": "Componente não renderiza interativamente",
+      "keywords": ["RenderMode", "InteractiveServer", "static", "onclick", "not working"],
+      "errorPattern": "@onclick.*not working|button.*not responding|interactive.*not working",
+      "file": "framework/standards/frontend/blazor/pitfalls.md",
+      "section": "RenderModes",
+      "severity": "high",
+      "scope": "blazor-azure",
+      "category": "blazor",
+      "cause": "Componente está em modo estático mas precisa de interatividade.",
+      "solution": "Adicionar @rendermode InteractiveServer no componente"
+    }
+  ],
+  "categories": {
+    "blazor": {
+      "name": "Blazor Server/WASM",
+      "description": "Problemas com componentes Blazor, lifecycle, renderização"
+    },
+    "efcore": {
+      "name": "Entity Framework Core",
+      "description": "Problemas com DbContext, migrations, queries"
+    },
+    "azure": {
+      "name": "Azure Infrastructure",
+      "description": "Problemas com Azure services, deploy, identity"
+    },
+    "auth": {
+      "name": "Authentication/Authorization",
+      "description": "Problemas com login, tokens, claims"
+    },
+    "deploy": {
+      "name": "Deployment/CI-CD",
+      "description": "Problemas com build, deploy, pipelines"
+    }
+  }
+}