mandrel 2.31.0 → 2.33.0

package/.agents/scripts/lib/orchestration/ticket-validator-conflicts.js

@@ -1,3 +1,4 @@
+import { resolveListValue } from '../config/shared.js';
 import { parse as parseStoryBody } from '../story-body/story-body.js';
 import { collectStoryAssumptionEntries } from './file-assumptions.js';
 import { computeStoryReachability } from './story-reachability.js';
@@ -108,8 +109,11 @@ const DEFAULT_POLICY = Object.freeze({
  * Patterns support two shapes:
  *   - exact path  — `lib/orchestration/lifecycle/listeners/index.js`
  *   - `**` suffix — `**\/listeners/index.js` (matches any depth)
+ *
+ * Module-private since `resolveConflictPolicy` became the one production
+ * reader; tests reach it through `_internal`.
  */
-export const DEFAULT_REGISTRY_PATTERNS = Object.freeze([
+const DEFAULT_REGISTRY_PATTERNS = Object.freeze([
   'lib/orchestration/lifecycle/listeners/index.js',
   '**/listeners/index.js',
   '**/handlers/index.js',
@@ -762,6 +766,117 @@ export function computeConflictFindings({ stories, policy } = {}) {
   ];
 }
 
+/**
+ * Resolve the config-derived half of the conflict policy from
+ * `config.planning` — the severity flags, the fan-out threshold, and the
+ * registry patterns, in one place.
+ *
+ * Two passes consume `planning.*` and must not disagree: the raw
+ * pre-assembly pass (`persist-helpers.validateTickets`, which attaches its
+ * production `fanOutCounter` on top of this) and the post-assembly pass
+ * (`computeAssembledConflictFindings`, which forces `fanOutCounter: null`).
+ * Under Story #5045 each resolved its own copy, and the copies had already
+ * drifted — `failOnMissingBddScaffold` reached only the assembled pass,
+ * `failOnLargeFanOut` / `largeFanOutThreshold` / `crossCuttingRegistries`
+ * only the raw one — so a knob set in config silently applied on one of the
+ * two passes. A knob read here reaches both; that is the contract.
+ *
+ * `fanOutCounter` is deliberately absent: it is probe machinery, not
+ * config, and each caller owns its own.
+ *
+ * @param {object} [config] Resolved config carrying `planning.*`.
+ * @returns {object} A `computeConflictFindings` policy (no `fanOutCounter`).
+ */
+export function resolveConflictPolicy(config) {
+  const planning = config?.planning;
+  const policy = {
+    failOnSharedEditors: planning?.failOnSharedEditors === true,
+    requireExplicitCrossStoryDeps:
+      planning?.requireExplicitCrossStoryDeps === true,
+    failOnRegistryConflicts: planning?.failOnRegistryConflicts === true,
+    failOnLargeFanOut: planning?.failOnLargeFanOut === true,
+    failOnMissingBddScaffold: planning?.failOnMissingBddScaffold === true,
+  };
+  if (Number.isFinite(planning?.largeFanOutThreshold)) {
+    policy.largeFanOutThreshold = planning.largeFanOutThreshold;
+  }
+  if (planning?.crossCuttingRegistries !== undefined) {
+    policy.registries = resolveListValue(
+      DEFAULT_REGISTRY_PATTERNS,
+      planning.crossCuttingRegistries,
+    );
+  }
+  return policy;
+}
+
+/**
+ * Re-run the cross-Story conflict passes over the **assembled** Story bodies —
+ * the artifact persist actually writes (Story #5045).
+ *
+ * `validateTickets` runs before `assemblePlanStories`, over the raw
+ * `stories.json` payload, so plan-time conflict analysis never saw what got
+ * persisted. That is not a cosmetic ordering nit: the canonical authoring shape
+ * carries `acceptance[]` / `verify[]` at the ticket's **top level**, and it is
+ * assembly's `syncContractFieldFromTopLevel` that folds them into the body.
+ * `indexConsumers` scans `body.acceptance` / `body.verify` for producer paths —
+ * so on the real payload it scanned two empty arrays, and every
+ * `implicit-cross-story-dep` and `missing-bdd-scaffold` finding was silently
+ * unreachable. Running the passes again over the serialized bodies restores
+ * them.
+ *
+ * **The fan-out pass is deliberately not re-run.** It is a `git grep` per
+ * deleted path and its inputs (`changes[]` deletes) are identical on both
+ * sides, so re-probing would double the git cost for a byte-identical answer;
+ * `enforceFanOutGate` already owns that class over the raw payload.
+ *
+ * @param {object} args
+ * @param {Array<{ slug: string, title?: string, body: string, depends_on?: string[] }>} args.stories
+ *   Assembled Stories — `body` is the serialized, footer-stamped markdown.
+ * @param {object} [args.config] Resolved config; `planning.*` supplies the
+ *   policy via {@link resolveConflictPolicy} — the same resolver the raw
+ *   pass uses, so a knob cannot apply on only one of the two passes.
+ * @returns {ConflictFinding[]}
+ */
+export function computeAssembledConflictFindings({ stories, config } = {}) {
+  return computeConflictFindings({
+    stories: (Array.isArray(stories) ? stories : []).map((story) => ({
+      slug: story.slug,
+      title: story.title,
+      body: story.body,
+      depends_on: Array.isArray(story.depends_on) ? story.depends_on : [],
+    })),
+    policy: {
+      ...resolveConflictPolicy(config),
+      fanOutCounter: null,
+    },
+  });
+}
+
+/**
+ * Stable identity for one conflict finding, so the post-assembly pass can be
+ * diffed against the raw pass and only the genuinely-new findings reported
+ * (Story #5045). Without it the two passes announce the same shared-editor
+ * collision twice per run, which is how a warning channel gets discounted.
+ *
+ * The separator is written as the `\u0000` escape and never as a raw byte — a
+ * literal NUL would make git classify this file as binary and drop its diffs.
+ *
+ * @param {object} finding
+ * @returns {string}
+ */
+export function conflictFindingKey(finding) {
+  return [
+    finding?.kind ?? '',
+    finding?.path ?? finding?.registryPath ?? '',
+    Array.isArray(finding?.storySlugs)
+      ? [...finding.storySlugs].sort().join(',')
+      : (finding?.storySlug ?? ''),
+    finding?.producer?.storySlug ?? '',
+    finding?.consumer?.storySlug ?? '',
+    finding?.consumer?.sourceField ?? '',
+  ].join('\u0000');
+}
+
 /**
  * Render the audit trail behind a fan-out finding's number, so an operator
  * can check the figure rather than trust it (Story #4547).

package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js

@@ -29,7 +29,7 @@
  */
 
 import { parse as parseStoryBody } from '../story-body/story-body.js';
-import { estimateTokens } from './context-envelope.js';
+import { estimateTokens } from './spec-spill.js';
 
 /**
  * Normalize a Story's `body` to the structured object the sizing layers

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -1,4 +1,5 @@
 import { ValidationError } from '../errors/index.js';
+import { normalizeOwnedProvenance } from '../findings/provenance-field.js';
 import { detectCycle } from '../Graph.js';
 import { gitSpawn } from '../git-utils.js';
 
@@ -528,6 +529,41 @@ function assertEveryStoryHasInlineContract({ stories }) {
   );
 }
 
+/**
+ * Shape-check the optional per-Story `provenance` field (Story #5045).
+ *
+ * The field decides which audit identities persist stamps into a Story body,
+ * so a malformed entry has to fail at the validator rather than at the
+ * stamper: by the time assembly runs, an unnoticed drop is indistinguishable
+ * from a Story that legitimately owns nothing — and the cost lands a whole
+ * sweep later, when the next audit re-files work this plan already tracked.
+ *
+ * Absence is valid and common: a Story with no `provenance` inherits the
+ * whole-seed union carry, which is the recall-safe default.
+ *
+ * Errors are batched across the backlog so one pass names every offender.
+ *
+ * @param {{ stories: object[] }} args
+ * @throws {Error} naming each malformed field.
+ */
+function assertStoryProvenanceShape({ stories }) {
+  const violations = [];
+  for (const story of stories) {
+    try {
+      normalizeOwnedProvenance(story?.provenance, story?.slug ?? '<unknown>');
+    } catch (err) {
+      violations.push(`  - ${err.message}`);
+    }
+  }
+  if (violations.length === 0) return;
+  throw new Error(
+    `Cross-Validation Failed: ${violations.length} Story provenance field(s) ` +
+      `are malformed:\n${violations.join('\n')}\n\nAuthor provenance as ` +
+      '{ "fingerprints": ["<40-char sha1>"], "semanticKeys": ["<area␟path>"] }, ' +
+      'or omit it entirely to inherit the seed-wide union.',
+  );
+}
+
 function assertNoUnknownDeps({ tickets, ticketBySlug }) {
   const unknownDeps = [];
   for (const t of tickets) {
@@ -575,6 +611,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
 
   assertAllTicketsAreStories({ tickets, stories });
   assertEveryStoryHasInlineContract({ stories });
+  assertStoryProvenanceShape({ stories });
   assertNoUnknownDeps({ tickets, ticketBySlug });
 
   assertAcyclic(slugAdjacency);
@@ -704,6 +741,7 @@ export const _internal = {
   indexTicketsBySlug,
   assertAllTicketsAreStories,
   assertEveryStoryHasInlineContract,
+  assertStoryProvenanceShape,
   assertNoUnknownDeps,
   assertAcyclic,
   attachFindingsAndErrors,

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -146,14 +146,14 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // `--steal`, not by TTL expiry. One entry per ticket; re-acquires upsert
   // in place.
   'plan-lease',
-  // Story #4415 (Epic #4406) — the feedback-loop graduators
-  // (`audit-results-graduator.js` / `retro-proposals-graduator.js`) upsert a
-  // `cross-repo-deferred` comment on the Epic listing findings that route
+  // Story #4415 (Epic #4406) — the feedback-loop graduator
+  // (`retro-proposals-graduator.js`) upserts a
+  // `cross-repo-deferred` comment listing findings that route
   // to a different repository and were therefore not filed here. Replaces
   // the prior log-line-only trace so the deferral survives the finalize
   // run as a durable, operator-visible record. Discriminated by a
-  // `graduator="audit-results|code-review"` attr so the two graduators
-  // upsert independent comments; re-runs upsert in place.
+  // `graduator="<name>"` attr so independent graduators do not clobber each
+  // other's comment; re-runs upsert in place.
   'cross-repo-deferred',
   // Epic #4474 (PR3) / v2 Stage 3 — `plan-persist.js` upserts a single
   // `plan-summary` comment on the primary Story at terminal persist

package/.agents/scripts/lib/orchestration/ticketing/transition.js

@@ -393,12 +393,13 @@ async function emitBlockedFriction(ticketId, fromState, newState, opts) {
  *   `agent::done` at story-close (after the merge lands), not when the
  *   last Task commit landed on the still-unmerged Story branch. The
  *   parameter is preserved for callers that still suppress cascade
- *   explicitly (e.g. batch-transition helpers).
+ *   explicitly (`single-story-init.js`, and `bulk.js` where the upward
+ *   recursion is driven by hand instead).
  *
  *   `ticketSnapshot` (Story #1795 / Epic #1788) is an optional pre-fetched
- *   ticket object. When the caller already holds the ticket (e.g.
- *   `batchTransitionTickets`, which loops over a list it just hydrated),
- *   passing the snapshot eliminates the two `getTicket` round-trips that
+ *   ticket object. When the caller already holds the ticket — e.g. it
+ *   hydrated the ticket to inspect its labels first — passing the
+ *   snapshot eliminates the two `getTicket` round-trips that
  *   `transitionTicketState` would otherwise issue — one for the notify
  *   `fromState` lookup and one inside `provider.updateTicket`'s label
  *   merge path. Backwards compatible: when omitted, behaviour is unchanged.

package/.agents/scripts/lib/orchestration/verify-tier-repair.js

@@ -0,0 +1,107 @@
+/**
+ * verify-tier-repair.js — repair-before-judging for the `verify[]` tier suffix
+ * (Story #5005).
+ *
+ * The tier suffix (`… (unit)`) is a deterministic, mechanically-derivable
+ * formality. `task-body-validator.js` already computed the corrected entry in
+ * order to print it as a "Suggested fix" — then rejected the plan anyway and
+ * charged the author a full re-drafting round to paste that exact string back.
+ * This module applies the inference the validator already trusts, so the hard
+ * error is reserved for the entries only the author can resolve.
+ *
+ * It lives beside the validator rather than inside it because the validator's
+ * job is to *judge*: mixing a mutating repair pass into a module of pure
+ * collectors muddies both. `persist-helpers.js#validateTickets` calls this
+ * first, then `validateTaskBodies`.
+ *
+ * @module lib/orchestration/verify-tier-repair
+ */
+
+import { suggestVerifyFix } from '../story-body/body-format-lints.js';
+import {
+  parse as parseStoryBody,
+  serialize as serializeStoryBody,
+} from '../story-body/story-body.js';
+import { VERIFY_TIER_VALUES } from './task-body-validator.js';
+
+/** A parenthesised tier drawn from the canonical vocabulary, at end of entry. */
+const VERIFY_TIER_RE = new RegExp(
+  `\\((?:${VERIFY_TIER_VALUES.join('|')})\\)\\s*$`,
+);
+
+/**
+ * Rewrite one `verify[]` list, appending the inferable testing tier to any
+ * entry missing one. Returns `null` when nothing changed, so callers can keep
+ * an already-compliant list byte-identical (and skip re-serializing the body
+ * it came from).
+ *
+ * @param {unknown} rawVerify
+ * @returns {string[]|null} The corrected list, or `null` when no fix applied.
+ */
+function repairVerifyList(rawVerify) {
+  if (!Array.isArray(rawVerify)) return null;
+  let changed = false;
+  const next = rawVerify.map((entry) => {
+    if (typeof entry !== 'string') return entry;
+    if (entry.startsWith('manual:') || VERIFY_TIER_RE.test(entry)) return entry;
+    const fix = suggestVerifyFix(entry);
+    if (fix === null) return entry;
+    changed = true;
+    return fix;
+  });
+  return changed ? next : null;
+}
+
+/**
+ * Repair the `## Verify` section of a serialized (string) body, in place on
+ * the ticket. Only re-serializes when a fix actually applied, so a compliant
+ * body is never round-tripped through `parse → serialize`.
+ *
+ * Leaving the body untouched while the top level was repaired would be worse
+ * than not repairing at all: `syncContractFieldFromTopLevel` fails closed on a
+ * body section that disagrees with its top-level array, so both sides must be
+ * repaired by the same rule or neither.
+ *
+ * @param {object} ticket
+ */
+function repairStringBodyVerify(ticket) {
+  let parsed;
+  try {
+    parsed = parseStoryBody(ticket.body).body;
+  } catch {
+    // An unparseable body is already a hard error in `validateTaskBodyShape`;
+    // there is nothing to repair and nothing to report twice.
+    return;
+  }
+  const repaired = repairVerifyList(parsed.verify);
+  if (repaired === null) return;
+  ticket.body = serializeStoryBody({ ...parsed, verify: repaired });
+}
+
+/**
+ * Auto-append the testing tier to `verify[]` entries that omit one, wherever
+ * `suggestVerifyFix` can infer it from the command. An entry whose tier cannot
+ * be inferred is left untouched and still hard-errors downstream.
+ *
+ * Mutates `tickets` in place (the persist pipeline threads this same array on
+ * to assembly) and returns it. Already-compliant tickets are untouched, so
+ * their persisted output stays byte-identical. Total — a non-array argument
+ * and non-Story tickets are no-ops.
+ *
+ * @param {object[]} tickets
+ * @returns {object[]} `tickets`
+ */
+export function normalizeVerifyTiers(tickets) {
+  for (const ticket of Array.isArray(tickets) ? tickets : []) {
+    if (!ticket || ticket.type !== 'story' || ticket.body == null) continue;
+    const topLevel = repairVerifyList(ticket.verify);
+    if (topLevel !== null) ticket.verify = topLevel;
+    if (typeof ticket.body === 'string') {
+      repairStringBodyVerify(ticket);
+      continue;
+    }
+    const bodyLevel = repairVerifyList(ticket.body.verify);
+    if (bodyLevel !== null) ticket.body.verify = bodyLevel;
+  }
+  return tickets;
+}

package/.agents/scripts/lib/qa/coverage-verdict.js

@@ -34,17 +34,12 @@
 //   operator-facing string explaining the verdict (always populated,
 //   including for present tiers).
 //
-//   acceptanceMatrix(criteria) -> {
-//     tiers: TIERS,
-//     rows: [{ id, label, verdict }, ...],
-//   }
-//
-//   Maps each acceptance criterion to its per-tier `coverageVerdict`, giving
-//   the AC × test-tier matrix the markdown report (lib/qa/coverage-report.js)
-//   renders.
+// Story #5008 removed the `acceptanceMatrix` feeder and the markdown report it
+// fed: the QA workflows read the per-tier verdict and author the missing-test
+// prose directly, so the AC x tier matrix was a round-trip with no reader.
 
-/** The three test tiers, in pyramid order (base → top). */
-export const TIERS = Object.freeze(['unit', 'contract', 'acceptance']);
+/** The three test tiers, in pyramid order (base -> top). */
+const TIERS = Object.freeze(['unit', 'contract', 'acceptance']);
 
 const PRESENT = 'present';
 const ABSENT = 'absent';
@@ -217,80 +212,3 @@ export function coverageVerdict(surface = {}) {
 
   return verdict;
 }
-
-/**
- * Normalize a single criterion descriptor into `{id, label, surface}`. A
- * descriptor may carry `id`, `label` (falls back to id), and either a nested
- * `surface` or a flat `{symbol, tests}` shape.
- */
-function normalizeOne(entry, index) {
-  const e = entry && typeof entry === 'object' ? entry : {};
-  const id =
-    typeof e.id === 'string' && e.id.trim() !== ''
-      ? e.id.trim()
-      : `AC-${index + 1}`;
-  const label =
-    typeof e.label === 'string' && e.label.trim() !== '' ? e.label.trim() : id;
-
-  let surface;
-  if (e.surface && typeof e.surface === 'object') {
-    surface = e.surface;
-  } else if (Array.isArray(e.tests) || typeof e.symbol === 'string') {
-    surface = { symbol: e.symbol, tests: e.tests };
-  } else {
-    surface = {};
-  }
-
-  return { id, label, surface };
-}
-
-/**
- * Normalize the criteria input for {@link acceptanceMatrix}. Accepts either an
- * array of criterion descriptors or a plain object keyed by criterion id whose
- * values are surfaces (or `{surface}` wrappers). Returns a normalized array of
- * `{id, label, surface}`.
- *
- * @param {Array<object>|object} criteria
- * @returns {Array<{id:string,label:string,surface:object}>}
- */
-function normalizeCriteria(criteria) {
-  if (Array.isArray(criteria)) {
-    return criteria.map((entry, index) => normalizeOne(entry, index));
-  }
-  if (criteria && typeof criteria === 'object') {
-    return Object.entries(criteria).map(([id, value], index) =>
-      normalizeOne(
-        value && typeof value === 'object' && !Array.isArray(value)
-          ? { id, ...value }
-          : { id, surface: { tests: value } },
-        index,
-      ),
-    );
-  }
-  throw new TypeError(
-    'acceptanceMatrix: criteria must be an array or an object',
-  );
-}
-
-/**
- * Build the AC × test-tier matrix: for each acceptance criterion, the per-tier
- * {@link coverageVerdict}. This is the structured shape the markdown report
- * (`lib/qa/coverage-report.js`) renders into a table.
- *
- * @param {Array<{id?:string,label?:string,surface?:object,symbol?:string,tests?:Array}>|Record<string,object>} criteria
- *   Acceptance criteria, either as an array of descriptors or an object keyed
- *   by criterion id. Each descriptor names a surface (nested `surface`, or a
- *   flat `{symbol, tests}`).
- * @returns {{tiers: ReadonlyArray<string>,
- *            rows: Array<{id:string,label:string,
- *                         verdict:ReturnType<typeof coverageVerdict>}>}}
- */
-export function acceptanceMatrix(criteria) {
-  const normalized = normalizeCriteria(criteria);
-  const rows = normalized.map(({ id, label, surface }) => ({
-    id,
-    label,
-    verdict: coverageVerdict(surface),
-  }));
-  return { tiers: TIERS, rows };
-}

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

@@ -2,7 +2,7 @@
  * detectors/common.js — shared helpers for the signals layer.
  *
  * Hoisted out of the detector modules (retry, rework) plus
- * `signals/read.js` and `signals/schema.js`, all of which shipped
+ * the since-deleted `signals/read.js`, and `signals/schema.js`, all of which shipped
  * byte-equivalent copies of these predicates. See Story #2464.
  */
 

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

@@ -1,7 +1,7 @@
 /**
  * `lib/signals/` barrel.
  *
- * Consumers do `import { read, schema, buildSpanTree, appendSignal } from './lib/signals/index.js'`
+ * Consumers do `import { schema, appendSignal } from './lib/signals/index.js'`
  * (or `import * as signals from './lib/signals/index.js'`) so a future
  * shape migration only has to touch this file.
  *
@@ -9,18 +9,20 @@
  *   - Epic #1181 / Story #1438 / Task #1459 — initial barrel with `read`
  *     + `schema`; `buildSpanTree` was a throwing placeholder.
  *   - Epic #1181 / Story #1440 / Task #1461 — placeholder replaced by
- *     the real export from `./span-tree.js`.
+ *     the real span-tree builder.
  *   - 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/`.
+ *   - Story #5003 — the reader half (`read`, `buildSpanTree`) went with the
+ *     debug viewer that consumed it: it walked a `run-<id>/` layout no v2
+ *     writer populates. `appendTrace` went with the trace hook, its only
+ *     producer. What remains is the live write surface.
  *
  * @module lib/signals
  */
 
-import { read } from './read.js';
 import * as schema from './schema.js';
-import { buildSpanTree } from './span-tree.js';
-import { appendSignal, appendTrace, forEachLine } from './write.js';
+import { appendSignal, forEachLine } from './write.js';
 
-export { appendSignal, appendTrace, buildSpanTree, forEachLine, read, schema };
+export { appendSignal, forEachLine, schema };

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

@@ -2,10 +2,10 @@
  * Signals schema — single source of truth for event-kind constants and
  * shape guards (Epic #1181 / Story #1438 / Task #1458).
  *
- * Both writers (`lib/observability/signals-writer.js` callers) and
- * 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.
+ * Both writers (`lib/observability/signals-writer.js` callers) and readers
+ * (its `forEachLine` / `forEachSignalStreamLine` walkers, and the retro's
+ * gather-signals phase) import their field names from this module so the
+ * on-disk NDJSON shape stays under one schema.
  *
  * Pure module: importing has **no I/O side effects**. The exported
  * `EVENT_KINDS` object is `Object.freeze`'d so consumers can use it as a
@@ -14,30 +14,25 @@
  * ## Event-kind enumeration
  *
  * The set below is the audited union of `kind:` literals emitted via
- * `signals-writer.appendSignal` and `signals-writer.appendTrace` across
- * the codebase as of Epic #1181 (audit-snapshot 2026-05-11):
+ * `signals-writer.appendSignal` across the codebase as of Epic #1181
+ * (audit-snapshot 2026-05-11):
  *
  * Signals-writer `appendSignal` call sites:
  *   - `friction`       — quality-gate / runtime friction (diagnose-friction.js,
  *                        lib/gates/friction.js)
  *   - `acceptance-eval` — acceptance-eval.js per-criterion terminus signal.
- *   - `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)
+ *   - `wave-start` / `wave-complete` — wave-window anchors.
+ *   - `wave-end`       — wave-window pairing anchor.
  *   - `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.
  *
- * Signals-writer `appendTrace` call sites (traces.ndjson sibling, but
- * sharing the same envelope shape — `tool-trace-hook.js`):
- *   - `trace`          — per-tool-call timing record
- *
- * 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`
+ * Producerless kinds, pinned in the enum so a re-introduction needs no schema
+ * bump. Story #5003 deleted the last emitters of `trace` (the tool-trace hook
+ * and its `appendTrace` writer limb) and of `rework` / `retry` (the detector
+ * pair the hook fed); `hotspot`, `churn`, `idle` never had one:
+ *   - `trace`, `hotspot`, `rework`, `churn`, `idle`, `retry`
  *
  * ## Common envelope (canonical — Epic #4406 / Story #4413)
  *
@@ -68,18 +63,18 @@ import { isPositiveInt } from './detectors/common.js';
 
 /**
  * Frozen enumeration of every event kind currently emitted by
- * `signals-writer.appendSignal` / `appendTrace`, plus the
- * aggregator-consumed kinds whose detectors are future Stories.
+ * `signals-writer.appendSignal`, plus the producerless kinds a future Story
+ * may re-introduce an emitter for.
  *
  * Field names are kebab-cased to match the on-disk literals.
  */
 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. Story #4545 deleted the `waveParallelism`
-  // consumer (perf-aggregator) with the execution-analysis surface; these
-  // kinds stay as the span-tree's anchors.
+  // Wave-window forensics signals. Story #4545 deleted the `waveParallelism`
+  // consumer (perf-aggregator) with the execution-analysis surface, and
+  // Story #5003 deleted the span-tree that paired them; the kinds stay
+  // pinned so a re-introduced window reader needs no schema bump.
   WAVE_START: 'wave-start',
   WAVE_END: 'wave-end',
   WAVE_COMPLETE: 'wave-complete',
@@ -156,7 +151,7 @@ function isTimestamp(v) {
  * 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`
+ * Returns true when the envelope is well-formed. Used by the stream readers
  * to discard malformed lines before yielding them to the consumer.
  *
  * @param {unknown} evt

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

@@ -1,18 +1,18 @@
 /**
- * `lib/signals/write.js` — thin re-export of the signals/traces writer.
+ * `lib/signals/write.js` — thin re-export of the signals writer.
  *
  * The real implementation lives at `../observability/signals-writer.js`
  * (Epic #1030 / Story #1041). This module exists so callers can converge
- * on `lib/signals/` for both reads and writes — the reader barrel landed
- * in Epic #1181 / Story #1438, but the writer surface was still split
- * across `lib/observability/`. New code should `import { appendSignal }
- * from './lib/signals/index.js'` (or `'./lib/signals/write.js'` for a
- * narrower import); legacy direct imports from `lib/observability/` keep
- * working unchanged.
+ * on `lib/signals/` for the write surface. New code should
+ * `import { appendSignal } from './lib/signals/index.js'` (or
+ * `'./lib/signals/write.js'` for a narrower import); legacy direct imports
+ * from `lib/observability/` keep working unchanged.
+ *
+ * `appendTrace` was removed in Story #5003 together with the tool-trace
+ * hook — its only producer — and the viewer that was its only reader.
  */
 
 export {
   appendSignal,
-  appendTrace,
   forEachLine,
 } from '../observability/signals-writer.js';