@polymorphism-tech/morph-spec 4.10.10 → 4.11.1

package/docs/QUICKSTART.md

@@ -6,13 +6,7 @@
 npm install -g @polymorphism-tech/morph-spec
 ```
 
-Or use `npx` without a global install:
-
-```bash
-npx @polymorphism-tech/morph-spec init
-```
-
-> **Windows / nvm-windows:** Global installs may not appear on PATH. Use `npx` or add the npm prefix to PATH manually: `npm config get prefix`, then add `{prefix}` to your PATH.
+> The installer automatically configures your PowerShell PATH on Windows. If `morph-spec` is not found, open a new terminal window.
 
 ---
 
@@ -203,4 +197,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.10.10 by Polymorphism Tech*
+*morph-spec v4.11.1 by Polymorphism Tech*

package/framework/agents/frontend/css-specialist.md

@@ -67,7 +67,7 @@ When reviewing CSS:
 
 If project already has CSS variables, scan them:
 ```bash
-npx morph-spec generate design-system --scan
+morph-spec generate design-system --scan
 ```
 
 This extracts existing `:root { --var: value }` declarations and populates design-system.md.

package/framework/agents/infrastructure/azure-deploy-specialist.md

@@ -220,7 +220,7 @@ Por favor, forneca os valores abaixo. Serao armazenados de forma segura.
 
 ```bash
 # Validar custos antes de deploy
-npx morph-spec cost infra/main.bicep --verbose
+morph-spec cost infra/main.bicep --verbose
 
 # Se custo > limite configurado:
 # 1. PARAR deployment
@@ -563,7 +563,7 @@ Para uso em pipelines Azure DevOps:
 
 ```bash
 # Uso automatico (sem pausas interativas)
-npx morph-spec deploy prod --auto \
+morph-spec deploy prod --auto \
   --sql-password "$(SQL_PASSWORD)" \
   --tenant-id "$(TENANT_ID)" \
   --client-secret "$(CLIENT_SECRET)" \
@@ -622,7 +622,7 @@ stages:
             deploy:
               steps:
                 - script: |
-                    npx morph-spec deploy dev --auto \
+                    morph-spec deploy dev --auto \
                       --sql-password "$(SqlPassword)" \
                       --skip-confirmation
                   displayName: 'Deploy to Dev'
@@ -638,7 +638,7 @@ stages:
             deploy:
               steps:
                 - script: |
-                    npx morph-spec deploy prod --auto \
+                    morph-spec deploy prod --auto \
                       --sql-password "$(SqlPasswordProd)" \
                       --skip-confirmation
                   displayName: 'Deploy to Prod'

package/framework/commands/morph-apply.md

@@ -23,10 +23,10 @@ Implement the feature by executing its task breakdown, tracking progress through
 |--------|------|-------------|
 | Read spec, tasks, contracts | **Read** all outputs | — |
 | Detect architecture style | **Bash** `cat .morph/config/config.json \| grep architecture` | — |
-| Agent dispatch config | **Bash** `npx morph-spec dispatch-agents $ARGUMENTS implement` | — |
+| Agent dispatch config | **Bash** `morph-spec dispatch-agents $ARGUMENTS implement` | — |
 | Parallel task execution | **Agent** subagent per task group | Sequential fallback |
 | Look up implementation patterns | **Context7 MCP** `query_docs()` | **WebSearch** |
-| Track progress | **Bash** `npx morph-spec state get $ARGUMENTS` | — |
+| Track progress | **Bash** `morph-spec state get $ARGUMENTS` | — |
 
 ---
 
@@ -37,9 +37,9 @@ Before writing any code, verify all prior phases are complete. This gate prevent
 ### 1. Check state and approvals
 
 ```bash
-npx morph-spec state get $ARGUMENTS
-npx morph-spec approval-status $ARGUMENTS
-npx morph-spec validate-feature $ARGUMENTS
+morph-spec state get $ARGUMENTS
+morph-spec approval-status $ARGUMENTS
+morph-spec validate-feature $ARGUMENTS
 ```
 
 **All three must pass.** If any fails:
@@ -87,13 +87,13 @@ cat .morph/config/config.json | grep -A3 '"architecture"'
 ### 4. Get agent dispatch config
 
 ```bash
