mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/story-init/context-resolver.js

@@ -1,92 +0,0 @@
-/**
- * context-resolver.js — Stage 1 of the story-init pipeline.
- *
- * Fetches the Story ticket, validates it carries `type::story`, parses its
- * body for hierarchy markers, and (optionally) injects/validates the
- * `recut-of` marker when `input.recutOf` is supplied.
- *
- * Pure stage signature: ({ provider, git, fs, logger, input }) → result.
- * `git` and `fs` are accepted for signature conformance but unused here.
- */
-
-import { TYPE_LABELS } from '../label-constants.js';
-import { injectRecutMarker, parseRecutMarker } from '../orchestration/recut.js';
-import { resolveStoryHierarchy } from '../story-lifecycle.js';
-
-/**
- * @param {object} deps
- * @param {object} deps.provider  Ticketing provider (getTicket, updateTicket).
- * @param {object} [deps.logger]  `{ progress?: (phase, msg) => void }`.
- * @param {object} deps.input
- * @param {number} deps.input.storyId
- * @param {number|null} [deps.input.recutOf]
- * @param {boolean} [deps.input.dryRun]
- * @returns {Promise<{ story: object, body: string, epicId: number, parentId: number|null }>}
- */
-export async function resolveContext({ provider, logger, input }) {
-  const { storyId, recutOf = null, dryRun = false } = input;
-  const progress = logger?.progress ?? (() => {});
-
-  let story;
-  try {
-    story = await provider.getTicket(storyId);
-  } catch (err) {
-    throw new Error(`Failed to fetch Story #${storyId}: ${err.message}`, {
-      cause: err,
-    });
-  }
-
-  if (!story.labels.includes(TYPE_LABELS.STORY)) {
-    throw new Error(
-      `Issue #${storyId} is not a Story (labels: ${story.labels.join(', ')}). Use the dispatcher for Epics.`,
-    );
-  }
-
-  let body = story.body ?? '';
-  const { epicId, parentId } = resolveStoryHierarchy(body);
-
-  if (!epicId) {
-    throw new Error(
-      `Story #${storyId} has no "Epic: #N" reference in its body. Cannot resolve hierarchy.`,
-    );
-  }
-
-  if (recutOf) {
-    if (recutOf === storyId) {
-      throw new Error(
-        `[story-init] --recut-of #${recutOf} cannot point at the Story itself.`,
-      );
-    }
-    const existing = parseRecutMarker(body);
-    if (existing && existing.parentStoryId !== recutOf) {
-      progress(
-        'RECUT',
-        `⚠️ Story #${storyId} already marked recut-of #${existing.parentStoryId}; overwriting with #${recutOf}.`,
-      );
-    }
-    if (!existing || existing.parentStoryId !== recutOf) {
-      const patched = injectRecutMarker(body, recutOf);
-      if (!dryRun) {
-        await provider.updateTicket(storyId, { body: patched });
-        progress(
-          'RECUT',
-          `🪪 Marked Story #${storyId} as recut-of #${recutOf} on the ticket body.`,
-        );
-      } else {
-        progress(
-          'RECUT',
-          `[DRY-RUN] Would mark Story #${storyId} as recut-of #${recutOf}.`,
-        );
-      }
-      body = patched;
-      story = { ...story, body: patched };
-    } else {
-      progress(
-        'RECUT',
-        `Story #${storyId} already carries recut-of #${recutOf} marker.`,
-      );
-    }
-  }
-
-  return { story, body, epicId, parentId };
-}

package/.agents/scripts/lib/story-init/donor-precheck.js

