@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

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

@@ -0,0 +1,538 @@
+#!/usr/bin/env python3
+# framework/hooks/claude-code/statusline.py
+# Claude Code statusline for morph-spec
+# Receives JSON via stdin from Claude Code after each response
+
+import sys
+import json
+import os
+import subprocess
+import time
+import re
+import hashlib
+from pathlib import Path
+from datetime import datetime, timezone
+
+# Ensure UTF-8 output on Windows (stdout defaults to CP1252 otherwise)
+if hasattr(sys.stdout, 'reconfigure'):
+    sys.stdout.reconfigure(encoding='utf-8')
+
+# ANSI colors
+R = '\033[0m'       # Reset
+BOLD = '\033[1m'
+CYAN = '\033[36m'
+MAGENTA = '\033[35m'
+GREEN = '\033[32m'
+YELLOW = '\033[33m'
+RED = '\033[31m'
+BLUE = '\033[34m'
+GRAY = '\033[90m'
+WHITE = '\033[97m'
+
+
+# ── MORPH framework constants (derived from phases.json / trust-manager.js) ──
+
+# Ordered core phases for pipeline mini-map (5 positions, optional phases mapped)
+# uiux maps to position 2 (same slot as design — they're mutually exclusive in practice)
+PHASE_POSITIONS = {
+    'proposal': 1, 'setup': 1,
+    'uiux': 2, 'design': 2,
+    'clarify': 3,
+    'tasks': 4,
+    'implement': 5, 'sync': 5,
+}
+PHASE_ABBREV = {
+    'proposal': 'prop', 'setup': 'setup',
+    'uiux': 'ui', 'design': 'design',
+    'clarify': 'clarify', 'tasks': 'tasks',
+    'implement': 'impl', 'sync': 'sync',
+}
+PIPELINE_TOTAL = 5
+
+# Approval gates per phase (from phases.json pausePoints)
+PHASE_GATES = {
+    'proposal': 'proposal',
+    'uiux':     'uiux',
+    'design':   'design',
+    'tasks':    'tasks',
+}
+
+# Trust level thresholds and badges (from trust-manager.js)
+# passRate >= threshold → level
+TRUST_LEVELS = [
+    (0.95, 'maximum', GREEN + BOLD, '◆◆◆◆'),
+    (0.90, 'high',    GREEN,        '◆◆◆○'),
+    (0.80, 'medium',  YELLOW,       '◆◆○○'),
+    (0.00, 'low',     RED,          '◆○○○'),
+]
+
+CHECKPOINT_FREQUENCY = 3  # matches llm-interaction.json default
+
+
+# ── General helpers ──────────────────────────────────────────────────────────
+
+def ctx_color(pct):
+    """Color based on context usage. 80% = Claude's auto-compact threshold."""
+    if pct < 60:
+        return GREEN
+    if pct < 80:
+        return YELLOW
+    return RED
+
+
+def progress_bar(pct, width=8):
+    filled = int(pct / 100 * width)
+    empty = width - filled
+    return f"{'█' * filled}{'░' * empty}"
+
+
+def format_tokens(n):
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}m"
+    if n >= 1000:
+        return f"{n // 1000}k"
+    return str(n)
+
+
+# ── MORPH feature helpers ────────────────────────────────────────────────────
+
+def calculate_trust(checkpoints):
+    """Return (level_str, color, badge, pass_rate) from checkpoint array."""
+    if not checkpoints:
+        return 'low', RED, '○○○○', 0.0
+    total = len(checkpoints)
+    passed = sum(1 for c in checkpoints if c.get('passed'))
+    rate = passed / total
+    for threshold, level, color, badge in TRUST_LEVELS:
+        if rate >= threshold:
+            return level, color, badge, rate
+    return 'low', RED, '○○○○', rate
+
+
+def get_phase_minimap(phase):
+    """Return colored dot strip + phase abbrev, e.g. '●►○○○ design'."""
+    pos = PHASE_POSITIONS.get(phase)
+    if pos is None:
+        return None
+    dots = ''
+    for i in range(1, PIPELINE_TOTAL + 1):
+        if i < pos:
+            dots += f"{GREEN}●{R}"
+        elif i == pos:
+            dots += f"{CYAN}►{R}"
+        else:
+            dots += f"{GRAY}○{R}"
+    abbrev = PHASE_ABBREV.get(phase, phase)
+    return f"{dots} {CYAN}{abbrev}{R}"
+
+
+def get_checkpoint_countdown(tasks_done):
+    """Tasks remaining until next checkpoint fires (frequency=3)."""
+    if tasks_done <= 0:
+        return None
+    remaining = CHECKPOINT_FREQUENCY - (tasks_done % CHECKPOINT_FREQUENCY)
+    return 0 if remaining == CHECKPOINT_FREQUENCY else remaining
+
+
+def get_next_gate(phase, approval_gates):
+    """Return the upcoming gate for this phase if not yet triggered in state."""
+    gate_id = PHASE_GATES.get(phase)
+    if not gate_id:
+        return None
+    # If the gate already appears in approvalGates (approved or pending),
+    # it's either done or already shown as pending — don't duplicate.
+    if gate_id in (approval_gates or {}):
+        return None
+    return gate_id
+
+
+def get_all_active_features(cwd):
+    """Return list of all in_progress features with enriched MORPH metadata."""
+    state_path = Path(cwd) / '.morph' / 'state.json'
+    if not state_path.exists():
+        return []
+    try:
+        state = json.loads(state_path.read_text())
+        features = state.get('features', {})
+        result = []
+        for name, feat in features.items():
+            if feat.get('status') != 'in_progress':
+                continue
+            phase      = feat.get('phase', '?')
+            tasks      = feat.get('tasks', {})
+            done       = tasks.get('completed', 0)
+            total      = tasks.get('total', 0)
+            gates      = feat.get('approvalGates', {})
+            checkpts   = feat.get('checkpoints', [])
+
+            pending    = [g for g, v in gates.items() if not v.get('approved')]
+            trust_lvl, trust_color, trust_badge, trust_rate = calculate_trust(checkpts)
+            countdown  = get_checkpoint_countdown(done)
+            next_gate  = get_next_gate(phase, gates)
+            minimap    = get_phase_minimap(phase)
+
+            result.append({
+                'name':         name,
+                'phase':        phase,
+                'tasks_done':   done,
+                'tasks_total':  total,
+                'pending':      pending[0] if pending else None,
+                'trust_level':  trust_lvl,
+                'trust_color':  trust_color,
+                'trust_badge':  trust_badge,
+                'trust_rate':   trust_rate,
+                'countdown':    countdown,
+                'next_gate':    next_gate,
+                'minimap':      minimap,
+            })
+        return result
+    except Exception:
+        return []
+
+
+# ── Git helpers ───────────────────────────────────────────────────────────────
+
+def get_git_info(cwd):
+    """Get git branch and diff stats. Uses a 5s file cache to avoid lag."""
+    try:
+        cache_file = Path(cwd) / '.morph' / '.git-cache'
+        try:
+            if cache_file.exists():
+                age = time.time() - cache_file.stat().st_mtime
+                if age < 5:
+                    return cache_file.read_text().strip()
+        except Exception:
+            pass
+
+        branch = subprocess.check_output(
+            ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+            cwd=cwd, stderr=subprocess.DEVNULL, timeout=2
+        ).decode().strip()
+
+        # Diff stats: insertions/deletions from staged + unstaged changes
+        ins, dels = 0, 0
+        for cmd in [['diff', '--shortstat'], ['diff', '--cached', '--shortstat']]:
+            try:
+                out = subprocess.check_output(
+                    ['git'] + cmd, cwd=cwd, stderr=subprocess.DEVNULL, timeout=2
+                ).decode()
+                m = re.search(r'(\d+) insertion', out)
+                if m:
+                    ins += int(m.group(1))
+                m = re.search(r'(\d+) deletion', out)
+                if m:
+                    dels += int(m.group(1))
+            except Exception:
+                pass
+
+        parts = [f"{BLUE} {branch}{R}"]
+        if ins or dels:
+            parts.append(f"{GREEN}+{ins}{R}{GRAY},{R}{RED}-{dels}{R}")
+
+        result = ' '.join(parts)
+        try:
+            cache_file.parent.mkdir(parents=True, exist_ok=True)
+            cache_file.write_text(result)
+        except Exception:
+            pass
+        return result
+    except Exception:
+        return ""
+
+
+def get_worktree_info(cwd):
+    """Detect if running in a git worktree (not the main worktree)."""
+    try:
+        out = subprocess.check_output(
+            ['git', 'worktree', 'list', '--porcelain'],
+            cwd=cwd, stderr=subprocess.DEVNULL, timeout=2
+        ).decode()
+        entries, current = [], {}
+        for line in out.splitlines():
+            if line.startswith('worktree '):
+                if current:
+                    entries.append(current)
+                current = {'path': line.split(' ', 1)[1]}
+            elif line.startswith('branch '):
+                current['branch'] = line.split(' ', 1)[1]
+        if current:
+            entries.append(current)
+        if len(entries) > 1:
+            cwd_r = str(Path(cwd).resolve())
+            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}"
+    except Exception:
+        pass
+    return ""
+
+
+# ── Transcript / JSONL helpers ────────────────────────────────────────────────
+
+def read_transcript_jsonl(path):
+    """Read and parse JSONL transcript file. Returns list of parsed entries."""
+    entries = []
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entries.append(json.loads(line))
+                except Exception:
+                    pass
+    except Exception:
+        pass
+    return entries
+
+
+def get_token_metrics(entries):
+    """Sum token usage from all non-sidechain JSONL entries."""
+    total_input, total_output, total_cached = 0, 0, 0
+    for entry in entries:
+        if entry.get('isSidechain') or entry.get('isApiErrorMessage'):
+            continue
+        usage = (entry.get('message') or {}).get('usage') or {}
+        if not usage:
+            continue
+        total_input  += usage.get('input_tokens', 0)
+        total_output += usage.get('output_tokens', 0)
+        total_cached += (
+            usage.get('cache_creation_input_tokens', 0) +
+            usage.get('cache_read_input_tokens', 0)
+        )
+    return {'input': total_input, 'output': total_output, 'cached': total_cached}
+
+
+def parse_timestamp(ts):
+    """Parse ISO 8601 timestamp to Unix float. Returns None on error."""
+    try:
+        return datetime.fromisoformat(ts.replace('Z', '+00:00')).timestamp()
+    except Exception:
+        return None
+
+
+def get_session_duration(entries):
+    """Elapsed time since first message. Returns 'Xhr Ym' or None."""
+    now = time.time()
+    for entry in entries:
+        ts = entry.get('timestamp')
+        if not ts:
+            continue
+        t = parse_timestamp(ts)
+        if t is None:
+            continue
+        elapsed_s = now - t
+        hours   = int(elapsed_s // 3600)
+        minutes = int((elapsed_s % 3600) // 60)
+        if hours == 0:
+            return f"{minutes}m"
+        elif minutes == 0:
+            return f"{hours}hr"
+        else:
+            return f"{hours}hr {minutes}m"
+    return None
+
+
+def get_session_name(entries):
+    """Find the most recent /rename title. Returns string or None."""
+    for entry in reversed(entries):
+        if entry.get('type') == 'custom-title' and entry.get('customTitle'):
+            return entry['customTitle']
+    return None
+
+
+def get_block_start(transcript_path, entries):
+    """Find start of current 5-hour billing block. Cached per transcript."""
+    h = hashlib.sha256(transcript_path.encode()).hexdigest()[:16]
+    cache_dir  = Path.home() / '.cache' / 'morph-spec'
+    cache_file = cache_dir / f'block-{h}.json'
+    now        = time.time()
+    block_s    = 5 * 3600
+
+    try:
+        if cache_file.exists():
+            cached = json.loads(cache_file.read_text())
+            start  = cached.get('block_start')
+            if start and (now - start) < block_s:
+                return start
+    except Exception:
+        pass
+
+    start = None
+    for entry in entries:
+        ts = entry.get('timestamp')
+        if not ts:
+            continue
+        t = parse_timestamp(ts)
+        if t is None:
+            continue
+        if (now - t) <= block_s:
+            start = t
+            break
+
+    if start is None:
+        return None
+
+    try:
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        cache_file.write_text(json.dumps({'block_start': start}))
+    except Exception:
+        pass
+    return start
+
+
+def format_block_timer(block_start):
+    """Format block timer as 'bar Xhr Ym' relative to 5-hour window."""
+    now       = time.time()
+    elapsed_s = max(0.0, now - block_start)
+    pct       = min(elapsed_s / (5 * 3600) * 100, 100)
+    hours     = int(elapsed_s // 3600)
+    minutes   = int((elapsed_s % 3600) // 60)
+    if hours == 0:
+        time_str = f"{minutes}m"
+    elif minutes == 0:
+        time_str = f"{hours}hr"
+    else:
+        time_str = f"{hours}hr {minutes}m"
+    return f"{progress_bar(pct, 6)} {time_str}"
+
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            sys.exit(0)
+        data = json.loads(raw)
+    except Exception:
+        sys.exit(0)
+
+    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.
+    entries = read_transcript_jsonl(transcript_path) if transcript_path else []
+
+    # ── MORPH feature lines (one line per active feature) ────────────────────
+    features = get_all_active_features(cwd)
+    for feat in features:
+        parts = [f"{CYAN}{BOLD}{feat['name']}{R}"]
+
+        # Phase pipeline mini-map: ●●►○○ design
+        if feat['minimap']:
+            parts.append(feat['minimap'])
+
+        # Task progress bar
+        if feat['tasks_total'] > 0:
+            pct = feat['tasks_done'] / feat['tasks_total'] * 100
+            bar = progress_bar(pct, 6)
+            parts.append(f"{GREEN}{bar} {feat['tasks_done']}/{feat['tasks_total']}{R}")
+
+        # Checkpoint countdown: how many tasks until next validation fires
+        if feat['countdown'] is not None:
+            if feat['countdown'] == 0:
+                parts.append(f"{GREEN}ckpt!{R}")          # just hit checkpoint
+            elif feat['countdown'] == 1:
+                parts.append(f"{YELLOW}ckpt:1{R}")        # 1 task away — heads up
+            else:
+                parts.append(f"{GRAY}ckpt:{feat['countdown']}{R}")
+
+        # Trust level badge: ◆◆◆○ high
+        tc = feat['trust_color']
+        parts.append(f"{tc}{feat['trust_badge']}{R}")
+
+        # Pending approval gate (blocking — already triggered, not yet approved)
+        if feat['pending']:
+            parts.append(f"{YELLOW}⏳ {feat['pending']} pending{R}")
+
+        # Upcoming gate (not yet triggered — reminds what comes at end of phase)
+        if feat['next_gate']:
+            parts.append(f"{GRAY}→gate:{feat['next_gate']}{R}")
+
+        print('  |  '.join(parts))
+
+    # ── Session info line (always shown) ─────────────────────────────────────
+    parts2 = []
+
+    # Session name (set via /rename)
+    if entries:
+        session_name = get_session_name(entries)
+        if session_name:
+            parts2.append(f"{CYAN}{BOLD}📌 {session_name}{R}")
+
+    # Model
+    model      = data.get('model', {})
+    model_name = model.get('display_name', model.get('id', ''))
+    if model_name:
+        short = model_name.replace('Claude ', '').replace(' (claude.ai)', '')
+        parts2.append(f"{WHITE}{BOLD}🤖 {short}{R}")
+
+    # Session clock (elapsed time since first message)
+    if entries:
+        duration = get_session_duration(entries)
+        if duration:
+            parts2.append(f"{YELLOW}⏱ {duration}{R}")
+
+    # Block timer (progress through current 5-hour billing window)
+    if entries and transcript_path:
+        block_start = get_block_start(transcript_path, entries)
+        if block_start is not None:
+            parts2.append(f"{YELLOW}blk:{format_block_timer(block_start)}{R}")
+
+    # Context window (60% = yellow, 80% = red/auto-compact threshold)
+    ctx = data.get('context_window', {})
+    if ctx:
+        used_pct  = ctx.get('used_percentage', 0)
+        cur       = ctx.get('current_usage', 0)
+        total_ctx = ctx.get('context_window_size', 0)
+        color     = ctx_color(used_pct)
+        bar       = progress_bar(used_pct, 8)
+        toks      = f"{format_tokens(cur)}/{format_tokens(total_ctx)}"
+        suffix    = f" {RED}~cmpct{R}" if used_pct >= 80 else ""
+        parts2.append(f"{color}{bar} {used_pct:.0f}%{R} ({toks}){suffix}")
+
+    # Token breakdown from JSONL (session totals: input / output / cached)
+    if entries:
+        tok = get_token_metrics(entries)
+        tok_parts = []
+        if tok['input']:
+            tok_parts.append(f"in:{format_tokens(tok['input'])}")
+        if tok['output']:
+            tok_parts.append(f"out:{format_tokens(tok['output'])}")
+        if tok['cached']:
+            tok_parts.append(f"↩{format_tokens(tok['cached'])}")
+        if tok_parts:
+            parts2.append(f"{GRAY}{' '.join(tok_parts)}{R}")
+
+    # Cost
+    cost = data.get('cost', {})
+    if cost.get('total_cost_usd'):
+        usd = cost['total_cost_usd']
+        parts2.append(f"{GRAY}${usd:.3f}{R}")
+
+    # Agent name (if running in agent mode)
+    agent = data.get('agent', {})
+    if agent.get('name'):
+        parts2.append(f"{BLUE}agent:{agent['name']}{R}")
+
+    # Git info (branch + diff stats, 5s cached)
+    git = get_git_info(cwd)
+    if git:
+        parts2.append(git)
+
+    # Worktree info
+    wt = get_worktree_info(cwd)
+    if wt:
+        parts2.append(wt)
+
+    if parts2:
+        print('  |  '.join(parts2))
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# morph-spec statusline — installed globally to ~/.claude/statusline.sh
+# Claude Code invokes this with JSON via stdin after each response.
+# Requires: Python 3 available as `python3` on PATH.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+python3 "${SCRIPT_DIR}/statusline.py" 2>/dev/null || true

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

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * Stop Hook: Validate Completion (Advisory)
+ *
+ * Event: Stop
+ *
+ * When Claude stops, checks for incomplete work:
+ *   - In implement phase: checks uncompleted tasks
+ *   - In spec phases: checks required outputs still created: false
+ *   - Returns additionalContext with what remains (advisory, not blocking)
+ *
+ * Uses stop_hook_active env check to prevent infinite loops.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { stateExists, getActiveFeature, getMissingOutputs } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+
+try {
+  // Prevent infinite loop
+  if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') pass();
+
+  if (!stateExists()) pass();
+
+  const active = getActiveFeature();
+  if (!active) pass();
+
+  const { name, feature } = active;
+  const warnings = [];
+
+  // Check for incomplete tasks during implement phase
+  if (feature.phase === 'implement' && feature.tasks) {
+    const remaining = (feature.tasks.total || 0) - (feature.tasks.completed || 0);
+    if (remaining > 0) {
+      warnings.push(`${remaining} task(s) remaining for feature '${name}'`);
+      if (feature.tasks.inProgress > 0) {
+        warnings.push(`  ${feature.tasks.inProgress} task(s) still in progress`);
+      }
+    }
+  }
+
+  // Check for missing outputs in spec phases
+  if (['proposal', 'design', 'clarify', 'tasks', 'uiux'].includes(feature.phase)) {
+    const missing = getMissingOutputs(name);
+    if (missing.length > 0) {
+      warnings.push(`Missing outputs for '${name}' (${feature.phase} phase):`);
+      for (const output of missing.slice(0, 5)) {
+        warnings.push(`  - ${output.type}: ${output.path}`);
+      }
+      if (missing.length > 5) {
+        warnings.push(`  ... and ${missing.length - 5} more`);
+      }
+    }
+  }
+
+  // Check pending approval gates
+  if (feature.approvalGates) {
+    const pendingGates = Object.entries(feature.approvalGates)
+      .filter(([, gate]) => !gate.approved && gate.timestamp === null)
+      .map(([name]) => name);
+
+    // Only warn about gates relevant to current/past phases
+    const relevantGates = pendingGates.filter(gate => {
+      const gatePhaseMap = { proposal: 'proposal', uiux: 'uiux', design: 'design', tasks: 'tasks' };
+      return gatePhaseMap[gate] !== undefined;
+    });
+
+    if (relevantGates.length > 0) {
+      warnings.push(`Pending approvals: ${relevantGates.join(', ')}`);
+    }
+  }
+
+  if (warnings.length === 0) pass();
+
+  const message = [
+    'MORPH-SPEC: Incomplete work detected:',
+    ...warnings.map(w => `  ${w}`),
+    '',
+    'Resume with: morph-spec status ' + name
+  ].join('\n');
+
+  injectContext(message);
+} catch {
+  // Fail-open
+  process.exit(0);
+}