@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

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

@@ -1,14 +1,5 @@
 #!/usr/bin/env node
 
-/**
- * Stop Hook: phase-transition alert, slice report audit, session usage.
- *
- * Phase transition tracking: stores last-seen phase per feature in
- * .morph/memory/phase-watch.json so the alert fires exactly once.
- *
- * Fail-open: exits 0 on any error.
- */
-
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { createHash } from 'crypto';
@@ -21,11 +12,7 @@ import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
 import { readTranscriptUsage, usageDelta } from '../../shared/transcript-usage.js';
 import { sliceProgress, sliceReportPath, inspectReport } from '../../shared/slice-progress.js';
 
-/**
- * Slices whose report is final but lacks what the report contract asks for:
- * prose, the files touched, every scenario the slice covers. Advisory: the
- * same rule `report-check` applies when the orchestrator resumes control.
- */
+// Advisory: the same rule `report-check` applies when the orchestrator resumes control.
 function auditSliceReports(featurePath) {
   const progress = sliceProgress(featurePath);
   if (!progress) return [];
@@ -47,30 +34,16 @@ const MISSING_HINT = {
   partial: '1ª linha PARCIAL: a fatia não terminou',
 };
 
-// Phases where compaction is strongly recommended before starting
 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']);
 
-/**
- * @param {object} payload - parsed Stop stdin payload. Most of this hook's
- *   logic reads its own state from disk rather than the payload, EXCEPT the
- *   session-usage capture below, which needs `payload.transcript_path` (and
- *   `payload.session_id` for the throttle key) — the one thing only the
- *   payload carries.
- * @returns {Promise<object|null>} a hookSpecificOutput advisory (phase
- *   transition / build failure / incomplete slice report), 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()) 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) return null;
 
@@ -79,9 +52,8 @@ export async function run(payload) {
     const warnings = [];
 
     const memDir = join(cwd, '.morph', 'memory');
-    try { mkdirSync(memDir, { recursive: true }); } catch { /* non-blocking */ }
+    try { mkdirSync(memDir, { recursive: true }); } catch {}
 
-    // ── Phase transition detection ────────────────────────────────────────────
     const currentPhase = feature.phase || derivePhaseForFeature(name, cwd);
 
     const watchPath = join(memDir, 'phase-watch.json');
@@ -92,13 +64,12 @@ export async function run(payload) {
 
     const lastPhase = phaseWatch[name];
 
-    // Update stored phase (always, so the alert only fires once per transition)
+    // Always stored, so the alert fires once per transition.
     try {
       phaseWatch[name] = currentPhase;
       writeFileSync(watchPath, JSON.stringify(phaseWatch, null, 2), 'utf-8');
-    } catch { /* non-blocking */ }
+    } catch {}
 
-    // 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);
@@ -116,14 +87,7 @@ export async function run(payload) {
       );
     }
 
-    // ── Slice report audit ────────────────────────────────────────────────────
-    // 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.
+    // Hash-gated: the audit re-runs every Stop, so only a changed warning set is injected; resolving clears the hash.
     try {
       const featurePath = join(cwd, '.morph', 'features', name);
       const reportWarnings = auditSliceReports(featurePath);
@@ -140,22 +104,15 @@ export async function run(payload) {
           warnings.push('📋 Relatórios de fatia:');
           for (const w of reportWarnings) warnings.push(`  • ${w}`);
           warnedHashes[name] = { ...warnedHashes[name], reports: hash };
-          try { writeFileSync(warnedHashesPath, JSON.stringify(warnedHashes, null, 2), 'utf-8'); } catch { /* non-blocking */ }
+          try { writeFileSync(warnedHashesPath, JSON.stringify(warnedHashes, null, 2), 'utf-8'); } catch {}
         }
-        // same hash as last time it fired → already surfaced, stay silent
       } else if (warnedHashes[name]?.reports) {
         delete warnedHashes[name].reports;
-        try { writeFileSync(warnedHashesPath, JSON.stringify(warnedHashes, null, 2), 'utf-8'); } catch { /* non-blocking */ }
+        try { writeFileSync(warnedHashesPath, JSON.stringify(warnedHashes, null, 2), 'utf-8'); } catch {}
       }
