@polymorphism-tech/morph-spec 4.18.0 → 4.20.0

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

@@ -20,11 +20,13 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
+import { runBuildCheck } from '../../shared/build-check.js';
+import { saveSessionSnapshot } from '../../shared/session-snapshot.js';
 import {
   stateExists, getActiveFeature, getMostRecentFeature, getMissingOutputs, derivePhaseForFeature,
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
-import { logHookActivity } from '../../shared/activity-logger.js';
+import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
 
 // Phases where compaction is strongly recommended before starting
 const COMPACT_TRIGGER_PHASES = new Set(['implement']);
@@ -82,6 +84,50 @@ try {
     );
   }
 
+  // ── Build/typecheck verification ──────────────────────────────────────────
+  // Stack-aware build check — advisory warning if build fails.
+  // Success is silent (no output on pass).
+  try {
+    const configPath = join(cwd, '.morph', 'config', 'config.json');
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      const stack = config?.project?.stack;
+      if (stack && currentPhase === 'implement') {
+        const buildResult = runBuildCheck(cwd, stack);
+        if (buildResult.status === 'fail') {
+          warnings.push('⚠ Build/typecheck failed:');
+          warnings.push(buildResult.output);
+          warnings.push('Fix build errors before ending session.');
+        }
+        // pass and skip → silent (success is silent)
+      }
+    }
+  } catch {
+    // Fail-open — build check must never block Stop
+  }
+  // ────────────────────────────────────────────────────────────────────────
+
+  // ── Session snapshot ──────────────────────────────────────────────────────
+  // Save session state for next session's "getting up to speed" routine.
+  try {
+    if (active) {
+      const { name, feature } = active;
+      const taskList = feature.taskList || [];
+      saveSessionSnapshot({
+        feature: name,
+        phase: currentPhase,
+        tasksCompleted: taskList.filter(t => t.status === 'completed').map(t => t.id),
+        tasksRemaining: taskList.filter(t => t.status === 'pending').map(t => t.id),
+        tasksInProgress: taskList.filter(t => t.status === 'in_progress').map(t => t.id),
+        buildStatus: 'skip',
+        lastEditedFiles: [],
+      }, cwd);
+    }
+  } catch {
+    // Fail-open — snapshot save must never block Stop
+  }
+  // ────────────────────────────────────────────────────────────────────────
+
   // ── Incomplete work checks ────────────────────────────────────────────────
 
   // Incomplete tasks during implement phase
@@ -152,6 +198,7 @@ try {
   ].join('\n');
 
   logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);
+  logEvent('session_end', { feature: name, phase: currentPhase, warnings: warnings.length });
   injectContext(message);
 } catch {
   process.exit(0);

package/framework/hooks/shared/activity-logger.js

@@ -11,7 +11,7 @@
  * - Windows-safe paths via path.join
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
 import { join } from 'path';
 
 const LOGS_DIR = '.morph/logs';
@@ -103,3 +103,58 @@ export function resetActivity(sessionId, feature, phase, projectPath) {
     // Fail-silent
   }
 }
+
+/**
+ * Log a structured event to the session activity log.
+ *
+ * @param {string} type   - Event type (e.g., 'task_start', 'loop_detected')
+ * @param {Object} data   - Event data payload
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ */
+export function logEvent(type, data, projectPath) {
+  try {
+    const activityPath = getActivityPath(projectPath);
+    ensureLogsDir(projectPath);
+
+    const now = new Date();
+    const ts = now.toTimeString().slice(0, 8); // HH:MM:SS
+
+    const activity = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], events: [] };
+    activity.events = activity.events || [];
+    activity.events.push({ type, data, ts });
+
+    writeFileSync(activityPath, JSON.stringify(activity, null, 2), 'utf-8');
+  } catch {
+    // Fail-silent
+  }
+}
+
+/**
+ * Archive current activity.json to sessions/ directory for historical logging.
+ * Called at the start of a new session.
+ *
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ */
+export function archiveSession(projectPath) {
+  try {
+    const activityPath = getActivityPath(projectPath);
+    if (!existsSync(activityPath)) return;
+
+    const data = readRaw(activityPath);
+    if (!data) return;
+
+    // Only archive if there are meaningful events
+    if ((!data.hooks || data.hooks.length === 0) && (!data.events || data.events.length === 0)) return;
+
+    const sessionsDir = join(projectPath || process.cwd(), LOGS_DIR, 'sessions');
+    mkdirSync(sessionsDir, { recursive: true });
+
+    const sessionId = (data.sessionId || new Date().toISOString()).replace(/[:.]/g, '-');
+    const archivePath = join(sessionsDir, `${sessionId}.json`);
+    writeFileSync(archivePath, JSON.stringify(data, null, 2), 'utf-8');
+
+    unlinkSync(activityPath);
+  } catch {
+    // Fail-silent
+  }
+}

