@polymorphism-tech/morph-spec 4.11.0 → 4.12.0

package/framework/agents.json

@@ -1282,7 +1282,7 @@
       "teammate": {
         "role": "CSS & Design System Specialist",
         "icon": "🎨",
-        "spawn_prompt": "You are the CSS & Design System Specialist (FASE 5 only). MANDATORY FIRST STEP: Read .morph/context/design-system.md. Validate all CSS follows the design system (no off-palette hardcoded colors, no inline styles with raw values). Enforce naming conventions (BEM for custom classes). Verify WCAG AA contrast (4.5:1 text, 3:1 UI). Run design-system, css, contrast validators. Any missing tokens must be added to design-system.md before proceeding."
+        "spawn_prompt": "You are the CSS & Design System Specialist (FASE 5 only). MANDATORY FIRST STEP: Read .morph/context/design-system.md. Validate all CSS follows the design system — colors (var(--color-*)), spacing (var(--space-*)), typography (var(--font-*, --text-*)), motion (var(--duration-*, --easing-*)), shadows (var(--shadow-*)), and advanced effects (var(--glass-*, --aurora-*, --perspective-*)). No off-palette hardcoded colors, no inline styles with raw values. Enforce naming conventions (BEM for custom classes). Verify WCAG AA contrast (4.5:1 text, 3:1 UI). Ref: framework/standards/frontend/design-system/design-trends.md for modern technique catalog. Run design-system, css, contrast validators. Any missing tokens must be added to design-system.md before proceeding."
       }
     },
     "seo-growth-hacker": {
@@ -1988,7 +1988,11 @@
         "design system",
         "css",
         "color palette",
-        "spacing"
+        "spacing",
+        "motion tokens",
+        "glassmorphism",
+        "design trends",
+        "advanced effects"
       ],
       "validators": [
         "design-system"
@@ -2008,13 +2012,16 @@
       "teammate": {
         "icon": "🎨",
         "role": "Design System Validator (read-only)",
-        "spawn_prompt": "You are the Design System Validator (Tier 4, READ-ONLY). Scan CSS/SCSS and component files for design system compliance:\n\n1. Color palette — look for hardcoded hex/rgb colors instead of CSS variables (var(--color-primary), var(--color-secondary), etc.)\n2. Spacing — look for hardcoded px/rem values instead of spacing variables (var(--spacing-*))\n3. Typography — look for hardcoded font-size/font-family instead of typography variables (var(--font-*))\n4. Component naming — verify PascalCase for Blazor components (.razor) and kebab-case for CSS classes\n5. Check .morph/context/design-system.md if it exists for project-specific design tokens\n\nUse Grep and Glob to scan. Do NOT modify any files.\n\nOutput a JSON object: { \"passed\": boolean, \"issues\": [{ \"file\": string, \"line\": number, \"message\": string, \"severity\": \"warning\" }] }"
+        "spawn_prompt": "You are the Design System Validator (Tier 4, READ-ONLY). Scan CSS/SCSS and component files for design system compliance:\n\n1. Color palette — look for hardcoded hex/rgb colors instead of CSS variables (var(--color-primary), var(--color-accent), var(--color-surface-*), var(--color-text-*), etc.)\n2. Spacing — look for hardcoded px/rem values instead of spacing variables (var(--space-*))\n3. Typography — look for hardcoded font-size/font-family instead of typography variables (var(--font-display), var(--font-body), var(--text-*))\n4. Motion — look for hardcoded transition/animation durations instead of motion tokens (var(--duration-*), var(--easing-*))\n5. Shadows — look for hardcoded box-shadow instead of shadow tokens (var(--shadow-*), var(--shadow-colored-*), var(--shadow-layered-*))\n6. Advanced effects — verify glassmorphism uses tokens (var(--glass-*)), aurora uses tokens (var(--aurora-*)), perspective uses tokens (var(--perspective-*))\n7. Component naming — verify PascalCase for Blazor components (.razor) and kebab-case for CSS classes\n8. Check .morph/context/design-system.md for project-specific design tokens\n9. Ref: framework/standards/frontend/design-system/design-trends.md for modern technique catalog\n\nUse Grep and Glob to scan. Do NOT modify any files.\n\nOutput a JSON object: { \"passed\": boolean, \"issues\": [{ \"file\": string, \"line\": number, \"message\": string, \"severity\": \"warning\" }] }"
       },
       "hook_behavior": {
         "validates": [
-          "CSS color palette compliance (primary, secondary, accent)",
-          "Spacing values (use var(--spacing-*))",
-          "Typography scale (use var(--font-*))",
+          "CSS color palette compliance (primary, accent, surface, text, neutral, semantic)",
+          "Spacing values (use var(--space-*))",
+          "Typography scale (use var(--font-display), var(--font-body), var(--text-*))",
+          "Motion tokens (use var(--duration-*), var(--easing-*))",
+          "Shadow tokens (use var(--shadow-*), var(--shadow-colored-*), var(--shadow-layered-*))",
+          "Advanced effects (glassmorphism: var(--glass-*), aurora: var(--aurora-*), perspective: var(--perspective-*))",
           "Component naming (PascalCase for Blazor, kebab-case for CSS)"
         ],
         "severity": "warning",
@@ -2129,6 +2136,9 @@
       "active_phases": [
         "implement"
       ],
+      "domains": [
+        "frontend-nextjs"
+      ],
       "keywords": [
         "nextjs",
         "tsx",

package/framework/commands/morph-apply.md

@@ -110,6 +110,18 @@ 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
@@ -145,6 +157,13 @@ 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.
 
@@ -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-proposal.md

@@ -18,7 +18,7 @@ Check if the feature already has state:
 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)
 
 ---
@@ -75,6 +75,35 @@ 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:
@@ -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,6 +141,8 @@ 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
 morph-spec approve {feature-name} uiux
@@ -120,6 +153,8 @@ 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.
@@ -138,6 +173,8 @@ 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.
@@ -166,6 +205,8 @@ 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.
@@ -184,6 +225,8 @@ morph-spec phase advance {feature-name}
 
 ## 9. Planning Complete
 
+> **Task lifecycle:** `TaskUpdate` the "Phase 5: Tasks" task → `completed`.
+
 After task approval:
 
 ```

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: Agent Completion Tracker
+ *
+ * Event: PostToolUse | Matcher: Agent
+ *
+ * Detects when morph-spec subagents complete (dispatched via the Agent tool)
+ * and injects status notifications:
+ *   - Partial: shows which agents are still pending
+ *   - Complete: instructs to run validate-feature
+ *
+ * Only tracks tier 1-3 agents (not validators: morph-validator-*).
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, getActiveFeature, getFeature, getFeaturePhase } from '../../shared/state-reader.js';
+import { pass, injectContext } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+import { subagentTypeToAgentId } from '../../shared/dispatch-helpers.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const subagentType = payload?.tool_input?.subagent_type || '';
+  if (!subagentType) pass();
+
+  // Only track morph-* agents (not external subagents)
+  if (!subagentType.startsWith('morph-')) pass();
+
+  // Skip validators (tier 4) — they have their own tracking
+  if (subagentType.startsWith('morph-validator-')) pass();
+
+  const result = buildAgentCompleteContext(subagentType);
+  if (result) {
+    logHookActivity('agent-complete', 'PostToolUse', result.type);
+    injectContext(result.text);
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}
+
+/**
+ * Build the agent completion notification context.
+ *
+ * @param {string} subagentType - e.g. 'morph-nextjs-expert'
+ * @returns {{ text: string, type: string }|null}
+ */
+function buildAgentCompleteContext(subagentType) {
+  // Get active feature
+  const active = getActiveFeature();
+  if (!active) return null;
+
+  const { name: featureName, feature } = active;
+
+  // Only track during implement phase
+  const phase = getFeaturePhase(featureName);
+  if (phase !== 'implement') return null;
+
+  // Get dispatch log
+  const dispatchLog = feature.dispatchLog;
+  if (!Array.isArray(dispatchLog) || dispatchLog.length === 0) return null;
+
+  // Get the most recent dispatch entry
+  const latestDispatch = dispatchLog[dispatchLog.length - 1];
+  const agents = latestDispatch?.agents;
+  if (!Array.isArray(agents) || agents.length === 0) return null;
+
+  // Find the completing agent in the dispatch
+  const agentId = subagentTypeToAgentId(subagentType);
+  let matchedAgent = agents.find(a => a.subagentType === subagentType);
+  if (!matchedAgent && agentId) {
+    matchedAgent = agents.find(a => a.id === agentId);
+  }
+
+  if (!matchedAgent) return null;
+
+  // Mark this agent as completed (in-memory for evaluation only)
+  // Check which agents are still pending (no completedAt)
+  const pendingAgents = agents.filter(a => {
+    if (a === matchedAgent) return false; // The one just completed
+    return !a.completedAt;
+  });
+
+  const totalAgents = agents.length;
+  const completedCount = totalAgents - pendingAgents.length;
+
+  if (pendingAgents.length === 0) {
+    // All agents complete
+    return {
+      type: 'all_complete',
+      text: [
+        '✅ ALL MORPH-SPEC AGENTS COMPLETE',
+        '════════════════════════════════════════',
+        `All ${totalAgents} dispatched agents have completed their tasks.`,
+        '',
+        'NEXT STEP:',
+        `  morph-spec validate-feature ${featureName} --phase implement`,
+      ].join('\n'),
+    };
+  }
+
+  // Partial completion
+  const remainingList = pendingAgents
+    .map(a => a.title || a.id || 'unknown')
+    .join(', ');
+
+  const agentTitle = matchedAgent.title || matchedAgent.id || subagentType;
+
+  return {
+    type: 'partial_complete',
+    text: `✅ Agent '${agentTitle}' completed (${completedCount}/${totalAgents}). Remaining: ${remainingList}`,
+  };
+}

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/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

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

@@ -98,6 +98,37 @@ 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] };
+}
+
+/**
+ * Convert a subagent_type string back to a morph agent ID.
+ * Reverses the mapping used when dispatching agents as subagents.
+ *
+ * Example: 'morph-nextjs-expert' → 'nextjs-expert'
+ *
+ * @param {string} subagentType - The subagent_type value (e.g. 'morph-nextjs-expert')
+ * @returns {string|null} - Agent ID without 'morph-' prefix, or null if invalid
+ */
+export function subagentTypeToAgentId(subagentType) {
+  if (!subagentType || typeof subagentType !== 'string') return null;
+  if (!subagentType.startsWith('morph-')) return null;
+  const agentId = subagentType.slice('morph-'.length);
+  if (!agentId) return null;
+  return agentId;
+}
+
 /**
  * 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);
 }

package/framework/rules/morph-task-tracking.md

@@ -0,0 +1,49 @@
+---
+stacks:
+  - "*"
+---
+
+# MORPH-SPEC Task Tracking
+
+> Session tasks are MANDATORY in every MORPH-SPEC phase. They track real progress and must be
+> created BEFORE any phase work begins.
+
+## Rules
+
+1. **Every phase skill MUST create session tasks** using `TaskCreate` before reading files or generating outputs
+2. **Tasks are dynamic** — analyze the phase workflow and create tasks that reflect YOUR actual planned actions for this session
+3. **Every task MUST be updated**: `in_progress` before starting, `completed` after finishing
+4. **Pipeline orchestrators** (`/morph-proposal`, `/morph-apply`) MUST create master tasks for each phase
+5. **Never skip task creation** — even if resuming mid-phase, create tasks for remaining steps
+6. **Granularity**: minimum 2, typically 3-7 tasks per phase — adjust to complexity
+7. **For iterative work** (clarification rounds, quality loops): update task `subject` with round/score progress
+
+## Task Update Pattern
+
+```
+TaskUpdate(taskId, status="in_progress")   // before starting the step
+// ... do the work ...
+TaskUpdate(taskId, status="completed")     // after step finishes
+```
+
+For iterative tasks:
+```
+TaskUpdate(taskId, subject="Round 3 — score 82/100")
+```
+
+## Deviation Tracking
+
+When completing a task differently than originally planned, record the reason:
+
+```
+morph-spec task done <feature> <taskId> --note "Reason for deviation"
+```
+
+For after-the-fact annotation (supports multiple types):
+```
+morph-spec task annotate <feature> <taskId> "Reason" --type deviation
+morph-spec task annotate <feature> <taskId> "Context info" --type context
+morph-spec task annotate <feature> <taskId> "Resolved" --type blocker-resolved
+```
+
+Note types: `deviation` (default), `context`, `blocker-resolved`

package/framework/skills/level-0-meta/morph-brainstorming/SKILL.md

@@ -33,17 +33,13 @@ allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
 
 ## Workflow
 
-### Step 0: Create session tasks
+## MANDATORY: Session Tasks
 
-```
-TaskCreate: "Explore project context"   → activeForm: "Exploring context"
-TaskCreate: "Ask clarifying questions"  → activeForm: "Asking questions"
-TaskCreate: "Propose 2-3 approaches"    → activeForm: "Analyzing approaches"
-TaskCreate: "Present design"            → activeForm: "Presenting design"
-TaskCreate: "Document recommendation"   → activeForm: "Documenting"
-```
-
-Update each to `in_progress` before its step and `completed` after.
+> **BEFORE starting any brainstorming work**, analyze what you need to do and create session tasks.
+>
+> **Rules:** Minimum 2 tasks, typically 3-5. Mark `in_progress` before starting, `completed` after.
+>
+> **Typical tasks:** context exploration, clarifying questions, approach analysis, recommendation, documentation
 
 ### Step 1: Explore Context
 

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.11.0"
+cliVersion: "4.12.0"
 ---
 
 # MORPH Clarify — Phase 3
@@ -94,6 +94,15 @@ Read: .morph/features/$ARGUMENTS/1-design/spec.md
 
 Calculate the initial score. Track accumulated answers from prior rounds to avoid repeating already-answered questions.
 
+## MANDATORY: Session Tasks
+
+> **BEFORE starting clarification work**, analyze the spec quality and create session tasks.
+>
+> **Rules:** Minimum 2 tasks, typically 2-4. Mark `in_progress` before starting, `completed` after.
+> For the clarification loop, update the task `subject` with round and score progress.
+>
+> **Typical tasks:** initial score calculation, clarification rounds (iterative), output generation
+
 ---
 
 ### Main Loop

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.11.0"
+cliVersion: "4.12.0"
 ---
 
 # 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.11.0"
+cliVersion: "4.12.0"
 ---
 
 # MORPH Design — Phase 2
@@ -53,19 +53,13 @@ Schema-first interactive design: read the real schema, validate with user, gener
 
 ## PRE-FLIGHT
 
-### Create session tasks for visibility
+## MANDATORY: Session Tasks
 
-```
-TaskCreate: "Pre-flight validation"       → activeForm: "Validating pre-flight"
-TaskCreate: "Schema analysis"             → activeForm: "Analyzing schema"
-TaskCreate: "Architecture blueprint"      → activeForm: "Designing architecture"
-TaskCreate: "Generate spec.md"            → activeForm: "Writing spec"
-TaskCreate: "Generate contracts"          → activeForm: "Writing contracts"
-TaskCreate: "Generate decisions.md"       → activeForm: "Documenting decisions"
-TaskCreate: "Design approval"             → activeForm: "Awaiting design approval"
-```
-
-Update each to `in_progress` before starting and `completed` after finishing.
+> **BEFORE starting any design work**, analyze the workflow below and create session tasks.
+>
+> **Rules:** Minimum 3 tasks, typically 5-7. Mark `in_progress` before starting, `completed` after.
+>
+> **Typical tasks:** pre-flight validation, schema analysis, architecture blueprint, spec generation, contracts generation, decisions documentation, design approval
 
 ---
 

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.11.0"
+cliVersion: "4.12.0"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 
@@ -150,6 +150,12 @@ Use `AskUserQuestion` with header `"{MCP}"` and options:
 
 ## Context Loading
 
+## MANDATORY: Session Tasks
+
+> **You MUST create one native task per T001-T00N from tasks.md BEFORE starting implementation.**
+> After creating all tasks, wire dependencies using `addBlockedBy`.
+> Update each to `in_progress` before starting and `completed` after `task done` succeeds.
+
 ### 1. Read full context in PARALLEL
 
 ```