-    } catch {
-      // Fail-open — audit must never block Stop
-    }
-    // ────────────────────────────────────────────────────────────────────────
+    } catch {}
 
-    // ── Session usage (real tokens, from the transcript) ──────────────────────
-    // Silent side effect. The transcript total is cumulative, so each event
-    // also carries the `delta` since the previous sample of the same session:
-    // summing deltas per sessionId is the only sum that does not double-count.
+    // The transcript total is cumulative: summing the per-session `delta` is the only sum that does not double-count.
     try {
       const usage = readTranscriptUsage(payload?.transcript_path);
       if (usage) {
@@ -177,13 +134,10 @@ export async function run(payload) {
             delta,
           }, cwd);
           stored[sessionKey] = usage;
-          try { writeFileSync(usagePath, JSON.stringify(stored, null, 2), 'utf-8'); } catch { /* non-blocking */ }
+          try { writeFileSync(usagePath, JSON.stringify(stored, null, 2), 'utf-8'); } catch {}
         }
       }
-    } catch {
-      // Fail-open — usage capture must never block Stop
-    }
-    // ────────────────────────────────────────────────────────────────────────
+    } catch {}
 
     if (warnings.length === 0) return null;
 

package/framework/hooks/claude-code/core/warn-bash-source-write.js

@@ -1,18 +1,10 @@
 #!/usr/bin/env node
-/**
- * warn-bash-source-write — PreToolUse Bash, warn only: a project source file written
- * by the shell (`writeTargets`) skips every Write/Edit guard (phase folders,
- * protected files, comment-guard). The command still runs.
- */
+// Warn only: a source file written by the shell skips every Write/Edit guard. The command still runs.
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { stateExists } from '../../shared/state-reader.js';
 import { writeTargets } from '../../shared/command-tokens.js';
 import { isProjectSource } from '../../shared/source-files.js';
 
