@polymorphism-tech/morph-spec 4.10.10 → 4.11.1

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.10"
+cliVersion: "4.11.1"
 ---
 
 # MORPH Tasks — Phase 4
@@ -33,8 +33,8 @@ Break the approved specification into executable tasks, define execution order,
 | Count similar existing patterns | **Glob** `**/Services/**/*.cs` | — |
 | Look up implementation patterns | **Context7 MCP** `query_docs()` | **WebSearch** |
 | Create GitHub issues from tasks | **GitHub MCP** `create_issue()` | **Bash** `gh issue create ...` |
-| Render tasks template | **Bash** `npx morph-spec template render docs/tasks ...` | — |
-| Update state with task count | **Bash** `npx morph-spec state set ... tasks.total N` | — |
+| Render tasks template | **Bash** `morph-spec template render docs/tasks ...` | — |
+| Update state with task count | **Bash** `morph-spec state set ... tasks.total N` | — |
 
 **Phase MCPs:** Context7 (estimate complexity), GitHub (create issues).
 
@@ -54,7 +54,7 @@ Break the approved specification into executable tasks, define execution order,
 ### 0. Ensure tasks phase
 
 ```bash
-npx morph-spec state get $ARGUMENTS
+morph-spec state get $ARGUMENTS
 ```
 
 Check the `"phase"` field:
@@ -62,8 +62,8 @@ Check the `"phase"` field:
 **If `"phase": "tasks"`** → correct phase, proceed.
 
 **If `"phase": "clarify"`** → run in sequence:
-1. `npx morph-spec state mark-output $ARGUMENTS clarifications`
-2. `npx morph-spec phase advance $ARGUMENTS` (→ tasks)
+1. `morph-spec state mark-output $ARGUMENTS clarifications`
+2. `morph-spec phase advance $ARGUMENTS` (→ tasks)
 
 **Any other value** → STOP — inconsistent state, report to user.
 
@@ -71,6 +71,14 @@ Check the `"phase"` field:
 
 ---
 
+## MANDATORY: Session Tasks
+
+> **BEFORE reading any files**, analyze the task breakdown workflow and create session tasks.
+>
+> **Rules:** Minimum 2 tasks, typically 3-4. Mark `in_progress` before starting, `completed` after.
+>
+> **Typical tasks:** spec analysis and task definition, tasks.md generation, state update and approval
+
 ### 1. Read all prerequisites in PARALLEL
 
 ```
@@ -82,25 +90,9 @@ Read: .morph/features/{feature}/1-design/spec.md
     + Read: .morph/config/config.json                               (→ architecture.style)
 ```
 
-### 2. Create session tasks for visibility
-
-After detecting `activeAgents` from state, create tasks with agent context:
-
-```
-TaskCreate: "Analyze spec and define tasks"
-  → description: "Active agents: {activeAgents.join(', ')}"
-  → activeForm: "Analyzing spec"
-TaskCreate: "Generate tasks.md"
-  → description: "Architecture: {config.architecture.style}"
-  → activeForm: "Generating tasks.md"
-TaskCreate: "Phase advance"  → activeForm: "Awaiting tasks approval + advancing phase"
-```
-
-> **Note:** Individual T001-T00N tasks are created as native tasks during the implementation phase (`phase-implement`). Here we only keep the 3 high-level tasks for this planning session.
-
 ---
 
-### 3. Entry checkpoint — verify prerequisites
+### 2. Entry checkpoint — verify prerequisites
 
 Before starting the breakdown:
 
@@ -114,8 +106,8 @@ Before starting the breakdown:
 If any checkbox is NOT checked → return to corresponding phase and resolve.
 
 ```bash
-npx morph-spec state get $ARGUMENTS
-npx morph-spec approval-status $ARGUMENTS
+morph-spec state get $ARGUMENTS
+morph-spec approval-status $ARGUMENTS
 ```
 
 ---
@@ -245,8 +237,8 @@ If there are Azure resources, add Bicep and migration tasks.
 ### Step 8: Update State
 
 ```bash
-npx morph-spec state set $ARGUMENTS tasks.total {N}
-npx morph-spec state mark-output $ARGUMENTS tasks
+morph-spec state set $ARGUMENTS tasks.total {N}
+morph-spec state mark-output $ARGUMENTS tasks
 ```
 
 ## Outputs
