@polymorphism-tech/morph-spec 4.8.5 → 4.8.7

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.5  
+**Version:** 4.8.7  
 **Requires:** Node.js 18+, Claude Code
 
 ---
@@ -376,4 +376,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.8.5 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v4.8.7 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "4.8.5",
+  "version": "4.8.7",
   "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.5 by Polymorphism Tech*
+*morph-spec v4.8.7 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -203,4 +203,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.8.5 by Polymorphism Tech*
+*morph-spec v4.8.7 by Polymorphism Tech*

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

@@ -10,6 +10,7 @@ import subprocess
 import time
 import re
 import hashlib
+import traceback
 from pathlib import Path
 from datetime import datetime, timezone
 
@@ -29,11 +30,12 @@ BLUE = '\033[34m'
 GRAY = '\033[90m'
 WHITE = '\033[97m'
 
+# Windows: flag to hide console window when spawning subprocesses
+_CREATE_NO_WINDOW = 0x08000000 if os.name == 'nt' else 0
+
 
 # ── 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,
@@ -41,11 +43,15 @@ PHASE_POSITIONS = {
     'tasks': 4,
     'implement': 5, 'sync': 5,
 }
-PHASE_ABBREV = {
-    'proposal': 'prop', 'setup': 'setup',
-    'uiux': 'ui', 'design': 'design',
-    'clarify': 'clarify', 'tasks': 'tasks',
-    'implement': 'impl', 'sync': 'sync',
+PHASE_LABELS = {
+    'proposal': 'proposal',
+    'setup': 'setup',
+    'uiux': 'UI/UX',
+    'design': 'design',
+    'clarify': 'refinement',
+    'tasks': 'planning',
+    'implement': 'implement',
+    'sync': 'sync',
 }
 PIPELINE_TOTAL = 5
 
@@ -72,10 +78,10 @@ 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:
+    """Color based on context usage. Thresholds from Claude Code docs: 70% / 90%."""
+    if pct < 70:
         return GREEN
-    if pct < 80:
+    if pct < 90:
         return YELLOW
     return RED
 
@@ -94,36 +100,33 @@ def format_tokens(n):
     return str(n)
 
 
+def safe_int(val, default=0):
+    """Safely convert value to int, handling None from JSON null."""
+    if val is None: return default
+    try: return int(val)
+    except (TypeError, ValueError): return default
+
+
+def safe_float(val, default=0.0):
+    """Safely convert value to float, handling None from JSON null."""
+    if val is None: return default
+    try: return float(val)
+    except (TypeError, ValueError): return default
+
+
 # ── MORPH feature helpers ────────────────────────────────────────────────────
 
 def calculate_trust(checkpoints):
-    """Return (level_str, color, badge, pass_rate) from checkpoint array."""
+    """Return (level_str, color, pass_rate) from checkpoint array."""
     if not checkpoints:
-        return 'low', RED, '○○○○', 0.0
+        return 'none', GRAY, None  # no data — silent
     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:
+    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}"
+            return level, color, rate
+    return 'low', RED, 0.0
 
 
 def get_checkpoint_countdown(tasks_done):
@@ -134,56 +137,59 @@ def get_checkpoint_countdown(tasks_done):
     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_session_feature_names(features_dict, entries):
+    """Return only feature names mentioned in the current session's transcript.
+    If a feature name appears in the transcript (tool calls, messages, results),
+    this session is actively working on it. Prevents showing features from other sessions.
+    """
+    if not features_dict or not entries:
+        return set()
+    # Serialize last 500 entries for search (avoids cost on long sessions)
+    recent = entries[-500:] if len(entries) > 500 else entries
+    transcript_text = json.dumps(recent, ensure_ascii=False)
+    return {name for name in features_dict if name in transcript_text}
 
 
-def get_all_active_features(cwd):
-    """Return list of all in_progress features with enriched MORPH metadata."""
+def get_all_active_features(cwd, entries):
+    """Return in_progress features that are active in the current session."""
     state_path = Path(cwd) / '.morph' / 'state.json'
     if not state_path.exists():
         return []
     try:
-        state = json.loads(state_path.read_text())
+        state = json.loads(state_path.read_text(encoding='utf-8'))
         features = state.get('features', {})
