mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/epic-runner/concurrency-gate.js

@@ -1,186 +0,0 @@
-/**
- * Cross-Story conflict-finding gate for `epic-deliver-prepare.js`.
- *
- * Story #2297 — when the bounded `/plan` flow emitted concurrency
- * findings (Story #2296's validator pass), the operator may have shipped
- * them through to `/deliver` without resolving the underlying
- * `depends_on` gaps. This gate runs at Phase 1 of `/deliver` and
- * refuses to flip the Epic to `agent::executing` when the upcoming
- * waves still contain unresolved conflicts — surfacing the exact
- * remediation commands the operator should run before retrying.
- *
- * The gate is opt-in by default:
- *   - Advisory findings (severity 'soft') only log a summary.
- *   - Hard findings (severity 'hard') OR `delivery.failOnConcurrencyHazards: true`
- *     promote a hard-stop.
- *
- * `--ignore-concurrency-hazards` bypasses the gate; the flag use is
- * recorded on the Epic checkpoint so retro tooling can flag a run that
- * shipped despite an outstanding hazard.
- *
- * The module is pure: it consumes a findings array and a wave plan and
- * returns either a `{ ok: true }` envelope or throws. No I/O.
- */
-
-/**
- * Build the set of "pending" story identifiers from a wave plan. A Story
- * is pending unless its labels carry `agent::done`. Identifiers are
- * collected in three shapes — `id` (number), `number`, and `slug` — so
- * the caller can match findings keyed by any of them.
- *
- * @param {Array<Array<{ id?: number|string, number?: number|string, slug?: string, labels?: string[] }>>} wavePlan
- * @returns {Set<string>}
- */
-export function collectPendingStoryKeys(wavePlan) {
-  const pending = new Set();
-  if (!Array.isArray(wavePlan)) return pending;
-  for (const wave of wavePlan) {
-    if (!Array.isArray(wave)) continue;
-    for (const story of wave) {
-      if (!story || typeof story !== 'object') continue;
-      const labels = Array.isArray(story.labels) ? story.labels : [];
-      if (labels.includes('agent::done')) continue;
-      if (story.id != null) pending.add(String(story.id));
-      if (story.number != null) pending.add(String(story.number));
-      if (story.slug != null) pending.add(String(story.slug));
-    }
-  }
-  return pending;
-}
-
-/**
- * Extract every story identifier a finding references. Both finding
- * kinds in #2296's shape carry slugs; future persisted shapes may carry
- * numeric IDs — accept both transparently.
- */
-function findingStoryKeys(finding) {
-  const keys = [];
-  if (Array.isArray(finding?.storySlugs)) {
-    for (const s of finding.storySlugs) keys.push(String(s));
-  }
-  if (finding?.producer?.storySlug != null) {
-    keys.push(String(finding.producer.storySlug));
-  }
-  if (finding?.consumer?.storySlug != null) {
-    keys.push(String(finding.consumer.storySlug));
-  }
-  return keys;
-}
-
-/**
- * Filter findings to those that touch at least one pending Story. A
- * finding all of whose referenced Stories are already `agent::done` is
- * harmless — the conflict has already played out — and is dropped.
- *
- * When `pendingKeys` is empty (every wave is done) every finding is
- * filtered out. When a finding carries no identifiers (shape drift),
- * conservatively keep it so the operator sees the signal.
- *
- * @param {object[]} findings
- * @param {Set<string>} pendingKeys
- * @returns {object[]}
- */
-export function filterFindingsToPending(findings, pendingKeys) {
-  if (!Array.isArray(findings)) return [];
-  if (!(pendingKeys instanceof Set)) return findings;
-  return findings.filter((f) => {
-    const keys = findingStoryKeys(f);
-    if (keys.length === 0) return true;
-    return keys.some((k) => pendingKeys.has(k));
-  });
-}
-
-function isHardFinding(f) {
-  return f && f.severity === 'hard';
-}
-
-/**
- * Render the operator-facing remediation block for a hard-gate trip.
- * Produces a single multi-line string suitable for `throw new Error(...)`
- * — names every offending path, the affected Stories, and the exact
- * `gh issue edit` commands needed to add the missing `depends_on` links.
- */
-export function renderGateErrorMessage(findings, ownerRepo) {
-  const lines = [
-    'Refusing to flip Epic to agent::executing — cross-Story concurrency hazards remain unresolved.',
-    '',
-  ];
-  const sharedEditors = findings.filter((f) => f.kind === 'shared-editor');
-  const implicit = findings.filter(
-    (f) => f.kind === 'implicit-cross-story-dep',
-  );
-  if (sharedEditors.length > 0) {
-    lines.push('Shared-editor conflicts:');
-    for (const f of sharedEditors) {
-      const stories = Array.isArray(f.storySlugs) ? f.storySlugs : [];
-      lines.push(
-        `  - "${f.path}" written by ${stories.length} concurrent Stories: ${stories.map((s) => `#${s}`).join(', ')}`,
-      );
-      lines.push(
-        '    Remediation: add a `depends_on` chain or split the edits into a dedicated late-wave wiring Story.',
-      );
-    }
-    lines.push('');
-  }
-  if (implicit.length > 0) {
-    lines.push('Implicit cross-Story dependencies:');
-    for (const f of implicit) {
-      const p = f.producer ?? {};
-      const c = f.consumer ?? {};
-      lines.push(
-        `  - "${f.path}" produced by Story #${p.storySlug ?? '?'} consumed by Story #${c.storySlug ?? '?'} (body.${c.sourceField ?? '?'})`,
-      );
-      const repoFlag = ownerRepo ? ` --repo ${ownerRepo}` : '';
-      lines.push(
-        `    Remediation: gh issue edit ${c.storySlug ?? '?'}${repoFlag} --add-body $'\\n\\nblocked by #${p.storySlug ?? '?'}'`,
-      );
-    }
-    lines.push('');
-  }
-  lines.push(
-    'Resolve the listed conflicts and re-run `/deliver`, or pass `--ignore-concurrency-hazards` to bypass this gate.',
-  );
-  return lines.join('\n');
-}
-
-/**
- * Apply the gate to a findings array.
- *
- * @param {object}    input
- * @param {object[]}  input.findings        - Findings filtered to pending waves.
- * @param {object}    [input.policy]        - Resolved `delivery.failOnConcurrencyHazards` (boolean).
- * @param {boolean}   [input.ignore]        - `--ignore-concurrency-hazards` flag value.
- * @param {string}    [input.ownerRepo]     - "owner/repo" string for `gh issue edit` hints.
- * @returns {{ tripped: boolean, reason: 'hard-severity'|'config-fail-on'|null, findings: object[], bypassed: boolean }}
- *          When the gate trips and `ignore` is false the caller should
- *          throw `renderGateErrorMessage(findings, ownerRepo)`. The
- *          returned `bypassed` is true when `ignore` short-circuits a
- *          trip; record it on the checkpoint.
- */
-export function evaluateConcurrencyGate({
-  findings = [],
-  policy = {},
-  ignore = false,
-  ownerRepo,
-} = {}) {
-  void ownerRepo;
-  const hardFindings = findings.filter(isHardFinding);
-  const failOnConcurrencyHazards = policy.failOnConcurrencyHazards === true;
-  if (hardFindings.length > 0) {
-    return {
-      tripped: true,
-      reason: 'hard-severity',
-      findings: hardFindings,
-      bypassed: ignore === true,
-    };
-  }
-  if (failOnConcurrencyHazards && findings.length > 0) {
-    return {
-      tripped: true,
-      reason: 'config-fail-on',
-      findings,
-      bypassed: ignore === true,
-    };
-  }
-  return { tripped: false, reason: null, findings: [], bypassed: false };
-}

