mandrel 2.30.0 → 2.32.0

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

@@ -1,57 +1,38 @@
 /**
  * ticket-lease.js — assignee-as-lease primitive (Story #3480, Epic #3457).
  *
- * The workflow-guards Feature (#3478) needs a way for one operator to take
- * an exclusive, time-bounded claim on a ticket so two concurrent runs do not
- * both drive the same Story. Rather than invent a new state column, the lease
- * rides the ticket's existing **assignees** surface: the single assignee *is*
- * the lease owner. Liveness is decided by the owner's last-heartbeat epoch-ms
- * compared against a configured TTL.
+ * The workflow-guards Feature (#3478) needs a way for one operator to take an
+ * exclusive claim on a ticket so two concurrent runs do not both drive the
+ * same Story. Rather than invent a new state column, the lease rides the
+ * ticket's existing **assignees** surface: the single assignee *is* the lease
+ * owner.
  *
- * **There is no live heartbeat source.** The `story.heartbeat` emitter this
- * module was designed against was structurally inert (it demanded an
- * `epicId >= 1` that v2, which has no Epics, never supplies) and has been
- * deleted. Every caller now reaches `acquireLease` through
- * `lease-guard-shared.acquireLeaseFailClosed` with `anchorHeartbeatToNow`,
- * which pins `heartbeatAt` to `now`: the lease **fails closed**, so any
- * foreign claim reads as live and refuses. A stranded claim is cleared with
- * `--steal`, never by TTL expiry. The TTL and the stale-reclaim branch below
- * are therefore reachable only via an explicit caller-supplied `heartbeatAt`
- * — the seam is kept, the automatic expiry is not real.
+ * **A foreign claim is a refusal, full stop (Story #5006).** The lease shipped
+ * with a TTL: a claim whose owner's last heartbeat was older than
+ * `delivery.lease.ttlMs` counted as stale and was silently reclaimed. The
+ * `story.heartbeat` emitter that would have fed it was structurally inert (it
+ * demanded an `epicId >= 1` that v2, which has no Epics, never supplies) and
+ * was deleted, after which every guard pinned `heartbeatAt` to `now` so the
+ * liveness test always answered "live" — the TTL, the heartbeat parameter and
+ * the reclaim branch were an elaborate way of writing `true`. They are gone.
+ * A stranded claim is cleared with `--steal`, which is now the only way past
+ * a foreign owner.
  *
- * The three exported operations are deliberately thin and provider-agnostic:
+ * The two exported operations are deliberately thin and provider-agnostic:
  *
  *   - `acquireLease`  — claim an unassigned ticket, re-affirm a self-held
- *                       claim, reclaim a ticket whose foreign claim has gone
- *                       stale (heartbeat older than TTL), or — with
- *                       `steal: true` — forcibly transfer a *live* foreign
- *                       claim.
+ *                       claim, or — with `steal: true` — forcibly transfer a
+ *                       foreign claim.
  *   - `releaseLease`  — clear the assignment, but only when the operator
  *                       still holds it (a no-op once the ticket was
  *                       reassigned elsewhere, so a late release never steals
  *                       a claim back from whoever took over).
- *   - `describeLease` — a read-only snapshot of the current claim and its
- *                       liveness, used by callers (and tests) to reason about
- *                       a ticket without mutating it.
  *
  * Provider contract (a subset of `ITicketingProvider`):
  *   - `getTicket(id)`            → `{ assignees: string[], ... }`
  *   - `updateTicket(id, { assignees })` writes the assignee list.
- *
- * Liveness seam: callers supply the owner's last-heartbeat epoch-ms via the
- * `heartbeatAt` option (a number, or `null`/`undefined` when no heartbeat has
- * ever been recorded for the current owner). Threading the timestamp in keeps
- * this module pure and trivially unit-testable — it does not read any ledger
- * itself. A claim with no heartbeat is treated as stale (reclaimable) by
- * `isClaimLive`; note the live guards never take that branch, per the
- * fail-closed anchoring described above.
- *
- * `now` is injectable (epoch ms) for deterministic tests; it defaults to
- * `Date.now()`.
  */
 
