@polymorphism-tech/morph-spec 8.15.1 → 8.17.0

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

@@ -1,28 +1,34 @@
 #!/usr/bin/env node
 
 /**
- * Stop Hook: Phase Transition Alert + Build Check + Session Snapshot
+ * Stop Hook: Phase Transition Alert + Build Check
  *
  * Event: Stop
  *
  * 1. Detects transitions into the `implement` phase and recommends /compact.
- * 2. Runs stack-aware build check — warns only on failure (silent on pass).
- * 3. Saves session snapshot for next-session orientation.
+ * 2. Runs stack-aware build check — dirty-flag gated (R1.2), warns only on
+ *    failure (silent on pass/skip).
  *
  * Phase transition tracking: stores last-seen phase per feature in
  * .morph/memory/phase-watch.json so the alert fires exactly once.
  *
+ * Build-dirty gate: post-edit-typecheck.js touches
+ * .morph/memory/build-dirty.json on every source-file Write/Edit. Without
+ * that flag nothing changed since the last verified build, so the (often
+ * expensive) full build/typecheck is skipped entirely instead of running on
+ * every single Stop.
+ *
  * Fail-open: exits 0 on any error.
  */
 
-import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
 import { join } from 'path';
+import { createHash } from 'crypto';
 import { runBuildCheck } from '../../shared/build-check.js';
-import { saveSessionSnapshot } from '../../shared/session-snapshot.js';
 import {
   stateExists, getActiveFeature, getMostRecentFeature, derivePhaseForFeature,
 } from '../../shared/state-reader.js';
