mandrel 1.94.0 → 2.1.0

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

@@ -1,18 +1,18 @@
 /**
  * Streaming signals reader (Epic #1181 / Story #1438 / Task #1459).
  *
- * Provides one async-iterator entry point — `read({ epic, story?, kind?,
+ * Provides one async-iterator entry point — `read({ run, story?, kind?,
  * config? })` — that consumers use instead of opening the NDJSON file
  * themselves. The reader streams line-by-line so callers never load the
  * full file into memory (50MB+ traces stay under file size in RSS).
  *
  * On-disk layout (resolved via `lib/config/temp-paths.js`):
  *
- *   <tempRoot>/epic-<epic>/story-<story>/signals.ndjson
+ *   <tempRoot>/run-<run>/story-<story>/signals.ndjson
  *
  * When `story` is omitted, the reader fans out across every
- * `story-<id>/signals.ndjson` under `<tempRoot>/epic-<epic>/`. When the
- * Epic directory is missing, the iterator yields nothing (consumers
+ * `story-<id>/signals.ndjson` under `<tempRoot>/run-<run>/`. When the
+ * run directory is missing, the iterator yields nothing (consumers
  * treat absence as "no signals yet").
  *
  * ## Filter semantics
@@ -21,7 +21,7 @@
  *     argument are yielded. Filtering happens after the per-line JSON
  *     parse + envelope guard (see `lib/signals/schema.js`).
  *   - `story` — narrows to a single Story's stream; otherwise we walk
- *     every Story directory under the Epic.
+ *     every Story directory under the run.
  *
  * ## Warn-once policy (AC #3)
  *
@@ -46,8 +46,8 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
 import {
-  epicArtifactPath,
-  epicTempDir,
+  runArtifactPath,
+  runTempDir,
   signalsFile,
   storyTempDir,
 } from '../config/temp-paths.js';
@@ -145,43 +145,43 @@ async function* streamFile(target, kindFilter) {
 }
 
 /**
- * List every `stories/story-<id>/signals.ndjson` path under the Epic's
- * `<tempRoot>/epic-<epic>/` directory. Returns an empty array when the
- * Epic directory is missing.
+ * List every `stories/story-<id>/signals.ndjson` path under the run's
+ * `<tempRoot>/run-<run>/` directory. Returns an empty array when the
+ * run directory is missing.
  *
  * The returned paths are sorted by Story ID ascending so the iterator's
  * output is stable across runs.
  *
  * Story #2940 nested per-Story directories under a `stories/` segment.
- * Epic-level signals continue to live at the Epic root.
+ * Run-level signals continue to live at the run root.
  *
- * @param {number} epic
+ * @param {number} run
  * @param {object | undefined} config
  * @returns {Promise<string[]>}
  */
