@polymorphism-tech/morph-spec 7.9.3 → 8.0.0

package/framework/hooks/README.md

@@ -7,8 +7,8 @@ Comprehensive hooks system for enforcing spec-driven development at the Claude C
 ```
 framework/hooks/
 ├── claude-code/                     # Claude Code native hooks
-│   ├── session-start/
-│   │   └── inject-morph-context.js  # Inject state summary on session start
+│   ├── core/
+│   │   └── worktree-context.js      # SessionStart: worktree feature identity / active-feature summary
 │   ├── user-prompt/
 │   │   └── enrich-prompt.js         # Context-aware prompt enrichment
 │   ├── pre-tool-use/
@@ -41,6 +41,7 @@ framework/hooks/
 
 | Event | Hook | Type | Purpose |
 |-------|------|------|---------|
+| **SessionStart** | worktree-context.js | Context inject | Secondary worktree → feature identity (name/branch/phase) + missing-junction warning; primary root → active-feature summary (phase, task stats, pending gates), silent if none |
 | **PreToolUse** (Write\|Edit) | _(native permissions.deny)_ | Block | Blocks edits to state.json and .morph/framework/ |
 | **PreToolUse** (Write\|Edit) | protect-spec-files.js | Block | Blocks edits to spec files after approval; for tasks.json validates the mutable-field diff, the status enum, and requires a `notes` when `outputs` diverge from the plan |
 | **PreToolUse** (Write\|Edit) | enforce-phase-writes.js | Block | Ensures writes go to current phase directory |
@@ -113,6 +114,8 @@ All Claude Code hooks import from `framework/hooks/shared/`:
 | `hook-response.js` | `block(reason)`, `approve(context)`, `injectContext(text)`, `pass()` |
 | `stdin-reader.js` | `readStdin()` — Promise-based stdin JSON reader |
 
+`injectContext(text)` is how `worktree-context.js` (and any other SessionStart hook) delivers context: it emits `{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": text } }` on stdout. Claude Code only honors additional context nested under `hookSpecificOutput` — a bare top-level field is ignored.
+
 ## How Hooks Work
 
 ### PreToolUse (Write|Edit) Flow
@@ -147,16 +150,28 @@ enforce-phase-writes.js
 ```
 Session starts/resumes/compacts
     ↓
-inject-morph-context.js
-    ├── No state.json → silent exit
-    ├── Has active feature → inject summary:
-    │   "MORPH-SPEC Status:
-    │    - Active feature: my-feature (phase: implement)
-    │    - Tasks: 3/10 completed
-    │    - Pending approvals: design, tasks"
-    └── No active feature → inject feature list
+worktree-context.js
+    ├── No morph project (no state.json AND no .morph/features/) → silent exit
+    ├── Secondary worktree (git-dir != git-common-dir)?
+    │   ├── Feature identified (branch morph/{f}, or the lone .morph/features/ dir)
+    │   │   → inject: "🌳 Worktree desta feature: {f} (branch morph/{f}, fase {phase}).
+    │   │      Trabalhe apenas nesta feature nesta sessão; o estado vive no .morph/
+    │   │      deste worktree." + a warning appended if node_modules/.claude
+    │   │      junctions are missing ("Rode: morph-spec worktree link --all")
+    │   └── No feature identified → silent exit
+    └── Primary root (not a worktree)
+        ├── Has active (in_progress/draft) feature → inject summary:
+        │   "MORPH-SPEC: feature ativa {name} (fase {phase}) · tasks {c}/{t}
+        │    · gates pendentes: {gate, gate}"
+        └── No active feature → silent exit (don't clutter idle sessions)
 ```
 
+v8 note: this hook also fulfills the SessionStart injection role this README
+used to describe as `inject-morph-context.js` — that file was documented but
+never registered in `MORPH_HOOKS`; `worktree-context.js` is the hook that
+actually ships (v3.2.0), and its primary-root branch covers the same
+active-feature-summary ground.
+
 ## Testing
 
 ```bash

package/framework/hooks/claude-code/core/gate-guard.js

@@ -98,7 +98,8 @@ function checkAskUserQuestion(input, state, feature, cwd) {
         `(trust:${decision.trust ?? 'auto'}, nenhum sinal de risco). ` +
         `Sob trust:auto sem risco, este gate deveria auto-passar com um summary curto, sem interromper o humano. ` +
         `Se a pausa foi intencional (você detectou um risco que o registro não capturou), atualize gateDecisions.${gate}.signals antes de prosseguir; ` +
-        `caso contrário, evite pausar gates auto-aprováveis.`
+        `caso contrário, evite pausar gates auto-aprováveis.`,
+        'PostToolUse'
       );
     }
     // The decision said pause:true and the LLM did pause — coherent.
@@ -138,7 +139,8 @@ function checkStateEdit(input, state, feature, cwd) {
         `mas a decisão registrada (gateDecisions.${gate}) era pause:true ` +
         `(sinal: ${decision.reason || 'risco detectado'}). ` +
         `Um sinal de risco exigia pausa humana via AskUserQuestion — uma auto-aprovação aqui ignora o trust mode. ` +
-        `Reabra o gate com AskUserQuestion (label "aprovado, prosseguir") ou corrija o sinal de risco antes de avançar.`
+        `Reabra o gate com AskUserQuestion (label "aprovado, prosseguir") ou corrija o sinal de risco antes de avançar.`,
+        'PostToolUse'
       );
     }
     checked = true;

package/framework/hooks/claude-code/core/loop-detect.js

@@ -95,7 +95,8 @@ try {
     `  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.`
+    `Do NOT continue the same pattern.`,
+    'PostToolUse'
   );
 } catch {
   // Fail-open

package/framework/hooks/claude-code/core/post-edit-typecheck.js

@@ -20,6 +20,7 @@ import { join } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
 import { pass, injectContext } from '../../shared/hook-response.js';
 import { stateExists } from '../../shared/state-reader.js';
+import { resolveRootForFile } from '../../shared/payload-utils.js';
 
 const DEBOUNCE_MS = 3000;
 
@@ -33,9 +34,17 @@ try {
   if (!['Write', 'Edit'].includes(toolName)) pass();
   if (!filePath.match(/\.tsx?$/)) pass();
 
-  // Debounce: skip if a typecheck ran within the last 3 seconds
-  const cwd = process.cwd();
-  const memDir = join(cwd, '.morph', 'memory');
+  // Resolve the root that OWNS the edited file — when a subagent edits inside
+  // its own git worktree (isolation: "worktree", §3b-w), tsc must run there,
+  // not in the main working tree. Falls back to cwd for the normal case.
+  const root = resolveRootForFile(filePath, process.cwd());
+
+  // No node_modules under the resolved root → tsc can't run; pass silently
+  // (a fresh worktree before `morph-spec worktree link` has no node_modules).
+  if (!existsSync(join(root, 'node_modules'))) pass();
+
+  // Debounce (keyed by root): skip if a typecheck ran within the last 3s.
+  const memDir = join(root, '.morph', 'memory');
   const debouncePath = join(memDir, 'typecheck-debounce.json');
 
   try {
@@ -51,7 +60,7 @@ try {
   } catch { /* non-blocking */ }
 
   try {
-    execSync('npx tsc --noEmit', { cwd, stdio: 'pipe', timeout: 30000 });
+    execSync('npx tsc --noEmit', { cwd: root, stdio: 'pipe', timeout: 30000 });
     pass();
   } catch (err) {
     const stderr = err.stderr?.toString() || '';
@@ -62,7 +71,7 @@ try {
       .filter(l => l.includes(fileName) || l.includes('error TS'))
       .slice(0, 10)
       .join('\n');
-    injectContext(`TypeScript errors after editing ${fileName}:\n${relevant || output.split('\n').slice(0, 10).join('\n')}`);
+    injectContext(`TypeScript errors after editing ${fileName}:\n${relevant || output.split('\n').slice(0, 10).join('\n')}`, 'PostToolUse');
   }
 } catch {
   pass();

package/framework/hooks/claude-code/core/tasks-json-guard.js

@@ -59,7 +59,8 @@ try {
     logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
     injectContext(
       '⚠️ [morph-spec] tasks.json INVÁLIDO — o arquivo gravado não parseia como JSON. ' +
-      'Corrija o arquivo antes de continuar.'
+      'Corrija o arquivo antes de continuar.',
+      'PostToolUse'
     );
   }
 
@@ -69,7 +70,8 @@ try {
     injectContext(
       '⚠️ [morph-spec] tasks.json com schema inválido após o write:\n' +
       errors.map(e => `  • ${e}`).join('\n') +
-      `\nStatus válidos: ${VALID_TASK_STATUS.join(', ')}. Corrija antes de marcar a task como done.`
+      `\nStatus válidos: ${VALID_TASK_STATUS.join(', ')}. Corrija antes de marcar a task como done.`,
+      'PostToolUse'
     );
   }
 

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

@@ -235,7 +235,7 @@ try {
 
   logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);
   logEvent('session_end', { feature: name, phase: currentPhase, warnings: warnings.length });
-  injectContext(message);
+  injectContext(message, 'Stop');
 } catch {
   process.exit(0);
 }

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

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * worktree-context.js — SessionStart hook
+ *
+ * Event: SessionStart
+ *
+ * v8 runs each feature in its own git worktree (`.worktrees/{feature}/` on
+ * branch `morph/{feature}`), each with its own Claude Code instance. When a
+ * session starts inside one of those worktrees, Claude has no built-in way to
+ * know which feature it belongs to — this hook injects that identity so the
+ * agent doesn't have to guess (or worse, wander into another feature's
+ * `.morph/`).
+ *
+ * This also fulfills the SessionStart injection role long documented in
+ * `framework/hooks/README.md` as `inject-morph-context.js` — a hook that was
+ * described but never registered in MORPH_HOOKS. In the primary root (not a
+ * worktree) this hook covers that same ground: a compact active-feature
+ * summary so a fresh session doesn't have to re-read state.json by hand.
+ *
+ * Two branches:
+ *   1. Secondary worktree → feature identity (name, branch, phase) +
+ *      a warning if shared infra junctions (node_modules/.claude) are
+ *      missing (they're created by `morph-spec worktree link --all`).
+ *   2. Primary root → active-feature summary (phase, task stats, pending
+ *      gates), or silent if there's no feature in progress.
+ *
+ * Fail-open: any error, or nothing to report, → pass() silently. This hook
+ * never blocks a session from starting.
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import {
+  stateExists,
+  getActiveFeature,
+  getFeaturePhase,
+  getPendingGates,
+  getTaskStats,
+} from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function projectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function gitRevParse(arg, dir) {
+  return execSync(`git rev-parse ${arg}`, { cwd: dir, stdio: ['pipe', 'pipe', 'pipe'] })
+    .toString()
+    .trim();
+}
+
+/**
+ * A secondary git worktree has a `--git-dir` (worktree-private, under
+ * `.../.git/worktrees/{name}`) distinct from its `--git-common-dir` (the
+ * primary repo's shared `.git`). In the primary root both resolve to the
+ * same path. Any git error (not a repo at all) is treated as "not a
+ * worktree" — fail-open.
+ */
+function isSecondaryWorktree(dir) {
+  try {
+    const gitDir = gitRevParse('--git-dir', dir);
+    const commonDir = gitRevParse('--git-common-dir', dir);
+    return gitDir !== commonDir;
+  } catch {
+    return false;
+  }
+}
+
+/** Feature name from the current branch, if it matches `morph/{feature}`. */
+function featureFromBranch(dir) {
+  try {
+    const branch = gitRevParse('--abbrev-ref HEAD', dir);
+    const match = branch.match(/^morph\/(.+)$/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Fallback: if exactly one feature directory exists, assume that's the one. */
+function featureFromSingleDir(dir) {
+  try {
+    const entries = readdirSync(join(dir, '.morph', 'features'), { withFileTypes: true })
+      .filter((e) => e.isDirectory());
+    return entries.length === 1 ? entries[0].name : null;
+  } catch {
+    return null;
+  }
+}
+
+function buildWorktreeContext(dir, feature) {
+  const phase = getFeaturePhase(feature, dir);
+  let text = `🌳 Worktree desta feature: ${feature} (branch morph/${feature}, fase ${phase}). ` +
+    `Trabalhe apenas nesta feature nesta sessão; o estado vive no .morph/ deste worktree.`;
+
+  const missingJunctions = !existsSync(join(dir, 'node_modules')) || !existsSync(join(dir, '.claude'));
+  if (missingJunctions) {
+    text += `\n⚠ Infra compartilhada ausente (node_modules/.claude). Rode: morph-spec worktree link --all`;
+  }
+
+  return text;
+}
+
+function buildActiveFeatureSummary(dir) {
+  const active = getActiveFeature(dir);
+  if (!active) return null;
+
+  const phase = getFeaturePhase(active.name, dir);
+  const stats = getTaskStats(active.feature);
+  const pending = getPendingGates(active.name, dir);
+
+  let text = `MORPH-SPEC: feature ativa ${active.name} (fase ${phase}) · tasks ${stats.completed}/${stats.total}`;
+  if (pending.length) {
+    text += ` · gates pendentes: ${pending.join(', ')}`;
+  }
+  return text;
+}
+
+async function main() {
+  try {
+    const dir = projectDir();
+    readStdin(); // consume the SessionStart payload (source/session_id) — unused here
+
+    if (!stateExists(dir)) {
+      pass();
+      return;
+    }
+
+    if (isSecondaryWorktree(dir)) {
+      const feature = featureFromBranch(dir) || featureFromSingleDir(dir);
+      if (!feature) {
+        pass();
+        return;
+      }
+      injectContext(buildWorktreeContext(dir, feature), 'SessionStart');
+      return;
+    }
+
+    // Primary root — active-feature summary (or silent if nothing's in progress)
+    const summary = buildActiveFeatureSummary(dir);
+    if (!summary) {
+      pass();
+      return;
+    }
+    injectContext(summary, 'SessionStart');
+  } catch {
+    pass();
+  }
+}
+
+main().catch(() => pass());