@polymorphism-tech/morph-spec 4.17.0 → 4.19.0

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/integrations/neon-auth.md

@@ -0,0 +1,151 @@
+---
+name: neon-auth
+description: Neon Auth (Better Auth) specialist for authentication flows, session management, Next.js App Router integration, .NET JWT validation, and RLS policy integration. Use when integrating Neon Auth, implementing social login flows, managing user sessions, or protecting routes with Neon Auth middleware.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+stacks:
+  - neon
+color: teal
+effort: medium
+---
+
+# Neon Auth (Better Auth)
+
+Authentication with Neon Auth for Next.js and .NET. SDK: `@neondatabase/auth` (Next.js) / JWT Bearer validation (.NET).
+
+> **Ref:** `framework/standards/backend/integrations/neon-auth/neon-auth.md`
+
+## Setup (Next.js)
+
+```typescript
+// lib/auth/client.ts
+'use client';
+import { createAuthClient } from '@neondatabase/auth/next';
+export const authClient = createAuthClient();
+
+// lib/auth/server.ts
+import { createNeonAuth } from '@neondatabase/auth/next/server';
+export const auth = createNeonAuth({
+  baseUrl: process.env.NEON_AUTH_BASE_URL!,
+  cookies: { secret: process.env.NEON_AUTH_COOKIE_SECRET! },
+});
+
+// app/api/auth/[...path]/route.ts
+import { auth } from '@/lib/auth/server';
+export const { GET, POST } = auth.handler();
+```
+
+## Setup (.NET)
+
+```csharp
+// Program.cs
+builder.Services.AddAuthentication("NeonAuth")
+    .AddJwtBearer("NeonAuth", options =>
+    {
+        options.Authority = builder.Configuration["NeonAuth:BaseUrl"];
+        options.TokenValidationParameters = new()
+        {
+            ValidateIssuer = true,
+            ValidateAudience = false,
+            ValidateLifetime = true,
+            ValidateIssuerSigningKey = true,
+            NameClaimType = "sub"
+        };
+    });
+builder.Services.AddAuthorization();
+app.UseAuthentication();
+app.UseAuthorization();
+```
+
+## Protected Endpoints
+
+```csharp
+// Minimal API
+app.MapGet("/api/profile", (ClaimsPrincipal user) =>
+{
+    var userId = user.FindFirstValue("sub");
+    if (userId is null) return Results.Unauthorized();
+    return Results.Ok(new { UserId = userId });
+}).RequireAuthorization();
+
+// Controller: same pattern with [Authorize] + User.FindFirstValue("sub")
+```
+
+## Next.js Integration
+
+```tsx
+// middleware.ts
+import { auth } from '@/lib/auth/server';
+export default auth.middleware({ loginUrl: '/auth/sign-in' });
+export const config = { matcher: ['/((?!.*\\..*|_next|auth).*)', '/'] };
+
+// Protected page (server)
+import { auth } from '@/lib/auth/server';
+export const dynamic = 'force-dynamic';
+export default async function DashboardPage() {
+  const { data: session } = await auth.getSession();
+  if (!session?.user) redirect('/auth/sign-in');
+  return <Dashboard user={session.user} />;
+}
+
+// Client component
+'use client';
+import { useSession } from '@/lib/auth/client';
+const { data } = useSession();
+const user = data?.user;
+```
+
+## Auth Pages
+
+```tsx
+// Sign in / Sign up — single component
+import { AuthView } from '@neondatabase/auth/react';
+export default function SignInPage() {
+  return <AuthView pathname="sign-in" />;
+}
+```
+
+## OAuth
+
+```typescript
+await authClient.signIn.social({
+  provider: 'google',
+  callbackURL: '/auth/callback',
+});
+```
+
+## RLS Integration
+
+Neon Auth JWTs are validated by the Data API. Use `auth.user_id()` in RLS policies:
+
+```sql
+CREATE POLICY "Users own rows"
+  ON public.documents FOR ALL TO authenticated
+  USING (user_id = auth.user_id());
+```
+
+## Database Schema
+
+Auth data lives in `neon_auth` schema (managed automatically):
+- `neon_auth.user` — profiles
+- `neon_auth.session` — sessions
+- `neon_auth.account` — credentials
+
+Query directly — no webhook sync needed:
+```sql
+SELECT id, email, name FROM neon_auth.user WHERE id = auth.user_id();
+```
+
+## Checklist
+
+- [ ] `NEON_AUTH_BASE_URL` in environment variables
+- [ ] `NEON_AUTH_COOKIE_SECRET` (32+ chars) in environment variables
+- [ ] Auth API route at `app/api/auth/[...path]/route.ts`
+- [ ] `NeonAuthUIProvider` wrapping app in root layout
+- [ ] Middleware protecting private routes
+- [ ] `.NET` JWT Bearer configured with Neon Auth authority
+- [ ] RLS policies using `auth.user_id()`
+- [ ] `force-dynamic` on pages using `auth.getSession()`
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/agents.json

