@polymorphism-tech/morph-spec 4.10.6 → 4.10.7

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

@@ -69,11 +69,16 @@ async function dispatch(command, payload) {
       // 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) {
+    // Always inject validator dispatch — deferred if --skip-validation
+    const validatorText = await buildValidatorDispatchContext(featureName, payload);
+    if (validatorText) {
+      if (skipValidation) {
+        contextParts.push(
+          '⏩ DEFERRED TO CHECKPOINT — validators skipped on this task but MUST run at next checkpoint:\n\n' +
+          validatorText
+        );
+        dispatchResult = 'task_done_deferred_validators';
+      } else {
         contextParts.push(validatorText);
         dispatchResult = 'task_done_with_validators';
       }

package/framework/skills/README.md

@@ -17,7 +17,6 @@ Each skill is a directory: `{name}/SKILL.md` + optional `scripts/`, `references/
 | `verification-before-completion` | Gate check before marking any work done |
 | `code-review` | .NET/C# review checklist (naming, arch, async, DI, DTOs) |
 | `morph-replicate` | Convert HTML prototypes to Blazor components |
-| `terminal-title` | Manually override the terminal window title for the current task |
 
 ### level-0-meta extras
 

package/framework/skills/level-1-workflows/morph-phase-clarify/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 3 (Clarify). Iterative clarification loop driven b
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.6"
+cliVersion: "4.10.7"
 ---
 
 # MORPH Clarify — Phase 3

package/framework/skills/level-1-workflows/morph-phase-codebase-analysis/SKILL.md

@@ -3,7 +3,7 @@ name: morph-phase-codebase-analysis
 description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.6"
+cliVersion: "4.10.7"
 ---
 
 # MORPH Codebase Analysis - Design Sub-phase

package/framework/skills/level-1-workflows/morph-phase-design/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 2 (Design). Schema-first interactive design: reads
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
-cliVersion: "4.10.6"
+cliVersion: "4.10.7"
 ---
 
 # MORPH Design — Phase 2

package/framework/skills/level-1-workflows/morph-phase-implement/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: "[feature-name]"
 context: fork
 agent: general-purpose
 user-invocable: false
-cliVersion: "4.10.6"
+cliVersion: "4.10.7"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 
@@ -112,7 +112,7 @@ Use `AskUserQuestion` with header `"{MCP}"` and options:
 | Action | Tool | Alternative |
 |--------|------|-------------|
 | Check execution mode (single/subagents/agent-teams) | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS implement` | Task groups + subagent prompts |
-| **Dispatch implementers by domain** (subagents) | **Agent** `subagent_type=<taskGroups[group].agentId>` + `prompt=taskPrompt` from dispatch config | Backend + frontend + infra in parallel |
+| **Dispatch implementers by domain** (subagents) | **Agent** `subagent_type=<taskGroups[group].subagentType>` + `prompt=taskPrompt` from dispatch config | Backend + frontend + infra in parallel |
 | **Create Agent Team** (critical multi-domain features) | Natural language — see Step 0.5b | — |
 | Read task details | **Read** tasks.md, spec.md, contracts.cs/.ts | — |
 | Create new files | **Write** source files | — |
@@ -216,21 +216,44 @@ The strategy was defined and approved in the Plan phase. Use it directly:
 | `"subagents"` | → Dispatch Task subagents in parallel (below) |
 | `"agent-teams"` | → Create Agent Team with plan approval (Step 0.5b) |
 
-If `plan.md` doesn't exist or the field is missing, run as fallback:
+If `plan.md` doesn't exist or the field is missing, auto-detect via dispatch-agents:
 
 ```bash
 npx morph-spec dispatch-agents $ARGUMENTS implement
 ```
 
+Check the `mode` field in the JSON output to determine the execution strategy.
+
 ---
 
 #### Subagents Mode (if strategy is `"subagents"`):
 
-1. Read `taskGroups` from dispatch config (e.g., `backend`, `frontend`, `infra`)
-2. For each group with >= 3 tasks and no cross-group dependencies, use **Agent tool** with `subagent_type=<agentId>` and `taskPrompt` from dispatch config:
+**Step 0.5a: Get dispatch config:**
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS implement
+```
+
+Parse the JSON output. Extract `taskGroups` and each group's `subagentType`.
+
+**Step 0.5b: Verify agent files exist:**
+
+For each group, verify `.claude/agents/{subagentType}.md` exists:
 
-> **Mapping:** `taskGroups[group].agentId` = `subagent_type` in Agent tool.
-> Example: `agentId: "dotnet-senior"` → `Agent(subagent_type=dotnet-senior, prompt=taskPrompt)`.
+```bash
+ls .claude/agents/{subagentType}.md
+```
+
+If missing → **STOP** with: `"Agent file .claude/agents/{subagentType}.md not found. Run: npx morph-spec setup-infra"`. Do NOT fall back to general-purpose agents for missing files.
+
+**Step 0.5c: Dispatch subagents:**
+
+1. For each group with >= 3 tasks and no cross-group dependencies, use **Agent tool** with `subagent_type` from dispatch config:
+
+> **Mapping:** `taskGroups[group].subagentType` = `subagent_type` in Agent tool.
+> Example: `subagentType: "morph-dotnet-senior"` → `Agent(subagent_type="morph-dotnet-senior", prompt=taskPrompt)`.
+>
+> **MANDATORY:** Use the exact `subagentType` value. Do NOT use `general-purpose` agents when a `subagentType` is available.
 
 Each subagent receives a prompt with:
 - Full spec.md and contracts.cs/.ts content
@@ -239,8 +262,10 @@ Each subagent receives a prompt with:
 - Domain isolation: modify ONLY files in their domain
 - **MANDATORY verification before every `task done`** (see Step 2, item 6b)
 
-3. Dispatch subagents for groups in **parallel** (when no cross-group dependencies)
-4. After all complete, validate integration: `npx morph-spec validate-feature $ARGUMENTS --phase implement`
+2. Dispatch subagents for groups in **parallel** (when no cross-group dependencies)
+3. After all complete, validate integration: `npx morph-spec validate-feature $ARGUMENTS --phase implement`
+
+**Fallback:** If `dispatch-agents` fails (non-zero exit or invalid JSON), log a warning and fall back to sequential single-agent mode (Step 2).
 
 **If strategy is `"single"`** → continue to sequential task loop below.
 
@@ -410,22 +435,26 @@ Implementers are dispatched via `dispatch-agents`:
 npx morph-spec dispatch-agents $ARGUMENTS implement
 ```
 
-Use the `agentId` from each group as `subagent_type` in the Agent tool:
+Use the `subagentType` from each group in the Agent tool:
 ```
-Agent(subagent_type=<agentId>, prompt=<filled prompts/implementer-prompt.md>)
+Agent(subagent_type=<subagentType>, prompt=<filled prompts/implementer-prompt.md>)
 ```
 
+> The `subagentType` maps agent IDs to `.claude/agents/` filenames:
+> - Tier 1-3: `morph-{id}` (e.g., `morph-dotnet-senior`)
+> - Tier 4: `morph-validator-{id}` (e.g., `morph-validator-architecture-expert`)
+
 ### Review (Two-Stage)
 
 **Stage 1 — Spec Compliance (mandatory):**
 ```
-Agent(subagent_type=<tier-4 validator>, prompt=<filled prompts/spec-reviewer-prompt.md>)
+Agent(subagent_type=<validator subagentType>, prompt=<filled prompts/spec-reviewer-prompt.md>)
 ```
 Use validators from `dispatch-agents --mode validate`. Spec compliance MUST pass before proceeding.
 
 **Stage 2 — Code Quality (mandatory):**
 ```
-Agent(subagent_type=standards-architect, prompt=<filled prompts/code-quality-reviewer-prompt.md>)
+Agent(subagent_type=morph-standards-architect, prompt=<filled prompts/code-quality-reviewer-prompt.md>)
 ```
 `critical` issues block. `important` issues must be fixed. `suggestion` is optional.
 

package/framework/skills/level-1-workflows/morph-phase-plan/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 4 (Plan). Generates a detailed implementation plan
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.6"
+cliVersion: "4.10.7"
 ---
 
 # MORPH Plan — Phase 4

package/framework/skills/level-1-workflows/morph-phase-setup/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech sta
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.6"
+cliVersion: "4.10.7"
 ---
 
 # MORPH Setup — Phase 1
@@ -27,7 +27,7 @@ Initialize the context and prepare the environment for an approved feature.
 | Action | Tool | Alternative |
 |--------|------|-------------|
 | Verify state | **Bash** `npx morph-spec state get` | — |
-| Detect agents + standards | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `npx morph-spec state add-agent` | — |
+| Detect agents + standards | **Bash** `npx morph-spec detect-agents $ARGUMENTS --json` → parse → **Bash** `npx morph-spec state add-agent` | **Read** agents.json manually |
 | Read project context | **Read** `.morph/context/README.md` | — |
 | Read config | **Read** `.morph/config/config.json` | — |
 | Detect VSA architecture | **Read** `.morph/config/config.json` → check `config.architecture.style` | — |
@@ -38,8 +38,8 @@ Initialize the context and prepare the environment for an approved feature.
 **MCPs for this phase:** GitHub (optional — repo metadata).
 
 **Anti-patterns:**
-- Do not call a `detect-agents` CLI command (it doesn't exist — read `.morph/framework/agents.json` directly)
-- Do not use a Task agent for inline keyword matching (fast enough to do directly)
+- Do not read agents.json manually for keyword matching — use `npx morph-spec detect-agents` CLI
+- Do not use a Task agent for agent detection (CLI is faster and consistent)
 - Do not use WebSearch for local project info (use Read/Glob)
 
 ---
@@ -87,18 +87,22 @@ Proceed with normal keyword detection for all other agents. The architect was al
 
 #### Step 2.1: Keyword Detection
 
-Read agents.json and match keywords (except `domain-architect` and `vsa-architect` which were handled in Step 2.0):
+Use the `detect-agents` CLI to match agent keywords against the proposal (excludes architects already handled in Step 2.0):
 
-1. Read `.morph/framework/agents.json` (or `framework/agents.json` in the framework project itself)
-2. Extract the feature title and description from `0-proposal/proposal.md`
-3. For each agent in the JSON (except architects), check if any keyword from the `keywords[]` field appears in the proposal text
-4. Include all agents with `always_active: true` automatically
-5. Add matched agents to state:
+```bash
+npx morph-spec detect-agents $ARGUMENTS --exclude domain-architect,vsa-architect --json
+```
+
+This reads the proposal from `.morph/features/$ARGUMENTS/0-proposal/proposal.md` and agents.json, returning JSON with `detected[]` and `skipped[]` arrays. Agents with `active_phases: ['*']` are always included.
+
+Parse the JSON output and add each detected agent to state:
 
 ```bash
 npx morph-spec state add-agent $ARGUMENTS {agent-id}
 ```
 
+Run `add-agent` once per detected agent ID from the `detected[]` array.
+
 **To load standards for detected agents:**
 - For each active agent, read the standards referenced by the `standards[]` field in `agents.json`
 - Standard files are located at `.morph/framework/standards/{path}`

package/framework/skills/level-1-workflows/morph-phase-tasks/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 4 (Tasks). Breaks approved spec into bottom-up ord
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.6"
+cliVersion: "4.10.7"
 ---
 
 # MORPH Tasks — Phase 4

package/framework/skills/level-1-workflows/morph-phase-uiux/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 1.5 (UI/UX). Creates design-system.md, mockups.md,
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.6"
+cliVersion: "4.10.7"
 ---
 
 # MORPH UI/UX Design - Phase 1.5

package/framework/skills/level-1-workflows/morph-scope-escalation/SKILL.md

@@ -4,7 +4,7 @@ description: Guided workflow for mid-implementation scope escalation — analyze
 user-invocable: true
 argument-hint: "[feature-name]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.6"
+cliVersion: "4.10.7"
 ---
 
 # Scope Escalation Workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.10.6",
+  "version": "4.10.7",
   "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",

package/src/commands/agents/agent-metrics.js

@@ -0,0 +1,174 @@
+/**
+ * agent-metrics — Display agent performance metrics for a feature
+ *
+ * Reads dispatchLog from state.json, computes per-agent metrics
+ * (dispatch count, task coverage, completion rate, avg duration),
+ * and renders a table or JSON output.
+ *
+ * Usage:
+ *   morph-spec agent-metrics <feature>
+ *   morph-spec agent-metrics <feature> --json
+ *   morph-spec agent-metrics --all
+ */
+
+import { loadState, stateExists } from '../../core/state/state-manager.js';
+import { calculateMetrics, calculateAggregatedMetrics, formatDuration } from '../../lib/agents/metrics-calculator.js';
+import chalk from 'chalk';
+
+/**
+ * CLI command: morph-spec agent-metrics [feature]
+ *
+ * @param {string} [featureName] - Feature name (required unless --all)
+ * @param {Object} [options] - CLI options
+ * @param {boolean} [options.json] - Output as JSON instead of table
+ * @param {boolean} [options.all] - Aggregate metrics across all features
+ */
+export async function agentMetricsCommand(featureName, options = {}) {
+  if (!options.all && !featureName) {
+    console.error(chalk.red('Usage: morph-spec agent-metrics <feature> [--json] [--all]'));
+    process.exit(1);
+  }
+
+  if (!stateExists()) {
+    console.error(chalk.red('No state.json found.'));
+    process.exit(1);
+  }
+
+  const state = loadState();
+
+  if (options.all) {
+    return renderAggregated(state.features || {}, options);
+  }
+
+  const feature = state.features?.[featureName];
+  if (!feature) {
+    console.error(chalk.red(`Feature '${featureName}' not found.`));
+    process.exit(1);
+  }
+
+  const log = feature.dispatchLog || [];
+  if (log.length === 0) {
+    console.log(chalk.gray('\n  No dispatch events recorded.\n'));
+    return;
+  }
+
+  const result = calculateMetrics(log);
+  result.feature = featureName;
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  renderTable(featureName, result);
+}
+
+/**
+ * Render per-feature metrics table.
+ */
+function renderTable(featureName, result) {
+  const { agents, summary } = result;
+
+  console.log(chalk.bold(`\n  Agent Performance \u2014 ${featureName}`));
+  console.log('  ' + '\u2500'.repeat(70));
+
+  // Header
+  console.log(
+    '  ' +
+    pad('Agent', 28) +
+    pad('Dispatches', 12) +
+    pad('Tasks', 8) +
+    pad('Completed', 12) +
+    pad('Avg Duration', 14)
+  );
+  console.log('  ' + '\u2500'.repeat(70));
+
+  for (const agent of agents) {
+    const tasks = agent.tasksAssigned > 0 ? String(agent.tasksAssigned) : '\u2014';
+    const completed = agent.tasksAssigned > 0
+      ? `${agent.tasksCompleted}/${agent.tasksAssigned}`
+      : '\u2014';
+    const duration = formatDuration(agent.avgDurationMs);
+
+    console.log(
+      '  ' +
+      pad(agent.id, 28) +
+      pad(String(agent.dispatches), 12) +
+      pad(tasks, 8) +
+      pad(completed, 12) +
+      pad(duration, 14)
+    );
+  }
+
+  console.log();
+  const rate = summary.totalTasks > 0
+    ? `${Math.round(summary.completionRate * 100)}%`
+    : '0%';
+  console.log(`  Summary: ${summary.completedTasks} tasks completed of ${summary.totalTasks} (${rate}), avg ${formatDuration(summary.avgTaskDurationMs)}/task`);
+  console.log(`  Dispatches: ${summary.totalDispatches} total`);
+  console.log();
+}
+
+/**
+ * Render aggregated metrics across all features.
+ */
+function renderAggregated(features, options) {
+  const featureNames = Object.keys(features);
+  if (featureNames.length === 0) {
+    console.log(chalk.gray('\n  No features found.\n'));
+    return;
+  }
+
+  const result = calculateAggregatedMetrics(features);
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Agent Performance \u2014 All Features (${result.featureCount})`));
+  console.log('  ' + '\u2500'.repeat(70));
+
+  console.log(
+    '  ' +
+    pad('Agent', 28) +
+    pad('Dispatches', 12) +
+    pad('Tasks', 8) +
+    pad('Completed', 12) +
+    pad('Avg Duration', 14)
+  );
+  console.log('  ' + '\u2500'.repeat(70));
+
+  for (const agent of result.agents) {
+    const tasks = agent.tasksAssigned > 0 ? String(agent.tasksAssigned) : '\u2014';
+    const completed = agent.tasksAssigned > 0
+      ? `${agent.tasksCompleted}/${agent.tasksAssigned}`
+      : '\u2014';
+    const duration = formatDuration(agent.avgDurationMs);
+
+    console.log(
+      '  ' +
+      pad(agent.id, 28) +
+      pad(String(agent.dispatches), 12) +
+      pad(tasks, 8) +
+      pad(completed, 12) +
+      pad(duration, 14)
+    );
+  }
+
+  console.log();
+  const { summary } = result;
+  const rate = summary.totalTasks > 0
+    ? `${Math.round(summary.completionRate * 100)}%`
+    : '0%';
+  console.log(`  Summary: ${summary.completedTasks} tasks completed of ${summary.totalTasks} (${rate}), avg ${formatDuration(summary.avgTaskDurationMs)}/task`);
+  console.log(`  Dispatches: ${summary.totalDispatches} total across ${result.featureCount} features`);
+  console.log();
+}
+
+/**
+ * Right-pad a string to a given width.
+ */
+function pad(str, width) {
+  return str.length >= width ? str : str + ' '.repeat(width - str.length);
+}

package/src/commands/agents/audit-dispatch.js

@@ -0,0 +1,82 @@
+/**
+ * audit-dispatch — Display dispatch audit log for a feature
+ *
+ * Reads dispatchLog from state.json and presents a summary:
+ * - Total dispatches
+ * - Per-dispatch: timestamp, phase, mode, agents with subagentTypes
+ * - Agent coverage: which agents handled which tasks
+ *
+ * Usage:
+ *   morph-spec audit-dispatch <feature>
+ *   morph-spec audit-dispatch <feature> --json
+ */
+
+import { loadState, stateExists } from '../../core/state/state-manager.js';
+import chalk from 'chalk';
+
+/**
+ * CLI command: morph-spec audit-dispatch <feature>
+ *
+ * @param {string} featureName - Feature name
+ * @param {Object} [options] - CLI options
+ * @param {boolean} [options.json] - Output as JSON instead of table
+ */
+export async function auditDispatchCommand(featureName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('Usage: morph-spec audit-dispatch <feature>'));
+    process.exit(1);
+  }
+
+  if (!stateExists()) {
+    console.error(chalk.red('No state.json found.'));
+    process.exit(1);
+  }
+
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) {
+    console.error(chalk.red(`Feature '${featureName}' not found.`));
+    process.exit(1);
+  }
+
+  const log = feature.dispatchLog || [];
+
+  if (options.json) {
+    console.log(JSON.stringify(log, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Dispatch Audit — ${featureName}`));
+  console.log('  ' + '─'.repeat(50));
+  console.log(`  Total dispatches: ${log.length}`);
+
+  if (log.length === 0) {
+    console.log(chalk.gray('\n  No dispatch events recorded.\n'));
+    return;
+  }
+
+  for (let i = 0; i < log.length; i++) {
+    const entry = log[i];
+    console.log(`\n  #${i + 1}: ${entry.timestamp} — ${entry.phase} (${entry.mode})`);
+    for (const agent of entry.agents || []) {
+      const taskCount = agent.tasks?.length || 0;
+      console.log(`      ${agent.id} → ${agent.subagentType} (${agent.group}) — ${taskCount} tasks`);
+    }
+  }
+
+  // Agent coverage summary
+  const coverage = {};
+  for (const entry of log) {
+    for (const agent of entry.agents || []) {
+      if (!coverage[agent.id]) coverage[agent.id] = { tasks: 0, dispatches: 0 };
+      coverage[agent.id].tasks += agent.tasks?.length || 0;
+      coverage[agent.id].dispatches += 1;
+    }
+  }
+
+  console.log(chalk.bold('\n  Agent Coverage:'));
+  for (const [id, data] of Object.entries(coverage)) {
+    console.log(`      ${id}: ${data.tasks} tasks across ${data.dispatches} dispatches`);
+  }
+  console.log();
+}