@polymorphism-tech/morph-spec 4.10.3 → 4.10.5

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

@@ -1,10 +1,10 @@
 ---
-name: morph:phase-uiux
+name: morph-phase-uiux
 description: MORPH-SPEC Phase 1.5 (UI/UX). Creates design-system.md, mockups.md, components.md, and flows.md using Playwright/Context7 MCPs. Use after setup for features with frontend UI components, pages, dashboards, forms, wizards, or visual interactions requiring design documentation.
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.3"
+cliVersion: "4.10.5"
 ---
 
 # MORPH UI/UX Design - Phase 1.5
@@ -310,14 +310,14 @@ Use `AskUserQuestion` to capture explicit approval before advancing:
 
 ## Phase Outputs
 
-<!-- morph:outputs:uiux -->
+<!-- morph-outputs:uiux -->
 | Output | Path |
 |--------|------|
 | `uiDesignSystem` | `.morph/features/{feature}/2-ui/design-system.md` |
 | `uiMockups` | `.morph/features/{feature}/2-ui/mockups.md` |
 | `uiComponents` | `.morph/features/{feature}/2-ui/components.md` |
 | `uiFlows` | `.morph/features/{feature}/2-ui/flows.md` |
-<!-- /morph:outputs -->
+<!-- /morph-outputs -->
 
 ---
 

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

@@ -1,10 +1,10 @@
 ---
-name: morph:scope-escalation
+name: morph-scope-escalation
 description: Guided workflow for mid-implementation scope escalation — analyzes complexity discovery, recommends action, and executes phase regression or task expansion
 user-invocable: true
 argument-hint: "[feature-name]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.3"
+cliVersion: "4.10.5"
 ---
 
 # Scope Escalation Workflow

package/framework/workflows/docs/STORY-DRIVEN-DEVELOPMENT.md

@@ -6,7 +6,7 @@
 
 ## 📋 Você Está Aqui
 
-Você acabou de terminar as fases 0-4 do MORPH:
+Você acabou de terminar as fases 0-4 do morph-
 - ✅ Criou `spec.md` (especificação técnica)
 - ✅ Criou `contracts.cs` (interfaces/DTOs)
 - ✅ Criou `tasks.json` (lista de tasks)

package/package.json

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

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