package/.agents/scripts/lib/orchestration/epic-runner/deliver-phases.js

@@ -1,50 +0,0 @@
-/**
- * deliver-phases.js — phase enum and ordering utility for `/deliver`.
- *
- * Story #1155 (Epic #1142, 5.40.0). Originally extracted from the
- * legacy class-based checkpoint module so the phase enum and close-tail
- * semantics live in a dedicated module that downstream tooling (the
- * contract test) can import without dragging the provider-coupled
- * checkpoint surface along. Story #2409 routes the runtime checkpoint
- * read/write surface through `../epic-run-state-store.js`; this file
- * remains the canonical home for the phase enum + validator.
- */
-
-/**
- * Ordered list of `/deliver` phases. The checkpoint's `phase` field
- * stores the **next phase to run**, so a mid-flight crash during
- * `code-review` resumes by reading `phase === 'code-review'` and re-
- * entering Phase D from the start.
- */
-export const DELIVER_PHASES = Object.freeze([
-  'prepare',
-  'wave-loop',
-  'close-validation',
-  'code-review',
-  'retro',
-  'finalize',
-]);
-
-/**
- * Pure: index of `phase` in `DELIVER_PHASES`. Returns `-1` for unknown
- * values (callers treat that as "start fresh"); `+Infinity` for the
- * terminal `'done'` sentinel.
- */
-export function phaseIndex(phase) {
-  if (phase === 'done') return Number.POSITIVE_INFINITY;
-  return DELIVER_PHASES.indexOf(phase);
-}
-
-/**
- * Pure: validate that `nextPhase` is a known phase tag (or the terminal
- * `'done'` sentinel). Throws on invalid input — exported so the
- * `setPhase` store function and downstream callers share one failure mode.
- */
-export function assertValidDeliverPhase(nextPhase) {
-  if (nextPhase === 'done') return;
-  if (phaseIndex(nextPhase) >= 0) return;
-  throw new Error(
-    `Invalid /deliver phase ${JSON.stringify(nextPhase)}. ` +
-      `Expected one of ${DELIVER_PHASES.join(', ')} or 'done'.`,
-  );
-}