@@ -273,8 +265,8 @@ Use `AskUserQuestion` to capture explicit approval before advancing. This gate p
 
 - **"Approve and implement"** →
   ```bash
-  npx morph-spec approve $ARGUMENTS tasks
-  npx morph-spec phase advance $ARGUMENTS
+  morph-spec approve $ARGUMENTS tasks
+  morph-spec phase advance $ARGUMENTS
   ```
 - **"I have feedback" or "Other"** → apply the feedback and repeat this PAUSE
 

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.10"
+cliVersion: "4.11.1"
 ---
 
 # MORPH UI/UX Design - Phase 1.5
@@ -36,9 +36,9 @@ Conditional phase for features with front-end. Collects UI/UX requirements, gene
 | Inspect page structure | **Playwright MCP** `browser_snapshot()` | **WebFetch** + manual parse |
 | Test responsive layout | **Playwright MCP** `browser_resize()` + `browser_take_screenshot()` | Manual testing |
 | External design references | **WebSearch** + **WebFetch** | — |
-| Render UI templates | **Bash** `npx morph-spec template render docs/ui-mockups ...` | — |
-| Generate design system from existing CSS | **Bash** `npx morph-spec generate design-system --scan` | — |
-| Update state | **Bash** `npx morph-spec state mark-output ...` | — |
+| Render UI templates | **Bash** `morph-spec template render docs/ui-mockups ...` | — |
+| Generate design system from existing CSS | **Bash** `morph-spec generate design-system --scan` | — |
+| Update state | **Bash** `morph-spec state mark-output ...` | — |
 
 **MCPs for this phase:** Playwright (preview, inspection, responsiveness), Context7 (component docs).
 
@@ -54,7 +54,7 @@ Conditional phase for features with front-end. Collects UI/UX requirements, gene
 ### Step 0: Ensure uiux phase
 
 ```bash
-npx morph-spec state get $ARGUMENTS
+morph-spec state get $ARGUMENTS
 ```
 
 Check the `"phase"` field in the output:
@@ -62,7 +62,7 @@ Check the `"phase"` field in the output:
 **If `"phase": "uiux"`** → correct phase, proceed.
 
 **If `"phase": "setup"`** → execute:
-1. `npx morph-spec phase advance $ARGUMENTS` (→ uiux)
+1. `morph-spec phase advance $ARGUMENTS` (→ uiux)
 
 **Any other value** → do not proceed — inconsistent state, report to user.
 
@@ -129,12 +129,20 @@ Print: `✓ Design system generated from [N] tokens — .morph/context/design-sy
 
 > **Design system is mandatory** for UI features. The implementation gate (Phase 5) will block if no design system exists.
 
+## MANDATORY: Session Tasks
+
+> **BEFORE starting UI/UX 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:** design system check, user input collection, UI library selection, visual mockup, deliverable generation, accessibility validation, approval
+
 ### Step 1: Detect If Phase Is Needed
 
 Check if active agents include `ui-designer`:
 
 ```bash
-npx morph-spec state get $ARGUMENTS
+morph-spec state get $ARGUMENTS
 ```
 
 If `ui-designer` is NOT in `activeAgents`, skip this phase and continue to Phase 2 (Design).
@@ -290,7 +298,7 @@ mcp__plugin_playwright_playwright__browser_take_screenshot({}) → save as .morp
 
 Create the following files in `.morph/features/$ARGUMENTS/`:
 
-> **Use templates:** Use `npx morph-spec template render` to generate files from templates in `.morph/framework/templates/docs/`. Available templates: `ui-design-system`, `ui-mockups`, `ui-components`, `ui-flows`.
+> **Use templates:** Use `morph-spec template render` to generate files from templates in `.morph/framework/templates/docs/`. Available templates: `ui-design-system`, `ui-mockups`, `ui-components`, `ui-flows`.
 
 #### 4.1. `ui-design-system.md`
 
@@ -367,17 +375,17 @@ Document in UI files:
 ### Step 6: Update State
 
 ```bash
