@polymorphism-tech/morph-spec 4.9.0 → 4.10.0

package/framework/commands/commit.md

@@ -0,0 +1,166 @@
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*), Bash(git log:*)
+argument-hint: [message] | --no-verify | --amend
+description: Create well-formatted commits with conventional commit format and emoji
+---
+
+# Smart Git Commit
+
+Create well-formatted commit: $ARGUMENTS
+
+## Current Repository State
+
+- Git status: !git status --porcelain
+- Current branch: !git branch --show-current
+- Staged changes: !git diff --cached --stat
+- Unstaged changes: !git diff --stat
+- Recent commits: !git log --oneline -5
+
+## What This Command Does
+
+1. Unless specified with --no-verify, automatically runs pre-commit checks:
+   - pnpm lint to ensure code quality
+   - pnpm build to verify the build succeeds
+   - pnpm generate:docs to update documentation
+2. Checks which files are staged with git status
+3. If 0 files are staged, automatically adds all modified and new files with git add
+4. Performs a git diff to understand what changes are being committed
+5. Analyzes the diff to determine if multiple distinct logical changes are present
+6. If multiple distinct changes are detected, suggests breaking the commit into multiple smaller commits
+7. For each commit (or the single commit if not split), creates a commit message using emoji conventional commit format
+
+## Best Practices for Commits
+
+- **Verify before committing**: Ensure code is linted, builds correctly, and documentation is updated
+- **Atomic commits**: Each commit should contain related changes that serve a single purpose
+- **Split large changes**: If changes touch multiple concerns, split them into separate commits
+- **Conventional commit format**: Use the format <type>: <description> where type is one of:
+  - feat: A new feature
+  - fix: A bug fix
+  - docs: Documentation changes
+  - style: Code style changes (formatting, etc)
+  - refactor: Code changes that neither fix bugs nor add features
+  - perf: Performance improvements
+  - test: Adding or fixing tests
+  - chore: Changes to the build process, tools, etc.
+- **Present tense, imperative mood**: Write commit messages as commands (e.g., "add feature" not "added feature")
+- **Concise first line**: Keep the first line under 72 characters
+- **Emoji**: Each commit type is paired with an appropriate emoji:
+  - ✨ feat: New feature
+  - 🐛 fix: Bug fix
+  - 📝 docs: Documentation
+  - 💄 style: Formatting/style
+  - ♻️ refactor: Code refactoring
+  - ⚡️ perf: Performance improvements
+  - ✅ test: Tests
+  - 🔧 chore: Tooling, configuration
+  - 🚀 ci: CI/CD improvements
+  - 🗑️ revert: Reverting changes
+  - 🧪 test: Add a failing test
+  - 🚨 fix: Fix compiler/linter warnings
+  - 🔒️ fix: Fix security issues
+  - 👥 chore: Add or update contributors
+  - 🚚 refactor: Move or rename resources
+  - 🏗️ refactor: Make architectural changes
+  - 🔀 chore: Merge branches
+  - 📦️ chore: Add or update compiled files or packages
+  - ➕ chore: Add a dependency
+  - ➖ chore: Remove a dependency
+  - 🌱 chore: Add or update seed files
+  - 🧑‍💻 chore: Improve developer experience
+  - 🧵 feat: Add or update code related to multithreading or concurrency
+  - 🔍️ feat: Improve SEO
+  - 🏷️ feat: Add or update types
+  - 💬 feat: Add or update text and literals
+  - 🌐 feat: Internationalization and localization
+  - 👔 feat: Add or update business logic
+  - 📱 feat: Work on responsive design
+  - 🚸 feat: Improve user experience / usability
+  - 🩹 fix: Simple fix for a non-critical issue
+  - 🥅 fix: Catch errors
+  - 👽️ fix: Update code due to external API changes
+  - 🔥 fix: Remove code or files
+  - 🎨 style: Improve structure/format of the code
+  - 🚑️ fix: Critical hotfix
+  - 🎉 chore: Begin a project
+  - 🔖 chore: Release/Version tags
+  - 🚧 wip: Work in progress
+  - 💚 fix: Fix CI build
+  - 📌 chore: Pin dependencies to specific versions
+  - 👷 ci: Add or update CI build system
+  - 📈 feat: Add or update analytics or tracking code
+  - ✏️ fix: Fix typos
+  - ⏪️ revert: Revert changes
+  - 📄 chore: Add or update license
+  - 💥 feat: Introduce breaking changes
+  - 🍱 assets: Add or update assets
+  - ♿️ feat: Improve accessibility
+  - 💡 docs: Add or update comments in source code
+  - 🗃️ db: Perform database related changes
+  - 🔊 feat: Add or update logs
+  - 🔇 fix: Remove logs
+  - 🤡 test: Mock things
+  - 🥚 feat: Add or update an easter egg
+  - 🙈 chore: Add or update .gitignore file
+  - 📸 test: Add or update snapshots
+  - ⚗️ experiment: Perform experiments
+  - 🚩 feat: Add, update, or remove feature flags
+  - 💫 ui: Add or update animations and transitions
+  - ⚰️ refactor: Remove dead code
+  - 🦺 feat: Add or update code related to validation
+  - ✈️ feat: Improve offline support
+
+## Guidelines for Splitting Commits
+
+When analyzing the diff, consider splitting commits based on these criteria:
+
+1. **Different concerns**: Changes to unrelated parts of the codebase
+2. **Different types of changes**: Mixing features, fixes, refactoring, etc.
+3. **File patterns**: Changes to different types of files (e.g., source code vs documentation)
+4. **Logical grouping**: Changes that would be easier to understand or review separately
+5. **Size**: Very large changes that would be clearer if broken down
+
+## Examples
+
+Good commit messages:
+- ✨ feat: add user authentication system
+- 🐛 fix: resolve memory leak in rendering process
+- 📝 docs: update API documentation with new endpoints
+- ♻️ refactor: simplify error handling logic in parser
+- 🚨 fix: resolve linter warnings in component files
+- 🧑‍💻 chore: improve developer tooling setup process
+- 👔 feat: implement business logic for transaction validation
+- 🩹 fix: address minor styling inconsistency in header
+- 🚑️ fix: patch critical security vulnerability in auth flow
+- 🎨 style: reorganize component structure for better readability
+- 🔥 fix: remove deprecated legacy code
+- 🦺 feat: add input validation for user registration form
+- 💚 fix: resolve failing CI pipeline tests
+- 📈 feat: implement analytics tracking for user engagement
+- 🔒️ fix: strengthen authentication password requirements
+- ♿️ feat: improve form accessibility for screen readers
+
+Example of splitting commits:
+- First commit: ✨ feat: add new solc version type definitions
+- Second commit: 📝 docs: update documentation for new solc versions
+- Third commit: 🔧 chore: update package.json dependencies
+- Fourth commit: 🏷️ feat: add type definitions for new API endpoints
+- Fifth commit: 🧵 feat: improve concurrency handling in worker threads
+- Sixth commit: 🚨 fix: resolve linting issues in new code
+- Seventh commit: ✅ test: add unit tests for new solc version features
+- Eighth commit: 🔒️ fix: update dependencies with security vulnerabilities
+
+## Command Options
+
+- --no-verify: Skip running the pre-commit checks (lint, build, generate:docs)
+
+## Important Notes
+
+- By default, pre-commit checks (pnpm lint, pnpm build, pnpm generate:docs) will run to ensure code quality
+- If these checks fail, you'll be asked if you want to proceed with the commit anyway or fix the issues first
+- If specific files are already staged, the command will only commit those files
+- If no files are staged, it will automatically stage all modified and new files
+- The commit message will be constructed based on the changes detected
+- Before committing, the command will review the diff to identify if multiple commits would be more appropriate
+- If suggesting multiple commits, it will help you stage and commit the changes separately
+- Always reviews the commit diff to ensure the message matches the changes

