@polymorphism-tech/morph-spec 7.9.3 → 8.0.0

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

@@ -1,160 +1,160 @@
-/**
- * Activity Logger — Session-scoped hook event log
- *
- * Writes hook activity to .morph/logs/activity.json for live consumption
- * by `morph-spec monitor`.
- *
- * Design constraints:
- * - Synchronous only (hooks run in process, no async overhead)
- * - Fail-silent (never throws — hooks must not be blocked by logger)
- * - ≤5ms per call (no retries, no network)
- * - Windows-safe paths via path.join
- */
-
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
-import { join } from 'path';
-
-const LOGS_DIR = '.morph/logs';
-const ACTIVITY_FILE = join(LOGS_DIR, 'activity.json');
-
-function getActivityPath(projectPath) {
-  return join(projectPath || process.cwd(), ACTIVITY_FILE);
-}
-
-function ensureLogsDir(projectPath) {
-  const dir = join(projectPath || process.cwd(), LOGS_DIR);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-}
-
-function readRaw(activityPath) {
-  try {
-    if (!existsSync(activityPath)) return null;
-    return JSON.parse(readFileSync(activityPath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Log a hook firing event to the session activity log.
- *
- * @param {string} name   - Hook name (e.g. 'dispatch.js', 'enrich-prompt')
- * @param {string} event  - Claude Code event (e.g. 'PostToolUse', 'UserPromptSubmit')
- * @param {string} result - Outcome summary (e.g. 'ok', 'blocked', 'checkpoint_saved')
- * @param {string} [projectPath] - Project root (defaults to cwd)
- */
-export function logHookActivity(name, event, result, projectPath) {
-  try {
-    const activityPath = getActivityPath(projectPath);
-    ensureLogsDir(projectPath);
-
-    const now = new Date();
-    const ts = now.toTimeString().slice(0, 8); // HH:MM:SS
-
-    const data = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], skills: [] };
-
-    data.hooks = data.hooks || [];
-    data.hooks.push({ name, event, result, ts });
-
-    writeFileSync(activityPath, JSON.stringify(data, null, 2), 'utf-8');
-  } catch {
-    // Fail-silent — never block hooks
-  }
-}
-
-
-/**
- * Read the current activity log.
- *
- * @param {string} [projectPath]
- * @returns {{ sessionId: string, feature: string, phase: string, hooks: Array, skills: Array }|null}
- */
-export function readActivity(projectPath) {
-  try {
-    return readRaw(getActivityPath(projectPath));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Reset the activity log for a new session.
- * Called from SessionStart hook to clear stale data.
- *
- * @param {string} sessionId  - ISO timestamp of new session
- * @param {string} feature    - Active feature name (empty string if none)
- * @param {string} phase      - Current phase (empty string if none)
- * @param {string} [projectPath]
- */
-export function resetActivity(sessionId, feature, phase, projectPath) {
-  try {
-    ensureLogsDir(projectPath);
-    const data = {
-      sessionId: sessionId || new Date().toISOString(),
-      feature: feature || '',
-      phase: phase || '',
-      hooks: [],
-      skills: []
-    };
-    writeFileSync(getActivityPath(projectPath), JSON.stringify(data, null, 2), 'utf-8');
-  } catch {
-    // 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
-  }
-}
+/**
+ * Activity Logger — Session-scoped hook event log
+ *
+ * Writes hook activity to .morph/logs/activity.json for live consumption
+ * by `morph-spec monitor`.
+ *
+ * Design constraints:
+ * - Synchronous only (hooks run in process, no async overhead)
+ * - Fail-silent (never throws — hooks must not be blocked by logger)
+ * - ≤5ms per call (no retries, no network)
+ * - Windows-safe paths via path.join
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
+import { join } from 'path';
+
+const LOGS_DIR = '.morph/logs';
+const ACTIVITY_FILE = join(LOGS_DIR, 'activity.json');
+
+function getActivityPath(projectPath) {
+  return join(projectPath || process.cwd(), ACTIVITY_FILE);
+}
+
+function ensureLogsDir(projectPath) {
+  const dir = join(projectPath || process.cwd(), LOGS_DIR);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function readRaw(activityPath) {
+  try {
+    if (!existsSync(activityPath)) return null;
+    return JSON.parse(readFileSync(activityPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Log a hook firing event to the session activity log.
+ *
+ * @param {string} name   - Hook name (e.g. 'dispatch.js', 'enrich-prompt')
+ * @param {string} event  - Claude Code event (e.g. 'PostToolUse', 'UserPromptSubmit')
+ * @param {string} result - Outcome summary (e.g. 'ok', 'blocked', 'checkpoint_saved')
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ */
+export function logHookActivity(name, event, result, projectPath) {
+  try {
+    const activityPath = getActivityPath(projectPath);
+    ensureLogsDir(projectPath);
+
+    const now = new Date();
+    const ts = now.toTimeString().slice(0, 8); // HH:MM:SS
+
+    const data = readRaw(activityPath) || { sessionId: '', feature: '', phase: '', hooks: [], skills: [] };
+
+    data.hooks = data.hooks || [];
+    data.hooks.push({ name, event, result, ts });
+
+    writeFileSync(activityPath, JSON.stringify(data, null, 2), 'utf-8');
+  } catch {
+    // Fail-silent — never block hooks
+  }
+}
+
+
+/**
+ * Read the current activity log.
+ *
+ * @param {string} [projectPath]
+ * @returns {{ sessionId: string, feature: string, phase: string, hooks: Array, skills: Array }|null}
+ */
+export function readActivity(projectPath) {
+  try {
+    return readRaw(getActivityPath(projectPath));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reset the activity log for a new session.
+ * Called from SessionStart hook to clear stale data.
+ *
+ * @param {string} sessionId  - ISO timestamp of new session
+ * @param {string} feature    - Active feature name (empty string if none)
+ * @param {string} phase      - Current phase (empty string if none)
+ * @param {string} [projectPath]
+ */
+export function resetActivity(sessionId, feature, phase, projectPath) {
+  try {
+    ensureLogsDir(projectPath);
+    const data = {
+      sessionId: sessionId || new Date().toISOString(),
+      feature: feature || '',
+      phase: phase || '',
+      hooks: [],
+      skills: []
+    };
+    writeFileSync(getActivityPath(projectPath), JSON.stringify(data, null, 2), 'utf-8');
+  } catch {
+    // 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

@@ -23,11 +23,11 @@ export function getBuildCommand(stack, hasTsConfig = false) {
   const s = stack.toLowerCase();
 
   if (s.includes('dotnet')) {
-    return 'dotnet build --no-restore --nologo -v q 2>&1 | tail -20';
+    return 'dotnet build --no-restore --nologo -v q';
   }
 
   if ((s.includes('nextjs') || s.includes('node') || s.includes('react')) && hasTsConfig) {
-    return 'npx tsc --noEmit 2>&1 | tail -20';
+    return 'npx tsc --noEmit';
   }
 
   return null;

package/framework/hooks/shared/hook-response.js

@@ -3,7 +3,11 @@
  *
  * Claude Code hooks communicate via JSON to stdout.
  * - PreToolUse: { "decision": "block"|"approve", "reason": "..." }
- * - SessionStart/Stop/etc: { "additionalContext": "..." }
+ * - SessionStart/Stop/PostToolUse/etc (non-blocking context injection):
+ *   { "hookSpecificOutput": { "hookEventName": "...", "additionalContext": "..." } }
+ *   A top-level `additionalContext` is NOT honored by Claude Code for any
+ *   event — it must be nested under `hookSpecificOutput` alongside the
+ *   event name (see https://code.claude.com/docs/en/hooks.md).
  */
 
 /**
@@ -28,12 +32,20 @@ export function approve(context) {
 }
 
 /**
- * Inject additional context (for SessionStart, Stop, UserPromptSubmit, etc.).
+ * Inject additional (non-blocking) context for the current hook event.
+ *
+ * Must be nested under `hookSpecificOutput` — Claude Code does not honor a
+ * top-level `additionalContext` for any event.
+ *
  * @param {string} text - Context text to inject
- * @param {Object} [extra] - Additional fields to include in response
+ * @param {string} eventName - The hook event this is responding to (e.g.
+ *   'SessionStart', 'Stop', 'PostToolUse') — required, echoed back as
+ *   `hookSpecificOutput.hookEventName`.
  */
-export function injectContext(text, extra = {}) {
-  console.log(JSON.stringify({ additionalContext: text, ...extra }));
+export function injectContext(text, eventName) {
+  console.log(JSON.stringify({
+    hookSpecificOutput: { hookEventName: eventName, additionalContext: text },
+  }));
   process.exit(0);
 }
 

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

@@ -5,6 +5,48 @@
  * normalizing between Write (content, file_path) and Edit (new_string, old_string, file_path).
  */
 
+import { existsSync } from 'fs';
+import { dirname, join, isAbsolute } from 'path';
+
+/**
+ * Resolve the project root that OWNS a given file: walk up from the file's
+ * directory to the nearest ancestor containing one of `markers` (default
+ * `package.json` — the tsc/build root). Falls back to `fallbackCwd` when
+ * nothing matches or on any error.
+ *
+ * This exists so a PostToolUse hook typechecks/builds in the CORRECT root when
+ * a subagent edits a file inside its own git worktree (`isolation: "worktree"`,
+ * morph-apply §3b-w) instead of always assuming the main working tree. In the
+ * normal (non-worktree) case it resolves to the same root as `process.cwd()`.
+ *
+ * Fail-open: never throws — returns `fallbackCwd` on any error.
+ *
+ * @param {string} filePath - edited file path (absolute or relative)
+ * @param {string} fallbackCwd - root to use if resolution fails (usually process.cwd())
+ * @param {string[]} [markers] - ancestor marker filenames to look for
+ * @returns {string} the resolved root directory
+ */
+export function resolveRootForFile(filePath, fallbackCwd, markers = ['package.json']) {
+  try {
+    if (!filePath) return fallbackCwd;
+    let p = String(filePath).replace(/\\/g, '/');
+    if (!isAbsolute(p)) p = join(fallbackCwd, p);
+
+    let dir = dirname(p);
+    let prev = null;
+    while (dir && dir !== prev) {
+      for (const marker of markers) {
+        if (existsSync(join(dir, marker))) return dir;
+      }
+      prev = dir;
+      dir = dirname(dir);
+    }
+    return fallbackCwd;
+  } catch {
+    return fallbackCwd;
+  }
+}
+
 /**
  * Get the file path from a hook payload, normalizing backslashes.
  * @param {Object} payload - Hook payload from stdin

package/framework/hooks/shared/state-reader.js

@@ -69,12 +69,32 @@ export function loadState(projectPath) {
 }
 
 /**
- * Check if state.json exists.
+ * Check if there is state to read: either the thin `.morph/state.json` index
+ * exists, or `.morph/features/` (committed, gitignore-exempt) already has at
+ * least one feature with a `feature.json`. The latter case covers a freshly
+ * checked-out worktree where state.json (gitignored) hasn't been materialized
+ * yet, but `loadState()` can already self-heal from feature.json — so hooks
+ * gating on `stateExists()` should be "on" there too, not dark.
+ * Fail-open: any unexpected error (e.g. permission denied) returns false.
  * @param {string} [projectPath]
  * @returns {boolean}
  */
 export function stateExists(projectPath) {
-  return existsSync(join(projectPath || process.cwd(), STATE_FILE));
+  try {
+    const base = projectPath || process.cwd();
+    if (existsSync(join(base, STATE_FILE))) return true;
+
+    const featuresDir = join(base, FEATURES_DIR);
+    if (!existsSync(featuresDir)) return false;
+
+    const names = readdirSync(featuresDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+
+    return names.some((name) => existsSync(join(featuresDir, name, 'feature.json')));
+  } catch {
+    return false;
+  }
 }
 
 /**

package/framework/hooks/shared/stdin-reader.js

@@ -1,26 +1,26 @@
-/**
- * Shared stdin reader for Claude Code hooks.
- *
- * Reads JSON payload from stdin (provided by Claude Code to hooks).
- * Returns parsed object or null on failure.
- */
-
-/**
- * Read and parse JSON from stdin
- * @returns {Promise<Object|null>} Parsed JSON or null
- */
-export function readStdin() {
-  return new Promise((resolve) => {
-    let input = '';
-    process.stdin.setEncoding('utf-8');
-    process.stdin.on('data', (chunk) => { input += chunk; });
-    process.stdin.on('end', () => {
-      try {
-        resolve(JSON.parse(input || '{}'));
-      } catch {
-        resolve(null);
-      }
-    });
-    process.stdin.on('error', () => resolve(null));
-  });
-}
+/**
+ * Shared stdin reader for Claude Code hooks.
+ *
+ * Reads JSON payload from stdin (provided by Claude Code to hooks).
+ * Returns parsed object or null on failure.
+ */
+
+/**
+ * Read and parse JSON from stdin
+ * @returns {Promise<Object|null>} Parsed JSON or null
+ */
+export function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input || '{}'));
+      } catch {
+        resolve(null);
+      }
+    });
+    process.stdin.on('error', () => resolve(null));
+  });
+}

package/framework/rubrics/backend.json

@@ -1,41 +1,41 @@
-{
-  "id": "backend",
-  "version": "1.1.0",
-  "description": "Backend-focused rubric. Higher weight on architecture, security, and package health. Deterministic-validator rubric — approve threshold aligned to the single bar 9 from MORPH.md §0.",
-  "categories": {
-    "functionality": {
-      "weight": 0.25,
-      "validators": ["contract-compliance"],
-      "description": "Core feature correctness and contract compliance"
-    },
-    "code_quality": {
-      "weight": 0.25,
-      "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"
-    },
-    "maf_compliance": {
-      "weight": 0.10,
-      "validators": [],
-      "description": "MAF agent compliance (agent-evaluated, applies only when the feature touches AI agents): Microsoft.Agents.AI GA packages used; Model Registry alias referenced not hardcoded models; structured output for pipelined agents; prompts from DB not hardcoded; no Semantic Kernel; no hosted agent services."
-    }
-  },
-  "thresholds": {
-    "approve": 9.0,
-    "retry": 6.0
-  }
-}
+{
+  "id": "backend",
+  "version": "1.1.0",
+  "description": "Backend-focused rubric. Higher weight on architecture, security, and package health. Deterministic-validator rubric — approve threshold aligned to the single bar 9 from MORPH.md §0.",
+  "categories": {
+    "functionality": {
+      "weight": 0.25,
+      "validators": ["contract-compliance"],
+      "description": "Core feature correctness and contract compliance"
+    },
+    "code_quality": {
+      "weight": 0.25,
+      "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"
+    },
+    "maf_compliance": {
+      "weight": 0.10,
+      "validators": [],
+      "description": "MAF agent compliance (agent-evaluated, applies only when the feature touches AI agents): Microsoft.Agents.AI GA packages used; Model Registry alias referenced not hardcoded models; structured output for pipelined agents; prompts from DB not hardcoded; no Semantic Kernel; no hosted agent services."
+    }
+  },
+  "thresholds": {
+    "approve": 9.0,
+    "retry": 6.0
+  }
+}