-npx morph-spec state mark-output $ARGUMENTS ui-design-system
-npx morph-spec state mark-output $ARGUMENTS ui-mockups
-npx morph-spec state mark-output $ARGUMENTS ui-components
-npx morph-spec state mark-output $ARGUMENTS ui-flows
+morph-spec state mark-output $ARGUMENTS ui-design-system
+morph-spec state mark-output $ARGUMENTS ui-mockups
+morph-spec state mark-output $ARGUMENTS ui-components
+morph-spec state mark-output $ARGUMENTS ui-flows
 ```
 
 > **Format note:** The `mark-output` commands accept BOTH kebab-case (`ui-design-system`)
 > AND camelCase (`uiDesignSystem`). Both formats work equally! Use whichever is more
 > comfortable for you. Examples:
-> - `npx morph-spec state mark-output my-feature uiDesignSystem`
-> - `npx morph-spec state mark-output my-feature ui-design-system`
+> - `morph-spec state mark-output my-feature uiDesignSystem`
+> - `morph-spec state mark-output my-feature ui-design-system`
 
 ## Generated Outputs
 
@@ -421,8 +429,8 @@ Use `AskUserQuestion` to capture explicit approval before advancing:
 
 - **"Approve UI/UX"** →
   ```bash
-  npx morph-spec approve $ARGUMENTS uiux
-  npx morph-spec phase advance $ARGUMENTS
+  morph-spec approve $ARGUMENTS uiux
+  morph-spec phase advance $ARGUMENTS
   ```
 - **"I have feedback" or "Other"** → apply the received feedback and repeat this PAUSE
 

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.10"
+cliVersion: "4.11.1"
 ---
 
 # Scope Escalation Workflow
@@ -57,7 +57,7 @@ Use `AskUserQuestion` to gather the details:
 Run dry-run analysis:
 
 ```bash
-npx morph-spec scope escalate <feature> --task <id> --reason "<reason>" --dry-run
+morph-spec scope escalate <feature> --task <id> --reason "<reason>" --dry-run
 ```
 
 Read the recommendation output. Additionally:
@@ -116,17 +116,17 @@ Based on approved action:
 
 **For expansion (low impact):**
 ```bash
-npx morph-spec task expand <feature> <task-id> --into "T017a: <title>" "T017b: <title>" ...
+morph-spec task expand <feature> <task-id> --into "T017a: <title>" "T017b: <title>" ...
 ```
 
 **For regression (medium/high impact):**
 ```bash
-npx morph-spec scope escalate <feature> --task <id> --reason "<reason>"
+morph-spec scope escalate <feature> --task <id> --reason "<reason>"
 ```
 
 Or with target override:
 ```bash
-npx morph-spec scope escalate <feature> --task <id> --reason "<reason>" --target design
+morph-spec scope escalate <feature> --task <id> --reason "<reason>" --target design
 ```
 
 ### Step 6: GUIDE Next Steps

package/framework/workflows/README.md

@@ -371,7 +371,7 @@ Keywords like: `bicep`, `azure`, `deploy`, `docker`, `kubernetes`, `infrastructu
 
 ```bash
 # When creating a feature
-npx morph-spec feature create user-pagination \
+morph-spec feature create user-pagination \
   --request "add pagination to users table"
 
 # System automatically:
@@ -385,7 +385,7 @@ npx morph-spec feature create user-pagination \
 
 ```bash
 # Analyze request without creating feature
-npx morph-spec detect-workflow "implement complete authentication system"
+morph-spec detect-workflow "implement complete authentication system"
 
 # Output:
 Detected Workflow: full-morph (92% confidence)
@@ -407,7 +407,7 @@ Alternative Workflows:
 ### JSON Output (for automation)
 
 ```bash
-npx morph-spec detect-workflow "add pagination" --json
+morph-spec detect-workflow "add pagination" --json
 
 # Output:
 {
@@ -435,17 +435,17 @@ npx morph-spec detect-workflow "add pagination" --json
 
 ```bash
 # Force specific workflow
-npx morph-spec state set user-auth workflow full-morph
+morph-spec state set user-auth workflow full-morph
 
 # Re-detect after request changes
-npx morph-spec state detect-workflow user-auth \
+morph-spec state detect-workflow user-auth \
   "implement basic login only (no OAuth)"
 ```
 
 ### View Current Workflow
 
 ```bash
-npx morph-spec state get user-auth workflow
+morph-spec state get user-auth workflow
 
 # Output:
 Workflow: standard
@@ -594,7 +594,7 @@ Create `framework/workflows/docs/my-workflow.md` explaining the workflow.
 **3. Test Detection:**
 
 ```bash
-npx morph-spec detect-workflow "request with custom-keyword"
+morph-spec detect-workflow "request with custom-keyword"
 ```
 
 ### Modifying Existing Workflows
