@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/framework/hooks/claude-code/core/block-destructive-worktree-removal.js

@@ -6,70 +6,31 @@ import { stateExists } from '../../shared/state-reader.js';
 import { scanForBlockers } from '../../shared/reparse-scan.js';
 import { tokenize } from '../../shared/command-tokens.js';
 
-/**
- * block-destructive-worktree-removal — the only defense that does not depend on
- * someone reading documentation.
- *
- * A morph worktree carries JUNCTIONS to the primary root's shared infra
- * (`node_modules`, `.claude`, `.morph/framework`). Every generic recursive
- * removal — `git worktree remove` (plain AND `--force`), `rm -rf`,
- * `Remove-Item -Recurse`, `rmdir /s` — FOLLOWS those links out of the worktree
- * and deletes what they point at, leaving the primary root's `.claude/` and
- * `.morph/framework/` as empty directories. That is the incident this hook
- * exists for, and it is not hypothetical: it happened, and the command was
- * copied from a message the CLI itself printed.
- *
- * `morph-spec worktree remove` is safe because it drops the junctions BEFORE
- * letting git near the directory. This hook is what stops the unsafe path from
- * being reachable by accident.
- *
- * DELIBERATELY NARROW — an inert or over-eager guardrail is worse than none:
- *   - only recursive-removal shapes, only when a target path can be extracted;
- *   - only when that path exists AND the scan finds reparse points under it
- *     (an already-unlinked worktree, or one that never had junctions, passes);
- *   - anything unparseable passes.
- * The scan is the authority, not the path shape: a worktree kept outside
- * `worktrees/` is protected just the same, and a `worktrees/` directory with
- * nothing to traverse is not blocked for looking dangerous.
- */
+// Generic recursive removals FOLLOW a worktree's junctions and empty the root's `.claude/` and `.morph/framework/`.
+// The reparse scan is the authority, not the path shape; anything unparseable passes.
 
-// The tokenizer lives in shared/command-tokens.js — block-raw-worktree-add.js
-// reads `git worktree add` off the same tokens, and a hook must never import a
-// sibling hook (its standalone tail would fire in the importer's process).
+// A hook never imports a sibling hook (its standalone tail would fire), so the tokenizer lives in shared/.
 export { tokenize };
 
