@polymorphism-tech/morph-spec 8.37.1 → 8.38.0

package/src/lib/specs/usecase-promoter.js

@@ -30,22 +30,26 @@
  *     rather than silently destroy the other feature's use case.
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
 import { basename, join, relative } from 'path';
 import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
 import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
 import { reservationOwner } from './usecase-registry.js';
+import { SUPERSEDED, useCaseFilesById, useCaseId } from './acervo-format.js';
+
+export { useCaseId };
 
 const UC = OUTPUT_SCHEMA.usecases;
-const UC_FILENAME_RE = new RegExp(UC.filenamePattern);
 
 /** Project-relative path of the permanent use-case archive (git pathspec-ready). */
 export const SPECS_USECASES_PATHSPEC = join('.morph', 'specs', 'usecases');
 
-/** `UC-07-listar-veterinarios.md` → `UC-07`. Null when the name isn't a use case. */
-export function useCaseId(filename) {
-  const m = /^(UC-\d+)-/.exec(filename);
-  return m ? m[1] : null;
+const FRONTMATTER_RE = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/;
+
+/** `true` when the document opens with a frontmatter block. */
+export function hasFrontmatter(content) {
+  const m = FRONTMATTER_RE.exec(content);
+  return !!m && m.index === 0;
 }
 
 /**
@@ -58,33 +62,70 @@ export function useCaseId(filename) {
  *
  * @param {string} content
  * @param {string} key
- * @param {string} value
+ * @param {string} value - written as-is; quote it first when it is free text
  * @returns {string}
  */
-function setFrontmatterField(content, key, value) {
-  const m = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(content);
+export function setFrontmatterField(content, key, value) {
+  const m = FRONTMATTER_RE.exec(content);
   if (!m || m.index !== 0) return content;
 
   const [full, open, body, close] = m;
   const eol = full.includes('\r\n') ? '\r\n' : '\n';
   const fieldLine = new RegExp(`^${key}:[ \\t]*.*$`, 'm');
+  // Function replacer: a value carrying `$&` or `$1` is text, not a pattern.
   const next = fieldLine.test(body)
-    ? body.replace(fieldLine, `${key}: ${value}`)
+    ? body.replace(fieldLine, () => `${key}: ${value}`)
     : `${body}${eol}${key}: ${value}`;
 
   return open + next + close + content.slice(full.length);
 }
 
-/** Read a single top-level frontmatter field. `null` when absent or there is no frontmatter block. */
-function readFrontmatterField(content, key) {
-  const m = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(content);
+/**
+ * Drop a single top-level frontmatter field (its whole line, EOL included).
+ * Absent field or no frontmatter → content unchanged.
+ *
+ * @param {string} content
+ * @param {string} key
+ * @returns {string}
+ */
+export function removeFrontmatterField(content, key) {
+  const m = FRONTMATTER_RE.exec(content);
+  if (!m || m.index !== 0) return content;
+
+  const [full, open, body, close] = m;
+  const lines = body.split(/(?<=\n)/);
+  const kept = lines.filter((line) => !new RegExp(`^${key}:`).test(line));
+  if (kept.length === lines.length) return content;
+  // The last kept line lost its EOL when the removed one was the final line;
+  // the closing delimiter carries its own leading EOL, so trim the dangling one.
+  const next = kept.join('').replace(/\r?\n$/, '');
+  return open + next + close + content.slice(full.length);
+}
+
+/**
+ * Read a single top-level frontmatter field. `null` when absent or there is no
+ * frontmatter block. A double-quoted value is read as the JSON string it is
+ * written as (that is how free text such as `scope:` is stored); a
+ * single-quoted one as YAML reads it (`''` is a quote).
+ */
+export function readFrontmatterField(content, key) {
+  const m = FRONTMATTER_RE.exec(content);
   if (!m || m.index !== 0) return null;
   const line = new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, 'm').exec(m[2]);
-  return line ? line[1].trim() : null;
+  if (!line) return null;
+  const raw = line[1].trim();
+  if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+    try { return JSON.parse(raw); } catch { return raw; }
+  }
+  if (raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1).replace(/''/g, "'");
+  return raw;
 }
 
 /**
- * Rewrite the frontmatter `status:` to `implemented`.
+ * Rewrite the frontmatter `status:` to `implemented` — unless the use case is
+ * superseded (its status says so, or it carries a `superseded_by`): a
+ * promotion, such as a `bug` fix on the part that still holds, must never
+ * hand the rest of it back its authority.
  *
  * A file with no frontmatter is copied verbatim: the use case belongs to the
  * author, and inventing a header would be a silent edit of their document.
@@ -93,7 +134,32 @@ function readFrontmatterField(content, key) {
  * @returns {string}
  */
 export function stampImplemented(content) {
-  return setFrontmatterField(content, 'status', 'implemented');
+  const superseded = readFrontmatterField(content, 'status') === SUPERSEDED
+    || readFrontmatterField(content, 'superseded_by') !== null;
+  return setFrontmatterField(content, 'status', superseded ? SUPERSEDED : 'implemented');
+}
+
+/**
+ * Carry the acervo's supersession onto an incoming copy that does not declare
+ * one — a copy taken before the revocation landed, or stripped of the fields
+ * on the way. Without this the promotion would publish the old use case as
+ * `implemented` again.
+ *
+ * @param {string} content  - the incoming copy
+ * @param {string|null} previous - the acervo entry it replaces
+ * @returns {{ content: string, supersededBy: string|null, scope: string|null }|null} null = nothing to carry
+ */
+function inheritSupersession(content, previous) {
+  if (!previous || readFrontmatterField(previous, 'status') !== SUPERSEDED) return null;
+  if (readFrontmatterField(content, 'status') === SUPERSEDED || readFrontmatterField(content, 'superseded_by') !== null) return null;
+  if (!hasFrontmatter(content)) return null;
+
+  const supersededBy = readFrontmatterField(previous, 'superseded_by');
+  const scope = readFrontmatterField(previous, 'scope');
+  let next = setFrontmatterField(content, 'status', SUPERSEDED);
+  if (supersededBy) next = setFrontmatterField(next, 'superseded_by', supersededBy);
+  if (scope !== null) next = setFrontmatterField(next, 'scope', JSON.stringify(scope));
+  return { content: next, supersededBy, scope };
 }
 
 /**
@@ -138,27 +204,24 @@ function collisionMessage({ id, incoming, existing, existingFeature, feature, re
  * @param {string} cwd        - project root that owns `.morph/specs/`
  * @param {string} featureDir - the feature folder holding `2-plan/usecases/`
  * @returns {{ promoted: string[], replaced: string[], refused: Array<{id: string,
- *   incoming: string, existing: string, existingFeature: string, message: string}> }}
- *   filenames, always arrays
+ *   incoming: string, existing: string, existingFeature: string, message: string}>,
+ *   keptSuperseded: Array<{id: string, file: string, supersededBy: string|null, scope?: string}> }}
+ *   always arrays; `keptSuperseded` = promoted copies that stayed superseded
+ *   because the acervo entry they replaced was
  */
 export function promoteUseCases(cwd, featureDir) {
-  const empty = { promoted: [], replaced: [], refused: [] };
+  const empty = { promoted: [], replaced: [], refused: [], keptSuperseded: [] };
   const srcDir = join(featureDir, UC.phaseDir, UC.dirname);
   const feature = basename(featureDir);
 
-  let names;
-  try {
-    if (!existsSync(srcDir)) return empty;
-    names = readdirSync(srcDir).filter((n) => UC_FILENAME_RE.test(n)).sort();
-  } catch {
-    return empty;
-  }
+  const names = [...useCaseFilesById(srcDir).values()].flat().sort();
   if (!names.length) return empty;
 
   const destDir = join(cwd, '.morph', 'specs', 'usecases');
   const promoted = [];
   const replaced = [];
   const refused = [];
+  const keptSuperseded = [];
 
   try {
     mkdirSync(destDir, { recursive: true });
@@ -173,18 +236,16 @@ export function promoteUseCases(cwd, featureDir) {
 
   // Existing archive entries, indexed by use-case ID — the key the overwrite
   // rule is written against.
-  const existingById = new Map();
-  try {
-    for (const name of readdirSync(destDir)) {
-      const id = UC_FILENAME_RE.test(name) ? useCaseId(name) : null;
-      if (id) existingById.set(id, name);
-    }
-  } catch { /* unreadable archive — treat as empty, never fatal */ }
+  const existingById = new Map([...useCaseFilesById(destDir)].map(([id, files]) => [id, files[files.length - 1]]));
 
   for (const name of names) {
     try {
       const id = useCaseId(name);
       const stale = id ? existingById.get(id) : null;
+      let previous = null;
+      if (stale) {
+        try { previous = readFileSync(join(destDir, stale), 'utf8'); } catch { /* unreadable — no signal */ }
+      }
 
       // Same ID under a different filename: normally the old file is dropped
       // (a slug reword, or the `bug` flow correcting a published UC), or the
@@ -202,8 +263,7 @@ export function promoteUseCases(cwd, featureDir) {
       // (no git common dir, or a legacy archive entry predating this stamp) is
       // fail-open: nothing to compare against, so nothing is refused.
       if (stale && stale !== name) {
-        let staleFeature = null;
-        try { staleFeature = readFrontmatterField(readFileSync(join(destDir, stale), 'utf8'), 'sourceFeature'); } catch { /* unreadable — no signal */ }
+        const staleFeature = previous === null ? null : readFrontmatterField(previous, 'sourceFeature');
         const incomingOwner = id ? reservationOwner(id, { cwd, gitCommonDir }) : null;
 
         if (staleFeature && staleFeature !== feature && incomingOwner === feature) {
@@ -224,13 +284,18 @@ export function promoteUseCases(cwd, featureDir) {
         replaced.push(stale);
       }
 
-      let content = stampImplemented(readFileSync(join(srcDir, name), 'utf8'));
-      content = stampSourceFeature(content, feature);
+      let content = readFileSync(join(srcDir, name), 'utf8');
+      const kept = inheritSupersession(content, previous);
+      if (kept) {
+        content = kept.content;
+        keptSuperseded.push({ id, file: name, supersededBy: kept.supersededBy, ...(kept.scope !== null ? { scope: kept.scope } : {}) });
+      }
+      content = stampSourceFeature(stampImplemented(content), feature);
       writeFileSync(join(destDir, name), content, 'utf8');
       promoted.push(name);
       if (id) existingById.set(id, name);
     } catch { /* one unreadable use case must not sink the rest */ }
   }
 
-  return { promoted, replaced, refused };
+  return { promoted, replaced, refused, keptSuperseded };
 }

package/src/lib/specs/usecase-registry.js

@@ -40,10 +40,9 @@ import {
 } from 'fs';
 import { join } from 'path';
 
-/** A UC filename's leading `UC-{nn}` — deliberately NOT imported from
- * `usecase-promoter.js`: that module will come to depend on THIS one (to look
- * up who reserved a given number), and a two-way import would be circular. */
-const UC_ID_RE = /^(UC-(\d+))-/;
+// From acervo-format.js, not usecase-promoter.js: the promoter depends on THIS
+// module (to look up who reserved a number), and a two-way import is circular.
+import { useCaseId } from './acervo-format.js';
 
 /** `UC-7` (or any width) -> `UC-07` — the archive's zero-padded convention. */
 function formatUcId(n) {
@@ -138,9 +137,10 @@ function maxUcNumberInDir(dir) {
   try {
     if (!existsSync(dir)) return 0;
     for (const name of readdirSync(dir)) {
-      const m = UC_ID_RE.exec(name);
-      if (!m) continue;
-      const n = parseInt(m[2], 10);
+      // Any `UC-{nn}-` prefix counts, canonical or not: a number already on disk is never handed out again.
+      const id = useCaseId(name);
+      if (!id) continue;
+      const n = parseInt(id.slice('UC-'.length), 10);
       if (Number.isFinite(n) && n > max) max = n;
     }
   } catch { /* unreadable dir — treat as empty, never fatal */ }

package/src/lib/tasks/tasks-json-parser.js

@@ -12,6 +12,7 @@ import fs from 'fs-extra';
 import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { UC_ID_RE } from '../specs/acervo-format.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SCHEMA_PATH = join(__dirname, '..', '..', '..', 'framework', 'schemas', 'tasks.schema.json');
@@ -26,8 +27,6 @@ export function getSchema() {
 const VALID_STATUS = ['pending', 'in_progress', 'done', 'skipped', 'blocked'];
 const VALID_EFFORT = ['S', 'M', 'L', 'XL'];
 const VALID_GROUP = ['backend', 'frontend', 'tests', 'infra', 'docs'];
-/** Use-case reference: the ID only (`UC-07`), never the filename. */
-const USECASE_RE = /^UC-\d+$/;
 /** Veredito de reuso por conceito — ver framework/schemas/tasks.schema.json. */
 const VALID_REUSE_VERDICT = ['REUSAR', 'ESTENDER', 'CRIAR'];
 
@@ -86,7 +85,7 @@ export function validateTasksJson(data) {
     // Optional: a task with no observable behaviour references no use case.
     // When present it must be the bare ID — `morph-spec dag` is the gate that
     // catches "UC-07-listar.md" or "UC7" before the plan reaches Gate 2.
-    if (task.usecase !== undefined && (typeof task.usecase !== 'string' || !USECASE_RE.test(task.usecase))) {
+    if (task.usecase !== undefined && (typeof task.usecase !== 'string' || !UC_ID_RE.test(task.usecase))) {
       errors.push(`${ctx}.usecase must match /^UC-\\d+$/ (the ID alone, e.g. "UC-07")`);
     }
 

package/src/lib/telemetry/metrics.js

@@ -0,0 +1,386 @@
+/**
+ * Loop measurements over the harness event stream: turns, tool calls split by
+ * orchestrator and sub-agent, time per command class, identical reruns, file
+ * rereads, feature-scope verify count, git calls per task and whether the
+ * reuse validator ran. Computed the same way on every window so a later
+ * window compares with an earlier one.
+ *
+ * Every number degrades to null ("not measurable here") when the stream lacks
+ * the field it needs — a v1 event never counts as a zero.
+ *
+ * A rerun is the same producer command (what runs before the output filter:
+ * `dotnet test | tail -25` then `| tail -20` is one test run twice) in the same
+ * feature within 10 minutes of its previous run. `rate` counts the repeats;
+ * `burstRate` counts every run that belongs to a burst, the first included.
+ */
+
+import { ingestedBytes } from './telemetry-reader.js';
+import { producerOf } from '../../../framework/hooks/shared/command-tokens.js';
+import { isFailedToolCall } from '../../../framework/hooks/shared/telemetry-logger.js';
+
+export const RERUN_WINDOW_MS = 10 * 60 * 1000;
+
+const RERUN_CLASSES = new Set(['test', 'build', 'verify']);
+const READ_ONLY = new Set(['grep', 'rg', 'sed', 'ls', 'cat', 'find', 'head', 'tail', 'wc', 'tree', 'awk']);
+const TOOL_EVENTS = new Set(['PostToolUse', 'PostToolUseFailure']);
+const NO_FEATURE = '\u0000';
+
+/**
+ * The command without quoted text and heredoc bodies: `morph-spec verify`
+ * inside a commit message is not a verify run.
+ */
+function executedText(command) {
+  const beforeHeredoc = command.split('<<', 1)[0];
+  return beforeHeredoc.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, (q) => q[0] + ' '.repeat(q.length - 2) + q[0]);
+}
+
+/**
+ * Kind (fine) and class (coarse) of a shell command. Searched anywhere in the
+ * command, most specific first, so `cd x && dotnet test` is a test.
+ *
+ * @param {string} command
+ * @returns {{ kind: string, klass: string }}
+ */
+export function classifyCommand(command) {
+  const cmd = String(command || '');
+  const verify = /\bmorph-spec(?:\.js)?\s+verify\s+[^\s;&|)]+(\s+T\d+\b)?/.exec(executedText(cmd));
+  if (verify) return { kind: verify[1] ? 'verify-task' : 'verify-feature', klass: 'verify' };
+  if (/\bdotnet\s+test\b/.test(cmd)) {
+    if (/--list-tests\b/.test(cmd)) return { kind: 'dotnet-test-list', klass: 'test' };
+    return { kind: /--filter\b/.test(cmd) ? 'dotnet-test-filtered' : 'dotnet-test-full', klass: 'test' };
+  }
+  if (/\b(?:(?:npm|pnpm|yarn)\s+(?:run\s+)?test|vitest|jest|node\s+--test|run-tests\.mjs)\b/.test(cmd)) {
+    return { kind: 'js-test', klass: 'test' };
+  }
+  if (/\b(?:dotnet\s+build|(?:npm|pnpm|yarn)\s+(?:run\s+)?build|next\s+build|tsc)\b/.test(cmd)) {
+    return { kind: 'build', klass: 'build' };
+  }
+  if (/\b(?:morph-spec\s+e2e|playwright\s+test|docker\s+compose\s+up)\b/.test(cmd)) return { kind: 'e2e', klass: 'e2e' };
+  const git = /\bgit\s+(?:-C\s+(?:"[^"]*"|\S+)\s+)?([a-z][a-z-]*)/.exec(cmd);
+  if (git) return { kind: `git-${git[1]}`, klass: 'git' };
+  const morph = /\bmorph-spec\s+([a-z][a-z-]*)/.exec(cmd);
+  if (morph) return { kind: `morph-spec-${morph[1]}`, klass: 'morph-spec' };
+  const first = cmd.trim().split(/\s+/, 1)[0];
+  if (READ_ONLY.has(first)) return { kind: first, klass: 'read' };
+  return { kind: 'other', klass: 'other' };
+}
+
+/** `git status` and `git diff` occurrences — `git status && git diff` is two calls. */
+function gitCalls(command) {
+  const text = executedText(String(command || ''));
+  const count = (sub) => (text.match(new RegExp(`\\bgit\\s+(?:-C\\s+(?:"[^"]*"|\\S+)\\s+)?${sub}\\b`, 'g')) || []).length;
+  return { status: count('status'), diff: count('diff') };
+}
+
+function median(values) {
+  const v = values.filter((x) => Number.isFinite(x)).sort((a, b) => a - b);
+  if (!v.length) return null;
+  const mid = Math.floor(v.length / 2);
+  return v.length % 2 ? v[mid] : (v[mid - 1] + v[mid]) / 2;
+}
+
+function rate(part, whole) {
+  return whole ? Math.round((part / whole) * 1000) / 1000 : null;
+}
+
+function isV2(e) {
+  return Number.isInteger(e.schemaVersion) && e.schemaVersion >= 2;
+}
+
+function whoOf(e) {
+  if (e.agentId) return 'subagent';
+  return isV2(e) ? 'orchestrator' : 'unknown';
+}
+
+function newCounters() {
+  return {
+    toolCalls: { total: 0, orchestrator: 0, subagent: 0, unknown: 0 },
+    turns: { total: 0, orchestrator: 0, subagent: 0, unknown: 0 },
+    timeByClass: {},
+    reruns: { runs: 0, reruns: 0, inBursts: 0 },
+    git: { status: 0, diff: 0 },
+    reads: { reads: 0, bytes: 0, redundantBytes: 0, windowed: 0 },
+  };
+}
+
+function addTime(counters, klass, durationMs) {
+  const slot = counters.timeByClass[klass] ||= { runs: 0, measuredMs: 0, unmeasured: 0 };
+  slot.runs += 1;
+  if (Number.isFinite(durationMs)) slot.measuredMs += durationMs;
+  else slot.unmeasured += 1;
+}
+
+function finishCounters(c, turnsObserved) {
+  return {
+    toolCalls: c.toolCalls,
+    turns: turnsObserved ? c.turns : null,
+    timeByClass: c.timeByClass,
+    reruns: { ...c.reruns, rate: rate(c.reruns.reruns, c.reruns.runs), burstRate: rate(c.reruns.inBursts, c.reruns.runs) },
+    git: c.git,
+    rereads: { ...c.reads, rate: rate(c.reads.redundantBytes, c.reads.bytes) },
+  };
+}
+
+/**
+ * Why a command ran again within the window. Edits in between and a changed
+ * output filter need no exit code; the pass/fail split does, so a masked or v1
+ * exit code falls back to "after an edit or not".
+ */
+function rerunClass(prev, current, editsBetween) {
+  if (isV2(prev) && prev.outcome === 'timeout') return 'timeout';
+  if (editsBetween === 0 && prev.command !== current.command) return 'refilter';
+  if (!isV2(prev) || !isV2(current) || prev.exitMasked || current.exitMasked) {
+    return editsBetween > 0 ? 'unknown-after-edit' : 'unknown-no-edit';
+  }
+  const prevFailed = prev.outcome === 'error' || (Number.isInteger(prev.exitCode) && prev.exitCode !== 0);
+  const nowFailed = current.outcome === 'error' || (Number.isInteger(current.exitCode) && current.exitCode !== 0);
+  if (prevFailed) {
+    if (editsBetween > 0) return 'fix-loop';
+    return nowFailed ? 'retry' : 'flake';
+  }
+  return editsBetween > 0 ? 're-verify' : 'redundant';
+}
+
+function reuseStateOf(e) {
+  const skipped = (e.nodes?.validators?.skipped || []).find((s) => s?.validator === 'reuse');
+  if (skipped) return { state: 'skipped', reason: skipped.reason || null };
+  if ((e.nodes?.validators?.ran || []).includes('reuse')) return { state: 'ran', reason: null };
+  return { state: 'absent', reason: null };
+}
+
+/**
+ * @param {Object[]} events - deduplicated, time-ordered (loadTelemetry)
+ * @param {{ feature?: string, top?: number }} [opts]
+ * @returns {Object} see framework/docs/CLI.md, "cost --metrics"
+ */
+export function computeMetrics(events, opts = {}) {
+  const top = Number.isInteger(opts.top) && opts.top > 0 ? opts.top : 10;
+  const scoped = (events || []).filter((e) => e && typeof e === 'object' && (!opts.feature || e.feature === opts.feature));
+
+  const global = newCounters();
+  const byFeature = new Map();
+  const openTask = new Map();
+  const tasks = [];
+  const lastRun = new Map();
+  const editCount = new Map();
+  const readsSeen = new Set();
+  const files = new Map();
+  const rerunClasses = {};
+  const rerunByKind = {};
+  const verifyByFeature = {};
+  const fullSuite = { runs: 0, withBuild: 0, byPhase: {} };
+  const lastFingerprint = new Map();
+  const unchangedRepeats = {};
+  const reuse = { runs: 0, byTree: {}, skipReasons: {} };
+  const tasksOf = new Map();
+  let callsInTaskWindows = 0;
+  let v2 = 0;
+  let legacy = 0;
+  let turnsObserved = false;
+  let from = null;
+  let to = null;
+
+  const featureCounters = (key) => {
+    if (!byFeature.has(key)) byFeature.set(key, newCounters());
+    return byFeature.get(key);
+  };
+  const closeTask = (key, endTs, status) => {
+    const task = openTask.get(key);
+    if (!task) return;
+    openTask.delete(key);
+    task.endTs = endTs;
+    task.status = status;
+    task.open = endTs === null;
+    tasks.push(task);
+  };
+
+  for (const e of scoped) {
+    if (isV2(e)) v2 += 1; else legacy += 1;
+    if (e.ts) {
+      from ??= e.ts;
+      to = e.ts;
+    }
+    const fkey = e.feature || NO_FEATURE;
+
+    if (e.event === 'TaskStart' && e.task) {
+      if (!tasksOf.has(fkey)) tasksOf.set(fkey, new Set());
+      tasksOf.get(fkey).add(e.task);
+      closeTask(fkey, null, null);
+      openTask.set(fkey, { feature: e.feature ?? null, task: e.task, startTs: e.ts, endTs: null, status: null, open: true, c: newCounters() });
+      continue;
+    }
+    if (e.event === 'TaskEnd' && e.task) {
+      if (openTask.get(fkey)?.task === e.task) closeTask(fkey, e.ts, e.status ?? null);
+      continue;
+    }
+
+    const sinks = [global, featureCounters(fkey)];
+    const task = openTask.get(fkey);
+    if (task) sinks.push(task.c);
+
+    if (e.event === 'ToolBatch') {
+      turnsObserved = true;
+      for (const c of sinks) { c.turns.total += 1; c.turns[whoOf(e)] += 1; }
+      continue;
+    }
+
+    if (e.event === 'Verify') {
+      if (e.scope === 'feature' && e.fingerprint && e.persisted !== false) {
+        if (lastFingerprint.get(fkey) === e.fingerprint) {
+          unchangedRepeats[e.feature || '(sem feature)'] = (unchangedRepeats[e.feature || '(sem feature)'] || 0) + 1;
+        }
+        lastFingerprint.set(fkey, e.fingerprint);
+      }
+      reuse.runs += 1;
+      const tree = e.tree || 'unknown';
+      const { state, reason } = reuseStateOf(e);
+      const slot = reuse.byTree[tree] ||= { ran: 0, skipped: 0, absent: 0 };
+      slot[state] += 1;
+      if (reason) reuse.skipReasons[reason] = (reuse.skipReasons[reason] || 0) + 1;
+      continue;
+    }
+
+    if (!TOOL_EVENTS.has(e.event) || !e.tool) continue;
+    for (const c of sinks) { c.toolCalls.total += 1; c.toolCalls[whoOf(e)] += 1; }
+    if (task) callsInTaskWindows += 1;
+
+    if (e.tool === 'Write' || e.tool === 'Edit') {
+      if (!isFailedToolCall(e)) editCount.set(fkey, (editCount.get(fkey) || 0) + 1);
+      continue;
+    }
+
+    if (e.tool === 'Read') {
+      const bytes = ingestedBytes(e);
+      if (bytes === null || !e.target) continue;
+      const window = `${fkey}\u0000${e.target}\u0000${e.offset || 1}\u0000${e.limit || 0}`;
+      const redundant = readsSeen.has(window) ? bytes : 0;
+      readsSeen.add(window);
+      for (const c of sinks) {
+        c.reads.reads += 1;
+        c.reads.bytes += bytes;
+        c.reads.redundantBytes += redundant;
+        if (Number.isFinite(e.bytesRead)) c.reads.windowed += 1;
+      }
+      const fileKey = `${fkey}\u0000${e.target}`;
+      const file = files.get(fileKey) || { feature: e.feature ?? null, file: e.target, reads: 0, bytes: 0, redundantBytes: 0 };
+      file.reads += 1;
+      file.bytes += bytes;
+      file.redundantBytes += redundant;
+      files.set(fileKey, file);
+      continue;
+    }
+
+    if (e.tool !== 'Bash' && e.tool !== 'PowerShell') continue;
+    const { kind, klass } = classifyCommand(e.command);
+    const git = gitCalls(e.command);
+    for (const c of sinks) {
+      addTime(c, klass, e.durationMs);
+      c.git.status += git.status;
+      c.git.diff += git.diff;
+    }
+
+    if (kind === 'dotnet-test-full') {
+      const rebuilds = !/--no-build\b/.test(e.command);
+      const phase = fullSuite.byPhase[e.phase || '-'] ||= { runs: 0, withBuild: 0 };
+      fullSuite.runs += 1;
+      phase.runs += 1;
+      if (rebuilds) { fullSuite.withBuild += 1; phase.withBuild += 1; }
+    }
+
+    if (klass === 'verify') {
+      const slot = verifyByFeature[e.feature || '(sem feature)'] ||= { feature: 0, task: 0 };
+      slot[kind === 'verify-feature' ? 'feature' : 'task'] += 1;
+    }
+
+    if (!RERUN_CLASSES.has(klass) || typeof e.command !== 'string') continue;
+    const runKey = `${fkey}\u0000${producerOf(e.command)}`;
+    const prev = lastRun.get(runKey);
+    const edits = editCount.get(fkey) || 0;
+    const t = Date.parse(e.ts ?? '');
+    const isRerun = Boolean(prev) && Number.isFinite(t) && t - prev.t <= RERUN_WINDOW_MS;
+    const kindSlot = rerunByKind[kind] ||= { runs: 0, reruns: 0, inBursts: 0 };
+    kindSlot.runs += 1;
+    for (const c of sinks) c.reruns.runs += 1;
+    const run = { t: Number.isFinite(t) ? t : 0, edits, event: e, sinks, kindSlot, inBurst: false };
+    if (isRerun) {
+      kindSlot.reruns += 1;
+      for (const c of sinks) c.reruns.reruns += 1;
+      // A burst counts its first run too; that one is only known once the
+      // second arrives, so it is credited to where it ran, late.
+      for (const r of prev.inBurst ? [run] : [prev, run]) {
+        r.inBurst = true;
+        r.kindSlot.inBursts += 1;
+        for (const c of r.sinks) c.reruns.inBursts += 1;
+      }
+      const why = rerunClass(prev.event, e, edits - prev.edits);
+      rerunClasses[why] = (rerunClasses[why] || 0) + 1;
+    }
+    lastRun.set(runKey, run);
+  }
+
+  for (const key of [...openTask.keys()]) closeTask(key, null, null);
+  tasks.sort((a, b) => String(a.startTs).localeCompare(String(b.startTs)));
+
+  const taskRows = tasks.map((t) => ({
+    feature: t.feature,
+    task: t.task,
+    startTs: t.startTs,
+    endTs: t.endTs,
+    open: t.open,
+    status: t.status,
+    ...finishCounters(t.c, turnsObserved),
+  }));
+
+  const featureRows = [...byFeature.entries()]
+    .filter(([key]) => key !== NO_FEATURE)
+    .map(([feature, c]) => ({
+      feature,
+      ...finishCounters(c, turnsObserved),
+      verify: verifyByFeature[feature] || { feature: 0, task: 0 },
+    }))
+    .sort((a, b) => b.toolCalls.total - a.toolCalls.total || a.feature.localeCompare(b.feature));
+
+  // A task window only holds what ran between its TaskStart and TaskEnd, and
+  // a parallel batch or a late `in_progress` leaves most calls outside any
+  // window. Dividing each feature's totals by its task count needs no window.
+  const perTaskOfFeature = (pick) => median(featureRows
+    .filter((f) => tasksOf.has(f.feature))
+    .map((f) => Math.round((pick(f) / tasksOf.get(f.feature).size) * 10) / 10));
+  const byKind = {};
+  for (const [kind, slot] of Object.entries(rerunByKind)) {
+    byKind[kind] = { ...slot, rate: rate(slot.reruns, slot.runs), burstRate: rate(slot.inBursts, slot.runs) };
+  }
+
+  return {
+    scope: { feature: opts.feature ?? null },
+    window: { from, to, events: scoped.length },
+    coverage: { v2, legacy },
+    ...finishCounters(global, turnsObserved),
+    rerunsByKind: byKind,
+    rerunClasses,
+    topRereads: [...files.values()]
+      .filter((f) => f.redundantBytes > 0)
+      .sort((a, b) => b.redundantBytes - a.redundantBytes || a.file.localeCompare(b.file))
+      .slice(0, top),
+    verify: {
+      byFeature: verifyByFeature,
+      featureScopeMedian: median(featureRows.map((f) => f.verify.feature).filter((n) => n > 0)),
+      unchangedRepeats,
+    },
+    gitPerTaskMedian: {
+      status: median(taskRows.map((t) => t.git.status)),
+      diff: median(taskRows.map((t) => t.git.diff)),
+    },
+    turnsPerTaskMedian: turnsObserved ? median(taskRows.map((t) => t.turns.total)) : null,
+    taskWindowCoverage: rate(callsInTaskWindows, global.toolCalls.total),
+    perTaskByFeature: {
+      git: perTaskOfFeature((f) => f.git.status + f.git.diff),
+      toolCalls: perTaskOfFeature((f) => f.toolCalls.total),
+      turns: turnsObserved ? perTaskOfFeature((f) => f.turns.total) : null,
+    },
+    dotnetFullSuite: fullSuite,
+    reuse,
+    features: featureRows,
+    tasks: taskRows,
+  };
+}