-import { resolveLeaseTtlMs } from '../config/limits.js';
-
 /**
  * The shipped, non-personal operator-identity placeholder (and its bare,
  * post-normalise form). The committed `.agentrc.json` and the distributed
@@ -94,35 +75,6 @@ export function normalizeOperatorHandle(raw) {
   return trimmed;
 }
 
-/**
- * Decide whether a foreign claim is still "live" given the owner's last
- * heartbeat and the configured TTL. A claim is live when a heartbeat exists
- * and is no older than `ttlMs`. A missing heartbeat (`null`/`undefined`) or a
- * heartbeat older than the TTL is stale and therefore reclaimable.
- *
- * The `heartbeatAt` seam is retained, but there is no longer any in-repo
- * heartbeat *source*: the `story.heartbeat` emitter was structurally inert
- * (it required an `epicId >= 1` that v2 never sets) and was deleted along
- * with the ledger reader that scanned for it. Every live caller reaches this
- * through `lease-guard-shared.acquireLeaseFailClosed` with
- * `anchorHeartbeatToNow`, which pins `heartbeatAt` to `now` so ANY foreign
- * claim reads live and the guard fails closed — a stranded claim is cleared
- * with `--steal`, not by TTL expiry. The parameter stays because that
- * anchoring is expressed through it.
- *
- * @param {object} args
- * @param {number|null|undefined} args.heartbeatAt  Owner's last heartbeat (epoch ms).
- * @param {number} args.ttlMs                        Lease TTL in milliseconds.
- * @param {number} args.now                          Current time (epoch ms).
- * @returns {boolean}
- */
-export function isClaimLive({ heartbeatAt, ttlMs, now }) {
-  if (typeof heartbeatAt !== 'number' || !Number.isFinite(heartbeatAt)) {
-    return false;
-  }
-  return now - heartbeatAt <= ttlMs;
-}
-
 /**
  * Normalise the assignee list into a single current owner. The lease model is
  * single-holder: the first assignee is authoritative. Returns `null` for an
@@ -141,10 +93,10 @@ export function currentOwner(assignees) {
  *
  * @param {string} op
  * @param {object} opts
- * @returns {{ provider: object, ticketId: number, operator: string, ttlMs: number, now: number }}
+ * @returns {{ provider: object, ticketId: number, operator: string }}
  */
 function normaliseOpts(op, opts) {
-  const { provider, ticketId, operator, config, now } = opts ?? {};
+  const { provider, ticketId, operator } = opts ?? {};
 
   if (!provider || typeof provider.getTicket !== 'function') {
     throw new Error(`${op}: provider with getTicket/updateTicket is required`);
@@ -156,45 +108,7 @@ function normaliseOpts(op, opts) {
     throw new Error(`${op}: operator must be a non-empty string`);
   }
 
-  const ttlMs = resolveLeaseTtlMs(config, opts.ttlMs);
-  const resolvedNow =
-    typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
-
-  return { provider, ticketId, operator, ttlMs, now: resolvedNow };
-}
-
-/**
- * Read-only snapshot of the current lease on a ticket. Never mutates.
- *
- * @param {object} opts
- * @param {object} opts.provider              Ticketing provider (getTicket).
- * @param {number} opts.ticketId              Ticket to inspect.
- * @param {string} opts.operator              The operator asking.
- * @param {number|null} [opts.heartbeatAt]    Owner's last heartbeat (epoch ms).
- * @param {object} [opts.config]              Resolved config (for TTL default).
- * @param {number} [opts.ttlMs]               Explicit TTL override (epoch ms).
- * @param {number} [opts.now]                 Injectable clock (epoch ms).
- * @returns {Promise<{
- *   ticketId: number,
- *   owner: string|null,
- *   heldByOperator: boolean,
- *   live: boolean,
- *   ttlMs: number,
- * }>}
- */
-export async function describeLease(opts) {
-  const { provider, ticketId, operator, ttlMs, now } = normaliseOpts(
-    'describeLease',
-    opts,
-  );
-  const ticket = await provider.getTicket(ticketId);
-  const owner = currentOwner(ticket?.assignees);
-  const heldByOperator = owner === operator;
-  const live =
-    owner === null
-      ? false
-      : isClaimLive({ heartbeatAt: opts.heartbeatAt, ttlMs, now });
-  return { ticketId, owner, heldByOperator, live, ttlMs };
+  return { provider, ticketId, operator };
 }
 
 /**
@@ -205,10 +119,8 @@ export async function describeLease(opts) {
  *                                     `reason: 'unclaimed'`.
  *   - Operator already holds it    → no write, `acquired: true`,
  *                                     `reason: 'already-held'`.
- *   - Live foreign claim, no steal → no write, `acquired: false`,
+ *   - Foreign claim, no steal      → no write, `acquired: false`,
  *                                     `owner: <foreign>`, `reason: 'held'`.
- *   - Stale foreign claim          → reassign operator, `acquired: true`,
- *                                     `reason: 'reclaimed'`.
  *   - Foreign claim + `steal:true` → reassign operator, `acquired: true`,
  *                                     `reason: 'stolen'`.
  *   - Lost a write race            → a foreign login co-assigned between our
@@ -226,23 +138,16 @@ export async function describeLease(opts) {
  * @param {object} opts.provider              Ticketing provider.
  * @param {number} opts.ticketId              Ticket to claim.
  * @param {string} opts.operator              Operator acquiring the lease.
- * @param {number|null} [opts.heartbeatAt]    Current owner's last heartbeat (epoch ms).
- * @param {boolean} [opts.steal=false]        Transfer a live foreign claim.
- * @param {object} [opts.config]              Resolved config (TTL default).
- * @param {number} [opts.ttlMs]               Explicit TTL override.
- * @param {number} [opts.now]                 Injectable clock.
+ * @param {boolean} [opts.steal=false]        Transfer a foreign claim.
  * @returns {Promise<{
  *   acquired: boolean,
  *   owner: string,
  *   previousOwner: string|null,
- *   reason: 'unclaimed'|'already-held'|'reclaimed'|'stolen'|'held'|'lost-race',
+ *   reason: 'unclaimed'|'already-held'|'stolen'|'held'|'lost-race',
  * }>}
  */
 export async function acquireLease(opts) {
-  const { provider, ticketId, operator, ttlMs, now } = normaliseOpts(
-    'acquireLease',
-    opts,
-  );
+  const { provider, ticketId, operator } = normaliseOpts('acquireLease', opts);
   const steal = opts.steal === true;
 
   const ticket = await provider.getTicket(ticketId);
@@ -269,9 +174,8 @@ export async function acquireLease(opts) {
     };
   }
 
-  // Foreign claim — decide on liveness / steal.
-  const live = isClaimLive({ heartbeatAt: opts.heartbeatAt, ttlMs, now });
-  if (live && !steal) {
+  // Foreign claim — refuse unless the operator explicitly steals it.
+  if (!steal) {
     return {
       acquired: false,
       owner,
@@ -285,7 +189,7 @@ export async function acquireLease(opts) {
     ticketId,
     operator,
     previousOwner: owner,
-    reason: steal && live ? 'stolen' : 'reclaimed',
+    reason: 'stolen',
   });
 }
 
@@ -359,9 +263,6 @@ async function claimAndVerify({
  * @param {object} opts.provider   Ticketing provider.
  * @param {number} opts.ticketId   Ticket to release.
  * @param {string} opts.operator   Operator releasing the lease.
- * @param {object} [opts.config]   Resolved config (TTL default).
- * @param {number} [opts.ttlMs]    Explicit TTL override.
- * @param {number} [opts.now]      Injectable clock.
  * @returns {Promise<{
  *   released: boolean,
  *   owner: string|null,

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/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