-npx morph-spec dispatch-agents $ARGUMENTS implement --table
+morph-spec dispatch-agents $ARGUMENTS implement --table
 ```
 
 This shows which agents are active for implementation and how tasks can be grouped. If agent teams are enabled and tasks have no dependencies between groups, consider dispatching parallel agents:
 
 ```bash
-npx morph-spec dispatch-agents $ARGUMENTS implement
+morph-spec dispatch-agents $ARGUMENTS implement
 ```
 
 The JSON output includes `shouldDispatch`, `agents[]`, and `taskGroups` for multi-agent coordination.
@@ -105,15 +105,27 @@ The JSON output includes `shouldDispatch`, `agents[]`, and `taskGroups` for mult
 ### Step 1: Advance to implement phase
 
 ```bash
-npx morph-spec phase advance $ARGUMENTS
+morph-spec phase advance $ARGUMENTS
 ```
 
 This validates phase eligibility and emits a SKILL DISPATCH block listing required skills for implementation (verification-before-completion, morph-checklist, etc.).
 
+### Step 1.5: Create pipeline visibility task
+
+> **MANDATORY** — Create umbrella task for implementation tracking.
+
+```
+TaskCreate: "Implement: {feature-name}"
+  → description: "Execute T001-T00N from tasks.md with checkpoints"
+  → activeForm: "Implementing feature"
+```
+
+Mark as `in_progress`. After all tasks complete (Step 5), mark as `completed`.
+
 ### Step 2: Initialize state tracking
 
 ```bash
-npx morph-spec state set $ARGUMENTS tasks.total {N}
+morph-spec state set $ARGUMENTS tasks.total {N}
 ```
 
 Where `{N}` is the number of tasks in tasks.md (e.g., 6 for T001-T006).
@@ -124,7 +136,7 @@ For each task in the breakdown, follow this cycle:
 
 ```bash
 # 1. Start the task (activates task-tracking guard)
-npx morph-spec task start $ARGUMENTS {task-id}
+morph-spec task start $ARGUMENTS {task-id}
 
 # 2. Implement the task
 #    - Follow spec.md and contracts
@@ -136,7 +148,7 @@ npx morph-spec task start $ARGUMENTS {task-id}
 #    matches the spec and contracts before marking done
 
 # 4. Complete the task (triggers Tier-4 validators automatically)
-npx morph-spec task done $ARGUMENTS {task-id}
+morph-spec task done $ARGUMENTS {task-id}
 ```
 
 **If validation fails on `task done`:**
@@ -145,6 +157,13 @@ npx morph-spec task done $ARGUMENTS {task-id}
 - Re-run `task done` — do NOT use `--skip-validation` unless the user explicitly authorizes it
 - After 3 consecutive failures, escalate to the user
 
+**`--skip-validation` budget system:**
+- Budget-limited: `min(5, ceil(totalTasks × 0.20))` — e.g., 5 tasks → 1 skip, 32 tasks → 5 skips
+- Requires `--reason <text>` (minimum 5 characters) for audit trail
+- Skipped tasks don't count as `passed` in validationHistory → degrades pass rate
+- Usage: `morph-spec task done feat T001 --skip-validation --reason "CSS-only change, no logic"`
+- When budget is exhausted, all remaining tasks must pass Tier-4 validation
+
 **Parallel execution (agent teams):**
 If `dispatch-agents` identified parallelizable task groups and agent teams are enabled, dispatch independent tasks to separate agents. Each agent still calls `task start` and `task done` for its assigned task.
 
@@ -153,8 +172,8 @@ If `dispatch-agents` identified parallelizable task groups and agent teams are e
 After every 3 completed tasks, save a checkpoint:
 
 ```bash
