mandrel 1.57.0

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

@@ -0,0 +1,290 @@
+/**
+ * Span-tree builder (Epic #1181 / Story #1440 / Task #1461).
+ *
+ * Pure transform over the `lib/signals/read` async iterator. Materialises
+ * a tree of:
+ *
+ *   epic
+ *     story (id)
+ *       task (id)
+ *         events (chronological)
+ *
+ * with `startedAt` / `endedAt` / `durationMs` computed from paired
+ * lifecycle events when they exist. The Tech Spec (#1433) defines the
+ * shape; this module is the canonical implementation.
+ *
+ * ## Lifecycle pairing
+ *
+ *   The schema audit in `lib/signals/schema.js` confirms that
+ *   `wave-start` / `wave-end` envelopes carry `epicId` + `storyId` and
+ *   bracket a Story's lifetime in a wave.
+ *   Per-Task lifecycle today comes via `state-transition` events
+ *   (`agent::executing` → `agent::done`) — we treat the **first**
+ *   timestamp we see for a given (story, task) pair as `startedAt` and
+ *   the **last** as `endedAt`. This is intentionally permissive: the
+ *   span-tree's contract is "what we have", not "what we wish were
+ *   emitted". When a Task has only a start event the `durationMs` stays
+ *   `null` per AC#2.
+ *
+ *   `wave-start` / `wave-end` (or any kind starting with `story.`)
+ *   anchor the Story-level start/end when present; absent those, we
+ *   fall back to the min/max of every event under that Story.
+ *
+ * ## Purity
+ *
+ *   No I/O, no globals, no `Date.now()` reads. The function is a pure
+ *   reducer over the iterator — identical input produces identical
+ *   output (AC#1). Time references come exclusively from the events'
+ *   own `ts` / `timestamp` fields.
+ *
+ * ## Empty input
+ *
+ *   `buildSpanTree(emptyIter)` with **no events** returns
+ *   `{ epic: null, stories: [] }` — the Epic is unknown when we never
+ *   see one (AC#3). When at least one event flows through we pin
+ *   `epic` to its `epic` / `epicId` field; mixed-Epic iterators
+ *   (uncommon — `read()` is single-Epic) take the first observed Epic
+ *   ID and ignore the rest with no warning, since silent permissiveness
+ *   is the pure-function contract.
+ *
+ * @module lib/signals/span-tree
+ */
+
+function tsOf(evt) {
+  // Schema accepts both `ts` (canonical) and `timestamp` (legacy).
+  return evt?.ts ?? evt?.timestamp ?? null;
+}
+
+function epicOf(evt) {
+  return evt?.epic ?? evt?.epicId ?? null;
+}
+
+function storyOf(evt) {
+  return evt?.story ?? evt?.storyId ?? null;
+}
+
+function taskOf(evt) {
+  return evt?.task ?? evt?.taskId ?? null;
+}
+
+/**
+ * Lexicographic timestamp comparison. ISO-8601 strings compare correctly
+ * with `<` / `>`, so we avoid the Date round-trip and stay pure (no TZ
+ * normalisation surprises).
+ *
+ * @param {string | null} a
+ * @param {string | null} b
+ * @returns {number} -1 / 0 / 1 (nulls sort last)
+ */
+function cmpTs(a, b) {
+  if (a === b) return 0;
+  if (a == null) return 1;
+  if (b == null) return -1;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+function diffMs(start, end) {
+  if (start == null || end == null) return null;
+  const s = Date.parse(start);
+  const e = Date.parse(end);
+  if (!Number.isFinite(s) || !Number.isFinite(e)) return null;
+  return e - s;
+}
+
+function isStoryLifecycle(kind) {
+  return (
+    kind === 'wave-start' ||
+    kind === 'wave-end' ||
+    kind === 'story.start' ||
+    kind === 'story.end'
+  );
+}
+
+function isStoryStart(kind) {
+  return kind === 'wave-start' || kind === 'story.start';
+}
+
+function isStoryEnd(kind) {
+  return kind === 'wave-end' || kind === 'story.end';
+}
+
+function emptyTaskNode(id) {
+  return {
+    id,
+    startedAt: null,
+    endedAt: null,
+    durationMs: null,
+    events: [],
+  };
+}
+
+function emptyStoryNode(id) {
+  return {
+    id,
+    startedAt: null,
+    endedAt: null,
+    durationMs: null,
+    tasks: [],
+    events: [],
+  };
+}
+
+function storyKeyOf(sid) {
+  return sid == null ? '__none__' : String(sid);
+}
+
+function getOrCreateStory(state, sid) {
+  const key = storyKeyOf(sid);
+  let node = state.stories.get(key);
+  if (!node) {
+    node = emptyStoryNode(sid);
+    state.stories.set(key, node);
+    state.tasksByStory.set(key, new Map());
+  }
+  return { key, node };
+}
+
+function getOrCreateTask(state, storyKey, tid) {
+  const taskMap = state.tasksByStory.get(storyKey);
+  const tkey = String(tid);
+  let node = taskMap.get(tkey);
+  if (!node) {
+    node = emptyTaskNode(tid);
+    taskMap.set(tkey, node);
+  }
+  return node;
+}
+
+function updateStoryLifecycle(storyNode, kind, ts) {
+  if (!isStoryLifecycle(kind)) return;
+  if (isStoryStart(kind)) {
+    if (storyNode.startedAt == null || cmpTs(ts, storyNode.startedAt) < 0) {
+      storyNode.startedAt = ts;
+    }
+  } else if (isStoryEnd(kind)) {
+    if (storyNode.endedAt == null || cmpTs(ts, storyNode.endedAt) > 0) {
+      storyNode.endedAt = ts;
+    }
+  }
+}
+
+function widenTaskWindow(taskNode, ts) {
+  if (ts == null) return;
+  if (taskNode.startedAt == null || cmpTs(ts, taskNode.startedAt) < 0) {
+    taskNode.startedAt = ts;
+  }
+  if (taskNode.endedAt == null || cmpTs(ts, taskNode.endedAt) > 0) {
+    taskNode.endedAt = ts;
+  }
+}
+
+function bootstrapStoryWindow(storyNode, ts) {
+  if (ts == null) return;
+  if (storyNode.startedAt == null) storyNode.startedAt = ts;
+  if (storyNode.endedAt == null) storyNode.endedAt = ts;
+}
+
+/**
+ * Reducer step — fold a single event into the running state. Extracted
+ * from `buildSpanTree` so the outer function's CRAP score stays under
+ * the new-method ceiling.
+ *
+ * @param {object} state — mutable accumulator (stories, tasksByStory, epic)
+ * @param {unknown} evt
+ * @returns {void}
+ */
+function ingestEvent(state, evt) {
+  if (evt == null || typeof evt !== 'object') return;
+
+  const eEpic = epicOf(evt);
+  if (state.epic == null && eEpic != null) state.epic = eEpic;
+
+  const ts = tsOf(evt);
+  const sid = storyOf(evt);
+  const tid = taskOf(evt);
+  const kind = typeof evt.kind === 'string' ? evt.kind : null;
+
+  const { key: storyKey, node: storyNode } = getOrCreateStory(state, sid);
+  updateStoryLifecycle(storyNode, kind, ts);
+
+  if (tid != null) {
+    const taskNode = getOrCreateTask(state, storyKey, tid);
+    widenTaskWindow(taskNode, ts);
+    taskNode.events.push(evt);
+  } else {
+    storyNode.events.push(evt);
+  }
+
+  bootstrapStoryWindow(storyNode, ts);
+}
+
+/**
+ * Default comparator for sorting Story / Task nodes by id ascending,
+ * with `null` ids sorting last and a string fallback for slug-shaped
+ * Task ids (the framework allows non-numeric task identifiers).
+ *
+ * @param {object} a
+ * @param {object} b
+ * @returns {number}
+ */
+function compareNodeIds(a, b) {
+  if (a.id === b.id) return 0;
+  if (a.id == null) return 1;
+  if (b.id == null) return -1;
+  if (typeof a.id === 'number' && typeof b.id === 'number') {
+    return a.id - b.id;
+  }
+  return String(a.id).localeCompare(String(b.id));
+}
+
+function finalizeTask(task) {
+  task.events.sort((ea, eb) => cmpTs(tsOf(ea), tsOf(eb)));
+  task.durationMs = diffMs(task.startedAt, task.endedAt);
+}
+
+function finalizeStory(state, story) {
+  const taskMap = state.tasksByStory.get(storyKeyOf(story.id));
+  const taskEntries = [...taskMap.values()];
+  taskEntries.sort(compareNodeIds);
+  for (const task of taskEntries) finalizeTask(task);
+  story.events.sort((ea, eb) => cmpTs(tsOf(ea), tsOf(eb)));
+  story.durationMs = diffMs(story.startedAt, story.endedAt);
+}
+
+/**
+ * Build the span tree from an async iterable of signal events.
+ *
+ * @param {AsyncIterable<object> | Iterable<object>} iter
+ * @returns {Promise<{ epic: number | null, stories: Array<object> }>}
+ *
+ * @example
+ *   import { read, buildSpanTree } from './lib/signals/index.js';
+ *   const tree = await buildSpanTree(read({ epic: 1181 }));
+ */
+export async function buildSpanTree(iter) {
+  if (iter == null || typeof iter !== 'object') {
+    throw new TypeError(
+      `signals/span-tree: iter must be an async iterable; got ${iter}`,
+    );
+  }
+
+  // Accumulator state. `stories` keys are `storyKeyOf(sid)` strings;
+  // `tasksByStory` mirrors that and holds per-task sub-maps.
+  const state = {
+    epic: null,
+    stories: new Map(),
+    tasksByStory: new Map(),
+  };
+
+  for await (const evt of iter) {
+    ingestEvent(state, evt);
+  }
+
+  const storyEntries = [...state.stories.values()];
+  storyEntries.sort(compareNodeIds);
+  for (const story of storyEntries) finalizeStory(state, story);
+
+  return { epic: state.epic, stories: storyEntries };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * `lib/signals/write.js` — thin re-export of the signals/traces 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.
+ */
+
+export {
+  appendEpicSignal,
+  appendSignal,
+  appendTrace,
+  forEachLine,
+} from '../observability/signals-writer.js';

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

@@ -0,0 +1,201 @@
+/**
+ * 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.
+ */
+
+import { notify as defaultNotify } from '../../notify.js';
+import { gh as defaultGh } from '../gh-exec.js';
+import { Logger } from '../Logger.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.
+  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,
+  };
+}
+
+/**
+ * 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 {Function} [args.progress]
+ * @param {object} [args.injectedGh]    Test seam for the `gh` facade.
+ * @param {Function} [args.injectedNotify] Test seam for the notify fn.
+ * @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).
+ */
+export async function confirmStoryMerged({
+  provider,
+  storyId,
+  prNumber,
+  prUrl,
+  cwd,
+  config,
+  progress,
+  injectedGh,
+  injectedNotify,
+  readPrMergeStateFn = readPrMergeState,
+}) {
+  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).
+  if (story.labels?.includes(STATE_LABELS.DONE)) {
+    progress?.(
+      'CONFIRM',
+      `⏭  Story #${storyId} already agent::done — nothing to confirm.`,
+    );
+    return { storyId, action: 'noop', reason: 'already-done', merged: true };
+  }
+
+  const { state, mergedAt } = await readPrMergeStateFn({
+    cwd,
+    prNumber,
+    gh: injectedGh,
+  });
+
+  const isMerged = state === 'MERGED' || Boolean(mergedAt);
+  if (!isMerged) {
+    const reason = state === 'CLOSED' ? 'pr-not-merged' : 'pr-open';
+    progress?.(
+      'CONFIRM',
+      `⏳ PR #${prNumber} not yet merged (state=${state ?? 'unknown'}). Story stays at agent::closing.`,
+    );
+    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).
+  const flipped = await flipDone(provider, storyId, story, progress);
+  if (flipped) {
+    await fireStoryMergedNotify({
+      notifyFn: injectedNotify ?? defaultNotify,
+      storyId,
+      story,
+      prUrl,
+      config,
+      provider,
+    });
+  }
+  return {
+    storyId,
+    action: flipped ? 'done' : 'flip-failed',
+    merged: true,
+  };
+}
+
+async function flipDone(provider, storyId, story, progress) {
+  try {
+    await transitionTicketState(provider, storyId, STATE_LABELS.DONE, {
+      ticketSnapshot: story,
+    });
+    progress?.(
+      'LABELS',
+      `🏷️  Story #${storyId} → agent::done (merge confirmed)`,
+    );
+    return true;
+  } catch (err) {
+    Logger.error(
+      `[single-story-confirm-merge] ⚠️ Failed to flip Story #${storyId} to agent::done: ${err?.message ?? err}`,
+    );
+    return false;
+  }
+}
+
+async function fireStoryMergedNotify({
+  notifyFn,
+  storyId,
+  story,
+  prUrl,
+  config,
+  provider,
+}) {
+  try {
+    await notifyFn(
+      storyId,
+      {
+        severity: 'medium',
+        message: `✅ Standalone Story #${storyId} — *${story.title}* — merge confirmed; flipped to \`agent::done\` and closed the issue.${prUrl ? ` PR: ${prUrl}.` : ''}`,
+        event: 'story-merged',
+        level: 'story',
+      },
+      { config, provider },
+    );
+  } catch (err) {
+    Logger.warn(
+      `[single-story-confirm-merge] ⚠️ story-merged notify dispatch failed (swallowed): ${err?.message ?? err}`,
+    );
+  }
+}

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