@@ -20,7 +20,7 @@ import { validateTransition } from '../../core/state/phase-state-machine.js';
 import { validateSpecContent, validateTasksContent } from '../../lib/validators/content/content-validator.js';
 import { getWorkflowConfig } from '../../core/workflows/workflow-detector.js';
 import { getStackProfile } from '../../lib/stack/stack-profile.js';
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { emitValidatorDispatch } from '../../lib/validators/shared/emit-validator-dispatch.js';
@@ -339,12 +339,12 @@ export async function advancePhaseCommand(feature, options = {}) {
 
   // === GATE 6: Clarifications Required ===
   // When advancing FROM clarify, clarifications.md must exist.
-  // This enforces that morph:phase-clarify was actually run (not just skipped).
+  // This enforces that morph-phase-clarify was actually run (not just skipped).
   if (currentPhase === 'clarify') {
     const clarPath = join(process.cwd(), '.morph', 'features', feature, '1-design', 'clarifications.md');
     if (!existsSync(clarPath)) {
       console.log(chalk.red('\n✗ Cannot advance from clarify — clarifications.md is missing'));
-      console.log(chalk.yellow('  Run the phase-clarify skill first: /morph:phase-clarify'));
+      console.log(chalk.yellow('  Run the phase-clarify skill first: /morph-phase-clarify'));
       console.log(chalk.gray('  Output expected at: .morph/features/' + feature + '/1-design/clarifications.md\n'));
       process.exit(1);
     }
@@ -373,6 +373,19 @@ export async function advancePhaseCommand(feature, options = {}) {
   const state = loadState();
   state.features[feature].phase = nextPhase;
   state.features[feature].updatedAt = new Date().toISOString();
+
+  // Create the target phase directory so derivePhase() reflects the new phase
+  const PHASE_DIR_MAP = {
+    'proposal': '0-proposal', 'design': '1-design', 'uiux': '2-ui',
+    'plan': '3-plan', 'tasks': '4-tasks', 'implement': '5-implement',
+  };
+  const targetDir = PHASE_DIR_MAP[nextPhase];
+  if (targetDir) {
+    const dirPath = join(featureFolderPath, targetDir);
+    if (!existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true });
+    }
+  }
   if (skippedPhases.length > 0) {
     const existingSkipped = state.features[feature].skippedPhases || [];
     state.features[feature].skippedPhases = [...new Set([...existingSkipped, ...skippedPhases])];
@@ -543,7 +556,7 @@ function designSystemGate(feature, projectPath = '.') {
       'Create a design system with one of these options:',
       '  1. Project-level: .morph/context/design-system.md (shared across features)',
       `  2. Feature-level: ${getOutputPath(feature, 'uiDesignSystem')} (feature-specific)`,
-      '  3. Run /morph:phase-uiux skill to auto-generate from existing codebase',
+      '  3. Run /morph-phase-uiux skill to auto-generate from existing codebase',
       '',
       'Or remove UI agents if they are not needed:',
       `  morph-spec state remove-agent ${feature} blazor-builder`

package/src/commands/state/approve.js

@@ -54,7 +54,7 @@ const program = new Command();
 /**
  * Valid approval gate names
  */
-const VALID_GATES = ['proposal', 'uiux', 'design', 'tasks'];
+const VALID_GATES = ['proposal', 'uiux', 'design', 'plan', 'tasks'];
 
 /**
  * Approve action function - Mark a gate as approved

package/src/commands/state/state.js

@@ -11,6 +11,24 @@ import { logger } from '../../utils/logger.js';
 import * as StateManager from '../../core/state/state-manager.js';
 import { derivePhase } from '../../core/state/state-manager.js';
 
+// ============================================================================
+// Phase Resolution
+// ============================================================================
+
+const PHASE_ORDER_LIST = ['setup', 'proposal', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement', 'sync', 'archived'];
+
+/**
+ * Resolve the effective phase: pick whichever is further ahead between the
+ * stored phase (set by `phase advance`) and the derived phase (from filesystem).
+ */
+function resolvePhase(storedPhase, derivedPhase) {
+  if (!storedPhase) return derivedPhase;
+  if (!derivedPhase) return storedPhase;
+  const storedIdx = PHASE_ORDER_LIST.indexOf(storedPhase);
+  const derivedIdx = PHASE_ORDER_LIST.indexOf(derivedPhase);
+  return storedIdx > derivedIdx ? storedPhase : derivedPhase;
+}
+
 // ============================================================================
 // Phase Protection
 // ============================================================================
@@ -167,7 +185,9 @@ async function getCommand(featureName, options) {
       logger.header(`Feature: ${featureName}`);
       logger.blank();
       const featurePath = join(process.cwd(), '.morph/features', featureName);
-      const phase = derivePhase(featurePath);
+      const derivedPhase = derivePhase(featurePath);
+      // Use stored phase when it's ahead of derived (directory may not exist yet)
+      const phase = resolvePhase(feature.phase, derivedPhase);
       const tasks = feature.tasks || { completed: 0, total: 0 };
       // Prefer taskList.length as total when tasks.total is stale/zero (Problem 3 complement)
       const total = tasks.total || (Array.isArray(feature.taskList) ? feature.taskList.length : 0);
@@ -293,13 +313,14 @@ async function listCommand(options) {
       }[feature.status] || '❓';
 
       const tasks = feature.tasks || {};
-      const progress = (tasks.total || 0) > 0
-        ? `${tasks.completed || 0}/${tasks.total}`
-        : '0/0';
+      const total = tasks.total || (Array.isArray(feature.taskList) ? feature.taskList.length : 0);
+      const progress = total > 0
+        ? `${tasks.completed || 0}/${total}`
+        : '-';
 
       logger.info(`${statusEmoji}  ${chalk.bold(name)}`);
       const featurePath = join(process.cwd(), '.morph/features', name);
-      const featurePhase = derivePhase(featurePath);
+      const featurePhase = resolvePhase(feature.phase, derivePhase(featurePath));
       logger.dim(`   Phase: ${featurePhase.padEnd(16)} │ Tasks: ${progress}`);
       logger.dim(`   Agents: ${(feature.activeAgents || []).slice(0, 5).join(', ') || 'None'}`);
       logger.blank();

package/src/lib/detectors/index.js

@@ -29,21 +29,28 @@ export function detectProject(targetPath, opts = {}) {
 
   try {
     // ── Package.json analysis ──────────────────────────────────────────────
-    const pkgPath = join(targetPath, 'package.json');
-    let pkg = null;
-    if (existsSync(pkgPath)) {
+    // Collect deps from root and common monorepo subfolders
+    const pkgLocations = ['.', 'src/frontend', 'frontend', 'apps/web', 'packages/app'];
+    const allDeps = {};
+    let rootPkg = null;
+    let scripts = [];
+    for (const loc of pkgLocations) {
+      const pkgPath = join(targetPath, loc, 'package.json');
+      if (!existsSync(pkgPath)) continue;
       try {
-        pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        if (loc === '.') rootPkg = pkg;
+        Object.assign(allDeps, pkg.dependencies, pkg.devDependencies);
+        scripts.push(...Object.keys(pkg.scripts || {}));
+        // Track frontend path for config
+        if (loc !== '.' && (pkg.dependencies?.next || pkg.dependencies?.react || pkg.dependencies?.vue)) {
+          structure.frontendPath = loc;
+        }
       } catch { /* invalid JSON */ }
     }
+    const depNames = Object.keys(allDeps);
 
-    if (pkg) {
-      const allDeps = {
-        ...pkg.dependencies,
-        ...pkg.devDependencies,
-      };
-      const depNames = Object.keys(allDeps);
-      const scripts = Object.keys(pkg.scripts || {});
+    if (depNames.length > 0) {
 
       // Stack detection from deps
       if (depNames.includes('next')) {
@@ -54,12 +61,12 @@ export function detectProject(targetPath, opts = {}) {
         structure.stack = 'vue';
       } else if (depNames.includes('express') || depNames.includes('fastify') || depNames.includes('hono')) {
         structure.stack = 'nodejs';
-      } else if (pkg.name) {
+      } else if (rootPkg?.name) {
         structure.stack = 'nodejs';
       }
 
       // UI library detection
-      if (existsSync(join(targetPath, 'components.json')) || depNames.includes('@shadcn/ui')) {
+      if (existsSync(join(targetPath, 'components.json')) || existsSync(join(targetPath, structure.frontendPath || '.', 'components.json')) || depNames.includes('@shadcn/ui')) {
         structure.uiLibrary = 'shadcn';
       } else if (depNames.some(d => d.includes('mudblazor'))) {
         structure.uiLibrary = 'mudblazor';
@@ -79,8 +86,7 @@ export function detectProject(targetPath, opts = {}) {
       }
 
       // Vercel detection
-      if (depNames.includes('vercel') || scripts.includes('vercel') ||
-          scripts.some(s => (pkg.scripts[s] || '').includes('vercel'))) {
+      if (depNames.includes('vercel') || scripts.includes('vercel')) {
         structure.hasVercel = true;
       }
     }
@@ -89,22 +95,34 @@ export function detectProject(targetPath, opts = {}) {
     let hasDotnet = false;
     let hasBlazer = false;
     const csprojLocations = ['.', 'src', 'src/Api', 'src/Web', 'src/backend'];
+
+    function checkCsproj(filePath) {
+      hasDotnet = true;
+      try {
+        const content = readFileSync(filePath, 'utf8');
+        if (content.includes('Microsoft.AspNetCore.Components') || content.includes('Blazor')) {
+          hasBlazer = true;
+        }
+        if (content.includes('Hangfire')) {
+          if (!structure.integrations.includes('hangfire')) structure.integrations.push('hangfire');
+        }
+      } catch { /* ignore */ }
+    }
+
     for (const loc of csprojLocations) {
       try {
         const dir = join(targetPath, loc);
-        if (existsSync(dir)) {
-          const entries = readdirSyncSafe(dir);
-          for (const entry of entries.filter(e => e.endsWith('.csproj'))) {
-            hasDotnet = true;
-            try {
-              const content = readFileSync(join(dir, entry), 'utf8');
-              if (content.includes('Microsoft.AspNetCore.Components') || content.includes('Blazor')) {
-                hasBlazer = true;
-              }
-              if (content.includes('Hangfire')) {
-                if (!structure.integrations.includes('hangfire')) structure.integrations.push('hangfire');
-              }
-            } catch { /* ignore */ }
+        if (!existsSync(dir)) continue;
+        const entries = readdirSyncSafe(dir);
+        // Direct .csproj files
+        for (const e of entries.filter(f => f.endsWith('.csproj'))) {
+          checkCsproj(join(dir, e));
+        }
+        // One level deeper (e.g., src/backend/MyProject/*.csproj)
+        for (const sub of entries) {
+          const subDir = join(dir, sub);
+          for (const e of readdirSyncSafe(subDir).filter(f => f.endsWith('.csproj'))) {
+            checkCsproj(join(subDir, e));
           }
         }
       } catch { /* ignore */ }

package/src/lib/phase-chain/phase-validator.js

@@ -99,7 +99,12 @@ const OUTPUT_PHASE_MAP = {
 function checkOutput(featurePath, outputFile) {
   const phaseDir = OUTPUT_PHASE_MAP[outputFile] || '';
   const filePath = path.join(featurePath, phaseDir, outputFile);
-  return fs.existsSync(filePath);
+  if (fs.existsSync(filePath)) return true;
+  // Fallback: check feature root (some generators place files there instead of phase subdirs)
+  if (phaseDir) {
+    return fs.existsSync(path.join(featurePath, outputFile));
+  }
+  return false;
 }
 
 /**

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

@@ -86,6 +86,10 @@ export async function ensureTaskList(feature, featureName, cwd = process.cwd())
  */
 export function syncCounters(feature) {
   if (Array.isArray(feature.tasks)) return; // v2 format — nothing to sync
+  // Safety: ensure feature.tasks is an object (may be undefined after migration or corruption)
+  if (!feature.tasks || typeof feature.tasks !== 'object') {
+    feature.tasks = { total: 0, completed: 0, inProgress: 0, pending: 0 };
+  }
   const list = feature.taskList || [];
   feature.tasks.total = list.length;
   feature.tasks.completed = list.filter(t => t.status === 'completed').length;

package/src/scripts/setup-infra.js

@@ -141,7 +141,7 @@ export async function setupInfra(targetPath, { _exec = execSync } = {}) {
   const contextReadmePath = join(contextDir, 'README.md');
   if (!(await pathExists(contextReadmePath))) {
     const dirName = targetPath.split(/[\/]/).pop();
-    const readmeContent = `# ${dirName} — Project Context\n\nRun /morph:init to generate project context.\n`;
+    const readmeContent = `# ${dirName} — Project Context\n\nRun /morph-init to generate project context.\n`;
     await writeFile(contextReadmePath, readmeContent);
   }
 

package/src/utils/agents-installer.js

@@ -39,9 +39,9 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
   mkdirSync(targetDir, { recursive: true });
 
   const eligible = agents.filter(a => {
-    if (a.tier !== 1 && a.tier !== 2 && a.tier !== 4) return false;
-    // Tier 4 validators must have a teammate with spawn_prompt
-    if (a.tier === 4 && !a.teammate?.spawn_prompt) return false;
+    if (a.tier < 1 || a.tier > 4) return false;
+    // Must have a teammate with spawn_prompt (except tier-1 orchestrators which always have one)
+    if (a.tier >= 3 && !a.teammate?.spawn_prompt) return false;
     // Filter by stacks if the agent declares them
     const stacks = a.stacks ?? [];
     if (!shouldInstall(stacks, projectTags)) return false;
@@ -50,13 +50,14 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
   let tier1 = 0;
   let tier2 = 0;
+  let tier3 = 0;
   let tier4 = 0;
   const installed = new Set();
 
   // Build the full set of possible filenames for orphan cleanup
   const allPossible = new Set();
   for (const a of agents) {
-    if (a.tier !== 1 && a.tier !== 2 && a.tier !== 4) continue;
+    if (a.tier < 1 || a.tier > 4) continue;
     const slug = a.id ?? a.name?.toLowerCase().replace(/\s+/g, '-');
     const prefix = a.tier === 4 ? 'morph-validator-' : 'morph-';
     allPossible.add(`${prefix}${slug}.md`);
@@ -78,6 +79,7 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
     if (agent.tier === 1) tier1++;
     else if (agent.tier === 2) tier2++;
+    else if (agent.tier === 3) tier3++;
     else if (agent.tier === 4) tier4++;
   }
 
@@ -88,7 +90,7 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     }
   }
 
-  return { tier1, tier2, tier4 };
+  return { tier1, tier2, tier3, tier4 };
 }
 
 /**
@@ -100,16 +102,23 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 const TIER_DEFAULTS = {
   1: {
     model: 'inherit',
-    tools: 'Read, Grep, Glob, Bash, Task',
+    tools: 'Read, Grep, Glob, Bash, Task, Write, Edit',
     maxTurns: 30,
-    skills: ['morph:checklist'],
+    skills: ['morph-checklist'],
     memory: 'project',
   },
   2: {
     model: 'inherit',
-    tools: 'Read, Grep, Glob, Bash',
+    tools: 'Read, Write, Edit, Bash, Glob, Grep',
     maxTurns: 20,
-    skills: ['morph:checklist'],
+    skills: ['morph-checklist'],
+    memory: 'local',
+  },
+  3: {
+    model: 'sonnet',
+    tools: 'Read, Write, Edit, Bash, Glob, Grep',
+    maxTurns: 15,
+    skills: [],
     memory: 'local',
   },
   4: {
@@ -309,8 +318,8 @@ export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
           .map(([id, data]) => ({ id, ...data }));
 
     for (const a of agents) {
-      if (a.tier !== 1 && a.tier !== 2 && a.tier !== 4) continue;
-      if (a.tier === 4 && !a.teammate?.spawn_prompt) continue;
+      if (a.tier < 1 || a.tier > 4) continue;
+      if (a.tier >= 3 && !a.teammate?.spawn_prompt) continue;
       const stacks = a.stacks ?? [];
       if (!shouldInstall(stacks, projectTags)) continue;
 

package/src/utils/banner.js

@@ -45,7 +45,7 @@ export function printInstallBanner({ version, nodeVersion, results = [] }) {
     '',
     sep('Next'),
     `  ${chalk.cyan('1.')} Open your project in Claude Code`,
-    `  ${chalk.cyan('2.')} Run ${chalk.bold.white('/morph:init')}`,
+    `  ${chalk.cyan('2.')} Run ${chalk.bold.white('/morph-init')}`,
     '',
   ].join('\n'));
 }