-import { injectContext, pass } from '../../shared/hook-response.js';
+import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
 
 /**
@@ -121,122 +127,156 @@ const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 // Phases where compaction is suggested when arriving (heavy spec phases)
 const HEAVY_SOURCE_PHASES = new Set(['plan', 'uiux']);
 
-try {
-  // Prevent infinite loop
-  if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') pass();
+/**
+ * @param {object} _payload - parsed Stop stdin payload (unused — this hook
+ *   reads its own state from disk, not from the tool payload)
+ * @returns {Promise<object|null>} a hookSpecificOutput advisory (phase
+ *   transition / build failure / recap drift), or null (pass/silent).
+ */
+export async function run(_payload) {
+  try {
+    // Prevent infinite loop
+    if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') return null;
 
-  if (!stateExists()) pass();
+    if (!stateExists()) return null;
 
-  // getActiveFeature() only returns in_progress/draft features.
-  // Fall back to the most recently updated feature when all features are 'done'.
-  let active = getActiveFeature() || getMostRecentFeature();
-  if (!active) pass();
+    // getActiveFeature() only returns in_progress/draft features.
+    // Fall back to the most recently updated feature when all features are 'done'.
+    let active = getActiveFeature() || getMostRecentFeature();
+    if (!active) return null;
 
-  const { name, feature } = active;
-  const cwd  = process.cwd();
-  const warnings = [];
+    const { name, feature } = active;
+    const cwd  = process.cwd();
+    const warnings = [];
 
-  // ── Phase transition detection ────────────────────────────────────────────
-  const currentPhase = feature.phase || derivePhaseForFeature(name, cwd);
+    // .morph/memory/ hosts phase-watch.json, build-dirty.json (written by
+    // post-edit-typecheck.js) and warned-hashes.json — ensure it exists once,
+    // up front, so every write below can assume the dir is there.
+    const memDir = join(cwd, '.morph', 'memory');
+    try { mkdirSync(memDir, { recursive: true }); } catch { /* non-blocking */ }
 
-  const watchPath = join(cwd, '.morph', 'memory', 'phase-watch.json');
-  let phaseWatch  = {};
-  try {
-    if (existsSync(watchPath)) phaseWatch = JSON.parse(readFileSync(watchPath, 'utf-8'));
-  } catch { /* corrupt file — start fresh */ }
+    // ── Phase transition detection ────────────────────────────────────────────
+    const currentPhase = feature.phase || derivePhaseForFeature(name, cwd);
 
-  const lastPhase = phaseWatch[name];
+    const watchPath = join(memDir, 'phase-watch.json');
+    let phaseWatch  = {};
+    try {
+      if (existsSync(watchPath)) phaseWatch = JSON.parse(readFileSync(watchPath, 'utf-8'));
+    } catch { /* corrupt file — start fresh */ }
 
-  // Update stored phase (always, so the alert only fires once per transition)
-  try {
-    phaseWatch[name] = currentPhase;
-    writeFileSync(watchPath, JSON.stringify(phaseWatch, null, 2), 'utf-8');
-  } catch { /* non-blocking */ }
-
-  // Alert when entering implement from a heavy spec phase
-  const isPhaseTransition = lastPhase && lastPhase !== currentPhase;
-  const enteringImplement = COMPACT_TRIGGER_PHASES.has(currentPhase);
-  const comingFromHeavyPhase = HEAVY_SOURCE_PHASES.has(lastPhase);
-
-  if (isPhaseTransition && enteringImplement && comingFromHeavyPhase) {
-    warnings.push(
-      `⚡ Phase advanced: ${lastPhase} → implement`,
-      ``,
-      `💡 Recommended before starting implementation:`,
-      `   Run /compact to free up context — spec.md, mandate.md and tasks.json`,
-      `   loaded during planning take significant space. A compact now gives`,
-      `   Claude a clean slate focused on writing code.`,
-      ``,
-      `   After /compact, resume with: /morph-apply ${name}`,
-    );
-  }
+    const lastPhase = phaseWatch[name];
 
-  // ── 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;
-      const { frontendPath, backendPath } = config?.project ?? {};
-      if (stack && currentPhase === 'implement') {
-        const buildResult = runBuildCheck(cwd, stack, undefined, { frontendPath, backendPath });
-        if (buildResult.status === 'fail') {
-          warnings.push('⚠ Build/typecheck failed:');
-          warnings.push(buildResult.output);
-          warnings.push('Fix build errors before ending session.');
+    // Update stored phase (always, so the alert only fires once per transition)
+    try {
+      phaseWatch[name] = currentPhase;
+      writeFileSync(watchPath, JSON.stringify(phaseWatch, null, 2), 'utf-8');
+    } catch { /* non-blocking */ }
+
+    // Alert when entering implement from a heavy spec phase
+    const isPhaseTransition = lastPhase && lastPhase !== currentPhase;
+    const enteringImplement = COMPACT_TRIGGER_PHASES.has(currentPhase);
+    const comingFromHeavyPhase = HEAVY_SOURCE_PHASES.has(lastPhase);
+
+    if (isPhaseTransition && enteringImplement && comingFromHeavyPhase) {
+      warnings.push(
+        `⚡ Phase advanced: ${lastPhase} → implement`,
+        ``,
+        `💡 Recommended before starting implementation:`,
+        `   Run /compact to free up context — spec.md, mandate.md and tasks.json`,
+        `   loaded during planning take significant space. A compact now gives`,
+        `   Claude a clean slate focused on writing code.`,
+        ``,
+        `   After /compact, resume with: /morph-apply ${name}`,
+      );
+    }
+
+    // ── Build/typecheck verification (dirty-flag gated — R1.2) ────────────────
+    // Only run the (often expensive) full build/typecheck when something
+    // actually changed since the last time it was verified — post-edit-
+    // typecheck.js sets the flag on every source-file Write/Edit. No flag →
+    // nothing to verify → skip silently, no config/stack read even attempted.
+    const BUILD_CHECK_TIMEOUT_MS = 30000; // per-step timeout — build-check.js's own default, made explicit here
+    try {
+      const dirtyFlagPath = join(memDir, 'build-dirty.json');
+      if (existsSync(dirtyFlagPath)) {
+        const configPath = join(cwd, '.morph', 'config', 'config.json');
+        if (existsSync(configPath)) {
+          const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+          const stack = config?.project?.stack;
+          const { frontendPath, backendPath } = config?.project ?? {};
+          if (stack && currentPhase === 'implement') {
+            const buildResult = runBuildCheck(cwd, stack, BUILD_CHECK_TIMEOUT_MS, { frontendPath, backendPath });
+            if (buildResult.status === 'fail') {
+              warnings.push('⚠ Build/typecheck failed:');
+              warnings.push(buildResult.output);
+              warnings.push('Fix build errors before ending session.');
+              // keep the dirty flag — still dirty until a build actually passes
+            } else {
+              // 'pass' → verified clean. 'skip' → no build step was even
+              // resolved for this stack (e.g. fresh worktree, no tsconfig) —
+              // nothing to verify, so there is nothing left to stay dirty about.
+              // Either way, re-arm on the NEXT source edit, not every Stop.
+              try { unlinkSync(dirtyFlagPath); } catch { /* non-blocking */ }
+            }
+          }
         }
-        // pass and skip → silent (success is silent)
       }
+      // No flag → skip the build entirely, silently.
+    } catch {
+      // Fail-open — build check must never block Stop
     }
-  } catch {
-    // Fail-open — build check must never block Stop
-  }
-  // ────────────────────────────────────────────────────────────────────────
+    // ────────────────────────────────────────────────────────────────────────
 
-  // ── Recap + tasks.json audit ──────────────────────────────────────────────
-  // Surface drift between recap.md and tasks.json, plus missing standard
-  // citations. Advisory warnings only — Stop hook never blocks.
-  try {
-    const featurePath = join(cwd, '.morph', 'features', name);
-    const recapWarnings = auditRecapAndTasks(featurePath);
-    if (recapWarnings.length > 0) {
-      warnings.push('📋 Recap audit:');
-      for (const w of recapWarnings) warnings.push(`  • ${w}`);
-    }
-  } catch {
-    // Fail-open — audit must never block Stop
-  }
-  // ────────────────────────────────────────────────────────────────────────
+    // ── Recap + tasks.json audit ──────────────────────────────────────────────
+    // Surface drift between recap.md and tasks.json, plus missing standard
+    // citations. Advisory warnings only — Stop hook never blocks.
+    //
+    // The same audit re-runs every Stop; without dedup it re-injects the same
+    // ~500-token block turn after turn even when nothing changed. Hash-gate it:
+    // only inject when the warning SET differs from the last one actually
+    // surfaced for this feature. Resolved (no more warnings) clears the stored
+    // hash, so a later recurrence — even an identical one — is reported fresh.
+    try {
+      const featurePath = join(cwd, '.morph', 'features', name);
+      const recapWarnings = auditRecapAndTasks(featurePath);
 
-  // ── Session snapshot ──────────────────────────────────────────────────────
-  // Save session state for next session's "getting up to speed" routine.
-  try {
-    if (active) {
-      const { name } = active;
-      saveSessionSnapshot({
-        feature: name,
-        phase: currentPhase,
-        buildStatus: 'skip',
-        lastEditedFiles: [],
-      }, cwd);
+      const warnedHashesPath = join(memDir, 'warned-hashes.json');
+      let warnedHashes = {};
+      try {
+        if (existsSync(warnedHashesPath)) warnedHashes = JSON.parse(readFileSync(warnedHashesPath, 'utf-8'));
+      } catch { /* corrupt file — start fresh */ }
+
+      if (recapWarnings.length > 0) {
+        const hash = createHash('sha1').update(recapWarnings.join('\n')).digest('hex');
+        if (warnedHashes[name]?.recap !== hash) {
+          warnings.push('📋 Recap audit:');
+          for (const w of recapWarnings) warnings.push(`  • ${w}`);
+          warnedHashes[name] = { ...warnedHashes[name], recap: hash };
+          try { writeFileSync(warnedHashesPath, JSON.stringify(warnedHashes, null, 2), 'utf-8'); } catch { /* non-blocking */ }
+        }
+        // same hash as last time it fired → already surfaced, stay silent
+      } else if (warnedHashes[name]?.recap) {
+        delete warnedHashes[name].recap;
+        try { writeFileSync(warnedHashesPath, JSON.stringify(warnedHashes, null, 2), 'utf-8'); } catch { /* non-blocking */ }
+      }
+    } catch {
+      // Fail-open — audit must never block Stop
     }
-  } catch {
-    // Fail-open — snapshot save must never block Stop
-  }
-  // ────────────────────────────────────────────────────────────────────────
+    // ────────────────────────────────────────────────────────────────────────
 
-  if (warnings.length === 0) pass();
+    if (warnings.length === 0) return null;
 
-  const message = [
-    'MORPH-SPEC:',
-    ...warnings.map(w => `  ${w}`),
-  ].join('\n');
+    const message = [
+      'MORPH-SPEC:',
+      ...warnings.map(w => `  ${w}`),
+    ].join('\n');
 
-  logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);
-  logEvent('session_end', { feature: name, phase: currentPhase, warnings: warnings.length });
-  injectContext(message, 'Stop');
-} catch {
-  process.exit(0);
+    logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);
+    logEvent('session_end', { feature: name, phase: currentPhase, warnings: warnings.length });
+    return contextResult(message, 'Stop');
+  } catch {
+    return null;
+  }
 }
