mandrel 1.87.0 → 1.89.0

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

@@ -0,0 +1,306 @@
+/**
+ * planning-corpus.js — corpus-aware context for the standalone-Story
+ * planning path (Story #4432).
+ *
+ * `/plan --idea` 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:
+ *
+ *   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 Epic list surface (`provider.getEpics`) maps every issue through
+ * `issueToEpicListItem`, which deliberately omits `body` (a list-scale
+ * payload trim). 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.
+ */
+
+import { overlapScore, tokenize } from './duplicate-search.js';
+import { extractEpicSection, hasEpicSection } from './epic-body-sections.js';
+import { Logger } from './Logger.js';
+import { buildDocsDigest } from './orchestration/docs-digest.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 — `issueToEpicListItem`
+ * has 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 (hasEpicSection(body, 'techSpec')) {
+    return { kind: 'techSpec', content: extractEpicSection(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,
+}) {
+  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 };
+}

package/.agents/scripts/lib/signals/detectors/common.js

@@ -1,7 +1,7 @@
 /**
  * detectors/common.js — shared helpers for the signals layer.
  *
- * Hoisted out of three detector modules (hotspot, retry, rework) plus
+ * Hoisted out of the detector modules (retry, rework) plus
  * `signals/read.js` and `signals/schema.js`, all of which shipped
  * byte-equivalent copies of these predicates. See Story #2464.
  */