@@ -1,207 +0,0 @@
-/**
- * donor-precheck.js — verify the symlink-strategy donor is primed.
- *
- * When `delivery.worktreeIsolation.nodeModulesStrategy === 'symlink'`, every
- * Story worktree junctions/symlinks its `node_modules/` from a donor (the
- * `primeFromPath` directory, typically the repo root). If the donor lacks
- * `node_modules/` the symlink will resolve to nothing and the worktree
- * cannot install or run tests. This module runs once, just before
- * `applyNodeModulesStrategy`, to make sure the donor is primed.
- *
- * The pre-check is idempotent across concurrent wave dispatches via a
- * filesystem lock directory at `<donor>/.agents-donor-precheck.lock`. The
- * first arrival creates the lock atomically (`fs.mkdirSync`), runs
- * `npm ci`, and removes the lock. Concurrent callers either skip
- * (donor already primed) or wait for the lock to clear and re-check
- * existence — they do not double-run the installer.
- *
- * The helpers are split so the pure decision logic (`planDonorAction`) is
- * trivially testable without filesystem or child-process side-effects.
- */
-
-import { spawnSync } from 'node:child_process';
-import nodeFs from 'node:fs';
-import nodePath from 'node:path';
-
-const LOCK_DIRNAME = '.agents-donor-precheck.lock';
-const LOCK_POLL_INTERVAL_MS = 100;
-const LOCK_WAIT_TIMEOUT_MS = 5 * 60_000;
-
-/**
- * Pure: decide whether the donor needs a one-shot install.
- *
- * Returns one of:
- *   - `{ action: 'skip', reason }` — strategy is not symlink, or donor
- *     already has node_modules.
- *   - `{ action: 'install', donorPath }` — caller should run install at
- *     `donorPath`.
- *
- * @param {object} opts
- * @param {string} opts.strategy         The configured `nodeModulesStrategy`.
- * @param {string|null} opts.primeFromPath  Relative donor path.
- * @param {string} opts.repoRoot         Absolute repo root.
- * @param {{ existsSync: (p: string) => boolean }} [opts.fs]
- *   Filesystem facade for tests.
- * @returns {{ action: 'skip', reason: string } | { action: 'install', donorPath: string }}
- */
-export function planDonorAction({
-  strategy,
-  primeFromPath,
-  repoRoot,
-  fs = nodeFs,
-  path = nodePath,
-}) {
-  if (strategy !== 'symlink') {
-    return { action: 'skip', reason: 'strategy-not-symlink' };
-  }
-  if (!primeFromPath) {
-    return { action: 'skip', reason: 'no-prime-from-path' };
-  }
-  const donorPath = path.resolve(repoRoot, primeFromPath);
-  if (fs.existsSync(path.join(donorPath, 'node_modules'))) {
-    return { action: 'skip', reason: 'donor-already-primed' };
-  }
-  return { action: 'install', donorPath };
-}
-
-/**
- * Wait for the donor lock directory to be removed by the lock holder.
- * Returns true if the lock cleared in time, false on timeout.
- *
- * Exported for tests.
- */
-export function waitForLockClear({
-  lockPath,
-  fs = nodeFs,
-  pollIntervalMs = LOCK_POLL_INTERVAL_MS,
-  timeoutMs = LOCK_WAIT_TIMEOUT_MS,
-  now = () => Date.now(),
-  sleepFn,
-}) {
-  const start = now();
-  const sleep =
-    sleepFn ??
-    ((ms) => {
-      const signal = new Int32Array(new SharedArrayBuffer(4));
-      Atomics.wait(signal, 0, 0, ms);
-    });
-  while (fs.existsSync(lockPath)) {
-    if (now() - start >= timeoutMs) return false;
-    sleep(pollIntervalMs);
-  }
-  return true;
-}
-
-/**
- * Ensure the symlink-strategy donor is primed. Runs at most once per
- * dispatch wave because the lock directory is created atomically with
- * `fs.mkdirSync` (EEXIST = another concurrent process already won).
- *
- * Behaviour by lock outcome:
- *   - Lock acquired → run `npm ci`, then remove the lock.
- *   - Lock contended → wait for the lock to clear, then re-check
- *     existence. If `node_modules` is now present, skip; otherwise,
- *     surface an error (the lock holder failed and the caller cannot
- *     safely proceed).
- *
- * @param {object} opts
- * @param {string} opts.strategy
- * @param {string|null} opts.primeFromPath
- * @param {string} opts.repoRoot
- * @param {{ progress?: (kind: string, msg: string) => void }} [opts.logger]
- * @param {{ existsSync: typeof nodeFs.existsSync, mkdirSync: typeof nodeFs.mkdirSync, rmSync: typeof nodeFs.rmSync }} [opts.fs]
- * @param {typeof spawnSync} [opts.spawnFn]   Injected installer for tests.
- * @param {(opts: object) => boolean} [opts.waitFn]  Injected lock waiter.
- * @returns {{ action: 'skip' | 'installed' | 'waited', reason?: string, donorPath?: string, durationMs?: number }}
- */
-export function ensureDonorPrimed({
-  strategy,
-  primeFromPath,
-  repoRoot,
-  logger,
-  fs = nodeFs,
-  path = nodePath,
-  spawnFn = spawnSync,
-  waitFn = waitForLockClear,
-  now = () => Date.now(),
-}) {
-  const t0 = now();
-  const progress = logger?.progress ?? (() => {});
-  const plan = planDonorAction({ strategy, primeFromPath, repoRoot, fs, path });
-  if (plan.action === 'skip') {
-    return { action: 'skip', reason: plan.reason, durationMs: now() - t0 };
-  }
-
-  const { donorPath } = plan;
-  const lockPath = path.join(donorPath, LOCK_DIRNAME);
-  let lockAcquired = false;
-  try {
-    fs.mkdirSync(lockPath);
-    lockAcquired = true;
-  } catch (err) {
-    if (err.code !== 'EEXIST') throw err;
-  }
-
-  if (!lockAcquired) {
-    progress('DONOR-PRECHECK', `donor=${donorPath} lock contended, waiting...`);
-    const cleared = waitFn({ lockPath, fs });
-    if (!cleared) {
-      throw new Error(
-        `donor-precheck: timed out waiting for lock ${lockPath} to clear after ${LOCK_WAIT_TIMEOUT_MS}ms`,
-      );
-    }
-    if (!fs.existsSync(path.join(donorPath, 'node_modules'))) {
-      throw new Error(
-        `donor-precheck: lock holder released ${lockPath} without priming node_modules at ${donorPath}`,
-      );
-    }
-    progress(
-      'DONOR-PRECHECK',
-      `donor=${donorPath} primed by concurrent dispatch, proceeding.`,
-    );
-    return { action: 'waited', donorPath, durationMs: now() - t0 };
-  }
-
-  try {
-    // Re-check between mkdir and install: another process could have run
-    // and finished while we were racing on mkdirSync.
-    if (fs.existsSync(path.join(donorPath, 'node_modules'))) {
-      progress(
-        'DONOR-PRECHECK',
-        `donor=${donorPath} already primed (post-lock recheck), skipping install.`,
-      );
-      return {
-        action: 'skip',
-        reason: 'donor-primed-post-lock',
-        donorPath,
-        durationMs: now() - t0,
-      };
-    }
-    progress(
-      'DONOR-PRECHECK',
-      `donor=${donorPath} missing node_modules — running one-shot npm ci...`,
-    );
-    const result = spawnFn('npm', ['ci'], {
-      cwd: donorPath,
-      stdio: 'inherit',
-      shell: process.platform === 'win32',
-      timeout: 10 * 60_000,
-    });
-    if (result.status !== 0) {
-      throw new Error(
-        `donor-precheck: 'npm ci' at ${donorPath} exited with status ${result.status}`,
-      );
-    }
-    progress('DONOR-PRECHECK', `donor=${donorPath} primed in ${now() - t0}ms.`);
-    return { action: 'installed', donorPath, durationMs: now() - t0 };
-  } finally {
-    try {
-      fs.rmSync(lockPath, { recursive: true, force: true });
-    } catch (_err) {
-      // Best-effort lock release; subsequent runs will recover by
-      // re-checking node_modules existence.
-    }
-  }
-}
-
-export const __LOCK_DIRNAME = LOCK_DIRNAME;

