@polymorphism-tech/morph-spec 4.8.16 → 4.8.18

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 4.8.16  
+**Version:** 4.8.18  
 **Requires:** Node.js 18+, Claude Code
 
 ---
@@ -376,4 +376,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.8.16 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v4.8.18 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { program } from 'commander';
 import chalk from 'chalk';
@@ -15,6 +15,7 @@ import { doctorCommand } from '../src/commands/project/doctor.js';
 import { tutorialCommand } from '../src/commands/project/tutorial.js';
 
 import { statusCommand } from '../src/commands/project/status.js';
+import { monitorCommand } from '../src/commands/project/monitor.js';
 import { checkpointSaveCommand, checkpointRestoreCommand, checkpointListCommand } from '../src/commands/project/checkpoint.js';
 
 // State commands
@@ -111,6 +112,13 @@ program
   .option('-v, --verbose', 'Show detailed output')
   .action(statusCommand);
 
+program
+  .command('monitor [feature]')
+  .description('Live TUI dashboard — hooks, agents, skills, rules in real time')
+  .option('--compact', 'Minimal single-view output')
+  .option('--mode <mode>', 'Start view: overview|hooks|agents|skills|rules', 'overview')
+  .action(monitorCommand);
+
 // State management commands
 program
   .command('state <action> [args...]')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "4.8.16",
+  "version": "4.8.18",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -200,4 +200,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v4.8.16 by Polymorphism Tech*
+*morph-spec v4.8.18 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -203,4 +203,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.8.16 by Polymorphism Tech*
+*morph-spec v4.8.18 by Polymorphism Tech*

package/framework/hooks/README.md

@@ -15,7 +15,8 @@ framework/hooks/
 │   │   ├── protect-spec-files.js    # Block edits to approved spec artifacts
 │   │   └── enforce-phase-writes.js  # Enforce writes to correct phase dir
 │   ├── post-tool-use/
-│   │   └── dispatch.js              # Dispatch on CLI commands (auto-checkpoint)
+│   │   ├── dispatch.js              # Dispatch on CLI commands (auto-checkpoint)
+│   │   └── context-refresh.js       # Auto-refresh context on structural git commits
 │   ├── stop/
 │   │   └── validate-completion.js   # Advisory: warn about incomplete work
 │   ├── pre-compact/
@@ -50,6 +51,7 @@ framework/hooks/
 | **PreToolUse** (Write\|Edit) | enforce-phase-writes.js | Block | Ensures writes go to current phase directory |
 | **PreToolUse** (Bash) | _(prompt-type inline guard)_ | Block | Blocks `rm -rf .morph/` and direct state edits via Claude's reasoning |
 | **PostToolUse** (Bash) | dispatch.js | Dispatch | Triggers checkpoints on task completion |
+| **PostToolUse** (Bash) | context-refresh.js | Inject context | Detects `git commit` with structural changes → instructs Claude to update `.morph/context/README.md` and `.morph/config/config.json` |
 | **PostToolUseFailure** | handle-tool-failure.js | Logging | Appends structured JSON to .morph/logs/tool-failures.log |
 | **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/pending gates |
 | **PreCompact** | save-morph-context.js | Snapshot | Saves state to .morph/memory/ before compaction |
@@ -199,4 +201,4 @@ morph-spec doctor --reset
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — Hooks Architecture v2.5*
+*MORPH-SPEC by Polymorphism Tech — Hooks Architecture v2.7*

package/framework/hooks/claude-code/notification/approval-reminder.js

