@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

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,15 +163,9 @@ 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)));
+      && (feature?.workType === 'chore' ? ['reviewer.md'] : ['verifier.md', 'reviewer.md']).some((f) => !existsSync(join(root, '.morph', 'features', featureName, '4-review', f)));
     if (selfAssessed) {
       warnings.push(
         `⚠️ [morph-spec] Gate 3 de "${featureName}" aprovado SEM os relatórios de review independentes (verifier.md, reviewer.md) — ` +
@@ -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;
   }
 }

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

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

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

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