mandrel 2.30.0 → 2.32.0

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

@@ -1,16 +1,16 @@
 /**
- * GitHub Provider — error classifier + sub-issues GraphQL shapes.
+ * GitHub Provider — error classifier + sub-issues GraphQL shape.
  *
  * `classifyGithubError` buckets `gh-exec`-thrown errors into 4 categories
  * (`feature-disabled` / `permission` / `transient` / `permanent`) so the
- * sub-issues fallback and the addSubIssue retry loop have a deterministic
+ * sub-issues fallback and the shared retry loop have a deterministic
  * switch. Rate-limit detection wins over the 401/403 → permission rule
  * because GitHub's secondary rate limit is delivered as HTTP 403 with a
  * known message; if we bucketed it as 'permission' it would never be
  * retried.
  *
- * `SUB_ISSUES_QUERY` / `ADD_SUB_ISSUE_MUTATION` / `REMOVE_SUB_ISSUE_MUTATION`
- * are the three GraphQL shapes the sub-issues feature reads/writes.
+ * `SUB_ISSUES_QUERY` is the GraphQL shape the sub-issues read path uses.
+ * Story #5008 removed the add/remove mutations with the write surface.
  *
  * Extracted from `../github.js` in Story #1846 / Task #1857.
  */
@@ -153,11 +153,11 @@ export function classifyGithubError(err) {
 // transient network/connectivity errors — so every former consumer of either
 // module keeps (or gains) its prior retry coverage with no shim.
 //
-// Mirrors the addSubIssue retry contract in `sub-issues.js` so read-path
-// callers (paginateRest, getTicket, getNativeSubIssues, …) absorb the same
-// jittered exponential backoff on transient GitHub errors instead of
-// bubbling a one-shot 502/429/ECONNRESET that kills a longer pipeline
-// (e.g. the /deliver Phase E retro). The network consumers repointed here
+// Read-path callers (paginateRest, getTicket, getNativeSubIssues, …) all
+// absorb the same jittered exponential backoff on transient GitHub errors
+// through this one primitive, instead of bubbling a one-shot
+// 502/429/ECONNRESET that kills a longer pipeline (e.g. the /deliver
+// Phase E retro). The network consumers repointed here
 // (branch-protection, labels, projects-v2-graphql) call with no opts, so
 // they adopt these defaults; their retry *classes* (the network blips) are
 // preserved via the unified classifier above.
@@ -174,8 +174,7 @@ export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
  * `classify` (defaults to `classifyGithubError`) decides whether each
  * failure is retry-eligible: only `'transient'` retries; every other
  * bucket (`feature-disabled` / `permission` / `permanent`) bubbles on the
- * first failure. The retry shape matches `addSubIssue` in
- * `sub-issues.js:119-167`.
+ * first failure.
  *
  * `sleep` and `random` are injectable so tests can drive deterministic
  * retry paths without real-world timing.
@@ -256,19 +255,3 @@ export const SUB_ISSUES_QUERY = `query($id: ID!, $cursor: String) {
     }
   }
 }`;
-
-export const ADD_SUB_ISSUE_MUTATION = `
-  mutation($parentId: ID!, $subIssueId: ID!, $replaceParent: Boolean) {
-    addSubIssue(input: { issueId: $parentId, subIssueId: $subIssueId, replaceParent: $replaceParent }) {
-      issue { number }
-      subIssue { number }
-    }
-  }`;
-
-export const REMOVE_SUB_ISSUE_MUTATION = `
-  mutation($parentId: ID!, $subIssueId: ID!) {
-    removeSubIssue(input: { issueId: $parentId, subIssueId: $subIssueId }) {
-      issue { number }
-      subIssue { number }
-    }
-  }`;

package/.agents/scripts/providers/github/request-helpers.js

@@ -9,8 +9,7 @@
  *   1. **Transient retry** — each underlying `gh.api({...})` call inside
  *      `paginateRest` is wrapped in `withTransientRetry` (from `./errors.js`),
  *      so a single 502 / 429 / ECONNRESET on page N of M does not lose
- *      pages 1..N-1 of work. The retry shape matches the existing
- *      `addSubIssue` mutation retry contract in `sub-issues.js`.
+ *      pages 1..N-1 of work.
  *   2. **Page cap** — `paginateRest` enforces a hard ceiling (default
  *      `DEFAULT_PAGE_CAP = 50` → 5000 items at `per_page=100`). Exceeding
  *      the cap throws a clear error naming the endpoint, cap, and items

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

@@ -1,21 +1,19 @@
 /**
  * GitHub Provider — SubIssueGateway.
  *
- * Owns the native GitHub Sub-Issues link surface (the GraphQL `subIssues`
- * field on an Issue, plus the add/remove mutations) along with the
- * `reconcileSubIssueLinks` walker that backfills missing parent/child
- * links across an Epic's child set.
+ * Owns the **read** side of the native GitHub Sub-Issues surface: the
+ * GraphQL `subIssues` field on an Issue, paginated into a child-number
+ * list. Story #5008 removed the write side (`addSubIssue`,
+ * `removeSubIssue`) and the `reconcileSubIssueLinks` walker along with the
+ * rest of the Epic-hierarchy provider surface — v2 delivery is Story-only,
+ * so nothing establishes or repairs parent/child links any more.
  *
- * Extracted from `../github.js` in Story #2462 / Task #2480. Public
- * surface on `GitHubProvider` is unchanged — `addSubIssue`,
- * `removeSubIssue`, and `reconcileSubIssueLinks` all delegate here.
+ * Extracted from `../github.js` in Story #2462 / Task #2480. The read path
+ * still reaches `GitHubProvider` as `_getNativeSubIssues`, and
+ * `IssuesGateway` calls it directly through its `getNativeSubIssues` hook.
  *
- * Constructed with `{ ghGraphql, hooks, classifyGithubError, cache, queries }`:
+ * Constructed with `{ ghGraphql, cache, classifyGithubError }`:
  *   - `ghGraphql(query, variables, opts)`    — bound `_ghGraphql` from the parent.
- *   - `hooks.getTicket(id, opts)`            — bound to the TicketGateway.
- *   - `hooks.getTickets(parentId)`           — bound to the TicketGateway (for the reconciler).
- *   - `hooks.primeTicketCache(tickets)`      — bound to the TicketGateway (reconciler priming).
- *   - `hooks.invalidateTicket(id)`           — bound to the TicketGateway (post-mutation invalidate).
  *   - `cache.primeIfAbsent(ticket)`          — bound to the shared cache (native-walk priming).
  *
  * The gateway holds **no** transport state of its own — every call goes
@@ -26,25 +24,14 @@
  */
 
 import { Logger } from '../../lib/Logger.js';
-import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import {
-  ADD_SUB_ISSUE_MUTATION,
   classifyGithubError as defaultClassifyGithubError,
-  REMOVE_SUB_ISSUE_MUTATION,
   SUB_ISSUES_QUERY,
   withTransientRetry,
 } from './errors.js';
 import { subIssueNodeToTicket } from './mappers.js';
 import { defaultRetryWarn } from './request-helpers.js';
 
-// Concurrency + retry budgets — preserved from `../github.js` so dispatch
-// fan-out and sub-issue reconciliation keep their established shapes.
-const SUB_ISSUE_RECONCILE_CONCURRENCY = 4;
-const SUB_ISSUE_RETRY_MAX_ATTEMPTS = 6;
-const SUB_ISSUE_RETRY_BASE_DELAY_MS = 1000;
-const SUB_ISSUE_RETRY_MAX_DELAY_MS = 30000;
-const SUB_ISSUE_RETRY_JITTER_MS = 500;
-
 // Story #2852: cap the native sub-issue cursor walk so a runaway pagination
 // (e.g. an upstream API regression that never sets `hasNextPage = false`)
 // fails fast instead of looping forever. 50 cursor pages × 100 nodes per
@@ -55,24 +42,16 @@ export class SubIssueGateway {
   /**
    * @param {{
    *   ghGraphql: (query: string, variables?: object, opts?: object) => Promise<object>,
-   *   hooks?: {
-   *     getTicket?: (id: number, opts?: object) => Promise<object>,
-   *     getTickets?: (parentId: number) => Promise<object[]>,
-   *     primeTicketCache?: (tickets: object[]) => void,
-   *     invalidateTicket?: (id: number) => void,
-   *   },
    *   cache?: { primeIfAbsent: (ticket: object) => void },
    *   classifyGithubError?: (err: unknown) => string,
    * }} deps
    */
   constructor({
     ghGraphql,
-    hooks = {},
     cache,
     classifyGithubError = defaultClassifyGithubError,
   } = {}) {
     this._ghGraphql = ghGraphql;
-    this._hooks = hooks;
     this._cache = cache;
     this._classify = classifyGithubError;
   }
@@ -132,191 +111,4 @@ export class SubIssueGateway {
     }
     return childIds;
   }
-
-  /**
-   * Establish the native sub-issue link between `parentNumber` and the
-   * child identified by `childNodeId`. Retries on transient errors with
-   * jittered exponential backoff before re-throwing.
-   */
-  async addSubIssue(
-    parentNumber,
-    childNodeId,
-    opts = { replaceParent: false },
-  ) {
-    const getTicket = this._hooks.getTicket;
-    if (typeof getTicket !== 'function') {
-      throw new Error(
-        '[SubIssueGateway] addSubIssue requires a getTicket hook',
-      );
-    }
-    const parentTicket = await getTicket(parentNumber);
-    let lastErr;
-    for (let attempt = 0; attempt < SUB_ISSUE_RETRY_MAX_ATTEMPTS; attempt++) {
-      try {
-        const result = await this._ghGraphql(
-          ADD_SUB_ISSUE_MUTATION,
-          {
-            parentId: parentTicket.nodeId,
-            subIssueId: childNodeId,
-            replaceParent: opts.replaceParent,
-          },
-          { headers: { 'GraphQL-Features': 'sub_issues' } },
-        );
-        // Sub-issue link mutates the parent's sub-issue list. Invalidate so
-        // the next `getTicket(parentNumber)` re-fetches a coherent view.
-        if (typeof this._hooks.invalidateTicket === 'function') {
-          this._hooks.invalidateTicket(parentNumber);
-        }
-        return result;
-      } catch (err) {
-        lastErr = err;
-        const category = this._classify(err);
-        const isFinalAttempt = attempt === SUB_ISSUE_RETRY_MAX_ATTEMPTS - 1;
-        if (category !== 'transient' || isFinalAttempt) throw err;
-        const base = Math.min(
-          SUB_ISSUE_RETRY_MAX_DELAY_MS,
-          SUB_ISSUE_RETRY_BASE_DELAY_MS * 2 ** attempt,
-        );
-        const delay =
-          base + Math.floor(Math.random() * SUB_ISSUE_RETRY_JITTER_MS);
-        Logger.warn(
-          `[GitHubProvider] sub-issue link transient error for parent #${parentNumber} (attempt ${attempt + 1}/${SUB_ISSUE_RETRY_MAX_ATTEMPTS}); retrying in ${delay}ms: ${err.message}`,
-        );
-        await new Promise((r) => setTimeout(r, delay));
-      }
-    }
-    throw lastErr;
-  }
-
-  async removeSubIssue(parentNumber, subIssueNumber) {
-    const getTicket = this._hooks.getTicket;
-    if (typeof getTicket !== 'function') {
-      throw new Error(
-        '[SubIssueGateway] removeSubIssue requires a getTicket hook',
-      );
-    }
-    const parentTicket = await getTicket(parentNumber);
-    const childTicket = await getTicket(subIssueNumber);
-    const result = await this._ghGraphql(
-      REMOVE_SUB_ISSUE_MUTATION,
-      { parentId: parentTicket.nodeId, subIssueId: childTicket.nodeId },
-      { headers: { 'GraphQL-Features': 'sub_issues' } },
-    );
-    if (typeof this._hooks.invalidateTicket === 'function') {
-      this._hooks.invalidateTicket(parentNumber);
-      this._hooks.invalidateTicket(subIssueNumber);
-    }
-    return result;
-  }
-
-  /**
-   * Walk every child of `epicId` whose body footer carries `parent: #N` and
-   * verify the native sub-issue link is present. Re-establish missing links
-   * via `addSubIssue` (which retries internally). Idempotent.
-   */
-  async reconcileSubIssueLinks(epicId) {
-    const PARENT_RE = /(?:^|\n)parent:\s*#(\d+)/;
-    const getTicket = this._hooks.getTicket;
-    const getTickets = this._hooks.getTickets;
-    if (typeof getTicket !== 'function' || typeof getTickets !== 'function') {
-      throw new Error(
-        '[SubIssueGateway] reconcileSubIssueLinks requires getTicket + getTickets hooks',
-      );
-    }
-    const allChildren = await getTickets(epicId);
-    const parentByChild = new Map();
-    for (const child of allChildren) {
-      const match = (child.body ?? '').match(PARENT_RE);
-      if (!match) continue;
-      parentByChild.set(child.id, Number.parseInt(match[1], 10));
-    }
-
-    const childrenByParent = new Map();
-    for (const [childId, parentId] of parentByChild) {
-      if (!childrenByParent.has(parentId)) childrenByParent.set(parentId, []);
-      childrenByParent.get(parentId).push(childId);
-    }
-
-    let alreadyLinked = 0;
-    let reconciled = 0;
-    let failed = 0;
-    const failures = [];
-
-    const parentEntries = Array.from(childrenByParent.entries());
-
-    await concurrentMap(
-      parentEntries,
-      async ([parentId, childIds]) => {
-        let parent;
-        try {
-          parent = await getTicket(parentId);
-        } catch (err) {
-          for (const childId of childIds) {
-            failures.push({ parentId, childId, reason: err.message });
-          }
-          failed += childIds.length;
-          return;
-        }
-        if (!parent?.nodeId) {
-          for (const childId of childIds) {
-            failures.push({
-              parentId,
-              childId,
-              reason: 'parent missing nodeId',
-            });
-          }
-          failed += childIds.length;
-          return;
-        }
-
-        const linked = new Set(
-          await this.getNativeSubIssues(parent.nodeId, parentId),
-        );
-
-        await concurrentMap(
-          childIds,
-          async (childId) => {
-            if (linked.has(childId)) {
-              alreadyLinked++;
-              return;
-            }
-            let childTicket;
-            try {
-              childTicket = await getTicket(childId);
-            } catch (err) {
-              failures.push({ parentId, childId, reason: err.message });
-              failed++;
-              return;
-            }
-            if (!childTicket?.nodeId) {
-              failures.push({
-                parentId,
-                childId,
-                reason: 'child missing nodeId',
-              });
-              failed++;
-              return;
-            }
-            try {
-              await this.addSubIssue(parentId, childTicket.nodeId);
-              reconciled++;
-            } catch (err) {
-              failures.push({ parentId, childId, reason: err.message });
-              failed++;
-            }
-          },
-          { concurrency: SUB_ISSUE_RECONCILE_CONCURRENCY },
-        );
-      },
-      { concurrency: SUB_ISSUE_RECONCILE_CONCURRENCY },
-    );
-
-    return {
-      totalExpected: parentByChild.size,
-      alreadyLinked,
-      reconciled,
-      failed,
-      failures,
-    };
-  }
 }

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

