mandrel 2.38.0 → 2.40.0

package/.agents/scripts/lib/orchestration/plan-persist/epic-ops.js

@@ -0,0 +1,320 @@
+/**
+ * epic-ops.js — create the optional container Epic for a plan-persist run.
+ *
+ * Story #5139. When `/mandrel-plan` authors more than two Stories it offers to
+ * group them under one container Epic. The Epic is **not** a work item: it
+ * holds a `## Goal` paragraph and a child checklist, carries `type::epic` and
+ * nothing else, and is never branched, implemented or delivered.
+ *
+ * Ordering matters — the Epic is created **after** the Stories, because its
+ * body embeds their issue numbers and its sub-issue edges need their database
+ * ids. A container that exists before its contents would have to be written
+ * twice.
+ *
+ * @module lib/orchestration/plan-persist/epic-ops
+ */
+
+import { createHash } from 'node:crypto';
+import { linkStoriesToEpic } from '../../../providers/github/sub-issue-add.js';
+import { Logger } from '../../Logger.js';
+import { LABEL_COLORS, TYPE_LABELS } from '../../label-constants.js';
+import { composeEpicBody } from '../epic-container.js';
+
+/**
+ * The Story count at or above which `/mandrel-plan` offers a container Epic.
+ *
+ * Three, i.e. "more than two" — at two Stories a pair of ids is as easy to
+ * carry as one, and the container earns nothing.
+ */
+export const EPIC_SUGGESTION_THRESHOLD = 3;
+
+/** Length of the truncated hex digest stamped into the Epic marker. */
+const EPIC_FINGERPRINT_LENGTH = 8;
+
+/** Marker prefix identifying a persist-authored Epic in an issue body. */
+const EPIC_FINGERPRINT_MARKER_PREFIX = 'mandrel-epic-fingerprint';
+
+/**
+ * Derive the Epic's resume identity from its title and the exact child set.
+ *
+ * Keyed on the children, not just the title: two runs that group *different*
+ * Stories are different containers even under the same title, and adopting
+ * one for the other would silently leave a cohort unlinked.
+ *
+ * Fields join on NUL, written as the `\u0000` escape and never as a raw byte
+ * — a literal NUL makes git classify the file binary and drop its diffs.
+ *
+ * @param {{ title: string, childIds: number[] }} opts
+ * @returns {string} Hex digest.
+ */
+function epicFingerprint({ title, childIds }) {
+  const ids = [...childIds].sort((a, b) => a - b).join(',');
+  return createHash('sha256')
+    .update(`${title}\u0000${ids}`)
+    .digest('hex')
+    .slice(0, EPIC_FINGERPRINT_LENGTH);
+}
+
+/**
+ * Render the invisible HTML-comment marker carrying the Epic's fingerprint.
+ *
+ * @param {string} fingerprint
+ * @returns {string}
+ */
+function epicFingerprintMarker(fingerprint) {
+  return `<!-- ${EPIC_FINGERPRINT_MARKER_PREFIX} ${fingerprint} -->`;
+}
+
+/**
+ * Ensure the `type::epic` label exists, **failing closed**.
+ *
+ * This is deliberately the opposite posture to the cohort and route labels
+ * (`ensurePersistLabel` in `story-ops.js`), which degrade to "create without
+ * the label" because they are cosmetic. `type::epic` is not cosmetic: it is
+ * the sole marker `isEpicTicket` reads, so an Epic created without it is not
+ * an Epic — it is a stray issue that `/mandrel-deliver` will hard-error on and
+ * no expansion will ever find. Skipping creation leaves the Stories, which
+ * are the part that matters, perfectly deliverable by id.
+ *
+ * @param {{ provider: object }} opts
+ * @returns {Promise<boolean>} Whether creation may proceed.
+ */
+async function ensureEpicLabel({ provider }) {
+  if (typeof provider?.ensureLabels !== 'function') return true;
+  try {
+    const result = await provider.ensureLabels([
+      {
+        name: TYPE_LABELS.EPIC,
+        color: LABEL_COLORS.TYPE,
+        description:
+          'Container-only grouping ticket — holds child Stories, carries no execution payload',
+      },
+    ]);
+    if (
+      Array.isArray(result?.missing) &&
+      result.missing.includes(TYPE_LABELS.EPIC)
+    ) {
+      Logger.warn(
+        `[plan-persist] "${TYPE_LABELS.EPIC}" could not be verified on the remote — ` +
+          'skipping the container Epic. The Stories are unaffected and deliver by id.',
+      );
+      return false;
+    }
+    return true;
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] "${TYPE_LABELS.EPIC}" label ensure failed (${err.message}) — ` +
+        'skipping the container Epic. The Stories are unaffected and deliver by id.',
+    );
+    return false;
+  }
+}
+
+/**
+ * Find an already-created Epic carrying this fingerprint, so a resumed
+ * persist adopts it instead of opening a second container.
+ *
+ * Non-fatal: a search failure returns `null` and the caller creates. A
+ * duplicate Epic is cosmetic; a crash mid-persist is not.
+ *
+ * @param {{ provider: object, fingerprint: string }} opts
+ * @returns {Promise<{ id: number, url?: string }|null>}
+ */
+async function findExistingEpic({ provider, fingerprint }) {
+  if (typeof provider?.listIssuesByLabel !== 'function') return null;
+  try {
+    const marker = epicFingerprintMarker(fingerprint);
+    const found = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.EPIC,
+    });
+    const hit = (Array.isArray(found) ? found : []).find((issue) =>
+      String(issue?.body ?? '').includes(marker),
+    );
+    if (!hit) return null;
+    const id = Number(hit.number ?? hit.id);
+    if (!Number.isInteger(id) || id <= 0) return null;
+    return { id, url: hit.html_url ?? hit.url ?? undefined };
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] Epic resume lookup failed (${err.message}); creating a new container.`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Link the created Stories under the Epic as native sub-issue edges.
+ *
+ * Non-fatal by design — the body checklist is the durable mirror, and
+ * `getSubTickets` reads it as a first-class child source. A lost edge costs
+ * the GitHub UI's nesting, not the grouping itself.
+ *
+ * @param {{ provider: object, epicNumber: number, childIds: number[] }} opts
+ * @returns {Promise<{ added: number, skipped: number, failed: number }|null>}
+ */
+async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
+  if (
+    typeof provider?.getDependencyWriteContext !== 'function' ||
+    typeof provider?.getTicket !== 'function'
+  ) {
+    Logger.warn(
+      '[plan-persist] provider exposes no getDependencyWriteContext/getTicket — ' +
+        'skipping native sub-issue edges. The Epic body checklist still lists every child.',
+    );
+    return null;
+  }
+
+  try {
+    const { gh, owner, repo } = provider.getDependencyWriteContext();
+    const summary = await linkStoriesToEpic({
+      epicNumber,
+      childIssueNumbers: childIds,
+      getTicket: (issueNumber) => provider.getTicket(issueNumber),
+      owner,
+      repo,
+      gh,
+    });
+    if (summary.failed > 0) {
+      Logger.warn(
+        `[plan-persist] ${summary.failed} sub-issue edge(s) could not be written. ` +
+          'The Epic body checklist still lists every child; add the links by hand ' +
+          'if you want them nested in the GitHub UI.',
+      );
+    } else {
+      Logger.info(
+        `[plan-persist] sub-issue edges: ${summary.added} added, ` +
+          `${summary.skipped} already present.`,
+      );
+    }
+    return summary;
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] native sub-issue mirroring failed (${err.message}) — ` +
+        'the Epic body checklist still lists every child.',
+    );
+    return null;
+  }
+}
+
+/**
+ * Create the container Epic for a persisted cohort.
+ *
+ * Returns `null` whenever no Epic was created — not requested, too few
+ * Stories, or the label could not be ensured. Callers treat `null` as the
+ * ordinary no-Epic outcome, never as a failure.
+ *
+ * **The Epic never receives an `agent::*` label.** Its labels are exactly
+ * `[type::epic]`. That absence is load-bearing: it keeps the container out
+ * of the bare `/mandrel-deliver` ready list and outside `lint-issue-body.js`,
+ * which scopes itself to `type::story`.
+ *
+ * @param {{
+ *   provider: object,
+ *   epic: { title: string, goal: string }|null,
+ *   created: Array<{ id: number, title: string }>,
+ *   opts?: { dryRun?: boolean, minStories?: number },
+ * }} args
+ * @returns {Promise<{
+ *   id: number,
+ *   title: string,
+ *   url?: string,
+ *   childIds: number[],
+ *   adopted: boolean,
+ *   edges: { added: number, skipped: number, failed: number }|null,
+ * }|null>}
+ */
+export async function createContainerEpic({
+  provider,
+  epic,
+  created,
+  opts = {},
+}) {
+  const { dryRun = false, minStories = EPIC_SUGGESTION_THRESHOLD } = opts;
+  if (!epic) return null;
+
+  const title = typeof epic.title === 'string' ? epic.title.trim() : '';
+  const goal = typeof epic.goal === 'string' ? epic.goal.trim() : '';
+  if (title === '' || goal === '') {
+    throw new Error(
+      '[plan-persist] A container Epic requires both a title and a goal.',
+    );
+  }
+
+  const childIds = (Array.isArray(created) ? created : [])
+    .map((s) => s.id)
+    .filter((id) => Number.isInteger(id) && id > 0);
+
+  // Dry-run reports the intended container write-free. `created` carries
+  // negative placeholder ids there, so `childIds` is empty by construction —
+  // report the count from `created` itself rather than from the filtered list.
+  if (dryRun) {
+    return {
+      id: -1,
+      title,
+      childIds: (Array.isArray(created) ? created : []).map((s) => s.id),
+      adopted: false,
+      edges: null,
+    };
+  }
+
+  if (childIds.length < minStories) {
+    Logger.info(
+      `[plan-persist] ${childIds.length} Story(ies) is below the ${minStories}-Story ` +
+        'Epic threshold — no container created.',
+    );
+    return null;
+  }
+
+  if (!(await ensureEpicLabel({ provider }))) return null;
+
+  const fingerprint = epicFingerprint({ title, childIds });
+  const existing = await findExistingEpic({ provider, fingerprint });
+  if (existing) {
+    Logger.info(
+      `[plan-persist] resuming: container Epic #${existing.id} already groups ` +
+        'this exact cohort — skipping create.',
+    );
+    const edges = await mirrorSubIssueEdges({
+      provider,
+      epicNumber: existing.id,
+      childIds,
+    });
+    return {
+      id: existing.id,
+      title,
+      url: existing.url,
+      childIds,
+      adopted: true,
+      edges,
+    };
+  }
+
+  const body = `${composeEpicBody({ goal, childIds })}\n${epicFingerprintMarker(fingerprint)}\n`;
+  const result = await provider.createIssue({
+    title,
+    body,
+    labels: [TYPE_LABELS.EPIC],
+  });
+
+  const epicNumber = result.number ?? result.id;
+  const edges = await mirrorSubIssueEdges({
+    provider,
+    epicNumber,
+    childIds,
+  });
+
+  Logger.info(
+    `[plan-persist] container Epic #${epicNumber} groups ${childIds.length} Story(ies): ` +
+      `deliver them all with /mandrel-deliver ${epicNumber}`,
+  );
+
+  return {
+    id: epicNumber,
+    title,
+    url: result.url,
+    childIds,
+    adopted: false,
+    edges,
+  };
+}

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -68,6 +68,7 @@ import {
   renderHardConflictError,
 } from '../ticket-validator-conflicts.js';
 import { upsertStructuredComment } from '../ticketing.js';
