mandrel 1.94.0 → 2.1.0

package/.agents/scripts/plan-run-epilogue.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * plan-run-epilogue.js — execute the real per-run closeout for a
+ * multi-Story `/deliver`.
+ *
+ * Usage:
+ *   node .agents/scripts/plan-run-epilogue.js --stories 1,2,3
+ *
+ * Keyed on the delivered id set: an `adhoc-<sorted-ids>` run id is
+ * synthesized from `--stories`. Story #4540 retired the `--run <planRunId>`
+ * label-resolution branch along with the `plan-run::<id>` label itself.
+ */
+
+import './lib/runtime-deps/ensure-installed.js';
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import { runPlanRunEpilogue } from './lib/orchestration/run-epilogue.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const CLI_OPTIONS = {
+  stories: { type: 'string' },
+  cwd: { type: 'string' },
+};
+
+/**
+ * @param {string[]} [argv]
+ * @returns {Promise<object>}
+ */
+export async function main(argv = process.argv.slice(2)) {
+  const { values } = parseArgs({
+    args: argv,
+    options: CLI_OPTIONS,
+    strict: false,
+  });
+  const hasStoriesFlag =
+    typeof values.stories === 'string' && values.stories.trim().length > 0;
+  if (!hasStoriesFlag) {
+    throw new Error('Usage: node plan-run-epilogue.js --stories 1,2,3');
+  }
+  const cwd =
+    typeof values.cwd === 'string' && values.cwd.trim()
+      ? values.cwd.trim()
+      : process.cwd();
+  const config = resolveConfig({ cwd });
+  const provider = createProvider(config);
+
+  // Story #4540 retired the `--run <planRunId>` label-resolution branch
+  // along with the label itself. The epilogue is keyed on the delivered id
+  // set, and the synthesized `adhoc-<ids>` id it already used for positional
+  // runs is now the only id it needs.
+  const stories = values.stories
+    .split(',')
+    .map((s) => Number(s.trim()))
+    .filter((n) => Number.isInteger(n) && n > 0);
+
+  const planRunId = `adhoc-${[...stories].sort((a, b) => a - b).join('-')}`;
+
+  const result = await runPlanRunEpilogue({
+    planRunId,
+    stories,
+    provider,
+    config,
+    cwd,
+  });
+  warnOnUnresolvedBase(result);
+  warnOnEmptyRollup(result);
+  Logger.info(JSON.stringify(result, null, 2));
+  if (result.errors?.length) {
+    process.exitCode = 1;
+  }
+  return result;
+}
+
+/**
+ * Surface an unresolvable combined landed diff as a loud operator warning.
+ *
+ * The roster's changed-file set is the input the host walks its audit lenses
+ * against; a silent absence would read as "nothing changed" and the lens walk
+ * would look complete while covering nothing. Not fatal — with no diff the
+ * selector degrades to keyword-only lens selection, so the rest of the
+ * roster is still useful.
+ *
+ * @param {object} result - `runPlanRunEpilogue` envelope.
+ * @returns {void}
+ */
+function warnOnUnresolvedBase(result) {
+  const roster = (result?.results ?? []).find(
+    (r) => r?.kind === 'audit-roster',
+  );
+  const base = roster?.baseResolution;
+  if (base?.resolved !== false) return;
+  Logger.warn(
+    `⚠️  Combined landed diff unavailable — the pre-run base sha could not be ` +
+      `resolved against \`${base.baseRef}\`: ${base.reason}\n` +
+      `    changedFiles is null (NOT an empty set). Determine the run diff by ` +
+      `hand before walking the selected lenses.`,
+  );
+}
+
+/**
+ * Surface a zero-signal roll-up over a multi-Story run as a loud operator
+ * warning (Story #4578).
+ *
+ * The failure this exists to prevent is a *reassuring* one. The roll-up read
+ * "No friction signals — nothing to follow up" for a 7-Story run that
+ * contained a mid-run git outage, a parked worker needing an operator
+ * resume, and an acceptance critic that needed four rounds. Nothing was
+ * broken in the roll-up — the stream really was empty — but the report was
+ * indistinguishable from a clean run, so the retro loop that exists to learn
+ * from a run was silently blind to that run's pain.
+ *
+ * Not fatal: a genuinely friction-free multi-Story run is possible, and this
+ * cannot tell the two apart — which is precisely why it asks the operator
+ * rather than asserting either reading.
+ *
+ * @param {object} result - `runPlanRunEpilogue` envelope.
+ * @returns {void}
+ */
+function warnOnEmptyRollup(result) {
+  const rollup = (result?.results ?? []).find(
+    (r) => r?.kind === 'follow-up-rollup',
+  );
+  if (!rollup?.emptyRollupSuspect) return;
+  Logger.warn(
+    `⚠️  0 friction signals across ${rollup.storyCount} Stories — telemetry may not ` +
+      `have fired.\n` +
+      `    An empty roll-up is NOT evidence of a clean run: it is the same output a ` +
+      `run with\n` +
+      `    heavy friction produces when nothing recorded it. The runtime emits ` +
+      `friction from its\n` +
+      `    own observables (agent::blocked transitions, failed closes, exhausted ` +
+      `merge waits), so\n` +
+      `    zero here also means none of those fired. If this run had friction you ` +
+      `can name, that\n` +
+      `    telemetry gap is itself worth filing.`,
+  );
+}
+
+await runAsCli(import.meta.url, main);