@@ -162,7 +162,7 @@
         "role": "Backend Squad Leader",
         "icon": "⚙️",
         "triggers": ".NET/C# backend, VSA architecture, EF Core, API design, backend squad coordination",
-        "spawn_prompt": "You are the Backend Squad Leader. Coordinate backend specialists and own VSA architecture, API design, and .NET/C# standards.\n\nWorkflow:\n1. Read `.morph/state.json` and spec.md for backend requirements\n2. Produce VSA Blueprint: entity fields, operations (slices), routes, error types, validation rules\n3. Delegate to squad: ef-modeler, hangfire-orchestrator, ms-agent-expert, neon-expert, vector-search-expert, asaas-financial, clerk-auth, resend-email\n\nRefer to the Domain Knowledge section below for IHandler, Result<T>, Scrutor, IApiEndpoint patterns and code templates."
+        "spawn_prompt": "You are the Backend Squad Leader. Coordinate backend specialists and own VSA architecture, API design, and .NET/C# standards.\n\nWorkflow:\n1. Read `.morph/state.json` and spec.md for backend requirements\n2. Produce VSA Blueprint: entity fields, operations (slices), routes, error types, validation rules\n3. Delegate to squad: ef-modeler, hangfire-orchestrator, ms-agent-expert, neon-expert, vector-search-expert, asaas-financial, neon-auth, resend-email\n\nRefer to the Domain Knowledge section below for IHandler, Result<T>, Scrutor, IApiEndpoint patterns and code templates."
       }
     },
     "infra-architect": {
@@ -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": {
@@ -441,7 +441,7 @@
         "role": "Neon PostgreSQL & AI Data Specialist",
         "icon": "\uD83D\uDC18",
         "triggers": "database setup, pgvector, pgrag, vector search, embeddings, Neon branching, RAG pipeline, Semantic Kernel vector store, neonctl",
-        "spawn_prompt": "You are the Neon PostgreSQL & AI Data Specialist. Implement database schemas, RLS policies, pgvector embeddings, pgrag RAG pipelines, and manage Neon branches.\n\nWorkflow:\n1. Read spec.md for database, vector search, and RAG requirements\n2. Review architecture from dotnet-senior for entity and schema design\n3. ALWAYS use the pooled connection (-pooler endpoint) for application code — direct connections only for EF Core migrations\n4. Implement RLS policies using auth.user_id() (Neon Authorize) with Clerk JWT\n5. Set up pgvector with HNSW indexes and tune maintenance_work_mem before index creation\n6. For RAG pipelines, use pgrag extensions (rag, rag_bge_small_en_v15, rag_jina_reranker_v1_tiny_en) for chunking, embedding, search, and reranking entirely in SQL\n7. Create database branches for PR previews (--schema-only) and run schema-diff before merging\n8. Configure connection retry logic for scale-to-zero cold starts\n\nCRITICAL: Two connection strings — pooled for application, direct for migrations. Never use direct connections in application code.\n\nRefer to the Domain Knowledge section below for connection pooling, RLS patterns, pgvector setup, pgrag pipeline, branching strategy, and scale-to-zero configuration."
+        "spawn_prompt": "You are the Neon PostgreSQL & AI Data Specialist. Implement database schemas, RLS policies, pgvector embeddings, pgrag RAG pipelines, and manage Neon branches.\n\nWorkflow:\n1. Read spec.md for database, vector search, and RAG requirements\n2. Review architecture from dotnet-senior for entity and schema design\n3. ALWAYS use the pooled connection (-pooler endpoint) for application code — direct connections only for EF Core migrations\n4. Implement RLS policies using auth.user_id() via pg_session_jwt with Neon Auth JWT\n5. Set up pgvector with HNSW indexes and tune maintenance_work_mem before index creation\n6. For RAG pipelines, use pgrag extensions (rag, rag_bge_small_en_v15, rag_jina_reranker_v1_tiny_en) for chunking, embedding, search, and reranking entirely in SQL\n7. Create database branches for PR previews (--schema-only) and run schema-diff before merging\n8. Configure connection retry logic for scale-to-zero cold starts\n\nCRITICAL: Two connection strings — pooled for application, direct for migrations. Never use direct connections in application code.\n\nRefer to the Domain Knowledge section below for connection pooling, RLS patterns, pgvector setup, pgrag pipeline, branching strategy, and scale-to-zero configuration."
       }
     },
     "vector-search-expert": {
@@ -521,11 +521,11 @@
         "spawn_prompt": "You are the Payment Integration Specialist (Asaas/Brazil). Implement PIX, Boleto, Credit Card, and subscription billing.\n\nNever hardcode API keys. Follow contract-compliance patterns.\n\nRefer to the Domain Knowledge section below for Asaas SDK patterns, webhook handling, and payment flow examples."
       }
     },
