mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/planning-corpus.js

@@ -2,310 +2,36 @@
  * planning-corpus.js — corpus-aware context for the standalone-Story
  * planning path (Story #4432).
  *
- * `/plan --seed` previously drafted a standalone Story from a blank
- * slate: the seed, the body template, and a title-only duplicate scan.
- * For a change request that is really a small delta against an
- * already-delivered surface, that blank slate throws away context the
- * project already has — the docs digest and the relevant Tech Spec
- * sections of existing Epics that cover the touched area.
- *
- * This module assembles that inherited context (`corpusContext`) for
- * `story-plan.js`'s `--emit-context` envelope:
+ * `/plan --seed` drafts a standalone Story from the seed, the body
+ * template, and a title-only duplicate scan. This module assembles the
+ * inherited context (`corpusContext`) for `story-plan.js`'s
+ * `--emit-context` envelope:
  *
  *   1. `docsDigest` — the same per-project docs digest
  *      `orchestration/docs-digest.js` builds for `/deliver` Story
  *      children, reused here so the standalone path gets the same
  *      compact outline instead of re-reading the whole docs set.
  *      `null` when `project.docsContextFiles` is not configured.
- *   2. `relevantSections` — a ranked list of existing Epic Tech Spec
- *      (or lede, when no Tech Spec region exists) excerpts that overlap
- *      with the seed, so the draft can build on prior art instead of
- *      re-deriving it.
- *
- * The historical Epic list surface (`provider.getEpics`) returns a
- * list-scale payload with no `body`. Body content therefore requires an
- * **explicit**, bounded per-candidate fetch via `provider.getEpic(id)` —
- * never a silent assumption that the list response carries prose to score
- * against.
- *
- * Relevance scoring reuses the same `tokenize` / `overlapScore` Jaccard
- * primitives `duplicate-search.js` exports for Epic-dedupe and
- * `story-plan.js` reuses for Story-dedupe — one matcher, three
- * consumers, no forked scoring logic.
+ *   2. `relevantSections` — always `[]`. This field previously carried
+ *      ranked Tech Spec excerpts mined from open Epics. v2.0.0 removed
+ *      the Epic tier, and the provider's Epic-list surface was reduced
+ *      to a `return []` stub, which made the entire ranking pipeline a
+ *      permanent no-op. The pipeline has been removed; the field is
+ *      retained so the envelope shape stays stable for its consumers.
  */
 
-import { overlapScore, tokenize } from './duplicate-search.js';
-import { Logger } from './Logger.js';
 import { buildDocsDigest } from './orchestration/docs-digest.js';
-import {
-  extractTicketSection,
-  hasTicketSection,
-} from './ticket-body-sections.js';
-
-/** Top-K Epics kept after the cheap title-only ranking pass. */
-const DEFAULT_CORPUS_MAX_CANDIDATES = 5;
-
-/**
- * Bound on the explicit per-candidate body fetch. Keeps corpus-context
- * assembly at a fixed, small number of GitHub reads regardless of how
- * many open Epics the repo carries.
- */
-export const DEFAULT_CORPUS_BODY_FETCH_TOP_K = 3;
-
-/** Minimum Jaccard overlap for a section excerpt to be worth surfacing. */
-const DEFAULT_CORPUS_MIN_SCORE = 0.1;
-
-/** Max relevant-section excerpts returned in the envelope. */
-const DEFAULT_CORPUS_MAX_SECTIONS = 5;
-
-/** Excerpt length cap (chars) so one oversized Tech Spec doesn't blow the envelope. */
-const EXCERPT_MAX_CHARS = 600;
-
-/**
- * Page-scan cap passed to `provider.getEpics({ state: 'open', pageCap })`.
- * The corpus lookup only ever ranks the list down to a top-5 shortlist
- * (`DEFAULT_CORPUS_MAX_CANDIDATES`), so there is no need to inherit
- * `paginateRest`'s full default ceiling (50 pages / 5000 items) to build
- * it — a bounded scan keeps this call a fixed, small number of GitHub
- * reads regardless of how many open Epics the repo carries.
- */
-const CORPUS_EPICS_PAGE_CAP = 5;
-
-/**
- * Rank open Epics by title-overlap with the seed. This is the cheap
- * first pass over the list surface (title only — no `body`), used solely
- * to pick the bounded top-K candidates
- * worth an explicit body fetch. It is not the final relevance signal;
- * `extractRelevantSections` re-scores against actual section content.
- *
- * @param {{ seed: string, epics: Array<{ id:number, title:string }>, maxResults?: number }} opts
- * @returns {Array<{ id:number, title:string, score:number }>}
- */
-export function rankCandidateEpics({
-  seed,
-  epics,
-  maxResults = DEFAULT_CORPUS_MAX_CANDIDATES,
-}) {
-  if (!seed || typeof seed !== 'string') {
-    throw new Error('rankCandidateEpics: seed must be a non-empty string');
-  }
-  if (!Array.isArray(epics)) {
-    throw new Error('rankCandidateEpics: epics must be an array');
-  }
-  const seedTokens = tokenize(seed);
-  if (seedTokens.size === 0) return [];
-
-  const ranked = [];
-  for (const epic of epics) {
-    if (!epic || typeof epic.title !== 'string') continue;
-    const score = overlapScore(seedTokens, tokenize(epic.title));
-    ranked.push({
-      id: epic.id,
-      title: epic.title,
-      score: Number(score.toFixed(4)),
-    });
-  }
-  ranked.sort((a, b) => b.score - a.score);
-  return ranked.slice(0, maxResults);
-}
-
-/**
- * Fetch full bodies for the top-K ranked candidates via the single-issue
- * read (`provider.getEpic`), which — unlike the `getEpics` list mapper —
- * does carry `body`. This is the explicit, bounded fetch the corpus
- * lookup performs instead of assuming the list surface already has
- * prose to score: a candidate never contributes a relevant section
- * without this round-trip resolving its body.
- *
- * A single candidate's fetch failing (deleted issue, transient error) is
- * non-fatal — it is dropped from the result rather than aborting corpus
- * assembly for every other candidate. Failures are logged via
- * `Logger.debug` (stderr) so they are visible under
- * `AGENT_LOG_LEVEL=verbose` triage without violating the friction-
- * telemetry posture in `.agents/instructions.md` §1.H of never silently
- * swallowing an error.
- *
- * The bounded candidate slice is fetched concurrently
- * (`Promise.allSettled`) rather than sequentially — `topK` is a fixed
- * small ceiling (default 3), so this is a bounded fan-out, not an
- * unbounded one, and it removes the serial network-latency stacking a
- * plain `for`-await loop would otherwise incur.
- *
- * @param {{ provider: object, candidates: Array<{ id:number, title:string }>, topK?: number }} opts
- * @returns {Promise<Array<{ id:number, title:string, body:string }>>}
- */
-export async function fetchCandidateBodies({
-  provider,
-  candidates,
-  topK = DEFAULT_CORPUS_BODY_FETCH_TOP_K,
-}) {
-  if (!provider || typeof provider.getEpic !== 'function') return [];
-  if (!Array.isArray(candidates) || candidates.length === 0) return [];
-
-  const bounded = candidates.slice(0, topK);
-  const settled = await Promise.allSettled(
-    bounded.map(async (candidate) => {
-      const epic = await provider.getEpic(candidate.id);
-      return {
-        id: candidate.id,
-        title: candidate.title ?? epic?.title ?? '',
-        body: epic?.body ?? '',
-      };
-    }),
-  );
-
-  const results = [];
-  for (let i = 0; i < settled.length; i += 1) {
-    const outcome = settled[i];
-    if (outcome.status === 'fulfilled') {
-      results.push(outcome.value);
-      continue;
-    }
-    // Best-effort: one candidate failing to resolve must not abort
-    // corpus-context assembly for the rest — but the failure is still
-    // surfaced for triage rather than silently swallowed.
-    Logger.debug(
-      `[planning-corpus] fetchCandidateBodies: candidate #${bounded[i].id} failed to resolve: ${outcome.reason?.message ?? outcome.reason}`,
-    );
-  }
-  return results;
-}
-
-/**
- * Extract a scoreable excerpt from an Epic body: the managed Tech Spec
- * region when present (the folded `## Delivery Slicing` section, #4324),
- * otherwise the ideation lede — the prose before the first `##` heading
- * — so a plain-body Epic still contributes something to score.
- *
- * @param {string} body
- * @returns {{ kind:'techSpec'|'lede', content:string }}
- */
-function extractScoreableExcerpt(body) {
-  if (hasTicketSection(body, 'techSpec')) {
-    return {
-      kind: 'techSpec',
-      content: extractTicketSection(body, 'techSpec'),
-    };
-  }
-  const lede = (body ?? '').split(/^##\s+/m)[0].trim();
-  return { kind: 'lede', content: lede };
-}
-
-/**
- * Rank existing-Epic body excerpts (Tech Spec section, or lede) by
- * overlap with the seed. Reuses the same `tokenize` / `overlapScore`
- * primitives as the title-ranking pass above and as
- * `duplicate-search.js` — one matcher shared across every corpus /
- * dedupe surface.
- *
- * @param {{ seed:string, epicBodies: Array<{ id:number, title:string, body:string }>, maxResults?: number, minScore?: number }} opts
- * @returns {Array<{ epicId:number, epicTitle:string, section:'techSpec'|'lede', score:number, excerpt:string }>}
- */
-export function extractRelevantSections({
-  seed,
-  epicBodies,
-  maxResults = DEFAULT_CORPUS_MAX_SECTIONS,
-  minScore = DEFAULT_CORPUS_MIN_SCORE,
-}) {
-  if (!seed || typeof seed !== 'string') {
-    throw new Error('extractRelevantSections: seed must be a non-empty string');
-  }
-  if (!Array.isArray(epicBodies)) {
-    throw new Error('extractRelevantSections: epicBodies must be an array');
-  }
-  const seedTokens = tokenize(seed);
-  if (seedTokens.size === 0) return [];
-
-  const ranked = [];
-  for (const epic of epicBodies) {
-    if (!epic) continue;
-    const { kind, content } = extractScoreableExcerpt(epic.body ?? '');
-    if (!content) continue;
-    const score = overlapScore(seedTokens, tokenize(content));
-    if (score < minScore) continue;
-    ranked.push({
-      epicId: epic.id,
-      epicTitle: epic.title ?? null,
-      section: kind,
-      score: Number(score.toFixed(4)),
-      excerpt: content.slice(0, EXCERPT_MAX_CHARS),
-    });
-  }
-  ranked.sort((a, b) => b.score - a.score);
-  return ranked.slice(0, maxResults);
-}
 
 /**
  * Assemble the `corpusContext` field of the story-plan context envelope.
- * Pure orchestration over the three helpers above plus `buildDocsDigest`
- * — no I/O beyond what `provider` and the docs-digest reader perform.
- *
- * `relevantSections` is `[]` (not an error) when the provider has no
- * `getEpics` surface, the seed tokenizes to nothing, or no candidate
- * clears `minScore` — the standalone-Story draft path degrades to
- * exactly today's blank-slate behavior in that case.
  *
  * @param {{
- *   seed: string,
- *   provider?: { getEpics?: Function, getEpic?: Function },
  *   docsContextFiles?: string[],
  *   docsRoot?: string,
- *   maxCandidates?: number,
- *   bodyFetchTopK?: number,
- *   maxSections?: number,
- *   minScore?: number,
  * }} opts
  * @returns {Promise<{ docsDigest: string|null, relevantSections: Array<object> }>}
  */
-export async function buildCorpusContext({
-  seed,
-  provider,
-  docsContextFiles,
-  docsRoot,
-  maxCandidates = DEFAULT_CORPUS_MAX_CANDIDATES,
-  bodyFetchTopK = DEFAULT_CORPUS_BODY_FETCH_TOP_K,
-  maxSections = DEFAULT_CORPUS_MAX_SECTIONS,
-  minScore = DEFAULT_CORPUS_MIN_SCORE,
-}) {
+export async function buildCorpusContext({ docsContextFiles, docsRoot }) {
   const docsDigest = await buildDocsDigest({ docsContextFiles, docsRoot });
-
-  let relevantSections = [];
-  if (provider && typeof provider.getEpics === 'function') {
-    // A single candidate-listing call failing (rate limit, transient
-    // network error, provider outage) must not abort the whole
-    // `--emit-context` envelope build — degrade to an empty candidate
-    // list instead of letting the rejection propagate out of the
-    // caller's `Promise.all` and take down the rest of the envelope
-    // (body template, tech-stack summary, docs digest) with it.
-    let epics = [];
-    try {
-      epics = await provider.getEpics({
-        state: 'open',
-        pageCap: CORPUS_EPICS_PAGE_CAP,
-      });
-    } catch (err) {
-      Logger.debug(
-        `[planning-corpus] buildCorpusContext: provider.getEpics failed, degrading to an empty candidate list: ${err?.message ?? err}`,
-      );
-      epics = [];
-    }
-    const ranked = rankCandidateEpics({
-      seed,
-      epics: Array.isArray(epics) ? epics : [],
-      maxResults: maxCandidates,
-    });
-    const bodies = await fetchCandidateBodies({
-      provider,
-      candidates: ranked,
-      topK: bodyFetchTopK,
-    });
-    relevantSections = extractRelevantSections({
-      seed,
-      epicBodies: bodies,
-      maxResults: maxSections,
-      minScore,
-    });
-  }
-
-  return { docsDigest, relevantSections };
+  return { docsDigest, relevantSections: [] };
 }

package/.agents/scripts/lib/preflight-runner.js

@@ -52,8 +52,8 @@ const DEFAULT_LOGGER = {
  * flag, finding/fix routing, and pretty-print of the blocker table.
  *
  * @param {object} opts
- * @param {string} opts.scope          Consumer surface — `'epic-close'`,
- *   `'story-close'`, `'npm-test'`, etc.
+ * @param {string} opts.scope          Consumer surface — `'story-close'`,
+ *   `'npm-test'`, `'diagnose'`, etc.
  * @param {boolean} [opts.autoFix=true] Forwarded to `runChecks`. Defaults
  *   to `true` because every wiring call site at this Story's level wants
  *   auto-correction (the `retro` consumer that needs `autoFix:false` does

package/.agents/scripts/lib/qa/qa-context-hydrator.js

@@ -142,7 +142,7 @@ export async function verifySurfaceMap(surfaceMap, gitPort, baseRef) {
  * with no network when the ports are fakes.
  *
  * @param {{
- *   epicNumber: number,
+ *   ticketNumber: number,
  *   githubPort: GithubPort,
  *   gitPort: GitPort,
  *   surfaceMap?: SurfaceMapEntry[],
@@ -162,7 +162,7 @@ export async function verifySurfaceMap(surfaceMap, gitPort, baseRef) {
  */
 export async function hydrateQaContext(opts) {
   const {
-    epicNumber,
+    ticketNumber,
     githubPort,
     gitPort,
     surfaceMap = [],
@@ -172,9 +172,9 @@ export async function hydrateQaContext(opts) {
     fsImpl,
   } = opts ?? {};
 
-  if (!Number.isInteger(epicNumber)) {
+  if (!Number.isInteger(ticketNumber)) {
     throw new Error(
-      'hydrateQaContext: `epicNumber` is required and must be an integer',
+      'hydrateQaContext: `ticketNumber` is required and must be an integer',
     );
   }
   if (!githubPort || typeof githubPort.fetchIssue !== 'function') {
@@ -192,7 +192,7 @@ export async function hydrateQaContext(opts) {
     );
   }
 
-  const epicIssue = await githubPort.fetchIssue(epicNumber);
+  const epicIssue = await githubPort.fetchIssue(ticketNumber);
   const epic = {
     number: epicIssue.number,
     body: epicIssue.body ?? '',

package/.agents/scripts/lib/signals/index.js

@@ -10,8 +10,8 @@
  *     + `schema`; `buildSpanTree` was a throwing placeholder.
  *   - Epic #1181 / Story #1440 / Task #1461 — placeholder replaced by
  *     the real export from `./span-tree.js`.
- *   - Story #1476 — `appendSignal` / `appendTrace` / `appendEpicSignal`
- *     re-exported here via `./write.js` so the gate scripts (and any
+ *   - Story #1476 — `appendSignal` / `appendTrace` re-exported here
+ *     via `./write.js` so the gate scripts (and any
  *     new code) converge on `lib/signals/` instead of importing the
  *     writer directly from `lib/observability/`.
  *
@@ -21,19 +21,6 @@
 import { read } from './read.js';
 import * as schema from './schema.js';
 import { buildSpanTree } from './span-tree.js';
-import {
-  appendEpicSignal,
-  appendSignal,
-  appendTrace,
-  forEachLine,
-} from './write.js';
+import { appendSignal, appendTrace, forEachLine } from './write.js';
 
-export {
-  appendEpicSignal,
-  appendSignal,
-  appendTrace,
-  buildSpanTree,
-  forEachLine,
-  read,
-  schema,
-};
+export { appendSignal, appendTrace, buildSpanTree, forEachLine, read, schema };

package/.agents/scripts/lib/signals/read.js

@@ -1,18 +1,18 @@
 /**
  * Streaming signals reader (Epic #1181 / Story #1438 / Task #1459).
  *
- * Provides one async-iterator entry point — `read({ epic, story?, kind?,
+ * Provides one async-iterator entry point — `read({ run, story?, kind?,
  * config? })` — that consumers use instead of opening the NDJSON file
  * themselves. The reader streams line-by-line so callers never load the
  * full file into memory (50MB+ traces stay under file size in RSS).
  *
  * On-disk layout (resolved via `lib/config/temp-paths.js`):
  *
- *   <tempRoot>/epic-<epic>/story-<story>/signals.ndjson
+ *   <tempRoot>/run-<run>/story-<story>/signals.ndjson
  *
  * When `story` is omitted, the reader fans out across every
- * `story-<id>/signals.ndjson` under `<tempRoot>/epic-<epic>/`. When the
- * Epic directory is missing, the iterator yields nothing (consumers
+ * `story-<id>/signals.ndjson` under `<tempRoot>/run-<run>/`. When the
+ * run directory is missing, the iterator yields nothing (consumers
  * treat absence as "no signals yet").
  *
  * ## Filter semantics
@@ -21,7 +21,7 @@
  *     argument are yielded. Filtering happens after the per-line JSON
  *     parse + envelope guard (see `lib/signals/schema.js`).
  *   - `story` — narrows to a single Story's stream; otherwise we walk
- *     every Story directory under the Epic.
+ *     every Story directory under the run.
  *
  * ## Warn-once policy (AC #3)
  *
@@ -46,8 +46,8 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 import {
-  epicArtifactPath,
-  epicTempDir,
+  runArtifactPath,
+  runTempDir,
   signalsFile,
   storyTempDir,
 } from '../config/temp-paths.js';
@@ -145,43 +145,43 @@ async function* streamFile(target, kindFilter) {
 }
 
 /**
- * List every `stories/story-<id>/signals.ndjson` path under the Epic's
- * `<tempRoot>/epic-<epic>/` directory. Returns an empty array when the
- * Epic directory is missing.
+ * List every `stories/story-<id>/signals.ndjson` path under the run's
+ * `<tempRoot>/run-<run>/` directory. Returns an empty array when the
+ * run directory is missing.
  *
  * The returned paths are sorted by Story ID ascending so the iterator's
  * output is stable across runs.
  *
  * Story #2940 nested per-Story directories under a `stories/` segment.
- * Epic-level signals continue to live at the Epic root.
+ * Run-level signals continue to live at the run root.
  *
- * @param {number} epic
+ * @param {number} run
  * @param {object | undefined} config
  * @returns {Promise<string[]>}
  */
-async function listEpicStorySignalsFiles(epic, config) {
-  const epicDir = epicTempDir(epic, config);
-  let epicEntries;
+async function listRunStorySignalsFiles(run, config) {
+  const runDir = runTempDir(run, config);
+  let runEntries;
   try {
-    epicEntries = await fs.readdir(epicDir, { withFileTypes: true });
+    runEntries = await fs.readdir(runDir, { withFileTypes: true });
   } catch {
     return [];
   }
-  let hasEpicLevelSignals = false;
+  let hasRunLevelSignals = false;
   let hasStoriesDir = false;
-  for (const ent of epicEntries) {
+  for (const ent of runEntries) {
     if (ent.isDirectory() && ent.name === 'stories') {
       hasStoriesDir = true;
     } else if (ent.isFile() && ent.name === 'signals.ndjson') {
       // Story #1430 — wave-runner lifecycle signals land here.
-      hasEpicLevelSignals = true;
+      hasRunLevelSignals = true;
     }
   }
   const storyIds = [];
   if (hasStoriesDir) {
     let storyEntries;
     try {
-      storyEntries = await fs.readdir(path.join(epicDir, 'stories'), {
+      storyEntries = await fs.readdir(path.join(runDir, 'stories'), {
         withFileTypes: true,
       });
     } catch {
@@ -195,43 +195,43 @@ async function listEpicStorySignalsFiles(epic, config) {
     }
   }
   storyIds.sort((a, b) => a - b);
-  // Yield epic-level signals first (wave-start precedes per-Story friction),
+  // Yield run-level signals first (wave-start precedes per-Story friction),
   // then walk the per-Story streams in ascending ID order.
-  const targets = hasEpicLevelSignals
-    ? [epicArtifactPath(epic, 'signals.ndjson', config)]
+  const targets = hasRunLevelSignals
+    ? [runArtifactPath(run, 'signals.ndjson', config)]
     : [];
   for (const sid of storyIds) {
-    targets.push(path.join(storyTempDir(epic, sid, config), 'signals.ndjson'));
+    targets.push(path.join(storyTempDir(run, sid, config), 'signals.ndjson'));
   }
   return targets;
 }
 
 /**
- * Stream every event matching `{ epic, story?, kind? }` from the
- * configured `tempRoot`'s `epic-<epic>/[story-<story>/]signals.ndjson`
+ * Stream every event matching `{ run, story?, kind? }` from the
+ * configured `tempRoot`'s `run-<run>/[story-<story>/]signals.ndjson`
  * file(s).
  *
  * Returns an async iterable so callers can `for await` over it without
  * buffering. The reader is **streaming** — peak memory stays below the
  * file size for any input.
  *
- * @param {{ epic: number, story?: number, kind?: string, config?: object }} args
+ * @param {{ run: number, story?: number, kind?: string, config?: object }} args
  * @returns {AsyncGenerator<object>}
  *
  * @example
- *   for await (const evt of read({ epic: 1181 })) { ... }
- *   for await (const evt of read({ epic: 1181, story: 1438, kind: 'friction' })) { ... }
+ *   for await (const evt of read({ run: 1181 })) { ... }
+ *   for await (const evt of read({ run: 1181, story: 1438, kind: 'friction' })) { ... }
  */
 export async function* read(args) {
   if (args == null || typeof args !== 'object') {
     throw new TypeError(
-      `signals/read: args must be an object with at minimum { epic }; got ${args}`,
+      `signals/read: args must be an object with at minimum { run }; got ${args}`,
     );
   }
-  const { epic, story, kind, config } = args;
-  if (!isPositiveInt(epic)) {
+  const { run, story, kind, config } = args;
+  if (!isPositiveInt(run)) {
     throw new RangeError(
-      `signals/read: epic must be a positive integer (got ${epic})`,
+      `signals/read: run must be a positive integer (got ${run})`,
     );
   }
   if (story !== undefined && !isPositiveInt(story)) {
@@ -259,8 +259,8 @@ export async function* read(args) {
   const kindFilter = kind ?? null;
   const targets =
     story !== undefined
-      ? [signalsFile(epic, story, config)]
-      : await listEpicStorySignalsFiles(epic, config);
+      ? [signalsFile(run, story, config)]
+      : await listRunStorySignalsFiles(run, config);
 
   for (const target of targets) {
     yield* streamFile(target, kindFilter);

package/.agents/scripts/lib/signals/schema.js

@@ -3,7 +3,7 @@
  * shape guards (Epic #1181 / Story #1438 / Task #1458).
  *
  * Both writers (`lib/observability/signals-writer.js` callers) and
- * readers (`lib/signals/read.js`, `lib/observability/perf-aggregator.js`)
+ * readers (`lib/signals/read.js`, the retro's gather-signals phase)
  * import their field names from this module so the on-disk NDJSON shape
  * stays under one schema.
  *
@@ -19,15 +19,12 @@
  *
  * Signals-writer `appendSignal` call sites:
  *   - `friction`       — quality-gate / runtime friction (diagnose-friction.js,
- *                        lib/gates/friction.js, auto-refresh-runner.js,
- *                        worktree-reap.js, lifecycle-emit.js)
+ *                        lib/gates/friction.js)
  *   - `acceptance-eval` — acceptance-eval.js per-criterion terminus signal.
- *   - `wave-start` / `wave-complete` — `lib/wave-runner/tick.js` (read by
- *                        perf-aggregator's `waveParallelism` report;
- *                        `wave-start` also anchors span-tree Story spans)
+ *   - `wave-start` / `wave-complete` — wave-window anchors; `wave-start` also
+ *                        anchors span-tree Story spans
  *   - `wave-end`       — span-tree pairing anchor (retained for span-tree)
- *   - `state-transition` — notification-derived window anchor read by the
- *                        waveParallelism bucketer.
+ *   - `state-transition` — notification-derived window anchor.
  *
  * The `dispatched` kind was deleted in the Epic #4406 signal-contract
  * cutover — it had no live emitter and no consumer.
@@ -80,9 +77,9 @@ export const EVENT_KINDS = Object.freeze({
   FRICTION: 'friction',
   TRACE: 'trace',
   // Wave-window forensics signals: `wave-start` / `wave-end` anchor the
-  // span-tree's Story spans, and the perf-aggregator brackets each wave's
-  // wall-clock from `wave-start` → `wave-complete` (the `waveParallelism`
-  // report). These are READ — they survive.
+  // span-tree's Story spans. Story #4545 deleted the `waveParallelism`
+  // consumer (perf-aggregator) with the execution-analysis surface; these
+  // kinds stay as the span-tree's anchors.
   WAVE_START: 'wave-start',
   WAVE_END: 'wave-end',
   WAVE_COMPLETE: 'wave-complete',

package/.agents/scripts/lib/signals/span-tree.js

@@ -192,15 +192,15 @@ function bootstrapStoryWindow(storyNode, ts) {
  * from `buildSpanTree` so the outer function's CRAP score stays under
  * the new-method ceiling.
  *
- * @param {object} state — mutable accumulator (stories, tasksByStory, epic)
+ * @param {object} state — mutable accumulator (stories, tasksByStory, run)
  * @param {unknown} evt
  * @returns {void}
  */
 function ingestEvent(state, evt) {
   if (evt == null || typeof evt !== 'object') return;
 
-  const eEpic = epicOf(evt);
-  if (state.epic == null && eEpic != null) state.epic = eEpic;
+  const eRun = epicOf(evt);
+  if (state.run == null && eRun != null) state.run = eRun;
 
   const ts = tsOf(evt);
   const sid = storyOf(evt);
@@ -258,11 +258,11 @@ function finalizeStory(state, story) {
  * Build the span tree from an async iterable of signal events.
  *
  * @param {AsyncIterable<object> | Iterable<object>} iter
- * @returns {Promise<{ epic: number | null, stories: Array<object> }>}
+ * @returns {Promise<{ run: number | null, stories: Array<object> }>}
  *
  * @example
  *   import { read, buildSpanTree } from './lib/signals/index.js';
- *   const tree = await buildSpanTree(read({ epic: 1181 }));
+ *   const tree = await buildSpanTree(read({ run: 1181 }));
  */
 export async function buildSpanTree(iter) {
   if (iter == null || typeof iter !== 'object') {
@@ -274,7 +274,7 @@ export async function buildSpanTree(iter) {
   // Accumulator state. `stories` keys are `storyKeyOf(sid)` strings;
   // `tasksByStory` mirrors that and holds per-task sub-maps.
   const state = {
-    epic: null,
+    run: null,
     stories: new Map(),
     tasksByStory: new Map(),
   };
@@ -287,5 +287,5 @@ export async function buildSpanTree(iter) {
   storyEntries.sort(compareNodeIds);
   for (const story of storyEntries) finalizeStory(state, story);
 
-  return { epic: state.epic, stories: storyEntries };
+  return { run: state.run, stories: storyEntries };
 }

package/.agents/scripts/lib/signals/write.js

@@ -12,7 +12,6 @@
  */
 
 export {
-  appendEpicSignal,
   appendSignal,
   appendTrace,
   forEachLine,