@@ -675,7 +675,7 @@ Phases: Quick Analysis → Implement
 
 **User Experience:**
 ```bash
-npx morph-spec feature create login-typo --request "fix typo in login button"
+morph-spec feature create login-typo --request "fix typo in login button"
 
 # Output:
 ✓ Detected workflow: fast-track
@@ -683,7 +683,7 @@ npx morph-spec feature create login-typo --request "fix typo in login button"
 📝 Write quick analysis (1 paragraph) and implement
 
 # User writes quick analysis, then:
-npx morph-spec phase advance login-typo
+morph-spec phase advance login-typo
 
 # Output:
 ⏩ Skipping: setup, uiux, design, clarify, tasks, sync
@@ -704,7 +704,7 @@ Phases: PROPOSAL → DESIGN → TASKS → IMPLEMENT
 
 **User Experience:**
 ```bash
-npx morph-spec feature create user-pagination \
+morph-spec feature create user-pagination \
   --request "add pagination to users table"
 
 # Output:
@@ -727,7 +727,7 @@ Phases: ALL (9 phases mandatory)
 
 **User Experience:**
 ```bash
-npx morph-spec feature create user-auth \
+morph-spec feature create user-auth \
   --request "implement complete authentication system with OAuth"
 
 # Output:
@@ -750,7 +750,7 @@ Phases: PROTOTYPE ANALYSIS → TASKS → IMPLEMENT
 
 **User Experience:**
 ```bash
-npx morph-spec feature create dashboard-screens \
+morph-spec feature create dashboard-screens \
   --request "implement screens from Figma design"
 
 # Output:
@@ -774,7 +774,7 @@ Phases: VISUAL ANALYSIS → DESIGN SYSTEM → IMPLEMENT
 
 **User Experience:**
 ```bash
-npx morph-spec feature create dashboard-redesign \
+morph-spec feature create dashboard-redesign \
   --request "redesign dashboard to look more modern"
 
 # Output:
@@ -794,13 +794,13 @@ npx morph-spec feature create dashboard-redesign \
 
 **Solution 1: Provide more context**
 ```bash
-npx morph-spec feature create simple-fix \
+morph-spec feature create simple-fix \
   --request "add pagination (simple, already have paginator component)"
 ```
 
 **Solution 2: Manual override**
 ```bash
-npx morph-spec state set my-feature workflow standard
+morph-spec state set my-feature workflow standard
 ```
 
 **Solution 3: Improve keywords**
@@ -849,7 +849,7 @@ If this happens often, add keywords to workflow config:
 **Alternative:**
 Use `detect-workflow` first to see both options:
 ```bash
-npx morph-spec detect-workflow "add authentication"
+morph-spec detect-workflow "add authentication"
 
 # Review both workflows
 # Decide based on:
@@ -891,13 +891,13 @@ Create `framework/workflows/configs/blazor-standard.json`:
 **Solution 1: Force phase**
 ```bash
 # Manually go to UIUX phase
-npx morph-spec phase set my-feature uiux
+morph-spec phase set my-feature uiux
 ```
 
 **Solution 2: Override workflow**
 ```bash
 # Use full-morph (includes all phases)
-npx morph-spec state set my-feature workflow full-morph
+morph-spec state set my-feature workflow full-morph
 ```
 
 **Solution 3: Document in decisions.md**

package/framework/workflows/docs/enforcement-pipeline.md