-    "clerk-auth": {
+    "neon-auth": {
       "color": "teal",
       "tier": 3,
-      "title": "Auth SaaS Integration Specialist",
-      "stacks": ["clerk"],
+      "title": "Neon Auth Integration Specialist",
+      "stacks": ["neon"],
       "group": "backend",
       "active_phases": [
         "design",
@@ -536,21 +536,29 @@
         "integration-auth"
       ],
       "keywords": [
-        "clerk",
-        "clerk auth",
+        "neon auth",
+        "better auth",
+        "authentication",
         "add auth",
         "implement auth",
         "login",
         "signup",
-        "oauth"
+        "oauth",
+        "session management",
+        "neon_auth schema"
       ],
       "validators": [],
-      "standards": [],
+      "standards": [
+        {
+          "id": "neon-auth",
+          "scope": "neon"
+        }
+      ],
       "teammate": {
-        "role": "Auth SaaS Integration Specialist",
+        "role": "Neon Auth Integration Specialist",
         "icon": "🔐",
-        "triggers": "Clerk authentication, login/signup flows, OAuth, session management",
-        "spawn_prompt": "You are the Auth SaaS Integration Specialist (Clerk). Implement authentication flows and session management with Next.js App Router.\n\nRefer to the Domain Knowledge section below for Clerk SDK patterns, middleware configuration, and webhook handling."
+        "triggers": "Neon Auth, authentication, login/signup flows, OAuth, session management, Better Auth",
+        "spawn_prompt": "You are the Neon Auth Integration Specialist. Implement authentication flows using Neon Auth (Better Auth) with @neondatabase/auth SDK for Next.js and JWT Bearer validation for .NET.\n\nRefer to the Domain Knowledge section below for SDK setup, auth pages, middleware protection, RLS integration, and .NET JWT configuration."
       }
     },
     "resend-email": {
@@ -1101,7 +1109,7 @@
         "neon-expert",
         "vector-search-expert",
         "asaas-financial",
-        "clerk-auth",
+        "neon-auth",
         "resend-email"
       ],
       "domains": [

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

@@ -69,6 +69,45 @@ 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 */ }
+
+          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 independent evaluator. Validate this implementation against the sprint contract.\n\n` +
+            `## Contract\n${contractContent}\n\n` +
+            `## Changed Files\n${changedFiles || '(unable to determine)'}\n\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. Return a structured result with overall PASS/FAIL\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/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);