-npx morph-spec checkpoint-save $ARGUMENTS "after-T003"
-npx morph-spec state get $ARGUMENTS
+morph-spec checkpoint-save $ARGUMENTS "after-T003"
+morph-spec state get $ARGUMENTS
 ```
 
 Checkpoints validate architecture compliance, check package versions, scan for security issues, and save a restorable snapshot. The cadence is every 3 tasks — for 6 tasks: checkpoint after T003 and T006. For 10 tasks: after T003, T006, T009, and at completion.
@@ -162,7 +181,7 @@ Checkpoints validate architecture compliance, check package versions, scan for s
 After each checkpoint, check progress:
 
 ```bash
-npx morph-spec state list
+morph-spec state list
 ```
 
 ### Step 5: Finalize implementation
@@ -171,16 +190,16 @@ After all tasks are complete:
 
 ```bash
 # Final validation
-npx morph-spec validate-feature $ARGUMENTS
+morph-spec validate-feature $ARGUMENTS
 
 # Generate recap (auto-marks 'recap' output in state)
-npx morph-spec generate recap $ARGUMENTS
+morph-spec generate recap $ARGUMENTS
 
 # Verify final state
-npx morph-spec state get $ARGUMENTS
+morph-spec state get $ARGUMENTS
 
 # Advance to next phase
-npx morph-spec phase advance $ARGUMENTS
+morph-spec phase advance $ARGUMENTS
 ```
 
 ### Step 6: Post-implementation review
@@ -212,7 +231,8 @@ Next: {next-task-id} — {next-task-title}
 
 - Using `state set phase` instead of `phase advance` — phase advance validates eligibility first
 - Skipping `task start` before implementing — the task-tracking guard will warn
-- Using `--skip-validation` without user authorization
+- Using `--skip-validation` without user authorization or without `--reason`
+- Exhausting `--skip-validation` budget on trivial tasks — reserve for genuine emergencies
 - Implementing without reading spec.md and contracts first
 - Writing code before `phase advance` to implement — the hook will block writes
 - Skipping checkpoints — they catch integration issues early

package/framework/commands/morph-preflight.md

@@ -26,9 +26,9 @@ These checks verify that the morph-spec workflow is complete for the feature bei
 
 ```bash
 # Verify implementation is complete
-npx morph-spec state get {feature}
-npx morph-spec approval-status {feature}
-npx morph-spec validate-feature {feature}
+morph-spec state get {feature}
+morph-spec approval-status {feature}
+morph-spec validate-feature {feature}
 ```
 
 | Check | Command | Pass Criteria |

package/framework/commands/morph-proposal.md

@@ -15,10 +15,10 @@ Guide a feature through the full planning pipeline (proposal through tasks) with
 Check if the feature already has state:
 
 ```bash
-npx morph-spec state get {feature-name}
+morph-spec state get {feature-name}
 ```
 
-- **Exists:** Read the current phase and resume from where it stopped (skip completed phases)
+- **Exists:** Read the current phase and resume from where it stopped (skip completed phases). Create pipeline master tasks (Step 6) and mark already-completed phases as `completed`.
 - **Does not exist:** Start from scratch (PHASE 0)
 
 ---
@@ -40,7 +40,7 @@ Read `framework/agents.json` (or `.morph/framework/agents.json` in client projec
 
 Register each selected agent:
 ```bash
-npx morph-spec state add-agent {feature-name} {agent-id}
+morph-spec state add-agent {feature-name} {agent-id}
 ```
 
 ### Step 3: Determine if UI/UX phase is needed
@@ -70,11 +70,40 @@ Fill every section of the template. In particular:
 ### Step 5: Register state
 
 ```bash
