@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

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;

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

@@ -1,21 +1,10 @@
 #!/usr/bin/env node
-/**
- * heavy-release.js — PostToolUse / PostToolUseFailure link: gives back the slot `heavy-gate` took
- * for this Bash call, matched by `tool_use_id`.
- *
- * Silent and fail-open. A call that fires neither event (refused by a rule, interrupted) leaves its
- * slot to the TTL. Releasing is not deciding, so this link is safe in the async failure binding.
- */
+// A call that fires neither Post event leaves its slot to the TTL. Releasing is not deciding, so this link is safe async.
 
 import { existsSync } from 'node:fs';
 import { stateExists } from '../../shared/state-reader.js';
 import { runStandalone } from '../../shared/hook-response.js';
 
-/**
- * @param {object} payload - PostToolUse or PostToolUseFailure stdin payload
- * @param {{ env?: object }} [deps] - test seam
- * @returns {Promise<null>}
- */
 export async function run(payload, deps = {}) {
   try {
     if (payload?.tool_name !== 'Bash' || !payload.tool_use_id) return null;
@@ -27,7 +16,7 @@ export async function run(payload, deps = {}) {
     if (!existsSync(dir)) return null;
     const { releaseLeaseById } = await import('../../shared/heavy-slots.js');
     releaseLeaseById(dir, payload.tool_use_id);
-  } catch { /* fail-open */ }
+  } catch {}
   return null;
 }
 

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

@@ -1,19 +1,5 @@
 #!/usr/bin/env node
 
-/**
- * PostToolUse Hook: Loop Detection
- *
- * Event: PostToolUse | Matcher: none (all tools)
- *
- * Detects when an agent is stuck in a repetitive loop by tracking
- * the last 15 actions. If the last 8 actions have <= 2 unique
- * signatures, injects a warning with escape instructions.
- *
- * Cooldown: 5 minutes between warnings to prevent meta-loop.
- *
- * Fail-open: exits 0 on any error.
- */
-
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { stateExists } from '../../shared/state-reader.js';
@@ -24,13 +10,8 @@ import { logEvent } from '../../shared/activity-logger.js';
 const MAX_BUFFER = 15;
 const LOOP_WINDOW = 8;
 const MAX_UNIQUE_SIGS = 2;
-const COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+const COOLDOWN_MS = 5 * 60 * 1000;
 