package/.agents/scripts/lib/orchestration/epic-runner/phases/build-wave-dag.js

@@ -1,129 +0,0 @@
-/**
- * Build the wave DAG from the Epic's open child Stories.
- *
- * `getSubTickets` returns the **direct** children of a parent ticket via
- * native sub-issues + checklist links + body reverse-lookup. The
- * canonical 2-tier hierarchy is Epic → Story, so the Epic's direct
- * `type::story` children are the complete Story set.
- *
- * We additionally filter out closed Stories — `getSubTickets`'s reverse-
- * reference search can surface closed-as-obsolete tickets whose body
- * still names the Epic (e.g. a Story replaced during a planning
- * iteration). Dispatching against those would silently fan a sub-agent
- * out at pre-replan work.
- *
- * Throws if no open Stories are found.
- */
-
-import { computeWaves } from '../../../Graph.js';
-import { TYPE_LABELS } from '../../../label-constants.js';
-import { buildStoryAdjacency } from '../../../story-adjacency.js';
-import { WaveScheduler } from '../wave-scheduler.js';
-
-/**
- * Collect the Epic's direct `type::story` children and return the open
- * ones, deduped by id.
- *
- * Exported so `snapshot.js#discoverStoryIds` and `epic-deliver-preflight`
- * can share the same enumeration contract — the snapshot.end payload,
- * preflight Story count, and wave DAG input set must never disagree.
- */
-export async function discoverOpenStories({ epicId, provider }) {
-  const descendants = (await provider.getSubTickets(epicId)) ?? [];
-  const seen = new Set();
-  const stories = [];
-  for (const t of descendants) {
-    const labels = t.labels ?? [];
-    if (!labels.includes(TYPE_LABELS.STORY)) continue;
-    // Defense-in-depth: never enumerate a context spec ticket (Tech
-    // Spec / Acceptance Spec) as a deliverable Story even if it carries
-    // `type::story`. The `createTicket` factory no longer stamps context
-    // tickets that way, but a context ticket mislabelled out-of-band must
-    // still never reach a delivery wave (it has no `story-<id>` branch or
-    // acceptance contract to deliver against).
-    if (
-      labels.some((l) => typeof l === 'string' && l.startsWith('context::'))
-    ) {
-      continue;
-    }
-    const rawState = t.state ?? 'open';
-    const norm = typeof rawState === 'string' ? rawState.toLowerCase() : 'open';
-    if (norm !== 'open') continue;
-    const id = t.id ?? t.number;
-    if (id == null || seen.has(id)) continue;
-    seen.add(id);
-    stories.push(t);
-  }
-  return stories;
-}
-
-export async function runBuildWaveDagPhase(ctx, collaborators, state) {
-  const { epicId, provider } = ctx;
-  const bus = collaborators?.bus ?? null;
-  if (bus) {
-    await bus.emit('epic.plan.start', { epicId });
-  }
-  const stories = await discoverOpenStories({ epicId, provider });
-  if (!stories.length) {
-    throw new Error(`Epic #${epicId} has no child stories to dispatch.`);
-  }
-  const { adjacency, taskMap } = buildStoryDag(stories);
-  const waves = computeWaves(adjacency, taskMap);
-  const scheduler = new WaveScheduler(waves);
-  if (bus) {
-    // epic.plan.end carries the computed waves as the array-of-arrays
-    // shape declared by the schema. Each inner array is the storyIds
-    // dispatched together in that wave. `computeWaves` may return
-    // entries that are objects (when fed `taskMap`); we normalize to a
-    // simple numeric matrix here so the payload validates and replays
-    // off the ledger without coupling readers to internal types.
-    await bus.emit('epic.plan.end', {
-      waves: normalizeWavesForEmit(waves),
-    });
-  }
-  return { ...state, stories, waves, scheduler };
-}
-
-/**
- * Normalize the runner's wave representation into the
- * `Array<Array<integer>>` shape declared by
- * `.agents/schemas/lifecycle/epic.plan.end.schema.json`. `computeWaves`
- * returns waves of `taskMap` entries (objects with `id`); the ledger
- * needs only the IDs. Defensive number coercion mirrors the same id
- * extraction used in `buildStoryDag` above so emit and DAG stay
- * structurally aligned.
- */
-function normalizeWavesForEmit(waves) {
-  if (!Array.isArray(waves)) return [];
-  return waves.map((wave) => {
-    if (!Array.isArray(wave)) return [];
-    return wave
-      .map((entry) => {
-        if (entry == null) return null;
-        if (typeof entry === 'number') return entry;
-        const id = entry.id ?? entry.number ?? entry.storyId;
-        return id == null ? null : Number(id);
-      })
-      .filter((n) => Number.isInteger(n) && n > 0);
-  });
-}
-
-/**
- * Convert an ordered list of story tickets into the adjacency/taskMap shape
- * that `Graph.computeWaves()` expects.
- *
- * The adjacency comes from the shared story-level builder
- * (`lib/story-adjacency.js#buildStoryAdjacency`), which owns the
- * dependency-source ordering contract (body `blocked by` references via
- * `parseBlockedBy`, then explicit `dependencies[]`) and drops foreign
- * edges so the DAG stays closed over the scheduled set.
- */
-function buildStoryDag(stories) {
-  const adjacency = buildStoryAdjacency(stories);
-  const taskMap = new Map();
-  for (const s of stories) {
-    const id = Number(s.id ?? s.number);
-    taskMap.set(id, { ...s, id });
-  }
-  return { adjacency, taskMap };
-}