@@ -0,0 +1,126 @@
+/**
+ * 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.
+ */
+
+import { notify as defaultNotify } from '../../notify.js';
+import { Logger } from '../Logger.js';
+import {
+  STATE_LABELS,
+  transitionTicketState,
+} from '../orchestration/ticketing.js';
+
+export async function flipLabelAndNotify({
+  provider,
+  notifyFn,
+  storyId,
+  story,
+  prUrl,
+  autoMergeEnabled,
+  autoMergeReason,
+  config,
+  progress,
+}) {
+  const labelFlipped = await flipLabel(provider, storyId, story, progress);
+  if (!labelFlipped) return;
+  await fireStoryClosingNotify({
+    notifyFn: notifyFn ?? defaultNotify,
+    storyId,
+    story,
+    prUrl,
+    autoMergeEnabled,
+    autoMergeReason,
+    config,
+    provider,
+  });
+}
+
+async function flipLabel(provider, storyId, story, progress) {
+  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.
+    await transitionTicketState(provider, storyId, STATE_LABELS.CLOSING, {
+      ticketSnapshot: story,
+    });
+    progress?.('LABELS', `🏷️  Story #${storyId} → agent::closing`);
+    return true;
+  } catch (err) {
+    Logger.error(
+      `[single-story-close] ⚠️ Failed to flip Story labels: ${err?.message ?? err}`,
+    );
+    return false;
+  }
+}
+
+async function fireStoryClosingNotify({
+  notifyFn,
+  storyId,
+  story,
+  prUrl,
+  autoMergeEnabled,
+  autoMergeReason,
+  config,
+  provider,
+}) {
+  const autoMergeNote = autoMergeEnabled
+    ? 'auto-merge enabled — GitHub will squash-merge when required checks pass, then the Story flips to `agent::done`'
+    : `auto-merge not enabled (${autoMergeReason ?? 'unknown'}) — operator merges via GitHub UI, then the Story flips to \`agent::done\``;
+  try {
+    await notifyFn(
+      storyId,
+      {
+        severity: 'medium',
+        message: `🔁 Standalone Story #${storyId} — *${story.title}* — flipped to \`agent::closing\`. PR: ${prUrl} (${autoMergeNote}). The issue stays OPEN until the merge is confirmed.`,
+        event: 'story-closing',
+        level: 'story',
+      },
+      { config, provider },
+    );
+  } catch (err) {
+    Logger.warn(
+      `[single-story-close] ⚠️ story-closing notify dispatch failed (swallowed): ${err?.message ?? err}`,
+    );
+  }
+}