-async function listEpicStorySignalsFiles(epic, config) {
-  const epicDir = epicTempDir(epic, config);
-  let epicEntries;
+async function listRunStorySignalsFiles(run, config) {
+  const runDir = runTempDir(run, config);
+  let runEntries;
   try {
-    epicEntries = await fs.readdir(epicDir, { withFileTypes: true });
+    runEntries = await fs.readdir(runDir, { withFileTypes: true });
   } catch {
     return [];
   }
-  let hasEpicLevelSignals = false;
+  let hasRunLevelSignals = false;
   let hasStoriesDir = false;
-  for (const ent of epicEntries) {
+  for (const ent of runEntries) {
     if (ent.isDirectory() && ent.name === 'stories') {
       hasStoriesDir = true;
     } else if (ent.isFile() && ent.name === 'signals.ndjson') {
       // Story #1430 — wave-runner lifecycle signals land here.
-      hasEpicLevelSignals = true;
+      hasRunLevelSignals = true;
     }
   }
   const storyIds = [];
   if (hasStoriesDir) {
     let storyEntries;
     try {
-      storyEntries = await fs.readdir(path.join(epicDir, 'stories'), {
+      storyEntries = await fs.readdir(path.join(runDir, 'stories'), {
         withFileTypes: true,
       });
     } catch {
@@ -195,43 +195,43 @@ async function listEpicStorySignalsFiles(epic, config) {
     }
   }
   storyIds.sort((a, b) => a - b);
-  // Yield epic-level signals first (wave-start precedes per-Story friction),
+  // Yield run-level signals first (wave-start precedes per-Story friction),
   // then walk the per-Story streams in ascending ID order.
-  const targets = hasEpicLevelSignals
-    ? [epicArtifactPath(epic, 'signals.ndjson', config)]
+  const targets = hasRunLevelSignals
+    ? [runArtifactPath(run, 'signals.ndjson', config)]
     : [];
   for (const sid of storyIds) {
-    targets.push(path.join(storyTempDir(epic, sid, config), 'signals.ndjson'));
+    targets.push(path.join(storyTempDir(run, sid, config), 'signals.ndjson'));
   }
   return targets;
 }
 
 /**
- * Stream every event matching `{ epic, story?, kind? }` from the
- * configured `tempRoot`'s `epic-<epic>/[story-<story>/]signals.ndjson`
+ * Stream every event matching `{ run, story?, kind? }` from the
+ * configured `tempRoot`'s `run-<run>/[story-<story>/]signals.ndjson`
  * file(s).
  *
  * Returns an async iterable so callers can `for await` over it without
  * buffering. The reader is **streaming** — peak memory stays below the
  * file size for any input.
  *
- * @param {{ epic: number, story?: number, kind?: string, config?: object }} args
+ * @param {{ run: number, story?: number, kind?: string, config?: object }} args
  * @returns {AsyncGenerator<object>}
  *
  * @example
- *   for await (const evt of read({ epic: 1181 })) { ... }
- *   for await (const evt of read({ epic: 1181, story: 1438, kind: 'friction' })) { ... }
+ *   for await (const evt of read({ run: 1181 })) { ... }
+ *   for await (const evt of read({ run: 1181, story: 1438, kind: 'friction' })) { ... }
  */
 export async function* read(args) {
   if (args == null || typeof args !== 'object') {
     throw new TypeError(
-      `signals/read: args must be an object with at minimum { epic }; got ${args}`,
+      `signals/read: args must be an object with at minimum { run }; got ${args}`,
     );
   }
-  const { epic, story, kind, config } = args;
-  if (!isPositiveInt(epic)) {
+  const { run, story, kind, config } = args;
+  if (!isPositiveInt(run)) {
     throw new RangeError(
-      `signals/read: epic must be a positive integer (got ${epic})`,
+      `signals/read: run must be a positive integer (got ${run})`,
     );
   }
   if (story !== undefined && !isPositiveInt(story)) {
@@ -259,8 +259,8 @@ export async function* read(args) {
   const kindFilter = kind ?? null;
   const targets =
     story !== undefined
-      ? [signalsFile(epic, story, config)]
-      : await listEpicStorySignalsFiles(epic, config);
+      ? [signalsFile(run, story, config)]
+      : await listRunStorySignalsFiles(run, config);
 
   for (const target of targets) {
     yield* streamFile(target, kindFilter);

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

@@ -3,7 +3,7 @@
  * shape guards (Epic #1181 / Story #1438 / Task #1458).
  *
  * Both writers (`lib/observability/signals-writer.js` callers) and
- * readers (`lib/signals/read.js`, `lib/observability/perf-aggregator.js`)
+ * 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.
  *
@@ -19,15 +19,12 @@
  *
  * Signals-writer `appendSignal` call sites:
  *   - `friction`       — quality-gate / runtime friction (diagnose-friction.js,
- *                        lib/gates/friction.js, auto-refresh-runner.js,
- *                        worktree-reap.js, lifecycle-emit.js)
+ *                        lib/gates/friction.js)
  *   - `acceptance-eval` — acceptance-eval.js per-criterion terminus signal.
- *   - `wave-start` / `wave-complete` — `lib/wave-runner/tick.js` (read by
- *                        perf-aggregator's `waveParallelism` report;
- *                        `wave-start` also anchors span-tree Story spans)
+ *   - `wave-start` / `wave-complete` — wave-window anchors; `wave-start` also
+ *                        anchors span-tree Story spans
  *   - `wave-end`       — span-tree pairing anchor (retained for span-tree)
- *   - `state-transition` — notification-derived window anchor read by the
- *                        waveParallelism bucketer.
+ *   - `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.
@@ -80,9 +77,9 @@ 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, and the perf-aggregator brackets each wave's
-  // wall-clock from `wave-start` → `wave-complete` (the `waveParallelism`
-  // report). These are READ — they survive.
+  // 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_START: 'wave-start',
   WAVE_END: 'wave-end',
   WAVE_COMPLETE: 'wave-complete',

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

@@ -192,15 +192,15 @@ function bootstrapStoryWindow(storyNode, ts) {
  * from `buildSpanTree` so the outer function's CRAP score stays under
  * the new-method ceiling.
  *
- * @param {object} state — mutable accumulator (stories, tasksByStory, epic)
+ * @param {object} state — mutable accumulator (stories, tasksByStory, run)
  * @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 eRun = epicOf(evt);
+  if (state.run == null && eRun != null) state.run = eRun;
 
   const ts = tsOf(evt);
   const sid = storyOf(evt);
@@ -258,11 +258,11 @@ function finalizeStory(state, story) {
  * 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> }>}
+ * @returns {Promise<{ run: number | null, stories: Array<object> }>}
  *
  * @example
  *   import { read, buildSpanTree } from './lib/signals/index.js';
- *   const tree = await buildSpanTree(read({ epic: 1181 }));
+ *   const tree = await buildSpanTree(read({ run: 1181 }));
  */
 export async function buildSpanTree(iter) {
   if (iter == null || typeof iter !== 'object') {
@@ -274,7 +274,7 @@ export async function buildSpanTree(iter) {
   // Accumulator state. `stories` keys are `storyKeyOf(sid)` strings;
   // `tasksByStory` mirrors that and holds per-task sub-maps.
   const state = {
-    epic: null,
+    run: null,
     stories: new Map(),
     tasksByStory: new Map(),
   };
@@ -287,5 +287,5 @@ export async function buildSpanTree(iter) {
   storyEntries.sort(compareNodeIds);
   for (const story of storyEntries) finalizeStory(state, story);
 
-  return { epic: state.epic, stories: storyEntries };
+  return { run: state.run, stories: storyEntries };
 }

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

@@ -12,7 +12,6 @@
  */
 
 export {
-  appendEpicSignal,
   appendSignal,
   appendTrace,
   forEachLine,

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

@@ -41,7 +41,13 @@ export async function flipLabelAndNotify({
   config,
   progress,
 }) {
-  const labelFlipped = await flipLabel(provider, storyId, story, progress);
+  const labelFlipped = await flipLabel(
+    provider,
+    storyId,
+    story,
+    progress,
+    config,
+  );
   if (!labelFlipped) return;
   await fireStoryClosingNotify({
     notifyFn: notifyFn ?? defaultNotify,
@@ -55,7 +61,7 @@ export async function flipLabelAndNotify({
   });
 }
 
-async function flipLabel(provider, storyId, story, progress) {
+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
@@ -81,8 +87,13 @@ async function flipLabel(provider, storyId, story, progress) {
     // 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.
     await transitionTicketState(provider, storyId, STATE_LABELS.CLOSING, {
       ticketSnapshot: story,
+      config,
     });
     progress?.('LABELS', `🏷️  Story #${storyId} → agent::closing`);
     return true;

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

@@ -4,7 +4,7 @@
  * 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`, `epic-deliver-prepare.js`, and the
+ * 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.
  *

package/.agents/scripts/lib/skills/parse-skill.js

@@ -30,6 +30,8 @@ const FRONTMATTER_DELIMITER = '---';
 const POLICY_HEADING_RE = /^## Policy Capsule\s*$/;
 const ANY_H2_RE = /^## /;
 const BULLET_RE = /^- /;
+/** An indented (wrapped) continuation of the bullet above it. */
+const CONTINUATION_RE = /^\s+\S/;
 
 /**
  * Repo root resolver. Walks up from the SKILL.md path until we find a
@@ -85,8 +87,14 @@ function extractFrontmatterBlock(lines, skillPath) {
 /**
  * Scan the body for the '## Policy Capsule' heading and count contiguous
  * top-level '- ' bullets that follow it, stopping at the next '## ' heading
- * or end-of-file. Blank lines inside the bullet run do not reset the count;
- * a non-bullet, non-blank line does.
+ * or end-of-file. Blank lines inside the bullet run do not reset the count.
+ *
+ * An **indented** continuation line belongs to the bullet above it — capsule
+ * bullets routinely wrap at the document's prose width — so it neither counts
+ * as a new bullet nor terminates the run. Only a **flush-left**, non-blank,
+ * non-bullet line after the run terminates it (Story #4546: treating any
+ * non-bullet line as a terminator counted a wrapped 5-bullet capsule as 1 and
+ * tripped the floor in validate-skills.js).
  */
 function findPolicyCapsule(lines, bodyStart) {
   let headingIndex = -1;
@@ -114,8 +122,13 @@ function findPolicyCapsule(lines, bodyStart) {
       // Blank lines inside or before the bullet run are tolerated.
       continue;
     }
+    if (sawBulletRun && CONTINUATION_RE.test(line)) {
+      // Indented continuation of the bullet above — same bullet, not a
+      // terminator. Wrapped capsule bullets are the norm, not an error.
+      continue;
+    }
     if (sawBulletRun) {
-      // Non-blank, non-bullet line after the bullet run terminates it.
+      // Flush-left, non-blank, non-bullet line after the run terminates it.
       break;
     }
     // Leading prose between heading and the first bullet is allowed.

package/.agents/scripts/lib/story-adjacency.js

@@ -1,27 +1,24 @@
 /**
  * lib/story-adjacency.js — the single story-level adjacency builder.
  *
- * Both Epic-path wave-computation wrappers bottom out in the shared
+ * Both pre-v2 Epic wave wrappers and the v2 `/deliver` ready-set path bottom out in the shared
  * `lib/Graph.js` kernel (`detectCycle` / `assignLayers` / `computeWaves`),
  * but each historically re-implemented the step that turns a list of Story
  * records into the `Map<storyId, number[]>` adjacency the kernel consumes.
- * This module is now the one home for that step; the consumers are:
+ * This module is now the one home for that step; the live consumer is:
  *
- *   - `lib/orchestration/epic-runner/phases/build-wave-dag.js`
- *     (`buildStoryDag` → `computeWaves`)
- *   - `lib/orchestration/dispatch-pipeline.js`
- *     (`buildStoryDispatchGraph` → `computeStoryWaves`)
  *   - `lib/wave-runner/ready-set.js` (`selectReadySet`, the path-agnostic
- *     continuous scheduler the standalone `stories-wave-tick.js` adapter
- *     and the Epic path both dispatch through)
+ *     continuous scheduler the `stories-wave-tick.js` adapter dispatches through)
  *   - `stories-wave-tick.js` (for cycle detection, before delegating
  *     selection to `selectReadySet`)
  *
- * Dependency source order (must stay aligned with manifest-builder.js so
- * the dispatch manifest and runtime wave scheduling never disagree):
+ * (Pre-v2: `epic-runner/phases/build-wave-dag.js` and `dispatch-pipeline.js`
+ * also called here; both entry seams were deleted.)
+ *
+ * Dependency source order (must stay aligned with `manifest-builder.js` and
+ * `helpers/deliver-story.md` so planning and runtime scheduling never disagree):
  *   1. Canonical: `blocked by #NNN` / `depends on #NNN` parsed from the
- *      Story body via `parseBlockedBy` (the same parser the dispatcher
- *      uses).
+ *      Story body via `parseBlockedBy` (the same parser planning uses).
  *   2. Fallback: an explicit `dependencies` (ticket shape) or
  *      `dependsOn` (operator-DAG shape) array on the Story record.
  *
@@ -45,16 +42,17 @@ import { parseBlockedBy } from './dependency-parser.js';
  *   Story records (live ticket payloads, fixture tickets, or operator
  *   DAG nodes).
  * @param {object} [opts]
- * @param {boolean} [opts.dropForeign=true] When true (the default,
- *   matching the Epic-scoped wrappers), edges pointing at ids outside
+ * @param {boolean} [opts.dropForeign=false] When `false` (the v2 default,
+ *   matching the `/deliver` path — `stories-wave-tick.js` and the
+ *   `selectReadySet` core), the operator-DAG contract is preserved: a
+ *   dependency on an id absent from the input is treated as not-yet-done
+ *   and withholds the dependent until it completes. When `true` (the
+ *   pre-v2 Epic-scoped-wrapper semantics), edges pointing at ids outside
  *   the supplied story set are dropped so the DAG stays closed over the
- *   scheduled set. The standalone path (`stories-wave-tick.js` and the
- *   `selectReadySet` core) passes `false` to preserve the operator-DAG
- *   contract, where a dependency on an id absent from the input is treated
- *   as not-yet-done and withholds the dependent until it completes.
+ *   scheduled set.
  * @returns {Map<number, number[]>}
  */
-export function buildStoryAdjacency(stories, { dropForeign = true } = {}) {
+export function buildStoryAdjacency(stories, { dropForeign = false } = {}) {
   const records = Array.isArray(stories) ? stories : [];
   const storyIds = new Set(records.map((s) => Number(s?.id ?? s?.number)));
   const adjacency = new Map();