@polymorphism-tech/morph-spec 4.8.19 → 4.9.0

package/framework/hooks/claude-code/post-tool-use/context-refresh.js

@@ -102,7 +102,7 @@ function isContextInitialized() {
     const contextPath = join(process.cwd(), '.morph/context/README.md');
     if (!existsSync(contextPath)) return false;
     const content = readFileSync(contextPath, 'utf-8');
-    return !content.includes('Run /morph-init to generate');
+    return !content.includes('Run /morph:init to generate');
   } catch {
     return false;
   }

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

@@ -58,7 +58,7 @@ function dispatch(command) {
       // Non-blocking
     }
 
-    logHookActivity('dispatch.js', 'PostToolUse', dispatchResult);
+    logHookActivity('phase-dispatch', 'PostToolUse', dispatchResult);
     pass();
   }
 
@@ -67,7 +67,7 @@ function dispatch(command) {
   if (phaseAdvanceMatch) {
     const [, featureName] = phaseAdvanceMatch;
     evaluatePhaseChain(featureName);
-    logHookActivity('dispatch.js', 'PostToolUse', 'phase_chain');
+    logHookActivity('phase-dispatch', 'PostToolUse', 'phase_chain');
     pass();
   }
 

package/framework/hooks/claude-code/post-tool-use/skill-reminder.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: Skill Reminder on Task Start
+ *
+ * Event: PostToolUse | Matcher: Bash
+ *
+ * Fires after `morph-spec task start <feature> <task>` completes.
+ * Reads requiredSkills from phases.json for the current phase and injects
+ * mandatory skill invocation instructions as additionalContext.
+ *
+ * The additionalContext appears directly in Claude's view of the Bash tool
+ * result — more prominent than any pre-loaded prompt text.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure helpers (exported for testing)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse `morph-spec task start <feature> <taskId>` from a bash command string.
+ * Returns { featureName, taskId } or null if the command doesn't match.
+ *
+ * @param {string} command
+ * @returns {{ featureName: string, taskId: string } | null}
+ */
+export function parseTaskStartCommand(command) {
+  if (!command || typeof command !== 'string') return null;
+  const match = command.match(/morph-spec\s+task\s+start\s+(\S+)\s+(\S+)/);
+  if (!match) return null;
+  return { featureName: match[1], taskId: match[2] };
+}
+
+/**
+ * Build the mandatory skill reminder message for a task start event.
+ * Returns null if no relevant skills exist for this phase.
+ *
+ * @param {string} featureName
+ * @param {string} taskId
+ * @param {string} phase
+ * @param {Object|null} phasesData - Parsed phases.json content
+ * @returns {string|null}
+ */
+export function buildSkillReminderMessage(featureName, taskId, phase, phasesData) {
+  try {
+    const allSkills = phasesData?.phases?.[phase]?.requiredSkills;
+    if (!allSkills || allSkills.length === 0) return null;
+
+    const nowSkills   = allSkills.filter(s => s.trigger === 'beforeEachTask');
+    const laterSkills = allSkills.filter(s => s.trigger === 'beforeTaskDone');
+    const bugSkills   = allSkills.filter(s => s.trigger === 'onBugOrUnexpected');
+
+    if (nowSkills.length === 0 && laterSkills.length === 0) return null;
+
+    const lines = [];
+    lines.push(`⚠️  MORPH-SPEC SKILL REMINDER — Task ${taskId} started (phase: ${phase})`);
+    lines.push('');
+
+    if (nowSkills.length > 0) {
+      lines.push('INVOKE NOW before writing any code:');
+      for (const s of nowSkills) {
+        lines.push(`  → Skill(${s.skill})`);
+      }
+      lines.push('');
+    }
+
+    if (laterSkills.length > 0) {
+      lines.push('INVOKE BEFORE marking task done:');
+      for (const s of laterSkills) {
+        lines.push(`  → Skill(${s.skill})`);
+      }
+      lines.push('');
+    }
+
+    if (bugSkills.length > 0) {
+      lines.push('IF you encounter a bug or unexpected behavior:');
+      for (const s of bugSkills) {
+        lines.push(`  → Skill(${s.skill})`);
+      }
+      lines.push('');
+    }
+
+    lines.push('These are MANDATORY. Use the Skill() tool. Do NOT skip.');
+    return lines.join('\n');
+  } catch {
+    return null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook entry point
+// ─────────────────────────────────────────────────────────────────────────────
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const command = payload?.tool_input?.command || '';
+  const parsed = parseTaskStartCommand(command);
+  if (!parsed) pass();
+
+  const { featureName, taskId } = parsed;
+
+  // Load state to get current phase
+  const statePath = join(process.cwd(), '.morph', 'state.json');
+  if (!existsSync(statePath)) pass();
+
+  let state;
+  try {
+    state = JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch {
+    pass();
+  }
+
+  const feature = state?.features?.[featureName];
+  if (!feature) pass();
+
+  const phase = feature.phase;
+  if (!phase) pass();
+
+  // Load phases.json (project-local first, fall back to package-level)
+  const localPhasesPath = join(process.cwd(), 'framework', 'phases.json');
+  const pkgPhasesPath = join(
+    process.cwd(), 'node_modules', '@polymorphism-tech', 'morph-spec', 'framework', 'phases.json'
+  );
+  const phasesPath = existsSync(localPhasesPath) ? localPhasesPath : pkgPhasesPath;
+  if (!existsSync(phasesPath)) pass();
+
+  let phasesData;
+  try {
+    phasesData = JSON.parse(readFileSync(phasesPath, 'utf8'));
+  } catch {
+    pass();
+  }
+
+  const message = buildSkillReminderMessage(featureName, taskId, phase, phasesData);
+  if (!message) pass();
+
+  logHookActivity('skill-reminder', 'PostToolUse', `injected(${featureName}/${taskId}/${phase})`);
+  injectContext(message);
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/claude-code/pre-tool-use/protect-spec-files.js

@@ -58,7 +58,7 @@ try {
       `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
       `Editing approved specs breaks the spec contract.\n\n` +
       `If changes are truly needed:\n` +
-      `  1. Revoke approval: morph-spec approve ${featureName} ${requiredGate} --revoke\n` +
+      `  1. Revoke approval: morph-spec unapprove ${featureName} ${requiredGate}\n` +
       `  2. Make your edits\n` +
       `  3. Re-approve: morph-spec approve ${featureName} ${requiredGate}`
     );

package/framework/hooks/claude-code/session-start/inject-morph-context.js

@@ -15,8 +15,11 @@ import { loadState, getActiveFeature, getPendingGates, getMissingOutputs, derive
 import { stateExists } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { resetActivity, logHookActivity } from '../../shared/activity-logger.js';
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync } from 'fs';
 import { join } from 'path';
+import { resetStaleTasks } from '../../shared/stale-task-reset.js';
+import { execSync as _execSync } from 'child_process';
+import { parseWorktreeResult, buildWorktreeContextLine } from '../../shared/worktree-helpers.js';
 
 const DEFAULT_SPEC_MAX_CHARS = 3000;
 
@@ -43,6 +46,26 @@ function getProjectConfig() {
 
 const SPEC_MAX_CHARS = getSpecMaxChars();
 
+/**
+ * Atomic state save for hook context.
+ * Same approach as state-manager.js saveState — write to tmp, then rename.
+ * Fail-open: any error is silently ignored.
+ * @param {Object} state - Full state object
+ * @param {string} cwd - Project root path
+ */
+function saveStateSync(state, cwd) {
+  try {
+    state.metadata = state.metadata || {};
+    state.metadata.lastUpdated = new Date().toISOString();
+    const statePath = join(cwd, '.morph/state.json');
+    const tmpPath = `${statePath}.tmp.hook.${process.pid}`;
+    writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
+    renameSync(tmpPath, statePath);
+  } catch {
+    try { unlinkSync(tmpPath); } catch { /* ignore cleanup errors */ }
+  }
+}
+
 try {
   if (!stateExists()) pass();
 
@@ -57,7 +80,19 @@ try {
   resetActivity(new Date().toISOString(), activeFeatureName, activePhase);
   logHookActivity('inject-morph-context', 'SessionStart', 'ok');
 
+  // ── Stale task cleanup ──────────────────────────────────────────────────────
+  // Reset any in_progress tasks older than 1 hour — they are orphans from an
+  // interrupted session and are no longer being actively implemented.
+  const staleResetLog = resetStaleTasks(state);
+  if (staleResetLog.length > 0) {
+    saveStateSync(state, process.cwd());
+  }
+  // ────────────────────────────────────────────────────────────────────────────
+
   const lines = ['MORPH-SPEC Status:'];
+  if (staleResetLog.length > 0) {
+    lines.push(`⚠️  ${staleResetLog.length} task(s) auto-reset in_progress → pending (orphaned from previous session): ${staleResetLog.join(', ')}`);
+  }
 
   if (active) {
     const { name, feature } = active;
@@ -129,6 +164,40 @@ try {
         // Non-blocking: skip spec injection on read error
       }
     }
+
+    // ── Worktree setup ──────────────────────────────────────────────────────────
+    // For the active feature, create or detect an existing git worktree.
+    // Trigger: uses getActiveFeature() (status-based) rather than checking
+    // activeAgents, because status is the canonical signal already used by the
+    // rest of this hook. activeAgents is populated later in the spec pipeline,
+    // so a status-based gate ensures the worktree is always created before work
+    // begins — even for features still in early phases.
+    // Fail-open: any error is silently ignored.
+    try {
+      let worktreeStdout = '';
+      try {
+        worktreeStdout = _execSync(`npx morph-spec worktree setup ${active.name}`, {
+          cwd: process.cwd(),
+          stdio: 'pipe',
+          timeout: 10000
+        }).toString();
+      } catch (execErr) {
+        // exit code 2 = already exists — stdout still has the JSON result
+        worktreeStdout = execErr.stdout?.toString() || '';
+      }
+      const worktreeResult = parseWorktreeResult(worktreeStdout);
+      if (worktreeResult) {
+        worktreeResult.feature = active.name; // enrich for context builder
+        const contextLine = buildWorktreeContextLine(worktreeResult);
+        if (contextLine) {
+          lines.push('');
+          lines.push(contextLine);
+        }
+      }
+    } catch {
+      // Fail-open — worktree setup must never block the session
+    }
+    // ────────────────────────────────────────────────────────────────────────────
   } else {
     // Show summary of all features
     const featureNames = Object.keys(state.features);
@@ -151,7 +220,7 @@ try {
     lines.push('');
     lines.push('── MORPH SYSTEM MAP ─────────────────────────────────────────────');
     lines.push(`🪝 Hooks: 10 registrados  |  📏 Rules: em .claude/rules/  |  🎯 Skills: em .claude/skills/`);
-    lines.push(`   Execute \`morph-spec monitor\` em terminal separado para live view`);
+    lines.push(`   Use \`morph-spec doctor\` para health check  |  \`morph-spec status ${name}\` para dashboard`);
     lines.push('─────────────────────────────────────────────────────────────────');
   }
 

package/framework/hooks/claude-code/statusline.py

@@ -151,7 +151,10 @@ def get_session_feature_names(features_dict, entries):
 
 
 def get_all_active_features(cwd, entries):
-    """Return in_progress features that are active in the current session."""
+    """Return in_progress features that are active in the current session.
+
+    Caller is responsible for only calling this when inside a secondary worktree.
+    """
     state_path = Path(cwd) / '.morph' / 'state.json'
     if not state_path.exists():
         return []
@@ -162,11 +165,6 @@ def get_all_active_features(cwd, entries):
         # Filter to features belonging to this session (mentioned in transcript)
         session_names = get_session_feature_names(features, entries)
 
-        # Auto-detect: if only one feature is in_progress, show it regardless of transcript
-        in_progress = [n for n, f in features.items() if f.get('status') == 'in_progress']
-        if len(in_progress) == 1:
-            session_names.add(in_progress[0])
-
         if not session_names:
             return []
 
@@ -310,8 +308,14 @@ def get_git_info(cwd):
         return ""
 
 
-def get_worktree_info(cwd):
-    """Detect if running in a git worktree (not the main worktree)."""
+def get_worktree_data(cwd):
+    """Detect worktree status for cwd.
+
+    Returns (is_secondary: bool, display_str: str).
+    is_secondary is True only when cwd is a non-primary git worktree.
+    display_str is the formatted label (non-empty only when is_secondary).
+    Called once in main() to avoid duplicate git subprocess.
+    """
     try:
         out = _run_git(['worktree', 'list', '--porcelain'], cwd)
         entries, current = [], {}
@@ -329,10 +333,45 @@ def get_worktree_info(cwd):
             for entry in entries[1:]:
                 if str(Path(entry.get('path', '')).resolve()) == cwd_r:
                     branch = entry.get('branch', '').replace('refs/heads/', '')
-                    return f"{MAGENTA}worktree:{branch}{R}"
+                    return True, f"{MAGENTA}worktree:{branch}{R}"
     except Exception:
         pass
-    return ""
+    return False, ""
+
+
+def get_recent_tool_calls(entries):
+    """Scan the last 50 transcript entries for the most recent Skill and Agent tool calls.
+
+    Returns (last_skill_name, last_agent_name) — either may be None.
+    Looks at assistant messages containing tool_use blocks.
+    """
+    last_skill = None
+    last_agent = None
+    recent = entries[-50:] if len(entries) > 50 else entries
+    for entry in reversed(recent):
+        if entry.get('isSidechain') or entry.get('isApiErrorMessage'):
+            continue
+        msg = entry.get('message') or {}
+        content = msg.get('content') or []
+        if not isinstance(content, list):
+            continue
+        # Within each entry, scan content from last to first to get most-recent call
+        for item in reversed(content):
+            if not isinstance(item, dict) or item.get('type') != 'tool_use':
+                continue
+            tool = item.get('name', '')
+            inp = item.get('input') or {}
+            if tool == 'Skill' and last_skill is None:
+                last_skill = inp.get('skill') or ''
+            elif tool == 'Agent' and last_agent is None:
+                agent_name = inp.get('subagent_type') or ''
+                if not agent_name:
+                    desc = inp.get('description') or inp.get('prompt') or ''
+                    agent_name = (desc[:22] + '…') if len(desc) > 25 else desc
+                last_agent = agent_name
+        if last_skill is not None and last_agent is not None:
+            break
+    return last_skill or None, last_agent or None
 
 
 # ── Transcript / JSONL helpers ────────────────────────────────────────────────
@@ -493,12 +532,18 @@ def main():
         cwd             = data.get('cwd', os.getcwd())
         transcript_path = data.get('transcript_path')
 
-        # Read JSONL transcript once — shared by session clock, block timer,
-        # token metrics, and session name.
+        # Read JSONL transcript once — shared by session clock, token metrics,
+        # session name, and skill/agent detection.
         entries = read_transcript_jsonl(transcript_path) if transcript_path else []
 
+        # ── Worktree detection (single git call) ─────────────────────────────────
+        # Feature lines are only shown when inside a secondary git worktree.
+        # This prevents stale feature names showing up during unrelated work
+        # in the main worktree.
+        is_worktree, wt_display = get_worktree_data(cwd)
+
         # ── MORPH feature lines (one line per active feature) ────────────────────
-        features = get_all_active_features(cwd, entries)
+        features = get_all_active_features(cwd, entries) if is_worktree else []
         for feat in features:
             # Feature name with visual prefix
             parts = [f"{CYAN}{BOLD}► {feat['name']}{R}"]
@@ -536,19 +581,14 @@ def main():
 
             print('  |  '.join(parts))
 
-        # ── Activity info line (hooks + last event) ──────────────────────────────
-        if features:  # only show when a feature is active
+        # ── Activity info line (hooks; only shown when a feature is active) ───────
+        if features:
             activity = get_activity_info(cwd)
-            if activity and (activity['hook_count'] > 0 or activity['skill_count'] > 0):
-                act_parts = []
-                if activity['hook_count'] > 0:
-                    hook_label = activity['last_hook'] or '?'
-                    age_str = f"({activity['last_hook_age']})" if activity['last_hook_age'] else ''
-                    act_parts.append(f"{BLUE}🪝 {hook_label} {age_str}{R}".strip())
-                if activity['skill_count'] > 0:
-                    act_parts.append(f"{YELLOW}🎯 {activity['skill_count']} skill(s){R}")
-                if act_parts:
-                    print(f"  {GRAY}└{R} " + f"  {GRAY}|{R}  ".join(act_parts))
+            if activity and activity['hook_count'] > 0:
+                hook_label = activity['last_hook'] or '?'
+                age_str = f"({activity['last_hook_age']})" if activity['last_hook_age'] else ''
+                hook_str = f"{BLUE}🪝 {hook_label} {age_str}{R}".strip()
+                print(f"  {GRAY}└{R} {hook_str}")
 
         # ── Session info line (always shown) ─────────────────────────────────────
         parts2 = []
@@ -580,6 +620,14 @@ def main():
             }
             parts2.append(f"{YELLOW}{_perm_labels.get(perm, perm)}{R}")
 
+        # Last skill and agent invoked (parsed from transcript tool_use blocks)
+        if entries:
+            last_skill, last_agent = get_recent_tool_calls(entries)
+            if last_skill:
+                parts2.append(f"{YELLOW}🎯 {last_skill}{R}")
+            if last_agent:
+                parts2.append(f"{MAGENTA}⚡ {last_agent}{R}")
+
         # Session clock (elapsed time since session start, survives transcript transitions)
         session_start = get_session_start(cwd, transcript_path, entries)
         duration = get_session_duration(session_start)
@@ -611,16 +659,14 @@ def main():
                 line += f" ({toks})"
             parts2.append(line + suffix)
 
-
         # Git info (branch + diff stats)
         git = get_git_info(cwd)
         if git:
             parts2.append(git)
 
-        # Worktree info
-        wt = get_worktree_info(cwd)
-        if wt:
-            parts2.append(wt)
+        # Worktree label (already computed above — reuse result)
+        if wt_display:
+            parts2.append(wt_display)
 
         if parts2:
             print('  |  '.join(parts2))

package/framework/hooks/claude-code/user-prompt/set-terminal-title.js

@@ -40,21 +40,29 @@ try {
   const prefix = process.env.CLAUDE_TITLE_PREFIX ? `${process.env.CLAUDE_TITLE_PREFIX} ` : '';
   const finalTitle = `${prefix}${title}`;
 
-  // Save to ~/.claude/terminal_title (for shell hook integration)
+  // Save to session-specific file (MORPH_TERMINAL_TITLE_FILE) or fallback to global
+  // MORPH_TERMINAL_TITLE_FILE is set by the shell wrapper (Invoke-Claude / claude())
+  // per-session so multiple terminal windows don't interfere with each other.
   try {
+    const titleFilePath = process.env.MORPH_TERMINAL_TITLE_FILE
+      || join(homedir(), '.claude', 'terminal_title');
     const claudeDir = join(homedir(), '.claude');
     await mkdir(claudeDir, { recursive: true });
-    await writeFile(join(claudeDir, 'terminal_title'), finalTitle, 'utf-8');
+    await writeFile(titleFilePath, finalTitle, 'utf-8');
   } catch { /* non-critical */ }
 
-  // Write ANSI escape to /dev/tty (bypasses stdout capture by Claude Code)
+  // Write ANSI escape to terminal device (bypasses stdout capture by Claude Code)
+  // Windows uses \\.\CONOUT$ as the equivalent of /dev/tty
+  let wrote = false;
   try {
-    const tty = openSync('/dev/tty', 'w');
+    const devicePath = process.platform === 'win32' ? '\\\\.\\CONOUT$' : '/dev/tty';
+    const tty = openSync(devicePath, 'w');
     writeSync(tty, `\x1b]0;${finalTitle}\x07`);
     closeSync(tty);
-  } catch { /* terminal may not support /dev/tty */ }
+    wrote = true;
+  } catch { /* terminal may not support direct device access */ }
 
-  logHookActivity('set-terminal-title', 'UserPromptSubmit', 'ok');
+  logHookActivity('set-terminal-title', 'UserPromptSubmit', wrote ? 'ok' : 'failed');
 } catch { /* fail-open */ }
 
 process.exit(0);

package/framework/hooks/shared/activity-logger.js

@@ -64,30 +64,6 @@ export function logHookActivity(name, event, result, projectPath) {
   }
 }
 
