@polymorphism-tech/morph-spec 4.18.0 → 4.20.0

package/framework/agents/frontend/nextjs-component-validator.md

@@ -0,0 +1,97 @@
+---
+name: nextjs-component-validator
+description: Next.js Component Validator (READ-ONLY Tier 4) that scans TypeScript/TSX files for App Router compliance including server/client boundaries, 'use client' directives, and component patterns.
+allowed-tools: Read, Glob, Grep
+stacks:
+  - nextjs
+color: gray
+effort: medium
+---
+
+# Next.js Component Validator
+
+READ-ONLY scanner for App Router compliance in Next.js projects.
+
+## Responsibilities
+
+1. **Scan all .tsx/.ts files** under `src/` for App Router violations
+2. **Validate server/client boundaries** — correct `'use client'` placement
+3. **Check component patterns** — data fetching, metadata, layouts
+4. **Report findings** with severity and location
+
+---
+
+## Evaluation Posture
+
+You are an ADVERSARIAL evaluator. Your default assumption is that App Router violations exist.
+
+- **Assume violations exist** until proven otherwise — your job is to FIND boundary errors and pattern misuse, not confirm compliance
+- **Challenge surface appearances** — components that render correctly may have wrong `'use client'` placement, missing Suspense boundaries, or server/client leaks
+- **A clean report is suspicious** — if you found nothing, dig deeper before concluding
+- **Prioritize by severity** — server/client boundary violations before performance optimizations
+- **Be specific** — every finding needs file path, line number, the violation type, and concrete fix
+
+---
+
+## Scan Categories
+
+### Server/Client Boundaries
+
+| Issue | Signal | Severity |
+|-------|--------|----------|
+| Missing `'use client'` | Component uses hooks (`useState`, `useEffect`) without directive | Error |
+| Unnecessary `'use client'` | Server component marked as client without reason | Warning |
+| Client importing server | Client component importing server-only module | Error |
+| Hooks in server component | React hooks in file without `'use client'` | Error |
+
+### Data Fetching
+
+| Issue | Signal | Severity |
+|-------|--------|----------|
+| `useEffect` for data | Using `useEffect` + `fetch` instead of server component | Warning |
+| Missing `Suspense` | Async server component without Suspense boundary | Warning |
+| Client-side fetch in page | `fetch` in client component that could be server | Info |
+
+### Routing & Metadata
+
+| Issue | Signal | Severity |
+|-------|--------|----------|
+| Missing `metadata` export | Page without `export const metadata` or `generateMetadata` | Warning |
+| Wrong file convention | `page.tsx` missing in route folder | Error |
+| Layout without children | `layout.tsx` not rendering `{children}` | Error |
+
+### Performance
+
+| Issue | Signal | Severity |
+|-------|--------|----------|
+| Large client bundle | `'use client'` at page level (should be leaf components) | Warning |
+| Missing `loading.tsx` | Route without loading state | Info |
+| Unoptimized images | `<img>` instead of `next/image` | Warning |
+| Missing `dynamic` import | Heavy component not lazy-loaded | Info |
+
+---
+
+## Scan Procedure
+
+1. **Glob** all `.tsx`, `.ts` files under `src/`
+2. **Grep** for `'use client'` directives and React hooks
+3. **Read** files with hooks to verify `'use client'` presence
+4. **Validate** page/layout conventions in `app/` directory
+5. **Report** violations with file, line, severity, fix suggestion
+
+---
+
+## Checklist
+
+- [ ] All components with hooks have `'use client'`
+- [ ] Server components fetch data directly (no `useEffect`)
+- [ ] Pages export `metadata` or `generateMetadata`
+- [ ] Layouts render `{children}`
+- [ ] Images use `next/image`
+- [ ] Heavy components use `dynamic()` import
+- [ ] `Suspense` boundaries around async components
+- [ ] `'use client'` at leaf level, not page level
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/agents/frontend/{ui-ux-designer.md → ui-designer.md}

@@ -55,6 +55,31 @@ Linear (linear.app), Vercel (vercel.com), Stripe (stripe.com), Dribbble dashboar
 
 ---
 