+import { createContainerEpic } from './epic-ops.js';
 import {
   enforceFanOutGate,
   surfaceSoftConflictFindings,
@@ -711,6 +712,10 @@ export async function runPlanPersist({
     closeSuperseded = true,
     routeDowngradeReason = null,
     injectedRules = undefined,
+    // Story #5139 — the optional container Epic. `null` (the default) is the
+    // ordinary shape: no Epic is created unless `/mandrel-plan` offered one
+    // above the threshold and the operator confirmed it.
+    epic = null,
   } = opts;
 
   // Boundary for the plan-metrics summary below: everything this invocation
@@ -840,6 +845,18 @@ export async function runPlanPersist({
     });
   }
 
+  // Story #5139 — the container Epic is created LAST among the writes: its
+  // body embeds the child issue numbers and its sub-issue edges need their
+  // database ids, neither of which exists until the Stories are live. It is
+  // never load-bearing, so a failure here degrades to "no container" and the
+  // Stories still deliver by id.
+  const containerEpic = await createContainerEpic({
+    provider,
+    epic,
+    created,
+    opts: { dryRun },
+  });
+
   const supersede = await runSupersedePhase({
     provider,
     stories,
@@ -866,5 +883,6 @@ export async function runPlanPersist({
     freshness,
     waveTable,
     supersede,
+    epic: containerEpic,
   };
 }

package/.agents/scripts/lib/orchestration/run-epilogue.js

@@ -7,6 +7,8 @@
  *   2. Rolls up friction follow-ups across every Story in the run and
  *      files/posts them on the primary Story.
  *   3. Checks sibling Spec/acceptance coherence across Story bodies.
+ *   4. Closes any container Epic whose children all landed (Story #5139) —
+ *      the only completion cascade v2 reintroduces.
  *
  * There is no inert planner-only path: `planRunEpilogue` enumerates steps
  * and `runPlanRunEpilogue` executes them. Single-Story runs skip the
@@ -19,6 +21,8 @@ import { selectAudits } from '../audit-suite/index.js';
 import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
 import { gitSpawn } from '../git-utils.js';
 import { Logger } from '../Logger.js';
+import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
+import { isEpicTicket, readEpicChildIds } from './epic-container.js';
 import { composeRoutedProposals } from './retro-proposals.js';
 import {
   assessRollupOutcome,
@@ -31,14 +35,130 @@ import { upsertStructuredComment } from './ticketing.js';
 
 /**
  * Canonical epilogue step kinds, in execution order.
- * @type {readonly ['audit-roster', 'follow-up-rollup', 'sibling-coherence']}
+ * @type {readonly ['audit-roster', 'follow-up-rollup', 'sibling-coherence', 'epic-close']}
  */
 export const RUN_EPILOGUE_STEP_KINDS = Object.freeze([
   'audit-roster',
   'follow-up-rollup',
   'sibling-coherence',
+  'epic-close',
 ]);
 
+/**
+ * Close a container Epic once every child Story has landed.
+ *
+ * This is the **only** completion cascade v2 reintroduces (Story #5139), and
+ * it is deliberately one-directional: closing the container, never touching a
+ * child's state, never reopening.
+ *
+ * The lookup runs child→parent by scanning open Epics, because linkage is
+ * parent→child only — a Story body carries no pointer back. That is the
+ * price of leaving Story bodies untouched, and it is cheap: open Epics are
+ * few, and the scan is scoped to Epics that actually contain one of this
+ * run's delivered Stories, so an unrelated Epic is never swept.
+ *
+ * Non-fatal throughout: the epilogue is a reporting tail, and a container
+ * left open costs tidiness, not correctness.
+ *
+ * @param {{ stories: string[], provider: object }} opts
+ * @returns {Promise<{ kind: string, closed: number[], pending: number[] }>}
+ */
+async function executeEpicClose({ stories, provider }) {
+  const result = { kind: 'epic-close', closed: [], pending: [] };
+  if (
+    typeof provider?.listIssuesByLabel !== 'function' ||
+    typeof provider?.updateTicket !== 'function'
+  ) {
+    return result;
+  }
+
+  const delivered = new Set(stories.map((id) => Number(id)));
+  let epics;
+  try {
+    epics = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.EPIC,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[run-epilogue] Could not list open Epics (${err?.message ?? err}); skipping the Epic close.`,
+    );
+    return result;
+  }
+
+  for (const epic of Array.isArray(epics) ? epics : []) {
+    if (!isEpicTicket(epic)) continue;
+    const epicId = Number(epic?.number ?? epic?.id);
+    if (!Number.isInteger(epicId)) continue;
+
+    const childIds = readEpicChildIds(epic?.body);
+    if (childIds.length === 0) continue;
+    // Only Epics this run actually advanced. Sweeping every open Epic would
+    // make a delivery close containers it had nothing to do with.
+    if (!childIds.some((c) => delivered.has(c))) continue;
+
+    let allLanded = true;
+    for (const childId of childIds) {
+      try {
+        const child = await provider.getTicket(childId);
+        if (!isSatisfiedChild(child)) {
+          allLanded = false;
+          break;
+        }
+      } catch (err) {
+        Logger.warn(
+          `[run-epilogue] Epic #${epicId}: could not read child #${childId} ` +
+            `(${err?.message ?? err}) — leaving the Epic open.`,
+        );
+        allLanded = false;
+        break;
+      }
+    }
+
+    if (!allLanded) {
+      result.pending.push(epicId);
+      continue;
+    }
+
+    try {
+      await provider.updateTicket(epicId, {
+        state: 'closed',
+        state_reason: 'completed',
+      });
+      Logger.info(
+        `[run-epilogue] Closed container Epic #${epicId} — all ${childIds.length} child Story(ies) landed.`,
+      );
+      result.closed.push(epicId);
+    } catch (err) {
+      Logger.warn(
+        `[run-epilogue] Could not close Epic #${epicId} (${err?.message ?? err}).`,
+      );
+      result.pending.push(epicId);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * A child no longer holds its Epic open once it is closed or `agent::done`.
+ *
+ * Mirrors `isSatisfiedBlocker` in `lib/orchestration/resolve-stories.js`
+ * rather than importing it: that module is the delivery-resolution path and
+ * pulling it in here would drag the whole story-body parser into the
+ * epilogue for a two-line predicate.
+ *
+ * @param {{ state?: string, labels?: unknown }} issue
+ * @returns {boolean}
+ */
+function isSatisfiedChild(issue) {
+  if (String(issue?.state ?? '').toLowerCase() === 'closed') return true;
+  const labels = Array.isArray(issue?.labels)
+    ? issue.labels.map((l) => (typeof l === 'string' ? l : l?.name))
+    : [];
+  return labels.includes(AGENT_LABELS.DONE);
+}
+
 /**
  * @param {string|number|{ id?: string|number, slug?: string }} entry
  * @returns {string|null}
@@ -123,6 +243,11 @@ export function planRunEpilogue({ planRunId, stories } = {}) {
       description: `Sibling-coherence check across the ${ids.length} Story specs of run ${effectiveRunId}`,
       stories: ids,
     },
+    {
+      kind: 'epic-close',
+      description: `Close any container Epic whose children all landed in run ${effectiveRunId}`,
+      stories: ids,
+    },
   ];
 
   return {
@@ -825,6 +950,10 @@ export async function runPlanRunEpilogue({
             provider,
           }),
         );
+      } else if (step.kind === 'epic-close') {
+        results.push(
+          await executeEpicClose({ stories: plan.stories, provider }),
+        );
       }
     } catch (err) {
       const message = err?.message ?? String(err);

package/.agents/scripts/lib/qa/resolve-qa-contract.js

@@ -26,11 +26,25 @@
  * harness invocation — by exact name or by raw-URL origin match against each
  * environment's `baseUrl` — and throws loudly (naming the known environments)
  * on an unknown name or unmatched URL.
+ *
+ * It also **resolves the selected environment's `signInSeam`** (Story #5135).
+ * A `{ skill }` seam naming an id that resolves to no readable `SKILL.md`
+ * under either skills root used to fail silently: the contract validated, the
+ * seam was returned unread, and the dangling pointer only surfaced much later
+ * when a sweep reached its sign-in step — after the harness had already
+ * driven a browser. Resolution now happens here, at config-resolution time,
+ * so the failure lands where the operator can fix `.agentrc.json`. A seam
+ * that is absent entirely is a legitimate, declarable state (the workflows
+ * drive the unauthenticated surface and record the gap), not an error.
  */
 
 import Ajv from 'ajv';
-
 import { QA_SCHEMA } from '../config-settings-schema.js';
+import { PROJECT_ROOT } from '../project-root.js';
+import {
+  resolveSkillFile,
+  SKILL_SEARCH_ROOTS,
+} from '../skills/walk-skill-files.js';
 
 /**
  * The harness-required fields. The AJV `QA_SCHEMA` keeps these optional so
@@ -242,6 +256,40 @@ function toOrigin(value) {
   }
 }
 
+/**
+ * Normalize and verify one environment's `signInSeam`.
+ *
+ * An absent seam normalizes to `null` — a declarable state, not an error.
+ * A `{ skill }` seam is resolved against both skills roots and throws when
+ * it resolves under neither, so a dangling pointer is caught here rather
+ * than mid-sweep. The resolved `SKILL.md` path is attached as
+ * `skillPath` so the harness reads the file the check actually found.
+ *
+ * @param {object | undefined} seam
+ * @param {string} envName Environment name, for the error message.
+ * @param {{ repoRoot?: string }} options
+ * @returns {object | null}
+ */
+function resolveSignInSeam(seam, envName, options) {
+  if (seam == null) return null;
+  if (typeof seam.skill !== 'string') return seam;
+
+  const repoRoot = options.repoRoot ?? PROJECT_ROOT;
+  const found = resolveSkillFile(repoRoot, seam.skill);
+  if (found === null) {
+    throw new Error(
+      `qa: environment \`${envName}\` declares signInSeam.skill ` +
+        `\`${seam.skill}\`, which resolves to no readable SKILL.md. ` +
+        `Searched ${SKILL_SEARCH_ROOTS.map((r) => `\`${r}/<skill>/SKILL.md\``).join(' and ')}. ` +
+        'Author the skill under the consumer-writable `.agents/local/skills/` ' +
+        'zone (it is never pruned by `mandrel sync` and never flagged as ' +
+        'payload drift), correct the id, or omit `signInSeam` entirely if ' +
+        'this target genuinely has no sign-in seam.',
+    );
+  }
+  return { ...seam, skillPath: found.path };
+}
+
 /**
  * Resolve a single QA environment for one harness invocation.
  *
@@ -262,13 +310,17 @@ function toOrigin(value) {
  * Fails **loudly**: an unknown name or an unmatched URL throws an error that
  * names the known environments so the operator can correct the invocation.
  *
- * @param {{ environments: Record<string, { baseUrl: string, signInSeam: object, allowWrites?: boolean }>, defaultEnvironment: string }} contract
+ * @param {{ environments: Record<string, { baseUrl: string, signInSeam?: object, allowWrites?: boolean }>, defaultEnvironment: string }} contract
  *   A contract returned by `resolveQaContract`.
  * @param {string} [target] Environment name or raw URL. Omit for the default.
- * @returns {{ name: string, baseUrl: string, signInSeam: object, allowWrites: boolean }}
- * @throws {Error} on an unknown name or unmatched URL.
+ * @param {{ repoRoot?: string }} [options] `repoRoot` roots skill-seam
+ *   resolution; defaults to the project root. Injected by tests.
+ * @returns {{ name: string, baseUrl: string, signInSeam: object | null, allowWrites: boolean }}
+ *   `signInSeam` is `null` when the environment declares none.
+ * @throws {Error} on an unknown name, an unmatched URL, or a `{ skill }` seam
+ *   that resolves under no skills root.
  */
-export function resolveQaEnvironment(contract, target) {
+export function resolveQaEnvironment(contract, target, options = {}) {
   const environments = contract?.environments;
   if (
     environments == null ||
@@ -320,7 +372,7 @@ export function resolveQaEnvironment(contract, target) {
   return {
     name: resolvedName,
     baseUrl: env.baseUrl,
-    signInSeam: env.signInSeam,
+    signInSeam: resolveSignInSeam(env.signInSeam, resolvedName, options),
     allowWrites,
   };
 }