+
+        # Filter to features belonging to this session (mentioned in transcript)
+        session_names = get_session_feature_names(features, entries)
+        if not session_names:
+            return []
+
         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)
+            if name not in session_names:
+                continue
+            phase    = feat.get('phase', '?')
+            tasks    = feat.get('tasks') or {}
+            done     = safe_int(tasks.get('completed'))
+            total    = safe_int(tasks.get('total'))
+            gates    = feat.get('approvalGates') or {}
+            checkpts = feat.get('checkpoints') or []
+
+            pending   = [g for g, v in gates.items() if not v.get('approved')]
+            trust_lvl, trust_color, trust_rate = calculate_trust(checkpts)
+            countdown = get_checkpoint_countdown(done)
 
             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,
+                '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,
+                'countdown':   countdown,
             })
         return result
     except Exception:
@@ -192,50 +198,61 @@ def get_all_active_features(cwd):
 
 # ── Git helpers ───────────────────────────────────────────────────────────────
 
+def _run_git(args, cwd):
+    """Run a git command safely on Windows (no console popup, with timeout)."""
+    return subprocess.check_output(
+        ['git'] + args,
+        cwd=cwd, stderr=subprocess.DEVNULL, timeout=3,
+        creationflags=_CREATE_NO_WINDOW,
+    ).decode().strip()
+
+
 def get_git_info(cwd):
-    """Get git branch and diff stats. Uses a 5s file cache to avoid lag."""
+    """Get git branch, files changed, line diff, and ahead/behind remote."""
     try:
-        cache_file = Path(cwd) / '.morph' / '.git-cache'
+        branch = _run_git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd)
+
+        # Files with changes (staged + unstaged, no untracked)
+        files = 0
         try:
