@polymorphism-tech/morph-spec 4.8.12 → 4.8.14

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produce
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.12"
+cliVersion: "4.8.14"
 ---
 
 # MORPH Design - FASE 2
@@ -58,6 +58,62 @@ Expanda a proposta em especificação técnica completa, contracts, decisões ar
 
 ---
 
+## ✅ PRÉ-VOO OBRIGATÓRIO (antes de gerar qualquer artefato)
+
+### 1. Verificar contexto injetado pelo SessionStart
+
+O hook já injetou o estado atual. Confirme que você leu:
+- Feature ativa, fase, status de approvals
+- Task progress e pending gates
+- Spec snippet (se disponível)
+
+### 2. Ler todos os prerequisitos em PARALELO
+
+```
+# Uma única chamada, não sequencial:
+Read: .morph/features/{feature}/0-proposal/proposal.md
+    + Read: .morph/config/config.json   (→ architecture.style)
+    + Read: .morph/context/README.md    (→ project context)
+    + Read: framework/agents.json       (→ activeAgents do feature)
+```
+
+### 3. Avaliar escopo → EnterPlanMode se necessário
+
+Se QUALQUER uma das condições abaixo for verdadeira:
+- [ ] Refactor toca ≥5 arquivos existentes de domínio
+- [ ] Estimativa de tasks ≥20
+- [ ] Mudança de arquitetura (ex: migrar de DDD Level 1 → Level 2)
+
+→ **USE EnterPlanMode** antes de gerar contratos. Explore o codebase, apresente opções, aguarde aprovação.
+
+### 4. Dispatch paralelo de subagents para artefatos independentes
+
+Os 4 artefatos de design são **independentes entre si**. Dispatch em paralelo:
+
+```
+# Executar TODOS ao mesmo tempo (uma mensagem, múltiplos Task tool calls):
+Task(subagent=general): gerar spec.md (endpoints, regras de negócio)
+Task(subagent=general): gerar contracts-vsa.cs ou contracts-levelN.cs
+Task(subagent=general): gerar decisions.md (ADRs)
+Task(subagent=general): gerar tasks.md skeleton
+```
+
+Ou obter config de dispatch:
+```bash
+npx morph-spec dispatch-agents {feature} design --table
+```
+
+### 5. Criar tasks de sessão para visibilidade
+
+```
+TaskCreate: "Gerar spec.md"          → activeForm: "Gerando spec.md"
+TaskCreate: "Gerar contracts.cs"     → activeForm: "Gerando contracts.cs"
+TaskCreate: "Gerar decisions.md"     → activeForm: "Gerando decisions.md"
+TaskCreate: "Avanço de fase"         → activeForm: "Avançando fase"
+```
+
+---
+
 ## Workflow
 
 ### Passo 1: Carregar Contexto, Agentes e Dispatch Config

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 user-invocable: false
-cliVersion: "4.8.12"
+cliVersion: "4.8.14"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
@@ -65,6 +65,28 @@ Implemente as tasks definidas na FASE 4, com checkpoints a cada 3 tasks e recap
 
 ---
 
+## ✅ PRÉ-VOO OBRIGATÓRIO (antes de iniciar implementação)
+
+### 1. Ler contexto completo em PARALELO
+
+```
+# Uma única chamada, não sequencial:
+Read: .morph/features/{feature}/3-tasks/tasks.md
+    + Read: .morph/features/{feature}/1-design/spec.md
+    + Read: .morph/features/{feature}/1-design/contracts.cs
+    + Read: .morph/config/config.json                       (→ architecture.style)
+```
+
+### 2. Criar tasks de sessão por grupo de implementação
+
+```
+TaskCreate: "Implementar [domínio] (T001-T00N)"   → activeForm: "Implementando [domínio]"
+TaskCreate: "Checkpoints e validação"              → activeForm: "Validando checkpoint"
+TaskCreate: "Gerar recap.md"                       → activeForm: "Gerando recap"
+```
+
+---
+
 ## Workflow
 
 ### Passo 0.5: Planejar Paralelização