@@ -12,6 +12,7 @@
 
 import { stateExists, getActiveFeature, getPendingGates } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
 
 try {
   if (!stateExists()) pass();
@@ -44,6 +45,7 @@ try {
     `  morph-spec approve ${name} ${gate}`
   );
 
+  logHookActivity('approval-reminder', 'Notification', `pending(${pendingRelevant.join(',')})`);
   injectContext(
     `MORPH-SPEC: Feature '${name}' has pending approval(s) that may be blocking progress:\n` +
     reminders.join('\n')

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

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: Context Auto-Refresh
+ *
+ * Event: PostToolUse | Matcher: Bash
+ *
+ * Detects `git commit` commands that touch structural files (package.json,
+ * *.csproj, next.config.*, etc.) and injects instructions for Claude to
+ * update .morph/context/README.md and .morph/config/config.json.
+ *
+ * Only fires when:
+ *   1. .morph/state.json exists (morph-spec project)
+ *   2. Command contains `git commit`
+ *   3. .morph/context/README.md is initialized (not a setup-infra placeholder)
+ *   4. Structural files changed in the commit (compared to HEAD~1)
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { execSync } from 'child_process';
+import { readFileSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { pass, injectContext } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+
+const STRUCTURAL_PATTERNS = [
+  /^package\.json$/,
+  /\.csproj$/,
+  /\.sln$/,
+  /^next\.config\./,
+  /^tailwind\.config\./,
+  /^tsconfig\.json$/,
+  /^jsconfig\.json$/,
+  /^docker-compose/,
+  /^Dockerfile/,
+  /^\.env\.example$/,
+  /^go\.mod$/,
+  /^requirements\.txt$/,
+  /^pyproject\.toml$/,
+  /^Gemfile$/,
+];
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const command = payload?.tool_input?.command || '';
+  if (!/\bgit\s+commit\b/.test(command)) pass();
+
+  if (!isContextInitialized()) pass();
+
+  let changedFiles = [];
+  try {
+    const output = execSync('git diff HEAD~1 --name-only', {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+      cwd: process.cwd(),
+      timeout: 10000,
+    });
+    changedFiles = output.trim().split('\n').filter(Boolean);
+  } catch {
+    // First commit (no HEAD~1) or git error — pass silently
+    pass();
+  }
+
+  const structuralFiles = changedFiles.filter(file => {
+    const name = basename(file);
+    return STRUCTURAL_PATTERNS.some(pattern => pattern.test(name));
+  });
+
+  if (structuralFiles.length === 0) pass();
+
+  const fileList = structuralFiles.join(', ');
+  logHookActivity('context-refresh', 'PostToolUse', `structural_change(${structuralFiles.length})`);
+  injectContext(
+    `📋 [morph-spec] Mudanças estruturais detectadas no commit: ${fileList}\n\n` +
+    `Atualizar contexto do projeto automaticamente:\n` +
+    `1. \`git show HEAD --stat\` — ver escopo completo da mudança\n` +
+    `2. Ler \`.morph/context/README.md\` → atualizar seções afetadas\n` +
+    `   (Tech Stack, Architecture, Key Integrations, Agent Notes)\n` +
+    `3. Ler \`.morph/config/config.json\` → atualizar campos relevantes\n` +
+    `   (stack, architecture, integrations, paths)\n` +
+    `4. Escrever os arquivos atualizados com as mudanças detectadas`
+  );
+} catch {
+  // Fail-open
+  process.exit(0);
+}
+
+/**
+ * Check if .morph/context/README.md is initialized (not a setup-infra placeholder).
+ * Returns false if the file is missing or contains the placeholder sentinel.
+ * @returns {boolean}
+ */
+function isContextInitialized() {
+  try {
+    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');
+  } catch {
+    return false;
+  }
+}

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

@@ -19,6 +19,7 @@ import { resolve } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists, getFeature } from '../../shared/state-reader.js';
 import { pass, injectContext } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
 
 try {
   if (!stateExists()) pass();
@@ -42,6 +43,7 @@ function dispatch(command) {
     const [, featureName, taskId] = taskDoneMatch;
 
     // Check if checkpoint should run (every 3 tasks)
+    let dispatchResult = 'task_done';
     try {
       const feature = getFeature(featureName);
       if (feature?.tasks) {
@@ -49,12 +51,14 @@ function dispatch(command) {
         if (completed > 0 && completed % 3 === 0) {
           const checkpointNum = Math.floor(completed / 3);
           run(`morph-spec checkpoint-save ${featureName} --note "Auto-checkpoint #${checkpointNum} at task ${completed}"`);
+          dispatchResult = 'checkpoint_saved';
         }
       }
     } catch {
       // Non-blocking
     }
 
+    logHookActivity('dispatch.js', 'PostToolUse', dispatchResult);
     pass();
   }
 
@@ -63,6 +67,7 @@ function dispatch(command) {
   if (phaseAdvanceMatch) {
     const [, featureName] = phaseAdvanceMatch;
     evaluatePhaseChain(featureName);
+    logHookActivity('dispatch.js', 'PostToolUse', 'phase_chain');
     pass();
   }
 

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

@@ -15,6 +15,7 @@ import { appendFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists } from '../../shared/state-reader.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
 
 try {
   // Only log in morph-spec projects
@@ -35,6 +36,7 @@ try {
   };
 
   appendFileSync(join(logDir, 'tool-failures.log'), JSON.stringify(entry) + '\n');
+  logHookActivity('handle-tool-failure', 'PostToolUseFailure', `logged(${entry.tool})`);
 } catch {
   // Fail-open: logging is non-critical
 }

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

@@ -21,6 +21,7 @@ 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';
 
 // Standard IDs referenced in remediation messages
 const STANDARD_REFS = {
@@ -65,9 +66,13 @@ try {
   if (!taskHistory) pass();
 
   // Only act on failed validations (passed = no feedback needed)
-  if (taskHistory.status === 'passed') pass();
+  if (taskHistory.status === 'passed') {
+    logHookActivity('validator-feedback', 'PostToolUse', 'passed');
+    pass();
+  }
 
   // Build remediation context based on validation issues
+  logHookActivity('validator-feedback', 'PostToolUse', `remediation_injected(attempt_${taskHistory.attempt || 1})`);
   buildRemediationContext(featureName, taskId, taskHistory);
 } catch {
   // Fail-open

package/framework/hooks/claude-code/pre-compact/save-morph-context.js

@@ -22,6 +22,7 @@ import {
   derivePhaseForFeature, getPendingGates, getOutputs,
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
 
 const DECISIONS_MAX_CHARS = 1500;
 const MAX_PENDING_TASKS   = 8;
@@ -173,6 +174,7 @@ try {
   lines.push('');
   lines.push('=== END MORPH CONTEXT ===');
 
+  logHookActivity('save-morph-context', 'PreCompact', 'context_saved');
   injectContext(lines.join('\n'));
 } catch {
   process.exit(0);

package/framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js

@@ -28,6 +28,7 @@ import {
   PHASE_DIRS
 } from '../../shared/phase-utils.js';
 import { block, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
 
 try {
   // Amend mode: bypass phase write enforcement for legitimate corrections
@@ -65,9 +66,13 @@ try {
   if (targetDir !== allowedDir) {
     // Allow editing already-existing files from previous phases
     const absolutePath = resolve(process.cwd(), filePath);
-    if (existsSync(absolutePath)) pass(); // editing existing file — allow
+    if (existsSync(absolutePath)) {
+      logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
+      pass(); // editing existing file — allow
+    }
 
     const phaseLabel = phase.toUpperCase();
+    logHookActivity('enforce-phase-writes', 'PreToolUse', 'blocked');
     block(
       `MORPH-SPEC: Writing to '${targetDir}/' is not allowed during ${phaseLabel} phase.\n` +
       `Current phase '${phase}' only permits writes to '${allowedDir}/'.\n\n` +
@@ -76,6 +81,7 @@ try {
     );
   }
 
+  logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
   pass();
 } catch {
   // Fail-open

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

@@ -22,6 +22,7 @@ import {
   PROTECTED_SPEC_FILES
 } from '../../shared/phase-utils.js';
 import { block, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
 
 try {
   // Amend mode: bypass spec protection for legitimate in-implementation corrections
@@ -52,6 +53,7 @@ try {
 
   // Check if the gate has been approved
   if (isGateApproved(featureName, requiredGate)) {
+    logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
     block(
       `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
       `Editing approved specs breaks the spec contract.\n\n` +
@@ -63,6 +65,7 @@ try {
   }
 
   // Gate not yet approved — allow editing
+  logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
   pass();
 } catch {
   // Fail-open

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

@@ -14,6 +14,7 @@
 import { loadState, getActiveFeature, getPendingGates, getMissingOutputs, derivePhaseForFeature } from '../../shared/state-reader.js';
 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 { join } from 'path';
 
@@ -49,6 +50,13 @@ try {
   if (!state?.features || Object.keys(state.features).length === 0) pass();
 
   const active = getActiveFeature();
+
+  // Reset activity log for new session
+  const activeFeatureName = active?.name || '';
+  const activePhase = active ? derivePhaseForFeature(active.name) : '';
+  resetActivity(new Date().toISOString(), activeFeatureName, activePhase);
+  logHookActivity('inject-morph-context', 'SessionStart', 'ok');
+
   const lines = ['MORPH-SPEC Status:'];
 
   if (active) {
@@ -136,6 +144,17 @@ try {
   lines.push('');
   lines.push('Key commands: morph-spec status <feature> | morph-spec phase advance <feature> | morph-spec approve <feature> <gate>');
 
+  // System Map — compact summary for sessions without a live monitor terminal
+  if (active) {
+    const { name } = active;
+    const sysPhase = derivePhaseForFeature(name);
+    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('─────────────────────────────────────────────────────────────────');
+  }
+
   injectContext(lines.join('\n'));
 } catch {
   // Fail-open

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

@@ -202,6 +202,53 @@ def get_all_active_features(cwd, entries):
         return []
 
 
+# ── Activity log helpers ──────────────────────────────────────────────────────
+
+def get_activity_info(cwd):
+    """Read .morph/logs/activity.json and return compact summary dict.
+    Returns None if file is missing or unreadable.
+    """
+    activity_path = Path(cwd) / '.morph' / 'logs' / 'activity.json'
+    if not activity_path.exists():
+        return None
+    try:
+        data = json.loads(activity_path.read_text(encoding='utf-8'))
+        hooks = data.get('hooks') or []
+        skills = data.get('skills') or []
+
+        last_hook = None
+        last_hook_age = None
+        if hooks:
+            last = hooks[-1]
+            last_hook = last.get('name', '')
+            # Try to compute age from timestamp (HH:MM:SS)
+            try:
+                ts = last.get('ts', '')
+                if ts and len(ts) == 8:
+                    now = datetime.now()
+                    hook_t = datetime.strptime(ts, '%H:%M:%S').replace(
+                        year=now.year, month=now.month, day=now.day
+                    )
+                    diff_s = (now - hook_t).total_seconds()
+                    if diff_s < 0:
+                        diff_s = 0
+                    if diff_s < 60:
+                        last_hook_age = f"{int(diff_s)}s"
+                    else:
+                        last_hook_age = f"{int(diff_s // 60)}m"
+            except Exception:
+                pass
+
+        return {
+            'hook_count': len(hooks),
+            'skill_count': len(skills),
+            'last_hook': last_hook,
+            'last_hook_age': last_hook_age,
+        }
+    except Exception:
+        return None
+
+
 # ── Git helpers ───────────────────────────────────────────────────────────────
 
 def _run_git(args, cwd):
@@ -489,6 +536,20 @@ def main():
 
             print('  |  '.join(parts))
 
+        # ── Activity info line (hooks + last event) ──────────────────────────────
+        if features:  # only show when a feature is active
+            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))
+
         # ── Session info line (always shown) ─────────────────────────────────────
         parts2 = []
 

package/framework/hooks/claude-code/stop/validate-completion.js

@@ -24,6 +24,7 @@ import {
   stateExists, loadState, getActiveFeature, getMissingOutputs, derivePhaseForFeature,
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
 
 // Phases where compaction is strongly recommended before starting
 const COMPACT_TRIGGER_PHASES = new Set(['implement']);
@@ -163,6 +164,7 @@ try {
     `Status: morph-spec status ${name}`,
   ].join('\n');
 
+  logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);
   injectContext(message);
 } catch {
   process.exit(0);

package/framework/hooks/claude-code/teammate-idle/teammate-idle.js

@@ -18,6 +18,7 @@
 import { execSync } from 'child_process';
 import { readStdin } from '../../../shared/stdin-reader.js';
 import { loadState, stateExists, getActiveFeature } from '../../../shared/state-reader.js';
+import { logHookActivity } from '../../../shared/activity-logger.js';
 
 try {
   // Read hook payload (TeammateIdle provides teammate info)
@@ -66,6 +67,7 @@ try {
 
   if (exitCode !== 0) {
     // Exit 2: send feedback to teammate to continue working
+    logHookActivity('teammate-idle', 'TeammateIdle', 'validation_failed');
     const feedback = [
       'MORPH-SPEC validation found issues — please fix before going idle:',
       '',
@@ -80,6 +82,7 @@ try {
   }
 
   // Exit 0: validation passed, teammate may become idle
+  logHookActivity('teammate-idle', 'TeammateIdle', 'passed');
   process.exit(0);
 } catch {
   // Fail-open: never block a teammate due to hook errors

package/framework/hooks/claude-code/user-prompt/enrich-prompt.js

@@ -17,6 +17,7 @@
 import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists, loadState, getActiveFeature, getFeature, getPendingGates } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
 
 try {
   if (!stateExists()) pass();
@@ -82,8 +83,12 @@ try {
     }
   }
 
-  if (context.length === 0) pass();
+  if (context.length === 0) {
+    logHookActivity('enrich-prompt', 'UserPromptSubmit', 'ok');
+    pass();
+  }
 
+  logHookActivity('enrich-prompt', 'UserPromptSubmit', 'context_injected');
   injectContext(context.join('\n'));
 } catch {
   // Fail-open

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

@@ -19,6 +19,7 @@ import { openSync, writeSync, closeSync } from 'fs';
 import { writeFile, mkdir } from 'fs/promises';
 import { homedir } from 'os';
 import { join } from 'path';
+import { logHookActivity } from '../../shared/activity-logger.js';
 
 try {
   const payload = await readStdin();
@@ -53,6 +54,7 @@ try {
     closeSync(tty);
   } catch { /* terminal may not support /dev/tty */ }
 
+  logHookActivity('set-terminal-title', 'UserPromptSubmit', 'ok');
 } catch { /* fail-open */ }
 
 process.exit(0);