+
+await runStandalone(run);

package/framework/hooks/claude-code/core/worktree-context.js

@@ -24,6 +24,11 @@
  *   2. Primary root → active-feature summary (phase, task stats, pending
  *      gates), or silent if there's no feature in progress.
  *
+ * Also the real call site for activity-log rotation (R1.2 of the performance
+ * plan): SessionStart is the only reliable "between sessions" checkpoint the
+ * harness gets, so this is where `.morph/logs/activity.jsonl` gets archived
+ * to `.morph/logs/sessions/` once it crosses the size threshold.
+ *
  * Fail-open: any error, or nothing to report, → pass() silently. This hook
  * never blocks a session from starting.
  */
@@ -38,16 +43,9 @@ import {
   getPendingGates,
   getTaskStats,
 } from '../../shared/state-reader.js';
-import { injectContext, pass } from '../../shared/hook-response.js';
+import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { acquireClaim, foreignClaim, claimAge } from '../../shared/claim-registry.js';
-
-function readStdin() {
-  try {
-    return JSON.parse(readFileSync(0, 'utf8') || '{}');
-  } catch {
-    return {};
-  }
-}
+import { rotateActivityLogIfLarge } from '../../shared/activity-logger.js';
 
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -209,40 +207,45 @@ function claimBlock(dir, feature, sessionId) {
   }
 }
 