package/framework/skills/level-1-workflows/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
-cliVersion: "4.8.12"
+cliVersion: "4.8.14"
 ---
 
 # MORPH Setup - FASE 1

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

@@ -5,7 +5,7 @@ argument-hint: "[feature-name]"
 disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.12"
+cliVersion: "4.8.14"
 ---
 
 # MORPH Tasks - FASE 4
@@ -50,6 +50,29 @@ Quebre a especificação em tasks executáveis, defina ordem de execução e est
 
 ---
 
+## ✅ PRÉ-VOO OBRIGATÓRIO (antes de iniciar breakdown de tasks)
+
+### 1. Ler todos os prerequisitos em PARALELO
+
+```
+# Uma única chamada, não sequencial:
+Read: .morph/features/{feature}/1-design/spec.md
+    + Read: .morph/features/{feature}/1-design/contracts.cs
+    + Read: .morph/features/{feature}/1-design/decisions.md
+    + Read: .morph/features/{feature}/1-design/schema-analysis.md  (se existir)
+    + Read: .morph/config/config.json                               (→ architecture.style)
+```
+
+### 2. Criar tasks de sessão para visibilidade
+
+```
+TaskCreate: "Analisar spec e definir tasks"   → activeForm: "Analisando spec"
+TaskCreate: "Gerar tasks.md"                  → activeForm: "Gerando tasks.md"
+TaskCreate: "Avanço de fase"                  → activeForm: "Avançando fase"
+```
+
+---
+
 ## Workflow
 
 ### CHECKPOINT DE ENTRADA: Verificar Pré-requisitos
@@ -329,7 +352,7 @@ Para cada task, estime tempo em minutos:
 | Média (Business logic, validações) | 60-120 min |
 | Complexa (Integrações, AI) | 120-240 min |
 
-### Passo 6: Gerar `tasks.json`
+### Passo 6: Gerar `tasks.md`
 
 Crie `.morph/features/$ARGUMENTS/3-tasks/tasks.md` com a estrutura completa de tasks, checkpoints e estimativas.
 

package/framework/skills/level-1-workflows/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
-cliVersion: "4.8.12"
+cliVersion: "4.8.14"
 ---
 
 # MORPH UI/UX Design - FASE 1.5

package/package.json

