mandrel 1.94.0 → 2.0.0

package/.agents/scripts/lib/orchestration/code-review.js

@@ -21,7 +21,8 @@
  *
  * Behaviour:
  *   - Loads the configured review adapter via the factory; defaults to
- *     `native` when `delivery.codeReview.provider` is unset.
+ *     a single `native` chain entry when `delivery.codeReview.providers`
+ *     is unset or empty.
  *   - Always posts the unified `verification-results` structured comment on
  *     the Epic issue (the adapter never posts; the orchestrator owns
  *     persistence). Story #4411 (Epic #4405) unified the former
@@ -36,11 +37,8 @@
  */
 
 import { hasSurvivingCritical } from '../audit-suite/findings.js';
-import { resolveLensTier } from '../audit-suite/selector.js';
 import { resolveConfig } from '../config-resolver.js';
-import { selectAuditStrategy } from '../dynamic-workflow/capability.js';
 import { gitSpawn } from '../git-utils.js';
-import { read as readPlanState } from './epic-plan-state-store.js';
 import { resolveDepth } from './review-depth.js';
 import {
   countBySeverity,
@@ -93,248 +91,6 @@ function countChangedFiles({ baseRef, headRef, gitSpawnFn = gitSpawn }) {
   }
 }
 
-/**
- * Resolve the `planning.taskSizing` operator override the same way the ticket
- * validator does, so an operator who retunes sizing retunes the depth
- * thresholds with it. Reads `config.planning.taskSizing` first, then the
- * legacy `config.agentSettings.planning.taskSizing` nest; absent → `undefined`
- * so {@link resolveDepth} falls back to `DEFAULT_TASK_SIZING`.
- *
- * @param {object|null|undefined} config
- * @returns {object|undefined}
- */
-function resolveTaskSizing(config) {
-  return (
-    config?.planning?.taskSizing ??
-    config?.agentSettings?.planning?.taskSizing ??
-    undefined
-  );
-}
-
-/**
- * Producer-side resolver (Story #3937, extended by Story #3938): read an
- * Epic's judged `planningRisk` envelope off its `epic-plan-state` checkpoint
- * and resolve the review depth via the shared {@link resolveDepth} resolver.
- * This is the live epic-scope counterpart to `resolveRiskRoutedLenses` in
- * `epic-audit-prepare.js` — it reuses the same best-effort `readPlanState`
- * pattern so the producer never aborts the review on a risk-read failure.
- *
- * Best-effort and total: a missing/unparseable checkpoint, an absent
- * `planningRisk` field, a read failure, or a malformed `overallLevel` all
- * degrade to `standard` (never throws). So an Epic that skipped `/plan`
- * (no checkpoint) still gets a passing `standard` review with no new failure
- * mode. The producer resolves depth from the judged risk alone (the diff is
- * not yet enumerated at this point); the full risk + diff-width combination is
- * applied in `runCodeReview`, which knows the changed-file count. A high-risk
- * Epic resolves to `deep` here; a low-risk one to `light` (the diff width can
- * only escalate, never downgrade, that producer-side resolution).
- *
- * @param {{
- *   epicId: number,
- *   provider: object,
- *   readPlanState?: typeof readPlanState,
- * }} params
- * @returns {Promise<ReviewDepth>}
- */
-export async function resolveReviewDepthForEpic({
-  epicId,
-  provider,
-  readPlanState: readPlanStateFn = readPlanState,
-}) {
-  let state = null;
-  try {
-    state = await readPlanStateFn({ provider, epicId });
-  } catch {
-    // A read failure (provider error, malformed comment) must not abort the
-    // review. Degrade to the neutral `standard` depth.
-    return 'standard';
-  }
-  return resolveDepth({ overallLevel: state?.planningRisk?.overallLevel });
-}
-
-/**
- * The axes whose presence (at `high` risk) routes a specific post-delivery
- * audit lens. Mirrors the audit-workflow names under
- * `.agents/workflows/audit-*.md`. Story #3939 broadened the routing so every
- * high-risk REQUIRED axis maps to a lens rather than leaving three of them
- * (`data-migration`, `destructive-mutation`, `billing`) routing nothing:
- *
- *   - `security`             → `audit-security`     (auth/secret boundary)
- *   - `public-api`           → `audit-architecture` (the canonical
- *                              architectural axis; a breaking public surface)
- *   - `data-migration`       → `audit-quality`      (migration correctness +
- *                              regression coverage)
- *   - `destructive-mutation` → `audit-security`     (irreversible mutation is
- *                              an auth/abuse boundary; co-routes with
- *                              `security`, de-duplicated)
- *   - `billing`              → `audit-privacy`      (money + the PII/consent
- *                              surface that travels with it)
- *   - `critical-workflow`    → `audit-quality`      (the load-bearing path
- *                              warrants the deepest coverage pass)
- *
- * The `visible-behavior` axis intentionally routes NO lens: it forces the
- * acceptance-spec disposition at plan time and no audit lens maps cleanly to
- * it. Any other axis (or a low/medium-risk axis) contributes no lens.
- *
- * Every key here MUST be a value in the `axis` enum of
- * `.agents/schemas/risk-verdict.schema.json` — the verdict-derived envelope
- * can only ever carry schema-valid axes, so a key absent from that enum is
- * unreachable dead routing (Story #3889 removed the unreachable
- * `architecture` key; the architectural axis is `public-api`).
- */
-const AXIS_TO_LENS = Object.freeze({
-  security: 'audit-security',
-  'public-api': 'audit-architecture',
-  'data-migration': 'audit-quality',
-  'destructive-mutation': 'audit-security',
-  billing: 'audit-privacy',
-  'critical-workflow': 'audit-quality',
-});
-
-/**
- * Stable output order for routed lenses so the lens list is deterministic
- * regardless of axis ordering in the verdict. Every lens any axis can route
- * appears here exactly once; `resolveAuditLenses` filters this canonical
- * order down to the matched set (Story #3939).
- */
-const LENS_ORDER = Object.freeze([
-  'audit-security',
-  'audit-architecture',
-  'audit-quality',
-  'audit-privacy',
-]);
-
-/**
- * Resolve the set of post-delivery audit lenses a judged risk envelope routes.
- *
- * High-risk axes map to their audit lens via {@link AXIS_TO_LENS}; only axes
- * judged `high` contribute (a `low`/`medium` axis carries no lens). The result
- * is de-duplicated and stably ordered by {@link LENS_ORDER} so an envelope
- * listing the `public-api` axis more than once routes `['audit-architecture']`
- * once, not twice — and two distinct axes routing the same lens (e.g.
- * `security` + `destructive-mutation` both → `audit-security`) collapse to a
- * single entry. A low-risk envelope — or any envelope with no high-risk routed
- * axis — resolves to an empty array (no lens beyond the existing baseline
- * gates).
- *
- * Pure function — no I/O, no side effects.
- *
- * @param {{ axes?: Array<{ axis?: string, level?: string }> }} [envelope]
- * @returns {string[]} Ordered, de-duplicated audit-lens identifiers.
- */
-export function resolveAuditLenses(envelope = {}) {
-  const axes = Array.isArray(envelope?.axes) ? envelope.axes : [];
-  const matched = new Set();
-  for (const entry of axes) {
-    if (!entry || entry.level !== 'high') continue;
-    const lens = AXIS_TO_LENS[entry.axis];
-    if (lens) matched.add(lens);
-  }
-  return LENS_ORDER.filter((lens) => matched.has(lens));
-}
-
-/**
- * Compose the Epic-close (gate3) lens roster from the change-set selection
- * plus every risk-routed lens.
- *
- * STOPGAP (post-#4405 review finding): Story #4412 excluded every
- * `local`-tier change-set lens here on the premise that the Story-scope
- * local-lens pass (Story #4409) verifies those concerns shift-left. That
- * premise does not hold yet — `runLocalLensReview`
- * (story-close/phases/code-review.js) materializes lens bodies with no
- * `artifactPrefix` (so no content persists) and no consumer acts on its
- * result, which left change-set lenses (security, privacy, performance,
- * quality, …) executed by NO reviewer at ANY tier. Local-tier lenses are
- * therefore KEPT at Epic close until the story-scope pass has a real
- * consumer; re-enable the exclusion then (tracked as a follow-up issue).
- * The write-time maker checklists (#4410) are advisory self-checks, not
- * verification. The `resolveLensTierFn` seam is retained so the
- * re-exclusion is a one-line revert.
- *
- * The two inputs mirror the `epic-audit-prepare.js` envelope:
- *   - `changeSetAudits` — the raw change-set gate3 selection, kept in full
- *     (see the stopgap note above).
- *   - `riskRoutedAudits` — the verdict-routed high-risk lenses plus the
- *     route-glob navigability lens. Kept in **full**, regardless of tier: a
- *     high-risk axis (or a route-adding change set) that demands a local-tier
- *     lens still runs it at Epic close, because that demand is the whole point
- *     of risk routing.
- *
- * De-duplicated and order-preserving (kept change-set lenses first, then the
- * risk-routed extras). Pure over the injected `resolveLensTierFn` seam; the
- * default resolver reads `audit-rules.json` from disk.
- *
- * @param {{
- *   changeSetAudits?: string[],
- *   riskRoutedAudits?: string[],
- *   resolveLensTierFn?: typeof resolveLensTier,
- * }} [params]
- * @returns {string[]} The Epic-close roster (all change-set tiers +
- *   risk-routed; local-tier exclusion suspended per the stopgap above).
- */
-export function selectEpicCloseLenses({
-  changeSetAudits = [],
-  riskRoutedAudits = [],
-  resolveLensTierFn = resolveLensTier,
-} = {}) {
-  const kept = [];
-  const seen = new Set();
-  const add = (lens) => {
-    if (typeof lens !== 'string' || lens.length === 0 || seen.has(lens)) return;
-    seen.add(lens);
-    kept.push(lens);
-  };
-  for (const lens of Array.isArray(changeSetAudits) ? changeSetAudits : []) {
-    if (typeof lens !== 'string' || lens.length === 0) continue;
-    // Stopgap: keep local-tier lenses (see docstring). The tier seam is
-    // deliberately untouched so restoring `=== 'local' → continue` is a
-    // one-line revert once the story-scope tier has a real consumer.
-    void resolveLensTierFn;
-    add(lens);
-  }
-  for (const lens of Array.isArray(riskRoutedAudits) ? riskRoutedAudits : []) {
-    add(lens);
-  }
-  return kept;
-}
-
-/**
- * Build the post-delivery audit-lens execution plan for a judged risk
- * envelope. Each routed lens (see {@link resolveAuditLenses}) is paired with a
- * strategy decision from the **existing** `selectAuditStrategy` engine — no new
- * audit machinery is introduced. A low-risk envelope resolves to an empty
- * `lenses` array and runs no audit beyond the baseline gates (Story #3876).
- *
- * Pure with respect to the injected `selectAuditStrategyFn` (default is the
- * shared dynamic-workflow engine, which is itself pure over its snapshot).
- *
- * @param {{ axes?: Array<{ axis?: string, level?: string }> }} [envelope]
- * @param {{
- *   snapshot?: object,
- *   forceStrategy?: ('orchestrated'|'sequential'|null),
- *   selectAuditStrategyFn?: typeof selectAuditStrategy,
- * }} [opts]
- * @returns {{ lenses: string[], plan: Array<{ lens: string, strategy: string, reason: string, forced: boolean }> }}
- */
-export function planAuditLenses(envelope = {}, opts = {}) {
-  const {
-    snapshot = {},
-    forceStrategy = null,
-    selectAuditStrategyFn = selectAuditStrategy,
-  } = opts;
-  const lenses = resolveAuditLenses(envelope);
-  const plan = lenses.map((lens) => {
-    const decision = selectAuditStrategyFn({ snapshot, forceStrategy });
-    return {
-      lens,
-      strategy: decision.strategy,
-      reason: decision.reason,
-      forced: decision.forced,
-    };
-  });
-  return { lenses, plan };
-}
-
 /**
  * Build the `code-review.end` payload from the normalized result envelope.
  * The runner result may carry a `report` field (full markdown body) which
@@ -376,9 +132,7 @@ function buildCodeReviewEndPayload({ epicId, result, durationMs }) {
  * `baseRef`.
  */
 function resolveConfigBase(config) {
-  return (
-    config?.project?.baseBranch ?? config?.agentSettings?.baseBranch ?? 'main'
-  );
+  return config?.project?.baseBranch ?? 'main';
 }
 
 /** Positive-integer override, else the supplied default. */
