@polymorphism-tech/morph-spec 4.3.0 → 4.3.1

package/src/commands/project/doctor.js

@@ -53,7 +53,7 @@ function getNpmGlobalPrefix() {
 }
 
 // lib files
-const V3_LIB_FILES = [
+const REQUIRED_LIB_FILES = [
   'src/lib/analytics/analytics-engine.js',
   'src/lib/tracking/artifact-trail.js',
   'src/lib/context/context-bundler.js',
@@ -71,22 +71,22 @@ const V3_LIB_FILES = [
   'src/lib/trust/trust-manager.js'
 ];
 
-// v3.0 command files (top-level new commands)
-const V3_COMMAND_FILES = [
-  'src/commands/agents-fuse.js',
-  'src/commands/analytics.js',
-  'src/commands/context-prime.js',
-  'src/commands/core-four.js',
-  'src/commands/mcp.js',
-  'src/commands/micro-agent.js',
-  'src/commands/squad-template.js',
-  'src/commands/thread-template.js',
-  'src/commands/threads.js',
-  'src/commands/trust.js'
+// command files
+const REQUIRED_COMMAND_FILES = [
+  'src/commands/agents/agents-fuse.js',
+  'src/commands/analytics/analytics.js',
+  'src/commands/context/context-prime.js',
+  'src/commands/context/core-four.js',
+  'src/commands/mcp/mcp.js',
+  'src/commands/agents/micro-agent.js',
+  'src/commands/agents/squad-template.js',
+  'src/commands/threads/thread-template.js',
+  'src/commands/threads/threads.js',
+  'src/commands/trust/trust.js'
 ];
 
-// v3.0 HOP templates (meta-prompts)
-const V3_HOP_TEMPLATES = [
+// HOP templates (meta-prompts)
+const HOP_TEMPLATES = [
   'framework/templates/meta-prompts/squad-leaders/backend-squad.md',
   'framework/templates/meta-prompts/squad-leaders/frontend-squad.md',
   'framework/templates/meta-prompts/parallel-workers/parallel-worker.md',
@@ -98,11 +98,11 @@ const V3_HOP_TEMPLATES = [
   'framework/templates/meta-prompts/validators/pre-commit-validator.md',
   'framework/templates/meta-prompts/fusion/fusion-agent.md',
   'framework/templates/meta-prompts/fusion/fusion-aggregator.md',
-  'framework/templates/meta-prompts/REGISTRY.json'
+  'framework/templates/REGISTRY.json'
 ];
 
-// v3.0 new standards (framework-level)
-const V3_STANDARDS = [
+// framework standards
+const FRAMEWORK_STANDARDS = [
   'framework/standards/observability/monitoring.md',
   'framework/standards/observability/logging.md',
   'framework/standards/observability/tracing.md',
@@ -128,8 +128,8 @@ const V3_STANDARDS = [
   'framework/standards/workflows/parallel-execution.md'
 ];
 
-// v3.0 new agents expected in agents.json
-const V3_NEW_AGENTS = [
+// required agents expected in agents.json
+const REQUIRED_AGENTS = [
   'vector-search-expert',
   'thread-orchestrator',
   'context-optimizer',
@@ -137,10 +137,10 @@ const V3_NEW_AGENTS = [
 ];
 
 /**
- * Run v3.0-specific health checks
+ * Run full health checks
  */
-async function doctorV3Command(frameworkRoot) {
-  console.log(chalk.bold('\n🔬 MORPH-SPEC v3.0 Health Check\n'));
+async function doctorFullCommand(frameworkRoot) {
+  console.log(chalk.bold('\n🔬 MORPH-SPEC Full Health Check\n'));
   console.log('─'.repeat(60));
 
   const checks = [];
@@ -157,55 +157,55 @@ async function doctorV3Command(frameworkRoot) {
     }
   };
 
-  // ── 1. v3.0 Lib Files (15) ──────────────────────────────────────────────
-  console.log(chalk.cyan('\n  src/lib/ — v3.0 Core Libraries (15 files)'));
+  // ── 1. Core Libraries ───────────────────────────────────────────────────
+  console.log(chalk.cyan(`\n  src/lib/ — Core Libraries (${REQUIRED_LIB_FILES.length} files)`));
   const missingLibs = [];
-  for (const f of V3_LIB_FILES) {
+  for (const f of REQUIRED_LIB_FILES) {
     if (!(await pathExists(join(frameworkRoot, f)))) missingLibs.push(f.split('/').pop());
   }
-  check(`v3.0 lib files (${V3_LIB_FILES.length - missingLibs.length}/${V3_LIB_FILES.length})`,
+  check(`Core Libraries (${REQUIRED_LIB_FILES.length - missingLibs.length}/${REQUIRED_LIB_FILES.length})`,
     missingLibs.length === 0, false,
     missingLibs.length > 0 ? `missing: ${missingLibs.join(', ')}` : '');
 
-  // ── 2. v3.0 Command Files (11) ──────────────────────────────────────────
-  console.log(chalk.cyan('\n  src/commands/ — v3.0 Command Files (11 files)'));
+  // ── 2. Command Files ─────────────────────────────────────────────────────
+  console.log(chalk.cyan(`\n  src/commands/ — Command Files (${REQUIRED_COMMAND_FILES.length} files)`));
   const missingCmds = [];
-  for (const f of V3_COMMAND_FILES) {
+  for (const f of REQUIRED_COMMAND_FILES) {
     if (!(await pathExists(join(frameworkRoot, f)))) missingCmds.push(f.split('/').pop());
   }
-  check(`v3.0 command files (${V3_COMMAND_FILES.length - missingCmds.length}/${V3_COMMAND_FILES.length})`,
+  check(`Command Files (${REQUIRED_COMMAND_FILES.length - missingCmds.length}/${REQUIRED_COMMAND_FILES.length})`,
     missingCmds.length === 0, false,
     missingCmds.length > 0 ? `missing: ${missingCmds.join(', ')}` : '');
 
-  // ── 3. HOP Templates (12) ───────────────────────────────────────────────
-  console.log(chalk.cyan('\n  framework/templates/meta-prompts/ — HOP Templates (12)'));
+  // ── 3. HOP Templates ────────────────────────────────────────────────────
+  console.log(chalk.cyan(`\n  framework/templates/meta-prompts/ — HOP Templates (${HOP_TEMPLATES.length})`));
   const missingHOPs = [];
-  for (const f of V3_HOP_TEMPLATES) {
+  for (const f of HOP_TEMPLATES) {
     if (!(await pathExists(join(frameworkRoot, f)))) missingHOPs.push(f.split('/').pop());
   }
-  check(`HOP templates (${V3_HOP_TEMPLATES.length - missingHOPs.length}/${V3_HOP_TEMPLATES.length})`,
+  check(`HOP Templates (${HOP_TEMPLATES.length - missingHOPs.length}/${HOP_TEMPLATES.length})`,
     missingHOPs.length === 0, false,
     missingHOPs.length > 0 ? `missing: ${missingHOPs.join(', ')}` : '');
 
-  // ── 4. New Standards (23) ───────────────────────────────────────────────
-  console.log(chalk.cyan('\n  framework/standards/ — v3.0 Standards (23 files)'));
+  // ── 4. Framework Standards ───────────────────────────────────────────────
+  console.log(chalk.cyan(`\n  framework/standards/ — Framework Standards (${FRAMEWORK_STANDARDS.length} files)`));
   const missingStds = [];
-  for (const f of V3_STANDARDS) {
+  for (const f of FRAMEWORK_STANDARDS) {
     if (!(await pathExists(join(frameworkRoot, f)))) missingStds.push(f.replace('framework/standards/', ''));
   }
-  check(`v3.0 standards (${V3_STANDARDS.length - missingStds.length}/${V3_STANDARDS.length})`,
+  check(`Framework Standards (${FRAMEWORK_STANDARDS.length - missingStds.length}/${FRAMEWORK_STANDARDS.length})`,
     missingStds.length === 0, false,
     missingStds.length > 0 ? `missing: ${missingStds.join(', ')}` : '');
 
-  // ── 5. New Agents in agents.json ────────────────────────────────────────
-  console.log(chalk.cyan('\n  .morph/config/agents.json — v3.0 Agents (4 new)'));
+  // ── 5. Required Agents in agents.json ───────────────────────────────────
+  console.log(chalk.cyan(`\n  .morph/config/agents.json — Required Agents (${REQUIRED_AGENTS.length})`));
   const agentsPath = join(frameworkRoot, '.morph/config/agents.json');
   if (await pathExists(agentsPath)) {
     try {
       const agentsConfig = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
       const agents = agentsConfig.agents || {};
-      const missingAgents = V3_NEW_AGENTS.filter(id => !agents[id]);
-      check(`v3.0 agents (${V3_NEW_AGENTS.length - missingAgents.length}/${V3_NEW_AGENTS.length})`,
+      const missingAgents = REQUIRED_AGENTS.filter(id => !agents[id]);
+      check(`Required Agents (${REQUIRED_AGENTS.length - missingAgents.length}/${REQUIRED_AGENTS.length})`,
         missingAgents.length === 0, false,
         missingAgents.length > 0 ? `missing: ${missingAgents.join(', ')}` : '');
     } catch {
@@ -220,15 +220,15 @@ async function doctorV3Command(frameworkRoot) {
   const ztPath = join(frameworkRoot, 'framework/workflows/configs/zero-touch.json');
   check('zero-touch.json workflow config', await pathExists(ztPath));
 
-  // ── 8. state.json v3.0 version ──────────────────────────────────────────
+  // ── 8. state.json schema version ────────────────────────────────────────
   console.log(chalk.cyan('\n  .morph/state.json — Schema Version'));
   const statePath = join(frameworkRoot, '.morph/state.json');
   if (await pathExists(statePath)) {
     try {
       const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
-      const isV3 = state.version === '3.0.0';
-      check(`state.json schema (v${state.version})`, isV3, true,
-        isV3 ? '' : 'run: morph-spec migrate v2-to-v3');
+      const isCurrent = state.version === '3.0.0';
+      check(`state.json schema (${state.version})`, isCurrent, true,
+        isCurrent ? '' : 'run: morph-spec state init --force');
     } catch {
       check('state.json parse', false, false, 'invalid JSON');
     }
@@ -254,20 +254,20 @@ async function doctorV3Command(frameworkRoot) {
   const total = checks.length;
 
   if (hasErrors) {
-    console.log(chalk.red(`\n❌ ${passed}/${total} checks passed — run "morph-spec migrate v2-to-v3" to fix\n`));
+    console.log(chalk.red(`\n❌ ${passed}/${total} checks passed — see errors above\n`));
     process.exit(1);
   } else if (hasWarnings) {
     console.log(chalk.yellow(`\n⚠️  ${passed}/${total} checks passed (warnings only)\n`));
   } else {
-    console.log(chalk.green(`\n✅ ${passed}/${total} — All v3.0 checks passed!\n`));
+    console.log(chalk.green(`\n✅ ${passed}/${total} — All checks passed!\n`));
   }
 }
 
 export async function doctorCommand(options = {}) {
-  // v3-specific check mode
-  if (options.v3) {
+  // full health check mode
+  if (options.full) {
     const frameworkRoot = process.cwd();
-    return doctorV3Command(frameworkRoot);
+    return doctorFullCommand(frameworkRoot);
   }
 
   const targetPath = process.cwd();

package/src/commands/project/init.js

@@ -18,6 +18,7 @@ import {
   createDirectoryLink
 } from '../../utils/file-copier.js';
 import { saveProjectMorphVersion, getInstalledCLIVersion } from '../../utils/version-checker.js';
+import { installClaudeHooks } from '../../utils/hooks-installer.js';
 import { AutoContextOrchestrator } from '../../core/orchestrator.js';
 import { detectClaudeCode } from '../../llm/environment-detector.js';
 
@@ -155,8 +156,9 @@ Run \`morph-spec detect\` to analyze your project.
     }
 
     // 9. Copy .claude commands and create symlinks for skills
+    // Source: framework root .claude/ (canonical for all stacks)
     spinner.text = 'Setting up Claude Code integration...';
-    const claudeSrc = join(contentDir, '.claude');
+    const claudeSrc = join(import.meta.dirname, '..', '..', '..', '.claude');
     const claudeDest = join(targetPath, '.claude');
 
     let symlinkCount = 0;
@@ -217,6 +219,10 @@ Run \`morph-spec detect\` to analyze your project.
       }
     }
 
+    // 9b. Install/update agent-teams hooks in .claude/settings.local.json
+    spinner.text = 'Installing Claude Code hooks...';
+    const hooksInstalled = await installClaudeHooks(targetPath);
+
     // 10. Save version info
     spinner.text = 'Saving version info...';
     const cliVersion = getInstalledCLIVersion();
@@ -251,6 +257,7 @@ Run \`morph-spec detect\` to analyze your project.
     logger.dim(`  ✓ .morph/templates/ (Bicep, integrations, saas, ...)`);
     logger.dim(`  ✓ .morph/project/ (context, standards, outputs)`);
     logger.dim(`  ✓ .claude/commands/ (slash commands)`);
+    logger.dim(`  ✓ .claude/settings.local.json (agent-teams hooks)`);
 
     if (symlinkCount > 0) {
       const linkType = process.platform === 'win32' ? 'junction-linked' : 'symlinked';

package/src/commands/project/update.js

@@ -1,4 +1,7 @@
-import { join } from 'path';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 import fs from 'fs-extra';
 import ora from 'ora';
 import chalk from 'chalk';
@@ -19,6 +22,7 @@ import {
   getUpdateInstructions,
   detectInstallMethod
 } from '../../utils/version-checker.js';
+import { installClaudeHooks } from '../../utils/hooks-installer.js';
 import { AutoContextOrchestrator } from '../../core/orchestrator.js';
 import { detectClaudeCode } from '../../llm/environment-detector.js';
 
@@ -117,8 +121,9 @@ export async function updateCommand(options) {
     }
 
     // Update .claude commands and skills
+    // Source: framework root .claude/ (canonical for all stacks)
     updateSpinner.text = 'Updating Claude commands and skills...';
-    const claudeSrc = join(contentDir, '.claude');
+    const claudeSrc = join(__dirname, '..', '..', '..', '.claude');
     const claudeDest = join(targetPath, '.claude');
     if (await pathExists(claudeSrc)) {
       // Copy commands (always copy, these are small)
@@ -154,6 +159,10 @@ export async function updateCommand(options) {
       }
     }
 
+    // Update agent-teams hooks in .claude/settings.local.json
+    updateSpinner.text = 'Updating Claude Code hooks...';
+    await installClaudeHooks(targetPath);
+
     // Update CLAUDE.md
     updateSpinner.text = 'Updating CLAUDE.md...';
     const claudeMdSrc = join(contentDir, 'CLAUDE.md');
@@ -192,6 +201,7 @@ export async function updateCommand(options) {
     if (updateStandards) logger.dim('  ✓ .morph/standards/');
     logger.dim('  ✓ .morph/config/agents.json');
     logger.dim('  ✓ .claude/commands/ and .claude/skills/');
+    logger.dim('  ✓ .claude/settings.local.json (agent-teams hooks)');
     logger.dim('  ✓ CLAUDE.md');
     logger.blank();
     logger.info('Your config.json was preserved.');

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

@@ -30,7 +30,7 @@ const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'tasks',
 /**
  * Get the next phase after the current one
  */
-function getNextPhase(currentPhase, feature, skipOptional) {
+function getNextPhase(currentPhase, feature, skipOptional, featureName) {
   // Load workflow config if workflow is set
   let workflowConfig = null;
   if (feature.workflow && feature.workflow !== 'auto') {
@@ -80,7 +80,7 @@ function getNextPhase(currentPhase, feature, skipOptional) {
         const condition = workflowConfig.phases.skipIfCondition[candidate];
         if (condition) {
           // Evaluate condition (simple conditions for now)
-          if (condition === '!hasUIAgents' && !hasUIAgentsActive(feature)) {
+          if (condition === '!hasUIAgents' && !hasUIAgentsActive(process.cwd(), featureName)) {
             console.log(chalk.gray(`  ⏩ Skipping ${candidate}: no UI agents active`));
             continue;
           }
@@ -145,7 +145,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);
+  const nextPhase = getNextPhase(currentPhase, featureData, options.skipOptional, feature);
 
   if (!nextPhase) {
     console.log(chalk.green('\n✓ Feature is at the final phase!'));
@@ -304,7 +304,7 @@ export async function advancePhaseCommand(feature, options = {}) {
 
   // Gate: Check design system when advancing to implement with UI agents
   if (nextPhase === 'implement') {
-    const gateResult = designSystemGate(feature);
+    const gateResult = designSystemGate(feature, process.cwd());
 
     if (gateResult.blocked) {
       console.log(chalk.red(`\n✗ ${gateResult.message}`));
@@ -327,6 +327,21 @@ export async function advancePhaseCommand(feature, options = {}) {
   state.features[feature].updatedAt = new Date().toISOString();
   saveState(state);
 
+  // Run PhaseAdvanced agent-teams hook (non-blocking)
+  try {
+    const { executeHook, formatHookResults } = await import('../../lib/hooks/hook-executor.js');
+    const hookResult = await executeHook(process.cwd(), feature, 'PhaseAdvanced', {
+      fromPhase: currentPhase,
+      toPhase: nextPhase
+    });
+    if (!hookResult.passed && hookResult.errors.length > 0) {
+      const output = formatHookResults(hookResult, 'PhaseAdvanced');
+      console.log(output);
+    }
+  } catch {
+    // Hook executor unavailable — non-blocking
+  }
+
   console.log(chalk.green(`\n✓ Advanced to ${nextPhaseDef.name}`));
 
   // Show what's needed in the new phase

package/src/commands/state/state.js

@@ -181,13 +181,13 @@ async function checkpointCommand(featureName, note, options) {
   try {
     const spinner = ora('Creating checkpoint...').start();
 
-    const checkpoint = StateManager.addCheckpoint(featureName, note);
+    const checkpoint = await StateManager.addCheckpoint(featureName, note);
 
     spinner.succeed(`Checkpoint registered for ${chalk.cyan(featureName)}`);
     logger.blank();
-    logger.dim(`  ${checkpoint.note}`);
+    logger.dim(`  ${checkpoint.summary?.note || note}`);
     logger.dim(`  Phase: ${checkpoint.phase}`);
-    logger.dim(`  Tasks completed: ${checkpoint.completedTasks}`);
+    logger.dim(`  Tasks completed: ${checkpoint.summary?.completedTasks ?? 0}`);
     logger.blank();
 
   } catch (error) {
@@ -208,8 +208,10 @@ async function listCommand(options) {
     const features = StateManager.listFeatures();
 
     // Project info
-    logger.info(`Project: ${chalk.cyan(summary.project.name)}`);
-    logger.info(`Type: ${chalk.cyan(summary.project.type)}`);
+    const projectName = summary.project?.name || '(unnamed)';
+    const projectType = summary.project?.type || '(unknown)';
+    logger.info(`Project: ${chalk.cyan(projectName)}`);
+    logger.info(`Type: ${chalk.cyan(projectType)}`);
     logger.blank();
 
     if (features.length === 0) {
@@ -232,21 +234,21 @@ async function listCommand(options) {
         archived: '📦'
       }[feature.status] || '❓';
 
-      const progress = feature.tasks.total > 0
-        ? `${feature.tasks.completed}/${feature.tasks.total}`
+      const tasks = feature.tasks || {};
+      const progress = (tasks.total || 0) > 0
+        ? `${tasks.completed || 0}/${tasks.total}`
         : '0/0';
 
       logger.info(`${statusEmoji}  ${chalk.bold(name)}`);
-      logger.dim(`   Phase: ${feature.phase.padEnd(16)} │ Tasks: ${progress}`);
-      logger.dim(`   Agents: ${feature.activeAgents.slice(0, 5).join(', ') || 'None'}`);
+      logger.dim(`   Phase: ${(feature.phase || 'unknown').padEnd(16)} │ Tasks: ${progress}`);
+      logger.dim(`   Agents: ${(feature.activeAgents || []).slice(0, 5).join(', ') || 'None'}`);
       logger.blank();
     });
 
     // Summary
     logger.header('Summary:');
-    logger.info(`Total Features: ${chalk.cyan(summary.metadata.totalFeatures)}`);
-    logger.info(`Completed: ${chalk.cyan(summary.metadata.completedFeatures)}`);
-    logger.info(`Estimated Cost: ${chalk.cyan(`$${summary.metadata.totalCostEstimated.toFixed(2)}/month`)}`);
+    logger.info(`Total Features: ${chalk.cyan(summary.metadata?.totalFeatures ?? features.length)}`);
+    logger.info(`Completed: ${chalk.cyan(summary.metadata?.completedFeatures ?? 0)}`);
     logger.blank();
 
   } catch (error) {

package/src/commands/tasks/task.js

@@ -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.cjs');
 
 /**
  * Execute task-manager.js with given arguments

package/src/commands/threads/thread-template.js

@@ -53,7 +53,7 @@ const THREAD_TYPE_INFO = {
 };
 
 export async function threadTemplateListCommand(options) {
-  console.log(chalk.cyan('\n  Thread Types (v3.0)\n'));
+  console.log(chalk.cyan('\n  Thread Types\n'));
   console.log('  ' + '─'.repeat(70));
 
   for (const [type, info] of Object.entries(THREAD_TYPE_INFO)) {

package/src/core/state/state-manager.js

@@ -188,7 +188,7 @@ async function ensureFeature(featureName, options = {}) {
         proposal: { created: false, path: `.morph/project/outputs/${featureName}/proposal.md` },
         spec: { created: false, path: `.morph/project/outputs/${featureName}/spec.md` },
         contracts: { created: false, path: `.morph/project/outputs/${featureName}/contracts.cs` },
-        tasks: { created: false, path: `.morph/project/outputs/${featureName}/tasks.json` },
+        tasks: { created: false, path: `.morph/project/outputs/${featureName}/tasks.md` },
         uiDesignSystem: { created: false, path: `.morph/project/outputs/${featureName}/ui-design-system.md` },
         uiMockups: { created: false, path: `.morph/project/outputs/${featureName}/ui-mockups.md` },
         uiComponents: { created: false, path: `.morph/project/outputs/${featureName}/ui-components.md` },
@@ -294,10 +294,15 @@ export async function addCheckpoint(featureName, note) {
   const feature = state.features[featureName];
 
   const checkpoint = {
+    passed: true,
+    checkpointNum: feature.checkpoints.length + 1,
     timestamp: new Date().toISOString(),
     phase: feature.phase,
-    completedTasks: feature.tasks.completed,
-    note: note
+    results: [],
+    summary: {
+      note: note,
+      completedTasks: feature.tasks.completed
+    }
   };
 
   feature.checkpoints.push(checkpoint);
@@ -393,21 +398,20 @@ export async function markOutput(featureName, outputType) {
 }
 
 /**
- * Sync tasks count from tasks array (if exists)
+ * Sync progress counters from taskList array into feature.progress
  * @param {Object} feature - Feature object
  */
 function syncTasksCount(feature) {
-  // If feature has tasks array (schema 3.0), count them
-  if (feature.tasks && Array.isArray(feature.tasks)) {
-    const tasks = feature.tasks;
-    feature.progress = {
-      total: tasks.length,
-      completed: tasks.filter(t => t.status === 'completed').length,
-      inProgress: tasks.filter(t => t.status === 'in_progress').length,
-      pending: tasks.filter(t => t.status === 'pending').length,
-      percentage: tasks.length > 0 ? Math.round((tasks.filter(t => t.status === 'completed').length / tasks.length) * 100) : 0
-    };
-  }
+  const list = feature.taskList;
+  if (!Array.isArray(list) || list.length === 0) return;
+  const completed = list.filter(t => t.status === 'completed').length;
+  feature.progress = {
+    total: list.length,
+    completed,
+    inProgress: list.filter(t => t.status === 'in_progress').length,
+    pending: list.filter(t => t.status === 'pending').length,
+    percentage: Math.round((completed / list.length) * 100)
+  };
 }
 
 /**

package/src/core/workflows/workflow-detector.js

@@ -12,6 +12,7 @@
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { getPhaseSequence } from '../state/phase-state-machine.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -336,7 +337,19 @@ export async function detectWorkflow(options) {
  */
 export function getWorkflowConfig(workflowId, projectPath = '.') {
   const workflows = loadWorkflowConfigs(projectPath);
-  return workflows.find(w => w.id === workflowId) || null;
+  const config = workflows.find(w => w.id === workflowId) || null;
+
+  if (config) {
+    const validPhases = new Set(getPhaseSequence());
+    const declaredPhases = config.phases?.run || [];
+    for (const phase of declaredPhases) {
+      if (!validPhases.has(phase)) {
+        console.warn(`[workflow] Warning: workflow "${workflowId}" declares unknown phase "${phase}" — ignored`);
+      }
+    }
+  }
+
+  return config;
 }
 
 /**

package/src/lib/checkpoints/checkpoint-hooks.js

@@ -1,8 +1,10 @@
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { execSync } from 'child_process';
+import chalk from 'chalk';
 import { executeStopHooks, isMaxRetriesExceeded, incrementRetryCount } from '../hooks/stop-hook-executor.js';
 import { recordEvent } from '../analytics/analytics-engine.js';
+import { getFeature } from '../../core/state/state-manager.js';
 
 /**
  * Checkpoint Hooks - Automated validation orchestration
@@ -236,10 +238,11 @@ export async function runCheckpointHooks(featureName, checkpointNum) {
 
       if (!stopHookResult.passed) {
         // Check retry count
+        let retryCount = null;
         if (isMaxRetriesExceeded(pseudoThreadId)) {
           console.log(chalk.red('\n❌ Stop hooks failed 5+ times. Escalating to user.'));
         } else {
-          const retryCount = incrementRetryCount(pseudoThreadId);
+          retryCount = incrementRetryCount(pseudoThreadId);
           console.log(chalk.yellow(`\n⚠ Stop hooks failed (attempt ${retryCount}/5). Feedback saved.`));
           if (stopHookResult.feedback?.suggestions?.length > 0) {
             stopHookResult.feedback.suggestions.forEach(s => console.log(`  → ${s}`));
@@ -250,7 +253,7 @@ export async function runCheckpointHooks(featureName, checkpointNum) {
         recordEvent({
           type: 'stop_hook_failed_at_checkpoint',
           feature: featureName,
-          data: { checkpointNum, retryCount: getRetryCount ? undefined : undefined }
+          data: { checkpointNum, retryCount }
         });
       }
     } catch {
@@ -258,12 +261,14 @@ export async function runCheckpointHooks(featureName, checkpointNum) {
     }
   }
 
+  const phase = featureName ? (getFeature(featureName)?.phase || null) : null;
+
   return {
     passed,
     checkpointNum,
     timestamp: new Date().toISOString(),
+    phase,
     results,
-    stopHookResult,
     summary: {
       errors: errorCount,
       warnings: warningCount,

package/src/lib/detectors/index.js

@@ -69,7 +69,7 @@ export function getDetectionSummary(results) {
     '### Stack',
     `- **Type**: ${structure?.stack || 'unknown'}`,
     `- **Architecture**: ${structure?.architecture || 'unknown'}`,
-    `- **UI Library**: ${structure?.uiLibrary || 'none'}`,
+    ...(structure?.uiLibrary ? [`- **UI Library**: ${structure.uiLibrary}`] : []),
     '',
     '### Technologies',
     `- **Language**: ${config?.language || 'unknown'}`,