@@ -1,87 +1,87 @@
-{
-  "name": "@polymorphism-tech/morph-spec",
-  "version": "4.8.12",
-  "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
-  "keywords": [
-    "claude-code",
-    "claude",
-    "ai-coding",
-    "ai-first",
-    "spec-driven",
-    "dotnet",
-    "dotnet10",
-    "blazor",
-    "agent-framework",
-    "fluent-ui",
-    "framework",
-    "developer-tools",
-    "morph",
-    "polymorphism",
-    "micro-saas"
-  ],
-  "main": "src/index.js",
-  "bin": {
-    "morph-spec": "bin/morph-spec.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "framework/",
-    "claude-plugin.json",
-    "docs/QUICKSTART.md",
-    "docs/CHEATSHEET.md",
-    "README.md",
-    "LICENSE",
-    "CLAUDE.md"
-  ],
-  "type": "module",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "scripts": {
-    "start": "node bin/morph-spec.js",
-    "generate": "node scripts/generate-refs.js",
-    "test": "node --test --test-concurrency=1",
-    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node --test --test-concurrency=1",
-    "test:coverage:summary": "c8 --reporter=text-summary node --test --test-concurrency=1",
-    "docs": "jsdoc -c jsdoc.json",
-    "docs:watch": "jsdoc -c jsdoc.json --watch",
-    "docs:serve": "npx http-server docs/api -p 8080 -o",
-    "version:bump": "node scripts/bump-version.js",
-    "release": "node scripts/release.js",
-    "postinstall": "node src/scripts/global-install.js"
-  },
-  "dependencies": {
-    "ajv": "^8.12.0",
-    "ajv-formats": "^3.0.1",
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "diff": "^5.2.0",
-    "fs-extra": "^11.2.0",
-    "glob": "^10.3.0",
-    "handlebars": "^4.7.8",
-    "inquirer": "^9.2.0",
-    "minimatch": "^9.0.5",
-    "ora": "^8.0.0",
-    "yaml": "^2.3.4"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lucasPolymorphism/morph-spec-framework.git"
-  },
-  "author": "Polymorphism Tech <contact@polymorphism.com.br>",
-  "license": "SEE LICENSE IN LICENSE",
-  "homepage": "https://polymorphism.com.br/morph-spec",
-  "bugs": {
-    "email": "support@polymorphism.com.br"
-  },
-  "private": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "c8": "^10.1.3",
-    "docdash": "^2.0.2",
-    "jsdoc": "^4.0.5"
-  }
-}
+{
+  "name": "@polymorphism-tech/morph-spec",
+  "version": "4.8.14",
+  "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "ai-coding",
+    "ai-first",
+    "spec-driven",
+    "dotnet",
+    "dotnet10",
+    "blazor",
+    "agent-framework",
+    "fluent-ui",
+    "framework",
+    "developer-tools",
+    "morph",
+    "polymorphism",
+    "micro-saas"
+  ],
+  "main": "src/index.js",
+  "bin": {
+    "morph-spec": "bin/morph-spec.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "framework/",
+    "claude-plugin.json",
+    "docs/QUICKSTART.md",
+    "docs/CHEATSHEET.md",
+    "README.md",
+    "LICENSE",
+    "CLAUDE.md"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node bin/morph-spec.js",
+    "generate": "node scripts/generate-refs.js",
+    "test": "node --test --test-concurrency=1",
+    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node --test --test-concurrency=1",
+    "test:coverage:summary": "c8 --reporter=text-summary node --test --test-concurrency=1",
+    "docs": "jsdoc -c jsdoc.json",
+    "docs:watch": "jsdoc -c jsdoc.json --watch",
+    "docs:serve": "npx http-server docs/api -p 8080 -o",
+    "version:bump": "node scripts/bump-version.js",
+    "release": "node scripts/release.js",
+    "postinstall": "node src/scripts/global-install.js"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "diff": "^5.2.0",
+    "fs-extra": "^11.2.0",
+    "glob": "^10.3.0",
+    "handlebars": "^4.7.8",
+    "inquirer": "^9.2.0",
+    "minimatch": "^9.0.5",
+    "ora": "^8.0.0",
+    "yaml": "^2.3.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucasPolymorphism/morph-spec-framework.git"
+  },
+  "author": "Polymorphism Tech <contact@polymorphism.com.br>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://polymorphism.com.br/morph-spec",
+  "bugs": {
+    "email": "support@polymorphism.com.br"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "c8": "^10.1.3",
+    "docdash": "^2.0.2",
+    "jsdoc": "^4.0.5"
+  }
+}

package/src/commands/state/advance-phase.js

@@ -10,7 +10,7 @@
  */
 
 import chalk from 'chalk';
-import { loadState, saveState, getFeature, getApprovalGate } from '../../core/state/state-manager.js';
+import { loadState, saveState, getFeature, getApprovalGate, derivePhase } from '../../core/state/state-manager.js';
 import { PHASES, validatePhase } from './validate-phase.js';
 import { detectDesignSystem, hasUIAgentsActive } from '../../lib/detectors/design-system-detector.js';
 import { getOutputPath } from '../../core/paths/output-schema.js';