@@ -535,25 +289,22 @@ function resolveScopeEnvelope(opts, config) {
  */
 /**
  * Resolve the human-facing provider name from the resolved code-review
- * config. Chain configs render as `chain[a,b,...]`; a single-provider
- * config renders its `provider` string; everything else falls back to
- * `'native'`. Story #4075 — extracted from `runCodeReview`.
+ * config. Multi-entry chains render as `chain[a,b,...]`; a single-entry
+ * chain (including the unset/empty default) renders that entry's name;
+ * everything else falls back to `'native'`.
  */
 function resolveProviderName(codeReviewConfig) {
-  const isChainConfig =
-    codeReviewConfig &&
-    Array.isArray(codeReviewConfig.providers) &&
-    codeReviewConfig.providers.length > 0;
-  if (isChainConfig) {
-    return `chain[${codeReviewConfig.providers
-      .map((p) => p?.name ?? '?')
-      .join(',')}]`;
+  const providers =
+    codeReviewConfig && Array.isArray(codeReviewConfig.providers)
+      ? codeReviewConfig.providers
+      : [];
+  if (providers.length === 1) {
+    return providers[0]?.name ?? 'native';
   }
-  return (
-    (codeReviewConfig && typeof codeReviewConfig.provider === 'string'
-      ? codeReviewConfig.provider
-      : null) ?? 'native'
-  );
+  if (providers.length > 1) {
+    return `chain[${providers.map((p) => p?.name ?? '?').join(',')}]`;
+  }
+  return 'native';
 }
 
 /**
@@ -564,15 +315,17 @@ function resolveProviderName(codeReviewConfig) {
  * envelope or the posted comment. Absent risk envelope + unknown width →
  * `standard`. Story #4075 — extracted from `runCodeReview`.
  */
-function buildReviewInput({ opts, config, scope, ticketId, baseRef, headRef }) {
+function buildReviewInput({ opts, scope, ticketId, baseRef, headRef }) {
   const changedFileCount =
     typeof opts.changedFileCount === 'number'
       ? opts.changedFileCount
       : countChangedFiles({ baseRef, headRef, gitSpawnFn: opts.gitSpawnFn });
+  // v2 Stage 2: review depth uses DEFAULT_DIFF_WIDTH (mechanical file count
+  // of the diff under review). It is deliberately decoupled from the
+  // planning model-capacity advisory (`DEFAULT_MODEL_CAPACITY`).
   const depth = resolveDepth({
     overallLevel: opts.planningRisk?.overallLevel,
     changedFileCount,
-    sizing: resolveTaskSizing(config),
   });
   return {
     scope,
@@ -670,7 +423,6 @@ async function executeReviewPipeline({ opts, config, envelope }) {
 
   const reviewInput = buildReviewInput({
     opts,
-    config,
     scope,
     ticketId,
     baseRef,

package/.agents/scripts/lib/orchestration/column-sync.js

@@ -28,7 +28,7 @@
  * Located at `lib/orchestration/column-sync.js` (Story #2548) so the
  * canonical state mutator `transitionTicketState`
  * (`lib/orchestration/ticketing/state.js`) can invoke it without an
- * upward dependency into `epic-runner/`. Prior to #2548 this module
+ * upward dependency into the deleted `epic-runner/` tree. Prior to #2548 this module
  * lived under `epic-runner/` and was only wired against the Epic
  * ticket — Stories and Tasks never updated their Projects v2 Status
  * column on label flips.

package/.agents/scripts/lib/orchestration/consolidation-precondition.js

@@ -30,7 +30,7 @@
  * Epic body off disk / the GitHub API.
  */
 
-import { DELIVERY_SLICING_RE as DELIVERY_SLICING_HEADING_RE } from '../epic-body-sections.js';
+import { DELIVERY_SLICING_RE as DELIVERY_SLICING_HEADING_RE } from '../ticket-body-sections.js';
 
 /** A row is a markdown table line: starts with `|` once trimmed. */
 const TABLE_ROW_RE = /^\|/;

package/.agents/scripts/lib/orchestration/context-envelope.js

@@ -8,7 +8,7 @@
  * @module lib/orchestration/context-envelope
  */
 
-/** @typedef {'protocolPolicy' | 'persona' | 'skillCapsules' | 'hierarchy' | 'acceptanceCriteria' | 'verificationCommands' | 'taskInstructions'} SectionName */
+/** @typedef {'protocolPolicy' | 'skillCapsules' | 'hierarchy' | 'acceptanceCriteria' | 'verificationCommands' | 'taskInstructions'} SectionName */
 
 /**
  * @typedef {object} SectionSource
@@ -37,7 +37,7 @@
 /**
  * @typedef {object} ContextEnvelope
  * @property {'1'} schemaVersion
- * @property {{ id: number, title: string, persona?: string, skills?: string[], protocolVersion?: string }} task
+ * @property {{ id: number, title: string, skills?: string[], protocolVersion?: string }} task
  * @property {Section[]} sections
  * @property {TicketSnapshot[]} provenance
  * @property {{ maxTokens: number, used: number, elided: string[] }} budget
@@ -51,7 +51,6 @@ export const PROMPT_SECTION_SEPARATOR =
 /** Rendering order for {@link envelopeToPrompt} (not elision priority). */
 export const SECTION_RENDER_ORDER = Object.freeze([
   'protocolPolicy',
-  'persona',
   'skillCapsules',
   'hierarchy',
   'acceptanceCriteria',
@@ -65,7 +64,6 @@ export const DEFAULT_SECTION_PRIORITIES = Object.freeze({
   hierarchy: 20,
   acceptanceCriteria: 30,
   verificationCommands: 40,
-  persona: 50,
   protocolPolicy: 80,
   taskInstructions: 100,
 });
@@ -76,7 +74,6 @@ export const DEFAULT_ELIDE_POLICIES = Object.freeze({
   hierarchy: 'summarize',
   acceptanceCriteria: 'summarize',
   verificationCommands: 'drop',
-  persona: 'summarize',
   protocolPolicy: 'drop',
   taskInstructions: 'drop',
 });

package/.agents/scripts/lib/orchestration/docs-digest.js

@@ -1,5 +1,5 @@
 /**
- * docs-digest.js — per-Epic docs digest builder (Story #4338).
+ * docs-digest.js — per-run docs digest builder (Story #4338).
  *
  * `/deliver` story sub-agents previously re-read every file in
  * `project.docsContextFiles` on every Story, re-paying the full docs payload
@@ -16,8 +16,8 @@
  * Story #4433 extends this module with {@link ensureDocsDigest}, a shared
  * generate-and-write export so the planner-context surface
  * (`plan-context.js` / `authoring-context.js`) can produce a session docs
- * digest without duplicating the mkdir+writeFile plumbing
- * `epic-deliver-prepare.js` already owns for the delivery-children digest.
+ * digest without duplicating the mkdir+writeFile plumbing shared by
+ * `plan-context.js` / `authoring-context.js` and the `/deliver` workflow.
  */
 
 import fs from 'node:fs';
@@ -110,7 +110,7 @@ function renderDocSection(doc) {
 }
 
 /**
- * Build the per-Epic docs digest markdown from the configured docs context
+ * Build the per-run docs digest markdown from the configured docs context
  * files. Missing files are skipped silently (the read seam returns only the
  * files it could stat + read). Returns `null` when there is nothing to digest
  * — i.e. `docsContextFiles` is empty/unset — so callers surface a null
@@ -130,7 +130,7 @@ export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
   const header = [
     '# Docs digest',
     '',
-    'Per-Epic outline of the project docs context set. Each entry lists the',
+    'Per-run outline of the project docs context set. Each entry lists the',
     'file path, byte size, and its heading outline (with line numbers) plus',
     'the first paragraph under each `##` section. Read the full file on demand',
     'when a section looks relevant — do **not** ingest the whole set per Story.',
@@ -144,10 +144,10 @@ export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
 /**
  * Build the docs digest and write it to `outputPath`, returning `null` (no
  * write) when there is nothing to digest. This is the single shared
- * generate-and-persist export both digest producers call: the per-Epic
- * delivery-children digest (`epic-deliver-prepare.js`) and the planner-
+ * generate-and-persist export both digest producers call: the per-run
+ * `/deliver` docs digest (`helpers/deliver-story.md`) and the planner-
  * context digest (`plan-context.js` → `authoring-context.js`, Story
- * #4433). Callers own path construction (temp-root layout, epic id, etc.)
+ * #4433). Callers own path construction (temp-root layout, run id, etc.)
  * so both surfaces can keep — or deliberately share — their own convention;
  * this function only owns "build digest, ensure parent dir, write file".
  *

package/.agents/scripts/lib/orchestration/file-assumptions.js

@@ -45,11 +45,10 @@
  * the shared-editor conflict gate's domain — that finding's rendering is
  * cross-referenced (see `renderMismatch`), not duplicated here.
  *
- * Legacy compatibility: stories whose `body.changes` items are still bare
- * strings carry no assumption and are skipped silently here. The
- * deprecation signal is emitted *once* per validator invocation through
- * `collectDeprecationWarnings`, so consumers running an older planner
- * see a clear migration nudge without a hard failure mid-flight.
+ * String bullets: stories whose `body.changes` items are still bare
+ * strings are hard errors — they are pushed to `errors[]` by the
+ * validator's body-shape gate before this module runs. There is no
+ * silent skip or deprecation nudge.
  */
 
 import { gitSpawn } from '../git-utils.js';
@@ -319,21 +318,16 @@ export function validateStoryFileAssumptions(opts) {
     const entries = collectStoryAssumptionEntries(story);
 
     if (entries.length === 0) {
-      // Legacy path: this Story carries no object-form entries. Emit a
-      // single deprecation warning so the operator sees the migration
-      // nudge once per Story rather than per-bullet.
       if (hasLegacyChangeBullets(story)) {
-        warnings.push(
-          `"${slug}" → body.changes uses legacy string bullets without { path, assumption }. Migrate to object form so Phase 8 can verify file-state assumptions. See Story #2636.`,
+        errors.push(
+          `"${slug}" → body.changes uses legacy string bullets without { path, assumption }. Migrate every bullet to object form so Phase 8 can verify file-state assumptions. See Story #2636.`,
         );
       }
       continue;
     }
 
-    // Partial-migration warning: some entries are object-form, some are
-    // still strings. Surface once so the operator notices the gap.
     if (hasLegacyChangeBullets(story)) {
-      warnings.push(
+      errors.push(
         `"${slug}" → body.changes mixes object-form entries with legacy string bullets. Migrate every bullet for full freshness coverage.`,
       );
     }

package/.agents/scripts/lib/orchestration/git-cleanup/phases/cli.js

@@ -26,7 +26,7 @@ function resolveBaseBranch(cwd, override) {
   if (override) return override;
   try {
     const cfg = resolveConfig({ cwd });
-    return cfg?.project?.baseBranch || cfg?.agentSettings?.baseBranch || 'main';
+    return cfg?.project?.baseBranch || 'main';
   } catch {
     return 'main';
   }

package/.agents/scripts/lib/orchestration/lifecycle/emit-loop-tick.js

@@ -40,7 +40,7 @@
  * `ledgerPath` (the host-loop case — the loop owns where its ledger
  * lives) OR an `epicId`, in which case the canonical
  * `epicLedgerPath(epicId)` is used so an Epic-scoped loop's ticks land
- * in the same `temp/epic-<id>/lifecycle.ndjson` the rest of the run
+ * in the same `temp/run-<id>/lifecycle.ndjson` the rest of the run
  * reads. Exactly one of the two MUST be supplied.
  */
 
@@ -65,8 +65,8 @@ const SCHEMA_DIR = path.resolve(
 const VALID_STATUSES = new Set(['running', 'done', 'blocked']);
 
 /**
- * Parse `temp/epic-<id>/lifecycle.ndjson` (or any
- * `<dir>/epic-<id>/lifecycle.ndjson`) back into `{ tempRoot, epicId }`
+ * Parse `temp/run-<id>/lifecycle.ndjson` (or any
+ * `<dir>/run-<id>/lifecycle.ndjson`) back into `{ tempRoot, epicId }`
  * so a LedgerWriter — which is constructed from `{ epicId, tempRoot }`
  * rather than a raw path — can be bound to the supplied ledger path.
  *
@@ -79,13 +79,13 @@ const VALID_STATUSES = new Set(['running', 'done', 'blocked']);
  * @returns {{ tempRoot: string, epicId: number }}
  */
 function decomposeLedgerPath(ledgerPath) {
-  const epicDir = path.dirname(ledgerPath);
-  const tempRoot = path.dirname(epicDir);
-  const epicDirName = path.basename(epicDir);
-  const m = /^epic-(\d+)$/.exec(epicDirName);
+  const runDir = path.dirname(ledgerPath);
+  const tempRoot = path.dirname(runDir);
+  const runDirName = path.basename(runDir);
+  const m = /^run-(\d+)$/.exec(runDirName);
   if (!m) {
     throw new Error(
-      `emitLoopTick: ledgerPath does not match <tempRoot>/epic-<id>/lifecycle.ndjson layout (got ${ledgerPath})`,
+      `emitLoopTick: ledgerPath does not match <tempRoot>/run-<id>/lifecycle.ndjson layout (got ${ledgerPath})`,
     );
   }
   const epicId = Number.parseInt(m[1], 10);

package/.agents/scripts/lib/orchestration/lifecycle/emit-story-heartbeat.js

@@ -2,8 +2,8 @@
  * emit-story-heartbeat.js — Story #3057.
  *
  * Programmatic helper that appends a single `story.heartbeat` NDJSON
- * record to `temp/epic-<id>/lifecycle.ndjson` during a Story's
- * implementation loop. Story-implementation phases can run for many
+ * record to the Story lifecycle ledger (`temp/.../lifecycle.ndjson` via
+ * `lib/config/temp-paths.js`) during a Story's implementation loop. Story-implementation phases can run for many
  * minutes between dispatch and merge; `story.heartbeat` is the
  * inspectable in-progress signal the host-loop reconciler reads to
  * confirm forward progress.

package/.agents/scripts/lib/orchestration/lifecycle/ledger-writer.js

@@ -25,6 +25,7 @@
 
 import { appendFileSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { runTempDir } from '../../config/temp-paths.js';
 
 /**
  * Static deny-list pulled from the Tech Spec § Security & Privacy. Keys
@@ -85,7 +86,7 @@ export class LedgerWriter {
    * @param {object} opts
    * @param {number} opts.epicId
    * @param {string} opts.tempRoot - absolute or repo-relative path; the
-   *   writer resolves `temp/epic-<id>/lifecycle.ndjson` underneath.
+   *   writer resolves `temp/run-<id>/lifecycle.ndjson` underneath.
    * @param {() => number} [opts.now] - injectable clock for tests.
    */
   constructor(opts) {
@@ -101,7 +102,9 @@ export class LedgerWriter {
     }
     this._epicId = opts.epicId;
     this._tempRoot = opts.tempRoot;
-    this._epicDir = path.join(this._tempRoot, `epic-${this._epicId}`);
+    this._epicDir = runTempDir(this._epicId, {
+      project: { paths: { tempRoot: this._tempRoot } },
+    });
     this._ledgerPath = path.join(this._epicDir, 'lifecycle.ndjson');
     this._now = typeof opts.now === 'function' ? opts.now : Date.now;
   }
@@ -127,7 +130,7 @@ export class LedgerWriter {
    * The naive optimization (cache "ensured" after the first call) is
    * unsound when a listener moves the ledger directory mid-handler —
    * which is exactly what the Cleaner does on Wave 8 (Story #2259):
-   * it renames `temp/epic-<id>/` under `archive/` between the listener
+   * it renames `temp/run-<id>/` under `archive/` between the listener
    * body and the bus's `onCompleted` hook fire-time, and the next
    * append (the `completed` record for the outer event) would land
    * in a vanished directory. `mkdirSync({recursive: true})` is