mandrel 2.59.0 → 2.61.0

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

@@ -1,59 +1,10 @@
 /**
- * Signals schema — single source of truth for event-kind constants and
- * shape guards (Epic #1181 / Story #1438 / Task #1458).
+ * Signals schema — the single source of event-kind constants, field names
+ * and the envelope guard for the NDJSON signal streams. Pure, no I/O.
  *
- * 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
- * compile-time-ish constant without worrying about mutation.
- *
- * ## Event-kind enumeration
- *
- * The set below is the audited union of `kind:` literals emitted via
- * `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-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.
- *
- * 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)
- *
- * Every signal MUST carry at minimum:
- *   - `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:
- *   - `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)
+ * Envelope: `ts` (ISO string), `kind` (an `EVENT_KINDS` value) and `epicId`
+ * (integer, or `null` for standalone-Story friction). No legacy aliases
+ * (`timestamp`, `epic`, …) are tolerated.
  *
  * @module lib/signals/schema
  */
@@ -62,71 +13,42 @@ import { isObject } from '../json-utils.js';
 import { isPositiveInt } from './detectors/common.js';
 
 /**
- * Frozen enumeration of every event kind currently emitted by
- * `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.
+ * Every emitted kind, plus producerless kinds (`trace`, wave-*, `hotspot`,
+ * `rework`, `churn`, `idle`, `retry`) pinned so a re-introduced emitter or
+ * reader needs no schema bump.
  */
 export const EVENT_KINDS = Object.freeze({
   FRICTION: 'friction',
   TRACE: 'trace',
-  // 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',
-  // Story #3909 — the write-only wave-lifecycle kinds with no consumer
-  // (`wave-tick`, `epic-complete`) were retired. They duplicated the
-  // `epic-run-state` checkpoint and the `epic-run-progress` rollup and nothing
-  // read them back.
   STATE_TRANSITION: 'state-transition',
   HOTSPOT: 'hotspot',
   REWORK: 'rework',
   CHURN: 'churn',
   IDLE: 'idle',
   RETRY: 'retry',
-  // Story #3819 — per-criterion acceptance self-eval signal emitted by
-  // acceptance-eval.js. One record per Story per eval-loop terminus,
-  // carrying which acceptance items needed rework and the round count, so
-  // the retro and /mandrel-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.
+  // Written by the notify dispatcher so resume can prove a dispatch survived a
+  // crash window; enumerated so the write-time validator does not drop it.
   NOTIFICATION_EMITTED: 'notification.emitted',
 });
 
 /**
- * The set of event-kind string values (for fast membership checks).
- *
  * @type {ReadonlySet<string>}
  */
 export const EVENT_KIND_VALUES = Object.freeze(
   new Set(Object.values(EVENT_KINDS)),
 );
 
