@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/framework/hooks/shared/hook-response.js

@@ -1,47 +1,18 @@
-/**
- * Shared hook response builders for Claude Code hooks.
- *
- * Claude Code hooks communicate via JSON to stdout.
- * - PreToolUse: { "decision": "block"|"approve", "reason": "..." }
- * - SessionStart/Stop/PostToolUse/etc (non-blocking context injection):
- *   { "hookSpecificOutput": { "hookEventName": "...", "additionalContext": "..." } }
- *   A top-level `additionalContext` is NOT honored by Claude Code for any
- *   event — it must be nested under `hookSpecificOutput` alongside the
- *   event name (see https://code.claude.com/docs/en/hooks.md).
- */
+// A top-level `additionalContext` is NOT honored for any event: it must be nested
+// under `hookSpecificOutput` (https://code.claude.com/docs/en/hooks.md).
 
-/**
- * Block a tool use with a reason.
- * @param {string} reason - Human-readable reason for blocking
- */
 export function block(reason) {
   console.log(JSON.stringify({ decision: 'block', reason }));
   process.exit(0);
 }
 
-/**
- * Approve a tool use, optionally injecting context.
- * @param {string} [context] - Additional context to inject
- */
 export function approve(context) {
   if (context) {
     console.log(JSON.stringify({ decision: 'approve', additionalContext: context }));
   }
-  // No output = implicit approve
   process.exit(0);
 }
 