package/.agents/scripts/post-structured-comment.js

@@ -22,10 +22,6 @@ import fs from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
-import {
-  outboxPathFor,
-  postCommentOrBuffer,
-} from './lib/orchestration/bookkeeping-outbox.js';
 import {
   assertValidStructuredCommentType,
   upsertStructuredComment,
@@ -41,11 +37,6 @@ Flags:
                  retro, epic-run-state, wave-0-start) (required).
   --body-file    Path to a file containing the markdown body (required).
   --provider     Provider name (default: inferred from .agentrc.json github block).
-  --buffer       Headless mode: buffer this upsert to the per-Epic bookkeeping
-                 outbox instead of posting live. Requires --epic. Drained to
-                 GitHub once at finalize by bookkeeping-reconcile.js (Epic
-                 #4476). Omit for attended runs (posts live, unchanged).
-  --epic <id>    Epic id owning the outbox (required with --buffer).
   --help         Show this message.
 `;
 
@@ -73,8 +64,6 @@ export function parseArgv(argv) {
       marker: { type: 'string' },
       'body-file': { type: 'string' },
       provider: { type: 'string' },
-      buffer: { type: 'boolean' },
-      epic: { type: 'string' },
       help: { type: 'boolean' },
     },
     strict: false,
@@ -126,33 +115,6 @@ export async function main(argv = process.argv.slice(2)) {
     : config;
   const provider = createProvider(effectiveConfig);
 
-  // Headless buffering (Epic #4476 M5): route the upsert to the per-Epic
-  // outbox instead of a live GitHub round-trip. Requires --epic to locate the
-  // outbox; finalize's bookkeeping-reconcile.js drains it once. Attended runs
-  // (no --buffer) are unchanged.
-  if (values.buffer) {
-    const epicId = Number.parseInt(values.epic ?? '', 10);
-    if (!Number.isInteger(epicId) || epicId <= 0) {
-      process.stderr.write(
-        '[post-structured-comment] --buffer requires --epic <id>.\n',
-      );
-      process.exit(2);
-    }
-    assertValidStructuredCommentType(values.marker);
-    const { buffered } = await postCommentOrBuffer({
-      provider,
-      ticketId,
-      marker: values.marker,
-      body,
-      headless: true,
-      outboxPath: outboxPathFor(epicId, config),
-    });
-    process.stdout.write(
-      `${JSON.stringify({ success: true, ticketId, type: values.marker, buffered })}\n`,
-    );
-    return;
-  }
-
   const envelope = await runPostStructuredComment({
     ticketId,
     type: values.marker,

package/.agents/scripts/pr-watch-with-update.js

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
 /**
- * pr-watch-with-update.js — the single CI-watch mechanism for BOTH the
- * Epic Phase 8 path (`deliver-epic.md`) and the standalone single-Story
- * Step 4 path (`single-story-deliver.md`). Story #4358 retired the bare
- * `gh pr checks --watch` from the single-Story path so both drive this
- * one CLI.
+ * pr-watch-with-update.js — the single CI-watch mechanism for the Story
+ * delivery path (`helpers/deliver-story.md` Step 4). Story #4358 retired
+ * the bare `gh pr checks --watch` so every caller drives this one CLI.
  *
  * Polls the PR's required checks to a terminal state and auto-recovers
  * from `mergeStateStatus: BEHIND` (via bounded `gh pr update-branch`
@@ -17,10 +15,13 @@
  *   - GREEN — every required check terminal + green → exit 0.
  *   - RED   — one or more required checks genuinely failed → exit 1
  *             IMMEDIATELY, consuming no resume budget. On red the CLI
- *             writes `temp/epic-<id>-ci-digest.{json,md}` (failing check
+ *             writes `temp/story-<id>-ci-digest.{json,md}` (failing check
  *             name, run id, a `gh run view --log-failed` tail, and a
  *             coarse classification) and prints the red-green
- *             remediation handoff.
+ *             remediation handoff. The digest is scoped by filename, so
+ *             it requires `--story` (Story #4539: the digest was
+ *             Epic-scoped and therefore never written on the only
+ *             delivery path v2 has).
  *   - STILL-RUNNING — the poll cap fired with checks still pending and
  *             none failed; the watcher re-armed up to
  *             `delivery.ci.watch.maxResumes` times, then returned a
@@ -35,8 +36,8 @@
  *   CLI flags override config; config overrides the framework fallback.
  *
  * Usage:
- *   node .agents/scripts/pr-watch-with-update.js --pr <n> [--repo owner/repo]
- *     [--epic <id>] [--max-updates N] [--poll-interval-ms MS]
+ *   node .agents/scripts/pr-watch-with-update.js --pr <n> --story <id>
+ *     [--repo owner/repo] [--max-updates N] [--poll-interval-ms MS]
  *     [--max-polls N] [--max-resumes N]
  */
 import { spawnSync } from 'node:child_process';
@@ -161,13 +162,33 @@ function resolveRunId({ prRef, checkName, cwd, spawnFn = spawnSync }) {
   }
 }
 
+/**
+ * Resolve which ticket the digest is keyed to. Story #4539: the digest used
+ * to be Epic-scoped by filename and returned `null` without an epic id — so
+ * on the v2 Story path (which has no Epic and invokes the watch with `--pr`
+ * alone) a red check wrote no digest at all, despite the module header
+ * advertising one. v2.0.0 removed the Epic tier; Story scope is the only
+ * scope.
+ *
+ * @param {{ storyId?: number|string|null }} opts
+ * @returns {{ kind: 'story', id: number } | null}
+ */
+export function resolveDigestScope({ storyId = null } = {}) {
+  if (storyId == null || String(storyId).length === 0) return null;
+  const parsed = Number.parseInt(String(storyId), 10);
+  return Number.isInteger(parsed) && parsed > 0
+    ? { kind: 'story', id: parsed }
+    : null;
+}
+
 /**
  * Write the CI failure digest (`.json` + `.md`) for a red watch. Returns
- * the two paths written (or `null` when no epic id was supplied — the
- * digest is Epic-scoped by filename). Exported for tests.
+ * the two paths written, or `null` when no story id was supplied (the
+ * digest is scoped by filename and has nothing to key on). Exported for
+ * tests.
  *
  * @param {object} opts
- * @param {number|string|null} opts.epicId
+ * @param {number|string|null} [opts.storyId] The v2 delivery scope.
  * @param {number} opts.prNumber
  * @param {Array<{name:string, outcome:string}>} opts.failures
  * @param {string} opts.tempRoot
@@ -178,7 +199,7 @@ function resolveRunId({ prRef, checkName, cwd, spawnFn = spawnSync }) {
  * @returns {{ jsonPath: string, mdPath: string } | null}
  */
 export function writeCiDigest({
-  epicId,
+  storyId = null,
   prNumber,
   failures,
   tempRoot,
@@ -187,13 +208,14 @@ export function writeCiDigest({
   runIdFn = resolveRunId,
   logTailFn = ghRunLogTail,
 }) {
-  if (epicId == null || String(epicId).length === 0) return null;
+  const scope = resolveDigestScope({ storyId });
+  if (!scope) return null;
   const primary = failures[0] ?? { name: 'unknown', outcome: 'failure' };
   const runId = runIdFn({ prRef, checkName: primary.name, cwd });
   const logTail = logTailFn({ runId, cwd });
   const classification = classifyFailure(primary.name);
   const digest = {
-    epicId: Number.parseInt(String(epicId), 10),
+    storyId: scope.id,
     prNumber,
     failingCheck: primary.name,
     failingOutcome: primary.outcome,
@@ -205,12 +227,12 @@ export function writeCiDigest({
   };
   const dir = path.isAbsolute(tempRoot) ? tempRoot : path.join(cwd, tempRoot);
   mkdirSync(dir, { recursive: true });
-  const base = `epic-${digest.epicId}-ci-digest`;
+  const base = `${scope.kind}-${scope.id}-ci-digest`;
   const jsonPath = path.join(dir, `${base}.json`);
   const mdPath = path.join(dir, `${base}.md`);
   writeFileSync(jsonPath, `${JSON.stringify(digest, null, 2)}\n`);
   const md = [
-    `# CI failure digest — Epic #${digest.epicId} (PR #${prNumber})`,
+    `# CI failure digest — Story #${scope.id} (PR #${prNumber})`,
     '',
     `- **Failing check:** \`${digest.failingCheck}\` (${digest.failingOutcome})`,
     `- **Run id:** ${runId ?? 'unresolved'}`,
@@ -247,7 +269,6 @@ export function writeCiDigest({
  * @param {object} opts
  * @param {number} opts.prNumber
  * @param {string|null} [opts.repo]
- * @param {number|string|null} [opts.epicId]  Epic id for the red-path digest.
  * @param {number|string} [opts.maxUpdates]
  * @param {number|string} [opts.pollIntervalMs]
  * @param {number|string} [opts.maxPolls]
@@ -266,7 +287,7 @@ export function writeCiDigest({
 export async function runPrWatch({
   prNumber,
   repo = null,
-  epicId = null,
+  storyId = null,
   maxUpdates,
   pollIntervalMs,
   maxPolls,
@@ -377,7 +398,7 @@ export async function runPrWatch({
   let digestPaths = null;
   try {
     digestPaths = writeDigestFn({
-      epicId,
+      storyId,
       prNumber,
       failures,
       tempRoot: effectiveTempRoot,
@@ -415,7 +436,7 @@ async function main() {
     options: {
       pr: { type: 'string' },
       repo: { type: 'string' },
-      epic: { type: 'string' },
+      story: { type: 'string' },
       'max-updates': { type: 'string' },
       'poll-interval-ms': { type: 'string' },
       'max-polls': { type: 'string' },
@@ -426,7 +447,7 @@ async function main() {
   return runPrWatch({
     prNumber: Number.parseInt(values.pr ?? '', 10),
     repo: values.repo ?? null,
-    epicId: values.epic ?? null,
+    storyId: values.story ?? null,
     maxUpdates: values['max-updates'],
     pollIntervalMs: values['poll-interval-ms'],
     maxPolls: values['max-polls'],

package/.agents/scripts/providers/github/compose.js

@@ -42,7 +42,6 @@ export function composeGateways(provider) {
     ...ghDeps,
     cache: p._cache,
     hooks: {
-      addSubIssue: (a, b) => p.addSubIssue(a, b),
       addItemToProject,
       getProjectNumber,
     },

package/.agents/scripts/providers/github/errors.js

@@ -272,22 +272,3 @@ export const REMOVE_SUB_ISSUE_MUTATION = `
       subIssue { number }
     }
   }`;
-
-// Story #2982 — native parent lookup for the cascade upward walk. The
-// inverse of `SUB_ISSUES_QUERY`: given a child Issue node, fetch the
-// `parent` field exposed by the Sub-Issues feature so `cascadeCompletion`
-// can resolve a parent even when the child body lacks the `parent: #N`
-// orchestrator footer.
-export const PARENT_ISSUE_QUERY = `query($id: ID!) {
-  node(id: $id) {
-    ... on Issue {
-      parent {
-        number
-        databaseId
-        id
-        title
-        state
-      }
-    }
-  }
-}`;

package/.agents/scripts/providers/github/issues.js

@@ -3,7 +3,7 @@
  *
  * Owns the remaining read-side surface that did not belong to any of the
  * earlier six gateways: the raw GraphQL shim (`graphql` / `_ghGraphql`),
- * epic enumeration (`getEpics`, `getEpic`), repository-wide label scans
+ * epic reads (`getEpic`), repository-wide label scans
  * (`listIssuesByLabel`), branch existence probes (`branchExists`), and the
  * three-strategy sub-ticket aggregator (`getSubTickets`).
  *
@@ -16,11 +16,10 @@
  */
 
 import { Logger } from '../../lib/Logger.js';
-import { TYPE_LABELS } from '../../lib/label-constants.js';
 import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import { isNotFoundError } from './branch-protection.js';
 import { withTransientRetry } from './errors.js';
-import { issueToEpic, issueToEpicListItem } from './mappers.js';
+import { issueToEpic } from './mappers.js';
 import {
   defaultRetryWarn,
   paginateRest,
@@ -114,13 +113,15 @@ export class IssuesGateway {
    * are returned (no `state:` qualifier is appended) so a closed-fingerprint
    * match can surface as `regression-of-closed`.
    *
-   * Returns the trimmed `[{ number, state, body }]` projection the dedup
-   * port expects. `state` is normalised to the REST lowercase form
-   * (`open` / `closed`).
+   * Returns the trimmed `[{ number, state, body, title, html_url }]`
+   * projection. Dedup callers use `{ number, state, body }`; duplicate-
+   * search also needs `title` / `html_url`. `state` is normalised to the
+   * REST lowercase form (`open` / `closed`). Results are capped at one
+   * Search API page (`per_page=100`).
    *
    * @param {{ query: string, owner?: string, repo?: string }} params
-   * @returns {Promise<Array<{ number: number, state: string, body: string }>>}
-   * @field-manifest GET /search/issues: total_count, items[number, state, body]
+   * @returns {Promise<Array<{ number: number, state: string, body: string, title: string, html_url?: string }>>}
+   * @field-manifest GET /search/issues: total_count, items[number, state, body, title, html_url]
    */
   async searchIssues({ query, owner, repo } = {}) {
     if (typeof query !== 'string' || query.trim().length === 0) {
@@ -133,7 +134,8 @@ export class IssuesGateway {
     // issue body where the `<!-- audit-fingerprints: ... -->` footer lives.
     const qualifiers = [`repo:${scopeOwner}/${scopeRepo}`, 'type:issue'];
     const q = `${query.trim()} ${qualifiers.join(' ')}`;
-    const endpoint = `/search/issues?q=${encodeURIComponent(q)}`;
+    const params = new URLSearchParams({ q, per_page: '100' });
+    const endpoint = `/search/issues?${params}`;
     const result = await withTransientRetry(
       () => this._gh.api({ method: 'GET', endpoint }),
       { label: `searchIssues ${query}`, onRetry: defaultRetryWarn },
@@ -144,39 +146,11 @@ export class IssuesGateway {
       number: item.number,
       state: item.state ?? 'open',
       body: item.body ?? '',
+      title: item.title ?? '',
+      html_url: item.html_url ?? undefined,
     }));
   }
 
-  /**
-   * List Epic-typed issues. Filter shape preserved from the old code.
-   *
-   * `filters.pageCap` / `filters.perPage` pass through to `paginateRest`
-   * so a caller that only needs a bounded shortlist (e.g. the
-   * standalone-Story corpus lookup in `planning-corpus.js`, which ranks
-   * candidates down to a top-5 shortlist) can cap the scan instead of
-   * inheriting the default 50-page / 5000-item ceiling. Omitted, both
-   * fall back to `paginateRest`'s own defaults — unchanged behavior for
-   * existing callers (e.g. `duplicate-search.js`).
-   *
-   * @field-manifest /repos/{owner}/{repo}/issues?labels=type::epic: number,
-   *                 title, labels, state, state_reason, pull_request
-   */
-  /* node:coverage ignore next */
-  async getEpics(filters = {}) {
-    const params = new URLSearchParams({
-      state: filters.state ?? 'all',
-      labels: TYPE_LABELS.EPIC,
-    });
-    const endpoint = `/repos/${this.owner}/${this.repo}/issues?${params}`;
-    const issues = await paginateRest(this._gh, endpoint, {
-      pageCap: filters.pageCap,
-      perPage: filters.perPage,
-    });
-    return issues
-      .filter((issue) => !issue.pull_request)
-      .map(issueToEpicListItem);
-  }
-
   /**
    * @field-manifest /repos/{owner}/{repo}/issues/{n}: number, id, node_id,
    *                 title, body, labels, state

package/.agents/scripts/providers/github/mappers.js

@@ -35,6 +35,11 @@ export function issueToTicket(issue) {
     labelSet: new Set(labels),
     assignees: (issue.assignees ?? []).map((a) => a.login),
     state: issue.state,
+    // `completed` | `not_planned` | `reopened` | null. `state` alone cannot
+    // tell a Story that landed from one closed as superseded — both read
+    // `closed` — so the close path needs this to avoid reporting a
+    // never-merged Story as landed.
+    stateReason: issue.state_reason ?? null,
   };
 }
 
@@ -109,15 +114,3 @@ export function issueToListItem(issue) {
     state: issue.state,
   };
 }
-
-export function issueToEpicListItem(issue) {
-  const labels = normalizeLabels(issue);
-  return {
-    id: issue.number,
-    title: issue.title,
-    labels,
-    labelSet: new Set(labels),
-    state: issue.state,
-    state_reason: issue.state_reason,
-  };
-}

package/.agents/scripts/providers/github/sub-issues.js

@@ -30,7 +30,6 @@ import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import {
   ADD_SUB_ISSUE_MUTATION,
   classifyGithubError as defaultClassifyGithubError,
-  PARENT_ISSUE_QUERY,
   REMOVE_SUB_ISSUE_MUTATION,
   SUB_ISSUES_QUERY,
   withTransientRetry,
@@ -134,52 +133,6 @@ export class SubIssueGateway {
     return childIds;
   }
 
-  /**
-   * Strategy 2 — native GitHub Sub-Issues, inverse direction. Given a
-   * child Issue node, return the parent's issue number (or `null` when
-   * the child has no native parent link, or the feature is disabled on
-   * this repo). Story #2982: used by `cascadeCompletion` as a third
-   * fallback so a Story whose body lost the `parent: #N` orchestrator
-   * footer still cascades upward to its true Sub-Issue parent.
-   *
-   * @param {string} childNodeId  GraphQL node ID of the child Issue.
-   * @param {number} childNumber  Issue number, for log context only.
-   * @returns {Promise<number|null>}
-   */
-  async getNativeParent(childNodeId, childNumber) {
-    if (!childNodeId) return null;
-    try {
-      const data = await withTransientRetry(
-        () =>
-          this._ghGraphql(
-            PARENT_ISSUE_QUERY,
-            { id: childNodeId },
-            { headers: { 'GraphQL-Features': 'sub_issues' } },
-          ),
-        {
-          label: `getNativeParent child=#${childNumber}`,
-          classify: this._classify,
-          onRetry: defaultRetryWarn,
-        },
-      );
-      const parent = data?.node?.parent;
-      if (!parent || typeof parent.number !== 'number') return null;
-      return parent.number;
-    } catch (err) {
-      const category = this._classify(err);
-      if (category === 'feature-disabled') {
-        Logger.warn(
-          `[GitHubProvider] sub-issues parent lookup unavailable (child #${childNumber})`,
-        );
-        return null;
-      }
-      Logger.error(
-        `[GitHubProvider] native parent lookup failed (child #${childNumber}, category=${category}): ${err.message}`,
-      );
-      throw err;
-    }
-  }
-
   /**
    * Establish the native sub-issue link between `parentNumber` and the
    * child identified by `childNodeId`. Retries on transient errors with