package/.agents/scripts/lib/orchestration/epic-runner/phases/snapshot.js

@@ -1,103 +0,0 @@
-/**
- * Epic snapshot phase — fetch Epic ticket and enforce the acceptance-spec
- * start gate.
- *
- * Auto-close is now the default for `/deliver` (the human PR-merge is
- * the gate); no per-Epic label snapshot is required.
- *
- * Acceptance-spec start gate (Story #4324): an Epic may be delivered when
- * *either* the operator has explicitly waived the acceptance requirement
- * via the `acceptance::n-a` label, *or* the Epic body carries the
- * `## Acceptance Table` managed section (the folded home of the retired
- * `context::acceptance-spec` ticket's AC-ID table). Presence is
- * sufficient — the reviewer's OK during /plan Phase 7 is the approval
- * signal. This still refuses to launch Epics that skipped the /plan
- * Phase 7 acceptance authoring step (or didn't waive), surfacing the gap
- * at delivery time rather than letting Story dispatch race ahead without
- * a spec at all.
- */
-
-import { hasEpicSection } from '../../../epic-body-sections.js';
-import { ACCEPTANCE_NA } from '../../../label-constants.js';
-import { discoverOpenStories } from './build-wave-dag.js';
-
-/**
- * Run the snapshot phase.
- *
- * Fetch the Epic ticket, assert the acceptance-spec start gate, and emit
- * `epic.snapshot.start` at entry and `epic.snapshot.end` at exit via the
- * lifecycle bus. After the Epic #2880 / Story #2898 hard cutover the bus
- * is the sole mutator of phase state — production wiring (see
- * `createEpicRunnerCollaborators`) always supplies a bus, and named
- * listeners on the bus (LabelTransitioner, StructuredCommentPoster, …)
- * own every state side effect. The phase return shape (`{ ...state, epic }`)
- * is the function's contract with the runner pipeline; it is not a parallel
- * state write.
- *
- * The `bus` parameter is still defensively typed as optional because unit
- * fixtures occasionally pass `{}` as the collaborator bag (e.g. the
- * acceptance-spec gate tests under `tests/epic-runner/`); those callers
- * skip the emit but still exercise the gate logic. Production cannot
- * reach the `!bus` branch.
- *
- * `epic.snapshot.end` carries the enumerated story IDs the Epic owns
- * (matching the schema at `.agents/schemas/lifecycle/epic.snapshot.end.schema.json`).
- * This makes the snapshot record self-describing on disk: a reader of
- * `temp/epic-<id>/lifecycle.ndjson` can recover the dispatch set without
- * re-querying the provider.
- */
-export async function runSnapshotPhase(ctx, collaborators, state) {
-  const { epicId, provider } = ctx;
-  const bus = collaborators?.bus ?? null;
-  if (bus) {
-    await bus.emit('epic.snapshot.start', { epicId });
-  }
-  const epic = await provider.getTicket(epicId);
-  assertAcceptanceSpecGate({ epic, epicId });
-  let storyIds = [];
-  if (bus) {
-    storyIds = await discoverStoryIds({ epicId, provider });
-    await bus.emit('epic.snapshot.end', { epicId, storyIds });
-  }
-  return { ...state, epic };
-}
-
-/**
- * Enumerate the Story IDs owned by an Epic. Delegates to
- * `discoverOpenStories` so the snapshot.end payload and the wave DAG
- * input set never disagree — both enumerate the Epic's direct Story
- * children and exclude closed reverse-referenced tickets.
- *
- * Returns a sorted array of positive integers (sort order makes the
- * ledger record deterministic across runs and platform iteration
- * quirks, which is what AC-3 / resume determinism depends on).
- */
-async function discoverStoryIds({ epicId, provider }) {
-  const stories = await discoverOpenStories({ epicId, provider });
-  const ids = stories
-    .map((t) => Number(t.id ?? t.number))
-    .filter((id) => Number.isInteger(id) && id > 0);
-  return [...new Set(ids)].sort((a, b) => a - b);
-}
-
-/**
- * Refuse to launch /deliver when the acceptance precondition has not been
- * satisfied. Throws a clear `Error` (per orchestration-error-handling
- * rule) so the `runAsCli` boundary maps it to `process.exit(1)` with the
- * operator-visible message intact.
- *
- * The gate checks section presence (or the waiver label) only.
- *
- * @param {{ epic: { labels?: string[], body?: string }, epicId: number }} args
- */
-function assertAcceptanceSpecGate({ epic, epicId }) {
-  const labels = epic?.labels ?? [];
-  if (labels.includes(ACCEPTANCE_NA)) return;
-
-  if (!hasEpicSection(epic?.body ?? '', 'acceptanceTable')) {
-    throw new Error(
-      `[epic-deliver] Epic #${epicId} cannot launch: the Epic body has no ## Acceptance Table section and the acceptance::n-a waiver label is absent. ` +
-        'Run /plan Phase 7 to author the acceptance table, or apply the acceptance::n-a label to the Epic to opt out.',
-    );
-  }
-}