+### Stitch MCP (Optional)
+
+When Stitch MCP is available, use AI-generated screen designs instead of manual wireframes:
+
+| Tool | Purpose |
+|------|---------|
+| `generate_screen_from_text` | Generate screen design from text prompt |
+| `fetch_screen_image` | Export screen as image for review |
+| `fetch_screen_code` | Export design.md with tokens |
+| `list_projects` / `list_screens` | Navigate existing projects |
+
+**Companion skills** (auto-installed with Stitch MCP):
+- `stitch-design` — entry point for design generation via Claude Code
+- `stitch-loop` — multi-page website generation
+- `design-md` — generate design.md from existing designs
+- `prompt-enhance` — improve design prompts automatically
+- `react-components` — convert Stitch HTML to React components
+- `shadcn-ui` — guide conversion to ShadCN components (recommended for Next.js projects)
+
+**Key:** Stitch MCP transmits real HTML/CSS code (not screenshots), producing dramatically better results.
+
+**Rule:** Stitch design.md is NOT a separate deliverable. Extract tokens into `design-system.md`.
+
+---
+
 ## Design Brief Protocol (MANDATORY)
 
 > **This protocol runs BEFORE any wireframe, mockup, or visual decision.**
@@ -74,6 +99,11 @@ Read: .morph/context/design-system.md
 - Fill in the missing sections using the Design Thinking questions (Step 1 below)
 - This file is the persistent record — update it, don't just keep it in memory
 
+**If Stitch MCP is available:**
+- Check `list_projects` — if a project exists for this feature, its design.md can seed the design system
+- Stitch tokens map INTO `design-system.md` — never a separate file
+- Validate Stitch-exported colors against WCAG AA before adopting
+
 **When taking any design decision not covered by the file:**
 1. Add the token/decision to `design-system.md` in the correct section
 2. Register in the Changelog: `- YYYY-MM-DD [ui-ux-designer] Description`
@@ -208,6 +238,7 @@ Per flow: Trigger, steps, happy path, edge cases, ASCII flowchart diagram.
 - [ ] `design-system.md` read (project-level at `.morph/context/`) OR created with real tokens
 - [ ] Design Brief declared before any visual output (direction, palette, motion)
 - [ ] All color values in deliverables use CSS tokens (`--color-accent: #FF4D1C`) not generic names
+- [ ] If Stitch was used: tokens extracted and mapped to `design-system.md` (no separate design.md output)
 - [ ] `mockups.md`: Wireframes for ALL screens + states (loading, error, empty) + responsiveness
 - [ ] `components.md`: shadcn components mapped with props/events/states
 - [ ] `flows.md`: Happy paths + edge cases + ASCII diagrams

package/framework/agents.json

@@ -261,7 +261,7 @@
         "role": "UI/UX Squad Leader",
         "icon": "🎨",
         "triggers": "UI/UX design, wireframes, user flows, design system, shadcn/ui component selection",