-/**
- * Inject additional (non-blocking) context for the current hook event.
- *
- * Must be nested under `hookSpecificOutput` — Claude Code does not honor a
- * top-level `additionalContext` for any event.
- *
- * @param {string} text - Context text to inject
- * @param {string} eventName - The hook event this is responding to (e.g.
- *   'SessionStart', 'Stop', 'PostToolUse') — required, echoed back as
- *   `hookSpecificOutput.hookEventName`.
- */
 export function injectContext(text, eventName) {
   console.log(JSON.stringify({
     hookSpecificOutput: { hookEventName: eventName, additionalContext: text },
@@ -49,63 +20,26 @@ export function injectContext(text, eventName) {
   process.exit(0);
 }
 
-/**
- * Silent exit — no output, no blocking.
- */
 export function pass() {
   process.exit(0);
 }
 
-// ── Pure (non-exiting) result builders ──────────────────────────────────────
-//
-// Every core hook used to run inline at module scope and call block()/pass()/
-// injectContext() above to print+exit(0) the moment it knew its verdict. That
-// stops being safe once a hook's logic moves into an exported `run(payload)`
-// that can ALSO be called by framework/hooks/claude-code/core/chain.js — which
-// imports several hooks' run() into ONE process and cannot have any of them
-// call process.exit() mid-chain (it would kill the other links). run() must
-// instead RETURN the verdict object; chain.js (or this file's own
-// runStandalone(), below) is what actually prints it and exits.
-//
-// These builders produce the exact same JSON shapes as block()/approve()/
-// injectContext() above — keep them in sync if that shape ever changes.
-
-/** Pure equivalent of block(reason) — returns the verdict instead of printing+exiting. */
+// `run()` returns these instead of exiting: chain.js runs several hooks in one
+// process. Same JSON shapes as block()/approve()/injectContext() above.
 export function blockResult(reason) {
   return { decision: 'block', reason };
 }
 
-/** Pure equivalent of approve(context) — null means "pass" (nothing to say). */
 export function approveResult(context) {
   return context ? { decision: 'approve', additionalContext: context } : null;
 }
 
-/** Pure equivalent of injectContext(text, eventName). */
 export function contextResult(text, eventName) {
   return { hookSpecificOutput: { hookEventName: eventName, additionalContext: text } };
 }
 
-/**
- * Standalone tail every core hook calls as its last line:
- * `await runStandalone(run);`
- *
- * Reads stdin once, calls the hook's `run(payload)`, prints the JSON verdict
- * (if any) and exits 0 — reproducing exactly what block()/injectContext()/
- * pass() used to do when a hook's logic lived inline at module scope.
- *
- * No-ops when MORPH_HOOK_CHAINED is set: that means core/chain.js already
- * imported this module and will call run() itself with a payload it read
- * once for the whole chain — this file must not ALSO read stdin or exit here
- * (doing so would race chain.js's own stdin read and kill the chain process
- * after the first link). chain.js sets the flag BEFORE its first dynamic
- * import, so every hook it loads sees it already set at call time.
- *
- * Fail-open: any error (including a rejected run()) prints nothing and exits
- * 0 — the same silent-pass behavior every hook's own outer try/catch used to
- * produce on an unexpected error.
- *
- * @param {(payload: object) => Promise<object|null>} run
- */
+// No-op under MORPH_HOOK_CHAINED: chain.js reads stdin once for the whole chain,
+// and reading or exiting here would kill it after the first link.
 export async function runStandalone(run) {
   if (process.env.MORPH_HOOK_CHAINED) return;
 
@@ -123,17 +57,8 @@ export async function runStandalone(run) {
   process.exit(0);
 }
 
-/**
- * Pure builder for a PreToolUse rewrite: Claude Code runs the tool with
- * `updatedInput` in place of the original `tool_input`, and the decision is
- * an explicit `allow` (a rewrite without a decision is ignored). Use it ONLY
- * when the hook actually changed something — an unconditional `allow` would
- * skip the permission prompt for every call it touches.
- *
- * @param {object} updatedInput - the full replacement tool_input
- * @param {string} eventName - 'PreToolUse'
- * @param {string} [context] - optional additionalContext (what was changed)
- */
+// A rewrite without a decision is ignored, so it carries `allow`: use it ONLY when
+// the input changed, or every call it touches skips the permission prompt.
 export function updatedInputResult(updatedInput, eventName, context) {
   const out = { hookEventName: eventName, permissionDecision: 'allow', updatedInput };
   if (context) out.additionalContext = context;

package/framework/hooks/shared/morph-cli.js

@@ -1,36 +1,10 @@
-/**
- * morph-cli.js — run the morph-spec CLI from inside a hook.
- *
- * Hooks are installed STANDALONE into `.morph/framework/hooks/` and may never
- * import from `src/`; the only way for a hook to reuse a CLI command (the
- * WorktreeCreate hook needs `worktree setup`/`provision`, WorktreeRemove needs
- * `worktree remove --if-clean`) is to spawn the CLI as a subprocess. This
- * module is the ONE place that knows how to find it.
- *
- * Resolution order:
- *   1. `MORPH_SPEC_BIN` — an explicit command, possibly with leading args and
- *      quoted paths (`node "R:/my repo/bin/morph-spec.js"`). What tests and a
- *      framework checkout use.
- *   2. `morph-spec` on PATH — the npm-installed bin. On win32 the shim is
- *      `morph-spec.cmd`, which Node refuses to spawn without a shell, so it is
- *      located by scanning PATH ourselves and then run through the shell with
- *      each arg quoted; on POSIX a plain `shell:false` spawn.
- *   3. `npx --no-install morph-spec` — a project-local dependency.
- *
- * ENOENT (or the shell's "not recognized"/"could not determine executable")
- * everywhere → `{ unavailable: true }`, never a throw: the caller decides what
- * degraded behavior looks like.
- *
- * `json` is the LAST line of stdout that parses as a JSON object (the CLI's
- * commands print exactly one JSON line; anything a stray console.log adds
- * before it is skipped), or null.
- */
-
+// A hook cannot import `src/`, so it reuses a CLI command by spawning the CLI; this is the one
+// place that finds it. On win32 `morph-spec.cmd` is located on PATH by hand and run through the
+// shell, since Node refuses to spawn a `.cmd` without one.
 import { spawnSync } from 'child_process';
 import { existsSync } from 'fs';
 import { delimiter, join } from 'path';
 
-/** Split a command string into argv, honoring single and double quotes. */
 function splitCommand(command) {
   const tokens = [];
   const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
@@ -39,22 +13,13 @@ function splitCommand(command) {
   return tokens;
 }
 
-/** Quote one argument for cmd.exe (the only shell path this module uses). */
 export function quoteForCmd(arg) {
   if (arg === '') return '""';
   if (!/[\s"&|<>^()]/.test(arg)) return arg;
   return `"${arg.replace(/"/g, '""')}"`;
 }
 
-/**
- * First PATH entry holding any of `files`, or null. The entries are walked in
- * PATH order and every name is tried inside each one, the way cmd.exe applies
- * PATHEXT: a `graphify.cmd` early in PATH wins over a `graphify.exe` later.
- *
- * @param {string[]} files
- * @param {NodeJS.ProcessEnv} env
- * @returns {string|null}
- */
+/** Walks PATH in order and tries every name in each entry, the way cmd.exe applies PATHEXT. */
 export function findFirstOnPath(files, env) {
   const raw = env.PATH || env.Path || env.path || '';
   for (const dir of raw.split(delimiter)) {
@@ -69,7 +34,6 @@ export function findFirstOnPath(files, env) {
 
 const findOnPath = (file, env) => findFirstOnPath([file], env);
 
-/** Last stdout line that parses as a JSON object, or null. */
 export function lastJsonLine(stdout) {
   const lines = String(stdout || '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
   for (let i = lines.length - 1; i >= 0; i--) {
@@ -82,10 +46,6 @@ export function lastJsonLine(stdout) {
   return null;
 }
 
-/**
- * The candidates to try, in order. Each is `{ file, args, shell }`.
- * @param {NodeJS.ProcessEnv} env
- */
 function candidates(env) {
   const list = [];
   const explicit = env.MORPH_SPEC_BIN && splitCommand(env.MORPH_SPEC_BIN);
@@ -107,10 +67,8 @@ function candidates(env) {
 const NOT_FOUND_RE = /not recognized as an internal or external command|could not determine executable to run|command not found|ENOENT/i;
 
 /**
- * Run `morph-spec <args>` and return its result.
- *
- * @param {string[]} args - CLI argv after the program name
- * @param {{ cwd?: string, timeoutMs?: number, env?: NodeJS.ProcessEnv }} [opts]
+ * A missing CLI is `{ unavailable: true }`, never a throw. `json` is the last stdout line that
+ * parses as an object.
  * @returns {{ ok: boolean, code: number|null, stdout: string, stderr: string, json: object|null, unavailable: boolean }}
  */
 export function runMorphSpec(args, { cwd, timeoutMs = 120000, env } = {}) {
@@ -134,10 +92,8 @@ export function runMorphSpec(args, { cwd, timeoutMs = 120000, env } = {}) {
     }
     const stdout = r.stdout || '';
     const stderr = r.stderr || '';
-    // The npx/shell paths cannot surface ENOENT: the shell (or npx itself)
-    // reports "not found" as a non-zero exit with a message. Only those two
-    // kinds are read that way — a real morph-spec failure is never mistaken
-    // for absence.
+    // Shell and npx report "not found" as a non-zero exit, never ENOENT; the explicit
+    // MORPH_SPEC_BIN is excluded so a real morph-spec failure is never read as absence.
     if (cand.kind !== 'env' && r.status !== 0 && !stdout.trim() && NOT_FOUND_RE.test(stderr)) continue;
     return { ok: r.status === 0, code: r.status, stdout, stderr, json: lastJsonLine(stdout), unavailable: false };
   }

package/framework/hooks/shared/payload-utils.js

@@ -1,32 +1,9 @@
-/**
- * Shared payload utilities for Claude Code Write/Edit hooks.
- *
- * Extracts file path and content from tool_input payloads,
- * normalizing between Write (content, file_path) and Edit (new_string, old_string, file_path).
- */
-
 import { createHash } from 'crypto';
 import { existsSync } from 'fs';
 import { dirname, join, isAbsolute } from 'path';
 
-/**
- * Resolve the project root that OWNS a given file: walk up from the file's
- * directory to the nearest ancestor containing one of `markers` (default
- * `package.json` — the tsc/build root). Falls back to `fallbackCwd` when
- * nothing matches or on any error.
- *
- * This exists so a PostToolUse hook typechecks/builds in the CORRECT root when
- * a subagent edits a file inside its own git worktree (`isolation: "worktree"`,
- * morph-apply §3b-w) instead of always assuming the main working tree. In the
- * normal (non-worktree) case it resolves to the same root as `process.cwd()`.
- *
- * Fail-open: never throws — returns `fallbackCwd` on any error.
- *
- * @param {string} filePath - edited file path (absolute or relative)
- * @param {string} fallbackCwd - root to use if resolution fails (usually process.cwd())
- * @param {string[]} [markers] - ancestor marker filenames to look for
- * @returns {string} the resolved root directory
- */
+// A sub-agent may edit inside its own worktree: the build root comes from the
+// file, not from the session's cwd.
 export function resolveRootForFile(filePath, fallbackCwd, markers = ['package.json']) {
   try {
     if (!filePath) return fallbackCwd;
@@ -48,33 +25,9 @@ export function resolveRootForFile(filePath, fallbackCwd, markers = ['package.js
   }
 }
 
-/**
- * Resolve the project root that OWNS a `.morph/features/...` path — the tree
- * whose `.morph/` the hook must read and write for that file.
- *
- * A hook process knows only where the SESSION lives (`process.cwd()` /
- * `CLAUDE_PROJECT_DIR`). That is not the same thing as where the FILE lives: a
- * session rooted in the primary repo can legitimately write to a feature that
- * lives in a secondary git worktree. Resolving state from the process instead
- * of the path is what made `enforce-phase-writes` block a legal `2-plan/` write
- * (the root still had the feature at `proposal`) while `protect-spec-files`
- * simultaneously went DARK there (the root had no approved gate to enforce) —
- * one defect, opposite directions.
- *
- * The anchor is exact, so no marker walk is needed: everything before the
- * file's own `.morph/features/` segment IS the owning root. `lastIndexOf` picks
- * the CLOSEST enclosing `.morph/` — the worktree's, not the root it nests under.
- *
- * Note this cannot be solved by locating the hook file itself: `worktree setup`
- * junctions `.morph/framework/` back to the primary root, so every worktree
- * executes the very same hook file. Only the target path identifies the tree.
- *
- * Fail-open: never throws — returns `fallbackCwd` for any non-feature path.
- *
- * @param {string} filePath - target file path (absolute or relative)
- * @param {string} fallbackCwd - root to use when the path owns no `.morph/`
- * @returns {string} the resolved project root
- */
+// State is resolved from the target PATH, never the session: a session in the
+// primary root may write a feature that lives in a worktree. `lastIndexOf` picks
+// the closest enclosing `.morph/`.
 export function resolveMorphRoot(filePath, fallbackCwd) {
   try {
     if (!filePath) return fallbackCwd;
@@ -88,111 +41,41 @@ export function resolveMorphRoot(filePath, fallbackCwd) {
   }
 }
 
-/**
- * Is this an already-absolute path, on EITHER convention?
- *
- * `path.isAbsolute` is platform-bound: `C:/x` is absolute on win32 and relative
- * on posix. That asymmetry is a real defect here, not a theoretical one — a
- * Windows-shaped path reaching a posix `join()` produces `/cwd/C:/x`, silently
- * resolving state against a directory that cannot exist. Recognizing the drive
- * letter explicitly makes the answer the same everywhere (and is a no-op on
- * win32, where `isAbsolute` already accepts it).
- */
+// `path.isAbsolute` is platform-bound: on posix `C:/x` would join into `/cwd/C:/x`.
 const isAbsolutePath = (p) => isAbsolute(p) || /^[a-zA-Z]:\//.test(p);
 
-/** Normalize to forward slashes and make absolute against `fallbackCwd`. */
 function toAbsolutePosix(filePath, fallbackCwd) {
   const p = String(filePath).replace(/\\/g, '/');
   return isAbsolutePath(p) ? p : join(fallbackCwd, p).replace(/\\/g, '/');
 }
 
-/**
- * Absolute path of a hook's target file, resolved against the root that owns
- * it. Pairs with `resolveMorphRoot` so a hook never mixes "the tree I read
- * state from" with "the file I read content from".
- *
- * @param {string} filePath
- * @param {string} fallbackCwd
- * @returns {string}
- */
 export function resolveTargetPath(filePath, fallbackCwd) {
   return toAbsolutePosix(filePath || '', fallbackCwd);
 }
 
-/**
- * Get the file path from a hook payload, normalizing backslashes.
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Normalized file path or empty string
- */
 export function getFilePath(payload) {
   const raw = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
   return raw.replace(/\\/g, '/');
 }
 
-/**
- * Get the content being written or edited.
- * For Write: returns `content` (full file content).
- * For Edit: returns `new_string` (replacement text).
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Content string or empty string
- */
 export function getContentToValidate(payload) {
   const input = payload?.tool_input;
   if (!input) return '';
-  // Write tool uses 'content', Edit tool uses 'new_string'
   return input.content || input.new_string || '';
 }
 
-/**
- * Check if this is a Write operation (full file content available).
- * @param {Object} payload - Hook payload from stdin
- * @returns {boolean} True if Write (content exists), false if Edit or unknown
- */
 export function isWriteOperation(payload) {
   return typeof payload?.tool_input?.content === 'string';
 }
 
-/**
- * Get the tool name from a hook payload.
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Tool name or 'unknown'
- */
 export function getToolName(payload) {
   return payload?.tool_name || 'unknown';
 }
 
-/** Assinatura de Bash: comando normalizado, truncado. Ver getCommandSignature. */
 const BASH_SIGNATURE_MAX = 120;
 
-/**
- * Build a normalized signature for loop detection.
- * - Edit/Write: "Edit:normalized/file/path#<sha1[0:8] do conteúdo>" ("Edit:path" sem conteúdo)
- * - Bash: "Bash:<normalized command, truncated>"
- * - Every other tool WITH input: "Tool:<truncated JSON of tool_input>"
- * - No tool_input at all: just the tool name
- *
- * The general (non-Edit/Write/Bash) case matters: a burst of `Read`/`Skill`/
- * `Grep`/`Agent` calls against DIFFERENT targets (phase-context loading,
- * post-task evaluation reads, parallel subagent dispatch) is normal work, not
- * a loop. Collapsing every one of them to the bare tool name is what made
- * loop-detect fire on exactly that legitimate traffic — a real, reported
- * false positive. Folding in the actual input (rather than hand-listing a
- * target field per tool) fixes it uniformly for every tool at once.
- *
- * **Bash ficou de fora daquele fix (2026-07-22) e continuou colapsando em DUAS
- * PALAVRAS**, o que é quase sempre o nome da ferramenta e nada mais:
- * `npm test -- a`, `npm test -- b` e `npm run build` viravam `Bash:npm test` /
- * `Bash:npm run`. Um ciclo legítimo de mutação — rodar o mesmo runner sobre
- * alvos diferentes, que é exatamente como se testa se um teste morde — disparava
- * o aviso de loop três vezes seguidas. Aviso que toca à toa é aviso que se
- * aprende a ignorar, e aí ele não serve nem quando está certo.
- *
- * O discriminador agora é o comando inteiro (normalizado e truncado), mesma
- * forma dos demais tools. Repetir o comando IDÊNTICO continua sendo loop.
- *
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Signature string
- */
+// The input is part of the signature: the same tool on DIFFERENT targets is
+// work, not a loop. Only an identical call repeats the signature.
 export function getCommandSignature(payload) {
   const tool = getToolName(payload);
   if (tool === 'unknown') return 'unknown';
@@ -203,11 +86,8 @@ export function getCommandSignature(payload) {
   if (tool === 'Edit' || tool === 'Write') {
     const path = (input.file_path || input.path || '').replace(/\\/g, '/');
     if (!path) return tool;
-    // O caminho sozinho confundia TRABALHO com LOOP: editar regiões diferentes
-    // de dois arquivos (a forma normal de uma correção que cruza teste e
-    // fonte) dava só duas assinaturas e disparava o aviso. O conteúdo da
-    // edição entra na assinatura; repetir a MESMA edição continua casando, e o
-    // ping-pong A→B / B→A continua dando duas assinaturas — loop de verdade.
+    // O caminho sozinho confundia editar regiões diferentes com loop; o
+    // ping-pong A→B / B→A continua dando duas assinaturas.
     const body = tool === 'Write'
       ? input.content
       : (input.old_string !== undefined || input.new_string !== undefined)
@@ -218,8 +98,6 @@ export function getCommandSignature(payload) {
   }
 
   if (tool === 'Bash') {
-    // Espaços colapsados para que a mesma invocação escrita com espaçamento
-    // diferente continue casando — o alvo é o comando, não a digitação.
     const cmd = (input.command || '').replace(/\s+/g, ' ').trim();
     return cmd ? `Bash:${cmd.slice(0, BASH_SIGNATURE_MAX)}` : 'Bash';
   }

package/framework/hooks/shared/phase-utils.js

@@ -1,136 +1,78 @@
 // GENERATED by scripts/generate-refs.js — DO NOT EDIT manually
 // Source of truth: src/core/paths/output-schema.js
 // Regenerate with: node scripts/generate-refs.js
-/**
- * Shared phase utilities for Claude Code hooks.
- *
- * Maps phases to directories and output types.
- */
 
-/** Phase order */
-export const PHASE_ORDER = ["proposal","uiux","plan","implement","review","sync"];
+export const PHASE_ORDER = ["plan","uiux","implement","review"];
 
-/** Map phase → allowed output subdirectory */
 export const PHASE_DIRS = {
-  proposal: '0-proposal',
-  uiux: '1-design',
   plan: '2-plan',
+  uiux: '1-design',
   implement: '3-implement',
   review: '4-review',
-  sync: '3-implement',
 };
 
-/** Map output type (camelCase) → phase that produces it */
 export const OUTPUT_PHASE_MAP = {
-  proposal: 'proposal',
-  stackScan: 'proposal',
+  plan: 'plan',
+  checks: 'plan',
   uiDesignSystem: 'uiux',
   uiMockups: 'uiux',
   uiComponents: 'uiux',
   uiFlows: 'uiux',
-  spec: 'plan',
-  tasks: 'plan',
-  decisions: 'plan',
-  usecases: 'plan',
-  recap: 'implement',
   evidencias: 'implement',
-  reviewReport: 'review',
-  evaluatorReport: 'review',
+  verifierReport: 'review',
+  reviewerReport: 'review',
+  securityReport: 'review',
 };
 
-/** Map filename → output type (camelCase) */
 export const FILENAME_TO_OUTPUT = {
-  'proposal.md': 'proposal',
-  'stack-scan.md': 'stackScan',
+  'plan.md': 'plan',
+  'checks.json': 'checks',
   'design-system.md': 'uiDesignSystem',
   'mockups.md': 'uiMockups',
   'components.md': 'uiComponents',
   'flows.md': 'uiFlows',
-  'spec.md': 'spec',
-  'tasks.json': 'tasks',
-  'decisions.md': 'decisions',
-  'recap.md': 'recap',
-  'review-report.md': 'reviewReport',
-  'evaluator-report.md': 'evaluatorReport',
+  'verifier.md': 'verifierReport',
+  'reviewer.md': 'reviewerReport',
+  'security.md': 'securityReport',
 };
 
-/** Protected spec files and the approval gate that locks them */
 export const PROTECTED_SPEC_FILES = {
+  'plan.md': 'plan',
+  'checks.json': 'plan',
   'design-system.md': 'uiux',
   'mockups.md': 'uiux',
   'components.md': 'uiux',
   'flows.md': 'uiux',
-  'spec.md': 'plan',
-  'tasks.json': 'plan',
 };
 
-/**
- * For protected files that carry mutable progress fields: filename → the
- * top-level array-item fields that may change after the gate is approved.
- * When a protected file is listed here, the protect-spec-files hook does a
- * semantic diff (allowing only these fields to change) instead of a blanket block.
- */
-export const MUTABLE_SPEC_FIELDS = {
-  'tasks.json': ['status', 'outputs', 'notes'],
-};
 
-/**
- * Extract feature name from a .morph/features/{feature}/... path
- * @param {string} filePath - File path to analyze
- * @returns {string|null} Feature name or null
- */
 export function extractFeatureName(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   const match = normalized.match(/\.morph\/features\/([^/]+)\//);
   return match ? match[1] : null;
 }
 
-/**
- * Extract phase subdirectory from a .morph/features/{feature}/{phaseDir}/... path
- * @param {string} filePath - File path to analyze
- * @returns {string|null} Phase directory (e.g., '0-proposal', '2-design') or null
- */
 export function extractPhaseDir(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   const match = normalized.match(/\.morph\/features\/[^/]+\/(\d+-[^/]+)\//);
   return match ? match[1] : null;
 }
 
-/**
- * Check if a file path is inside .morph/features/
- * @param {string} filePath
- * @returns {boolean}
- */
 export function isFeaturePath(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   return normalized.includes('.morph/features/');
 }
 
-/**
- * Check if a file path is inside .morph/framework/ (readonly)
- * @param {string} filePath
- * @returns {boolean}
- */
 export function isFrameworkPath(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   return normalized.includes('.morph/framework/');
 }
 
-/**
- * Check if a file path is state.json
- * @param {string} filePath
- * @returns {boolean}
- */
 export function isStatePath(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   return normalized.endsWith('.morph/state.json');
 }
 
-/**
- * Get the basename of a file path
- * @param {string} filePath
- * @returns {string}
- */
 export function getBasename(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   return normalized.split('/').pop();

package/framework/hooks/shared/redact-secrets.js

@@ -1,14 +1,6 @@
-/**
- * Redaction of obvious secrets in free text that telemetry persists (Bash
- * commands, dispatch prompts). events.jsonl is copied into finish backups
- * under `.git/`, so whatever lands there outlives the session.
- *
- * Pattern-based by design: it catches a secret written NEXT TO its name
- * (`KEY=…`, `Authorization: …`, `user:pass@`) or in a well-known token shape.
- * A bare value with no name beside it is invisible to any pattern — which is
- * why tool OUTPUT (stdout/stderr, a failure's `error` body) is never persisted
- * at all instead of being redacted.
- */
+// Catches a secret written next to its name or in a known token shape; a bare
+// value is invisible to any pattern, which is why tool OUTPUT is never
+// persisted at all instead of being redacted.
 
 export const REDACTED = '[REDACTED]';
 
@@ -43,10 +35,7 @@ const RULES = [
   [/\beyJ[A-Za-z0-9_-]{5,}\.eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]+/g, REDACTED],
 ];
 
-/**
- * @param {*} text
- * @returns {*} the text with secrets replaced by `[REDACTED]`; non-strings unchanged
- */
+/** Non-strings pass through unchanged. */
 export function redactSecrets(text) {
   if (typeof text !== 'string' || text === '') return text;
   let out = text;