package/.agents/scripts/lib/story-init/state-transitioner.js

@@ -1,80 +0,0 @@
-/**
- * state-transitioner.js — Stage 6 of the story-init pipeline.
- *
- * Flips the Story ticket to `agent::executing` at init time. Under the
- * 2-tier hierarchy the Story has inline acceptance and no child Task
- * lifecycle — `/deliver` runs a single Story-implementation phase.
- */
-
-import {
-  STATE_LABELS,
-  transitionTicketState,
-} from '../orchestration/ticketing.js';
-import { batchTransitionTickets } from '../story-lifecycle.js';
-
-/**
- * Flip the Story to `agent::executing` and cascade upward (Epic / Feature).
- *
- * @param {object} deps
- * @param {object} deps.provider
- * @param {object} [deps.logger]
- * @param {object} deps.input
- * @param {number} deps.input.storyId
- * @param {object} deps.input.story - Prefetched Story ticket (`ticketSnapshot`).
- * @param {Function|null} [deps.input.notify]
- * @returns {Promise<{ ok: true }>}
- */
-export async function transitionStoryToExecuting({ provider, logger, input }) {
-  const { storyId, story, notify = null } = input;
-  const progress = logger?.progress ?? (() => {});
-
-  progress('TICKETS', `Transitioning Story #${storyId} to agent::executing...`);
-  await transitionTicketState(provider, storyId, STATE_LABELS.EXECUTING, {
-    ticketSnapshot: story,
-    cascade: true,
-    notify,
-  });
-
-  return { ok: true };
-}
-
-/**
- * Batch-transitions every child Task to a target label. Retained for
- * `batchTransitionTickets` unit coverage and post-merge batch closes;
- * story-init no longer calls this at startup.
- *
- * @param {object} deps
- * @param {object} deps.provider
- * @param {object} [deps.logger]
- * @param {object} deps.input
- * @param {Array<object>} deps.input.tasks
- * @param {Function|null} [deps.input.notify]
- * @returns {Promise<{
- *   ok: boolean,
- *   failed: Array<{id:number,attempts:number,error:string}>,
- *   transitioned: number[],
- *   skipped: number[],
- * }>}
- */
-export async function transitionTaskStates({ provider, logger, input }) {
-  const { tasks, notify = null } = input;
-  const progress = logger?.progress ?? (() => {});
-
-  progress(
-    'TICKETS',
-    `Transitioning ${tasks.length} Task(s) to agent::executing...`,
-  );
-  const transitionResult = await batchTransitionTickets(
-    provider,
-    tasks,
-    STATE_LABELS.EXECUTING,
-    { progress, notify },
-  );
-
-  return {
-    ok: transitionResult.failed.length === 0,
-    failed: transitionResult.failed,
-    transitioned: transitionResult.transitioned,
-    skipped: transitionResult.skipped,
-  };
-}