-        "spawn_prompt": "You are the UI/UX Squad Leader. Create wireframes, design system, and user flows during the UI/UX phase.\n\nWorkflow:\n1. Read `.morph/context/design-system.md` FIRST — use only defined tokens\n2. Read spec.md for UI requirements\n3. Generate deliverables: design-system.md, mockups.md, components.md, flows.md\n4. Coordinate squad: nextjs-expert, css-specialist, seo-growth-hacker\n\nWork is UI/UX phase ONLY — no implementation code. Refer to the Domain Knowledge section below for design brief protocol, shadcn/ui reference, and accessibility rules."
+        "spawn_prompt": "You are the UI/UX Squad Leader. Create wireframes, design system, and user flows during the UI/UX phase.\n\nWorkflow:\n1. Read `.morph/context/design-system.md` FIRST — use only defined tokens\n2. Read spec.md for UI requirements\n3. If Stitch MCP available, offer AI-generated screen designs. Use companion skills (stitch-design, design-md) for workflow. Extract Stitch design.md tokens into design-system.md — no separate output.\n4. Generate deliverables: design-system.md, mockups.md, components.md, flows.md\n5. Coordinate squad: nextjs-expert, css-specialist, seo-growth-hacker\n\nWork is UI/UX phase ONLY — no implementation code. Refer to the Domain Knowledge section below for design brief protocol, shadcn/ui reference, and accessibility rules."
       }
     },
     "ef-modeler": {

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

@@ -69,6 +69,62 @@ async function dispatch(command, payload) {
       // Non-blocking
     }
 
+    // Evaluator dispatch: if sprint contract exists, instruct Claude to dispatch evaluator
+    try {
+      const taskId = taskDoneParsed.taskId;
+      if (taskId && !command.includes('--skip-eval')) {
+        const contractPath = join(process.cwd(), '.morph', 'features', featureName, '5-implement', 'contracts', `${taskId}-contract.yaml`);
+        if (existsSync(contractPath)) {
+          const contractContent = readFileSync(contractPath, 'utf-8');
+          let changedFiles = '';
+          try {
+            changedFiles = execSync('git diff --name-only HEAD~1 2>/dev/null | head -10', {
+              cwd: process.cwd(), encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe']
+            }).trim();
+          } catch { /* no git */ }
+
+          // Include score context from latest validation if available
+          let scoreContext = '';
+          try {
+            const evalFeature = getFeature(featureName);
+            const taskScores = evalFeature?.validationHistory?.[taskId]?.scores;
+            if (taskScores) {
+              scoreContext = `\n## Previous Validation Score: ${taskScores.score}/10\n` +
+                Object.entries(taskScores.breakdown || {})
+                  .map(([cat, d]) => `  ${cat}: ${Math.round(d.score * 10) / 10}/10 (weight ${Math.round(d.weight * 100)}%)`)
+                  .join('\n') + '\n\nFocus your evaluation on categories with the lowest scores.\n';
+            }
+          } catch { /* non-blocking */ }
+
+          contextParts.push(
+            `🔍 EVALUATOR DISPATCH\n` +
+            `════════════════════════════════════════\n` +
+            `Sprint contract exists for ${taskId}. Dispatch an evaluator sub-agent:\n\n` +
+            `Use the Agent tool with:\n` +
+            `  subagent_type: "general-purpose"\n` +
+            `  model: "sonnet"\n` +
+            `  prompt: (see below)\n\n` +
+            `--- EVALUATOR PROMPT ---\n` +
+            `You are an ADVERSARIAL evaluator. Your default assumption is that defects exist.\n` +
+            `Do NOT confirm correctness — actively search for problems.\n\n` +
+            `## Contract\n${contractContent}\n\n` +
+            `## Changed Files\n${changedFiles || '(unable to determine)'}\n` +
+            `${scoreContext}\n` +
+            `## Instructions\n` +
+            `1. Read each changed file\n` +
+            `2. Run the verification commands from the contract\n` +
+            `3. Evaluate each definitionOfDone item: PASS or FAIL with evidence\n` +
+            `4. For each category, score 0-10 and explain deficiencies found\n` +
+            `5. A clean report is suspicious — dig deeper before declaring PASS\n` +
+            `6. Return a structured result with overall PASS/FAIL and score breakdown\n` +
+            `--- END EVALUATOR PROMPT ---`
+          );
+        }
+      }
+    } catch {
+      // Non-blocking — evaluator is optional
+    }
+
     // Always inject validator dispatch — deferred if --skip-validation
     const validatorText = await buildValidatorDispatchContext(featureName, payload);
     if (validatorText) {

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

@@ -1,44 +1,78 @@
-#!/usr/bin/env node
-
-/**
- * PostToolUseFailure Hook: Log Tool Failures
- *
- * Event: PostToolUseFailure
- *
- * Runs when any tool fails. Appends a structured JSON entry to
- * .morph/logs/tool-failures.log for debugging and pattern analysis.
- *
- * Fail-open: exits 0 on any error.
- */
-
-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
-  if (!stateExists()) {
-    process.exit(0);
-  }
-
-  const input = await readStdin();
-
-  const logDir = join(process.cwd(), '.morph', 'logs');
-  mkdirSync(logDir, { recursive: true });
-
-  const entry = {
-    timestamp: new Date().toISOString(),
-    tool: input?.tool_name ?? 'unknown',
-    error: input?.error ?? null,
-    input: input?.tool_input ?? null,
-  };
-
-  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
-}
-
-process.exit(0);
+#!/usr/bin/env node
+
+/**
+ * PostToolUseFailure Hook: Log Tool Failures + Rollback Awareness
+ *
+ * Event: PostToolUseFailure
+ *
+ * Runs when any tool fails. Appends a structured JSON entry to
+ * .morph/logs/tool-failures.log for debugging and pattern analysis.
+ *
+ * If a critical failure occurs and there are unstaged changes,
+ * suggests git stash as a recovery option.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { appendFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { injectContext } from '../../shared/hook-response.js';
+import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
+
+const CRITICAL_ERROR_PATTERNS = ['ENOENT', 'EPERM', 'EACCES', 'segfault', 'out of memory', 'ENOMEM'];
+
+try {
+  // Only log in morph-spec projects
+  if (!stateExists()) {
+    process.exit(0);
+  }
+
+  const input = await readStdin();
+
+  const logDir = join(process.cwd(), '.morph', 'logs');
+  mkdirSync(logDir, { recursive: true });
+
+  const entry = {
+    timestamp: new Date().toISOString(),
+    tool: input?.tool_name ?? 'unknown',
+    error: input?.error ?? null,
+    input: input?.tool_input ?? null,
+  };
+
+  appendFileSync(join(logDir, 'tool-failures.log'), JSON.stringify(entry) + '\n');
+  logHookActivity('handle-tool-failure', 'PostToolUseFailure', `logged(${entry.tool})`);
+
+  // Rollback awareness: check for unstaged changes after critical failures
+  const errorStr = JSON.stringify(input?.error || '');
+  const isCritical = CRITICAL_ERROR_PATTERNS.some(p => errorStr.includes(p));
+
+  logEvent('tool_failure', { tool: entry.tool, critical: isCritical });
+
+  if (isCritical) {
+    try {
+      const gitStatus = execSync('git status --porcelain', {
+        cwd: process.cwd(),
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+
+      if (gitStatus) {
+        injectContext(
+          `⚠️ [morph-spec] Critical tool failure (${entry.tool}). ` +
+          `Unstaged changes detected:\n${gitStatus.split('\n').slice(0, 5).join('\n')}\n\n` +
+          `Consider: git stash to save current state before retrying.`
+        );
+      }
+    } catch {
+      // git not available or not a git repo — ignore
+    }
+  }
+} catch {
+  // Fail-open: logging is non-critical
+}
+
+process.exit(0);

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

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: Loop Detection
+ *
+ * Event: PostToolUse | Matcher: none (all tools)
+ *
+ * Detects when an agent is stuck in a repetitive loop by tracking
+ * the last 15 actions. If the last 8 actions have <= 2 unique
+ * signatures, injects a warning with escape instructions.
+ *
+ * Cooldown: 5 minutes between warnings to prevent meta-loop.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { getCommandSignature } from '../../shared/payload-utils.js';
+import { logEvent } from '../../shared/activity-logger.js';
+
+const MAX_BUFFER = 15;
+const LOOP_WINDOW = 8;
+const MAX_UNIQUE_SIGS = 2;
+const COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const cwd = process.cwd();
+  const memoryDir = join(cwd, '.morph', 'memory');
+  const bufferPath = join(memoryDir, 'action-buffer.json');
+  const cooldownPath = join(memoryDir, 'loop-cooldown.json');
+
+  mkdirSync(memoryDir, { recursive: true });
+
+  // Read existing buffer
+  let buffer = [];
+  try {
+    if (existsSync(bufferPath)) {
+      buffer = JSON.parse(readFileSync(bufferPath, 'utf-8'));
+      if (!Array.isArray(buffer)) buffer = [];
+    }
+  } catch {
+    buffer = [];
+  }
+
+  // Append current action
+  const sig = getCommandSignature(payload);
+  buffer.push({ sig, ts: new Date().toISOString() });
+
+  // Trim to max size (FIFO)
+  if (buffer.length > MAX_BUFFER) {
+    buffer = buffer.slice(-MAX_BUFFER);
+  }
+
+  // Save updated buffer
+  writeFileSync(bufferPath, JSON.stringify(buffer), 'utf-8');
+
+  // Check for loop (need at least LOOP_WINDOW actions)
+  if (buffer.length < LOOP_WINDOW) pass();
+
+  const recent = buffer.slice(-LOOP_WINDOW);
+  const uniqueSigs = new Set(recent.map(a => a.sig));
+
+  if (uniqueSigs.size > MAX_UNIQUE_SIGS) pass();
+
+  // Check cooldown
+  try {
+    if (existsSync(cooldownPath)) {
+      const cooldown = JSON.parse(readFileSync(cooldownPath, 'utf-8'));
+      const elapsed = Date.now() - new Date(cooldown.lastDetected).getTime();
+      if (elapsed < COOLDOWN_MS) pass();
+    }
+  } catch {
+    // Ignore corrupt cooldown — proceed with detection
+  }
+
+  // Loop detected — set cooldown and warn
+  writeFileSync(cooldownPath, JSON.stringify({ lastDetected: new Date().toISOString() }), 'utf-8');
+
+  logEvent('loop_detected', { signatures: uniqueSigs.size }, process.cwd());
+
+  const sigList = [...uniqueSigs].join(', ');
+  injectContext(
+    `⚠️ [morph-spec] LOOP DETECTED — the last ${LOOP_WINDOW} actions repeat only ${uniqueSigs.size} pattern(s): ${sigList}\n\n` +
+    `This usually means you're stuck. Stop and try a different approach:\n` +
+    `  1. Re-read the error message carefully — what is it actually saying?\n` +
+    `  2. Try a completely different fix strategy\n` +
+    `  3. If the test keeps failing, check if the test itself is wrong\n` +
+    `  4. If blocked, ask the user for guidance\n\n` +
+    `Do NOT continue the same pattern.`
+  );
+} catch {
+  // Fail-open
+  process.exit(0);
+}

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

@@ -79,6 +79,7 @@ try {
 function buildRemediationContext(featureName, taskId, taskHistory) {
   const attempt = taskHistory.attempt || 1;
   const validators = taskHistory.validators || {};
+  const scores = taskHistory.scores || null;
 
   // Collect all issues across all validators
   const allIssues = [];
@@ -95,28 +96,60 @@ function buildRemediationContext(featureName, taskId, taskHistory) {
   const lines = [];
 
   if (taskHistory.status === 'blocked') {
-    // Max attempts reached — escalation message
-    lines.push(`⛔ ESCALATION REQUIRED — Task ${taskId} in feature '${featureName}'`);
-    lines.push(`   Validation failed ${attempt} times (max attempts reached).`);
+    // Max attempts reached OR score-based escalation
+    const scoreInfo = scores ? ` (score: ${scores.score}/10)` : '';
+    lines.push(`⛔ ESCALATION REQUIRED — Task ${taskId} in feature '${featureName}'${scoreInfo}`);
+    if (scores?.action === 'escalate') {
+      lines.push(`   Score below retry threshold — immediate escalation.`);
+    } else {
+      lines.push(`   Validation failed ${attempt} times (max attempts reached).`);
+    }
     lines.push(`   Human review required before proceeding.`);
+    if (scores) {
+      lines.push(``);
+      lines.push(`   Score breakdown:`);
+      appendScoreBreakdown(lines, scores);
+    }
     lines.push(`   Last failures:`);
     for (const issue of allIssues.slice(0, 5)) {
       lines.push(`     • [${issue.validator}] ${issue.message} ${issue.file ? `(${issue.file}${issue.line ? ':' + issue.line : ''})` : ''}`);
     }
   } else {
     // Active remediation — attempt N of 3
-    lines.push(`🔄 REMEDIATION REQUIRED — Task ${taskId} (attempt ${attempt}/3)`);
+    const scoreInfo = scores ? ` | score: ${scores.score}/10` : '';
+    lines.push(`🔄 REMEDIATION REQUIRED — Task ${taskId} (attempt ${attempt}/3${scoreInfo})`);
     lines.push(`   Validation failed. Fix the following issues and re-run:`);
     lines.push(`   morph-spec task done ${featureName} ${taskId}`);
     lines.push(``);
 
-    for (const issue of allIssues) {
-      const refKey = getRefKey(issue.rule || issue.validator);
-      const ref = refKey ? ` — Ref: ${STANDARD_REFS[refKey] || refKey}` : '';
-      const location = issue.file
-        ? ` (${issue.file}${issue.line ? ':' + issue.line : ''})`
-        : '';
-      lines.push(`  • [${issue.validator}] ${issue.message}${location}${ref}`);
+    // Score-based prioritized feedback (when available)
+    if (scores?.breakdown) {
+      lines.push(`   Priority fixes (by impact):`);
+      const sorted = Object.entries(scores.breakdown)
+        .filter(([, cat]) => (cat.issues?.length || 0) > 0)
+        .sort((a, b) => ((10 - b[1].score) * b[1].weight) - ((10 - a[1].score) * a[1].weight));
+
+      for (const [category, cat] of sorted) {
+        const topIssue = cat.issues[0];
+        const location = topIssue?.file ? ` (${topIssue.file}${topIssue.line ? ':' + topIssue.line : ''})` : '';
+        const msg = topIssue?.message || 'Issues detected';
+        lines.push(`   ${Math.round(cat.score * 10) / 10}/10 [${category}] ${msg}${location}`);
+        if (cat.issues.length > 1) {
+          lines.push(`         ... and ${cat.issues.length - 1} more issue(s)`);
+        }
+      }
+      lines.push(``);
+      appendScoreBreakdown(lines, scores);
+    } else {
+      // Fallback: original issue-by-issue format
+      for (const issue of allIssues) {
+        const refKey = getRefKey(issue.rule || issue.validator);
+        const ref = refKey ? ` — Ref: ${STANDARD_REFS[refKey] || refKey}` : '';
+        const location = issue.file
+          ? ` (${issue.file}${issue.line ? ':' + issue.line : ''})`
+          : '';
+        lines.push(`  • [${issue.validator}] ${issue.message}${location}${ref}`);
+      }
     }
 
     if (attempt >= 2) {
@@ -128,6 +161,22 @@ function buildRemediationContext(featureName, taskId, taskHistory) {
   injectContext(lines.join('\n'));
 }
 
+/**
+ * Append score breakdown lines to output.
+ * @param {string[]} lines - Output array
+ * @param {Object} scores - { score, action, breakdown }
+ */
+function appendScoreBreakdown(lines, scores) {
+  if (!scores?.breakdown) return;
+  const approveThreshold = scores.approveThreshold ?? 8.0;
+  for (const [category, data] of Object.entries(scores.breakdown)) {
+    if (category === '_unmapped') continue; // skip internal unmapped category
+    const pct = Math.round(data.weight * 100);
+    const indicator = data.score >= approveThreshold ? '\u2713' : data.score >= 6 ? '\u2193' : '\u2193\u2193';
+    lines.push(`     ${category}: ${Math.round(data.score * 10) / 10}/10 (weight ${pct}%) ${indicator}`);
+  }
+}
+
 /**
  * Map a rule/validator name to a STANDARD_REFS key.
  * @param {string} ruleOrValidator

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

@@ -12,9 +12,10 @@
  */
 
 import { loadState, getActiveFeature, getPendingGates, getMissingOutputs, derivePhaseForFeature, getTaskStats } from '../../shared/state-reader.js';
+import { loadSessionSnapshot, formatPreviousSession } from '../../shared/session-snapshot.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 { resetActivity, logHookActivity, archiveSession, logEvent } from '../../shared/activity-logger.js';
 import { readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, statSync } from 'fs';
 import { join } from 'path';
 import { resetStaleTasks } from '../../shared/stale-task-reset.js';
@@ -74,10 +75,14 @@ try {
 
   const active = getActiveFeature();
 
-  // Reset activity log for new session
+  // Archive previous session log before resetting
   const activeFeatureName = active?.name || '';
   const activePhase = active ? derivePhaseForFeature(active.name) : '';
+  archiveSession();
+
+  // Reset activity log for new session
   resetActivity(new Date().toISOString(), activeFeatureName, activePhase);
+  logEvent('session_start', { feature: activeFeatureName, phase: activePhase });
   logHookActivity('inject-morph-context', 'SessionStart', 'ok');
 
   // ── Stale task cleanup ──────────────────────────────────────────────────────
@@ -201,6 +206,20 @@ try {
       // Fail-open — worktree context must never block the session
     }
     // ────────────────────────────────────────────────────────────────────────────
+
+    // ── Previous session context ──────────────────────────────────────────────
+    // Inject summary from previous session for "getting up to speed"
+    try {
+      const snapshot = loadSessionSnapshot(process.cwd());
+      const previousSessionText = formatPreviousSession(snapshot);
+      if (previousSessionText) {
+        lines.push('');
+        lines.push(previousSessionText);
+      }
+    } catch {
+      // Fail-open — previous session context must never block
+    }
+    // ────────────────────────────────────────────────────────────────────────
   } else {
     // Show summary of all features
     const featureNames = Object.keys(state.features);