package/framework/hooks/shared/build-check.js

@@ -0,0 +1,79 @@
+/**
+ * Build/Typecheck verification utility.
+ *
+ * Stack-aware: determines the correct build command based on project stack.
+ * Used by the Stop hook to verify code health before session ends.
+ *
+ * Pure functions — no I/O except the actual build execution.
+ */
+
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Determine the build command for a given stack.
+ *
+ * @param {string} stack - Project stack (e.g., 'dotnet-nextjs', 'nextjs')
+ * @param {boolean} [hasTsConfig] - Whether tsconfig.json exists (for TS projects)
+ * @returns {string|null} Build command or null if no check available
+ */
+export function getBuildCommand(stack, hasTsConfig = false) {
+  if (!stack) return null;
+  const s = stack.toLowerCase();
+
+  if (s.includes('dotnet')) {
+    return 'dotnet build --no-restore --nologo -v q 2>&1 | tail -20';
+  }
+
+  if ((s.includes('nextjs') || s.includes('node') || s.includes('react')) && hasTsConfig) {
+    return 'npx tsc --noEmit 2>&1 | tail -20';
+  }
+
+  return null;
+}
+
+/**
+ * Parse build command result into a structured object.
+ *
+ * @param {number} exitCode - Process exit code (0 = success)
+ * @param {string} output - stdout+stderr from build
+ * @returns {{ status: 'pass'|'fail', output: string }}
+ */
+export function parseBuildResult(exitCode, output) {
+  const trimmed = (output || '').trim();
+  if (exitCode === 0) {
+    return { status: 'pass', output: '' };
+  }
+  // Truncate to last 20 lines
+  const lines = trimmed.split('\n');
+  const truncated = lines.slice(-20).join('\n');
+  return { status: 'fail', output: truncated };
+}
+
+/**
+ * Run build check for a project.
+ *
+ * @param {string} cwd - Project root directory
+ * @param {string} stack - Project stack string
+ * @param {number} [timeout=30000] - Timeout in ms
+ * @returns {{ status: 'pass'|'fail'|'skip', output: string }}
+ */
+export function runBuildCheck(cwd, stack, timeout = 30000) {
+  const hasTsConfig = existsSync(join(cwd, 'tsconfig.json'));
+  const cmd = getBuildCommand(stack, hasTsConfig);
+  if (!cmd) return { status: 'skip', output: '' };
+
+  try {
+    const output = execSync(cmd, {
+      cwd,
+      encoding: 'utf-8',
+      timeout,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    return parseBuildResult(0, output);
+  } catch (err) {
+    const output = (err.stdout || '') + (err.stderr || '');
+    return parseBuildResult(err.status || 1, output);
+  }
+}

package/framework/hooks/shared/payload-utils.js

@@ -37,3 +37,42 @@ export function getContentToValidate(payload) {
 export function isWriteOperation(payload) {
   return typeof payload?.tool_input?.content === 'string';
 }
+
+/**
+ * Get the tool name from a hook payload.
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {string} Tool name or 'unknown'
+ */
+export function getToolName(payload) {
+  return payload?.tool_name || 'unknown';
+}
+
+/**
+ * Build a normalized signature for loop detection.
+ * - Edit/Write: "Edit:normalized/file/path"
+ * - Bash: "Bash:first two words" (e.g., "Bash:npm test")
+ * - Other: just the tool name
+ *
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {string} Signature string
+ */
+export function getCommandSignature(payload) {
+  const tool = getToolName(payload);
+  if (tool === 'unknown') return 'unknown';
+
+  const input = payload?.tool_input;
+  if (!input) return tool;
+
+  if (tool === 'Edit' || tool === 'Write') {
+    const path = (input.file_path || input.path || '').replace(/\\/g, '/');
+    return path ? `${tool}:${path}` : tool;
+  }
+
+  if (tool === 'Bash') {
+    const cmd = (input.command || '').trim();
+    const words = cmd.split(/\s+/).slice(0, 2).join(' ');
+    return words ? `Bash:${words}` : 'Bash';
+  }
+
+  return tool;
+}

package/framework/hooks/shared/session-snapshot.js

@@ -0,0 +1,105 @@
+/**
+ * Session Snapshot — cross-session persistence utility
+ *
+ * Saves and loads session state for "getting up to speed" on next session.
+ * Single file (overwrites) — history preserved via git.
+ *
+ * Fail-silent: never throws.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, unlinkSync } from 'fs';
+import { join } from 'path';
+
+const SNAPSHOT_PATH = '.morph/memory/session-snapshot.json';
+
+/**
+ * Save session snapshot atomically.
+ * @param {Object} data - Snapshot data
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ */
+export function saveSessionSnapshot(data, projectPath) {
+  try {
+    const root = projectPath || process.cwd();
+    const dir = join(root, '.morph', 'memory');
+    mkdirSync(dir, { recursive: true });
+
+    const snapshot = { ...data, savedAt: new Date().toISOString() };
+    const filePath = join(root, SNAPSHOT_PATH);
+    const tmpPath = `${filePath}.tmp.${process.pid}`;
+
+    writeFileSync(tmpPath, JSON.stringify(snapshot, null, 2), 'utf-8');
+    try {
+      renameSync(tmpPath, filePath);
+    } catch {
+      writeFileSync(filePath, JSON.stringify(snapshot, null, 2), 'utf-8');
+      try { unlinkSync(tmpPath); } catch { /* ignore */ }
+    }
+  } catch {
+    // Fail-silent
+  }
+}
+
+/**
+ * Load session snapshot.
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ * @returns {Object|null} Parsed snapshot or null
+ */
+export function loadSessionSnapshot(projectPath) {
+  try {
+    const filePath = join(projectPath || process.cwd(), SNAPSHOT_PATH);
+    if (!existsSync(filePath)) return null;
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format snapshot as concise context string for SessionStart injection.
+ * Budget: max ~150 tokens (~600 chars).
+ *
+ * @param {Object|null} snapshot
+ * @returns {string|null} Formatted context or null
+ */
+export function formatPreviousSession(snapshot) {
+  if (!snapshot) return null;
+
+  const lines = ['=== PREVIOUS SESSION ==='];
+
+  // Header line
+  const date = snapshot.savedAt ? new Date(snapshot.savedAt).toISOString().slice(0, 16).replace('T', ' ') : '?';
+  const phase = snapshot.phase || '?';
+  const build = snapshot.buildStatus || 'unknown';
+  lines.push(`Last: ${date} | Phase: ${phase} | Build: ${build}`);
+
+  // Tasks (truncated)
+  const done = snapshot.tasksCompleted || [];
+  if (done.length > 0) {
+    const shown = done.slice(-5).join(', ');
+    const prefix = done.length > 5 ? `...${done.length} total, last: ` : '';
+    lines.push(`Done: ${prefix}${shown}`);
+  }
+
+  const wip = snapshot.tasksInProgress || [];
+  if (wip.length > 0) {
+    lines.push(`WIP: ${wip.join(', ')}`);
+  }
+
+  const remaining = snapshot.tasksRemaining || [];
+  if (remaining.length > 0) {
+    const shown = remaining.slice(0, 5).join(', ');
+    const suffix = remaining.length > 5 ? ` +${remaining.length - 5} more` : '';
+    lines.push(`Remaining: ${shown}${suffix}`);
+  }
+
+  // Files (truncated)
+  const files = snapshot.lastEditedFiles || [];
+  if (files.length > 0) {
+    const shown = files.slice(0, 3).join(', ');
+    const suffix = files.length > 3 ? ` +${files.length - 3} more` : '';
+    lines.push(`Files: ${shown}${suffix}`);
+  }
+
+  lines.push('===');
+  return lines.join('\n');
+}

package/framework/phases.json

@@ -35,7 +35,7 @@
       ],
       "requiredOutputs": ["uiDesignSystem"],
       "optionalOutputs": ["uiMockups", "uiComponents", "uiFlows"],
-      "recommendedMCPs": ["playwright", "context7"],
+      "recommendedMCPs": ["playwright", "context7", "stitch"],
       "pausePoints": [
         { "id": "uiux", "label": "Approve UI/UX Design" }
       ],

package/framework/rubrics/backend.json

@@ -0,0 +1,36 @@
+{
+  "id": "backend",
+  "version": "1.0.0",
+  "description": "Backend-focused rubric. Higher weight on architecture, security, and package health.",
+  "categories": {
+    "functionality": {
+      "weight": 0.30,
+      "validators": ["contract-compliance"],
+      "description": "Core feature correctness and contract compliance"
+    },
+    "code_quality": {
+      "weight": 0.30,
+      "validators": ["architecture"],
+      "description": "Architecture patterns, dependency direction, and code structure"
+    },
+    "design_ui": {
+      "weight": 0.05,
+      "validators": ["design-system", "css", "contrast", "nextjs-component"],
+      "description": "Design system compliance (minimal weight for backend projects)"
+    },
+    "security": {
+      "weight": 0.15,
+      "validators": [],
+      "description": "Security posture (agent-evaluated, no automated validator)"
+    },
+    "packages": {
+      "weight": 0.20,
+      "validators": ["packages"],
+      "description": "Dependency health, version compatibility, and deprecated packages"
+    }
+  },
+  "thresholds": {
+    "approve": 8.0,
+    "retry": 6.0
+  }
+}

package/framework/rubrics/default.json

@@ -0,0 +1,36 @@
+{
+  "id": "default",
+  "version": "1.0.0",
+  "description": "Default rubric for general-purpose projects. Balanced weights across all categories.",
+  "categories": {
+    "functionality": {
+      "weight": 0.30,
+      "validators": ["contract-compliance"],
+      "description": "Core feature correctness and contract compliance"
+    },
+    "code_quality": {
+      "weight": 0.25,
+      "validators": ["architecture"],
+      "description": "Architecture patterns and code structure"
+    },
+    "design_ui": {
+      "weight": 0.15,
+      "validators": ["design-system", "css", "contrast", "nextjs-component"],
+      "description": "Design system compliance, CSS quality, and UI correctness"
+    },
+    "security": {
+      "weight": 0.15,
+      "validators": [],
+      "description": "Security posture (agent-evaluated, no automated validator)"
+    },
+    "packages": {
+      "weight": 0.15,
+      "validators": ["packages"],
+      "description": "Dependency health and compatibility"
+    }
+  },
+  "thresholds": {
+    "approve": 8.0,
+    "retry": 6.0
+  }
+}

package/framework/rubrics/frontend.json

@@ -0,0 +1,36 @@
+{
+  "id": "frontend",
+  "version": "1.0.0",
+  "description": "Frontend-focused rubric. Higher weight on design system compliance and UI quality.",
+  "categories": {
+    "functionality": {
+      "weight": 0.25,
+      "validators": ["contract-compliance"],
+      "description": "Core feature correctness and contract compliance"
+    },
+    "code_quality": {
+      "weight": 0.15,
+      "validators": ["architecture"],
+      "description": "Architecture patterns and code structure"
+    },
+    "design_ui": {
+      "weight": 0.35,
+      "validators": ["design-system", "css", "contrast", "nextjs-component"],
+      "description": "Design system compliance, CSS quality, contrast ratios, and component correctness"
+    },
+    "security": {
+      "weight": 0.10,
+      "validators": [],
+      "description": "Security posture (agent-evaluated, no automated validator)"
+    },
+    "packages": {
+      "weight": 0.15,
+      "validators": ["packages"],
+      "description": "Dependency health and compatibility"
+    }
+  },
+  "thresholds": {
+    "approve": 8.0,
+    "retry": 6.0
+  }
+}

package/framework/skills/level-0-meta/mcp-registry.json

@@ -152,11 +152,44 @@
         "warnings": ["API call execution requires your Asaas access_token. Doc search works without authentication."],
         "setupGuide": "Run: claude mcp add --transport http asaas https://docs.asaas.com/mcp"
       }
+    },
+    "stitch": {
+      "phases": ["uiux"],
+      "tools": ["create_project", "list_projects", "get_project", "list_screens", "get_screen", "generate_screen_from_text", "fetch_screen_code", "fetch_screen_image"],
+      "detection": "mcpServers includes stitch",
+      "fallback": "HTML mockup + Playwright screenshots (Step 3.5 workflow)",
+      "usage": "AI-generated screen designs, design.md export, visual design exploration",
+      "healthCheck": {
+        "toolPattern": "stitch",
+        "testCall": "Call list_projects to verify connectivity",
+        "testParams": {},
+        "successIndicator": "Returns a list of projects (possibly empty) without auth errors",
+        "failureHint": "Stitch MCP not responding. Ensure @_davideast/stitch-mcp is installed or configure official MCP: claude mcp add stitch --transport http https://stitch.googleapis.com/mcp"
+      },
+      "install": {
+        "autoInstall": true,
+        "transport": "stdio",
+        "config": {
+          "command": "cmd",
+          "args": ["/c", "npx", "-y", "@_davideast/stitch-mcp@latest", "proxy"]
+        },
+        "credentials": [],
+        "prerequisites": [],
+        "stackRelevance": ["nextjs", "nextjs-neon", "vite"],
+        "warnings": ["Community MCP tool. Official alternative: claude mcp add stitch --transport http https://stitch.googleapis.com/mcp (requires gcloud auth)"],
+        "setupGuide": "Auto-installed via npx. For official Google MCP: claude mcp add stitch --transport http https://stitch.googleapis.com/mcp"
+      },
+      "companionSkills": {
+        "repo": "google-labs-code/stitch-skills",
+        "installCommand": "npx skills add google-labs-code/stitch-skills",
+        "skills": ["stitch-design", "stitch-loop", "design-md", "prompt-enhance", "react-components", "shadcn-ui"],
+        "description": "Official Stitch agent skills for Claude Code — design generation, multi-page loops, design.md export"
+      }
     }
   },
   "phaseMatrix": {
     "proposal": ["context7"],
-    "uiux": ["playwright", "context7"],
+    "uiux": ["playwright", "context7", "stitch"],
     "design": ["context7", "github"],
     "tasks": ["context7", "github"],
     "implement": ["context7", "playwright", "github", "vercel"]

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

@@ -10,7 +10,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion,
   mcp__playwright__browser_navigate, mcp__playwright__browser_resize,
   mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot,
   mcp__playwright__browser_evaluate, mcp__playwright__browser_console_messages
-cliVersion: "4.18.0"
+cliVersion: "4.20.0"
 stacks:
   - nextjs
 ---

package/framework/skills/level-1-workflows/morph-phase-codebase-analysis/SKILL.md

@@ -3,7 +3,7 @@ name: morph-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, AskUserQuestion
-cliVersion: "4.18.0"
+cliVersion: "4.20.0"
 ---
 
 # MORPH Codebase Analysis - Design Sub-phase

package/framework/skills/level-1-workflows/morph-phase-design/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 2 (Design). Schema-first interactive design: reads
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
-cliVersion: "4.18.0"
+cliVersion: "4.20.0"
 ---
 
 # MORPH Design — Phase 2
@@ -440,4 +440,14 @@ morph-spec state set $ARGUMENTS costs.estimated {X.XX}
 | `decisions` | `.morph/features/{feature}/2-design/decisions.md` |
 <!-- /morph-outputs -->
 
+## Relevant Standards
+
+Before starting the design phase, proactively read standards relevant to the project's stack:
+- Architecture standards: `.morph/framework/standards/architecture/` — especially vertical-slice patterns
+- Backend standards: `.morph/framework/standards/backend/` — for API contracts and patterns
+- Data standards: `.morph/framework/standards/data/` — for database schema and access patterns
+- These standards are also available as rules that auto-load when editing matching file types.
+
+---
+
 Continue automatically to Plan phase after approval.

package/framework/skills/level-1-workflows/morph-phase-implement/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: "[feature-name]"
 context: fork
 agent: general-purpose
 user-invocable: false
-cliVersion: "4.18.0"
+cliVersion: "4.20.0"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 
@@ -479,4 +479,15 @@ Agent(subagent_type=morph-standards-architect, prompt=<filled prompts/code-quali
 
 ---
 
+## Relevant Standards
+
+During implementation, standards auto-load via rules when editing relevant file types.
+For proactive reference:
+- Architecture: `.morph/framework/standards/architecture/` — structural compliance
+- Backend/Frontend: `.morph/framework/standards/backend/` or `.morph/framework/standards/frontend/`
+- Security: `.morph/framework/standards/security/` — authentication, authorization patterns
+- Testing: follow the project's existing test patterns (check `test/` or `tests/` directory)
+
+---
+
 Feature complete! Consider creating a PR and running `morph-spec generate recap $ARGUMENTS`.

package/framework/skills/level-1-workflows/morph-phase-plan/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 3 (Plan). Generates a detailed implementation plan
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.18.0"
+cliVersion: "4.20.0"
 ---
 
 # MORPH Plan — Phase 3

package/framework/skills/level-1-workflows/morph-phase-tasks/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 4 (Tasks). Breaks approved spec into bottom-up ord
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.18.0"
+cliVersion: "4.20.0"
 ---
 
 # MORPH Tasks — Phase 4