-            if cache_file.exists():
-                age = time.time() - cache_file.stat().st_mtime
-                if age < 5:
-                    return cache_file.read_text().strip()
+            status_out = _run_git(['status', '--porcelain', '--untracked-files=no'], cwd)
+            files = len([l for l in status_out.splitlines() if l.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
+        # Lines inserted/removed vs HEAD
         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
+        try:
+            out = _run_git(['diff', 'HEAD', '--shortstat'], cwd)
+            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
+
+        # Commits ahead/behind remote
+        ahead, behind = 0, 0
+        try:
+            ab = _run_git(['rev-list', '--left-right', '--count', 'HEAD...@{upstream}'], cwd)
+            ahead, behind = (int(x) for x in ab.split('\t'))
+        except Exception:
+            pass
 
         parts = [f"{BLUE} {branch}{R}"]
+        if ahead or behind:
+            ab_str = ''
+            if ahead:  ab_str += f"{GREEN}↑{ahead}{R}"
+            if behind: ab_str += f"{RED}↓{behind}{R}"
+            parts.append(ab_str)
+        if files:
+            parts.append(f"{GRAY}{files} files{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
+        return ' '.join(parts)
     except Exception:
         return ""
 
@@ -243,10 +260,7 @@ def get_git_info(cwd):
 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()
+        out = _run_git(['worktree', 'list', '--porcelain'], cwd)
         entries, current = [], {}
         for line in out.splitlines():
             if line.startswith('worktree '):
@@ -314,95 +328,101 @@ def parse_timestamp(ts):
         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_session_start(cwd, transcript_path, entries):
+    """Return Unix timestamp for the start of the current session.
 
+    Uses two caches:
+    - sess-tp-*  : keyed by transcript_path — persists the start for this
+                   session even after long absences (wall-clock elapsed)
+    - sess-cwd-* : keyed by cwd, 2-min window — detects plan→accept
+                   (new transcript created seconds after the previous one)
 
-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]
-    # Use platform-appropriate cache directory
+    Each Claude Code window gets its own timer (per transcript).
+    """
     if os.name == 'nt':
         base = Path(os.environ.get('LOCALAPPDATA', str(Path.home() / 'AppData' / 'Local')))
         cache_dir = base / 'morph-spec' / 'cache'
     else:
         cache_dir = Path.home() / '.cache' / 'morph-spec'
-    cache_file = cache_dir / f'block-{h}.json'
-    now        = time.time()
-    block_s    = 5 * 3600
 
+    now = time.time()
+
+    if transcript_path:
+        tp_h     = hashlib.sha256(transcript_path.encode()).hexdigest()[:16]
+        tp_cache = cache_dir / f'sess-tp-{tp_h}.json'
+    else:
+        tp_cache = None
+
+    cwd_h     = hashlib.sha256(cwd.encode()).hexdigest()[:16]
+    cwd_cache = cache_dir / f'sess-cwd-{cwd_h}.json'
+
+    # 1. This transcript already has a recorded start?
+    session_start = None
     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
+        if tp_cache and tp_cache.exists():
+            session_start = json.loads(tp_cache.read_text()).get('session_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
+    # 2. New transcript — continuation from plan→accept? (cwd gap < 2 min)
+    if session_start is None:
+        try:
+            if cwd_cache.exists():
+                cwd_data = json.loads(cwd_cache.read_text())
+                if (now - cwd_data.get('last_seen', 0)) < 120:
+                    session_start = cwd_data.get('session_start')
+        except Exception:
+            pass
+
+    # 3. Genuinely new session — use first entry from current transcript
+    if session_start is None:
+        for entry in entries:
+            ts = entry.get('timestamp')
+            if not ts:
+                continue
+            t = parse_timestamp(ts)
+            if t is not None:
+                session_start = t
+                break
 
-    if start is None:
+    if session_start is None:
         return None
 
+    # Persist both caches
     try:
         cache_dir.mkdir(parents=True, exist_ok=True)
-        cache_file.write_text(json.dumps({'block_start': start}))
+        payload = json.dumps({'session_start': session_start, 'last_seen': now})
+        if tp_cache:
+            tp_cache.write_text(payload)
+        cwd_cache.write_text(payload)
     except Exception:
         pass
-    return start
+
+    return session_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)
+def get_session_duration(session_start):
+    """Format elapsed time since session_start. Returns string or None."""
+    if session_start is None:
+        return None
+    elapsed_s = time.time() - session_start
+    hours   = int(elapsed_s // 3600)
+    minutes = int((elapsed_s % 3600) // 60)
     if hours == 0:
-        time_str = f"{minutes}m"
+        return f"{minutes}m"
     elif minutes == 0:
-        time_str = f"{hours}hr"
+        return f"{hours}hr"
     else:
-        time_str = f"{hours}hr {minutes}m"
-    return f"{progress_bar(pct, 6)} {time_str}"
+        return f"{hours}hr {minutes}m"
+
+
+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
+
 
 
 # ── Main ──────────────────────────────────────────────────────────────────────
@@ -416,127 +436,143 @@ def main():
     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:
+    try:
+        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, entries)
+        for feat in features:
+            # Feature name with visual prefix
+            parts = [f"{CYAN}{BOLD}► {feat['name']}{R}"]
+
+            # Phase: human-readable label + position in pipeline (e.g. "implement 4/5")
+            phase = feat['phase']
+            pos   = PHASE_POSITIONS.get(phase)
+            label = PHASE_LABELS.get(phase, phase)
+            if pos:
+                parts.append(f"{CYAN}{label} {pos}/{PIPELINE_TOTAL}{R}")
+            elif phase != '?':
+                parts.append(f"{CYAN}{label}{R}")
+
+            # Task progress (only if tasks exist)
+            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']} tasks{R}")
+
+            # Checkpoint: only show when imminent (0 = now, 1 = next task)
             if feat['countdown'] == 0:
-                parts.append(f"{GREEN}ckpt!{R}")          # just hit checkpoint
+                parts.append(f"{GREEN}💾 checkpoint!{R}")
             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}")
+                parts.append(f"{YELLOW}💾 in 1 task{R}")
 
-        # Pending approval gate (blocking — already triggered, not yet approved)
-        if feat['pending']:
-            parts.append(f"{YELLOW}⏳ {feat['pending']} pending{R}")
+            # Trust: silent when good, alert only if problematic
+            if feat['trust_level'] == 'low':
+                parts.append(f"{RED}⚠ low trust{R}")
+            elif feat['trust_level'] == 'medium':
+                parts.append(f"{YELLOW}⚠ medium trust{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}")
+            # Blocking approval gate
+            if feat['pending']:
+                parts.append(f"{RED}⛔ approval required{R}")
 
-        print('  |  '.join(parts))
+            print('  |  '.join(parts))
 
-    # ── Session info line (always shown) ─────────────────────────────────────
-    parts2 = []
+        # ── 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}")
+        # 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)
+        # Model
+        model = data.get('model') or ''
+        if isinstance(model, dict):
+            model_name = model.get('display_name') or model.get('id') or ''
+        else:
+            model_name = str(model) if model else ''
+        if model_name:
+            short = model_name.replace('Claude ', '').replace('claude-', '').replace(' (claude.ai)', '')
+            parts2.append(f"{WHITE}{BOLD}🤖 {short}{R}")
+
+        # Permission mode (only shown when non-default)
+        perm = data.get('permission_mode') or ''
+        if perm and perm != 'default':
+            _perm_labels = {
+                'plan':               '📋 plan',
+                'acceptEdits':        '✏ accept edits',
+                'bypassPermissions':  '⚠ bypass',
+                'dontAsk':            '🔕 auto',
+            }
+            parts2.append(f"{YELLOW}{_perm_labels.get(perm, perm)}{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)
         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))
+        # Context window
+        # used_percentage excludes output_tokens — underestimates real usage in long sessions.
+        # Compute (input + cache_creation + cache_read + output) / context_window_size,
+        # which reflects true context consumption for the next turn.
+        ctx = data.get('context_window', {})
+        if ctx:
+            cur_usage = ctx.get('current_usage') or {}
+            total_ctx = safe_int(ctx.get('context_window_size'))
+            if isinstance(cur_usage, dict) and total_ctx > 0:
+                tokens = (safe_int(cur_usage.get('input_tokens'))
+                        + safe_int(cur_usage.get('cache_creation_input_tokens'))
+                        + safe_int(cur_usage.get('cache_read_input_tokens'))
+                        + safe_int(cur_usage.get('output_tokens')))
+                used_pct = tokens / total_ctx * 100 if tokens > 0 else safe_float(ctx.get('used_percentage'))
+            else:
+                used_pct = safe_float(ctx.get('used_percentage'))
+            color  = ctx_color(used_pct)
+            bar    = progress_bar(used_pct, 8)
+            toks   = f"{format_tokens(tokens)}/{format_tokens(total_ctx)}" if total_ctx and isinstance(cur_usage, dict) else ""
+            suffix = f" {RED}~cmpct{R}" if used_pct >= 90 else ""
+            line   = f"{color}{bar} {used_pct:.0f}%{R}"
+            if toks:
+                line += f" ({toks})"
+            parts2.append(line + 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}")
+
+        # 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)
+
+        if parts2:
+            print('  |  '.join(parts2))
+
+    except Exception:
+        err = traceback.format_exc().splitlines()[-1]
+        print(f"{RED}ERRO: {err}{R}")
 
 
 if __name__ == '__main__':

package/framework/hooks/dev/guard-version-numbers.js

@@ -7,7 +7,7 @@
  * Scope: Framework codebase only (dev hook)
  *
  * Blocks Write/Edit to files that contain hardcoded version patterns
- * like "MORPH-SPEC v4.8.5". Version should only be in package.json.
+ * like "MORPH-SPEC v4.8.7". Version should only be in package.json.
  *
  * Checked extensions: .md, .cs, .css, .js (covers templates + source)
  * Exceptions: CHANGELOG.md, node_modules/, test/, package.json, package-lock.json

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

@@ -14,12 +14,33 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 
 # morph-init — LLM-Powered Project Initialization
 
-> Run once after `npm install -g @polymorphism-tech/morph-spec`.
+> Run once after `npm install @polymorphism-tech/morph-spec`.
 > Re-run as `/morph-init refresh` when your project evolves.
 
 ---
 
-## Step 0 — Required Plugins
+## Step 0 — Resolve CLI
+
+Before running any `morph-spec` command, detect how to invoke the CLI:
+
+```bash
+# Try local first (project dependency), then global
+npx morph-spec --version
+```
+
+- If `npx morph-spec --version` succeeds → use `npx morph-spec` as the CLI prefix for all commands.
+- If it fails → try `morph-spec --version` (global install). If that works → use `morph-spec`.
+- If both fail → **STOP** and show:
+  ```
+  morph-spec CLI not found. Install it first:
+    npm install @polymorphism-tech/morph-spec
+  ```
+
+Use the resolved CLI prefix (e.g. `npx morph-spec`) for ALL bash commands in the following steps.
+
+---
+
+## Step 1 — Required Plugins
 
 Check for required Claude Code plugins: **superpowers** and **context7**.
 
@@ -30,8 +51,8 @@ Read `~/.claude/plugins/installed_plugins.json` and check for:
 For each missing plugin, run:
 
 ```bash
-morph-spec install-plugin superpowers
-morph-spec install-plugin context7
+npx morph-spec install-plugin superpowers
+npx morph-spec install-plugin context7
 ```
 
 **If the command succeeds:** `✓ {plugin} installed. Restart Claude Code after /morph-init completes.`
@@ -53,25 +74,30 @@ Both `superpowers` and `context7` are required. Do not continue if either is mis
 
 ---
 
-## Step 1 — Infrastructure
+## Step 2 — Infrastructure
 
 Check if `.morph/` exists in the current directory.
 
 **If MISSING:**
 ```bash
-morph-spec setup-infra
+npx morph-spec setup-infra
 ```
 Output confirms: `✓ MORPH-SPEC infrastructure installed.`
 
-**If EXISTS and argument is `refresh`:** Continue — will overwrite context and config.
+**If EXISTS and argument is `refresh`:**
+Re-run setup-infra to update framework files, then continue with context/config refresh:
+```bash
+npx morph-spec setup-infra
+```
 
 **If EXISTS and no argument:**
 Ask: *"MORPH already initialized. Refresh context and config? (y/n)"*
+If `y` → re-run `npx morph-spec setup-infra` then continue.
 If `n` → STOP.
 
 ---
 
-## Step 2 — Analyze Project
+## Step 3 — Analyze Project
 
 Gather evidence to build a stack map. Run these in parallel:
 
@@ -104,7 +130,7 @@ backendPath:   src/backend (if monorepo)
 
 ---
 
-## Step 3 — Ask Targeted Questions
+## Step 4 — Ask Targeted Questions
 
 **Rule: only ask what cannot be inferred with ≥90% confidence from files.**
 
@@ -120,7 +146,7 @@ Do **not** ask about technology already confirmed by file evidence.
 
 ---
 
-## Step 4 — Generate `context/README.md`
+## Step 5 — Generate `context/README.md`
 
 Write `.morph/context/README.md`:
 
@@ -148,7 +174,7 @@ Write `.morph/context/README.md`:
 
 ---
 
-## Step 5 — Update `config.json`
+## Step 6 — Update `config.json`
 
 Read `.morph/config/config.json` and merge into `project`:
 
@@ -171,14 +197,14 @@ Read `.morph/config/config.json` and merge into `project`:
 
 ---
 
-## Step 6 — Configure MCPs
+## Step 7 — Configure MCPs
 
 For each detected integration with an available MCP:
 
 **Supabase detected:**
 > *"Configure Supabase MCP now? I'll need `SUPABASE_URL` and `SERVICE_ROLE_KEY`."*
 - YES → collect credentials → add to `.claude/settings.local.json` under `mcpServers`
-- NO → show snippet + `morph-spec mcp setup supabase`
+- NO → show snippet + `npx morph-spec mcp setup supabase`
 
 **GitHub:**
 > *"Configure GitHub MCP? I'll need a `GITHUB_PERSONAL_ACCESS_TOKEN`."*
@@ -188,7 +214,7 @@ Only offer Figma, Docker, Azure if explicitly detected in `.env.example`.
 
 ---
 
-## Step 7 — Final Output
+## Step 8 — Final Output
 
 Before printing the summary, check `~/.claude/settings.local.json` for `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`. If set to `"1"`, mark Agent Teams as enabled; otherwise show the warning.
 

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.5"
+cliVersion: "4.8.7"
 ---
 
 # 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.5"
+cliVersion: "4.8.7"
 ---
 
 # 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.5"
+cliVersion: "4.8.7"
 ---
 
 # 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.5"
+cliVersion: "4.8.7"
 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.5"
+cliVersion: "4.8.7"
 ---
 
 # 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.5"
+cliVersion: "4.8.7"
 ---
 
 # 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.5"
+cliVersion: "4.8.7"
 ---
 
 # MORPH UI/UX Design - FASE 1.5

package/package.json

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