package/.agents/scripts/lib/story-init/task-graph-builder.js

@@ -1,124 +0,0 @@
-/**
- * task-graph-builder.js — Stage 4 of the story-init pipeline.
- *
- * Enumerates child Tasks of the Story, then topologically sorts them using
- * `blocked by` edges that reference other Tasks in the same set. Inter-Task
- * dependencies outside the child set are ignored (they are handled by the
- * Story-level blocker validator).
- */
-
-import { parseBlockedBy } from '../dependency-parser.js';
-import { buildGraph, detectCycle, topologicalSort } from '../Graph.js';
-import { Logger } from '../Logger.js';
-import { fetchChildTickets } from '../story-lifecycle.js';
-
-/**
- * Detect whether a Story body carries inline acceptance criteria, the
- * structural signal that the Story is authored in the 2-tier
- * (Story-with-inline-acceptance) shape and therefore should not be expected
- * to enumerate child Task tickets. Recognises both `## Acceptance` and
- * `## Acceptance Criteria` headings, with at least one list bullet under
- * them (mirroring the heading set the manifest-builder extracts).
- *
- * @param {string} body
- * @returns {boolean}
- */
-export function hasInlineAcceptance(body) {
-  if (typeof body !== 'string' || body.length === 0) return false;
-  const headingRe = /^##\s+Acceptance(?:\s+Criteria)?\s*$/im;
-  const match = body.match(headingRe);
-  if (!match || match.index == null) return false;
-  const rest = body.slice(match.index + match[0].length);
-  const nextHeading = rest.search(/^##\s+/m);
-  const block = nextHeading === -1 ? rest : rest.slice(0, nextHeading);
-  for (const rawLine of block.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (/^[-*]\s+(?:\[[ xX]\]\s+)?\S/.test(line)) return true;
-  }
-  return false;
-}
-
-function sortTasksByDependencies(tasks) {
-  if (tasks.length <= 1) return tasks;
-
-  const graphTasks = tasks.map((t) => ({
-    ...t,
-    dependsOn: parseBlockedBy(t.body ?? '').filter((dep) =>
-      tasks.some((tt) => tt.id === dep),
-    ),
-  }));
-  const { adjacency, taskMap } = buildGraph(graphTasks);
-
-  const cycle = detectCycle(adjacency);
-  if (cycle) {
-    throw new Error(
-      `[story-init] Dependency cycle detected among child tasks: ` +
-        `#${cycle.join(' → #')}. Fix the \`blocked by\` references before retrying.`,
-    );
-  }
-
-  return topologicalSort(adjacency, taskMap);
-}
-
-/**
- * @param {object} deps
- * @param {object} deps.provider
- * @param {object} [deps.logger]
- * @param {object} deps.input
- * @param {number} deps.input.storyId
- * @param {string} [deps.input.storyBody]   Story body — used to detect
- *   whether the Story carries inline acceptance (2-tier shape) so the
- *   empty-Task-list path is treated as expected rather than as a warning.
- *
- * Task #3154 (Epic #3078) deleted the `planning.hierarchy` flag; the
- * 2-tier vs 4-tier mode is now derived entirely from the ticket shape —
- * inline acceptance + zero Tasks resolves to `'2-tier'`, otherwise
- * `'4-tier'`.
- *
- * @returns {Promise<{ sortedTasks: Array<object>, mode: '2-tier'|'4-tier' }>}
- */
-export async function buildTaskGraph({ provider, logger, input }) {
-  const { storyId, storyBody = '' } = input;
-  const warn = logger?.warn ?? ((msg) => Logger.error(msg));
-  const progress = logger?.progress ?? (() => {});
-
-  // Story #4251 — under the 2-tier hierarchy every Story is childless, so the
-  // `fetchChildTickets` call (a `getTicket` + empty sub-issues GraphQL query +
-  // a never-matching `/search/issues` fallback) is pure waste on every
-  // story-init. The Story body is already in scope, so detect the inline-
-  // acceptance 2-tier shape FIRST and short-circuit without any child fetch —
-  // sparing the most aggressively rate-limited GitHub endpoint exactly during
-  // wide wave fan-out. A body lacking inline acceptance still falls through to
-  // the legacy child-enumeration path below.
-  if (hasInlineAcceptance(storyBody)) {
-    progress(
-      'TASKS',
-      `Story #${storyId} has inline acceptance — no child Tasks expected (2-tier shape).`,
-    );
-    return { sortedTasks: [], mode: '2-tier' };
-  }
-
-  // Legacy / 4-tier fall-through: a body lacking inline acceptance still
-  // enumerates child Tasks for the topological sort below.
-  const tasks = await fetchChildTickets(provider, storyId);
-
-  const mode = '4-tier';
-
-  if (tasks.length === 0) {
-    warn(
-      `[story-init] Warning: Story #${storyId} has no child Tasks. The agent will need to work from the Story body directly.`,
-    );
-  }
-
-  const sortedTasks = sortTasksByDependencies(tasks);
-  if (sortedTasks.length > 0) {
-    progress(
-      'TASKS',
-      `Found ${sortedTasks.length} child Task(s) in dependency order`,
-    );
-  }
-
-  return { sortedTasks, mode };
-}
-
-export { sortTasksByDependencies };

package/.agents/scripts/lib/story-init/transition-summary.js

@@ -1,34 +0,0 @@
-/**
- * transition-summary.js — Story-level summary of the batched task-start
- * fanout produced by `transitionTaskStates`.
- *
- * Replaces the previous N-per-Task `agent::executing` GitHub-comment fanout
- * with a single `low` notification routed to the Story. The dispatch
- * carries no `event` field, so under the curated `commentEvents` /
- * `webhookEvents` allowlists it never reaches either channel — init stays
- * silent on the GitHub timeline by default. The call remains as a sentinel
- * for operators who curate a `story-task-summary` event into their
- * `commentEvents` allowlist (out-of-tree extension).
- */
-
-/**
- * @param {object} deps
- * @param {Function|null} deps.notify - The standard `notify(ticketId, payload)` hook.
- * @param {number} deps.storyId
- * @param {number[]} deps.transitioned - IDs of Tasks that flipped to `agent::executing`.
- * @returns {Promise<{posted: boolean, message: string|null}>}
- */
-export async function postBatchedTransitionSummary({
-  notify,
-  storyId,
-  transitioned,
-}) {
-  if (typeof notify !== 'function') return { posted: false, message: null };
-  if (!Array.isArray(transitioned) || transitioned.length === 0) {
-    return { posted: false, message: null };
-  }
-  const taskList = transitioned.map((id) => `#${id}`).join(', ');
-  const message = `Story #${storyId} · ${transitioned.length} Task(s) transitioned to \`agent::executing\`: ${taskList}`;
-  await notify(storyId, { severity: 'low', message });
-  return { posted: true, message };
-}

package/.agents/scripts/lib/test-reserved-epic-temp-ids.js

@@ -1,35 +0,0 @@
-/**
- * Epic IDs reserved for tests that create `<repo>/temp/epic-<id>/` trees (or
- * other on-disk artefacts keyed by Epic number in the framework repo).
- *
- * Real GitHub Epic / issue numbers live outside this inclusive band. Tests
- * MUST use IDs in [TEST_EPIC_TEMP_ID_MIN, TEST_EPIC_TEMP_ID_MAX] whenever they
- * write per-Epic temp paths under the repository root so post-test cleanup and
- * tripwire helpers never collide with real delivery scratch.
- */
-
-export const TEST_EPIC_TEMP_ID_MIN = 999_000;
-export const TEST_EPIC_TEMP_ID_MAX = 999_999;
-
-/**
- * @param {unknown} id
- * @returns {boolean}
- */
-export function isReservedTestEpicTempId(id) {
-  return (
-    typeof id === 'number' &&
-    Number.isInteger(id) &&
-    id >= TEST_EPIC_TEMP_ID_MIN &&
-    id <= TEST_EPIC_TEMP_ID_MAX
-  );
-}
-
-/**
- * @param {string} dirName  Directory basename, e.g. `epic-999007`
- * @returns {boolean}
- */
-export function isReservedTestEpicTempDirName(dirName) {
-  const m = /^epic-([0-9]+)$/.exec(dirName);
-  if (!m) return false;
-  return isReservedTestEpicTempId(Number(m[1]));
-}