package/framework/commands/morph-apply.md

@@ -1,3 +1,9 @@
+---
+description: Implementa a feature especificada seguindo as tasks definidas na FASE 5 do workflow MORPH
+argument-hint: <feature-name>
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
 # Apply MORPH Feature Implementation - FASE 5
 
 Implemente a feature especificada seguindo as tasks definidas.
@@ -42,7 +48,11 @@ npx morph-spec state get {feature-name}
    - [ ] Phase passou por "clarify"
    - [ ] Spec atualizado com clarificações
 
-6. **FASE 4 (Tasks):**
+6. **FASE 4 (Plan):**
+   - [ ] Output `plan` criado
+   - [ ] Plano de implementação aprovado
+
+7. **FASE 5 (Tasks):**
    - [ ] Output `tasks` criado
    - [ ] `tasks.json` tem array de tasks
    - [ ] `tasks.total` > 0 no state
@@ -69,7 +79,8 @@ Para completar as fases de planejamento, execute:
 
 1. **Carregue o contexto**:
    - Leia `.morph/features/{feature}/1-design/spec.md`
-   - Leia `.morph/features/{feature}/3-tasks/tasks.md`
+   - Leia `.morph/features/{feature}/3-plan/plan.md`
+   - Leia `.morph/features/{feature}/4-tasks/tasks.md`
    - Leia `.morph/features/{feature}/1-design/contracts.cs`
    - Leia framework/standards/ e .morph/context/ para padrões
 