-npx morph-spec state init {feature-name}
-npx morph-spec state set {feature-name} status draft
-npx morph-spec state mark-output {feature-name} proposal
+morph-spec state init {feature-name}
+morph-spec state set {feature-name} status draft
+morph-spec state mark-output {feature-name} proposal
 ```
 
+### Step 6: Create pipeline master tasks
+
+> **MANDATORY** — Create one native task per pipeline phase for progress visibility.
+> These are high-level tasks — one per phase, not per workflow step.
+
+```
+TaskCreate: "Phase 0: Proposal"     → description: "Define feature scope and approach"          → activeForm: "Proposal"
+TaskCreate: "Phase 1: Setup"        → description: "Load context, detect agents, confirm stack"  → activeForm: "Setup"
+TaskCreate: "Phase 2: Design"       → description: "Schema analysis, spec, contracts, decisions" → activeForm: "Design"
+TaskCreate: "Phase 3: Clarify"      → description: "Resolve ambiguities and edge cases"          → activeForm: "Clarify"
+TaskCreate: "Phase 4: Plan"         → description: "Implementation plan with TDD and file paths" → activeForm: "Plan"
+TaskCreate: "Phase 5: Tasks"        → description: "Break spec into T001-T00N with dependencies" → activeForm: "Tasks"
+```
+
+If `ui-designer` is among the activated agents, also create:
+```
+TaskCreate: "Phase 1.5: UI/UX"     → description: "Design system, mockups, components, flows"   → activeForm: "UI/UX"
+```
+
+Wire dependencies (addBlockedBy) matching the phase sequence:
+- Setup ← Proposal
+- UI/UX (if created) ← Setup
+- Design ← UI/UX (or Setup if no UI/UX)
+- Clarify ← Design
+- Plan ← Clarify
+- Tasks ← Plan
+
+Mark "Phase 0: Proposal" as `in_progress` immediately.
+
 ### MANDATORY PAUSE
 
 Use `AskUserQuestion` to present the approval gate with these elements:
@@ -88,8 +117,8 @@ Options: Approve proposal / Request changes / Reject
 
 After approval:
 ```bash
-npx morph-spec approve {feature-name} proposal
-npx morph-spec phase advance {feature-name}
+morph-spec approve {feature-name} proposal
+morph-spec phase advance {feature-name}
 ```
 
 ---
@@ -100,6 +129,8 @@ Invoke the `morph-phase-setup` skill.
 
 Summary: load project context, confirm stack, list active agents, update state.
 
+> **Task lifecycle:** `TaskUpdate` the "Phase 0: Proposal" task → `completed`. `TaskUpdate` the "Phase 1: Setup" task → `in_progress`.
+
 **No pause here.** Continue automatically to the next phase.
 
 ---
@@ -110,16 +141,20 @@ Check if `ui-designer` is in `activeAgents`:
 - **Yes:** Invoke the `morph-phase-uiux` skill. **MANDATORY PAUSE** after generating UI deliverables.
 - **No:** Skip to PHASE 2.
 
+> **Task lifecycle:** `TaskUpdate` the "Phase 1: Setup" task → `completed`. `TaskUpdate` the "Phase 1.5: UI/UX" task → `in_progress` (if UI/UX), or the "Phase 2: Design" task → `in_progress` (if skipping UI/UX).
+
 After approval:
 ```bash
-npx morph-spec approve {feature-name} uiux
-npx morph-spec phase advance {feature-name}
+morph-spec approve {feature-name} uiux
+morph-spec phase advance {feature-name}
 ```
 
 ---
 
 ## 5. PHASE 2: DESIGN
 
+> **Task lifecycle:** `TaskUpdate` the completing phase task (UI/UX or Setup) → `completed`. `TaskUpdate` the "Phase 2: Design" task → `in_progress`.
+
 Invoke the `morph-phase-design` skill.
 
 Summary: generate spec.md, contracts.cs (or contracts-vsa.cs for VSA), decisions.md with ADRs.
@@ -130,14 +165,16 @@ Present: spec, contracts, decisions, effort estimate. Use `AskUserQuestion` with
 
 After approval:
 ```bash
-npx morph-spec approve {feature-name} design
-npx morph-spec phase advance {feature-name}
+morph-spec approve {feature-name} design
+morph-spec phase advance {feature-name}
 ```
 
 ---
 
 ## 6. PHASE 3: CLARIFY (interactive)
 
+> **Task lifecycle:** `TaskUpdate` the "Phase 2: Design" task → `completed`. `TaskUpdate` the "Phase 3: Clarify" task → `in_progress`.
+
 Invoke the `morph-phase-clarify` skill.
 
 Summary: identify ambiguities in spec.md, generate 3-7 targeted questions (building on the questions seeded in the proposal), wait for user answers, update spec with clarifications and edge cases.
@@ -148,6 +185,8 @@ Summary: identify ambiguities in spec.md, generate 3-7 targeted questions (build
 
 ## 7. PHASE 4: PLAN
 
+> **Task lifecycle:** `TaskUpdate` the "Phase 3: Clarify" task → `completed`. `TaskUpdate` the "Phase 4: Plan" task → `in_progress`.
+
 Invoke the `morph-phase-plan` skill.
 
 Summary: generate a detailed implementation plan with exact file paths, TDD structure, and context-aware execution strategy.
@@ -158,14 +197,16 @@ Present: implementation plan with recommended strategy. Use `AskUserQuestion` wi
 
 After approval:
 ```bash