-/**
- * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
- * @returns {Promise<object|null>} additionalContext naming the files, or null
- */
 export async function run(payload) {
   try {
     if (!stateExists()) return null;

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

@@ -1,40 +1,4 @@
 #!/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.
- *
- * 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. The same
- * checkpoint now also rotates `.morph/logs/events.jsonl` (telemetry-logger.js)
- * once IT crosses its own threshold — events.jsonl grew unbounded even after
- * R1.2, since that rotation only ever covered activity.jsonl.
- *
- * 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, resolve } from 'path';
@@ -80,7 +44,6 @@ function gitRevParse(arg, dir) {
     .trim();
 }
 
-/** Feature name from the current branch, if it matches `morph/{feature}`. */
 function featureFromBranch(dir) {
   try {
     const branch = gitRevParse('--abbrev-ref HEAD', dir);
@@ -91,12 +54,6 @@ function featureFromBranch(dir) {
   }
 }
 
-/**
- * Task-isolation worktree (`morph-task/{name}`): the tree a `WorktreeCreate`
- * hook provisions for a parallel sub-agent batch (morph-apply §3b-w) or for a
- * `claude -w` session with no feature behind it. Not a feature — no
- * feature.json, no gates — but it owns a port block and the same junctions.
- */
 function taskFromBranch(dir) {
   try {
     const branch = gitRevParse('--abbrev-ref HEAD', dir);
@@ -107,14 +64,7 @@ function taskFromBranch(dir) {
   }
 }
 
-/**
- * Is this secondary worktree inside the primary root's `worktrees/` (or the
- * legacy `.worktrees/`) container? A tree kept anywhere else — `.claude/
- * worktrees/` from a native Claude Code run before the hook existed, a
- * sibling `../repo-x`, superpowers' `~/.config/...` — was created without
- * morph: no junctions, no ports, invisible to `fleet`. Fail-open: any error
- * reads as "in container" so a healthy tree is never nagged by mistake.
- */
+// Any error reads as "in container" so a healthy tree is never nagged.
 function isOutsideContainer(dir) {
   try {
     const common = resolve(dir, gitRevParse('--git-common-dir', dir)).replace(/\\/g, '/');
@@ -143,7 +93,6 @@ function buildTaskContext(dir, task) {
   return text;
 }
 
-/** 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 })
@@ -154,12 +103,6 @@ function featureFromSingleDir(dir) {
   }
 }
 
-/**
- * Fleet env line: the worktree's allocated port block, read from the manifest
- * `worktree setup` writes. Fail-open — a missing or malformed manifest just
- * omits the line (the session then uses project defaults, which is exactly
- * the pre-fleet behavior).
- */
 function buildEnvLine(dir) {
   try {
     const envPath = join(dir, '.morph', 'worktree.env');
@@ -178,10 +121,6 @@ function buildEnvLine(dir) {
   }
 }
 
-/**
- * Fleet handoff line: point the fresh session at the compressed handoff doc
- * before it starts re-deriving context by hand. Fail-open.
- */
 function buildHandoffLine(dir, feature) {
   try {
     const handoffPath = join(dir, '.morph', 'features', feature, 'handoff.md');
@@ -209,13 +148,7 @@ function buildWorktreeContext(dir, feature) {
   return text;
 }
 
-/**
- * `.morph/framework` is checked alongside the other two because the hook
- * commands resolve to `$CLAUDE_PROJECT_DIR/.morph/framework/hooks/...`: if
- * that junction is missing, `node` finds no file and EVERY guardrail in this
- * worktree is silently dark — the worst failure mode of the lot, and the one
- * the old two-item check could not see.
- */
+// The hook commands resolve through the .morph/framework junction: without it every guardrail here is silently off.
 function buildMissingInfraWarning(dir) {
   const missing = ['node_modules', '.claude', join('.morph', 'framework')]
     .filter((rel) => !existsSync(join(dir, rel)));
@@ -243,20 +176,7 @@ function buildActiveFeatureSummary(dir) {
   return text;
 }
 
-/**
- * Advisory feature ownership (B1): claim the feature this session is about to
- * work on, and — if another session already holds a LIVE claim — say so loudly
- * before any work starts.
- *
- * Never blocks: the claim is a warning, not a lock (see claim-registry.js).
- * The claim is taken regardless, so the registry reflects reality; the operator
- * decides what to do with the collision.
- *
- * Fail-open per FIELD: no git common dir, or any registry error, just means no
- * claim line — never a failed session start.
- *
- * @returns {string} a block to append to the injected context ('' when quiet)
- */
+// Advisory: the claim is taken even on collision; it warns, never locks.
 function claimBlock(dir, feature, sessionId) {
   try {
     const gitCommonDir = resolve(dir, gitRevParse('--git-common-dir', dir));
@@ -274,37 +194,21 @@ function claimBlock(dir, feature, sessionId) {
   }
 }
 
-/**
- * @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 = sessionDir(payload);
-    // The SessionStart payload carries session_id — the identity the claim
-    // registry uses to tell "me" from "another session".
     const sessionId = payload?.session_id || `pid-${process.pid}`;
 
     if (!stateExists(dir)) {
       return null;
     }
 
-    // Rotate the activity + events logs before anything else touches them
-    // this session. Best-effort, never fatal to session start — both rotate*
-    // helpers are themselves fail-open (return false on any error).
-    try { rotateActivityLogIfLarge(dir); } catch { /* non-blocking */ }
-    try { rotateEventsLogIfLarge(dir); } catch { /* non-blocking */ }
-    // Between sessions is where commits made outside the agent (a terminal, an
-    // IDE, a `git pull`) are caught: the detached refresh brings the ROOT's
-    // graph to HEAD — never a worktree's (a detached process holding a
-    // worktree directory made `finish` fail on win32). A worktree that has no
-    // graph yet (created before seeding existed) gets the root's copy here;
-    // from then on it is refreshed by hand (`morph-spec graph refresh`).
-    // Returns immediately — nothing here waits on graphify.
-    try { seedFromPrimary(dir); } catch { /* non-blocking — a no-op on the root */ }
-    try { kickGraphRefresh(dir); } catch { /* non-blocking */ }
-    try { kickAgentReap(dir); } catch { /* non-blocking */ }
+    try { rotateActivityLogIfLarge(dir); } catch {}
+    try { rotateEventsLogIfLarge(dir); } catch {}
+    // Only the ROOT's graph is refreshed in background: a detached process holding a worktree directory made `finish` fail on win32.
+    try { seedFromPrimary(dir); } catch {}
+    try { kickGraphRefresh(dir); } catch {}
+    try { kickAgentReap(dir); } catch {}
 
     if (isSecondaryWorktree(dir)) {
       const task = taskFromBranch(dir);
@@ -313,16 +217,12 @@ export async function run(payload) {
       }
       const feature = featureFromBranch(dir) || featureFromSingleDir(dir);
       if (!feature) {
-        // A tree with no morph identity at all: worth a warning ONLY when it
-        // also lives outside the container — that is the signature of a
-        // worktree created behind morph's back (native tool, raw git, another
-        // skill). Inside the container with no identity → stay silent.
+        // No identity AND outside the container is the signature of a worktree created behind morph's back.
         return isOutsideContainer(dir) ? contextResult(buildOutOfContainerWarning(dir), 'SessionStart') : null;
       }
       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) {
       return null;

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

@@ -1,40 +1,4 @@
 #!/usr/bin/env node
-/**
- * worktree-create.js — WorktreeCreate hook
- *
- * Event: WorktreeCreate (fires for `claude -w`, the EnterWorktree tool, and
- * `Agent isolation:"worktree"` — measured, not assumed).
- *
- * Claude Code's native worktree is a bare `git worktree add` somewhere under
- * `.claude/worktrees/`: no infra junctions (so no hooks run in there), no port
- * block, no identity, invisible to the fleet. When this hook is registered it
- * REPLACES that logic entirely: it must print the path of the tree it created
- * as the last non-empty stdout line and exit 0; any non-zero exit fails the
- * creation. It cannot return JSON — the standalone tail below is therefore
- * NOT `runStandalone` (which prints a JSON verdict). Diagnostics go to stderr.
- *
- * What it does:
- *   1. root = the PRIMARY root of the repo `payload.cwd` is in (never a
- *      secondary worktree — a tree under a tree is the fleet-invisible shape).
- *   2. name → kebab slug (`Bold_Oak` → `bold-oak`, `agent-a1b2` stays).
- *   3. feature or task? `<root>/.morph/features/<n>/feature.json` exists, or
- *      branch `morph/<n>` exists → `morph-spec worktree setup <n>`; otherwise
- *      `morph-spec worktree provision <n> [--base <ref>]`.
- *   4. `worktree.baseRef` from the merged settings (`~/.claude/settings.json`
- *      < `<root>/.claude/settings.json` < `<root>/.claude/settings.local.json`):
- *      `"head"` → the current branch (or sha) of `payload.cwd`; unset and
- *      `payload.cwd` on `morph/<f>` → that feature branch; `"fresh"` or
- *      anything else → the repo's default branch (the CLI's own default).
- *   5. CLI exit 0 or 2 (already exists) → its `path`. Exit 1/3 → error.
- *      CLI unavailable → in-hook git fallback that still lands the tree under
- *      `<root>/worktrees/<n>` on `morph-task/<n>` (degraded: no junctions, no
- *      ports — but never outside the governed directory).
- *
- * `stateExists(root)` gate: outside a morph project (no `.morph/state.json`
- * and no feature.json) there is nothing to govern — the same in-hook git
- * fallback runs, so a non-morph repo with this hook installed still gets a
- * worktree instead of a failed creation.
- */
 
 import { existsSync, mkdirSync, readFileSync } from 'fs';
 import { execFileSync } from 'child_process';
@@ -51,21 +15,16 @@ function git(args, cwd) {
   return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
 }
 
-/**
- * The primary root of the repo containing `startDir`. `git worktree list`'s
- * first entry is the primary checkout, from any worktree; the pure-filesystem
- * common-dir resolver is the no-subprocess fallback. Null outside a repo.
- */
+// `git worktree list`'s first entry is the primary checkout, from any worktree.
 export function resolvePrimaryRoot(startDir) {
   try {
     const first = git(['worktree', 'list', '--porcelain'], startDir).split('\n').find((l) => l.startsWith('worktree '));
     if (first) return fwd(first.slice('worktree '.length).trim());
-  } catch { /* fall through */ }
+  } catch {}
   const common = resolveGitCommonDir(startDir);
   return common ? fwd(dirname(common)) : null;
 }
 
-/** `Bold_Oak` → `bold-oak`; empty → a timestamped slug. */
 export function slugify(name) {
   const slug = String(name || '')
     .toLowerCase()
@@ -79,11 +38,7 @@ function readJsonSafe(path) {
   try { return JSON.parse(readFileSync(path, 'utf8').replace(/^/, '')); } catch { return null; }
 }
 
-/**
- * `worktree.baseRef` across the three settings layers, last one wins.
- * Fail-open per file. `null` when unset — distinct from an explicit `'fresh'`,
- * which overrides the feature-branch default (see `resolveBase`).
- */
+// `null` when unset, distinct from an explicit `'fresh'`, which overrides the feature-branch default.
 export function readBaseRefSetting(root, home = homedir()) {
   let value = null;
   for (const p of [
@@ -98,7 +53,6 @@ export function readBaseRefSetting(root, home = homedir()) {
   return value;
 }
 
-/** The ref `baseRef:"head"` means: the branch checked out in `cwd`, or its sha. */
 function headRef(cwd) {
   try {
     const name = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
@@ -109,14 +63,7 @@ function headRef(cwd) {
   }
 }
 
-/**
- * The base of a task tree. `"head"` → whatever `cwd` has checked out;
- * `"fresh"` (or any other explicit value) → the default branch; unset → the
- * `morph/<f>` branch `cwd` is on, when it is one. A sub-agent dispatched by
- * the apply needs the feature's work, and a tree born from the default branch
- * made every dispatch open with `git merge --ff-only morph/<f>`.
- * `morph-task/*` does not match: a tree of a tree tips at the default.
- */
+// Unset → the `morph/<f>` branch `cwd` is on: a sub-agent tree born from the default branch lacks the feature's work.
 export function resolveBase(setting, cwd) {
   if (setting === 'head') return headRef(cwd);
   if (setting) return null;
@@ -138,17 +85,13 @@ function defaultBranch(root) {
   try {
     const m = git(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], root).match(/^refs\/remotes\/origin\/(.+)$/);
     if (m) return m[1];
-  } catch { /* no origin/HEAD */ }
+  } catch {}
   for (const c of ['main', 'master']) {
-    try { git(['show-ref', '--verify', '--quiet', `refs/heads/${c}`], root); return c; } catch { /* next */ }
+    try { git(['show-ref', '--verify', '--quiet', `refs/heads/${c}`], root); return c; } catch {}
   }
   return null;
 }
 
-/**
- * Degraded path — the CLI is not reachable, but the tree still has to land
- * in the governed directory on the governed branch namespace.
- */
 function gitFallback(root, name, base) {
   const branch = `morph-task/${name}`;
   const container = newWorktreesDir(root);
@@ -164,11 +107,6 @@ function gitFallback(root, name, base) {
   return { path };
 }
 
-/**
- * @param {object} payload - parsed WorktreeCreate stdin payload
- *   ({ session_id, cwd, hook_event_name, name })
- * @returns {Promise<{ path: string }|{ error: string }>}
- */
 export async function run(payload) {
   const start = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const root = resolvePrimaryRoot(start) || (process.env.CLAUDE_PROJECT_DIR ? fwd(resolve(process.env.CLAUDE_PROJECT_DIR)) : null);
@@ -177,8 +115,6 @@ export async function run(payload) {
   const name = slugify(payload?.name);
   const base = resolveBase(readBaseRefSetting(root), start);
 
-  // Outside a morph project there is nothing to govern beyond WHERE the tree
-  // lands — plain git, under <root>/worktrees/.
   if (!stateExists(root)) {
     try { return gitFallback(root, name, base); }
     catch (err) { return { error: `worktree-create: ${err?.message || err}` }; }

package/framework/hooks/claude-code/core/worktree-env-inject.js

@@ -1,34 +1,6 @@
 #!/usr/bin/env node
-/**
- * worktree-env-inject.js — PreToolUse hook (Bash matcher), last link of the
- * Bash chain.
- *
- * `.morph/worktree.env` used to be a manifest nobody executed: SessionStart
- * printed the port block and the model was expected to pass `PORT` by hand
- * every time it started a dev server. Two worktrees whose sessions forgot
- * collided on 3000 — a runtime clash dressed as a broken app. This hook makes
- * the block reach the process deterministically: when the command is a
- * dev-server / compose / spec launcher and the cwd is a worktree that owns a
- * manifest, the command is rewritten to `export K='V' …; <command>` via
- * `updatedInput`, and the rewrite is named in `additionalContext`.
- *
- * Scope is deliberately narrow: only launcher-shaped commands, only when the
- * command does not already set a layout key itself (`PORT=…`, `--port`,
- * `compose -p`), only for the Bash tool. Everything else passes untouched.
- *
- * Second job, same mechanism — the SESSION ANCHOR. `morph-spec finish` and
- * `morph-spec worktree remove` tear a worktree down, and the session that runs
- * them may be ANCHORED in that very worktree: its CLAUDE_PROJECT_DIR is the
- * worktree, and every project hook is `node "$CLAUDE_PROJECT_DIR/.morph/framework/…"`.
- * The CLI cannot see that anchor (the Bash tool does not export
- * CLAUDE_PROJECT_DIR, and `cd <root> && morph-spec finish` erases the cwd), so
- * it unlinked the junction the session's hooks resolve through — and every hook
- * of every later tool call died with MODULE_NOT_FOUND (48 in one real session).
- * Hooks DO see the anchor, so this one exports it as MORPH_SESSION_PROJECT_DIR
- * on those two commands; the CLI then defers the teardown.
- *
- * Fail-open: no state, no manifest, unreadable manifest → null (pass).
- */
+// Launchers get the worktree's port block exported; teardowns get the session anchor, because the CLI cannot see
+// CLAUDE_PROJECT_DIR and tearing down the worktree a session is anchored in kills every later hook (MODULE_NOT_FOUND).
 
 import { existsSync } from 'fs';
 import { join } from 'path';
@@ -36,47 +8,30 @@ import { stateExists } from '../../shared/state-reader.js';
 import { updatedInputResult, runStandalone } from '../../shared/hook-response.js';
 import { loadEnvFile } from '../../shared/e2e-check.js';
 
-/** Commands that start a server or a stack and therefore need the block. */
 const LAUNCHER_RE = /\b(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start)\b|next\s+(?:dev|start)\b|vite\b|dotnet\s+(?:run|watch)\b|docker(?:\s+|-)compose\b|playwright\s+test\b)/;
 
-/** The command already chose its own port/project — respect it. */
 const SELF_CONFIGURED_RE = /(?:^|[\s;&|])(?:PORT|API_PORT|POSTGRES_PORT|COMPOSE_PROJECT_NAME|ASPNETCORE_URLS)=|--port\b|(?:^|\s)-p\s+\d|compose\b[^|;&]*\s-p\s/;
 
-/** POSIX single-quote, safe for Git Bash on Windows too. */
+// POSIX single quote, safe for Git Bash on Windows too.
 function shq(v) {
   return `'${String(v).replace(/'/g, "'\\''")}'`;
 }
 
-/**
- * Pure decision: the rewritten command, or null when nothing should change.
- * @param {string} command
- * @param {Record<string,string>} env - parsed manifest
- * @returns {{ command: string, injected: string[] }|null}
- */
 export function rewriteCommand(command, env) {
   if (!command || !LAUNCHER_RE.test(command)) return null;
   if (SELF_CONFIGURED_RE.test(command)) return null;
   const pairs = Object.keys(env).filter((k) => k !== 'MORPH_FEATURE' && env[k]).map((k) => [k, env[k]]);
   if (!pairs.some(([k]) => k === 'PORT')) return null;
-  // The web tier's URL is what the spec suite needs; derive it once here.
   if (!env.PLAYWRIGHT_BASE_URL) pairs.push(['PLAYWRIGHT_BASE_URL', `http://localhost:${env.PORT}`]);
   const prefix = `export ${pairs.map(([k, v]) => `${k}=${shq(v)}`).join(' ')}; `;
   return { command: prefix + command, injected: pairs.map(([k, v]) => `${k}=${v}`) };
 }
 
-/** `morph-spec finish` / `morph-spec worktree remove` — incl. `node …/morph-spec.js` and `npx morph-spec`. */
+// Also matches `node …/morph-spec.js` and `npx morph-spec`.
 const TEARDOWN_RE = /\bmorph-spec(?:\.js)?\b[^\n;&|]*?\s(?:finish|worktree\s+remove)\b/;
 
 const ANCHOR_KEY = 'MORPH_SESSION_PROJECT_DIR';
 
-/**
- * Pure decision: export the session anchor in front of a teardown command, or
- * null when nothing should change (other command, anchor already declared,
- * no anchor to give).
- * @param {string} command
- * @param {string} anchorDir - the session's project dir (CLAUDE_PROJECT_DIR)
- * @returns {{ command: string, anchor: string }|null}
- */
 export function anchorSessionCommand(command, anchorDir) {
   if (!command || !anchorDir) return null;
   if (!TEARDOWN_RE.test(command)) return null;
@@ -84,10 +39,6 @@ export function anchorSessionCommand(command, anchorDir) {
   return { command: `export ${ANCHOR_KEY}=${shq(anchorDir)}; ${command}`, anchor: anchorDir };
 }
 
-/**
- * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
- * @returns {Promise<object|null>} an updatedInput result, or null (pass).
- */
 export async function run(payload) {
   try {
     if (payload?.tool_name && payload.tool_name !== 'Bash') return null;
@@ -95,9 +46,7 @@ export async function run(payload) {
     const command = payload?.tool_input?.command || '';
     if (!command) return null;
 
-    // CLAUDE_PROJECT_DIR first: it is what the project hooks resolve
-    // `.morph/framework` against — the thing a teardown would pull out from
-    // under this session. The payload cwd is the fallback.
+    // CLAUDE_PROJECT_DIR first: it is what the project hooks resolve `.morph/framework` against.
     const anchored = anchorSessionCommand(command, process.env.CLAUDE_PROJECT_DIR || payload?.cwd || '');
     if (anchored) {
       return updatedInputResult(