@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

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;
   }
 }

package/framework/hooks/claude-code/core/state-sync.js

@@ -1,15 +1,4 @@
 #!/usr/bin/env node
-/**
- * state-sync.js — PostToolUse hook
- *
- * Keeps .morph/state.json in sync with the agent's actions, without requiring
- * the agent to think about state. Fail-open: any error returns {} silently.
- *
- * Triggers:
- *  - Write/Edit of .morph/features/{feature}/2-plan/plan.md          → register feature
- *  - Write/Edit of .morph/features/{feature}/{phase}/{output}        → mark output created
- *  - AskUserQuestion answered with option starting "aprovado"        → advance gate
- */
 
 import { existsSync } from 'fs';
 import { join } from 'path';
@@ -27,7 +16,7 @@ import {
 
 const PHASE_FOLDERS = {
   '1-design': 'design',
-  '1-ui': 'uiux', // legacy alias — still recognized during folder transition
+  '1-ui': 'uiux', // legacy alias
   '2-plan': 'plan',
   '3-implement': 'implement',
   '4-review': 'review',
@@ -62,8 +51,6 @@ function registerFeatureIfMissing(state, featureName) {
   if (!state.features) state.features = {};
   if (state.features[featureName]) return false;
 
-  // Canonical object-form gates (incl. optional uiux) + stamped identity
-  // (name=slug, workType, createdAt) — no anonymous shell, no boolean drift.
   state.features[featureName] = createDefaultFeature(featureName);
   return true;
 }
@@ -94,9 +81,7 @@ function isApprovalAnswer(answer) {
   );
 }
 
-// Gate monotonicity — mirror of src/core/state/gate-order.js (hooks are
-// installed standalone and cannot import from src/). Keep in sync:
-// plan first; uiux and review require plan.
+// Mirror of src/core/state/gate-order.js: hooks are installed standalone and cannot import src/.
 const GATE_PREREQ = { plan: [], uiux: ['plan'], review: ['plan'] };
 function unmetGatePrereqs(gate, gates) {
   const isApproved = (g) => gates?.[g]?.approved === true || gates?.[g] === true;
@@ -108,9 +93,7 @@ function handleWriteEdit(input, sessionRoot) {
   const featureName = extractFeatureName(filePath);
   if (!featureName) return false;
 
-  // Sync the tree that OWNS the written file. Syncing the session's tree
-  // instead registered the feature (and its outputs) in the wrong `.morph/`
-  // whenever a root-rooted session wrote into a secondary worktree.
+  // Sync the tree that OWNS the written file: a root session also writes into worktrees.
   const cwd = resolveMorphRoot(filePath, sessionRoot);
   if (!stateExists(cwd)) return false;
 
@@ -125,8 +108,6 @@ function handleWriteEdit(input, sessionRoot) {
   }
 
   if (changed) {
-    // Persist the touched feature to its authoritative feature.json and refresh
-    // the thin root index. The feature's state thus travels in its own folder.
     persistFeature(featureName, state.features[featureName], cwd);
   }
   return true;
@@ -142,22 +123,11 @@ function handleAskUserQuestion(input, sessionRoot) {
     const gate = gateFromQuestion(question);
     if (!gate) continue;
 
-    // Attribute the approval to the feature the QUESTION names, in the tree
-    // that owns it — never to "the first in_progress feature of whatever tree
-    // the session sits in", which is how a Gate 2 for one feature was stamped
-    // onto `export-hub`, leaving it with G2 approved and G1 never asked.
+    // The feature the QUESTION names, in the tree that owns it — never the session tree's first in-progress feature.
     const located = locateFeatureForQuestion(question, sessionRoot);
     if (!located) {
-      // Refuse to guess. A gate on the wrong feature inverts gate order and
-      // invites a second stamp on the real owner; writing nothing costs one
-      // explicit remediation step.
-      //
-      // The remediation differs by WHY it refused. When the question names a
-      // specific slug that no known tree has registered (a hotfix gate asked
-      // before `create` ran — the case that used to fall through to "the
-      // tree's one feature"), `morph-spec approve <that-name> <gate>` is a
-      // dead end: approve.js does `getFeature()` and hard-refuses "Feature
-      // not found". Name the real fix instead of the wrong command.
+      // Refuse to guess: a gate on the wrong feature inverts gate order. For an unregistered slug
+      // `approve` is a dead end ("Feature not found"), so the remediation names `create`.
       const allNames = allWorkTrees(sessionRoot).flatMap((r) => featureNamesIn(r));
       const candidate = unrecognizedSlugLike(question, allNames);
       const remediation = candidate
@@ -176,20 +146,14 @@ function handleAskUserQuestion(input, sessionRoot) {
     const { name: featureName, root } = located;
     if (!stateExists(root)) continue;
 
-    // Prefer the authoritative feature.json; fall back to loadState's merged
-    // view so a feature carried only by the thin index still reports its real
-    // gates (otherwise every predecessor reads as unapproved and the
-    // out-of-order warning below fires on a perfectly ordered approval).
+    // Fallback to the merged view: a feature only in the thin index would read every predecessor as unapproved.
     const feature = readFeatureFile(featureName, root) || loadState(root)?.features?.[featureName];
     const gates = feature?.approvalGates;
     const existing = gates?.[gate];
     const alreadyApproved = existing === true || existing?.approved === true;
     if (alreadyApproved) continue;
 
-    // Gate monotonicity: fail-open. The human said "aprovado", so we DO approve
-    // (never block a human in the loop), but if a predecessor gate is still
-    // pending we surface a non-blocking warning — the CLI `morph-spec approve`
-    // hard-refuses the same shape; here we alert so the operator can reconcile.
+    // Out of order still approves (never block a human in the loop); `morph-spec approve` refuses the same shape.
     const unmet = unmetGatePrereqs(gate, gates);
     if (unmet.length) {
       warnings.push(
@@ -199,13 +163,7 @@ function handleAskUserQuestion(input, sessionRoot) {
       );
     }
 
-    // An "aprovado" answer to AskUserQuestion is a human approving in the loop.
-    // Route through the shared canonical gate writer so the hook and the CLI
-    // (`morph-spec approve`) produce one consistent shape
-    // ({ approved, timestamp, approvedBy }) in the authoritative feature.json —
-    // and a manual approval stays distinguishable from a policy auto-approval.
-    // Same contract as `approve`'s --self-assessed: a human may ship Gate 3 without the
-    // independent review reports, but the degradation is stamped, never silent.
+    // Same contract as `approve --self-assessed`: approving review without its reports is stamped, never silent.
     const selfAssessed = gate === 'review' && feature?.workType !== 'hotfix'
       && ['verifier.md', 'reviewer.md'].some((f) => !existsSync(join(root, '.morph', 'features', featureName, '4-review', f)));
     if (selfAssessed) {
@@ -219,19 +177,9 @@ function handleAskUserQuestion(input, sessionRoot) {
   return warnings.length ? warnings.join('\n') : null;
 }
 
-/**
- * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit|AskUserQuestion)
- * @returns {Promise<object|null>} a hookSpecificOutput warning on a gate
- *   order/attribution violation, or null (pass/silent).
- */
 export async function run(payload) {
   try {
-    // The SESSION's root. It is only a starting point: which `.morph/` actually
-    // gets read and written is decided per event — by the target path for
-    // Write/Edit, by the feature the question names for AskUserQuestion. The
-    // `stateExists` gate therefore moved into each handler, against the tree that
-    // handler resolved; gating on the session's tree up here would skip work that
-    // belongs to a worktree (and, worse, silently pass it to the wrong one).
+    // Only a starting point: each handler resolves the tree it reads and writes, so the stateExists gate lives there.
     const sessionRoot = projectDir();
 
     const input = payload || {};
@@ -244,12 +192,8 @@ export async function run(payload) {
       } else if (toolName === 'AskUserQuestion') {
         warning = handleAskUserQuestion(input, sessionRoot);
       }
-    } catch {
-      // fail-open
-    }
+    } catch {}
 
-    // A non-blocking order-violation warning is surfaced as injected context
-    // (hookSpecificOutput.additionalContext); everything else stays silent.
     return warning ? contextResult(warning, 'PostToolUse') : null;
   } catch {
     return null;

package/framework/hooks/claude-code/core/telemetry-log.js

@@ -1,41 +1,5 @@
 #!/usr/bin/env node
 
-/**
- * Telemetry Hook: harness execution-path capture
- *
- * Events: PostToolUse + PostToolUseFailure (all tools), PostToolBatch,
- * SubagentStop, UserPromptSubmit
- *
- * morph-spec is a Natural Language Harness: there is no central runtime to
- * instrument — Claude Code executes the skills and sub-agents. The only
- * vantage points are hooks. This one is the generic capture point: every tool
- * call and every user prompt is appended (one JSON line) to
- * .morph/logs/events.jsonl, from which `morph-spec telemetry` and
- * `morph-spec cost` reconstruct the path and measure it.
- *
- * Correlation is by an EXPLICIT key (feature + phase) written into each event,
- * not by ambient span context — hooks fire as separate node processes with no
- * shared trace context. `sessionId` and `agentId` (present only inside a
- * sub-agent) separate the orchestrator from the sub-agents it dispatched.
- *
- * PostToolUse fires only when a tool SUCCEEDS; a Bash command that exits
- * non-zero fires PostToolUseFailure instead. Only the exit code parsed from
- * its `error` first line is kept — the rest of `error` is the command's
- * output, where a secret value can appear with no name beside it.
- *
- * SINK RESOLUTION: the event is appended to the `.morph/` tree that OWNS the
- * tool's target file — the tree of its `.morph/features/` segment
- * (`resolveMorphRoot`), else the nearest morph tree above the file; tools with
- * no file path sink on the nearest morph tree above the payload's `cwd`, so a
- * sub-agent working in a worktree logs its Bash calls next to its Reads and
- * Writes. The feature is the tree's BINDING (`morph/<f>` branch, then
- * `MORPH_FEATURE` in `.morph/worktree.env`) before its most recent active
- * feature; a bound feature with no `feature.json` in that tree keeps phase null.
- *
- * SILENT: never blocks, never injects context — only appends. Fail-open on any
- * error (exit 0). Only active inside a morph project (stateExists gate).
- */
-
 import { statSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { dirname, join } from 'path';
 import { stateExists, getActiveFeature, derivePhaseForFeature } from '../../shared/state-reader.js';
@@ -51,10 +15,7 @@ function normalize(p) {
   return (p || '').replace(/\\/g, '/');
 }
 
-// A multi-KB prompt or command written verbatim on every call dominates the
-// per-line cost. The ORIGINAL length travels in a sibling `<field>Chars` key,
-// which `morph-spec cost` prefers over the truncated string's own length —
-// a contract with the telemetry reader: do not rename either half.
+// The original length travels in a sibling `<field>Chars` key that `morph-spec cost` prefers: do not rename either half.
 const MAX_FIELD_CHARS = 2000;
 const TRUNCATE_SUFFIX = '…[truncado]';
 
@@ -64,13 +25,7 @@ const DEFAULT_READ_LINES = 2000;
 const MAX_SLICE_BYTES = 10 * 1024 * 1024;
 const BINARY_READ = /\.(png|jpe?g|gif|webp|bmp|ico|pdf)$/i;
 
-/**
- * Redact, then cap a free-text field, reporting its original length. Redacting
- * first keeps a token cut at the cap from surviving as a recognizable prefix.
- *
- * @param {string} value
- * @returns {{ value: string, chars: number }}
- */
+// Redact before capping: a token cut at the cap would survive as a recognizable prefix.
 function capField(value) {
   const str = typeof value === 'string' ? value : '';
   const clean = redactSecrets(str);
@@ -78,15 +33,11 @@ function capField(value) {
   return { value: clean.slice(0, MAX_FIELD_CHARS) + TRUNCATE_SUFFIX, chars: str.length };
 }
 
-/**
- * Classify a Read target into the telemetry `kind` taxonomy — a contract with
- * src/lib/telemetry/telemetry-reader.js, so these values are pinned. Specific
- * categories first, 'code' last.
- */
+// The `kind` values are a contract with src/lib/telemetry/telemetry-reader.js.
 function classifyReadKind(target) {
   const t = (target || '').toLowerCase();
 
-  if (t.includes('evals/review-checklist')) return 'rubric';
+  if (t.includes('evals/review-checklist')) return 'checklist';
   if (t.includes('standards/')) return 'standard';
   if (t.endsWith('skill.md') || t.includes('/skills/')) return 'skill';
   if (t.split('/').pop() === 'agents.json') return 'agents';
@@ -107,7 +58,6 @@ function classifyReadKind(target) {
   return 'code';
 }
 
-/** Nearest directory at or above `dir` that is a morph project; `fallback` when none. */
 function morphRootAbove(dir, fallback) {
   if (!dir) return fallback;
   let current = normalize(dir);
@@ -122,12 +72,7 @@ function morphRootAbove(dir, fallback) {
 
 const FEATURE_NAME = /^[A-Za-z0-9._-]+$/;
 
-/**
- * The feature the TREE is bound to, before any guess from its state: the
- * branch `morph/<f>` checked out there, then `MORPH_FEATURE` in its
- * `.morph/worktree.env` (a task worktree sits on `morph-task/<n>`). Without
- * it, a sub-agent's worktree reported the root's most recent active feature.
- */
+// Branch binding before state: otherwise a sub-agent's worktree reports the root's most recent active feature.
 async function boundFeature(root) {
   const fromBranch = morphBranchFeature(root);
   if (fromBranch) return fromBranch;
@@ -143,10 +88,6 @@ function featureFromPath(target) {
   return m ? m[1] : null;
 }
 
-/**
- * What a Read actually put in context: the requested line window, not the
- * whole file. Binary reads (images, PDFs) go in whole.
- */
 function readSliceBytes(absPath, input, size) {
   if (BINARY_READ.test(absPath)) return size;
   if (size > MAX_SLICE_BYTES) return undefined;
@@ -157,7 +98,7 @@ function readSliceBytes(absPath, input, size) {
   return Buffer.byteLength(lines.slice(offset - 1, offset - 1 + limit).join('\n'), 'utf-8');
 }
 
-/** Exit code and outcome of a finished tool call, without keeping its output. */
+// Only the exit code is kept: the rest of `error` is command output, where a secret can appear with no name beside it.
 function outcomeOf(payload, input) {
   if (payload.hook_event_name === 'PostToolUseFailure') {
     const firstLine = String(payload.error ?? '').split('\n', 1)[0];
@@ -181,11 +122,7 @@ function countByName(calls) {
   return out;
 }
 
-/**
- * Sub-agent tokens live in their own transcript; each stop emits the delta.
- * One file per agent: two sub-agents stopping together never share a
- * read-modify-write, and one agent never stops twice at once.
- */
+// One store file per agent, so two sub-agents stopping together never share a read-modify-write.
 function agentUsageEvent(payload, cwd) {
   const usage = readTranscriptUsage(payload.agent_transcript_path);
   if (!usage || !payload.agent_id) return null;
@@ -204,11 +141,6 @@ function agentUsageEvent(payload, cwd) {
   return { event: 'AgentUsage', ...usage, delta };
 }
 
-/**
- * @param {object} payload - parsed hook payload (PostToolUse, PostToolUseFailure,
- *   PostToolBatch, SubagentStop or UserPromptSubmit)
- * @returns {Promise<null>} always null — pure side effect (append + claim heartbeat)
- */
 export async function run(payload) {
   try {
     if (!payload) return null;
@@ -222,8 +154,6 @@ export async function run(payload) {
 
     if (!stateExists(cwd)) return null;
 
-    // getActiveFeature → loadState hydrates every feature.json: O(active
-    // features) per call, fine while archive keeps that set small.
     let feature = null;
     let phase = null;
     try {
@@ -237,14 +167,9 @@ export async function run(payload) {
         feature = active?.name ?? featureFromPath(targetFilePath);
         if (feature) phase = active?.feature?.phase || derivePhaseForFeature(feature, cwd);
       }
-    } catch {
-      // enrichment is best-effort — a missing feature never blocks capture
-    }
+    } catch {}
 
-    // Claim heartbeat: this hook fires on every tool call, so it is the proof
-    // of life for the advisory feature claim. shouldHeartbeat() is a local,
-    // git-free pre-check that says no on ~99% of calls; only then is the git
-    // common dir resolved (pure filesystem, no subprocess).
+    // Claim heartbeat: shouldHeartbeat is a git-free pre-check that says no on ~99% of calls.
     if (feature && payload.session_id) {
       try {
         const { shouldHeartbeat, heartbeatClaim } = await import('../../shared/claim-registry.js');
@@ -253,7 +178,7 @@ export async function run(payload) {
           const common = resolveGitCommonDir(cwd);
           if (common) heartbeatClaim(feature, { gitCommonDir: common, sessionId: payload.session_id });
         }
-      } catch { /* fail-open — a missed heartbeat only shortens a claim's life */ }
+      } catch {}
     }
 
     const hookEvent = payload.hook_event_name;
@@ -290,17 +215,14 @@ export async function run(payload) {
         event.kind = classifyReadKind(event.target);
         if (Number.isInteger(input.offset)) event.offset = input.offset;
         if (Number.isInteger(input.limit)) event.limit = input.limit;
-        // A failed Read ingested nothing. A stat/read race with a file deleted
-        // between the Read and this hook omits the numbers rather than fail.
+        // A failed Read ingested nothing; a file deleted before this hook just omits the numbers.
         if (hookEvent !== 'PostToolUseFailure') {
           try {
             const abs = targetAbs || resolveTargetPath(event.target, projectDir);
             event.bytes = statSync(abs).size;
             const read = readSliceBytes(abs, input, event.bytes);
             if (read !== undefined) event.bytesRead = read;
-          } catch {
-            // omit bytes
-          }
+          } catch {}
         }
       } else if (tool === 'Bash' || tool === 'PowerShell') {
         const command = capField(input.command || '');
@@ -311,8 +233,6 @@ export async function run(payload) {
       } else if (tool === 'Write' || tool === 'Edit') {
         event.target = normalize(input.file_path || input.path);
       } else {
-        // Every other tool still counts toward "the whole path" — a compact
-        // target keeps Grep/Glob/WebFetch bursts distinguishable.
         const target = input.file_path || input.path || input.pattern || input.query || input.url || '';
         if (target) event.target = normalize(String(target));
       }
@@ -333,7 +253,6 @@ export async function run(payload) {
     appendTelemetryEvent(event, cwd);
     return null;
   } catch {
-    // Fail-open
     return null;
   }
 }