-npx morph-spec approve {feature-name} plan
-npx morph-spec phase advance {feature-name}
+morph-spec approve {feature-name} plan
+morph-spec phase advance {feature-name}
 ```
 
 ---
 
 ## 8. PHASE 5: TASKS
 
+> **Task lifecycle:** `TaskUpdate` the "Phase 4: Plan" task → `completed`. `TaskUpdate` the "Phase 5: Tasks" task → `in_progress`.
+
 Invoke the `morph-phase-tasks` skill.
 
 Summary: break spec into tasks T001-TXXX with dependencies, checkpoints, estimates.
@@ -176,14 +217,16 @@ Present: task breakdown, execution order, total estimate. Use `AskUserQuestion`
 
 After approval:
 ```bash
-npx morph-spec approve {feature-name} tasks
-npx morph-spec phase advance {feature-name}
+morph-spec approve {feature-name} tasks
+morph-spec phase advance {feature-name}
 ```
 
 ---
 
 ## 9. Planning Complete
 
+> **Task lifecycle:** `TaskUpdate` the "Phase 5: Tasks" task → `completed`.
+
 After task approval:
 
 ```

package/framework/commands/morph-status.md

@@ -13,7 +13,7 @@ Show the current MORPH project status and features in development.
 **ALWAYS** use the state-manager CLI to get status:
 
 ```bash
-npx morph-spec state list
+morph-spec state list
 ```
 
 This command automatically shows:
@@ -35,7 +35,7 @@ This command automatically shows:
 To get detailed JSON for a feature:
 
 ```bash
-npx morph-spec state get {feature-name}
+morph-spec state get {feature-name}
 ```
 
 ### 3. Archived Features
@@ -51,7 +51,7 @@ Check `.morph/specs/` for consolidated specs.
 
 ## Output
 