-/**
- * @param {object} payload - parsed PostToolUse stdin payload (any tool)
- * @returns {Promise<object|null>} a hookSpecificOutput loop warning, or null
- *   (pass/silent).
- */
 export async function run(payload) {
   try {
     if (!stateExists()) return null;
@@ -43,7 +24,6 @@ export async function run(payload) {
 
     mkdirSync(memoryDir, { recursive: true });
 
-    // Read existing buffer
     let buffer = [];
     try {
       if (existsSync(bufferPath)) {
@@ -54,19 +34,15 @@ export async function run(payload) {
       buffer = [];
     }
 
-    // Append current action
     const sig = getCommandSignature(payload);
     buffer.push({ sig, ts: new Date().toISOString() });
 
-    // Trim to max size (FIFO)
     if (buffer.length > MAX_BUFFER) {
       buffer = buffer.slice(-MAX_BUFFER);
     }
 
-    // Save updated buffer
     writeFileSync(bufferPath, JSON.stringify(buffer), 'utf-8');
 
-    // Check for loop (need at least LOOP_WINDOW actions)
     if (buffer.length < LOOP_WINDOW) return null;
 
     const recent = buffer.slice(-LOOP_WINDOW);
@@ -74,18 +50,14 @@ export async function run(payload) {
 
     if (uniqueSigs.size > MAX_UNIQUE_SIGS) return null;
 
-    // Check cooldown
     try {
       if (existsSync(cooldownPath)) {
         const cooldown = JSON.parse(readFileSync(cooldownPath, 'utf-8'));
         const elapsed = Date.now() - new Date(cooldown.lastDetected).getTime();
         if (elapsed < COOLDOWN_MS) return null;
       }
-    } catch {
-      // Ignore corrupt cooldown — proceed with detection
-    }
+    } catch {}
 
-    // Loop detected — set cooldown and warn
     writeFileSync(cooldownPath, JSON.stringify({ lastDetected: new Date().toISOString() }), 'utf-8');
 
     logEvent('loop_detected', { signatures: uniqueSigs.size }, process.cwd());
@@ -102,7 +74,6 @@ export async function run(payload) {
       'PostToolUse'
     );
   } catch {
-    // Fail-open
     return null;
   }
 }

package/framework/hooks/claude-code/core/pre-bash-denylist.js

@@ -38,10 +38,6 @@ export function matchesExecutableRule(command, rule) {
   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/protect-spec-files.js

@@ -1,22 +1,5 @@
 #!/usr/bin/env node
 
-/**
- * PreToolUse Hook: Protect Approved Spec Files
- *
- * Event: PreToolUse | Matcher: Write|Edit
- *
- * Blocks Write/Edit to spec artifacts after their approval gate has passed:
- *   - 2-plan/plan.md → after 'plan', only an append under `## Errata`
- *   - 2-plan/checks.json → never by hand: `morph-spec plan-check` is its only writer
- *   - 1-design/design-system.md, etc. → after 'uiux', only an errata append
- *
- * A gate freezes the APPROVED ARTIFACT, so a protected file that does not yet
- * exist on disk is a CREATION and passes — the criterion is the file's
- * existence, never who signed the gate (see the carve-out in run()).
- *
- * Fail-open: exits 0 on any error.
- */
-
 import { existsSync, readFileSync } from 'fs';
 import { stateExists, isGateApproved } from '../../shared/state-reader.js';
 import {
@@ -32,10 +15,6 @@ import { ERRATA_HEADING, errataViolation } from '../../shared/errata.js';
 
 const CHECKS_FILE = 'checks.json';
 
-/**
- * Texto proposto para um arquivo totalmente travado, a partir de Write ou Edit.
- * @returns {string|null} null quando o payload não permite reconstruir (fail-open).
- */
 function proposedText(payload, toolName, original) {
   if (toolName === 'Edit') {
     const oldStr = payload?.tool_input?.old_string;
@@ -49,14 +28,8 @@ function proposedText(payload, toolName, original) {
   return typeof content === 'string' ? content : null;
 }
 
-/**
- * @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 spec protection for legitimate in-implementation corrections
     if (process.env.MORPH_AMEND_PHASE) {
       console.error(`[morph-spec] AMEND MODE: bypassing spec protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
       return null;
@@ -67,14 +40,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;
 
-    // The gate that locks this file is recorded in the feature.json of the tree
-    // that OWNS it. Asking the session's tree instead made this guard go DARK in
-    // a secondary worktree: the root had no approved gate, so a post-Gate-2
-    // plan.md rewrite sailed through. Same defect as enforce-phase-writes,
-    // opposite direction — there it over-blocked, here it under-protected.
+    // The gate lives in the feature.json of the tree that OWNS the file: asking the session's tree left this guard dark in a worktree.
     const root = resolveMorphRoot(filePath, process.cwd());
     if (!stateExists(root)) return null;
 
@@ -84,12 +52,10 @@ export async function run(payload) {
     const filename = getBasename(filePath);
     const requiredGate = PROTECTED_SPEC_FILES[filename];
 
-    // Not a protected file
     if (!requiredGate) return null;
 
-    // Only plan-check writes checks.json; a hand-written one would carry
-    // checks the parser never judged. Decided before the creation carve-out:
-    // chore/hotfix are born with the plan gate stamped.
+    // Generated only by the CLI: a hand-written one would carry checks the parser never judged.
+    // Decided before the creation carve-out, since chore/hotfix are born with the plan gate stamped.
     if (filename === CHECKS_FILE) {
       logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
       return blockResult(
@@ -100,53 +66,28 @@ export async function run(payload) {
       );
     }
 
-    // Gate not yet approved — allow editing
     if (!isGateApproved(featureName, requiredGate, root)) {
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
       return null;
     }
 
-    // ── Gate approved — file is locked ──────────────────────────────────────
     const absPath = resolveTargetPath(filePath, root);
 
-    // Um gate aprovado congela o ARTEFATO APROVADO. Se o arquivo ainda não
-    // existe no disco, não há artefato aprovado a proteger: isto é a CRIAÇÃO
-    // inicial, não a edição de uma spec fechada. O caso é real e não é raro —
-    // `chore`/`hotfix` nascem com `plan` carimbado `policy:{tipo}`
-    // (create.js → work-types.js skippedGates), então o primeiro `Write` de
-    // `2-plan/plan.md` já chega aqui com o gate "aprovado" sem que humano
-    // nenhum tenha aprovado coisa alguma — e era barrado com uma mensagem
-    // mandando revogar o gate de um arquivo inexistente.
-    //
-    // O critério é a EXISTÊNCIA, nunca o `approvedBy`. Liberar por assinatura
-    // (`policy:` passa, `lucas` não) transformaria este carve-out em licença
-    // para reescrever qualquer spec aprovada: bastaria apagá-la antes. Por ser
-    // sobre o disco, a janela fecha sozinha no instante em que o arquivo
-    // existe — os contra-canários de test/hooks/protect-spec-files.test.js
-    // pinam exatamente isso.
-    // O `result` distinto no log é o que torna a criação observável.
+    // A file not yet on disk is its CREATION (chore/hotfix are born with `plan` stamped), not an edit of a frozen spec.
+    // The criterion is existence, never `approvedBy`: by signature, deleting a spec first would license rewriting it.
     if (!existsSync(absPath)) {
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok:absent');
       return null;
     }
 
-    // ── Arquivo totalmente travado (plan.md, design) ────────────
-    // O corpo continua congelado. A ÚNICA passagem é a errata append-only:
-    // corpo byte-idêntico + texto novo sob `## Errata` no fim. Qualquer falha
-    // de leitura/reconstrução cai no bloqueio: a regra base é "não se edita".
-    //
-    // O arquivo EXISTE neste ponto — a inexistência foi decidida lá em cima, e
-    // é a única coisa que este catch NÃO significa mais. ENOENT tratado como
-    // "ilegível" era o defeito F14; "ilegível de verdade" continua bloqueando.
+    // The only way through is the append-only errata; any read or rebuild failure falls into the block.
     const toolName = getToolName(payload);
     let errataCheck = null;
     try {
       const original = readFileSync(absPath, 'utf-8');
       const proposed = proposedText(payload, toolName, original);
       if (proposed !== null) errataCheck = errataViolation(original, proposed);
-    } catch {
-      // arquivo ilegível → sem errata possível, segue para o bloqueio
-    }
+    } catch {}
 
     if (errataCheck?.ok) {
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
@@ -165,7 +106,6 @@ export async function run(payload) {
       `edite, rode plan-check quando for o plan.md, e re-apresente o gate para aprovação.`
     );
   } catch {
-    // Fail-open
     return null;
   }
 }