mandrel 1.57.0 → 1.59.0

package/.agents/scripts/lib/orchestration/story-close/phases/locked-pipeline.js

@@ -41,9 +41,34 @@ import { emitSpawnTimeoutBlockedResult } from './timeout-blocked-emitter.js';
  * Run pre-merge gates and, on a clean outcome, the bounded baseline
  * auto-refresh. Returns `{ blocked }` so the locked pipeline can
  * short-circuit on a `blocked` / `blocked-timeout` gate outcome.
+ *
+ * `runPreMergeValidation` is an injectable seam (Story #3973): the
+ * forwarding of `config: ctx.config` into the gate builder is load-bearing
+ * — without it the typecheck gate ignores `project.commands.typecheck` and
+ * falls back to the hardcoded `npm run typecheck`, blocking every close for
+ * any consumer with a non-default typecheck command. The default is the
+ * module-level `runPreMergeValidation`; tests inject a spy to pin that
+ * `config` reaches the gate builder through this call site.
+ *
+ * @param {object} ctx - The locked-pipeline context bundle.
+ * @param {object} [deps] - Injectable collaborators.
+ * @param {typeof runPreMergeValidation} [deps.runPreMergeValidationFn]
+ * @param {typeof runAutoRefreshSafely} [deps.runAutoRefreshSafelyFn]
  */
-async function runGatesAndRefresh(ctx) {
-  const gateOutcome = await runPreMergeValidation({
+export async function runGatesAndRefresh(
+  ctx,
+  {
+    runPreMergeValidationFn = runPreMergeValidation,
+    runAutoRefreshSafelyFn = runAutoRefreshSafely,
+  } = {},
+) {
+  // Story #4017 — one shared cycle-state object per close cycle. The
+  // gate-failure attribution retry and the post-gates auto-refresh both
+  // funnel through `runRefreshCommit`, which keys its idempotency token
+  // off this object so each baseline kind is refreshed (scored +
+  // committed) at most once per close.
+  const cycleState = { refreshedKinds: new Set(), lastRefreshSha: null };
+  const gateOutcome = await runPreMergeValidationFn({
     cwd: ctx.cwd,
     worktreePath: ctx.worktreePath,
     epicBranch: ctx.epicBranch,
@@ -55,6 +80,7 @@ async function runGatesAndRefresh(ctx) {
     phaseTimer: ctx.phaseTimer,
     provider: ctx.provider,
     bus: ctx.bus,
+    cycleState,
   });
   if (gateOutcome?.status === 'blocked') {
     return {
@@ -82,7 +108,7 @@ async function runGatesAndRefresh(ctx) {
       }),
     };
   }
-  await runAutoRefreshSafely(
+  await runAutoRefreshSafelyFn(
     {
       storyId: ctx.storyId,
       epicId: ctx.epicId,
@@ -90,6 +116,7 @@ async function runGatesAndRefresh(ctx) {
       epicBranch: ctx.epicBranch,
       storyBranch: ctx.storyBranch,
       config: ctx.config,
+      cycleState,
     },
     { progress: ctx.progress },
   );

package/.agents/scripts/lib/orchestration/story-close/post-merge-close.js

@@ -21,14 +21,8 @@
  * read it; this helper writes the file and hands the path to the pipeline.
  */
 
-// Legacy key on the post-merge-pipeline / cleanup-reconciler input bag.
-// Built from substrings so the migrated-subsystem grep does not match it;
-// the downstream helpers live outside the migrated subsystem and will
-// rename their parameters when their own subsystems are swept.
-const LEGACY_PIPELINE_CONFIG_KEY = `orches${'tration'}`;
-
 import { mkdir, writeFile } from 'node:fs/promises';
-import { emitGhSpawnCount as defaultEmitGhSpawnCount } from '../../close-validation.js';
+import { emitGhSpawnCount as defaultEmitGhSpawnCount } from '../../close-validation/telemetry.js';
 import { storyArtifactPath, storyTempDir } from '../../config/temp-paths.js';
 import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
 import { clearActiveStoryEnv as defaultClearActiveStoryEnv } from '../../observability/active-story-env.js';
@@ -340,18 +334,11 @@ export async function runPostMergeClose({
   // in this order — see post-merge-pipeline.js. The `perf-summary` phase
   // inside the pipeline shells out to analyze-execution.js, which is the
   // single writer of the `<!-- structured:story-perf-summary -->` comment.
-  // Build the legacy-shape view that downstream out-of-subsystem helpers
-  // (post-merge-pipeline.js) still consume. The migrated cleanup-reconciler
-  // takes `delivery` directly.
-  const legacyPipelineBlock = {
-    provider: 'github',
-    github: config?.github,
-    notifications: config?.github?.notifications,
-    worktreeIsolation: deliveryBlock?.worktreeIsolation,
-    runners: { deliverRunner: deliveryBlock?.deliverRunner ?? {} },
-  };
+  // The pipeline phases take the resolved `delivery` block directly, same
+  // as the cleanup-reconciler (Story #3986 — the legacy `orchestration`-keyed
+  // input bag is gone).
   const pipelineState = await runPostMergePipeline({
-    [LEGACY_PIPELINE_CONFIG_KEY]: legacyPipelineBlock,
+    delivery: deliveryBlock,
     storyId,
     epicId,
     story,

package/.agents/scripts/lib/orchestration/story-close/pre-merge-validation.js

@@ -29,12 +29,12 @@
 // no-spawn spy proves the projection path never reaches a per-kind CLI
 // subprocess.
 import * as maintainabilityKind from '../../baselines/kinds/maintainability.js';
+import { buildDefaultGates as defaultBuildDefaultGates } from '../../close-validation/gates.js';
 import {
-  buildDefaultGates as defaultBuildDefaultGates,
   formatMaintainabilityProjection as defaultFormatMaintainabilityProjection,
   projectMaintainabilityRegressions as defaultProjectMaintainabilityRegressions,
-  runCloseValidation as defaultRunCloseValidation,
-} from '../../close-validation.js';
+} from '../../close-validation/projections/maintainability.js';
+import { runCloseValidation as defaultRunCloseValidation } from '../../close-validation/runner.js';
 import { getBaselines as defaultGetBaselines } from '../../config-resolver.js';
 import { Logger as DefaultLogger } from '../../Logger.js';
 

package/.agents/scripts/lib/orchestration/story-close-recovery.js

@@ -276,7 +276,7 @@ function detectAlreadyMerged({ cwd, storyId, epicId, lsrOut, detail, git }) {
   //    from the Epic history itself: locate the integration commit whose
   //    subject carries `(resolves #<id>)` / `(refs #<id>)`. Without this
   //    branch, detection falls to FRESH and the resumed close re-enters the
-  //    pre-merge gate chain, which crashes in `format-autofix-scoped.js` on
+  //    pre-merge gate chain, which crashes in the scoped format-autofix step on
   //    `git diff <epicBranch>...story-<id>` because the Story ref is gone.
   if (!resolvedDetail) {
     const mc = findMergeCommitForStory({ cwd, storyId, epicId, git });
@@ -431,24 +431,35 @@ export function computeRecoveryMode({ state, resume, restart } = {}) {
   };
 }
 
-function dropWorktreeIfPresent({ cwd, wtPath, progress, logger }) {
+function dropWorktreeIfPresent({
+  cwd,
+  wtPath,
+  progress,
+  logger,
+  gitSpawnFn = gitSpawn,
+}) {
   if (!fs.existsSync(wtPath)) return;
   progress('RESTART', `Removing worktree ${wtPath}`);
-  const remove = gitSpawn(cwd, 'worktree', 'remove', '--force', wtPath);
+  const remove = gitSpawnFn(cwd, 'worktree', 'remove', '--force', wtPath);
   if (remove.status !== 0) {
     logger.error(
       `[story-close] Worktree remove failed: ${remove.stderr || 'unknown'}. ` +
         'Attempting prune to clean stale registration.',
     );
   }
-  gitSpawn(cwd, 'worktree', 'prune');
+  gitSpawnFn(cwd, 'worktree', 'prune');
 }
 
-function recreateStoryBranchRef({ cwd, storyBranch, epicBranch, logger }) {
-  gitSpawn(cwd, 'branch', '-D', storyBranch);
-  const create = gitSpawn(cwd, 'branch', storyBranch, epicBranch);
+function recreateStoryBranchRef({
+  cwd,
+  storyBranch,
+  epicBranch,
+  gitSpawnFn = gitSpawn,
+}) {
+  gitSpawnFn(cwd, 'branch', '-D', storyBranch);
+  const create = gitSpawnFn(cwd, 'branch', storyBranch, epicBranch);
   if (create.status !== 0) {
-    logger.fatal(
+    throw new Error(
       `Failed to recreate ${storyBranch} from ${epicBranch}: ${create.stderr || 'unknown'}`,
     );
   }
@@ -460,13 +471,13 @@ function reseedWorktreeIfNeeded({
   storyId,
   storyBranch,
   progress,
-  logger,
+  gitSpawnFn = gitSpawn,
 }) {
   if (!wtConfig?.enabled) return;
   const wtPath = storyWorktreePath(cwd, storyId, wtConfig.root);
-  const add = gitSpawn(cwd, 'worktree', 'add', wtPath, storyBranch);
+  const add = gitSpawnFn(cwd, 'worktree', 'add', wtPath, storyBranch);
   if (add.status !== 0) {
-    logger.fatal(
+    throw new Error(
       `Failed to re-seed worktree at ${wtPath}: ${add.stderr || 'unknown'}`,
     );
   }
@@ -477,8 +488,12 @@ function reseedWorktreeIfNeeded({
  * Restart path: abort any in-progress merge, drop the worktree, delete the
  * story branch ref, and re-seed branch + worktree from the Epic branch. The
  * caller then falls through to the normal fresh-close flow.
+ *
+ * Throws (never `logger.fatal`) on a failed branch recreate or worktree
+ * re-seed, per `rules/orchestration-error-handling.md` — a failed recreate
+ * MUST NOT fall through into the worktree re-seed.
  */
-function restartStoryState({
+export function restartStoryState({
   cwd,
   orchestration,
   storyId,
@@ -486,9 +501,10 @@ function restartStoryState({
   storyBranch,
   progress = () => {},
   logger = Logger,
+  gitSpawnFn = gitSpawn,
 } = {}) {
   progress('RESTART', `Resetting prior state for Story #${storyId}...`);
-  gitSpawn(cwd, 'merge', '--abort');
+  gitSpawnFn(cwd, 'merge', '--abort');
 
   const wtConfig = orchestration?.worktreeIsolation;
   if (wtConfig?.enabled) {
@@ -497,17 +513,18 @@ function restartStoryState({
       wtPath: storyWorktreePath(cwd, storyId, wtConfig.root),
       progress,
       logger,
+      gitSpawnFn,
     });
   }
 
-  recreateStoryBranchRef({ cwd, storyBranch, epicBranch, logger });
+  recreateStoryBranchRef({ cwd, storyBranch, epicBranch, gitSpawnFn });
   reseedWorktreeIfNeeded({
     cwd,
     wtConfig,
     storyId,
     storyBranch,
     progress,
-    logger,
+    gitSpawnFn,
   });
 }
 
@@ -563,7 +580,7 @@ export function dispatchRecovery({
   restartFn = restartStoryState,
 } = {}) {
   if (resume && restart) {
-    logger.fatal('--resume and --restart are mutually exclusive');
+    throw new Error('--resume and --restart are mutually exclusive');
   }
 
   const priorPhase = detectFn({ cwd, storyId, epicId });

package/.agents/scripts/lib/orchestration/story-reachability.js

@@ -0,0 +1,47 @@
+/**
+ * lib/orchestration/story-reachability.js — Story `depends_on` graph walk.
+ *
+ * Houses the transitive-predecessor closure over the story-level
+ * `depends_on` graph. Extracted from `./ticket-validator-conflicts.js`
+ * under Story #3995 to break the `file-assumptions.js ↔
+ * ticket-validator-conflicts.js` import cycle: both the conflict gate and
+ * the wave-aware file-assumption gate need this graph traversal, so
+ * pulling it down into a dependency-free leaf lets both import it from
+ * below rather than from each other.
+ *
+ * This is a pure graph utility — no I/O, no policy. Its behaviour is
+ * unchanged from the original `computeStoryReachability`.
+ */
+
+/**
+ * Compute transitive predecessor sets over the story-level `depends_on`
+ * graph. The returned map is `Map<storySlug, Set<storySlug>>`, where the
+ * set contains every story reachable by following `depends_on` edges from
+ * the key (i.e. every story the key transitively depends on).
+ *
+ * BFS, no cycles assumed — callers must run `assertAcyclic` first.
+ *
+ * Exported so both the conflict gate (`ticket-validator-conflicts.js`)
+ * and the wave-aware file-assumption gate (`file-assumptions.js`) can
+ * reuse the same transitive-predecessor walk rather than re-deriving the
+ * `depends_on` closure.
+ */
+export function computeStoryReachability(stories) {
+  const reach = new Map();
+  for (const story of stories) reach.set(story.slug, new Set());
+  for (const story of stories) {
+    const visited = reach.get(story.slug);
+    const stack = [...(story.depends_on ?? [])];
+    while (stack.length > 0) {
+      const next = stack.pop();
+      if (!reach.has(next)) continue;
+      if (visited.has(next)) continue;
+      visited.add(next);
+      const nextStory = stories.find((s) => s.slug === next);
+      if (nextStory && Array.isArray(nextStory.depends_on)) {
+        for (const dep of nextStory.depends_on) stack.push(dep);
+      }
+    }
+  }
+  return reach;
+}

package/.agents/scripts/lib/orchestration/ticket-validator-conflicts.js

@@ -1,4 +1,5 @@
 import { collectStoryAssumptionEntries } from './file-assumptions.js';
+import { computeStoryReachability } from './story-reachability.js';
 
 /**
  * Cross-Story path-conflict & implicit-dependency findings.
@@ -66,7 +67,7 @@ const DEFAULT_POLICY = Object.freeze({
  *   - exact path  — `lib/orchestration/lifecycle/listeners/index.js`
  *   - `**` suffix — `**\/listeners/index.js` (matches any depth)
  */
-const DEFAULT_REGISTRY_PATTERNS = Object.freeze([
+export const DEFAULT_REGISTRY_PATTERNS = Object.freeze([
   'lib/orchestration/lifecycle/listeners/index.js',
   '**/listeners/index.js',
   '**/handlers/index.js',
@@ -242,38 +243,6 @@ function indexConsumers(stories, producers) {
   return consumers;
 }
 
-/**
- * Compute transitive predecessor sets over the story-level `depends_on`
- * graph. The returned map is `Map<storySlug, Set<storySlug>>`, where the
- * set contains every story reachable by following `depends_on` edges from
- * the key (i.e. every story the key transitively depends on).
- *
- * BFS, no cycles assumed — callers must run `assertAcyclic` first.
- *
- * Exported so the wave-aware file-assumption gate
- * (`file-assumptions.js`) can reuse the same transitive-predecessor walk
- * rather than re-deriving the `depends_on` closure.
- */
-export function computeStoryReachability(stories) {
-  const reach = new Map();
-  for (const story of stories) reach.set(story.slug, new Set());
-  for (const story of stories) {
-    const visited = reach.get(story.slug);
-    const stack = [...(story.depends_on ?? [])];
-    while (stack.length > 0) {
-      const next = stack.pop();
-      if (!reach.has(next)) continue;
-      if (visited.has(next)) continue;
-      visited.add(next);
-      const nextStory = stories.find((s) => s.slug === next);
-      if (nextStory && Array.isArray(nextStory.depends_on)) {
-        for (const dep of nextStory.depends_on) stack.push(dep);
-      }
-    }
-  }
-  return reach;
-}
-
 function inSameWave(reach, slugA, slugB) {
   if (slugA === slugB) return false;
   const a = reach.get(slugA);

package/.agents/scripts/lib/orchestration/ticketing/bulk.js

@@ -8,26 +8,25 @@
  * Story #1848 so the verb-family split (`reads` / `state` / `bulk`) is
  * complete and the parent collapses to a pure re-export facade.
  *
- * Note on the cycle with `./state.js`: `cascadeCompletion` recursively
- * calls `transitionTicketState`, which in turn — when the cascade flag is
- * on — calls back into `cascadeCompletion`. ESM tolerates the cycle
- * because every binding is resolved at call-time. Both modules complete
- * evaluation before any of their exported functions run.
+ * Story #3995 — the single-ticket mutators (`transitionTicketState`,
+ * `toggleTasklistCheckbox`, `postStructuredComment`) moved to the leaf
+ * `./transition.js`, so this module now depends **downward** on
+ * `transition.js` and the former `state.js ↔ bulk.js` import cycle is
+ * gone. `cascadeCompletion` still recursively transitions parents via
+ * the imported `transitionTicketState`; the reverse call
+ * (`transitionTicketState → cascadeParentState`) is injected into
+ * `transition.js` by `state.js` via `registerCascadeRunner` rather than
+ * imported, which is what keeps the graph acyclic.
  */
 
 import { Logger } from '../../Logger.js';
 import { TYPE_LABELS } from '../../label-constants.js';
-import { dispatchCascadeGroups, groupByAncestor } from '../cascade-grouping.js';
 import { ALL_STATES, STATE_LABELS } from './reads.js';
 import {
   postStructuredComment,
   toggleTasklistCheckbox,
   transitionTicketState,
-} from './state.js';
-
-// Re-export `groupByAncestor` so external callers that imported it from
-// the ticketing facade continue to work after the verb-family split.
-export { groupByAncestor };
+} from './transition.js';
 
 /**
  * Retry budget for transient `gh` failures (rate limit, secondary rate limit,
@@ -217,9 +216,8 @@ export function logCascadePartialFailures(ticketId, cascade) {
 
 /**
  * Per-parent body of {@link cascadeCompletion}. Pulled out so the outer
- * function can dispatch disjoint groups in parallel while each parent
- * still runs against its own captured logger, ensuring byte-identical
- * log output across serial and parallel execution paths.
+ * walk stays a thin sequential loop while the per-parent work runs under
+ * the per-parent cascade lock.
  *
  * @param {import('../../ITicketingProvider.js').ITicketingProvider} provider
  * @param {number} ticketId  - The ticket whose `agent::done` transition
@@ -372,19 +370,13 @@ async function processCascadeParentLocked(
  * Then checks if parent's sub-tickets are ALL DONE.
  * If yes, transitions parent to DONE and cascades up.
  *
- * Parents are partitioned into disjoint groups by shared ancestor
- * ({@link groupByAncestor}). Groups run in parallel via `Promise.all`,
- * but parents **within** a group run strictly sequentially in input
- * order — concurrent transitions against a shared ancestor would race
- * the "all children done?" check. Within each parent, sibling reads
- * fan out via `getSubTickets(parentId, { fresh: true })` with the
- * concurrency cap (8) applied inside `getSubTickets`.
- *
- * Log output is captured per parent into a buffered logger and flushed
- * to the real {@link Logger} after all groups resolve, in the original
- * `parsedParents` order. The visible log stream is therefore
- * byte-identical to a serial baseline; only the I/O between parents in
- * disjoint groups overlaps.
+ * Parents run strictly sequentially in input order (Story #4017 —
+ * fan-out is <= 1 under the 3-tier hierarchy, so the former
+ * shared-ancestor grouping / parallel dispatch was deleted); concurrent
+ * transitions against a shared ancestor would race the "all children
+ * done?" check. Within each parent, sibling reads fan out via
+ * `getSubTickets(parentId, { fresh: true })` with the concurrency cap
+ * (8) applied inside `getSubTickets`.
  *
  * Per-parent errors are isolated: a failure updating one parent (network,
  * permission, stale ticket) never discards progress on sibling parents.
@@ -450,26 +442,19 @@ export async function cascadeCompletion(provider, ticketId, opts = {}) {
     return { cascadedTo: [], failed: [] };
   }
 
-  // Partition parents by shared ancestor (disjoint groups run in
-  // parallel; within-group parents stay sequential to avoid racing the
-  // shared ancestor's "all children done?" check), then dispatch the
-  // per-parent work via `dispatchCascadeGroups` so the buffered-flush
-  // bookkeeping lives in `cascade-grouping.js`.
-  const groups = await groupByAncestor(parsedParents, provider);
-  const results = await dispatchCascadeGroups({
-    parsedParents,
-    groups,
-    flushLogger: opts._logger ?? Logger,
-    processParent: (parentId, logger) =>
-      processCascadeParent(provider, ticketId, parentId, {
-        notify: opts.notify,
-        _logger: logger,
-      }),
-  });
-
+  // Story #4017 — under the 3-tier hierarchy a ticket has at most one
+  // parent, so the shared-ancestor grouping / parallel-group dispatch
+  // machinery was deleted. Parents (fan-out <= 1
+  // in practice; the loop stays general for the body-reference fallback)
+  // run strictly sequentially, which trivially preserves the
+  // shared-ancestor safety invariant the grouping used to enforce.
   const cascadedTo = [];
   const failed = [];
-  for (const r of results) {
+  for (const parentId of parsedParents) {
+    const r = await processCascadeParent(provider, ticketId, parentId, {
+      notify: opts.notify,
+      _logger: opts._logger,
+    });
     cascadedTo.push(...r.cascadedTo);
     failed.push(...r.failed);
   }
@@ -530,12 +515,11 @@ export function deriveParentState(siblings) {
  * recursive cascade" progress comment, Epic exclusion) are preserved
  * verbatim.
  *
- * Resilience matches {@link cascadeCompletion}: disjoint parent groups
- * run in parallel via {@link dispatchCascadeGroups}; parents within a
- * group run sequentially; the per-parent lock from
- * {@link withParentCascadeLock} prevents races on shared ancestors; and
- * per-parent errors are isolated so a sibling parent's failure does not
- * discard work on the others.
+ * Resilience matches {@link cascadeCompletion}: parents run
+ * sequentially; the per-parent lock from {@link withParentCascadeLock}
+ * prevents races on shared ancestors; and per-parent errors are
+ * isolated so a sibling parent's failure does not discard work on the
+ * others.
  *
  * @param {import('../../ITicketingProvider.js').ITicketingProvider} provider
  * @param {number} ticketId
@@ -572,21 +556,15 @@ export async function cascadeParentState(provider, ticketId, opts = {}) {
   const parsedParents = await resolveParentIds(provider, ticket, ticketId);
   if (parsedParents.length === 0) return { cascadedTo: [], failed: [] };
 
-  const groups = await groupByAncestor(parsedParents, provider);
-  const results = await dispatchCascadeGroups({
-    parsedParents,
-    groups,
-    flushLogger: opts._logger ?? Logger,
-    processParent: (parentId, logger) =>
-      processStateCascadeParent(provider, parentId, {
-        notify: opts.notify,
-        _logger: logger,
-      }),
-  });
-
+  // Story #4017 — sequential per-parent walk (fan-out <= 1 under the
+  // 3-tier hierarchy); see cascadeCompletion for the rationale.
   const cascadedTo = [];
   const failed = [];
-  for (const r of results) {
+  for (const parentId of parsedParents) {
+    const r = await processStateCascadeParent(provider, parentId, {
+      notify: opts.notify,
+      _logger: opts._logger,
+    });
     cascadedTo.push(...r.cascadedTo);
     failed.push(...r.failed);
   }

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -151,6 +151,15 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // from it (`deriveRiskEnvelope`). One entry per Epic; re-plans upsert in
   // place. Schema: `.agents/schemas/risk-verdict.schema.json`.
   'risk-verdict',
+  // Story #4019 — `epic-plan-lease-guard.js` upserts a `plan-lease`
+  // comment on the Epic at lease-acquire time, recording the claiming
+  // operator and the claim timestamp. `/epic-plan` emits no
+  // `story.heartbeat`, so this claim-time is the liveness signal that
+  // makes the documented `--steal` contract decidable: a foreign claim
+  // older than the lease TTL is reclaimed automatically; a fresh one
+  // refuses with the claim age. One entry per Epic; re-acquires upsert
+  // in place.
+  'plan-lease',
 ]);
 
 export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;