package/framework/commands/morph-archive.md

@@ -1,3 +1,9 @@
+---
+description: Arquiva uma feature concluída movendo de features/ para archive/ e atualizando o state
+argument-hint: <feature-name>
+allowed-tools: Read, Write, Edit, Bash
+---
+
 # Archive MORPH Feature
 
 Arquive uma feature concluída, movendo-a de `features/` para `archive/`.
@@ -13,12 +19,12 @@ Verifique antes de arquivar:
 ## Workflow
 
 1. **Valide a conclusão**:
-   - Leia `.morph/features/{feature}/3-tasks/tasks.md`
+   - Leia `.morph/features/{feature}/4-tasks/tasks.md`
    - Verifique que todas tasks estão completadas
    - Confirme com o usuário se pode arquivar
 
 2. **Complete o recap**:
-   - Atualize `.morph/features/{feature}/4-implement/recap.md`
+   - Atualize `.morph/features/{feature}/5-implement/recap.md`
    - Preencha métricas finais
    - Documente lições aprendidas
 

package/framework/commands/morph-infra.md

@@ -1,3 +1,9 @@
+---
+description: Gerencia infraestrutura Azure com Bicep templates — provisiona, atualiza e monitora recursos cloud
+argument-hint: [up|down|plan|status]
+allowed-tools: Read, Write, Edit, Bash, Glob
+---
+
 # /morph-infra - Infrastructure Management
 
 Gerencia infraestrutura Azure usando Bicep templates.

package/framework/commands/morph-preflight.md

@@ -1,3 +1,9 @@
+---
+description: Valida readiness do projeto antes do deploy Azure — verifica specs, contratos, testes, e infraestrutura
+argument-hint: [feature-name]
+allowed-tools: Read, Bash, Glob, Grep
+---
+
 # Pre-Flight Check for Azure Deployment
 
 Validates project readiness before deploying to Azure.

package/framework/commands/morph-proposal.md

@@ -1,3 +1,9 @@
+---
+description: MORPH Spec Pipeline — cria ou retoma o planejamento de uma feature pelas fases 0→4 com pausas obrigatórias de aprovação
+argument-hint: <feature-name>
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
 # MORPH Spec Pipeline
 
 Crie ou retome o planejamento de uma feature, guiando automaticamente pelas fases 0→4 com pausas obrigatórias.
@@ -37,7 +43,8 @@ npx morph-spec state get {feature-name}
    .morph/features/{feature-name}/
    ├── 0-proposal/proposal.md
    ├── 1-design/spec.md (iniciar)