@@ -19,15 +19,15 @@ export function isPositiveInt(v) {
 
 /**
  * Pull the tool name from a trace record. The hook writes the tool name
- * into `source.tool` and (defensively) into `details.tool` — we accept
- * either so older traces still classify correctly.
+ * into `emitter.tool` (canonical provenance) and, defensively, into
+ * `details.tool` — we accept either.
  *
  * @param {object} rec
  * @returns {string|null}
  */
 export function extractTool(rec) {
-  if (typeof rec?.source?.tool === 'string' && rec.source.tool.length > 0) {
-    return rec.source.tool;
+  if (typeof rec?.emitter?.tool === 'string' && rec.emitter.tool.length > 0) {
+    return rec.emitter.tool;
   }
   if (typeof rec?.details?.tool === 'string' && rec.details.tool.length > 0) {
     return rec.details.tool;
@@ -38,12 +38,12 @@ export function extractTool(rec) {
 /**
  * Validate and normalize the shared detector argument preamble.
  *
- * `detectRework`, `detectRetry`, and `detectHotspot` previously shipped a
- * near-identical guard block: the `args` object-shape `TypeError`, the
- * `nowFn` function-type `TypeError`, the positive-integer `RangeError`s for
- * the id fields, the non-empty-string `tracesPath` check, and the
+ * `detectRework` and `detectRetry` previously shipped a near-identical
+ * guard block: the `args` object-shape `TypeError`, the `nowFn`
+ * function-type `TypeError`, the positive-integer `RangeError`s for the id
+ * fields, the non-empty-string `tracesPath` check, and the
  * non-negative-integer `threshold` check. Story #4077 hoists that preamble
- * here so the three detectors share one error-message contract.
+ * here so the detectors share one error-message contract.
  *
  * Error wording stays per-detector-accurate by prefixing every message with
  * `fnName` (e.g. `detectRework: …`). Error *types* are preserved exactly:

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

@@ -2,13 +2,13 @@
  * Detectors barrel (Epic #1721 / Story #1771 / Task #1774).
  *
  * Single import surface for every signal detector. Detector Stories
- * (rework in #1771, retry in #1768, hotspot in #1769) re-export from
- * here so callers (`lib/observability/perf-aggregator.js`, future
- * emission orchestrators) only ever import from one place.
+ * (rework in #1771, retry in #1768) re-export from here so callers
+ * (`lib/orchestration/detectors-phase.js`) only ever import from one
+ * place. The Epic #1769 hotspot detector was retired in the Epic #4406
+ * signal-contract cutover (no live emitter, no consumer).
  *
  * @module lib/signals/detectors
  */
 
-export { detectHotspot, nearestRankP95 } from './hotspot.js';
 export { detectRetry } from './retry.js';
 export { detectRework } from './rework.js';

package/.agents/scripts/lib/signals/detectors/retry.js

@@ -27,11 +27,12 @@
  * ## Failure rule
  *
  * A trace record is treated as **failed** when its `details.exitCode`
- * is a number and not `0`. The hook does not itself capture the exit
- * code today (the field is set by callers / future hook extensions);
- * records without an `exitCode` field are ignored, which matches the
- * decision in the parent Epic body that retry only counts non-zero-exit
- * commands.
+ * is a number and not `0`. As of Epic #4406 / Story #4413 the tool-trace
+ * hook captures `details.exitCode` for Bash `PostToolUse` events, so this
+ * detector fires on real deliveries; records without an `exitCode` field
+ * (non-Bash tools, or tools that report no exit code) are ignored, which
+ * matches the decision in the parent Epic body that retry only counts
+ * non-zero-exit commands.
  *
  * Successful runs after failures **do not** cancel the count — failure-
  * count is monotonic per identity. This matches the Epic's intent: once
@@ -41,12 +42,11 @@
  *
  * ## Tool filter
  *
- * Only trace records whose `source.tool === 'Bash'` participate. Edit /
+ * Only trace records whose `emitter.tool === 'Bash'` participate. Edit /
  * Write / Read / Grep / Glob events are not retries — those belong to
- * other detectors (rework for file-edit churn, hotspot at Epic scope).
- * The tool name is read from `source.tool` first and falls back to
- * `details.tool` to mirror the rework detector's tolerance for legacy
- * trace shapes.
+ * other detectors (rework for file-edit churn). The tool name is read
+ * from `emitter.tool` first and falls back to `details.tool` (see
+ * `common.extractTool`).
  *
  * ## Privacy contract
  *
@@ -124,13 +124,14 @@ function resolveIdentity(rec) {
 }
 
 /**
- * Decide whether a trace record represents a failed invocation. The
- * hook (today) does not capture exit codes; the field is populated by
- * future hook extensions and by tests that need to assert behaviour.
- * A record counts as failed when `details.exitCode` is a number and
- * not zero. Anything else (missing field, null, non-number, zero) is
- * NOT a failure and is ignored entirely — the detector only counts
- * non-zero-exit commands per the parent Epic.
+ * Decide whether a trace record represents a failed invocation. As of
+ * Epic #4406 / Story #4413 the tool-trace hook records `details.exitCode`
+ * for Bash `PostToolUse` events, so the field is present on real Bash
+ * traces (and still set directly by tests). A record counts as failed
+ * when `details.exitCode` is a number and not zero. Anything else
+ * (missing field, null, non-number, zero) is NOT a failure and is ignored
+ * entirely — the detector only counts non-zero-exit commands per the
+ * parent Epic.
  *
  * @param {object} rec
  * @returns {boolean}
@@ -238,7 +239,7 @@ export async function detectRetry(args) {
   return offenders.map(([commandHash, failureCount]) => ({
     ts,
     kind: 'retry',
-    source: { tool: 'retry-detector' },
+    emitter: { tool: 'retry-detector' },
     epicId,
     storyId,
     taskId,

package/.agents/scripts/lib/signals/detectors/rework.js

@@ -158,7 +158,7 @@ export async function detectRework(args) {
   return offenders.map(([targetHash, editCount]) => ({
     ts,
     kind: 'rework',
-    source: { tool: 'rework-detector' },
+    emitter: { tool: 'rework-detector' },
     epicId,
     storyId,
     taskId,

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

@@ -18,48 +18,50 @@
  * the codebase as of Epic #1181 (audit-snapshot 2026-05-11):
  *
  * Signals-writer `appendSignal` call sites:
- *   - `friction`       — quality-gate / runtime friction (check-crap.js,
- *                        check-maintainability.js, diagnose-friction.js,
- *                        post-merge-pipeline.js, progress-reporter.js,
- *                        auto-refresh-runner.js)
- *   - `dispatched`     — (no live emitter; retained pending Story #3908 sweep)
+ *   - `friction`       — quality-gate / runtime friction (diagnose-friction.js,
+ *                        lib/gates/friction.js, auto-refresh-runner.js,
+ *                        worktree-reap.js, lifecycle-emit.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-end`       — span-tree pairing anchor (no live emitter after the
- *                        Epic #2646 listener deletion; retained for span-tree)
- *   - `state-transition` — orchestration/ticketing.js
+ *   - `wave-end`       — span-tree pairing anchor (retained for span-tree)
+ *   - `state-transition` — notification-derived window anchor read by the
+ *                        waveParallelism bucketer.
  *
- * Story #3909 retired the write-only wave kinds with no consumer (`wave-tick`,
- * `epic-complete`) — they duplicated the checkpoint + `epic-run-progress`
- * rollup and nothing read them back.
+ * The `dispatched` kind was deleted in the Epic #4406 signal-contract
+ * cutover — it had no live emitter and no consumer.
  *
  * Signals-writer `appendTrace` call sites (traces.ndjson sibling, but
  * sharing the same envelope shape — `tool-trace-hook.js`):
  *   - `trace`          — per-tool-call timing record
  *
- * Aggregator-consumed kinds (perf-aggregator.js scans these — emitters
- * for `hotspot`, `rework`, `churn`, `idle`, `retry` are future Epic #1030
- * detector Stories that the aggregator was built to receive; the schema
- * pins the names so emitters land on a known shape):
+ * Detector-emitted / aggregator-consumed kinds (`rework`, `retry` are
+ * emitted by `lib/signals/detectors/*`; `hotspot`, `churn`, `idle` remain
+ * pinned in the enum for the aggregator's kind-count rollup even though no
+ * live detector emits them):
  *   - `hotspot`, `rework`, `churn`, `idle`, `retry`
  *
- * ## Common envelope
+ * ## Common envelope (canonical — Epic #4406 / Story #4413)
  *
  * Every signal MUST carry at minimum:
- *   - `ts`     — ISO-8601 timestamp string (writers historically used
- *                `timestamp:` instead; both keys are accepted by the
- *                guards below for backward-compat — the migration to
- *                `ts:` lands in a follow-on Story).
- *   - `epic`   — integer Epic ID (writers historically used `epicId:`;
- *                same backward-compat note).
+ *   - `ts`     — ISO-8601 timestamp string. The single canonical
+ *                timestamp key; the legacy `timestamp:` alias was deleted
+ *                from every writer and this guard in the same PR.
  *   - `kind`   — one of `EVENT_KINDS`.
  *
+ * Scoped signals additionally carry:
+ *   - `epicId` — integer Epic ID (or `null` for standalone-Story
+ *                friction). The single canonical epic-id key; the legacy
+ *                `epic:` alias was deleted.
+ *
  * Optional but commonly carried:
- *   - `story` / `storyId`  — integer Story ID
- *   - `task` / `taskId`    — integer Task ID (nullable)
- *   - `source`             — `{ tool: string }`
- *   - `details`            — kind-specific payload (object or string)
+ *   - `storyId`  — integer Story ID
+ *   - `taskId`   — integer Task ID (nullable)
+ *   - `emitter`  — `{ tool: string, command?: string }` provenance
+ *   - `source`   — `"framework" | "consumer"` classifier tag
+ *   - `category` — top-level friction category string
+ *   - `details`  — kind-specific payload (always an object)
  *
  * @module lib/signals/schema
  */
@@ -77,7 +79,6 @@ import { isPositiveInt } from './detectors/common.js';
 export const EVENT_KINDS = Object.freeze({
   FRICTION: 'friction',
   TRACE: 'trace',
-  DISPATCHED: 'dispatched',
   // 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`
@@ -101,6 +102,13 @@ export const EVENT_KINDS = Object.freeze({
   // the retro and /plan Phase 0 feedback fetch can see acceptance
   // churn alongside friction/hotspot data.
   ACCEPTANCE_EVAL: 'acceptance-eval',
+  // Forensic breadcrumb appended to the per-Epic stream by the notify
+  // dispatcher (lib/orchestration/lifecycle/listeners/notify-dispatcher.js)
+  // when a lifecycle event maps to a webhook notification — the resume
+  // suite reads it back to prove a dispatch survived a crash window without
+  // duplicating. Enumerated so the write-time validator (Story #4413) does
+  // not drop it; it is a deliberate write, not malformed data.
+  NOTIFICATION_EMITTED: 'notification.emitted',
 });
 
 /**
@@ -117,20 +125,17 @@ export const EVENT_KIND_VALUES = Object.freeze(
  * spread string literals across the module graph.
  */
 export const FIELDS = Object.freeze({
-  // Envelope (canonical names — migration to these is in flight)
+  // Canonical envelope keys — there is exactly one key per concept. The
+  // legacy `timestamp` / `epic` / `story` / `task` aliases were deleted in
+  // the Epic #4406 signal-contract cutover; no reader tolerates them.
   TS: 'ts',
-  EPIC: 'epic',
-  STORY: 'story',
-  TASK: 'task',
-  KIND: 'kind',
-
-  // Legacy envelope aliases still emitted by some writers
-  TIMESTAMP: 'timestamp',
   EPIC_ID: 'epicId',
   STORY_ID: 'storyId',
   TASK_ID: 'taskId',
+  KIND: 'kind',
 
   // Common payload fields
+  EMITTER: 'emitter',
   SOURCE: 'source',
   DETAILS: 'details',
   CATEGORY: 'category',
@@ -150,8 +155,9 @@ function isTimestamp(v) {
 }
 
 /**
- * Common envelope guard: every signal MUST carry `ts` (or legacy
- * `timestamp`), `epic` (or legacy `epicId`), and a recognised `kind`.
+ * Common envelope guard: every signal MUST carry `ts`, `epicId`, and a
+ * recognised `kind`. Canonical keys only — the legacy `timestamp` / `epic`
+ * aliases were deleted in the Epic #4406 cutover.
  *
  * Returns true when the envelope is well-formed. Used by `lib/signals/read`
  * to discard malformed lines before yielding them to the consumer.
@@ -164,16 +170,24 @@ export function hasCommonEnvelope(evt) {
   if (typeof evt.kind !== 'string' || !EVENT_KIND_VALUES.has(evt.kind)) {
     return false;
   }
-  const ts = evt.ts ?? evt.timestamp;
-  if (!isTimestamp(ts)) return false;
-  const epic = evt.epic ?? evt.epicId;
-  if (!isPositiveInt(epic)) return false;
+  if (!isTimestamp(evt.ts)) return false;
+  // The canonical `epicId` key MUST be present — a record carrying only the
+  // legacy `epic` alias is rejected (the cutover deleted that alias). Its
+  // value is nullable by contract: standalone-Story friction carries
+  // `epicId: null` (see signal-event.schema.json, where epicId is
+  // `["integer","null"]`). So accept an explicit null, reject a missing key
+  // or a present-but-non-positive-int value.
+  if (!Object.hasOwn(evt, 'epicId')) return false;
+  if (evt.epicId !== null && !isPositiveInt(evt.epicId)) return false;
   return true;
 }
 
 /**
  * Generic per-kind guard. Returns true when the envelope is well-formed
- * AND (when `kind` is supplied) the event's `kind` matches.
+ * AND (when `kind` is supplied) the event's `kind` matches. The full
+ * canonical-shape check lives in the AJV validator compiled from
+ * `signal-event.schema.json` (see `lib/observability/signal-validator.js`);
+ * this predicate is the cheap envelope gate the streaming reader uses.
  *
  * @param {unknown} evt
  * @param {string} [kind] — optional kind to match (one of `EVENT_KINDS`).
@@ -184,42 +198,3 @@ export function isValidSignal(evt, kind) {
   if (kind != null && evt.kind !== kind) return false;
   return true;
 }
-
-/**
- * Per-kind shape guards. Each entry asserts the envelope plus any
- * required per-kind fields. Unknown kinds fall back to the envelope
- * check.
- *
- * The guards are intentionally lax — they reject records that are
- * obviously malformed (missing `kind`, missing `ts`, missing `epic`),
- * not records with extra fields or future schema extensions. The
- * aggregator (perf-aggregator.js) carries its own per-kind narrowing.
- *
- * @type {Readonly<Record<string, (evt: unknown) => boolean>>}
- */
-export const GUARDS = Object.freeze({
-  [EVENT_KINDS.FRICTION]: (evt) => {
-    if (!isValidSignal(evt, EVENT_KINDS.FRICTION)) return false;
-    // friction signals commonly carry a `category` field, but some
-    // writers (early in the migration) omit it. We accept both.
-    return true;
-  },
-  [EVENT_KINDS.TRACE]: (evt) => isValidSignal(evt, EVENT_KINDS.TRACE),
-  [EVENT_KINDS.DISPATCHED]: (evt) => isValidSignal(evt, EVENT_KINDS.DISPATCHED),
-  [EVENT_KINDS.WAVE_START]: (evt) => isValidSignal(evt, EVENT_KINDS.WAVE_START),
-  [EVENT_KINDS.WAVE_END]: (evt) => isValidSignal(evt, EVENT_KINDS.WAVE_END),
-  [EVENT_KINDS.WAVE_TICK]: (evt) => isValidSignal(evt, EVENT_KINDS.WAVE_TICK),
-  [EVENT_KINDS.WAVE_COMPLETE]: (evt) =>
-    isValidSignal(evt, EVENT_KINDS.WAVE_COMPLETE),
-  [EVENT_KINDS.EPIC_COMPLETE]: (evt) =>
-    isValidSignal(evt, EVENT_KINDS.EPIC_COMPLETE),
-  [EVENT_KINDS.STATE_TRANSITION]: (evt) =>
-    isValidSignal(evt, EVENT_KINDS.STATE_TRANSITION),
-  [EVENT_KINDS.HOTSPOT]: (evt) => isValidSignal(evt, EVENT_KINDS.HOTSPOT),
-  [EVENT_KINDS.REWORK]: (evt) => isValidSignal(evt, EVENT_KINDS.REWORK),
-  [EVENT_KINDS.CHURN]: (evt) => isValidSignal(evt, EVENT_KINDS.CHURN),
-  [EVENT_KINDS.IDLE]: (evt) => isValidSignal(evt, EVENT_KINDS.IDLE),
-  [EVENT_KINDS.RETRY]: (evt) => isValidSignal(evt, EVENT_KINDS.RETRY),
-  [EVENT_KINDS.ACCEPTANCE_EVAL]: (evt) =>
-    isValidSignal(evt, EVENT_KINDS.ACCEPTANCE_EVAL),
-});