@@ -29,7 +29,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'tasks', 'implement', 'sync'];
 
 /**
- * Get the next phase after the current one
+ * Get the next phase after the current one.
+ * Returns { nextPhase, skippedPhases } so callers can persist skipped phases in state.
  */
 function getNextPhase(currentPhase, feature, skipOptional, featureName) {
   // Load workflow config if workflow is set
@@ -40,9 +41,16 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
 
   const currentIndex = PHASE_ORDER.indexOf(currentPhase);
   if (currentIndex === -1 || currentIndex >= PHASE_ORDER.length - 1) {
-    return null;
+    return { nextPhase: null, skippedPhases: [] };
   }
 
+  // Agents that justify the uiux phase (wireframes, design system).
+  // Implementation-only agents (blazor-builder, nextjs-expert) are NOT included —
+  // they build components from existing designs but don't create the design artifacts.
+  const uiDesignAgents = ['uiux-designer', 'ui-ux-designer', 'ui-designer'];
+
+  const skippedPhases = [];
+
   for (let i = currentIndex + 1; i < PHASE_ORDER.length; i++) {
     const candidate = PHASE_ORDER[i];
     const phaseDef = PHASES[candidate];
@@ -52,6 +60,7 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
       // Check if workflow explicitly skips this phase
       if (workflowConfig.phases.skip && workflowConfig.phases.skip.includes(candidate)) {
         console.log(chalk.gray(`  ⏩ Skipping ${candidate}: workflow ${feature.workflow} skips this phase`));
+        skippedPhases.push(candidate);
         continue;
       }
 
@@ -60,6 +69,7 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
         for (const [combinedName, phases] of Object.entries(workflowConfig.phases.combined)) {
           if (phases.includes(candidate) && candidate !== combinedName) {
             console.log(chalk.gray(`  ⏩ Skipping ${candidate}: combined into ${combinedName} phase`));
+            skippedPhases.push(candidate);
             continue;
           }
         }
@@ -72,6 +82,7 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
           Object.keys(workflowConfig.phases.combined).includes(candidate);
         if (!isCombinedPhase) {
           console.log(chalk.gray(`  ⏩ Skipping ${candidate}: not in workflow run list`));
+          skippedPhases.push(candidate);
           continue;
         }
       }
@@ -83,6 +94,7 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
           // Evaluate condition (simple conditions for now)
           if (condition === '!hasUIAgents' && !hasUIAgentsActive(process.cwd(), featureName)) {
             console.log(chalk.gray(`  ⏩ Skipping ${candidate}: no UI agents active`));
+            skippedPhases.push(candidate);
             continue;
           }
         }
@@ -93,15 +105,16 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
     if (!workflowConfig) {
       // Skip optional phases if flag set or no relevant agents/outputs
       if (phaseDef?.optional && skipOptional) {
+        skippedPhases.push(candidate);
         continue;
       }
 
-      // Skip uiux if no UI agents are active
+      // Skip uiux if no UI design agents are active
       if (candidate === 'uiux') {
-        const uiAgents = ['blazor-builder', 'uiux-designer', 'nextjs-expert', 'ui-ux-designer'];
-        const hasUiAgent = feature.activeAgents?.some(a => uiAgents.includes(a));
-        if (!hasUiAgent && skipOptional !== false) {
-          console.log(chalk.gray(`  ⏩ Skipping ${candidate}: no UI agents active`));
+        const hasUiDesignAgent = feature.activeAgents?.some(a => uiDesignAgents.includes(a));
+        if (!hasUiDesignAgent && skipOptional !== false) {
+          console.log(chalk.gray(`  ⏩ Skipping ${candidate}: no UI design agents active`));
+          skippedPhases.push(candidate);
           continue;
         }
       }
@@ -111,15 +124,16 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
         const isSimple = feature.workflow === 'fast-track';
         if (isSimple && skipOptional !== false) {
           console.log(chalk.gray(`  ⏩ Skipping ${candidate}: fast-track workflow`));
+          skippedPhases.push(candidate);
           continue;
         }
       }
     }
 