-async function main() {
+/**
+ * @param {object} payload - parsed SessionStart stdin payload
+ * @returns {Promise<object|null>} a hookSpecificOutput context (worktree
+ *   identity or active-feature summary), or null (pass/silent).
+ */
+export async function run(payload) {
   try {
     const dir = projectDir();
     // The SessionStart payload carries session_id — the identity the claim
     // registry uses to tell "me" from "another session".
-    const payload = readStdin();
     const sessionId = payload?.session_id || `pid-${process.pid}`;
 
     if (!stateExists(dir)) {
-      pass();
-      return;
+      return null;
     }
 
+    // Rotate the activity log before anything else touches it this session.
+    // Best-effort, never fatal to session start — rotateActivityLogIfLarge()
+    // is itself fail-open (returns false on any error).
+    try { rotateActivityLogIfLarge(dir); } catch { /* non-blocking */ }
+
     if (isSecondaryWorktree(dir)) {
       const feature = featureFromBranch(dir) || featureFromSingleDir(dir);
       if (!feature) {
-        pass();
-        return;
+        return null;
       }
-      injectContext(buildWorktreeContext(dir, feature) + claimBlock(dir, feature, sessionId), 'SessionStart');
-      return;
+      return contextResult(buildWorktreeContext(dir, feature) + claimBlock(dir, feature, sessionId), 'SessionStart');
     }
 
     // Primary root — active-feature summary (or silent if nothing's in progress)
     const summary = buildActiveFeatureSummary(dir);
     if (!summary) {
-      pass();
-      return;
+      return null;
     }
     const active = getActiveFeature(dir);
-    injectContext(summary + (active?.name ? claimBlock(dir, active.name, sessionId) : ''), 'SessionStart');
+    return contextResult(summary + (active?.name ? claimBlock(dir, active.name, sessionId) : ''), 'SessionStart');
   } catch {
-    pass();
+    return null;
   }
 }
 
-main().catch(() => pass());
+await runStandalone(run);

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

@@ -443,15 +443,37 @@ def get_active_features(cwd):
 
 
 def get_last_hook(cwd):
-    """Name of the most recent hook from .morph/logs/activity.json.
+    """Name of the most recent hook from .morph/logs/activity.jsonl.
+
+    activity-logger.js (R1.2) writes append-only JSONL now, one event per
+    line (`{"kind": "hook", ...}` or `{"kind": "event", ...}`), instead of a
+    single JSON doc rewritten whole on every call. The log can grow up to the
+    rotation threshold (2 MB, see ROTATE_THRESHOLD_BYTES in activity-logger.js)
+    between SessionStarts, and this function runs on every prompt redraw, so
+    only the trailing slice is read — never the whole file.
 
     The age is deliberately not shown: activity-logger.js only records
     HH:MM:SS, so any age computed from it is wrong across midnight.
     """
     try:
-        raw = (Path(cwd) / '.morph' / 'logs' / 'activity.json').read_text(encoding='utf-8')
-        hooks = json.loads(raw).get('hooks') or []
-        return hooks[-1].get('name') or None if hooks else None
+        path = Path(cwd) / '.morph' / 'logs' / 'activity.jsonl'
+        size = path.stat().st_size
+        tail_bytes = 8192
+        with path.open('rb') as f:
+            if size > tail_bytes:
+                f.seek(-tail_bytes, 2)
+            tail = f.read().decode('utf-8', errors='ignore')
+        for line in reversed(tail.splitlines()):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except Exception:
+                continue
+            if obj.get('kind') == 'hook':
+                return obj.get('name') or None
+        return None
     except Exception:
         return None