@polymorphism-tech/morph-spec 8.15.0 → 8.16.0

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

@@ -11,10 +11,10 @@
  *  - AskUserQuestion answered with option starting "aprovado"        → advance gate
  */
 
-import { readFileSync } from 'fs';
 import { loadState, stateExists } from '../../shared/state-reader.js';
 import { persistFeature, setGateApproved, createDefaultFeature, readFeatureFile } from '../../shared/state-writer.js';
 import { resolveMorphRoot } from '../../shared/payload-utils.js';
+import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import {
   locateFeatureForQuestion,
   allWorkTrees,
@@ -32,19 +32,6 @@ const PHASE_FOLDERS = {
   '5-implement': 'implement', // legacy alias
 };
 
-function exit(output = {}) {
-  process.stdout.write(JSON.stringify(output));
-  process.exit(0);
-}
-
-function readStdin() {
-  try {
-    return JSON.parse(readFileSync(0, 'utf8') || '{}');
-  } catch {
-    return {};
-  }
-}
-
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
@@ -229,36 +216,41 @@ function handleAskUserQuestion(input, sessionRoot) {
   return warnings.length ? warnings.join('\n') : null;
 }
 
-async function main() {
-  // 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).
-  const sessionRoot = projectDir();
+/**
+ * @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).
+    const sessionRoot = projectDir();
 
-  const input = readStdin();
-  const toolName = input.tool_name;
+    const input = payload || {};
+    const toolName = input.tool_name;
 
-  let warning = null;
-  try {
-    if (toolName === 'Write' || toolName === 'Edit') {
-      handleWriteEdit(input, sessionRoot);
-    } else if (toolName === 'AskUserQuestion') {
-      warning = handleAskUserQuestion(input, sessionRoot);
+    let warning = null;
+    try {
+      if (toolName === 'Write' || toolName === 'Edit') {
+        handleWriteEdit(input, sessionRoot);
+      } else if (toolName === 'AskUserQuestion') {
+        warning = handleAskUserQuestion(input, sessionRoot);
+      }
+    } catch {
+      // fail-open
     }
-  } catch {
-    // fail-open
-  }
 
-  // A non-blocking order-violation warning is surfaced as injected context
-  // (hookSpecificOutput.additionalContext); everything else exits silently.
-  if (warning) {
-    exit({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: warning } });
-  } else {
-    exit();
+    // 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;
   }
 }
 
-main().catch(() => exit());
+await runStandalone(run);

package/framework/hooks/claude-code/core/tasks-json-guard.js

@@ -22,62 +22,62 @@
 import { readFileSync } from 'fs';
 import { isAbsolute, join } from 'path';
 import { stateExists } from '../../shared/state-reader.js';
-import { injectContext, pass } from '../../shared/hook-response.js';
+import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 import { getFilePath } from '../../shared/payload-utils.js';
 import { isFeaturePath, getBasename } from '../../shared/phase-utils.js';
 import { VALID_TASK_STATUS, validateTasksDoc } from '../../shared/tasks-validator.js';
 
-function readStdin() {
-  try {
-    return JSON.parse(readFileSync(0, 'utf8') || '{}');
-  } catch {
-    return {};
-  }
-}
-
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
 
-try {
-  const cwd = projectDir();
-  if (!stateExists(cwd)) pass();
+/**
+ * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit)
+ * @returns {Promise<object|null>} a hookSpecificOutput warning when tasks.json
+ *   is unparseable or schema-invalid, or null (pass/silent).
+ */
+export async function run(payload) {
+  try {
+    const cwd = projectDir();
+    if (!stateExists(cwd)) return null;
 
-  const payload = readStdin();
-  const filePath = getFilePath(payload);
-  if (!filePath) pass();
-  if (!isFeaturePath(filePath)) pass();
-  if (getBasename(filePath) !== 'tasks.json') pass();
+    const filePath = getFilePath(payload);
+    if (!filePath) return null;
+    if (!isFeaturePath(filePath)) return null;
+    if (getBasename(filePath) !== 'tasks.json') return null;
 
-  const absPath = isAbsolute(filePath) ? filePath : join(cwd, filePath);
+    const absPath = isAbsolute(filePath) ? filePath : join(cwd, filePath);
 
-  let doc;
-  try {
-    doc = JSON.parse(readFileSync(absPath, 'utf-8'));
-  } catch {
-    logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
-    injectContext(
-      '⚠️ [morph-spec] tasks.json INVÁLIDO — o arquivo gravado não parseia como JSON. ' +
-      'Corrija o arquivo antes de continuar.',
-      'PostToolUse'
-    );
-  }
+    let doc;
+    try {
+      doc = JSON.parse(readFileSync(absPath, 'utf-8'));
+    } catch {
+      logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
+      return contextResult(
+        '⚠️ [morph-spec] tasks.json INVÁLIDO — o arquivo gravado não parseia como JSON. ' +
+        'Corrija o arquivo antes de continuar.',
+        'PostToolUse'
+      );
+    }
 
-  const { valid, errors } = validateTasksDoc(doc);
-  if (!valid) {
-    logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
-    injectContext(
-      '⚠️ [morph-spec] tasks.json com schema inválido após o write:\n' +
-      errors.map(e => `  • ${e}`).join('\n') +
-      `\nStatus válidos: ${VALID_TASK_STATUS.join(', ')}. Corrija antes de marcar a task como done.`,
-      'PostToolUse'
-    );
-  }
+    const { valid, errors } = validateTasksDoc(doc);
+    if (!valid) {
+      logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
+      return contextResult(
+        '⚠️ [morph-spec] tasks.json com schema inválido após o write:\n' +
+        errors.map(e => `  • ${e}`).join('\n') +
+        `\nStatus válidos: ${VALID_TASK_STATUS.join(', ')}. Corrija antes de marcar a task como done.`,
+        'PostToolUse'
+      );
+    }
 
-  logHookActivity('tasks-json-guard', 'PostToolUse', 'ok', cwd);
-  pass();
-} catch {
-  // Fail-open
-  process.exit(0);
+    logHookActivity('tasks-json-guard', 'PostToolUse', 'ok', cwd);
+    return null;
+  } catch {
+    // Fail-open
+    return null;
+  }
 }
+
+await runStandalone(run);

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

@@ -18,100 +18,177 @@
  * shared trace context (the enrichment lesson from the observability standard:
  * propagate a correlation key, a TraceId does not survive the boundary).
  *
+ * SINK RESOLUTION: the event is appended to the `.morph/` tree that OWNS the
+ * tool's target file, not to `process.cwd()`/`CLAUDE_PROJECT_DIR` — same
+ * pattern as trace-autogen/state-sync (`resolveMorphRoot`). A session rooted
+ * in the primary repo can legitimately touch a feature living in a secondary
+ * git worktree; sinking on the session's cwd put those events in the WRONG
+ * tree's events.jsonl, the mirror of the trace-autogen worktree defect. Tools
+ * that carry no file_path (Bash, Skill, Agent…) have no target to resolve —
+ * the session cwd stays the reference for those, same as before.
+ *
  * SILENT: never blocks, never injects context — only appends. Fail-open on any
  * error (exit 0). Only active inside a morph project (stateExists gate).
  */
 
-import { readStdin } from '../../shared/stdin-reader.js';
+import { statSync } from 'fs';
 import { stateExists, getActiveFeature, derivePhaseForFeature } from '../../shared/state-reader.js';
 import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
-import { pass } from '../../shared/hook-response.js';
+import { runStandalone } from '../../shared/hook-response.js';
+import { getFilePath, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 
 function normalize(p) {
   return (p || '').replace(/\\/g, '/');
 }
 
-try {
-  if (!stateExists()) pass();
-
-  const payload = await readStdin();
-  if (!payload) pass();
+/**
+ * Classify a Read target into the telemetry `kind` taxonomy — a contract with
+ * the observability side (src/lib/telemetry/telemetry-reader.js), so these
+ * values are pinned, not free-form. Order matters: check the specific
+ * categories before falling back to 'code'. Case-insensitive; `/` and `\`
+ * both normalize to `/` upstream via `normalize()`.
+ */
+function classifyReadKind(target) {
+  const t = (target || '').toLowerCase();
 
-  const cwd = process.cwd();
+  if (t.includes('evals/rubrics')) return 'rubric';
+  if (t.includes('standards/')) return 'standard';
+  if (t.endsWith('skill.md') || t.includes('/skills/')) return 'skill';
+  if (t.split('/').pop() === 'agents.json') return 'agents';
 
-  // Correlation key: active feature + its phase (explicit, not ambient).
-  // NOTE (perf): getActiveFeature → loadState hydrates every .morph/features/*/
-  // feature.json, so enrichment is O(active-feature-count) per tool call. That
-  // is fine for realistic projects (archive removes finished features, so the
-  // dir holds only the few in-flight ones) but would grow on a project that
-  // keeps many un-archived features. If that ever bites, resolve the active
-  // feature from the thin state.json index alone. Kept accurate-over-cheap for
-  // now because phase is not stored in feature.json — it needs derivation.
-  let feature = null;
-  let phase = null;
-  try {
-    const active = getActiveFeature(cwd);
-    if (active) {
-      feature = active.name;
-      phase = active.feature?.phase || derivePhaseForFeature(active.name, cwd);
+  // Inside a feature folder AND one of the named plan artifacts (or under a
+  // usecases/ or reports/ subfolder) — everything else in a feature folder
+  // (source files a task produced, say) is 'code'.
+  const inFeature = t.match(/\.morph\/features\/[^/]+\/(.+)$/);
+  if (inFeature) {
+    const rel = inFeature[1];
+    const PLAN_ARTIFACT_BASENAMES = new Set([
+      'proposal.md', 'spec.md', 'mandate.md', 'tasks.json',
+      'decisions.md', 'recap.md', 'handoff.md',
+    ]);
+    const base = rel.split('/').pop();
+    if (PLAN_ARTIFACT_BASENAMES.has(base) || rel.includes('usecases/') || rel.includes('reports/')) {
+      return 'plan-artifact';
     }
-  } catch {
-    // enrichment is best-effort — a missing feature never blocks capture
   }
 
-  // Claim heartbeat (B1): this hook already fires on EVERY tool call, so it is
-  // the natural proof-of-life for the advisory feature claim — no extra hook,
-  // no discipline asked of the operator. The registry throttles the actual
-  // write (HEARTBEAT_THROTTLE_MS), so this is a small read on most calls.
-  // Silent and fail-open, like everything else here.
-  if (feature && payload.session_id) {
+  return 'code';
+}
+
+/**
+ * @param {object} payload - parsed PostToolUse (any tool) or UserPromptSubmit payload
+ * @returns {Promise<null>} always null — this hook is pure side-effect
+ *   (appends to events.jsonl + claim heartbeat), never prints/injects context.
+ */
+export async function run(payload) {
+  try {
+    if (!payload) return null;
+
+    // Resolve the sink tree from the tool's target file (when it has one)
+    // BEFORE the stateExists gate below — otherwise a root session writing
+    // into a worktree would be gated on the ROOT's state instead of the
+    // worktree's.
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const targetFilePath = getFilePath(payload);
+    const cwd = targetFilePath ? resolveMorphRoot(targetFilePath, projectDir) : projectDir;
+
+    if (!stateExists(cwd)) return null;
+
+    // Correlation key: active feature + its phase (explicit, not ambient).
+    // NOTE (perf): getActiveFeature → loadState hydrates every .morph/features/*/
+    // feature.json, so enrichment is O(active-feature-count) per tool call. That
+    // is fine for realistic projects (archive removes finished features, so the
+    // dir holds only the few in-flight ones) but would grow on a project that
+    // keeps many un-archived features. If that ever bites, resolve the active
+    // feature from the thin state.json index alone. Kept accurate-over-cheap for
+    // now because phase is not stored in feature.json — it needs derivation.
+    let feature = null;
+    let phase = null;
     try {
-      const { execSync } = await import('child_process');
-      const { resolve } = await import('path');
-      const { heartbeatClaim } = await import('../../shared/claim-registry.js');
-      const common = execSync('git rev-parse --git-common-dir', { cwd, stdio: 'pipe' }).toString().trim();
-      if (common) heartbeatClaim(feature, { gitCommonDir: resolve(cwd, common), sessionId: payload.session_id });
-    } catch { /* fail-open — a missed heartbeat only shortens a claim's life */ }
-  }
+      const active = getActiveFeature(cwd);
+      if (active) {
+        feature = active.name;
+        phase = active.feature?.phase || derivePhaseForFeature(active.name, cwd);
+      }
+    } catch {
+      // enrichment is best-effort — a missing feature never blocks capture
+    }
+
+    // Claim heartbeat (B1): this hook already fires on EVERY tool call, so it is
+    // the natural proof-of-life for the advisory feature claim — no extra hook,
+    // no discipline asked of the operator. Two throttles guard the cost:
+    //   1. shouldHeartbeat() — a LOCAL, git-independent pre-check (see its own
+    //      doc in claim-registry.js) that answers "is a heartbeat even due"
+    //      from a marker beside this project's own `.morph/logs/`. On ~99% of
+    //      calls it says no and NOTHING git-related happens — not even the
+    //      pure-FS walk below, let alone a subprocess.
+    //   2. Only when (1) says yes do we resolve the git common dir — via
+    //      git-paths.js, pure filesystem, no `git` subprocess spawn (this used
+    //      to be `execSync('git rev-parse --git-common-dir')`, ~34ms wasted on
+    //      ~99% of calls because the write below was ALREADY throttled) — and
+    //      call heartbeatClaim(), which has its own authoritative throttle
+    //      keyed to claims.json's stored heartbeatAt.
+    // Silent and fail-open, like everything else here.
+    if (feature && payload.session_id) {
+      try {
+        const { shouldHeartbeat, heartbeatClaim } = await import('../../shared/claim-registry.js');
+        if (shouldHeartbeat(feature, { cwd, sessionId: payload.session_id })) {
+          const { resolveGitCommonDir } = await import('../../shared/git-paths.js');
+          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 */ }
+    }
 
-  let event;
-
-  // UserPromptSubmit carries the user's prompt and no tool_name.
-  if (payload.hook_event_name === 'UserPromptSubmit' || (!payload.tool_name && typeof payload.prompt === 'string')) {
-    event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: payload.prompt || '' };
-  } else {
-    const tool = payload.tool_name;
-    if (!tool) pass();
-    const input = payload.tool_input || {};
-    event = { event: 'PostToolUse', tool };
-
-    if (tool === 'Skill') {
-      event.skill = input.skill || '';
-    } else if (tool === 'Agent' || tool === 'Task') {
-      event.persona = input.subagent_type || '';
-      if (input.description) event.desc = input.description;
-      event.prompt = input.prompt || '';
-    } else if (tool === 'Read') {
-      event.target = normalize(input.file_path || input.path);
-      if (/\/standards\//.test(event.target)) event.kind = 'standard';
-    } else if (tool === 'Bash') {
-      event.command = input.command || '';
-    } else if (tool === 'Write' || tool === 'Edit') {
-      event.target = normalize(input.file_path || input.path);
+    let event;
+
+    // UserPromptSubmit carries the user's prompt and no tool_name.
+    if (payload.hook_event_name === 'UserPromptSubmit' || (!payload.tool_name && typeof payload.prompt === 'string')) {
+      event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: payload.prompt || '' };
     } else {
-      // Every other tool still counts toward "the whole path" — record a
-      // compact target so Grep/Glob/WebFetch bursts remain distinguishable.
-      const target = input.file_path || input.path || input.pattern || input.query || input.url || '';
-      if (target) event.target = normalize(String(target));
+      const tool = payload.tool_name;
+      if (!tool) return null;
+      const input = payload.tool_input || {};
+      event = { event: 'PostToolUse', tool };
+
+      if (tool === 'Skill') {
+        event.skill = input.skill || '';
+      } else if (tool === 'Agent' || tool === 'Task') {
+        event.persona = input.subagent_type || '';
+        if (input.description) event.desc = input.description;
+        event.prompt = input.prompt || '';
+      } else if (tool === 'Read') {
+        event.target = targetFilePath || normalize(input.file_path || input.path);
+        event.kind = classifyReadKind(event.target);
+        // bytes is best-effort: statSync races a file that got deleted/moved
+        // between the Read and this hook firing, or lacks permission — omit
+        // the field rather than fail the whole (silent, fail-open) capture.
+        try {
+          event.bytes = statSync(resolveTargetPath(event.target, cwd)).size;
+        } catch {
+          // omit bytes
+        }
+      } else if (tool === 'Bash') {
+        event.command = input.command || '';
+      } else if (tool === 'Write' || tool === 'Edit') {
+        event.target = normalize(input.file_path || input.path);
+      } else {
+        // Every other tool still counts toward "the whole path" — record a
+        // compact target so Grep/Glob/WebFetch bursts remain distinguishable.
+        const target = input.file_path || input.path || input.pattern || input.query || input.url || '';
+        if (target) event.target = normalize(String(target));
+      }
     }
-  }
 
-  event.feature = feature;
-  event.phase = phase;
+    event.feature = feature;
+    event.phase = phase;
 
-  appendTelemetryEvent(event, cwd);
-  pass();
-} catch {
-  // Fail-open
-  process.exit(0);
+    appendTelemetryEvent(event, cwd);
+    return null;
+  } catch {
+    // Fail-open
+    return null;
+  }
 }
+
+await runStandalone(run);

package/framework/hooks/claude-code/core/trace-autogen.js

@@ -24,13 +24,22 @@
  * (session_id/started_at preserved); a new dated file is created otherwise.
  * `completed_at` + phase_summary are stamped when no task is left
  * pending/in_progress. Fail-open: any error exits 0 silently.
+ *
+ * This is also the vantage point for TaskStart/TaskEnd telemetry: a
+ * pending→in_progress flip and a flip to done/skipped are the only two task
+ * transitions the harness can observe (tasks.json is the single place task
+ * status is written), so this hook diffs each task's previous status against
+ * `.morph/logs/task-times.json` and appends the matching event via the shared
+ * telemetry logger (see `updateTaskTimes` below). The same start/end pair
+ * feeds `duration_seconds` in the trace entry.
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
 import { join } from 'path';
-import { readStdin } from '../../shared/stdin-reader.js';
+import { runStandalone } from '../../shared/hook-response.js';
 import { stateExists } from '../../shared/state-reader.js';
 import { getFilePath, resolveMorphRoot } from '../../shared/payload-utils.js';
+import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
 
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -68,8 +77,100 @@ function sessionId(d) {
 /** tasks.json status → trace-schema status. Unsettled statuses are omitted. */
 const STATUS_MAP = { done: 'completed', skipped: 'skipped', blocked: 'failed' };
 
-async function main() {
-  const payload = await readStdin();
+const TASK_TIMES_PATH = join('.morph', 'logs', 'task-times.json');
+
+/**
+ * Read `.morph/logs/task-times.json`: `{ [feature]: { [taskId]: { status,
+ * start?, end? } } }`. Nested by feature — not flat by task id, as a literal
+ * reading of "keyed by taskId" might suggest — because task ids (T1, T2…)
+ * are only unique WITHIN a feature; a flat map would let two sibling
+ * features in the same tree (see worktree-state-resolution.test.js for that
+ * shape) clobber each other's start/end timestamps.
+ * Fail-open: a missing/corrupt file reads as {}.
+ */
+function readTaskTimes(root) {
+  const p = join(root, TASK_TIMES_PATH);
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeTaskTimes(root, allTimes) {
+  mkdirSync(join(root, '.morph', 'logs'), { recursive: true });
+  writeFileSync(join(root, TASK_TIMES_PATH), JSON.stringify(allTimes, null, 2), 'utf8');
+}
+
+/**
+ * Diff each task's PREVIOUS status (from `times`, this feature's slice of
+ * task-times.json) against its status in the tasks.json that was just
+ * written, and append the matching telemetry event via the shared logger —
+ * same shape/mechanism as every other event in events.jsonl, just a
+ * different `event` value.
+ *
+ *  - pending → in_progress   ⇒ TaskStart, stamp `start`
+ *  - anything → done/skipped ⇒ TaskEnd (carries the new status), stamp `end`
+ *  - first sight of a task id (no prior entry) only seeds the baseline,
+ *    silently — there is no prior status to diff, and emitting an event here
+ *    would fabricate a transition that never happened (e.g. a task whose
+ *    first-ever tasks.json write already shows it `done`, from historical
+ *    data predating this file).
+ *
+ * Mutates `times` in place and returns whether anything changed, so the
+ * caller only rewrites task-times.json when needed and the entries built
+ * right after this call see the freshly-stamped start/end for
+ * `duration_seconds`.
+ */
+function updateTaskTimes(times, tasks, feature, root, nowIso) {
+  let changed = false;
+  for (const t of tasks) {
+    const prev = times[t.id];
+    if (!prev) {
+      times[t.id] = { status: t.status };
+      changed = true;
+      continue;
+    }
+    if (prev.status === t.status) continue;
+
+    if (prev.status === 'pending' && t.status === 'in_progress') {
+      appendTelemetryEvent({ event: 'TaskStart', feature, task: t.id, phase: 'implement' }, root);
+      times[t.id] = { ...prev, status: t.status, start: nowIso };
+    } else if (t.status === 'done' || t.status === 'skipped') {
+      appendTelemetryEvent({ event: 'TaskEnd', feature, task: t.id, status: t.status, phase: 'implement' }, root);
+      times[t.id] = { ...prev, status: t.status, end: nowIso };
+    } else {
+      times[t.id] = { ...prev, status: t.status };
+    }
+    changed = true;
+  }
+  return changed;
+}
+
+/** Seconds between recorded start/end for a task, or null when either is missing. */
+function taskDuration(times, taskId) {
+  const rec = times[taskId];
+  if (!rec?.start || !rec?.end) return null;
+  const secs = (new Date(rec.end).getTime() - new Date(rec.start).getTime()) / 1000;
+  return Number.isFinite(secs) ? Math.round(secs * 10) / 10 : null;
+}
+
+/**
+ * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit)
+ * @returns {Promise<null>} always null — this hook is pure side-effect (trace
+ *   file + task-times.json), never prints/injects context.
+ */
+export async function run(payload) {
+  try {
+    await generateTrace(payload);
+  } catch {
+    // Fail-open
+  }
+  return null;
+}
+
+async function generateTrace(payload) {
   if (!payload) return;
 
   const filePath = getFilePath(payload);
@@ -90,6 +191,16 @@ async function main() {
   const tasksDoc = JSON.parse(readFileSync(tasksPath, 'utf8'));
   const tasks = Array.isArray(tasksDoc.tasks) ? tasksDoc.tasks : [];
 
+  const now = new Date();
+
+  // TaskStart/TaskEnd telemetry + duration_seconds source: diff each task's
+  // previous status (persisted below) against the status just written.
+  const allTimes = readTaskTimes(cwd);
+  const times = allTimes[feature] ?? (allTimes[feature] = {});
+  if (updateTaskTimes(times, tasks, feature, cwd, now.toISOString())) {
+    writeTaskTimes(cwd, allTimes);
+  }
+
   let recap = {};
   const recapPath = join(featureDir, '3-implement', 'recap.md');
   if (existsSync(recapPath)) {
@@ -118,7 +229,6 @@ async function main() {
     try { previous = JSON.parse(readFileSync(join(tracesDir, existing), 'utf8')); } catch { previous = null; }
   }
 
-  const now = new Date();
   const fileName = existing ?? `${now.toISOString().slice(0, 10)}${suffix}`;
 
   const entries = tasks
@@ -144,7 +254,7 @@ async function main() {
           test_coverage: dims.testCoverage ?? null,
         } : null,
         files_modified: Array.isArray(t.outputs) ? t.outputs.filter(o => typeof o === 'string') : [],
-        duration_seconds: null,
+        duration_seconds: taskDuration(times, t.id),
       };
     });
 
@@ -185,4 +295,4 @@ async function main() {
   writeFileSync(join(tracesDir, fileName), JSON.stringify(trace, null, 2), 'utf8');
 }
 
-main().catch(() => { /* fail-open */ }).finally(() => process.exit(0));
+await runStandalone(run);