-    return candidate;
+    return { nextPhase: candidate, skippedPhases };
   }
 
-  return null;
+  return { nextPhase: null, skippedPhases };
 }
 
 /**
@@ -138,7 +152,8 @@ export async function advancePhaseCommand(feature, options = {}) {
     process.exit(1);
   }
 
-  const currentPhase = featureData.phase;
+  const featureFolderPath = join(process.cwd(), '.morph', 'features', feature);
+  const currentPhase = featureData.phase || derivePhase(featureFolderPath);
   const currentPhaseDef = PHASES[currentPhase];
 
   console.log(chalk.gray('Feature:'), feature);
@@ -146,7 +161,7 @@ export async function advancePhaseCommand(feature, options = {}) {
   console.log(chalk.gray('Workflow:'), featureData.workflow || 'auto');
 
   // Determine next phase
-  const nextPhase = getNextPhase(currentPhase, featureData, options.skipOptional, feature);
+  const { nextPhase, skippedPhases } = getNextPhase(currentPhase, featureData, options.skipOptional, feature);
 
   if (!nextPhase) {
     console.log(chalk.green('\n✓ Feature is at the final phase!'));
@@ -277,7 +292,7 @@ export async function advancePhaseCommand(feature, options = {}) {
   }
 
   // === GATE 5: Tasks Content Validation ===
-  // Validate tasks.json structure when advancing to implement
+  // Validate tasks.md structure when advancing to implement
   if (currentPhase === 'tasks' && nextPhase === 'implement') {
     if (featureData.outputs?.tasks?.created) {
       const tasksContentValidation = validateTasksContent(featureData.outputs.tasks.path);
@@ -326,6 +341,10 @@ export async function advancePhaseCommand(feature, options = {}) {
   const state = loadState();
   state.features[feature].phase = nextPhase;
   state.features[feature].updatedAt = new Date().toISOString();
+  if (skippedPhases.length > 0) {
+    const existingSkipped = state.features[feature].skippedPhases || [];
+    state.features[feature].skippedPhases = [...new Set([...existingSkipped, ...skippedPhases])];
+  }
   saveState(state);
 
   // Run PhaseAdvanced agent-teams hook (non-blocking)

package/src/commands/tasks/task.js

@@ -1,6 +1,6 @@
 /**
  * Task management commands
- * Wrapper for bin/task-manager.js (CommonJS) to ESM
+ * Spawns bin/task-manager.js (ESM) as a subprocess.
  */
 
 import { spawn } from 'child_process';
@@ -9,7 +9,7 @@ import { dirname, join } from 'path';
 import chalk from 'chalk';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const taskManagerPath = join(__dirname, '..', '..', '..', 'bin', 'task-manager.cjs');
