@polymorphism-tech/morph-spec 4.3.3 → 4.3.5

package/{stacks/nextjs-supabase/.claude → framework}/commands/morph-infra.md

@@ -41,7 +41,7 @@ Quando o usuário solicitar `/morph-infra init`:
        └── app-insights.bicep
    ```
 
-2. Copiar templates de `.morph/templates/infra/`
+2. Copiar templates de `.morph/templates/infrastructure/...`
 
 3. Substituir placeholders:
    - `{{APP_NAME}}` → nome do projeto

package/framework/hooks/README.md

@@ -0,0 +1,282 @@
+# MORPH-SPEC Hooks Architecture
+
+Git hooks and Agent Teams event handlers for automated validation.
+
+## Architecture
+
+```
+framework/hooks/              # Universal hooks (all stacks share)
+├── pre-commit/
+│   ├── agents.sh             # Validates agents.json Schema
+│   ├── specs.sh              # Validates spec.md sections
+│   └── orchestrator.sh       # Calls framework + stack hooks
+├── commit-msg/
+│   └── conventional-commits.sh # Enforces Conventional Commits format
+├── pre-push/
+│   └── run-tests.sh          # Runs test suite before push
+├── agent-teams/
+│   ├── teammate-idle.js      # Agent Teams idle event
+│   ├── task-completed.js     # Task completion validation
+│   └── phase-advanced.js     # Phase advancement validation
+└── README.md                 # This file
+
+.morph/hooks/                 # Project-specific hooks (optional)
+└── pre-commit/
+    └── tests-{lang}.sh       # Language-specific test coverage
+```
+
+## Hook Types
+
+### Pre-Commit Hooks (Bash)
+
+**Universal (framework/hooks/pre-commit/):**
+- `agents.sh` - Validates agents.json with JSON Schema (BLOCKING)
+- `specs.sh` - Validates spec.md required sections (BLOCKING)
+- `orchestrator.sh` - Master hook that calls all hooks (BLOCKING)
+
+**Project-Specific (.morph/hooks/pre-commit/):**
+- `tests-csharp.sh` - C# test coverage (WARNING ONLY)
+- `tests-typescript.sh` - TypeScript test coverage (WARNING ONLY)
+
+### Commit Message Hook (Bash)
+
+**Universal (framework/hooks/commit-msg/):**
+- `conventional-commits.sh` - Enforces Conventional Commits format (BLOCKING)
+  - Validates: `<type>(<scope>): <description>` format
+  - Allowed types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert
+
+### Pre-Push Hook (Bash)
+
+**Universal (framework/hooks/pre-push/):**
+- `run-tests.sh` - Runs full test suite before push (BLOCKING)
+  - Auto-detects .NET (`dotnet test`) or Node.js (`npm test`) projects
+
+### Agent Teams Hooks (JavaScript)
+
+**Universal (framework/hooks/agent-teams/):**
+- `teammate-idle.js` - Triggered when teammate is idle, validates recent work
+- `task-completed.js` - Triggered when task marked complete, validates deliverables
+- `phase-advanced.js` - Triggered when advancing phases, validates outputs and deliverables
+
+## Installation
+
+### Git Hooks (Pre-Commit, Commit-Msg, Pre-Push)
+
+```bash
+# In your project root (.git/hooks directory)
+cd .git/hooks
+
+# Pre-commit hook (validates agents.json, spec.md, runs stack tests)
+ln -sf ../../framework/hooks/pre-commit/orchestrator.sh pre-commit
+chmod +x pre-commit
+
+# Commit-msg hook (enforces Conventional Commits format)
+ln -sf ../../framework/hooks/commit-msg/conventional-commits.sh commit-msg
+chmod +x commit-msg
+
+# Pre-push hook (runs test suite before push)
+ln -sf ../../framework/hooks/pre-push/run-tests.sh pre-push
+chmod +x pre-push
+```
+
+### Agent Teams Hooks
+
+Add to `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "TeammateIdle": "node framework/hooks/agent-teams/teammate-idle.js {feature}",
+    "TaskCompleted": "node framework/hooks/agent-teams/task-completed.js {feature} {taskId}",
+    "PhaseAdvanced": "node framework/hooks/agent-teams/phase-advanced.js {feature} {fromPhase} {toPhase}"
+  }
+}
+```
+
+## How It Works
+
+### Pre-Commit Flow
+
+```
+git commit -m "message"
+    ↓
+.git/hooks/pre-commit executes
+    ↓
+framework/hooks/pre-commit/orchestrator.sh
+    ├─ Runs framework hooks (agents.sh, specs.sh)
+    └─ Runs stack hooks (.morph/hooks/pre-commit/*.sh)
+    ↓
+If ANY FAILS → COMMIT BLOCKED
+If ALL PASS → COMMIT ALLOWED
+```
+
+### Agent Teams Flow
+
+```
+Teammate becomes idle
+    ↓
+Claude Code triggers "TeammateIdle" event
+    ↓
+framework/hooks/agent-teams/teammate-idle.js
+    ├─ Loads agents.json
+    ├─ Filters validators with hook_triggers: ["TeammateIdle"]
+    ├─ Executes validators via hook-executor.js
+    └─ Formats results
+    ↓
+If BLOCKED → Show errors, prevent teammate from proceeding
+If PASSED → Allow teammate to continue
+```
+
+## Configuring Validators
+
+Validators register for hook events in `agents.json`:
+
+```json
+{
+  "security-expert": {
+    "tier": 4,
+    "role": "validator",
+    "relationships": {
+      "runs_in": "hooks",
+      "hook_triggers": ["TeammateIdle", "TaskCompleted"]
+    },
+    "hook_behavior": {
+      "validates": ["SQL injection", "XSS", "Secrets"],
+      "severity": "error",
+      "blocks_on_fail": true
+    }
+  }
+}
+```
+
+## Testing Hooks
+
+### Pre-Commit Hooks
+
+```bash
+# Test orchestrator
+bash framework/hooks/pre-commit/orchestrator.sh
+
+# Test individual hook
+bash framework/hooks/pre-commit/agents.sh
+```
+
+### Git Hooks
+
+```bash
+# Test pre-commit orchestrator
+bash framework/hooks/pre-commit/orchestrator.sh
+
+# Test individual framework hooks
+bash framework/hooks/pre-commit/agents.sh
+bash framework/hooks/pre-commit/specs.sh
+
+# Test commit-msg hook (pass test message as argument)
+echo "feat(test): add new feature" > /tmp/test-msg.txt
+bash framework/hooks/commit-msg/conventional-commits.sh /tmp/test-msg.txt
+
+# Test pre-push hook
+bash framework/hooks/pre-push/run-tests.sh
+```
+
+### Agent Teams Hooks
+
+```bash
+# Simulate TeammateIdle event
+node framework/hooks/agent-teams/teammate-idle.js test-feature --verbose --dry-run
+
+# Simulate TaskCompleted event
+node framework/hooks/agent-teams/task-completed.js test-feature T001 --verbose --dry-run
+
+# Simulate PhaseAdvanced event
+node framework/hooks/agent-teams/phase-advanced.js test-feature design clarify --verbose --dry-run
+```
+
+## Bypassing Hooks
+
+```bash
+# Skip pre-commit hooks (NOT RECOMMENDED)
+git commit --no-verify
+
+# Skip commit-msg hook (NOT RECOMMENDED)
+git commit --no-verify
+
+# Skip pre-push hook (NOT RECOMMENDED)
+git push --no-verify
+
+# Skip task completion validation (NOT RECOMMENDED)
+morph-spec task done feature-name task-id --skip-validation
+```
+
+## Creating Custom Hooks
+
+### Stack-Specific Pre-Commit Hook
+
+Create `.morph/hooks/pre-commit/my-hook.sh`:
+
+```bash
+#!/bin/bash
+# Scope: my-stack | Custom validation
+echo "🎯 Running custom validation..."
+
+# Your validation logic here
+
+exit 0
+```
+
+The orchestrator will automatically detect and run it.
+
+### New Hook Event Type
+
+Add to `framework/hooks/agent-teams/`:
+
+```javascript
+#!/usr/bin/env node
+// Scope: universal | My custom event
+
+import { executeHook, formatHookResults } from '../../src/lib/hooks/hook-executor.js';
+
+// Your hook logic here
+```
+
+Register in `agents.json`:
+
+```json
+{
+  "hook_triggers": ["MyCustomEvent"]
+}
+```
+
+## Troubleshooting
+
+### Pre-Commit Hook Not Running
+
+```bash
+# Check if hook exists
+ls -la .git/hooks/pre-commit
+
+# Recreate symlink
+cd .git/hooks
+ln -sf ../../framework/hooks/pre-commit/orchestrator.sh pre-commit
+chmod +x pre-commit
+```
+
+### Agent Teams Hook Failing
+
+```bash
+# Test manually with verbose output
+node framework/hooks/agent-teams/teammate-idle.js my-feature --verbose
+
+# Check agents.json configuration
+npx morph-spec validate-agents-skills
+```
+
+## References
+
+- Hook executor: `src/lib/hooks/hook-executor.js`
+- Checkpoint hooks: `src/lib/checkpoints/checkpoint-hooks.js`
+- Agents configuration: `.morph/config/agents.json`
+
+---
+
+*MORPH-SPEC v4.0.0 - Hooks Architecture*

package/framework/hooks/agent-stop/validate-and-continue.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * Stop Hook: validate-and-continue
+ *
+ * Runs architecture and security validators.
+ * Writes structured JSON to stdout for stop-hook-executor to parse.
+ *
+ * Output format:
+ * {
+ *   "passed": boolean,
+ *   "issues": [{ "message": string, "severity": "error"|"warning" }],
+ *   "suggestions": [string],
+ *   "error": string | null
+ * }
+ */
+
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+const VALIDATORS = ['architecture', 'security'];
+const cwd = process.cwd();
+
+async function runValidators() {
+  const issues = [];
+  const suggestions = [];
+  let allPassed = true;
+
+  for (const validator of VALIDATORS) {
+    try {
+      const validateBin = join(cwd, 'bin/validate.js');
+      if (!existsSync(validateBin)) {
+        // Validator binary not found — skip gracefully
+        suggestions.push(`Install morph-spec validator: bin/validate.js not found`);
+        continue;
+      }
+
+      const result = execSync(
+        `node "${validateBin}" ${validator} --json --quiet`,
+        { encoding: 'utf8', stdio: 'pipe', cwd, timeout: 60000 }
+      );
+
+      const parsed = JSON.parse(result);
+      if (parsed.errors > 0) {
+        allPassed = false;
+        (parsed.issues || []).forEach(issue => {
+          if (issue.severity === 'error') {
+            issues.push({ message: `[${validator}] ${issue.message}`, severity: 'error' });
+          }
+        });
+      }
+
+      if (parsed.warnings > 0) {
+        (parsed.issues || []).forEach(issue => {
+          if (issue.severity === 'warning') {
+            issues.push({ message: `[${validator}] ${issue.message}`, severity: 'warning' });
+          }
+        });
+      }
+    } catch (err) {
+      // If validator fails to run, report as warning but don't block
+      issues.push({
+        message: `[${validator}] Validator execution failed: ${err.message}`,
+        severity: 'warning'
+      });
+      suggestions.push(`Run manually: node bin/validate.js ${validator}`);
+    }
+  }
+
+  if (!allPassed && issues.some(i => i.severity === 'error')) {
+    suggestions.push('Fix architecture and security violations before continuing');
+    suggestions.push('See framework/standards/architecture.md for patterns');
+  }
+
+  const output = {
+    passed: allPassed,
+    validatorsRun: VALIDATORS,
+    issues,
+    suggestions,
+    timestamp: new Date().toISOString(),
+    error: null
+  };
+
+  process.stdout.write(JSON.stringify(output));
+  process.exit(allPassed ? 0 : 1);
+}
+
+runValidators().catch(err => {
+  process.stdout.write(JSON.stringify({
+    passed: false,
+    issues: [{ message: err.message, severity: 'error' }],
+    suggestions: [],
+    error: err.message
+  }));
+  process.exit(1);
+});

package/framework/hooks/agent-stop/validate-checkpoints.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Stop Hook: validate-checkpoints
+ *
+ * Checks that the last 3 tasks passed their checkpoints.
+ * Reads from state.json checkpoint history.
+ *
+ * Output format: { passed, issues, suggestions, checkpointSummary, error }
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const cwd = process.cwd();
+const REQUIRED_PASSING = 3;
+
+function validateCheckpoints() {
+  const statePath = join(cwd, '.morph/state.json');
+
+  if (!existsSync(statePath)) {
+    process.stdout.write(JSON.stringify({
+      passed: true,
+      issues: [],
+      suggestions: ['State file not found — checkpoint validation skipped'],
+      checkpointSummary: null,
+      error: null
+    }));
+    process.exit(0);
+  }
+
+  let state;
+  try {
+    state = JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch (err) {
+    process.stdout.write(JSON.stringify({
+      passed: false,
+      issues: [{ message: `Failed to read state.json: ${err.message}`, severity: 'error' }],
+      suggestions: [],
+      error: err.message
+    }));
+    process.exit(1);
+  }
+
+  // Find all features with checkpoints
+  const features = Object.entries(state.features || {});
+  const issues = [];
+  const suggestions = [];
+  let allPassed = true;
+
+  for (const [featureName, feature] of features) {
+    if (feature.phase !== 'implement') continue;
+
+    const checkpoints = feature.checkpoints || [];
+    const recentCheckpoints = checkpoints.slice(-REQUIRED_PASSING);
+
+    if (recentCheckpoints.length === 0) {
+      // No checkpoints yet — pass
+      continue;
+    }
+
+    const failedRecent = recentCheckpoints.filter(c => c.passed === false);
+    if (failedRecent.length > 0) {
+      allPassed = false;
+      issues.push({
+        message: `Feature ${featureName}: ${failedRecent.length} recent checkpoint(s) failed`,
+        severity: 'error'
+      });
+      suggestions.push(`Review checkpoint failures in ${featureName} before continuing`);
+    }
+  }
+
+  const checkpointSummary = features.map(([name, f]) => ({
+    feature: name,
+    totalCheckpoints: f.checkpoints?.length || 0,
+    recentPassed: (f.checkpoints || []).slice(-3).filter(c => c.passed !== false).length
+  }));
+
+  const output = {
+    passed: allPassed,
+    issues,
+    suggestions,
+    checkpointSummary,
+    timestamp: new Date().toISOString(),
+    error: null
+  };
+
+  process.stdout.write(JSON.stringify(output));
+  process.exit(allPassed ? 0 : 1);
+}
+
+try {
+  validateCheckpoints();
+} catch (err) {
+  process.stdout.write(JSON.stringify({
+    passed: false,
+    issues: [{ message: err.message, severity: 'error' }],
+    suggestions: [],
+    error: err.message
+  }));
+  process.exit(1);
+}

package/framework/hooks/agent-stop/validate-tests.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * Stop Hook: validate-tests
+ *
+ * Runs the project test suite (if available) and returns results.
+ * Gracefully handles projects without tests.
+ *
+ * Output format: { passed, issues, suggestions, testResults, error }
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const cwd = process.cwd();
+
+function validateTests() {
+  // Check if test runner is configured
+  let pkgJson;
+  try {
+    pkgJson = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+  } catch {
+    process.stdout.write(JSON.stringify({
+      passed: true,
+      issues: [],
+      suggestions: ['No package.json found — test validation skipped'],
+      testResults: null,
+      error: null
+    }));
+    process.exit(0);
+  }
+
+  const hasTestScript = pkgJson.scripts?.test && !pkgJson.scripts.test.includes('no test specified');
+  const hasVitest = pkgJson.dependencies?.vitest || pkgJson.devDependencies?.vitest;
+  const hasJest = pkgJson.dependencies?.jest || pkgJson.devDependencies?.jest;
+
+  if (!hasTestScript && !hasVitest && !hasJest) {
+    process.stdout.write(JSON.stringify({
+      passed: true,
+      issues: [],
+      suggestions: ['No test runner configured — consider adding vitest or jest'],
+      testResults: { skipped: true, reason: 'No test runner found' },
+      error: null
+    }));
+    process.exit(0);
+  }
+
+  try {
+    const testCmd = hasVitest ? 'npx vitest run' : (hasJest ? 'npx jest' : 'npm test');
+    const output = execSync(`${testCmd} --passWithNoTests`, {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      cwd,
+      timeout: 300000 // 5 minutes for tests
+    });
+
+    // Parse test results from output
+    const passedMatch = output.match(/(\d+)\s+passed/);
+    const failedMatch = output.match(/(\d+)\s+failed/);
+    const skippedMatch = output.match(/(\d+)\s+skipped/);
+
+    const testResults = {
+      passed: parseInt(passedMatch?.[1] || '0'),
+      failed: parseInt(failedMatch?.[1] || '0'),
+      skipped: parseInt(skippedMatch?.[1] || '0'),
+      rawOutput: output.substring(0, 500) // First 500 chars
+    };
+
+    process.stdout.write(JSON.stringify({
+      passed: testResults.failed === 0,
+      issues: testResults.failed > 0
+        ? [{ message: `${testResults.failed} test(s) failed`, severity: 'error' }]
+        : [],
+      suggestions: testResults.failed > 0
+        ? ['Fix failing tests before continuing implementation']
+        : [],
+      testResults,
+      timestamp: new Date().toISOString(),
+      error: null
+    }));
+    process.exit(testResults.failed === 0 ? 0 : 1);
+  } catch (err) {
+    // Extract test failure count from error output
+    const output = err.stdout || err.stderr || err.message;
+    const failedMatch = output.match(/(\d+)\s+failed/);
+    const failed = parseInt(failedMatch?.[1] || '1');
+
+    process.stdout.write(JSON.stringify({
+      passed: false,
+      issues: [{ message: `Test suite failed with ${failed} failure(s)`, severity: 'error' }],
+      suggestions: ['Review test output and fix failing tests', 'Run: npm test locally'],
+      testResults: { failed, rawOutput: output.substring(0, 500) },
+      error: null
+    }));
+    process.exit(1);
+  }
+}
+
+try {
+  validateTests();
+} catch (err) {
+  process.stdout.write(JSON.stringify({
+    passed: false,
+    issues: [{ message: err.message, severity: 'error' }],
+    suggestions: [],
+    error: err.message
+  }));
+  process.exit(1);
+}

package/framework/hooks/agent-teams/dispatch.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+/**
+ * Agent Teams Hook Dispatcher
+ *
+ * Reads Claude Code PostToolUse JSON from stdin and dispatches to the
+ * appropriate agent-teams hook based on the Bash command content.
+ *
+ * Wired via .claude/settings.local.json:
+ *   "PostToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "node framework/hooks/agent-teams/dispatch.js" }] }]
+ *
+ * Dispatches:
+ *   morph-spec task done <feature> <taskId>  → task-completed.js <feature> <taskId>
+ *   morph-spec phase advance <feature>       → phase-advanced.js <feature> <from> <to>
+ */
+
+import { execSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(input || '{}');
+    const command = payload?.tool_input?.command || '';
+    dispatch(command);
+  } catch {
+    // Non-JSON or empty stdin — ignore silently
+    process.exit(0);
+  }
+});
+
+function dispatch(command) {
+  // morph-spec task done <feature> <taskId> [--skip-validation]
+  const taskDoneMatch = command.match(/morph-spec\s+task\s+done\s+(\S+)\s+(\S+)/);
+  if (taskDoneMatch) {
+    const [, feature, taskId] = taskDoneMatch;
+    run(`node "${join(__dirname, 'task-completed.js')}" ${feature} ${taskId}`);
+    return;
+  }
+
+  // morph-spec phase advance <feature>
+  const phaseAdvanceMatch = command.match(/morph-spec\s+phase\s+advance\s+(\S+)/);
+  if (phaseAdvanceMatch) {
+    const [, feature] = phaseAdvanceMatch;
+    // from/to phases not available at PostToolUse time — use placeholder
+    run(`node "${join(__dirname, 'phase-advanced.js')}" ${feature} unknown advanced`);
+    return;
+  }
+
+  // No match — exit cleanly
+  process.exit(0);
+}
+
+function run(cmd) {
+  try {
+    execSync(cmd, { stdio: 'inherit', cwd: join(__dirname, '../../..') });
+  } catch {
+    // Hook failures are non-blocking for the dispatch layer
+  }
+  process.exit(0);
+}