-The `npx morph-spec state list` command automatically generates a formatted dashboard:
+The `morph-spec state list` command automatically generates a formatted dashboard:
 
 ```
 ╔════════════════════════════════════════════════════════════════╗

package/framework/commands/morph-troubleshoot.md

@@ -72,7 +72,7 @@ site:learn.microsoft.com/azure {error}
 **WebSearch usage example:**
 
 If the user asks about a SignalR error:
-1. First: `npx morph-spec troubleshoot SignalR connection`
+1. First: `morph-spec troubleshoot SignalR connection`
 2. If not found: WebSearch with `site:github.com/dotnet/aspnetcore SignalR connection closed`
 3. Return formatted relevant links
 

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

@@ -27,7 +27,7 @@ import { readStdin } from '../../shared/stdin-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';
+import { extractValidationDispatch, formatValidatorInstruction, getToolOutput, parseTaskDoneCommand, parsePhaseAdvanceCommand, parseDispatchAgentsCommand } from '../../shared/dispatch-helpers.js';
 
 try {
   if (!stateExists()) pass();
@@ -73,8 +73,21 @@ async function dispatch(command, payload) {
     const validatorText = await buildValidatorDispatchContext(featureName, payload);
     if (validatorText) {
       if (skipValidation) {
+        // Include budget info when available
+        let budgetInfo = '';
+        try {
+          const feature = getFeature(featureName);
+          if (feature) {
+            const total = feature.tasks?.total || 0;
+            const budget = total === 0 ? 1 : Math.max(1, Math.min(5, Math.ceil(total * 0.2)));
+            const used = (feature.skipValidationLog || []).length;
+            budgetInfo = ` (budget: ${used}/${budget})`;
+          }
+        } catch {
+          // Non-blocking
+        }
         contextParts.push(
-          '⏩ DEFERRED TO CHECKPOINT — validators skipped on this task but MUST run at next checkpoint:\n\n' +
+          `⏩ DEFERRED TO CHECKPOINT — validators skipped on this task${budgetInfo} but MUST run at next checkpoint:\n\n` +
           validatorText
         );
         dispatchResult = 'task_done_deferred_validators';
@@ -107,6 +120,23 @@ async function dispatch(command, payload) {
     const validatorText = await buildValidatorDispatchContext(featureName, payload);
     if (validatorText) contextParts.push(validatorText);
 
+    // Mandatory dispatch instruction when advancing to implement phase
+    try {
+      const advancedPhase = getFeaturePhase(featureName);
+      if (advancedPhase === 'implement') {
+        contextParts.push(
+          '🔧 MANDATORY AGENT DISPATCH\n' +
+          '════════════════════════════════════════\n' +
+          `Run this command BEFORE starting any task:\n\n` +
+          `  morph-spec dispatch-agents ${featureName} implement\n\n` +
+          `Task start will be BLOCKED until dispatch is recorded.\n` +
+          `Use the dispatch output to determine execution mode (single/subagents/agent-teams).`
+        );
+      }
+    } catch {
+      // Non-blocking
+    }
+
     logHookActivity('phase-dispatch', 'PostToolUse',
       validatorText ? 'phase_advance_with_validators' : 'phase_chain');
 
@@ -116,6 +146,21 @@ async function dispatch(command, payload) {
     pass();
   }
 
+  // morph-spec dispatch-agents <feature> <phase>
+  const dispatchParsed = parseDispatchAgentsCommand(command);
+  if (dispatchParsed) {
+    const { featureName: dispFeature, phase: dispPhase } = dispatchParsed;
+    if (dispPhase === 'implement') {
+      injectContext(
+        `✓ Agent dispatch recorded for '${dispFeature}' (implement phase).\n` +
+        `You may now start tasks with: morph-spec task start ${dispFeature} <taskId>\n` +
+        `Use the dispatch config above to assign tasks to the correct typed agents.`
+      );
+    }
+    logHookActivity('phase-dispatch', 'PostToolUse', 'dispatch_agents_confirmed');
+    pass();
+  }
+
   // morph-spec approve <feature> <gate>
   const approveMatch = command.match(/morph-spec\s+approve\s+(\S+)\s+(\S+)/);
   if (approveMatch) {

package/framework/hooks/claude-code/pre-tool-use/task-tracking-guard.js

@@ -50,8 +50,8 @@ try {
   approve(
     `[morph-spec] WARNING: No active task tracking detected during implement phase.\n` +
     `Before writing code, start a task:\n` +
-    `  npx morph-spec task next ${name}        # see what's next\n` +
-    `  npx morph-spec task start ${name} <id>   # mark it in progress\n` +
+    `  morph-spec task next ${name}        # see what's next\n` +
+    `  morph-spec task start ${name} <id>   # mark it in progress\n` +
     `Task tracking ensures validators run, checkpoints fire, and progress is recorded.`
   );
 } catch {

package/framework/hooks/claude-code/session-start/inject-morph-context.js

@@ -125,10 +125,11 @@ try {
     }
 
     // Task tracking guidance for work phases
-    if (['design', 'tasks', 'implement'].includes(phase)) {
+    if (['proposal', 'setup', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement'].includes(phase)) {
       lines.push('');
-      lines.push('💡 TaskCreate/TaskUpdate: Para sessões com 3+ ações planejadas, crie tasks Claude Code');
-      lines.push('   para visibilidade do progresso. Ex: TaskCreate("Gerar spec.md"), TaskUpdate(id, "completed")');
+      lines.push('⚠️  MANDATORY: Create session tasks (TaskCreate) BEFORE starting phase work.');
+      lines.push('   Analyze the phase workflow and create tasks reflecting your planned actions.');
+      lines.push('   Mark each in_progress → completed as you go. See phase skill for guidance.');
     }
 
     // Trust level visibility — warn when low trust may block approval gates
@@ -140,7 +141,7 @@ try {
       if (trustLevel !== 'high' && trustLevel !== 'maximum') {
         lines.push('');
         lines.push(`⚠ Trust level: ${trustLevel} — approval gates require manual approval`);
-        lines.push(`  To auto-approve: npx morph-spec trust set ${name} high`);
+        lines.push(`  To auto-approve: morph-spec trust set ${name} high`);
       }
       if (!workflow && config?.workflowDetection?.confidence === 0) {
         lines.push('');

package/framework/hooks/claude-code/teammate-idle/teammate-idle.js

@@ -51,7 +51,7 @@ try {
 
   try {
     output = execSync(
-      `npx morph-spec validate-feature "${featureName}" --phase implement --quiet`,
+      `morph-spec validate-feature "${featureName}" --phase implement --quiet`,
       {
         cwd: process.cwd(),
         encoding: 'utf-8',
@@ -71,9 +71,9 @@ try {
     const feedback = [
       'MORPH-SPEC validation found issues — please fix before going idle:',
       '',
-      output.trim() || 'Run `npx morph-spec validate-feature to see details.',
+      output.trim() || 'Run `morph-spec validate-feature to see details.',
       '',
-      `Run: npx morph-spec validate-feature ${featureName} --phase implement`,
+      `Run: morph-spec validate-feature ${featureName} --phase implement`,
     ].join('\n');
 
     // Claude Code reads additionalContext from stdout for exit code 2

package/framework/hooks/claude-code/user-prompt/enrich-prompt.js

@@ -72,8 +72,8 @@ try {
         context.push(
           `[morph-spec] REMINDER: No task is currently in_progress for '${name}'.` +
           ` Start a task before coding:\n` +
-          `  npx morph-spec task next ${name}        # see what's next\n` +
-          `  npx morph-spec task start ${name} <id>   # mark it in progress`
+          `  morph-spec task next ${name}        # see what's next\n` +
+          `  morph-spec task start ${name} <id>   # mark it in progress`
         );
       }
     }

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

@@ -10,7 +10,7 @@ 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
+  if ! morph-spec validate-agents-skills; then
     echo ""
     echo "❌ COMMIT BLOCKED: agents.json validation failed"
     echo "   Fix errors above before committing"

package/framework/hooks/shared/dispatch-helpers.js

@@ -98,6 +98,20 @@ export function parsePhaseAdvanceCommand(command) {
   return { featureName: match[1] };
 }
 
+/**
+ * Parse `morph-spec dispatch-agents <feature> <phase>` from a bash command string.
+ * Returns { featureName, phase } or null if the command doesn't match.
+ *
+ * @param {string} command
+ * @returns {{ featureName: string, phase: string } | null}
+ */
+export function parseDispatchAgentsCommand(command) {
+  if (!command || typeof command !== 'string') return null;
+  const match = command.match(/morph-spec\s+dispatch-agents\s+(\S+)\s+(\S+)/);
+  if (!match) return null;
+  return { featureName: match[1], phase: match[2] };
+}
+
 /**
  * Extract the tool result string from a PostToolUse hook payload.
  * Handles multiple possible formats.

package/framework/hooks/shared/state-reader.js

@@ -142,7 +142,9 @@ export function getFeaturePhase(featureName, projectPath) {
  */
 export function isGateApproved(featureName, gate, projectPath) {
   const feature = getFeature(featureName, projectPath);
-  return feature?.approvalGates?.[gate]?.approved === true;
+  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
+  const gates = feature?.approvals || feature?.approvalGates;
+  return gates?.[gate]?.approved === true;
 }
 
 /**
@@ -153,9 +155,11 @@ export function isGateApproved(featureName, gate, projectPath) {
  */
 export function getPendingGates(featureName, projectPath) {
   const feature = getFeature(featureName, projectPath);
-  if (!feature?.approvalGates) return [];
+  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
+  const gates = feature?.approvals || feature?.approvalGates;
+  if (!gates) return [];
 
-  return Object.entries(feature.approvalGates)
+  return Object.entries(gates)
     .filter(([, gate]) => !gate.approved)
     .map(([name]) => name);
 }