-/**
- * Log a skill invocation to the session activity log.
- *
- * @param {string} name   - Skill name (e.g. 'brainstorming')
- * @param {string} [projectPath]
- */
-export function logSkillActivity(name, projectPath) {
-  try {
-    const activityPath = getActivityPath(projectPath);
-    ensureLogsDir(projectPath);
-
-    const now = new Date();
-    const ts = now.toTimeString().slice(0, 8);
-
-    const data = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], skills: [] };
-
-    data.skills = data.skills || [];
-    data.skills.push({ name, ts });
-
-    writeFileSync(activityPath, JSON.stringify(data, null, 2), 'utf-8');
-  } catch {
-    // Fail-silent
-  }
-}
 
 /**
  * Read the current activity log.

package/framework/hooks/shared/phase-utils.js

@@ -29,6 +29,7 @@ export const OUTPUT_PHASE_MAP = {
   spec: 'design',
   clarifications: 'clarify',
   contracts: 'design',
+  contractsTs: 'design',
   contractsVsa: 'design',
   tasks: 'tasks',
   uiDesignSystem: 'uiux',
@@ -46,6 +47,7 @@ export const FILENAME_TO_OUTPUT = {
   'spec.md': 'spec',
   'clarifications.md': 'clarifications',
   'contracts.cs': 'contracts',
+  'contracts.ts': 'contractsTs',
   'contracts-vsa.cs': 'contractsVsa',
   'tasks.md': 'tasks',
   'design-system.md': 'uiDesignSystem',
@@ -61,6 +63,7 @@ export const PROTECTED_SPEC_FILES = {
   'schema-analysis.md': 'design',
   'spec.md': 'design',
   'contracts.cs': 'design',
+  'contracts.ts': 'design',
   'contracts-vsa.cs': 'design',
   'tasks.md': 'tasks',
   'design-system.md': 'uiux',

package/framework/hooks/shared/skill-reminder-helpers.js

@@ -0,0 +1,79 @@
+/**
+ * Pure helper functions for the skill-reminder PostToolUse hook.
+ * Extracted to shared/ so they can be unit-tested without running the hook entry point.
+ */
+
+/**
+ * Parse `morph-spec task start <feature> <taskId>` from a bash command string.
+ * Returns { featureName, taskId } or null if the command doesn't match.
+ *
+ * @param {string} command
+ * @returns {{ featureName: string, taskId: string } | null}
+ */
+export function parseTaskStartCommand(command) {
+  if (!command || typeof command !== 'string') return null;
+  const match = command.match(/morph-spec\s+task\s+start\s+(\S+)\s+(\S+)/);
+  if (!match) return null;
+  return { featureName: match[1], taskId: match[2] };
+}
+
+/**
+ * Build the mandatory skill reminder message for a task start event.
+ * Returns null if no relevant skills exist for this phase at task-start time.
+ *
+ * Relevant triggers:
+ *   - beforeEachTask   → invoke NOW before writing any code
+ *   - beforeTaskDone   → invoke BEFORE marking task done
+ *   - onBugOrUnexpected → invoke IF a bug is encountered
+ *
+ * @param {string} featureName
+ * @param {string} taskId
+ * @param {string} phase
+ * @param {Object|null} phasesData - Parsed phases.json content
+ * @returns {string|null}
+ */
+export function buildSkillReminderMessage(featureName, taskId, phase, phasesData) {
+  try {
+    const allSkills = phasesData?.phases?.[phase]?.requiredSkills;
+    if (!allSkills || allSkills.length === 0) return null;
+
+    const nowSkills   = allSkills.filter(s => s.trigger === 'beforeEachTask');
+    const laterSkills = allSkills.filter(s => s.trigger === 'beforeTaskDone');
+    const bugSkills   = allSkills.filter(s => s.trigger === 'onBugOrUnexpected');
+
+    if (nowSkills.length === 0 && laterSkills.length === 0) return null;
+
+    const lines = [];
+    lines.push(`⚠️  MORPH-SPEC SKILL REMINDER — Task ${taskId} started (phase: ${phase})`);
+    lines.push('');
+
+    if (nowSkills.length > 0) {
+      lines.push('INVOKE NOW before writing any code:');
+      for (const s of nowSkills) {
+        lines.push(`  → Skill(${s.skill})`);
+      }
+      lines.push('');
+    }
+
+    if (laterSkills.length > 0) {
+      lines.push('INVOKE BEFORE marking task done:');
+      for (const s of laterSkills) {
+        lines.push(`  → Skill(${s.skill})`);
+      }
+      lines.push('');
+    }
+
+    if (bugSkills.length > 0) {
+      lines.push('IF you encounter a bug or unexpected behavior:');
+      for (const s of bugSkills) {
+        lines.push(`  → Skill(${s.skill})`);
+      }
+      lines.push('');
+    }
+
+    lines.push('These are MANDATORY. Use the Skill() tool. Do NOT skip.');
+    return lines.join('\n');
+  } catch {
+    return null;
+  }
+}