@@ -113,7 +113,7 @@ export function loadStandardsForAgent(agentId, projectPath) {
 
 ```bash
 # Standards auto-injected when running detect-agents with --json
-npx morph-spec detect-agents --json "create blazor dashboard"
+morph-spec detect-agents --json "create blazor dashboard"
 
 # Output includes standardsSummary for each agent:
 {

package/framework/workflows/docs/full-morph.md

@@ -18,7 +18,7 @@
 6. Ativar agentes baseado em stack + keywords
 
 ### FASE 0: PROPOSAL
-1. `npx morph-spec detect "{user-request}"`
+1. `morph-spec detect "{user-request}"`
 2. Analisar solicitação, identificar stack, estimar complexidade
 3. Gerar proposal.md, registrar agentes no state.json
 - **⛔ PAUSA:** 3 itens (1 ação + 1 pergunta + 1 sugestão)
@@ -55,7 +55,7 @@
 
 ### FASE 5: IMPLEMENT
 1. Implementar task por task
-2. `npx morph-spec task done {feature} {task-id}` após cada task
+2. `morph-spec task done {feature} {task-id}` após cada task
 3. Framework gerencia checkpoints automaticamente (a cada 3 tasks)
 4. Gerar recap.md ao final
 

package/package.json

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

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

@@ -19,7 +19,7 @@
 import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { loadState, stateExists } from '../../core/state/state-manager.js';
+import { loadState, stateExists, logDispatch } from '../../core/state/state-manager.js';
 import { buildAgentBriefing, buildValidatorPrompt } from '../../lib/standards/digest-builder.js';
 import { agentIdToSubagentType } from '../../utils/agent-id-mapper.js';
 import { shouldInstall, getProjectTags } from '../../lib/stack-filter.js';
@@ -434,6 +434,30 @@ export async function dispatchAgentsCommand(featureName, phase, options = {}) {
     if (options.mode) dispatchOpts.mode = options.mode;
     const config = await buildDispatchConfig(process.cwd(), featureName, normalizedPhase, dispatchOpts);
 
+    // Log dispatch to state.json so enforcement gates can verify it happened
+    if (config.agents?.length > 0) {
+      try {
+        logDispatch(featureName, {
+          timestamp: new Date().toISOString(),
+          phase: normalizedPhase,
+          mode: config.mode,
+          agents: config.agents.map(a => {
+            const groupEntry = Object.entries(config.taskGroups || {}).find(
+              ([, g]) => g.agentId === a.id
+            );
+            return {
+              id: a.id,
+              subagentType: a.subagentType,
+              group: a.parallelGroup,
+              tasks: groupEntry ? groupEntry[1].tasks : [],
+            };
+          }),
+        });
+      } catch {
+        // Non-blocking — dispatch output still succeeds even if log fails
+      }
+    }
+
     if (options.table) {
       // Human-readable table format
       console.log(chalk.bold(`\n  Dispatch Config — ${featureName} (${normalizedPhase})`));

package/src/commands/project/doctor.js

@@ -947,13 +947,12 @@ export async function doctorCommand(options = {}) {
         logger.dim('  PowerShell (as Administrator):');
         console.log(chalk.gray(`    [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";${prefix}", "User")`));
         logger.blank();
-        logger.dim('  Or use npx instead:');
-        logger.dim('    npx @polymorphism-tech/morph-spec init');
+        logger.dim('  Then open a new terminal.');
         logger.blank();
       } else if (!inPath) {
         logger.info('morph-spec not in PATH:');
-        logger.dim('  Use npx instead:');
-        logger.dim('    npx @polymorphism-tech/morph-spec init');
+        logger.dim('  Open a new terminal — the installer adds npm global to $PROFILE automatically.');
+        logger.dim('  If it persists, add manually: npm config get prefix → add to PATH');
         logger.blank();
       }
     }

package/src/commands/project/status.js

@@ -236,7 +236,14 @@ export async function statusCommand(featureName, options = {}) {
     process.exit(1);
   }
 
-  const feature = getFeature(featureName);
+  let feature;
+  try {
+    feature = getFeature(featureName);
+  } catch (err) {
+    console.error(chalk.red(`✗ Error: ${err.message}`));
+    console.error(chalk.gray('Run \'morph-spec doctor\' to diagnose or fix your state.json'));
+    process.exit(1);
+  }
   if (!feature) {
     console.error(chalk.red(`✗ Error: Feature '${featureName}' not found`));
     console.error(chalk.gray(`Run 'morph-spec state get ${featureName}' to check if feature exists`));

package/src/commands/scope/escalate.js

@@ -13,7 +13,7 @@
 import chalk from 'chalk';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
-import { loadState, saveState } from '../../core/state/state-manager.js';
+import { loadState, saveState, derivePhase } from '../../core/state/state-manager.js';
 import { analyzeImpact } from '../../lib/scope/impact-analyzer.js';
 
 /**
@@ -35,8 +35,10 @@ export async function escalateScope(featureName, options) {
     return { success: false, error: `Feature "${featureName}" not found in state.json` };
   }
 
-  if (feature.phase !== 'implement') {
-    return { success: false, error: `Scope escalation only available during implement phase (current: ${feature.phase})` };
+  const featurePath = join(process.cwd(), '.morph', 'features', featureName);
+  const currentPhase = feature.phase || derivePhase(featurePath);
+  if (currentPhase !== 'implement') {
+    return { success: false, error: `Scope escalation only available during implement phase (current: ${currentPhase})` };
   }
 
   // Read tasks.md

package/src/commands/tasks/task.js

@@ -42,6 +42,8 @@ export async function taskDoneCommand(featureName, taskIds, options) {
   try {
     const args = ['done', featureName, ...taskIds];
     if (options.skipValidation) args.push('--skip-validation');
+    if (options.reason) args.push('--reason', options.reason);
+    if (options.note) args.push('--note', options.note);
     if (options.dryRun) args.push('--dry-run');
     await executeTaskManager(args);
   } catch (error) {
@@ -64,6 +66,58 @@ export async function taskStartCommand(featureName, taskId, options) {
   }
 }
 
+/**
+ * Bulk-start tasks command
+ */
+export async function taskBulkStartCommand(featureName, range, options) {
+  try {
+    const args = ['bulk-start', featureName];
+    if (range) args.push(range);
+    if (options.all) args.push('--all');
+    if (options.from) args.push('--from', options.from);
+    if (options.to) args.push('--to', options.to);
+    await executeTaskManager(args);
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Bulk-done tasks command
+ */
+export async function taskBulkDoneCommand(featureName, range, options) {
+  try {
+    const args = ['bulk-done', featureName];
+    if (range) args.push(range);
+    if (options.all) args.push('--all');
+    if (options.from) args.push('--from', options.from);
+    if (options.to) args.push('--to', options.to);
+    if (options.skipValidation) args.push('--skip-validation');
+    if (options.reason) args.push('--reason', options.reason);
+    if (options.note) args.push('--note', options.note);
+    if (options.dryRun) args.push('--dry-run');
+    await executeTaskManager(args);
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Annotate a task with a note
+ */
+export async function taskAnnotateCommand(featureName, taskId, text, options) {
+  try {
+    const args = ['annotate', featureName, taskId, text];
+    if (options.type) args.push('--type', options.type);
+    await executeTaskManager(args);
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+
 /**
  * Get next task command
  */

package/src/commands/validation/validate-feature.js

@@ -70,6 +70,19 @@ const PHASE_OUTPUTS = {
   implement: ['spec.md', 'contracts.cs', 'tasks.md']
 };
 
+/**
+ * Phase-to-folder mapping (filesystem convention)
+ */
+const PHASE_FOLDERS = {
+  proposal: '0-proposal',
+  uiux: '2-ui',
+  design: '1-design',
+  clarify: '1-design',
+  plan: '3-plan',
+  tasks: '4-tasks',
+  implement: '5-implement',
+};
+
 /**
  * Validate a single output file
  */
@@ -254,12 +267,28 @@ export async function validateFeatureCommand(featureName, options = {}) {
       process.exit(1);
     }
   } else {
-    // Validate all existing outputs
-    outputFiles = fs.readdirSync(featurePath).filter(f => f.endsWith('.md') || f.endsWith('.cs'));
+    // Validate all existing outputs across all phase folders
+    outputFiles = [];
+    const entries = fs.readdirSync(featurePath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const subDir = path.join(featurePath, entry.name);
+        const files = fs.readdirSync(subDir).filter(f => f.endsWith('.md') || f.endsWith('.cs'));
+        outputFiles.push(...files.map(f => ({ file: f, dir: subDir })));
+      } else if (entry.name.endsWith('.md') || entry.name.endsWith('.cs')) {
+        outputFiles.push({ file: entry.name, dir: featurePath });
+      }
+    }
   }
 
+  // Resolve phase folder for path lookup
+  const phaseFolder = phase ? PHASE_FOLDERS[phase] : null;
+  const searchPath = phaseFolder ? path.join(featurePath, phaseFolder) : featurePath;
+
   // Run validation
-  const results = outputFiles.map(file => validateOutput(featurePath, file));
+  const results = phase
+    ? outputFiles.map(file => validateOutput(searchPath, file))
+    : outputFiles.map(({ file, dir }) => validateOutput(dir, file));
   const schemaWarnings = crossValidateSchema(featurePath);
 
   // Aggregate results