@@ -19,8 +19,10 @@
  * module.
  *
  * Gateway map: tickets, sub-issues, comments, labels, branch-protection,
- * merge-methods, prs, project-board, issues (epics + sub-tickets +
- * branch probe + raw GraphQL).
+ * merge-methods, project-board, issues (epics + sub-tickets + branch probe
+ * + raw GraphQL). Story #5008 retired the `prs` gateway — `single-story-close`
+ * drives `gh pr create` directly — along with the sub-issue write surface and
+ * the repo-wide recent-comments feed.
  */
 
 import { createGh, gh as defaultGh } from '../lib/gh-exec.js';
@@ -125,16 +127,11 @@ const DELEGATIONS = [
   ['updateTicket', 'tickets.updateTicket'],
   ['_applyLabelMutations', 'tickets._applyLabelMutations'],
   ['_getNativeSubIssues', 'subIssues.getNativeSubIssues'],
-  ['addSubIssue', 'subIssues.addSubIssue'],
-  ['removeSubIssue', 'subIssues.removeSubIssue'],
-  ['reconcileSubIssueLinks', 'subIssues.reconcileSubIssueLinks'],
-  ['getRecentComments', 'comments.getRecentComments'],
   ['getTicketComments', 'comments.getTicketComments'],
   ['deleteComment', 'comments.deleteComment'],
   ['postComment', 'comments.postComment'],
   ['getBranchProtection', 'branchProtection.getBranchProtection'],
   ['setBranchProtection', 'branchProtection.setBranchProtection'],
-  ['createPullRequest', 'pullRequests.createPullRequest'],
   ['ensureLabels', 'labels.ensureLabels'],
   ['_reconcileLabelsPresence', 'labels._reconcileLabelsPresence'],
   ['getMergeMethods', 'mergeMethods.getMergeMethods'],

package/.agents/scripts/prune-baseline-orphans.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+// .agents/scripts/prune-baseline-orphans.js — Story #5012.
+//
+// Delete the baseline rows that are provably inert, and nothing else.
+//
+// This is the cheap remedy that makes `check-baseline-scope.js` fair. A gate
+// that hard-fails on a stale row is only defensible while clearing one costs a
+// command rather than a full re-score: the honest alternative — re-derive the
+// whole baseline — spends a coverage run or a full-tree MI pass to express a
+// deletion, which is why stale rows accumulate instead.
+//
+// Two row classes qualify, both decidable without measuring anything:
+//
+//   - `absent`       — the row's file is gone from disk.
+//   - `out-of-scope` — the file is still there, but the gate's own
+//                      `targetDirs` / `ignoreGlobs` no longer match it.
+//
+// The pruner never adds a row, never restamps `generatedAt` (a fresh stamp
+// over unmeasured rows is the exact failure an age check exists to catch), and
+// recomputes `rollup` through the kind's own arithmetic so the pruned envelope
+// still validates against its schema. An unreadable scope config degrades to
+// orphan-only pruning rather than treating unknown scope as empty scope.
+//
+// Exit codes:
+//   0  nothing to prune (or, without `--check`, the prune was written)
+//   1  `--check` found rows that would be pruned
+//   2  the pruner could not run
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import { PRUNABLE_KINDS, runPrune } from './lib/baselines/orphan-pruner.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { getQuality } from './lib/config/quality.js';
+import { resolveConfig } from './lib/config-resolver.js';
+
+const EXIT_CLEAN = 0;
+const EXIT_WOULD_PRUNE = 1;
+const EXIT_CANNOT_RUN = 2;
+
+const HELP = {
+  invocation:
+    'node .agents/scripts/prune-baseline-orphans.js [--check] [--kind <kind>] [--json]',
+  summary:
+    "Remove baseline rows whose file is gone from disk or has left the gate's scope. Never adds a row, never restamps generatedAt, never re-scores.",
+  flags: [
+    ['--check', 'Report what would be pruned, write nothing, exit 1 if any.'],
+    ['--kind <kind>', 'Prune one kind only (repeatable). Default: all.'],
+    ['--json', 'Emit the report as JSON instead of text.'],
+    ['--cwd <dir>', 'Repository root to prune. Default: process.cwd().'],
+  ],
+  notes: [
+    'Exit codes:\n  0  clean, or pruned\n  1  --check found prunable rows\n  2  the pruner could not run',
+  ],
+};
+
+/**
+ * Parse argv into an options bag. An unknown flag is an error, never a silent
+ * no-op — a typo'd `--dry-run` must not read as "write the files".
+ *
+ * @param {string[]} argv
+ * @returns {{ kinds: string[], check: boolean, json: boolean, cwd: string }}
+ */
+export function parseArgs(argv = []) {
+  const out = { kinds: [], check: false, json: false, cwd: null };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+    i += 1;
+    if (arg === '--check') out.check = true;
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--kind') {
+      out.kinds.push(value);
+      i += 1;
+    } else if (arg === '--cwd') {
+      out.cwd = value;
+      i += 1;
+    } else throw new Error(`unknown flag "${arg}" (try --help)`);
+  }
+  const unknown = out.kinds.filter((k) => !PRUNABLE_KINDS.includes(k));
+  if (unknown.length > 0) {
+    throw new Error(
+      `unknown --kind ${unknown.join(', ')}; expected one of ${PRUNABLE_KINDS.join(', ')}`,
+    );
+  }
+  if (out.kinds.length === 0) out.kinds = [...PRUNABLE_KINDS];
+  out.cwd = out.cwd ?? process.cwd();
+  return out;
+}
+
+/**
+ * Render one kind's outcome as indented text lines.
+ *
+ * @param {object} entry
+ * @param {boolean} check
+ * @returns {string[]}
+ */
+function renderKind(entry, check) {
+  if (!entry.present) return [];
+  if (entry.skipped)
+    return [`  - ${entry.kind}: skipped (${entry.skipReason})`];
+  const suffix = entry.degraded
+    ? ` [orphan-only: ${entry.degradedReason}]`
+    : '';
+  if (entry.removed.length === 0) {
+    return [`  - ${entry.kind}: clean${suffix}`];
+  }
+  const verb = check ? 'would prune' : 'pruned';
+  return [
+    `  - ${entry.kind}: ${verb} ${entry.removed.length} row(s)${suffix}`,
+    ...entry.removed.map((row) => `      · ${row.reason}: ${row.path}`),
+  ];
+}
+
+/**
+ * Render the whole report as text.
+ *
+ * @param {object} report
+ * @returns {string}
+ */
+export function formatReport(report) {
+  const verb = report.check ? 'would prune' : 'pruned';
+  const lines = [
+    `[prune-baseline-orphans] ${verb} ${report.removedCount} row(s) across ` +
+      `${report.writtenCount} file(s)`,
+    ...report.kinds.flatMap((entry) => renderKind(entry, report.check)),
+  ];
+  if (report.check && report.removedCount > 0) {
+    lines.push(
+      '',
+      'Run without --check to write the prune:',
+      '  node .agents/scripts/prune-baseline-orphans.js',
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * CLI entry point. Returns its exit code rather than calling `process.exit()`,
+ * so `runAsCli`'s `propagateExitCode` path settles it through `flushStdio` and
+ * an unbounded report is not truncated at a pipe boundary (Story #4783).
+ *
+ * @returns {Promise<number>}
+ */
+async function main() {
+  let opts;
+  let report;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+    const config = resolveConfig({ cwd: opts.cwd });
+    report = runPrune({
+      cwd: opts.cwd,
+      kinds: opts.kinds,
+      check: opts.check,
+      quality: getQuality(config) ?? { gates: {} },
+    });
+  } catch (err) {
+    const message = err?.message ?? String(err);
+    process.stdout.write(
+      `${JSON.stringify({ schemaVersion: '1', error: message }, null, 2)}\n`,
+    );
+    return EXIT_CANNOT_RUN;
+  }
+  process.stdout.write(
+    opts.json
+      ? `${JSON.stringify(report, null, 2)}\n`
+      : `${formatReport(report)}\n`,
+  );
+  return report.check && report.removedCount > 0
+    ? EXIT_WOULD_PRUNE
+    : EXIT_CLEAN;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'prune-baseline-orphans',
+  usage: HELP,
+  propagateExitCode: true,
+});

package/.agents/scripts/resolve-stories.js

@@ -197,7 +197,6 @@ export async function runResolveStories(
     stories,
     nativeEdges,
     warn: (m) => Logger.warn(m),
-    config,
   });
   const foreignDone = await resolveForeignDone({
     provider,
@@ -209,7 +208,6 @@ export async function runResolveStories(
     nativeEdges,
     foreignDone,
     warn: () => {},
-    config,
   });
 
   stdout.write(