-   └── 3-tasks/tasks.md (iniciar)
+   └── 4-tasks/tasks.md (iniciar)
+
    ```
 
 5. **Preencha `proposal.md`** baseado em `framework/templates/proposal.md`
@@ -55,11 +62,17 @@ npx morph-spec state get {feature-name}
 
 Apresente: resumo da proposta, agentes ativados, custo estimado, 3 itens de pausa.
 
+Após o usuário aprovar:
+```bash
+npx morph-spec approve {feature-name} proposal
+npx morph-spec phase advance {feature-name}
+```
+
 ---
 
 ## 3. Após Aprovação do Proposal → FASE 1: SETUP (auto, sem pausa)
 
-**Ler:** `.claude/skills/level-1-workflows/phase-setup.md` para instruções detalhadas.
+Use o skill `morph-phase-setup` para instruções detalhadas.
 
 Resumo: carregar contexto do projeto, confirmar stack, listar agentes ativos, atualizar state.
 
@@ -70,14 +83,20 @@ Resumo: carregar contexto do projeto, confirmar stack, listar agentes ativos, at
 ## 4. FASE 1.5: UI/UX (condicional)
 
 Verificar se `uiux-designer` está nos `activeAgents`:
-- **Se SIM:** Ler `.claude/skills/level-1-workflows/phase-uiux.md` e executar. **PAUSA OBRIGATORIA** após gerar deliverables UI.
+- **Se SIM:** Use o skill `morph-phase-uiux` e executar. **PAUSA OBRIGATORIA** após gerar deliverables UI.
 - **Se NÃO:** Pular para FASE 2.
 
+Após o usuário aprovar:
+```bash
+npx morph-spec approve {feature-name} uiux
+npx morph-spec phase advance {feature-name}
+```
+
 ---
 
 ## 5. FASE 2: DESIGN
 
-**Ler:** `.claude/skills/level-1-workflows/phase-design.md` para instruções detalhadas.
+Use o skill `morph-phase-design` para instruções detalhadas.
 
 Resumo: gerar spec.md, contracts.cs, decisions.md com ADRs, estimar custos.
 
@@ -85,11 +104,17 @@ Resumo: gerar spec.md, contracts.cs, decisions.md com ADRs, estimar custos.
 
 Apresente: spec, contracts, decisions, custos. 3 itens de pausa (aprovar, ajustar escopo, modificar contracts).
 
+Após o usuário aprovar:
+```bash
+npx morph-spec approve {feature-name} design
+npx morph-spec phase advance {feature-name}
+```
+
 ---
 
 ## 6. Após Aprovação do Design → FASE 3: CLARIFY (interativo)
 
-**Ler:** `.claude/skills/level-1-workflows/phase-clarify.md` para instruções detalhadas.
+Use o skill `morph-phase-clarify` para instruções detalhadas.
 
 Resumo: identificar ambiguidades, gerar 3-7 perguntas, aguardar respostas, atualizar spec com clarificações e edge cases.
 
@@ -97,9 +122,27 @@ Resumo: identificar ambiguidades, gerar 3-7 perguntas, aguardar respostas, atual
 
 ---
 
-## 7. FASE 4: TASKS
+## 6.5. FASE 4: PLAN
+
+Use o skill `morph-phase-plan` para instruções detalhadas.
 
-**Ler:** `.claude/skills/level-1-workflows/phase-tasks.md` para instruções detalhadas.
+Resumo: gerar plano de implementação detalhado com paths exatos, código TDD, e estratégia de execução context-aware.
+
+### PAUSA OBRIGATORIA
+
+Apresente: plano de implementação com estratégia recomendada. 3 itens de pausa (aprovar plano, ajustar estratégia, modificar plano).
+
+Após o usuário aprovar:
+```bash
+npx morph-spec approve {feature-name} plan
+npx morph-spec phase advance {feature-name}
+```
+
+---
+
+## 7. FASE 5: TASKS
+
+Use o skill `morph-phase-tasks` para instruções detalhadas.
 
 Resumo: quebrar spec em tasks T001-TXXX, definir dependências, checkpoints, estimativas.
 
@@ -107,6 +150,12 @@ Resumo: quebrar spec em tasks T001-TXXX, definir dependências, checkpoints, est
 
 Apresente: breakdown de tasks, ordem de execução, estimativa total. 3 itens de pausa (aprovar, repriorizar, adicionar/remover).
 
+Após o usuário aprovar:
+```bash
+npx morph-spec approve {feature-name} tasks
+npx morph-spec phase advance {feature-name}
+```
+
 ---
 
 ## 8. Planejamento Completo

package/framework/commands/morph-status.md

@@ -1,3 +1,9 @@
+---
+description: Mostra o status atual do projeto MORPH e todas as features em desenvolvimento com suas fases e aprovações
+argument-hint: [feature-name]
+allowed-tools: Read, Bash
+---
+
 # MORPH Project Status
 
 Mostre o status atual do projeto MORPH e features em desenvolvimento.

package/framework/commands/morph-troubleshoot.md

@@ -1,3 +1,9 @@
+---
+description: Busca soluções para erros e problemas comuns no desenvolvimento .NET/Blazor/Azure com análise root-cause
+argument-hint: "[error-message]"
+allowed-tools: Read, Bash, Glob, Grep
+---
+
 # Troubleshoot - Buscar Soluções para Erros
 
 Busca soluções para erros e problemas comuns no desenvolvimento .NET/Blazor/Azure.

package/framework/hooks/claude-code/notification/approval-reminder.js

@@ -10,7 +10,7 @@
  * Fail-open: exits 0 on any error.
  */
 
-import { stateExists, getActiveFeature, getPendingGates } from '../../shared/state-reader.js';
+import { stateExists, getActiveFeature, getPendingGates, derivePhaseForFeature } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 
@@ -36,7 +36,8 @@ try {
     implement: ['design', 'tasks']
   };
 
-  const relevantGates = phaseGateRelevance[feature.phase] || [];
+  const currentPhase = feature.phase || derivePhaseForFeature(name);
+  const relevantGates = phaseGateRelevance[currentPhase] || [];
   const pendingRelevant = pending.filter(g => relevantGates.includes(g));
 
   if (pendingRelevant.length === 0) pass();

package/framework/hooks/claude-code/post-tool-use/dispatch.js

@@ -1,25 +1,33 @@
 #!/usr/bin/env node
 
 /**
- * PostToolUse Hook: Improved Dispatch
+ * PostToolUse Hook: Dispatch + Validator Injection
  *
  * Event: PostToolUse | Matcher: Bash
  *
- * Replaces the old agent-teams/dispatch.js with:
- *   - Reads state BEFORE dispatching to pass correct from/to phases
- *   - Handles more CLI commands: approve, state init, checkpoint commands
- *   - Triggers checkpoint validation on task completion when count % 3 === 0
+ * Handles:
+ *   - morph-spec task done: auto-checkpoint every 3 tasks + validator dispatch injection
+ *   - morph-spec phase advance: phase chain evaluation + validator dispatch injection
+ *   - morph-spec approve: pass-through
+ *
+ * Validator dispatch: extracts VALIDATION DISPATCH JSON from tool output
+ * and injects it as additionalContext so Claude reliably dispatches validators
+ * as subagents via the Agent tool.
  *
  * Fail-open: exits 0 on any error.
  */
 
 import { execSync } from 'child_process';
 import { readFileSync, existsSync } from 'fs';
-import { resolve } from 'path';
+import { resolve, join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists, getFeature } from '../../shared/state-reader.js';
+import { stateExists, getFeature, getFeaturePhase } from '../../shared/state-reader.js';
 import { pass, injectContext } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
+import { extractValidationDispatch, formatValidatorInstruction, getToolOutput, parseTaskDoneCommand, parsePhaseAdvanceCommand } from '../../shared/dispatch-helpers.js';
 
 try {
   if (!stateExists()) pass();
@@ -30,24 +38,27 @@ try {
   const command = payload?.tool_input?.command || '';
   if (!command) pass();
 
-  dispatch(command);
+  await dispatch(command, payload);
 } catch {
   // Fail-open
   process.exit(0);
 }
 
-function dispatch(command) {
+async function dispatch(command, payload) {
   // 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 [, featureName, taskId] = taskDoneMatch;
+  const taskDoneParsed = parseTaskDoneCommand(command);
+  if (taskDoneParsed) {
+    const { featureName } = taskDoneParsed;
+    const skipValidation = command.includes('--skip-validation');
+
+    const contextParts = [];
 
     // Check if checkpoint should run (every 3 tasks)
     let dispatchResult = 'task_done';
     try {
       const feature = getFeature(featureName);
       if (feature?.tasks) {
-        const completed = (feature.tasks.completed || 0) + 1; // +1 because task-done hasn't executed yet
+        const completed = (feature.tasks.completed || 0) + 1;
         if (completed > 0 && completed % 3 === 0) {
           const checkpointNum = Math.floor(completed / 3);
           run(`morph-spec checkpoint-save ${featureName} --note "Auto-checkpoint #${checkpointNum} at task ${completed}"`);
@@ -58,16 +69,45 @@ function dispatch(command) {
       // Non-blocking
     }
 
+    // Inject validator dispatch for task completion.
+    // Skip when --skip-validation: no validators needed, avoids subprocess fallback.
+    if (!skipValidation) {
+      const validatorText = await buildValidatorDispatchContext(featureName, payload);
+      if (validatorText) {
+        contextParts.push(validatorText);
+        dispatchResult = 'task_done_with_validators';
+      }
+    }
+
     logHookActivity('phase-dispatch', 'PostToolUse', dispatchResult);
+
+    if (contextParts.length > 0) {
+      injectContext(contextParts.join('\n\n'));
+    }
     pass();
   }
 
   // morph-spec phase advance <feature>
-  const phaseAdvanceMatch = command.match(/morph-spec\s+phase\s+advance\s+(\S+)/);
-  if (phaseAdvanceMatch) {
-    const [, featureName] = phaseAdvanceMatch;
-    evaluatePhaseChain(featureName);
-    logHookActivity('phase-dispatch', 'PostToolUse', 'phase_chain');
+  const phaseAdvanceParsed = parsePhaseAdvanceCommand(command);
+  if (phaseAdvanceParsed) {
+    const { featureName } = phaseAdvanceParsed;
+
+    const contextParts = [];
+
+    // Phase chain evaluation
+    const chainText = buildPhaseChainContext(featureName);
+    if (chainText) contextParts.push(chainText);
+
+    // Validator dispatch injection
+    const validatorText = await buildValidatorDispatchContext(featureName, payload);
+    if (validatorText) contextParts.push(validatorText);
+
+    logHookActivity('phase-dispatch', 'PostToolUse',
+      validatorText ? 'phase_advance_with_validators' : 'phase_chain');
+
+    if (contextParts.length > 0) {
+      injectContext(contextParts.join('\n\n'));
+    }
     pass();
   }
 
@@ -83,45 +123,128 @@ function dispatch(command) {
 }
 
 /**
- * Evaluate whether the phase chain should auto-continue after a phase advance.
- * Injects a `morph-spec phase run` instruction when the workflow has phaseChain.enabled.
- * Silently passes when workflow doesn't support chaining or feature is not found.
+ * Build phase chain context text (returns null if not applicable).
+ * Replaces the old evaluatePhaseChain that called injectContext directly.
  *
  * @param {string} featureName
+ * @returns {string|null}
  */
-function evaluatePhaseChain(featureName) {
+function buildPhaseChainContext(featureName) {
   try {
     const feature = getFeature(featureName);
-    if (!feature) return;
+    if (!feature) return null;
 
     const workflowId = feature.workflow;
-    if (!workflowId || workflowId === 'auto') return;
+    if (!workflowId || workflowId === 'auto') return null;
 
-    // Load workflow config to check phaseChain.enabled
     const configPath = resolve(
       process.cwd(),
       `.morph/framework/workflows/configs/${workflowId}.json`
     );
-    if (!existsSync(configPath)) return;
+    if (!existsSync(configPath)) return null;
 
     let workflowConfig;
     try {
       workflowConfig = JSON.parse(readFileSync(configPath, 'utf8'));
     } catch {
-      return;
+      return null;
     }
 
-    if (!workflowConfig?.phaseChain?.enabled) return;
+    if (!workflowConfig?.phaseChain?.enabled) return null;
 
-    // Inject instruction to continue the phase chain
-    injectContext(
+    return (
       `Phase advance complete. Continue the phase chain:\n` +
       `  morph-spec phase run ${featureName}\n\n` +
       `The phase runner will check eligibility and auto-advance if all gates pass. ` +
       `It will pause automatically on blocked tasks, low pass rate, or trust gates.`
     );
   } catch {
-    // Non-blocking — fail silently
+    return null;
+  }
+}
+
+/**
+ * Extract validator dispatch from tool output and build injection context.
+ *
+ * Strategy:
+ * 1. Try to parse VALIDATION DISPATCH JSON from the tool_result (stdout of phase advance)
+ * 2. If not found, fallback to running dispatch-agents CLI in validate mode
+ *
+ * @param {string} featureName
+ * @param {object} payload - PostToolUse hook payload
+ * @returns {string|null} - Formatted injection text or null
+ */
+async function buildValidatorDispatchContext(featureName, payload) {
+  try {
+    // Strategy 1: Extract from tool output
+    const toolOutput = getToolOutput(payload);
+    const dispatch = extractValidationDispatch(toolOutput);
+    if (dispatch) return formatValidatorInstruction(dispatch);
+
+    // Strategy 2: Direct import of buildDispatchConfig (no subprocess)
+    return await buildDispatchDirect(featureName);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fallback: build validator dispatch config via direct import (no subprocess).
+ *
+ * Attempts to import buildDispatchConfig from the installed package or local
+ * framework. Falls back to null on any error (fail-open).
+ *
+ * @param {string} featureName
+ * @returns {Promise<string|null>}
+ */
+async function buildDispatchDirect(featureName) {
+  try {
+    const phase = getFeaturePhase(featureName);
+    if (!phase) return null;
+
+    // Try local project path first, then package path
+    let buildDispatchConfig;
+    const localPath = resolve(process.cwd(), 'src/commands/agents/dispatch-agents.js');
+    const pkgPath = resolve(process.cwd(), 'node_modules/@polymorphism-tech/morph-spec/src/commands/agents/dispatch-agents.js');
+
+    if (existsSync(localPath)) {
+      ({ buildDispatchConfig } = await import(`file://${localPath.replace(/\\/g, '/')}`));
+    } else if (existsSync(pkgPath)) {
+      ({ buildDispatchConfig } = await import(`file://${pkgPath.replace(/\\/g, '/')}`));
+    } else {
+      return null;
+    }
+
+    const config = await buildDispatchConfig(process.cwd(), featureName, phase, { mode: 'validate' });
+    const validators = config.agents?.filter(a => a.tier === 4);
+    if (!validators || validators.length === 0) return null;
+
+    const agentsJsonPath = resolve(process.cwd(), 'framework/agents.json');
+    const pkgAgentsPath = resolve(process.cwd(), 'node_modules/@polymorphism-tech/morph-spec/framework/agents.json');
+    const agentsPath = existsSync(agentsJsonPath) ? agentsJsonPath : pkgAgentsPath;
+
+    let allAgents = {};
+    if (existsSync(agentsPath)) {
+      allAgents = JSON.parse(readFileSync(agentsPath, 'utf8')).agents || {};
+    }
+
+    const dispatch = {
+      validators: validators.map(v => {
+        const agentData = allAgents[v.id];
+        return {
+          id: v.id,
+          title: v.title,
+          taskPrompt: v.taskPrompt,
+          severity: agentData?.hook_behavior?.severity || 'error',
+          blocksOnFail: agentData?.hook_behavior?.blocks_on_fail ?? true,
+          checks: agentData?.hook_behavior?.validates || [],
+        };
+      }),
+    };
+
+    return formatValidatorInstruction(dispatch);
+  } catch {
+    return null;
   }
 }