-/**
- * The path a recursive-removal command would destroy, or null when this is not
- * such a command (or the target cannot be read off it).
- *
- * @param {string} command
- * @returns {string|null}
- */
 export function extractRemovalTarget(command) {
   const tokens = tokenize(command);
   if (!tokens.length) return null;
   const lower = tokens.map((t) => t.toLowerCase());
 
-  // `git worktree remove [--force] <path>` — the path is always the last
-  // non-flag token; git has no form of this command without one.
+  // The path is always the last non-flag token.
   const gi = lower.indexOf('git');
   if (gi !== -1 && lower[gi + 1] === 'worktree' && lower[gi + 2] === 'remove') {
     const rest = tokens.slice(gi + 3).filter((t) => !t.startsWith('-'));
     return rest.length ? rest[rest.length - 1] : null;
   }
 
-  // Generic recursive deletes. Each needs BOTH its command word and a recursive
-  // flag — a plain `rm file` or `Remove-Item file` cannot traverse a junction's
-  // contents and is none of this hook's business.
+  // Needs both the command word and a recursive flag: a plain `rm file` cannot traverse a junction.
   const recursive = tokens.some((t) => /^(-[a-z]*r[a-z]*|--recursive|\/s)$/i.test(t));
   const removalCmd = lower.find((t) => /^(rm|remove-item|ri|rd|rmdir|del)$/.test(t));
   if (!removalCmd || !recursive) return null;
 
   const idx = lower.indexOf(removalCmd);
-  // A cmd.exe switch is a slash plus a letter or two (`rmdir /s /q`). Anything
-  // longer that starts with `/` is a POSIX ABSOLUTE PATH — filtering on the
-  // bare `/` made every Linux target look like a flag, so `rm -rf /tmp/wt`
-  // extracted nothing and the hook passed exactly where it had to block.
+  // A cmd.exe switch is a slash plus one or two letters; anything longer is a POSIX absolute path.
   const isCmdSwitch = (t) => /^\/[a-z]{1,2}$/i.test(t);
   const operands = tokens.slice(idx + 1).filter((t) => !t.startsWith('-') && !isCmdSwitch(t));
   // Named-parameter form: `Remove-Item -Path <p> -Recurse`.
@@ -78,10 +39,6 @@ export function extractRemovalTarget(command) {
   return operands.length ? operands[0] : null;
 }
 
-/**
- * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
- * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
- */
 export async function run(payload) {
   try {
     if (!stateExists()) return null;

package/framework/hooks/claude-code/core/block-raw-worktree-add.js

@@ -5,56 +5,23 @@ import { stateExists } from '../../shared/state-reader.js';
 // standalone tail (stdin read + exit) inside THIS process.
 import { tokenize } from '../../shared/command-tokens.js';
 
-/**
- * block-raw-worktree-add — PreToolUse (Bash) guard against `git worktree add`.
- *
- * A worktree created by raw git is a worktree morph cannot see: no infra
- * junctions (`.claude`, `node_modules`, `.morph/framework` — so NO hooks run
- * in there), no port block (its dev server collides with the root's), no
- * feature/task identity (invisible to `fleet`, `doctor --worktrees`,
- * `worktree list`), and a location git chose, not `<root>/worktrees/`. The
- * sibling guard (block-destructive-worktree-removal) protects the way OUT;
- * this one protects the way IN, by naming the two commands that build a
- * governed tree:
- *
- *   morph-spec worktree setup <feature>                — a feature's tree
- *   morph-spec worktree provision <name> [--base <ref>] — a task-isolation tree
- *
- * DELIBERATELY NARROW: only the `add` subcommand. `list`, `prune`, `remove`
- * (the sibling's business), `lock`, `unlock`, `move`, `repair` all pass. The
- * `git` token may be followed by global options (`-C <dir>`, `--git-dir=<d>`,
- * `-c k=v`) before `worktree`, and may sit anywhere in a chained command
- * (`cd a && git worktree add b`) — every `git` occurrence is checked.
- */
-
-/** Global `git` options that take a separate value: `git -C <dir> worktree add`. */
 const GIT_GLOBAL_WITH_VALUE = new Set(['-c', '-C', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env']);
 
-/**
- * Does this command line invoke `git worktree add` anywhere?
- * @param {string} command
- * @returns {boolean}
- */
 export function isRawWorktreeAdd(command) {
   const tokens = tokenize(command);
   const lower = tokens.map((t) => t.toLowerCase());
   for (let i = 0; i < lower.length; i++) {
     if (lower[i] !== 'git' && !/(^|[\\/])git(\.exe)?$/.test(lower[i])) continue;
     let j = i + 1;
-    // Skip global options between `git` and the subcommand.
     while (j < lower.length && lower[j].startsWith('-')) {
-      if (GIT_GLOBAL_WITH_VALUE.has(tokens[j])) j += 2; // `-C dir` consumes its value
-      else j += 1;                                       // `--git-dir=x`, `--no-pager`, …
+      if (GIT_GLOBAL_WITH_VALUE.has(tokens[j])) j += 2;
+      else j += 1;
     }
     if (lower[j] === 'worktree' && lower[j + 1] === 'add') return true;
   }
   return false;
 }
 
-/**
- * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
- * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
- */
 export async function run(payload) {
   try {
     if (!stateExists()) return null;

package/framework/hooks/claude-code/core/chain.js

@@ -1,54 +1,6 @@
 #!/usr/bin/env node
-/**
- * chain.js — roda vários hooks core num único processo node.
- *
- * Motivação (onda de performance R2): cada hook registrado no Claude Code é
- * hoje um processo node próprio (~60ms de cold start). Um único Write/Edit
- * disparava até 9 desses processos — 2 PreToolUse + 3+2+2 PostToolUse. Este
- * script agrupa os elos de um mesmo event+matcher (a mesma entrada do
- * registry em src/utils/hooks-installer.js) num só spawn: lê stdin UMA vez,
- * importa e chama `run(payload)` de cada hook em sequência, e combina as
- * respostas — reduzindo esses 9 spawns para 4 por Write/Edit (1 PreToolUse +
- * 3 PostToolUse: Write|Edit / Write|Edit|AskUserQuestion / matcher-`*`).
- *
- * Uso: `node chain.js <hook1> <hook2> ...` — nomes de arquivo SEM `.js`,
- * resolvidos no mesmo diretório deste script (core/), na ORDEM em que devem
- * rodar. A ordem é a mesma que o registry antigo (duas entries separadas)
- * já implicava — ver o comentário de cada grupo em hooks-installer.js.
- *
- * Cada hook core exporta `run(payload)` (ver framework/hooks/shared/hook-response.js
- * `runStandalone`) — o arquivo continua executável standalone (spawnSync
- * direto, como os testes já fazem) porque a própria cauda do arquivo só lê
- * stdin/imprime/sai quando NÃO está sendo importado por esta cadeia.
- *
- * Regras de combinação:
- *  - PreToolUse (decision:'block'): o PRIMEIRO elo que retornar um bloqueio
- *    VENCE e encerra a cadeia — os elos seguintes nem chegam a rodar. Isto é
- *    uma otimização NOVA desta consolidação (antes, Claude Code podia
- *    disparar os dois processos de qualquer forma); o resultado observável
- *    pro Claude Code é idêntico (o tool call é bloqueado do mesmo jeito).
- *  - PostToolUse / outros eventos de contexto: os textos de TODOS os elos que
- *    retornarem `hookSpecificOutput.additionalContext` (ou `decision:'approve'`
- *    com additionalContext) são concatenados, na ORDEM dos argv, separados por
- *    uma linha em branco — nenhum elo é pulado por um vizinho ter respondido.
- *  - Nome do evento (hookSpecificOutput.hookEventName) no resultado final:
- *    o valor que o PRIMEIRO elo a declarar um venceu (mesma regra de
- *    "primeiro vence" do bloqueio acima — na prática todos os elos de um
- *    mesmo grupo observam o MESMO evento real do Claude Code, então isto só
- *    importa como desempate determinístico); na ausência de qualquer elo
- *    declarando, cai para `payload.hook_event_name`; por último, `'PostToolUse'`.
- *  - updatedInput (PreToolUse): um elo pode devolver
- *    `hookSpecificOutput.updatedInput` (ver `updatedInputResult` em
- *    hook-response.js) para reescrever o tool_input. O ÚLTIMO elo a devolver um
- *    vence (só um elo do grupo reescreve, por construção). `permissionDecision:
- *    'allow'` + `updatedInput` só entram no resultado final quando algum elo
- *    reescreveu — um `allow` incondicional pularia o prompt de permissão de
- *    TODO Bash, que é exatamente o contrário de um guardrail.
- *  - Fail-open POR ELO: uma exceção não tratada por um hook individual (import
- *    falhou, run() não existe, etc.) não derruba a cadeia — os elos seguintes
- *    ainda rodam. Cada hook já fail-opens sozinho dentro do seu próprio
- *    try/catch; isto é a segunda rede de segurança, para o import em si.
- */
+// Usage: node chain.js <hook> ... (names without .js, run in argv order). The first block wins and ends the chain,
+// the contexts of every link concatenate, and an exception in one link never stops the next.
 
 import { dirname, join } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
@@ -56,20 +8,12 @@ import { readStdin } from '../../shared/stdin-reader.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Marca "já estou dentro de uma cadeia" para os hooks importados abaixo: a
-// cauda de execução standalone de cada hook (runStandalone() em
-// hook-response.js) só dispara quando esta flag NÃO está setada. Setada
-// ANTES do primeiro import dinâmico — cada hook importado herda o mesmo
-// process.env deste processo.
+// Set before the first import: each hook's standalone tail runs only when this is unset.
 process.env.MORPH_HOOK_CHAINED = '1';
 
-// Override só para testes da mecânica genérica desta cadeia (fixtures fora
-// de core/, sem precisar ser hooks reais nem satisfazer as convenções que
-// hook-wiring.test.js exige de todo arquivo em core/). Produção nunca seta
-// isto — resolve sempre no próprio diretório deste script.
+// Test-only override; production always resolves next to this script.
 const coreDir = process.env.MORPH_HOOK_CORE_DIR || __dirname;
 
-/** Extrai o texto de contexto de um resultado de hook, se houver. */
 function contextOf(result) {
   if (!result) return null;
   if (result.decision === 'approve' && typeof result.additionalContext === 'string') {
@@ -93,13 +37,11 @@ async function main() {
       const mod = await import(pathToFileURL(join(coreDir, `${name}.js`)).href);
       result = await mod.run(payload);
     } catch {
-      // Fail-open POR ELO — ver doc do módulo acima.
       result = null;
     }
 
     if (!result) continue;
 
-    // PreToolUse: o primeiro bloqueio vence e encerra a cadeia.
     if (result.decision === 'block') {
       // A later link blocking must not swallow what earlier links reported (a tsc error on the same edit).
       if (contexts.length) result = { ...result, reason: [...contexts, result.reason].join('\n\n') };
@@ -116,9 +58,6 @@ async function main() {
     const ctx = contextOf(result);
     if (ctx) {
       contexts.push(ctx);
-      // First link to declare a name wins (mirrors block-first-wins above) —
-      // in practice every link in a group observes the SAME real Claude Code
-      // event, so this only matters as a deterministic tie-break.
       eventName = eventName || result?.hookSpecificOutput?.hookEventName;
     }
   }

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

@@ -1,17 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * PostToolUse Hook: comments the edit added in a shape the
- * `architecture-code-comments` standard never allows.
- *
- * Event: PostToolUse | Matcher: Write|Edit
- *
- * `decision: block` makes the agent fix it in the same turn; the edit itself
- * already landed. Only comments absent from `tool_response.originalFile`
- * count, so editing a legacy file never reports its old comments.
- *
- * Fail-open: any error passes silently.
- */
+// `decision: block` makes the agent fix it in the same turn (the edit already landed). Only comments absent from
+// `tool_response.originalFile` count, so editing a legacy file never reports its old comments.
 
 import { readFileSync } from 'fs';
 import { isAbsolute, relative, resolve } from 'path';
@@ -78,10 +68,6 @@ function describe(file, findings) {
   ].join('\n');
 }
 
-/**
- * @param {object} payload - PostToolUse stdin payload
- * @returns {Promise<object|null>}
- */
 export async function run(payload) {
   try {
     if (!['Write', 'Edit'].includes(payload?.tool_name)) return null;

package/framework/hooks/claude-code/core/enforce-phase-writes.js

@@ -1,22 +1,5 @@
 #!/usr/bin/env node
 
-/**
- * PreToolUse Hook: Enforce Phase-Appropriate File Writes
- *
- * Event: PreToolUse | Matcher: Write|Edit
- *
- * Ensures writes to .morph/features/{feature}/ go to the current phase's subfolder:
- *   plan → only 2-plan/ (and 2-plan/ is writable in every phase: the errata
- *          and plan-check live there)
- *   uiux → only 1-design/
- *   implement → 3-implement/ + any source code (unrestricted)
- *   review → only 4-review/
- *
- * Files outside .morph/features/ are always allowed.
- *
- * Fail-open: exits 0 on any error.
- */
-
 import { existsSync } from 'fs';
 import { stateExists, getFeaturePhase, isGateApproved } from '../../shared/state-reader.js';
 import {
@@ -26,13 +9,7 @@ import {
   PHASE_DIRS
 } from '../../shared/phase-utils.js';
 
-/**
- * The gate that authorizes writing a phase folder's FIRST artifact. Once that
- * gate is approved, the next phase's canonical file may be created even though
- * the phase only advances (via derivation) once that file exists — this is the
- * fix for the forward-transition chicken-and-egg. The plan gate unlocks both
- * the optional `1-design/` and `3-implement/` (the uiux fork).
- */
+// Approving this gate lets the next phase's first file be created: the phase only advances once that file exists.
 const PHASE_DIR_ENTRY_GATE = {
   '1-design': 'plan',
   '3-implement': 'plan',
@@ -44,14 +21,8 @@ import { blockResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 import { getFilePath, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 
-/**
- * @param {object} payload - parsed PreToolUse stdin payload
- * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
- *   Never prints, never exits — see runStandalone()/chain.js at the bottom.
- */
 export async function run(payload) {
   try {
-    // Amend mode: bypass phase write enforcement for legitimate corrections
     if (process.env.MORPH_AMEND_PHASE) {
       console.error(`[morph-spec] AMEND MODE: bypassing phase protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
       return null;
@@ -62,14 +33,9 @@ export async function run(payload) {
     const filePath = getFilePath(payload);
     if (!filePath) return null;
 
-    // Only check files inside .morph/features/
     if (!isFeaturePath(filePath)) return null;
 
-    // Resolve the tree that OWNS this file, NOT the tree the session sits in.
-    // A session rooted in the primary repo may legitimately write to a feature
-    // living in a secondary worktree; reading the session's `.morph/` there
-    // reported the ROOT's phase for the WORKTREE's file and blocked a legal write.
-    // `stateExists` must be asked of that same tree — a worktree carries its own state.
+    // The tree that OWNS the file, not the session's: a root session may write into a worktree's feature.
     const root = resolveMorphRoot(filePath, process.cwd());
     if (!stateExists(root)) return null;
 
@@ -79,28 +45,22 @@ export async function run(payload) {
     const phase = getFeaturePhase(featureName, root);
     if (!phase) return null;
 
-    // During implement phase, all writes are allowed (source code is unrestricted)
-    if (phase === 'implement' || phase === 'sync') return null;
+    if (phase === 'implement') return null;
 
     const targetDir = extractPhaseDir(filePath);
-    if (!targetDir) return null; // File directly in feature root — allow
+    if (!targetDir) return null;
     if (targetDir === ALWAYS_WRITABLE_DIR) return null;
 
     const allowedDir = PHASE_DIRS[phase];
-    if (!allowedDir) return null; // Unknown phase — allow
+    if (!allowedDir) return null;
 
     if (targetDir !== allowedDir) {
-      // Allow editing already-existing files from previous phases
       const absolutePath = resolveTargetPath(filePath, root);
       if (existsSync(absolutePath)) {
         logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
-        return null; // editing existing file — allow
+        return null;
       }
 
-      // Gate-aware forward transition: allow creating the NEXT phase's first
-      // artifact as soon as the gate authorizing that phase is approved. Without
-      // this, the first file of a new phase can never be written (the phase only
-      // advances once that file exists) — the deadlock this hook used to create.
       const entryGate = PHASE_DIR_ENTRY_GATE[targetDir];
       if (entryGate && isGateApproved(featureName, entryGate, root)) {
         // uiux is optional, but once 1-design/ exists its gate is not
@@ -124,9 +84,6 @@ export async function run(payload) {
       }
 
       const phaseLabel = phase.toUpperCase();
-      // Name the tree the verdict came from whenever it is NOT the session's own.
-      // The phase read is per-tree, so "which .morph/ said plan?" is the first
-      // question anyone debugging this asks.
       const treeNote = root !== process.cwd().replace(/\\/g, '/')
         ? `\n(phase read from the tree that owns the file: ${root})`
         : '';
@@ -143,7 +100,6 @@ export async function run(payload) {
     logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
     return null;
   } catch {
-    // Fail-open
     return null;
   }
 }

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

@@ -1,28 +1,5 @@
 #!/usr/bin/env node
-/**
- * gate-guard.js — PostToolUse hook (detect-and-warn, never block)
- *
- * Closes the gap from issue #63: the trust-mode contract lived only in skill
- * pseudocode, with nothing verifying the LLM actually honored it. This hook
- * compares the OBSERVED gate action against the decision the skill persisted
- * to state.json (`features[feature].gateDecisions[gate]`) and injects a
- * non-blocking warning when they disagree.
- *
- * It is a guardrail, NOT an orchestrator (per MORPH.md): it never blocks,
- * never writes state, and fails open on any error or missing data.
- *
- * Two mismatch directions:
- *  - LLM PAUSED (AskUserQuestion on a gate) but the persisted decision said
- *    pause:false  → over-pausing under trust:auto. Warn.
- *  - LLM AUTO-APPROVED (gate became approvedBy:"auto") but the persisted
- *    decision said pause:true → skipped a required human pause. Warn.
- *
- * Observability: every time a gate action is actually checked against a
- * persisted gateDecisions entry, one line lands in the activity log
- * (.morph/logs/activity.json) with result 'coherent' or 'divergent' — so a
- * human can confirm the guard verified coherence instead of absolute silence.
- * No persisted decision, non-gate action, or any error → silence.
- */
+// Detect-and-warn, never block: compares the observed gate action with the persisted gateDecisions.
 
 import { loadState, stateExists, getActiveFeature } from '../../shared/state-reader.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
@@ -35,17 +12,12 @@ function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
 
-/** Feature slug from a `.morph/features/{name}/feature.json` path. */
 function featureFromStatePath(filePath) {
   const fp = String(filePath ?? '').replace(/\\/g, '/');
   return (fp.match(/\.morph\/features\/([^/]+)\/feature\.json$/) ?? [])[1] ?? null;
 }
 
-/**
- * The tree owning an edited gate-state file. `resolveMorphRoot` covers the v5
- * per-feature `feature.json`; the legacy `.morph/state.json` has no feature
- * segment to anchor on, so strip its own suffix instead.
- */
+// The legacy `.morph/state.json` has no feature segment to anchor on, so strip its own suffix.
 function rootOfGateStateFile(filePath, fallback) {
   const abs = resolveTargetPath(filePath, fallback);
   const suffix = '/.morph/state.json';
@@ -53,7 +25,6 @@ function rootOfGateStateFile(filePath, fallback) {
   return resolveMorphRoot(abs, fallback);
 }
 
-/** Every question/header text this AskUserQuestion call surfaced. */
 function askedTexts(input) {
   const texts = [];
   const questions = input.tool_input?.questions;
@@ -75,29 +46,20 @@ function getDecision(state, feature, gate) {
   return d;
 }
 
-/**
- * The LLM just asked a gate question. If the persisted decision said this
- * gate should auto-pass (pause:false), the human was interrupted needlessly.
- */
 function checkAskUserQuestion(input, sessionRoot) {
   for (const text of askedTexts(input)) {
     const gate = gateFromQuestion(text);
     if (!gate) continue;
 
-    // Check the decision of the feature the question NAMES, in its own tree.
-    // Reading the session tree's first in_progress feature made this guard
-    // compare a gate against an unrelated feature's gateDecisions — a warning
-    // about the wrong thing is worse than silence, so an unattributable
-    // question is skipped rather than guessed at (state-sync already tells the
-    // operator when a gate answer could not be attributed).
+    // Only the feature the question NAMES: a warning about the wrong feature is worse than silence.
     const located = locateFeatureForQuestion(text, sessionRoot);
     if (!located) continue;
     const { name: feature, root: cwd } = located;
-    if (!stateExists(cwd)) continue; // fail-open
+    if (!stateExists(cwd)) continue;
 
     const state = loadState(cwd);
     const decision = getDecision(state, feature, gate);
-    if (!decision) continue; // no persisted decision → nothing to verify
+    if (!decision) continue;
     if (decision.pause === false) {
       logHookActivity('gate-guard', 'PostToolUse', 'divergent', cwd);
       return contextResult(
@@ -110,34 +72,24 @@ function checkAskUserQuestion(input, sessionRoot) {
         'PostToolUse'
       );
     }
-    // The decision said pause:true and the LLM did pause — coherent.
     logHookActivity('gate-guard', 'PostToolUse', 'coherent', cwd);
     return null;
   }
   return null;
 }
 
-/** True for edits to .morph/state.json (legacy) or a per-feature feature.json (v5). */
 function isGateStateFile(filePath) {
   const fp = String(filePath ?? '').replace(/\\/g, '/');
   if (fp.endsWith('.morph/state.json')) return true;
   return fp.includes('.morph/features/') && fp.endsWith('/feature.json');
 }
 
-/**
- * The LLM just edited gate state (state.json legacy, or the authoritative
- * feature.json in v5). If a gate flipped to approvedBy:"auto" but the
- * persisted decision said pause:true, a required human pause was skipped.
- */
 function checkStateEdit(input, sessionRoot) {
   const filePath = input.tool_input?.file_path;
   if (!isGateStateFile(filePath)) return null;
 
-  // The edited file names its own tree — and, for the v5 per-feature
-  // feature.json, its own feature. Only the legacy `.morph/state.json` shape
-  // still needs a most-recently-updated fallback within that tree.
   const cwd = rootOfGateStateFile(filePath, sessionRoot);
-  if (!stateExists(cwd)) return null; // fail-open
+  if (!stateExists(cwd)) return null;
   const state = loadState(cwd);
   if (!state) return null;
   const feature = featureFromStatePath(filePath) || getActiveFeature(cwd)?.name;
@@ -168,22 +120,12 @@ function checkStateEdit(input, sessionRoot) {
   return null;
 }
 
-/**
- * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit|AskUserQuestion)
- * @returns {Promise<object|null>} a hookSpecificOutput warning on a
- *   trust-mode divergence, or null (pass/silent).
- */
 export async function run(payload) {
-  // Starting point only — each branch resolves the tree it actually inspects
-  // (from the edited path, or from the feature the question names).
   const sessionRoot = projectDir();
 
   const input = payload || {};
   const toolName = input.tool_name;
 
-  // Short-circuit before loading state: a Write/Edit only matters if it
-  // touched gate state (state.json legacy, or the v5 per-feature
-  // feature.json). Skip the disk read for unrelated edits.
   if (toolName === 'Edit' || toolName === 'Write') {
     if (!isGateStateFile(input.tool_input?.file_path)) return null;
   } else if (toolName !== 'AskUserQuestion') {
@@ -193,9 +135,7 @@ export async function run(payload) {
   try {
     if (toolName === 'AskUserQuestion') return checkAskUserQuestion(input, sessionRoot);
     return checkStateEdit(input, sessionRoot);
-  } catch {
-    // fail-open
-  }
+  } catch {}
   return null;
 }
 

package/framework/hooks/claude-code/core/graph-refresh-kick.js

@@ -1,20 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * PostToolUse Hook: dispara o refresh do grafo de codebase
- *
- * Event: PostToolUse | Matcher: none (elo da cadeia de todos os tools)
- *
- * Depois de um comando de shell — Bash ou PowerShell, que no Windows é o shell
- * principal do Claude Code — que chama git, gh ou morph-spec, solta o refresh
- * do grafo da RAIZ em background (framework/hooks/shared/graph-refresh.js) e
- * volta na hora. O filtro é largo de propósito: o refresh só roda quando o
- * grafo da raiz está atrás do HEAD, então um `git status` custa um processo
- * que sai sem fazer nada — e um comando que move o HEAD sem ser reconhecido é
- * exatamente como o grafo ficou 85 commits atrás.
- *
- * Silencioso e fail-open: nunca injeta contexto, nunca bloqueia.
- */
+// Wide filter on purpose: the refresh only runs when the root's graph is behind HEAD, and a HEAD-moving command
+// left unrecognized is how the graph falls behind.
 
 import { stateExists } from '../../shared/state-reader.js';
 import { runStandalone } from '../../shared/hook-response.js';
@@ -24,20 +11,12 @@ import { kickGraphRefresh } from '../../shared/graph-refresh.js';
 const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);
 const GIT_TOOL = /(^|[\\/])(git|gh|morph-spec)(\.exe|\.cmd)?$/i;
 
-/**
- * @param {string} command
- * @returns {boolean} o comando chama git, gh ou morph-spec em algum ponto
- */
 export function touchesGit(command) {
   return tokenize(command)
     .flatMap((t) => t.split(/[;&|()]+/))
     .some((t) => GIT_TOOL.test(t));
 }
 
-/**
- * @param {object} payload - PostToolUse stdin payload
- * @returns {Promise<null>}
- */
 export async function run(payload) {
   try {
     if (!SHELL_TOOLS.has(payload?.tool_name)) return null;
@@ -45,7 +24,7 @@ export async function run(payload) {
     const dir = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
     if (!stateExists(dir)) return null;
     kickGraphRefresh(dir);
-  } catch { /* fail-open */ }
+  } catch {}
   return null;
 }
 

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

@@ -1,20 +1,7 @@
 #!/usr/bin/env node
-/**
- * heavy-gate.js — PreToolUse hook (Bash matcher), link of the Bash chain before worktree-env-inject.
- *
- * A sub-agent that runs `dotnet build` or `npm test` straight through Bash bypasses the heavy-node
- * semaphore that `morph-spec verify` respects. With `heavy.gateBash: true` this hook takes a slot
- * before such a command runs and `heavy-release` gives it back on Post/PostFailure, matched by
- * `tool_use_id`. It never rewrites the command: a rewrite would be judged against the user's
- * permission rules in its rewritten form, and would auto-approve what the prompt would have asked.
- *
- * A slot taken here has no live process to watch — the hook exits at once — so it lapses by TTL
- * (the call's own timeout plus slack). A call refused by a permission rule or interrupted by the
- * user fires no Post hook and keeps its slot until then.
- *
- * Waits below the platform's 600 s hook timeout, because a timed-out PreToolUse hook lets the call
- * run: the refusal has to come from here. Fail-open otherwise.
- */
+// Never rewrites the command: a rewrite would be judged against the user's permission rules in its rewritten form.
+// The lease has no live pid (the hook exits at once), so it lapses by TTL; a call that fires no Post hook holds it until then.
+// The wait stays under the 600 s hook timeout because a timed-out PreToolUse hook lets the call run.
 
 import { stateExists } from '../../shared/state-reader.js';
 import { blockResult, runStandalone } from '../../shared/hook-response.js';
@@ -22,11 +9,6 @@ import { heavyKind, leaseTtlMs } from '../../shared/heavy-command.js';
 
 const HOOK_BUDGET_SEC = 540;
 
-/**
- * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
- * @param {{ env?: object, acquire?: Function }} [deps] - test seams; production passes none
- * @returns {Promise<object|null>} a block result when no slot came free, else null (pass)
- */
 export async function run(payload, deps = {}) {
   try {
     if (payload?.tool_name && payload.tool_name !== 'Bash') return null;