@polymorphism-tech/morph-spec 4.8.16 → 4.8.17

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

@@ -0,0 +1,129 @@
+/**
+ * Activity Logger — Session-scoped hook event log
+ *
+ * Writes hook activity to .morph/logs/activity.json for live consumption
+ * by `morph-spec monitor`.
+ *
+ * Design constraints:
+ * - Synchronous only (hooks run in process, no async overhead)
+ * - Fail-silent (never throws — hooks must not be blocked by logger)
+ * - ≤5ms per call (no retries, no network)
+ * - Windows-safe paths via path.join
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const LOGS_DIR = '.morph/logs';
+const ACTIVITY_FILE = join(LOGS_DIR, 'activity.json');
+
+function getActivityPath(projectPath) {
+  return join(projectPath || process.cwd(), ACTIVITY_FILE);
+}
+
+function ensureLogsDir(projectPath) {
+  const dir = join(projectPath || process.cwd(), LOGS_DIR);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function readRaw(activityPath) {
+  try {
+    if (!existsSync(activityPath)) return null;
+    return JSON.parse(readFileSync(activityPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Log a hook firing event to the session activity log.
+ *
+ * @param {string} name   - Hook name (e.g. 'dispatch.js', 'enrich-prompt')
+ * @param {string} event  - Claude Code event (e.g. 'PostToolUse', 'UserPromptSubmit')
+ * @param {string} result - Outcome summary (e.g. 'ok', 'blocked', 'checkpoint_saved')
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ */
+export function logHookActivity(name, event, result, projectPath) {
+  try {
+    const activityPath = getActivityPath(projectPath);
+    ensureLogsDir(projectPath);
+
+    const now = new Date();
+    const ts = now.toTimeString().slice(0, 8); // HH:MM:SS
+
+    const data = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], skills: [] };
+
+    data.hooks = data.hooks || [];
+    data.hooks.push({ name, event, result, ts });
+
+    writeFileSync(activityPath, JSON.stringify(data, null, 2), 'utf-8');
+  } catch {
+    // Fail-silent — never block hooks
+  }
+}
+
+/**
+ * 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.
+ *
+ * @param {string} [projectPath]
+ * @returns {{ sessionId: string, feature: string, phase: string, hooks: Array, skills: Array }|null}
+ */
+export function readActivity(projectPath) {
+  try {
+    return readRaw(getActivityPath(projectPath));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reset the activity log for a new session.
+ * Called from SessionStart hook to clear stale data.
+ *
+ * @param {string} sessionId  - ISO timestamp of new session
+ * @param {string} feature    - Active feature name (empty string if none)
+ * @param {string} phase      - Current phase (empty string if none)
+ * @param {string} [projectPath]
+ */
+export function resetActivity(sessionId, feature, phase, projectPath) {
+  try {
+    ensureLogsDir(projectPath);
+    const data = {
+      sessionId: sessionId || new Date().toISOString(),
+      feature: feature || '',
+      phase: phase || '',
+      hooks: [],
+      skills: []
+    };
+    writeFileSync(getActivityPath(projectPath), JSON.stringify(data, null, 2), 'utf-8');
+  } catch {
+    // Fail-silent
+  }
+}

package/framework/skills/level-0-meta/morph-init/SKILL.md

@@ -51,8 +51,8 @@ Read `~/.claude/plugins/installed_plugins.json` and check for:
 For each missing plugin, run:
 
 ```bash
-npx morph-spec install-plugin superpowers
-npx morph-spec install-plugin context7
+claude plugin install superpowers@claude-plugins-official
+claude plugin install context7@claude-plugins-official
 ```
 
 **If the command succeeds:** `✓ {plugin} installed. Restart Claude Code after /morph-init completes.`
@@ -60,14 +60,10 @@ npx morph-spec install-plugin context7
 **If the command fails:** Show this and **STOP** — do not continue:
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│  Plugin {plugin} requires manual installation:              │
-│                                                             │
-│  1. Claude Code → Settings (Cmd/Ctrl+,) → Extensions        │
-│  2. Browse → search "{plugin}" → Install                    │
-│  3. Restart Claude Code                                     │
-│  4. Re-run /morph-init                                      │
-└─────────────────────────────────────────────────────────────┘
+Plugin {plugin} could not be installed automatically.
+Run manually and restart Claude Code:
+  claude plugin install {plugin}
+Then re-run /morph-init.
 ```
 
 Both `superpowers` and `context7` are required. Do not continue if either is missing.

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 3 (Clarify). Reviews spec.md for ambiguities, gene
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.16"
+cliVersion: "4.8.17"
 ---
 
 # MORPH Clarify - FASE 3

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

@@ -3,7 +3,7 @@ name: phase-codebase-analysis
 description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.16"
+cliVersion: "4.8.17"
 ---
 
 # MORPH Codebase Analysis - Sub-fase de DESIGN

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 2 (Design). Analyzes codebase/schema, then produce
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.16"
+cliVersion: "4.8.17"
 ---
 
 # MORPH Design - FASE 2

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 context: fork
 agent: general-purpose
 user-invocable: false
-cliVersion: "4.8.16"
+cliVersion: "4.8.17"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech sta
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.16"
+cliVersion: "4.8.17"
 ---
 
 # MORPH Setup - FASE 1

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

@@ -5,7 +5,7 @@ argument-hint: "[feature-name]"
 disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.16"
+cliVersion: "4.8.17"
 ---
 
 # MORPH Tasks - FASE 4

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

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 1.5 (UI/UX). Creates design-system.md, mockups.md,
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
-cliVersion: "4.8.16"
+cliVersion: "4.8.17"
 ---
 
 # MORPH UI/UX Design - FASE 1.5

package/package.json

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

package/src/commands/project/index.js

@@ -5,3 +5,4 @@ export { initCommand } from './init.js';
 export { doctorCommand } from './doctor.js';
 export { updateCommand } from './update.js';
 export { tutorialCommand } from './tutorial.js';
+export { monitorCommand } from './monitor.js';

package/src/commands/project/monitor.js

@@ -0,0 +1,295 @@
+/**
+ * morph-spec monitor — Live TUI Dashboard
+ *
+ * Opens a live-updating terminal UI showing:
+ *   - Active agents by tier
+ *   - Hook events (chronological feed)
+ *   - Skills invoked this session
+ *   - Rules in effect
+ *   - Overview summary
+ *
+ * Reads .morph/logs/activity.json (written by hooks via activity-logger.js).
+ * Uses fs.watch for live updates (no polling, no chokidar).
+ *
+ * Usage:
+ *   morph-spec monitor [feature]
+ *   morph-spec monitor --compact
+ *   morph-spec monitor --mode hooks
+ */
+
+import { watch, existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, basename } from 'path';
+import chalk from 'chalk';
+
+import {
+  renderBox,
+  renderFeed,
+  renderAgents,
+  renderSkills,
+  renderRules,
+  renderOverview,
+  renderStatusBar,
+  renderHeader,
+} from '../../lib/monitor/renderer.js';
+
+import { getActiveAgents } from '../../lib/monitor/agent-resolver.js';
+import { readActivity } from '../../../framework/hooks/shared/activity-logger.js';
+import { loadState, getActiveFeature, derivePhaseForFeature } from '../../../framework/hooks/shared/state-reader.js';
+
+const MODES = ['overview', 'hooks', 'agents', 'skills', 'rules'];
+const ACTIVITY_FILE = '.morph/logs/activity.json';
+const RULES_DIR_PROJECT = '.claude/rules';
+const RULES_DIR_FRAMEWORK = '.morph/framework/rules';
+
+// ─────────────────────────────────────────────────────────
+// Rules loading
+// ─────────────────────────────────────────────────────────
+
+function loadRules(cwd) {
+  const rules = [];
+  const dirs = [
+    join(cwd, RULES_DIR_PROJECT),
+    join(cwd, RULES_DIR_FRAMEWORK),
+    join(cwd, 'framework/rules'),
+  ];
+
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    try {
+      const files = readdirSync(dir).filter(f => f.endsWith('.md'));
+      for (const file of files) {
+        // Parse front-matter paths glob if present
+        let glob = '*';
+        try {
+          const content = readFileSync(join(dir, file), 'utf-8');
+          const match = content.match(/paths:\s*\n((?:\s*-\s*.+\n?)+)/);
+          if (match) {
+            const paths = match[1].match(/- (.+)/g);
+            if (paths) glob = paths.map(p => p.replace('- ', '').trim()).join(', ');
+          }
+        } catch { /* skip */ }
+        rules.push({ name: basename(file, '.md'), glob });
+      }
+    } catch { /* skip */ }
+  }
+  return rules;
+}
+
+// ─────────────────────────────────────────────────────────
+// Available skills loading
+// ─────────────────────────────────────────────────────────
+
+function loadAvailableSkills(cwd) {
+  const skillDirs = [
+    join(cwd, '.claude/skills'),
+    join(cwd, 'framework/skills'),
+  ];
+  const names = [];
+  for (const dir of skillDirs) {
+    if (!existsSync(dir)) continue;
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          // Level-N-meta/skill-name or direct skill dirs
+          const sub = readdirSync(join(dir, entry.name), { withFileTypes: true });
+          for (const s of sub) {
+            if (s.isDirectory()) names.push(s.name);
+          }
+        }
+      }
+    } catch { /* skip */ }
+  }
+  return [...new Set(names)];
+}
+
+// ─────────────────────────────────────────────────────────
+// Screen rendering
+// ─────────────────────────────────────────────────────────
+
+function render(state) {
+  const { feature, phase, tasks, agentsByTier, activity, rules, availableSkills, mode, compact } = state;
+
+  const hooks = activity?.hooks || [];
+  const skills = activity?.skills || [];
+
+  // Clear screen
+  process.stdout.write('\x1Bc');
+
+  // Header
+  process.stdout.write(renderHeader(feature, phase, tasks) + '\n');
+
+  if (compact) {
+    // Compact: just show overview
+    const overviewData = { feature, phase, agentsByTier, hooks, skills, rules };
+    process.stdout.write(renderOverview(overviewData) + '\n');
+  } else {
+    switch (mode) {
+      case 'hooks':
+        process.stdout.write(renderFeed(hooks) + '\n');
+        break;
+
+      case 'agents':
+        process.stdout.write(renderAgents(agentsByTier, phase) + '\n');
+        break;
+
+      case 'skills':
+        process.stdout.write(renderSkills(skills, availableSkills) + '\n');
+        break;
+
+      case 'rules':
+        process.stdout.write(renderRules(rules) + '\n');
+        break;
+
+      case 'overview':
+      default: {
+        const overviewData = { feature, phase, agentsByTier, hooks, skills, rules };
+        process.stdout.write(renderOverview(overviewData) + '\n');
+        break;
+      }
+    }
+  }
+
+  // Status bar
+  process.stdout.write(renderStatusBar(mode, MODES) + '\n');
+}
+
+// ─────────────────────────────────────────────────────────
+// State loading
+// ─────────────────────────────────────────────────────────
+
+function loadMonitorState(cwd, featureArg) {
+  let feature = featureArg || '';
+  let phase = '';
+  let tasks = null;
+
+  try {
+    const morphState = loadState(cwd);
+    if (!feature && morphState) {
+      const active = getActiveFeature(cwd);
+      if (active) {
+        feature = active.name;
+        tasks = active.feature.tasks || null;
+      }
+    }
+    if (feature) {
+      phase = derivePhaseForFeature(feature, cwd);
+    }
+  } catch { /* fail-open */ }
+
+  const agentsByTier = getActiveAgents(cwd, phase);
+  const activity = readActivity(cwd);
+  const rules = loadRules(cwd);
+  const availableSkills = loadAvailableSkills(cwd);
+
+  return { feature, phase, tasks, agentsByTier, activity, rules, availableSkills };
+}
+
+// ─────────────────────────────────────────────────────────
+// Main command
+// ─────────────────────────────────────────────────────────
+
+/**
+ * @param {string|undefined} featureArg
+ * @param {{ compact: boolean, mode: string }} opts
+ */
+export function monitorCommand(featureArg, opts = {}) {
+  const cwd = process.cwd();
+  const compact = !!opts.compact;
+  const startMode = MODES.includes(opts.mode) ? opts.mode : 'overview';
+
+  let modeIndex = MODES.indexOf(startMode);
+  let currentMode = startMode;
+
+  // Initial render
+  let monitorState = loadMonitorState(cwd, featureArg);
+  render({ ...monitorState, mode: currentMode, compact });
+
+  // Watch activity.json for changes
+  const activityPath = join(cwd, ACTIVITY_FILE);
+  let watcher = null;
+
+  function startWatcher() {
+    if (!existsSync(activityPath)) {
+      // Retry watch setup when file is created
+      setTimeout(startWatcher, 2000);
+      return;
+    }
+
+    try {
+      watcher = watch(activityPath, { persistent: true }, () => {
+        try {
+          monitorState = loadMonitorState(cwd, featureArg);
+          render({ ...monitorState, mode: currentMode, compact });
+        } catch { /* fail-open */ }
+      });
+    } catch {
+      // fs.watch not supported — fall back to polling
+      setInterval(() => {
+        try {
+          monitorState = loadMonitorState(cwd, featureArg);
+          render({ ...monitorState, mode: currentMode, compact });
+        } catch { /* fail-open */ }
+      }, 2000);
+    }
+  }
+
+  startWatcher();
+
+  // Keyboard input: raw mode
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+
+    process.stdin.on('data', (key) => {
+      // q or Ctrl-C → quit
+      if (key === 'q' || key === '\u0003') {
+        if (watcher) watcher.close();
+        process.stdin.setRawMode(false);
+        process.stdout.write('\n' + chalk.gray('morph-spec monitor closed.\n'));
+        process.exit(0);
+      }
+
+      // shift+tab → cycle modes (forward)
+      // \x1b[Z is the standard escape for shift+tab
+      if (key === '\x1b[Z' || key === '\t') {
+        modeIndex = (modeIndex + 1) % MODES.length;
+        currentMode = MODES[modeIndex];
+        render({ ...monitorState, mode: currentMode, compact });
+      }
+
+      // Arrow keys: left/right also cycle
+      if (key === '\x1b[C') { // right arrow
+        modeIndex = (modeIndex + 1) % MODES.length;
+        currentMode = MODES[modeIndex];
+        render({ ...monitorState, mode: currentMode, compact });
+      }
+      if (key === '\x1b[D') { // left arrow
+        modeIndex = (modeIndex - 1 + MODES.length) % MODES.length;
+        currentMode = MODES[modeIndex];
+        render({ ...monitorState, mode: currentMode, compact });
+      }
+
+      // r → force refresh
+      if (key === 'r') {
+        monitorState = loadMonitorState(cwd, featureArg);
+        render({ ...monitorState, mode: currentMode, compact });
+      }
+    });
+  } else {
+    // Non-TTY: just render once and exit (useful for scripting/piping)
+    process.stdout.write('\n' + chalk.gray('(non-interactive mode — run in a real terminal for live updates)\n'));
+  }
+
+  // Handle process signals
+  process.on('SIGINT', () => {
+    if (watcher) watcher.close();
+    process.stdout.write('\n' + chalk.gray('morph-spec monitor closed.\n'));
+    process.exit(0);
+  });
+  process.on('SIGTERM', () => {
+    if (watcher) watcher.close();
+    process.exit(0);
+  });
+}

package/src/lib/monitor/agent-resolver.js

@@ -0,0 +1,144 @@
+/**
+ * Agent Resolver — Resolves active agents for a given phase
+ *
+ * Reads .morph/framework/agents.json (installed copy) or falls back to
+ * framework/agents.json (source). Filters agents by phase and VSA config.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const AGENTS_PATHS = [
+  '.morph/framework/agents.json',
+  'framework/agents.json',
+];
+
+/**
+ * Load agents.json from the project or framework source.
+ *
+ * @param {string} [cwd]
+ * @returns {Object|null}
+ */
+export function loadAgentsJson(cwd = process.cwd()) {
+  for (const rel of AGENTS_PATHS) {
+    const full = join(cwd, rel);
+    if (existsSync(full)) {
+      try {
+        return JSON.parse(readFileSync(full, 'utf-8'));
+      } catch {
+        // Try next path
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Determine which agents are active for the given phase.
+ *
+ * Rules:
+ * - always_active: true → always included
+ * - Agents with phase-scoped keywords matching the current phase
+ * - VSA architecture: include vsa-architect, exclude domain-architect in phase-setup
+ * - Tier-4 validators are always included in implement phase
+ *
+ * @param {string} [cwd]
+ * @param {string} [phase]
+ * @returns {{ tier1: Agent[], tier2: Agent[], tier3: Agent[], tier4: Agent[] }}
+ */
+export function getActiveAgents(cwd = process.cwd(), phase = '') {
+  const data = loadAgentsJson(cwd);
+  if (!data?.agents) {
+    return { tier1: [], tier2: [], tier3: [], tier4: [] };
+  }
+
+  // Detect VSA config
+  let isVsa = false;
+  try {
+    const configPath = join(cwd, '.morph/config/config.json');
+    if (existsSync(configPath)) {
+      const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+      isVsa = cfg?.config?.architecture?.style === 'vertical-slice';
+    }
+  } catch {
+    // Non-blocking
+  }
+
+  // Phase → active domains heuristic
+  const PHASE_DOMAINS = {
+    proposal: ['architecture', 'developer-experience', 'ai-orchestration'],
+    setup: ['architecture', 'developer-experience', 'ai-orchestration'],
+    design: ['architecture', 'dotnet', 'frontend', 'ai-orchestration'],
+    uiux: ['frontend', 'ui', 'architecture'],
+    clarify: ['architecture', 'developer-experience'],
+    tasks: ['architecture', 'dotnet', 'frontend', 'testing'],
+    implement: ['dotnet', 'frontend', 'testing', 'devops', 'blazor'],
+    sync: ['architecture', 'developer-experience'],
+  };
+
+  const activeDomains = new Set(PHASE_DOMAINS[phase] || Object.values(PHASE_DOMAINS).flat());
+
+  const result = { tier1: [], tier2: [], tier3: [], tier4: [] };
+
+  for (const [name, agent] of Object.entries(data.agents)) {
+    if (name.startsWith('_comment')) continue;
+
+    const tier = agent.tier;
+    if (!tier || tier < 1 || tier > 4) continue;
+
+    const tierKey = `tier${tier}`;
+
+    // Always-active agents
+    if (agent.always_active === true) {
+      // VSA: swap domain-architect for vsa-architect
+      if (name === 'domain-architect' && isVsa) continue;
+      result[tierKey].push({ name, ...agent });
+      continue;
+    }
+
+    // VSA architect: only active when VSA config is set
+    if (name === 'vsa-architect') {
+      if (isVsa && (phase === 'setup' || phase === 'design')) {
+        result[tierKey].push({ name, ...agent });
+      }
+      continue;
+    }
+
+    // Tier-4 validators: active in implement phase
+    if (tier === 4) {
+      if (phase === 'implement' || phase === 'sync') {
+        result[tierKey].push({ name, ...agent });
+      }
+      continue;
+    }
+
+    // Domain-based activation
+    const agentDomains = agent.domains || [];
+    const isActive = agentDomains.some(d => activeDomains.has(d));
+    if (isActive) {
+      result[tierKey].push({ name, ...agent });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get icon for an agent based on its teammate config or tier.
+ *
+ * @param {Object} agent
+ * @returns {string}
+ */
+export function getAgentIcon(agent) {
+  return agent.teammate?.icon || '';
+}
+
+/**
+ * Count total active agents across all tiers.
+ *
+ * @param {{ tier1: any[], tier2: any[], tier3: any[], tier4: any[] }} agentsByTier
+ * @returns {number}
+ */
+export function countActiveAgents(agentsByTier) {
+  return Object.values(agentsByTier).flat().length;
+}