-/**
- * Field-name constants exported so reader/aggregator code does not
- * spread string literals across the module graph.
- */
 export const FIELDS = Object.freeze({
-  // 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_ID: 'epicId',
   STORY_ID: 'storyId',
   TASK_ID: 'taskId',
   KIND: 'kind',
 
-  // Common payload fields
   EMITTER: 'emitter',
   SOURCE: 'source',
   DETAILS: 'details',
@@ -135,9 +57,7 @@ export const FIELDS = Object.freeze({
 });
 
 /**
- * Return true when `v` is a non-empty ISO-8601-ish timestamp string.
- * We don't fully validate format here — the schema's contract is "looks
- * like a timestamp string", not "round-trips through Date.parse exactly".
+ * "Looks like a timestamp string" — the format is not validated.
  *
  * @param {unknown} v
  * @returns {boolean}
@@ -147,13 +67,6 @@ function isTimestamp(v) {
 }
 
 /**
- * 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 the stream readers
- * to discard malformed lines before yielding them to the consumer.
- *
  * @param {unknown} evt
  * @returns {boolean}
  */
@@ -163,23 +76,15 @@ export function hasCommonEnvelope(evt) {
     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.
+  // The key must be present; its value may be null but never a non-positive int.
   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. 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.
+ * Cheap envelope gate for the streaming reader; the full shape check is the
+ * AJV validator in `lib/observability/signal-validator.js`.
  *
  * @param {unknown} evt
  * @param {string} [kind] — optional kind to match (one of `EVENT_KINDS`).

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

@@ -1,15 +1,6 @@
 /**
- * `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 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.
+ * `lib/signals/write.js` — re-export of `../observability/signals-writer.js`
+ * so callers converge on `lib/signals/` for the write surface.
  */
 
 export {

package/.agents/scripts/lib/single-story/confirm-merge.js

@@ -1,62 +1,31 @@
 /**
  * confirm-merge.js — post-merge confirmation for a standalone Story.
  *
- * Story #3385 — `single-story-close.js` leaves a standalone Story at
- * `agent::closing` with its GitHub issue OPEN while the PR is open with
- * auto-merge armed. GitHub auto-merge completes *asynchronously* after the
- * close script exits, so the `agent::done` flip (which closes the issue)
- * must be driven by a post-merge confirmation rather than fired at
- * PR-open. This module is that driver: it reads the live PR state, and
- * only once the merge is confirmed (`state === 'MERGED'`) flips
- * `agent::closing → agent::done` — which routes through the canonical
- * `transitionTicketState` mutator that closes the issue
- * (`state: 'closed'`, `state_reason: 'completed'`).
- *
- * Outcomes (returned as a structured envelope, never thrown for the
- * not-yet-merged / recoverable cases so the CI-watch loop can re-poll):
- *
- *   - `{ action: 'done', merged: true }`
- *       PR merged → flipped `agent::done`, issue closed.
- *   - `{ action: 'noop', reason: 'already-done' }`
- *       Story already carries `agent::done`. A closed issue *alone* does
- *       NOT short-circuit — GitHub's `Closes #<id>` footer closes the issue
- *       on auto-merge before this step runs, so a closed issue whose label
- *       is still `agent::closing` must still drive the `agent::done` flip
- *       (Story #3415).
- *   - `{ action: 'pending', reason: 'pr-open' | 'pr-not-merged' }`
- *       PR is still open (or closed-without-merge); the Story is left at
- *       `agent::closing` and the issue stays OPEN. Recoverable — re-run
- *       once the merge lands.
- *
- * This mirrors the epic path's `assertMergeReachable` gate in
- * `post-merge-close.js`: the `agent::done` transition is the single
- * writer gated behind a confirmed merge, so the label sequence is exactly
- * `executing → closing → done` on a successful close and
- * `executing → closing` (sticky) on a stalled / failed PR.
+ * Auto-merge completes asynchronously after close exits, so the
+ * `agent::closing → agent::done` flip (which closes the issue) is gated on a
+ * confirmed `MERGED` PR here, never fired at PR-open. Not-yet-merged cases
+ * return `pending` rather than throw so the CI-watch loop can re-poll; a
+ * stalled PR leaves the Story sticky at `agent::closing`.
  */
 
 import { notify as defaultNotify } from '../../notify.js';
 import { gh as defaultGh } from '../gh-exec.js';
 import { Logger } from '../Logger.js';
+import { isPrMerged } from '../orchestration/merge-poll.js';
 import {
   STATE_LABELS,
   transitionTicketState,
 } from '../orchestration/ticketing.js';
 
 /**
- * Read the live PR state for `prNumber` via `gh pr view --json`.
- *
  * @param {{ cwd: string, prNumber: number, gh?: object }} args
  * @returns {Promise<{ state: string|null, mergedAt: string|null }>}
  */
 export async function readPrMergeState({ cwd, prNumber, gh = defaultGh }) {
-  // `cwd` is accepted on the signature for call-site clarity, but the
-  // `gh-exec` facade spawns `gh` against the current process cwd (matching
-  // `ensurePullRequestWith`); the CLI runs from the main-repo so the
-  // effective cwd is correct.
+  // gh-exec spawns against the process cwd (the main repo); `cwd` is
+  // accepted for call-site clarity only.
   void cwd;
   const view = await gh.pr.view(prNumber, ['state', 'mergedAt']);
-  // `gh.pr.view` resolves the parsed JSON when `--json` fields are passed.
   return {
     state: typeof view?.state === 'string' ? view.state : null,
     mergedAt: typeof view?.mergedAt === 'string' ? view.mergedAt : null,
@@ -64,22 +33,22 @@ export async function readPrMergeState({ cwd, prNumber, gh = defaultGh }) {
 }
 
 /**
- * Confirm a standalone Story's PR merged and flip `agent::closing →
- * agent::done` (closing the issue) when it has.
- *
  * @param {object} args
  * @param {object} args.provider        Ticketing provider.
  * @param {number} args.storyId
  * @param {number} args.prNumber
  * @param {string} [args.prUrl]
- * @param {string} args.cwd             Working directory for `gh`.
- * @param {object} [args.config]        Resolved config (threaded to notify).
+ * @param {string} args.cwd
+ * @param {object} [args.config]
  * @param {Function} [args.progress]
- * @param {object} [args.injectedGh]    Test seam for the `gh` facade.
- * @param {Function} [args.injectedNotify] Test seam for the notify fn.
+ * @param {object} [args.injectedGh]
+ * @param {Function} [args.injectedNotify]
  * @param {(args: object) => Promise<{state: string|null, mergedAt: string|null}>} [args.readPrMergeStateFn]
- *   Test seam for the PR-state reader.
- * @returns {Promise<object>} structured envelope (see module docblock).
+ * @param {{ state: string|null, mergedAt: string|null }} [args.prState] The
+ *   merge state the caller already read, so a land reads it once; omitted,
+ *   it is read here.
+ * @returns {Promise<object>} `done` | `noop` (already-done) | `pending`
+ *   (pr-open / pr-not-merged) | `flip-failed`.
  */
 export async function confirmStoryMerged({
   provider,
@@ -92,23 +61,16 @@ export async function confirmStoryMerged({
   injectedGh,
   injectedNotify,
   readPrMergeStateFn = readPrMergeState,
+  prState,
 }) {
   progress?.('CONFIRM', `Confirming merge for standalone Story #${storyId}...`);
 
   const story = await provider.getTicket(storyId);
 
-  // Idempotence: short-circuit only when the Story already carries
-  // `agent::done`. A *closed issue alone* is NOT sufficient — GitHub
-  // auto-merge closes the issue via the `Closes #<id>` PR footer *before*
-  // this confirm step runs, so a Story whose label is still `agent::closing`
-  // routinely arrives here with `state === 'closed'`. Gating the noop on
-  // `state === 'closed'` mistook that for already-done and skipped the
-  // `agent::closing → agent::done` flip, stranding the label and the
-  // Projects board at "In Progress" (reproduced on Story #3413 / PR #3414).
-  // Requiring the `agent::done` label preserves idempotence for a genuinely
-  // finished Story while still driving the flip for the closed-by-footer
-  // case below (`transitionTicketState` is idempotent against an
-  // already-closed issue).
+  // Only the `agent::done` label short-circuits. A closed issue alone does
+  // not: the PR's `Closes #<id>` footer closes it before this step runs, and
+  // the flip must still happen (transitionTicketState is idempotent on a
+  // closed issue).
   if (story.labels?.includes(STATE_LABELS.DONE)) {
     progress?.(
       'CONFIRM',
@@ -117,14 +79,15 @@ export async function confirmStoryMerged({
     return { storyId, action: 'noop', reason: 'already-done', merged: true };
   }
 
-  const { state, mergedAt } = await readPrMergeStateFn({
-    cwd,
-    prNumber,
-    gh: injectedGh,
-  });
+  const { state, mergedAt } =
+    prState ??
+    (await readPrMergeStateFn({
+      cwd,
+      prNumber,
+      gh: injectedGh,
+    }));
 
-  const isMerged = state === 'MERGED' || Boolean(mergedAt);
-  if (!isMerged) {
+  if (!isPrMerged({ state, mergedAt })) {
     const reason = state === 'CLOSED' ? 'pr-not-merged' : 'pr-open';
     progress?.(
       'CONFIRM',
@@ -133,11 +96,7 @@ export async function confirmStoryMerged({
     return { storyId, action: 'pending', reason, merged: false };
   }
 
-  // Merge confirmed — flip agent::closing → agent::done. This routes
-  // through the canonical mutator, which closes the issue
-  // (`state: 'closed'`, `state_reason: 'completed'`) on the `agent::done`
-  // transition. Best-effort: a flaky GitHub API must not crash the
-  // confirmation (the CI-watch loop re-runs idempotently).
+  // Best-effort: a flaky API must not crash confirmation; re-runs are idempotent.
   const flipped = await flipDone(provider, storyId, story, progress);
   if (flipped) {
     await fireStoryMergedNotify({

package/.agents/scripts/lib/single-story/story-merged-notify.js

@@ -1,26 +1,9 @@
 /**
  * story-merged-notify.js — flip a standalone Story to its close-entry rest
- * state and fire the matching operator notification.
- *
- * Story #3385 — the standalone close path no longer flips `agent::done`
- * (and no longer closes the GitHub issue) at PR-open time. GitHub
- * auto-merge completes *asynchronously* after `single-story-close.js`
- * exits, so closing the issue at PR-open left the Story marked "done"
- * while its PR could still fail CI, go `BEHIND` base, or be closed
- * without merging — stranding a CLOSED issue with no merged work.
- *
- * The fix brings the standalone path to parity with the epic path
- * (#2155): the Story rests at `agent::closing` while the PR is open with
- * auto-merge armed, and only flips `agent::done` (closing the issue) once
- * the merge is confirmed by the post-merge confirmation step
- * (`single-story-confirm-merge.js`, invoked by the CI-watch loop in
- * `single-story-deliver.md` Step 5). This module owns the close-entry
- * `agent::closing` flip + the `story-closing` notify; the `agent::done`
- * flip + the `story-merged` notify live in `./confirm-merge.js`.
- *
- * Both the label flip and the notify dispatch are best-effort: failures
- * are logged and swallowed so neither a flaky GitHub API nor a flaky
- * webhook ever fails the close.
+ * state, `agent::closing`, and fire the `story-closing` notify. The issue
+ * stays open until confirm-merge.js sees the merge, because auto-merge lands
+ * asynchronously and the PR can still fail. Both steps are best-effort:
+ * failures are logged and swallowed, never failing the close.
  */
 
 import { notify as defaultNotify } from '../../notify.js';
@@ -63,34 +46,10 @@ export async function flipLabelAndNotify({
 
 async function flipLabel(provider, storyId, story, progress, config) {
   try {
-    // Story #3385 — flip to `agent::closing`, NOT `agent::done`. The
-    // canonical mutator (`transitionTicketState`) only closes the GitHub
-    // issue (`state: 'closed'`, `state_reason: 'completed'`) on a
-    // transition to `agent::done`; flipping to `agent::closing` leaves the
-    // issue OPEN, which is exactly the rest state the standalone path must
-    // hold while the PR is open with auto-merge armed.
-    //
-    // Route through the canonical state mutator so the Projects v2 Status
-    // column mirrors the `agent::closing` flip (Story #2548 wires
-    // column-sync inside `transitionTicketState`). Threading the
-    // prefetched `story` as `ticketSnapshot` preserves the round-trip
-    // elimination from Story #1795.
-    //
-    // Cascade is left at the default (true) so Stories that have a parent
-    // Feature (e.g. an Epic-parented Story closed via the standalone path)
-    // propagate the `agent::closing` state upward. For truly standalone
-    // Stories with no parent the cascade short-circuits immediately via
-    // the provider-capability guard in `cascadeParentState`, so there is
-    // no extra cost.
-    //
-    // We deliberately omit `notify` here: the `state-transition`
-    // notification that `transitionTicketState` would dispatch is
-    // redundant with the typed `story-closing` event that
-    // `fireStoryClosingNotify` emits immediately afterwards.
-    //
-    // `config` is threaded so the on-disk board-metadata cache (issue #4555)
-    // lands under the project's configured `tempRoot` rather than the
-    // framework default, matching every other transition call site.
+    // Only an `agent::done` transition closes the issue, so this leaves it
+    // open. The canonical mutator also syncs the board column and cascades
+    // to any parent. `notify` is omitted: the typed `story-closing` event
+    // below supersedes the generic state-transition one.
     await transitionTicketState(provider, storyId, STATE_LABELS.CLOSING, {
       ticketSnapshot: story,
       config,

package/.agents/scripts/lib/single-story-sweep/protection-ctx.js

@@ -1,35 +1,17 @@
 /**
  * single-story-sweep/protection-ctx.js
  *
- * Shared builder for the `evaluateProtection` context the boot-sweep
- * engine ([`sweepMergedBranches`](../single-story-sweep.js)) threads into
- * every candidate protection check. Single-homed here so the three boot
- * callers — `single-story-init.js` and the
- * `boot-sweep.js` CLI — build an identical ctx instead of each re-wiring
- * the git/gh/ticket ports.
- *
- * Story #2990: the sweep protection-ctx `ghRunner` stays on raw
- * `spawnSync('gh', …)` (not the `lib/gh-exec.js` async facade) because
- * `executeCleanup` invokes the protection checks inside a synchronous
- * candidate-filter loop. The runner contract is the legacy
- * `(args, opts) => stdout string` shape.
+ * The one builder of the `evaluateProtection` ctx for every sweep caller.
+ * `ghRunner` stays on synchronous `spawnSync` (not the async gh-exec facade)
+ * because the checks run inside a synchronous candidate-filter loop.
  */
 
 import { spawnSync as defaultSpawnSync } from 'node:child_process';
 import { gitSpawn } from '../git-utils.js';
 
 /**
- * Build the synchronous `gh` runner the sweep uses for its
- * candidate-protection checks.
- *
- * Story #4073: the `spawnImpl` seam injects the `spawnSync` boundary so
- * the runner's success/error handling can be unit-tested without a live
- * `gh` binary. It defaults to `child_process.spawnSync`, so the
- * production CLI path is unchanged.
- *
  * @param {string} cwd Repo root used as the default spawn cwd.
- * @param {typeof defaultSpawnSync} [spawnImpl] Injectable spawn boundary —
- *   defaults to `child_process.spawnSync`.
+ * @param {typeof defaultSpawnSync} [spawnImpl]
  * @returns {(args: string[], opts?: { cwd?: string }) => string}
  */
 export function makeGhRunner(cwd, spawnImpl = defaultSpawnSync) {
@@ -49,10 +31,6 @@ export function makeGhRunner(cwd, spawnImpl = defaultSpawnSync) {
 }
 
 /**
- * Build the `evaluateProtection` ctx bag: the repo root, the `gitSpawn`
- * port, the synchronous `gh` runner, and a `getTicket` port bound to the
- * supplied provider.
- *
  * @param {{
  *   cwd: string,
  *   provider: { getTicket: (id: number) => Promise<object> },