+const taskManagerPath = join(__dirname, '..', '..', '..', 'bin', 'task-manager.js');
 
 /**
  * Execute task-manager.js with given arguments

package/src/core/paths/output-schema.js

@@ -28,6 +28,7 @@ export const OUTPUT_SCHEMA = {
   spec:          { filename: 'spec.md',             phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
   clarifications:{ filename: 'clarifications.md',  phaseDir: '1-design',    phase: 'clarify',   protected: false },
   contracts:     { filename: 'contracts.cs',        phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
+  contractsVsa:  { filename: 'contracts-vsa.cs',    phaseDir: '1-design',    phase: 'design',    protected: true,  approvalGate: 'design' },
   tasks:         { filename: 'tasks.md',            phaseDir: '3-tasks',     phase: 'tasks',     protected: true,  approvalGate: 'tasks' },
   uiDesignSystem:{ filename: 'design-system.md',   phaseDir: '2-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
   uiMockups:     { filename: 'mockups.md',          phaseDir: '2-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },

package/src/lib/detectors/design-system-detector.js

@@ -136,12 +136,13 @@ export function hasUIAgentsActive(projectPath, featureName) {
       return false;
     }
 
-    // UI agents that require design system
+    // UI design agents that require a design system before implement phase.
+    // Implementation-only agents (blazor-builder, nextjs-expert, css-specialist)
+    // build from existing designs and do NOT trigger this gate.
     const uiAgents = [
-      'blazor-builder',
       'ui-designer',
-      'css-specialist',
-      'nextjs-expert'
+      'uiux-designer',
+      'ui-ux-designer',
     ];
 
     return feature.activeAgents.some(agentId => uiAgents.includes(agentId));

package/src/lib/tasks/task-parser.js

@@ -0,0 +1,94 @@
+/**
+ * Task Parser — Shared utilities for reading and syncing task state.
+ *
+ * Extracted from bin/task-manager.cjs so both the task-manager and any
+ * future consumers can share the same parsing logic without duplication.
+ */
+
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+
+// ============================================================================
+// parseTasksMd
+// ============================================================================
+
+/**
+ * Parse tasks.md to extract task stubs for the v3 state format.
+ * Accepts headings in either format:
+ *   ### T001 — Task title   (em-dash / en-dash / hyphen)
+ *   ### T001: Task title    (colon)
+ *
+ * @param {string} featureName
+ * @param {string} [cwd] - Project root (defaults to process.cwd())
+ * @returns {Promise<Array<{id, title, status, dependencies, files, checkpoint}>>}
+ */
+export async function parseTasksMd(featureName, cwd = process.cwd()) {
+  const tasksPath = join(cwd, `.morph/features/${featureName}/3-tasks/tasks.md`);
+  let content = '';
+  try {
+    content = await readFile(tasksPath, 'utf-8');
+  } catch {
+    return [];
+  }
+
+  const tasks = [];
+  const headingRe = /^###\s+(T\d+)\s*[—–:\-]\s*(.+)$/gm;
+  let match;
+  while ((match = headingRe.exec(content)) !== null) {
+    tasks.push({
+      id: match[1],
+      title: match[2].trim(),
+      status: 'pending',
+      dependencies: [],
+      files: [],
+      checkpoint: null,
+    });
+  }
+  return tasks;
+}
+
+// ============================================================================
+// ensureTaskList
+// ============================================================================
+
+/**
+ * Ensure feature.taskList exists (array of individual task objects).
+ *
+ * In v3 state, feature.tasks is a counter object {total, completed, …}.
+ * Individual task objects live in feature.taskList.
+ *
+ * @param {Object} feature - Feature state object (mutated in place)
+ * @param {string} featureName
+ * @param {string} [cwd]
+ * @returns {Promise<Array>} The task list
+ */
+export async function ensureTaskList(feature, featureName, cwd = process.cwd()) {
+  if (Array.isArray(feature.tasks)) {
+    // v2 format: tasks IS the array
+    return feature.tasks;
+  }
+  // v3 format: use taskList or build from tasks.md
+  if (!feature.taskList || feature.taskList.length === 0) {
+    feature.taskList = await parseTasksMd(featureName, cwd);
+  }
+  return feature.taskList;
+}
+
+// ============================================================================
+// syncCounters
+// ============================================================================
+
+/**
+ * After modifying taskList, sync the counter fields back to feature.tasks.
+ * tasks.total is derived from the actual taskList length (not trusted from state).
+ *
+ * @param {Object} feature - Feature state object (mutated in place)
+ */
+export function syncCounters(feature) {
+  if (Array.isArray(feature.tasks)) return; // v2 format — nothing to sync
+  const list = feature.taskList || [];
+  feature.tasks.total = list.length;
+  feature.tasks.completed = list.filter(t => t.status === 'completed').length;
+  feature.tasks.inProgress = list.filter(t => t.status === 'in_progress').length;
+  feature.tasks.pending = list.filter(t => t.status === 'pending').length;
+}