mandrel 2.60.0 → 2.61.0

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

@@ -1,18 +1,6 @@
 /**
- * GitHub Provider — IssuesGateway.
- *
- * Owns the remaining read-side surface that did not belong to any of the
- * earlier six gateways: the raw GraphQL shim (`graphql` / `_ghGraphql`),
- * epic reads (`getEpic`), repository-wide label scans
- * (`listIssuesByLabel`), branch existence probes (`branchExists`), and the
- * three-strategy sub-ticket aggregator (`getSubTickets`).
- *
- * Extracted from `../github.js` in Story #2462 / Task #2481 — the final
- * slice that brings `GitHubProvider` down to a thin composition root.
- * Public surface on `GitHubProvider` is unchanged: every method here is
- * exposed by a one-line delegating wrapper on the parent provider.
- *
- * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ * GitHub Provider — IssuesGateway: the raw GraphQL shim, epic reads, label
+ * scans, branch probes, issue search, and the sub-ticket aggregator.
  */
 
 import { GhRateLimitError } from '../../lib/gh-exec.js';
@@ -33,12 +21,8 @@ import {
 import { composeBoundedQuery } from './search-query.js';
 
 /**
- * Retry classifier for the `searchIssues` call site. A rate-limit error is
- * non-transient **here** — the shared search budget (not `withTransientRetry`)
- * owns the wait, so the call must fail fast rather than burn its retry budget
- * re-issuing into an empty window. Every other error keeps the global
- * classification, so a 5xx/network blip still retries. `classifyGithubError`
- * itself is unchanged: other endpoints legitimately retry on rate-limit.
+ * Rate-limit is non-transient for search: the shared search budget owns the
+ * wait, so retrying would only re-issue into an empty window.
  *
  * @param {unknown} err
  * @returns {string}
@@ -48,20 +32,11 @@ function classifySearchRetry(err) {
   return classifyGithubError(err);
 }
 
-/**
- * Concurrency budget for the `getSubTickets` fan-out — preserved from
- * the old `./github/issues.js` predecessor.
- */
 export const SUBTICKET_HYDRATION_CONCURRENCY = 8;
 
 /**
- * The `Issue.parent` read backing {@link IssuesGateway#getParentIssue}.
- *
- * Node selection is deliberately identical to `SUB_ISSUES_QUERY`'s, so the
- * parent and the children a caller holds come back in one shape and
- * `subIssueNodeToTicket` maps both. Addressed by `owner/repo/number` rather
- * than by node id because every caller starts from an issue number and would
- * otherwise pay a round-trip just to learn the node id.
+ * Node selection matches `SUB_ISSUES_QUERY` so `subIssueNodeToTicket` maps
+ * parent and children alike; addressed by number to skip a node-id lookup.
  */
 const PARENT_ISSUE_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
   repository(owner: $owner, name: $repo) {
@@ -80,9 +55,6 @@ const PARENT_ISSUE_QUERY = `query($owner: String!, $repo: String!, $number: Int!
   }
 }`;
 
-// Re-export so existing test consumers that previously imported
-// `paginateRest` from this module continue to work without an extra
-// migration step.
 export { paginateRest };
 
 export class IssuesGateway {
@@ -104,16 +76,13 @@ export class IssuesGateway {
     this.owner = owner;
     this.repo = repo;
     this._hooks = hooks;
-    // The `/search/issues` fan-out budget. Defaults to the process-wide
-    // singleton so every gateway instance shares one 30/min window; injectable
-    // so unit tests drive it deterministically (Story #4678).
+    // Process-wide singleton by default so all gateways share one 30/min
+    // `/search/issues` window.
     this._searchBudget = searchBudget ?? defaultSearchBudget;
   }
 
   /**
-   * Run a GraphQL query/mutation through `gh api graphql` (POST with a
-   * JSON `{ query, variables }` body on stdin). Returns the `data` field.
-   * Throws when the response contains a non-empty `errors[]`.
+   * Returns the response's `data`; throws on a non-empty `errors[]`.
    */
   async ghGraphql(query, variables = {}, _opts = {}) {
     const body = { query };
@@ -135,9 +104,7 @@ export class IssuesGateway {
   }
 
   /**
-   * List every issue carrying `labels` (comma-separated string per GitHub
-   * REST). Used by the dispatcher / reconciler to scan for `agent::*`
-   * state.
+   * Raw REST issues (PRs excluded); `labels` is GitHub's comma-separated form.
    *
    * @field-manifest /repos/{owner}/{repo}/issues: number, title, body, labels,
    *                 state, assignees, pull_request
@@ -151,21 +118,9 @@ export class IssuesGateway {
   }
 
   /**
-   * The same scan as {@link listIssuesByLabel}, mapped through
-   * `issueToTicket` — one **declared** shape instead of a raw REST payload.
-   *
-   * The two differ in exactly the field that keeps biting: the REST payload
-   * calls the issue number `number` and the database id `id`, while every
-   * mapped read calls the issue number `id`. Consumers that could be handed
-   * either wrote `number ?? id` to cope, and that fallback is not a
-   * defensive nicety — it is a live bug, because on a *mapped* ticket `id`
-   * is the number and on a *raw* one it is the database id. A caller that
-   * ever receives the raw shape silently addresses issues by database id.
-   *
-   * `url` is carried alongside the mapped fields because two consumers
-   * (`epic-candidates`, `dependency-candidates`) render a link and
-   * `issueToTicket` drops `html_url`. It is the only addition; everything
-   * else is exactly what every other single-issue read returns.
+   * {@link listIssuesByLabel} mapped through `issueToTicket`, plus `url`.
+   * Prefer this: on a raw payload `id` is the database id, on a mapped one it
+   * is the issue number, and a `number ?? id` fallback silently mis-addresses.
    *
    * @param {{ state?: 'open'|'closed'|'all', labels?: string }} [opts]
    * @returns {Promise<Array<object>>} Mapped tickets (`id` is the issue number).
@@ -182,20 +137,9 @@ export class IssuesGateway {
   }
 
   /**
-   * Resolve an issue's container parent in **one** request.
-   *
-   * The rollup's child→parent lookup used to scan every open `type::epic`
-   * issue and read each one's children looking for the Story it was handed:
-   * O(open Epics) requests to answer a question the API answers directly.
-   * `Issue.parent` is the native sub-issue edge read backwards, so a Story
-   * with a container costs one call and a Story without one costs the same.
-   *
-   * Returns `null` — never throws — when the issue has no parent, when the
-   * response is shaped unexpectedly, or when the sub-issues feature is
-   * unavailable on this repo. A null is "no parent resolved here", which is
-   * exactly what the caller's body-checklist fallback exists for; turning a
-   * disabled feature into an exception would convert a degraded lookup into a
-   * failed lifecycle edge.
+   * Resolve an issue's container parent in one request via `Issue.parent`.
+   * Never throws: no parent, an odd shape, or sub-issues being unavailable all
+   * return `null`, leaving the caller's checklist fallback to run.
    *
    * @param {number} number Issue number whose parent to resolve.
    * @returns {Promise<object|null>} Mapped parent ticket, or null.
@@ -230,25 +174,10 @@ export class IssuesGateway {
   }
 
   /**
-   * Search issues by a free-text query via the REST search API
-   * (`GET /search/issues`). Deliberately REST, **not** GraphQL: transient
-   * GraphQL 401s are a known failure mode in this repo (the dedup port that
-   * consumes this method must not silently no-op on an auth blip), so the
-   * search rides the same `gh api` REST surface + transient-retry shim as
-   * every other read here.
-   *
-   * The caller (`audit-to-stories.js` `loadProvider()`) passes a 40-char
-   * fingerprint sha as the query so the search resolves the handful of
-   * issues whose fingerprint footer carries that sha; `route-finding.js`
-   * then confirms identity against the footer. Both open and closed issues
-   * are returned (no `state:` qualifier is appended) so a closed-fingerprint
-   * match can surface as `regression-of-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`).
+   * Search issues (open and closed, so a closed match can surface as a
+   * regression) in this repo via REST — not GraphQL, whose transient 401s
+   * would make the dedup port silently no-op. Capped at one 100-item page;
+   * `state` is lowercase.
    *
    * @param {{ query: string, owner?: string, repo?: string }} params
    * @returns {Promise<Array<{ number: number, state: string, body: string, title: string, html_url?: string }>>}
@@ -260,18 +189,12 @@ export class IssuesGateway {
     }
     const scopeOwner = owner ?? this.owner;
     const scopeRepo = repo ?? this.repo;
-    // Constrain the search to this repo and to issues (not PRs). The
-    // fingerprint sha is the free-text term; GitHub matches it against the
-    // issue body where the `<!-- audit-fingerprints: ... -->` footer lives.
-    // The composed `q` is bounded to GitHub Search's 256-char limit here — the
-    // only place that knows both the free text and the qualifiers it appends —
-    // truncating the free-text portion on a whole-token boundary (Story #4678).
+    // Bounded here — the only place that sees both the free text and the
+    // qualifiers — to Search's 256-char `q` limit.
     const qualifiers = [`repo:${scopeOwner}/${scopeRepo}`, 'type:issue'];
     const q = composeBoundedQuery(query, qualifiers);
     const params = new URLSearchParams({ q, per_page: '100' });
     const endpoint = `/search/issues?${params}`;
-    // Await the shared 30/min budget before every call so the whole scan's
-    // fan-out is throttled at the endpoint, not per caller (Story #4678).
     await this._searchBudget.take();
     let result;
     try {
@@ -284,9 +207,8 @@ export class IssuesGateway {
         },
       );
     } catch (err) {
-      // A rate limit means the window is empty: drain the budget until the
-      // reported reset so the *next* call pauses once, rather than every call
-      // retrying independently into the exhausted window.
+      // Drain the budget until reset so the next call pauses once instead of
+      // every caller retrying into the exhausted window.
       if (err instanceof GhRateLimitError) {
         this._searchBudget.noteRateLimited(parseRateLimitResetMs(err));
       }
@@ -320,9 +242,8 @@ export class IssuesGateway {
   }
 
   /**
-   * Probe whether `branch` exists on the remote. Returns `true` when the
-   * branch resolves, `false` on 404, and propagates any other transport
-   * error so auth/scope failures don't masquerade as a missing branch.
+   * `false` only on 404; other errors propagate so auth failures don't
+   * masquerade as a missing branch.
    *
    * @field-manifest GET /repos/{owner}/{repo}/branches/{branch}: name
    */
@@ -340,7 +261,6 @@ export class IssuesGateway {
     }
   }
 
-  /** Strategy 2 — Markdown checklist links `- [ ] #N` / `- [x] #N`. */
   _getChecklistChildren(parentBody) {
     const re = /-\s*\[[ xX]\]\s+#(\d+)/g;
     return [...(parentBody ?? '').matchAll(re)].map((m) =>
@@ -348,10 +268,7 @@ export class IssuesGateway {
     );
   }
 
-  /**
-   * Strategy 3 — reverse-search for issues that reference the parent
-   * (`Epic: #N` / `parent: #N`). Non-fatal on error.
-   */
+  /** Reverse-search for issues referencing the parent; non-fatal on error. */
   async _getReferencedChildren(parentId) {
     const getTickets = this._hooks.getTickets;
     const primeTicketCache = this._hooks.primeTicketCache;
@@ -370,32 +287,23 @@ export class IssuesGateway {
   }
 
   /**
-   * Aggregate sub-tickets via a priority-fallback strategy:
-   *   1. Native sub-issues (GraphQL) + checklist links in body — run in
-   *      parallel because checklist parsing is pure/synchronous.
-   *   2. Reverse-search (`_getReferencedChildren`) — a full-repo label
-   *      scan that is **only** executed when both strategy 1 sources
-   *      return empty. This avoids the unconditional full-repo scan that
-   *      fired on every call in the old `Promise.all` path.
+   * Union of native sub-issues and body checklist links; the full-repo
+   * reverse search runs only when both are empty.
    *
    * @param {number} parentId
-   * @param {{ fresh?: boolean }} [opts] - Pass `{ fresh: true }` to bypass
-   *   the per-instance ticket cache for every child hydration fetch. Used
-   *   by the cascade logic to skip a redundant second fan-out.
+   * @param {{ fresh?: boolean }} [opts] - `fresh` bypasses the ticket cache
+   *   for every child fetch.
    */
   async getSubTickets(parentId, opts = {}) {
     const getTicket = this._hooks.getTicket;
     const getNativeSubIssues = this._hooks.getNativeSubIssues;
     const parent = await getTicket(parentId);
 
-    // Strategy 1: native sub-issues (GraphQL) + checklist (synchronous).
     const [nativeChildIds, checklistChildIds] = await Promise.all([
       getNativeSubIssues(parent.nodeId, parentId),
       Promise.resolve(this._getChecklistChildren(parent.body)),
     ]);
 
-    // Strategy 2 (fallback): full-repo reverse-search — only when strategy
-    // 1 produced nothing, avoiding the unconditional scan on every call.
     let referencedChildIds = [];
     if (nativeChildIds.length === 0 && checklistChildIds.length === 0) {
       referencedChildIds = await this._getReferencedChildren(parentId);

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

@@ -1,57 +1,25 @@
 /**
- * GitHub Provider — LabelGateway.
- *
- * Owns `ensureLabels` (idempotent label create) plus the live-set
- * reconciliation helper (`_reconcileLabelsPresence` /
- * `_normalizeLabelListResult`). `gh label create` is the canonical CLI
- * surface for label creation; this gateway swallows the "already exists"
- * signal across all three surfaces (CLI stderr, API 422 body, legacy test
- * mock) so re-runs are idempotent.
- *
- * Extracted from `../github.js` in Story #2462 / Task #2478. Public
- * surface on `GitHubProvider` is unchanged — `ensureLabels`,
- * `_reconcileLabelsPresence`, and `_normalizeLabelListResult` all
- * delegate here.
- *
- * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ * GitHub Provider — LabelGateway: idempotent label create with live-set
+ * reconciliation, paginated listing, and delete.
  */
 
 import { withTransientRetry } from './errors.js';
 import { paginateRest } from './request-helpers.js';
 
 /**
- * Detect the "label already exists" signal across the surfaces `gh label
- * create` can emit it on. The CLI prints
- *
- *   `! Label "<name>" already exists`
- *
- * to stderr and exits non-zero; the underlying API surfaces a 422 with
- * `errors[].code === 'already_exists'`. The test mock throws
- * `Error('... code 422')`. Match all three — but require the patterns to
- * be **anchored to the label-create lexicon** so unrelated stderr lines
- * that happen to mention "already exists" don't get misclassified as
- * idempotent skips and let real creation failures look successful.
- *
- * Story #2018 (Bug 2) tightened the regexes after a fresh-repo bootstrap
- * counted 23 labels as "skipped" when none were actually created.
+ * "Label already exists" across CLI stderr, the API 422 `already_exists`
+ * body, and the legacy mock shape. Anchored to the label lexicon so an
+ * unrelated "already exists" can't turn a real create failure into a skip.
  */
 export function isLabelAlreadyExistsError(err) {
   if (!err) return false;
   const message = err?.message ?? '';
   const stderr = err?.stderr ?? '';
-  // CLI shapes (vary by gh version):
-  //   `! Label "<name>" already exists`
-  //   `label with name "<name>" already exists; use ` + '`--force`' + ` ...`
-  // Require both the "label" lexicon and the "already exists" signal (with
-  // anything in between) so unrelated errors are not misclassified as skips.
   if (/label\b[\s\S]*?already exists/i.test(stderr)) return true;
   if (/label\b[\s\S]*?already exists/i.test(message)) return true;
-  // REST API shape: 422 + `already_exists` code in the error body.
   if (/already_exists/i.test(stderr) || /already_exists/i.test(message)) {
     return true;
   }
-  // Test-mock legacy shape: `Error('... code 422 ...')` combined with the
-  // word "already exists" anywhere in the message.
   if (
     /\bcode\s+422\b/i.test(message) &&
     /already exists/i.test(message + stderr)
@@ -62,15 +30,8 @@ export function isLabelAlreadyExistsError(err) {
 }
 
 /**
- * Detect the "label does not exist" signal on the delete path. `gh api` exits
- * non-zero on a 404 with `gh: Not Found (HTTP 404)` on stderr; the REST body
- * carries `"message": "Not Found"`. Both are matched, and the numeric status
- * is matched on its own so a transport that surfaces only `err.status` still
- * classifies.
- *
- * Deliberately narrow: only a 404 counts. A 403 (scope) or a 422 must stay
- * loud, because reading either as "already gone" would let a sweep report
- * labels as reaped that are all still there.
+ * Only a 404 counts: reading a 403 or 422 as "already gone" would let a
+ * sweep report labels reaped that still exist.
  *
  * @param {unknown} err
  * @returns {boolean}
@@ -83,33 +44,13 @@ export function isLabelNotFoundError(err) {
   );
 }
 
-/**
- * GitHub's cap on a label description. A longer one is refused with an HTTP
- * 422 that `gh label create` reports as a bare exit 1 — a deterministic
- * create failure, never a truncation. Lives here rather than in the
- * provider-agnostic label vocabulary because it is an API constraint of this
- * provider (Story #5201, where two over-long `plan-persist` descriptions made
- * the `plan-run::<id>` cohort label uncreatable on every run).
- */
-// Module-private on purpose: nothing in production reads the number outside
-// the guard below, and the suite pins GitHub's published cap as a literal
-// rather than against our own constant.
+/** GitHub's description cap; longer is a 422 that `gh` reports as exit 1. */
 const LABEL_DESCRIPTION_MAX_LENGTH = 100;
 
 /**
- * Refuse a label description GitHub will reject anyway, **before** `gh` is
- * spawned.
- *
- * The API caps a description at {@link LABEL_DESCRIPTION_MAX_LENGTH}
- * characters and answers a longer one with an HTTP 422 that `gh label create`
- * surfaces as a bare exit 1 — legible only to a caller that digs the reason
- * out of stderr. Failing at the call site instead names the label and its
- * actual length, so the fix is obvious from the message alone.
- *
- * Deliberately a throw rather than a silent truncation: a truncated
- * description is a label whose text nobody chose, and every `ensureLabels`
- * caller already handles a throw — the bootstrap paths surface it, and
- * `plan-persist` degrades to creating its Stories without the cosmetic label.
+ * Fail before spawning `gh`, naming the label and its length. A throw, not a
+ * truncation: every caller already handles a throw, and a truncated
+ * description is text nobody chose.
  *
  * @param {{ name?: string, description?: string }} def
  * @throws {Error} when the description exceeds the cap.
@@ -134,22 +75,10 @@ export class LabelGateway {
   }
 
   /**
-   * Idempotent label creation. Each def's description is checked against
-   * GitHub's length cap first (`assertLabelDescriptionWithinCap`) so a
-   * guaranteed-422 create never reaches the network. Then, for each labelDef,
-   * attempt `gh label create
-   * <name> --color <hex> --description <text>`. The CLI prints
-   * "label already exists" (or the API surfaces a 422 "already_exists"
-   * error) when the name is taken; we swallow that and count it as
-   * `skipped`. Any other error propagates so transport faults stay loud.
-   *
-   * After the per-def loop, **reconcile against the live label set** by
-   * listing the labels actually present on the remote. Anything counted
-   * in `created` or `skipped` that isn't actually present is moved to a
-   * `missing[]` envelope — the bootstrap caller surfaces this loudly so a
-   * silent classification miss (Story #2018, Bug 2) can't pretend success.
-   * Verification failures (rate-limit, scope) are best-effort: they leave
-   * `missing` empty rather than aborting the bootstrap.
+   * Create each label, counting "already exists" as `skipped`; other errors
+   * propagate. Then reconcile against the live set: anything believed
+   * created/skipped but absent moves to `missing[]`, so a misclassification
+   * can't pass as success. A failed verification leaves `missing` empty.
    *
    * Returns `{ created: string[], skipped: string[], missing: string[] }`.
    */
@@ -182,10 +111,6 @@ export class LabelGateway {
     if (missing.length === 0) {
       return { created, skipped, missing };
     }
-    // Anything we believed we created/skipped that isn't actually on the
-    // remote is by definition a silent failure — drop it from those lists
-    // so the consumer's `created.length + skipped.length` math stays
-    // honest. The full label name survives in `missing[]`.
     const missingSet = new Set(missing);
     return {
       created: created.filter((n) => !missingSet.has(n)),
@@ -195,13 +120,9 @@ export class LabelGateway {
   }
 
   /**
-   * Best-effort post-loop reconcile for `ensureLabels`. Lists the live
-   * label set and returns the names from `labelDefs` that are absent.
-   * Internal helper — production callers go through `ensureLabels`.
-   *
-   * Accepts either the real `gh-exec` --json shape (returns an `Array`
-   * directly) or the legacy/test shape (`{stdout: '<json>', ...}`) so
-   * the verification path stays harness-agnostic.
+   * Names from `labelDefs` absent from the live set. Best-effort: an
+   * unreadable or empty listing means "verification unavailable", not
+   * "everything missing".
    */
   async _reconcileLabelsPresence(labelDefs) {
     let result;
@@ -212,9 +133,6 @@ export class LabelGateway {
     }
     const liveLabels = this._normalizeLabelListResult(result);
     if (!Array.isArray(liveLabels) || liveLabels.length === 0) {
-      // Listing returned nothing parseable. Treat as "verification
-      // unavailable" rather than "every label is missing" — false
-      // positives on this path would derail an otherwise-clean bootstrap.
       return [];
     }
     const liveNames = new Set();
@@ -230,19 +148,9 @@ export class LabelGateway {
   }
 
   /**
-   * List the repository's whole label vocabulary, paginated.
-   *
-   * Deliberately NOT modelled on `_reconcileLabelsPresence`'s
-   * `gh label list --limit 500`. That hard cap is fine for its own job —
-   * "are these 20 bootstrap labels present?" — and fatal for this one: a
-   * caller deciding which labels to delete from a truncated view would skip
-   * exactly the labels that sort after an accumulated pile, which is the
-   * failure Story #5189 exists to stop reproducing. `paginateRest` walks
-   * pages until a short one lands and throws (loudly) rather than truncating
-   * if the repository somehow exceeds its ceiling.
-   *
-   * Rows are projected to the fields a caller can rely on; a row without a
-   * usable `name` is dropped rather than passed on as a deletable target.
+   * The full label vocabulary, paginated — never the capped `--limit 500`
+   * list, since a caller choosing deletions from a truncated view would skip
+   * labels past the cap. Rows without a usable `name` are dropped.
    *
    * @returns {Promise<Array<{ name: string, color: string|null, description: string|null }>>}
    * @field-manifest /repos/{owner}/{repo}/labels: name, color, description
@@ -262,17 +170,8 @@ export class LabelGateway {
   }
 
   /**
-   * Delete one label by name.
-   *
-   * Goes through the REST surface (`DELETE /repos/{owner}/{repo}/labels/{name}`)
-   * rather than `gh label delete`, so the "already gone" signal arrives as a
-   * structured 404 on the same facade every other read here uses instead of
-   * as CLI prose — and so this gateway needs no new verb on the `gh` facade.
-   *
-   * A missing label resolves as a successful no-op. That is not leniency: the
-   * sweep this port exists for is expected to run repeatedly and concurrently
-   * with the close-path reap, so "someone else already deleted it" is the
-   * normal case, not an error.
+   * Delete via REST so "already gone" is a structured 404. A missing label is
+   * a normal no-op: sweeps run repeatedly and concurrently with the close reap.
    *
    * @param {string} name
    * @returns {Promise<{ deleted: boolean, reason: string|null }>}
@@ -294,6 +193,7 @@ export class LabelGateway {
     }
   }
 
+  /** Accepts the `gh-exec` array shape or a `{ stdout }` JSON wrapper. */
   _normalizeLabelListResult(result) {
     if (Array.isArray(result)) return result;
     if (result && typeof result.stdout === 'string') {

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

@@ -1,14 +1,6 @@
 /**
- * GitHub Provider — pure REST/GraphQL ticket mappers.
- *
- * Pure functions that translate raw GitHub API payloads (REST `Issue`,
- * GraphQL sub-issue node) into the normalized ticket shape consumed
- * throughout the dispatcher / reconciler layer. No I/O, no state, no
- * `execSync` —
- * verified by the sibling test which exercises the mappers without `gh`
- * installed.
- *
- * Extracted from `../github.js` in Story #1846 / Task #1859.
+ * GitHub Provider — pure mappers from REST issues / GraphQL sub-issue nodes
+ * to the normalized ticket shape.
  */
 
 function normalizeLabels(issue) {
@@ -35,10 +27,7 @@ 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.
+    // Distinguishes a landed Story from a superseded one; both are `closed`.
     stateReason: issue.state_reason ?? null,
   };
 }
@@ -57,13 +46,7 @@ export function issueToEpic(issue) {
 }
 
 export function subIssueNodeToTicket(node) {
-  // Story #3097 (Wave-0 additive, Epic #3078 Strategy B) — return `null`
-  // for absent sub-issue nodes instead of dereferencing properties on
-  // `null`/`undefined`. In 2-tier mode a Story can legitimately have zero
-  // Task children, which surfaces as an empty / missing sub-issue node
-  // when callers iterate the GraphQL response and pass each entry through
-  // this mapper. The legacy 4-tier path also benefits — a transient
-  // empty node returned mid-pagination no longer throws.
+  // Absent nodes are legitimate (childless Story, empty page entry).
   if (node == null) return null;
   const labels = normalizeLabels(node);
   return {
@@ -81,12 +64,7 @@ export function subIssueNodeToTicket(node) {
 }
 
 /**
- * Map a list of raw GraphQL sub-issue nodes to ticket objects, skipping
- * any null/undefined entries. Story #3097 (Wave-0 additive, Epic #3078
- * Strategy B) — gives callers a single Storyless-tolerant entry point so
- * the existing per-node mappers can stay strict for the 4-tier path while
- * the 2-tier path (Storyless: a Story with zero child Tasks) gets a
- * well-defined empty-array result.
+ * Skips null entries; a non-array yields `[]`.
  *
  * @param {Array<object|null|undefined>|null|undefined} nodes
  * @returns {object[]}

package/.agents/scripts/providers/github/merge-methods.js

@@ -1,24 +1,10 @@
 /**
- * GitHub Provider — MergeMethodsGateway.
- *
- * Owns `getMergeMethods` / `setMergeMethods` against `/repos/{owner}/{repo}`.
- * The narrow field list (`MERGE_METHOD_FIELDS`) keeps `getMergeMethods` and
- * `setMergeMethods` aligned on which keys they mirror — operators may have
- * tuned other repo flags and we deliberately do not surface them through
- * this interface.
- *
- * Extracted from `../github.js` in Story #2462 / Task #2479. Public
- * surface on `GitHubProvider` is unchanged — both merge-method methods
- * delegate here.
- *
- * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ * GitHub Provider — MergeMethodsGateway. Reads and writes only
+ * `MERGE_METHOD_FIELDS`, leaving other operator-tuned repo flags alone.
  */
 
 import { parseApiJson } from './request-helpers.js';
 
-/**
- * Fields the merge-method bootstrap reads/writes.
- */
 export const MERGE_METHOD_FIELDS = [
   'allow_squash_merge',
   'allow_rebase_merge',
@@ -38,10 +24,6 @@ export class MergeMethodsGateway {
   }
 
   /**
-   * Read the repo's current merge-method-related settings. Returns only
-   * the fields the bootstrap cares about so the diff layer can compare
-   * apples to apples regardless of what other knobs the repo exposes.
-   *
    * @field-manifest GET /repos/{owner}/{repo}: allow_squash_merge,
    *                 allow_rebase_merge, allow_merge_commit,
    *                 allow_auto_merge, delete_branch_on_merge
@@ -60,8 +42,7 @@ export class MergeMethodsGateway {
   }
 
   /**
-   * PATCH the repo with the supplied merge-method settings. Sparse body —
-   * only the supplied fields are sent / touched.
+   * Sparse PATCH: only supplied fields are sent.
    *
    * @field-manifest PATCH /repos/{owner}/{repo}: allow_squash_merge,
    *                 allow_rebase_merge, allow_merge_commit,

package/.agents/scripts/providers/github/project-board.js

@@ -1,18 +1,6 @@
 /**
- * GitHub Provider — ProjectBoardGateway.
- *
- * Owns the Projects V2 bootstrap surface: `resolveOrCreateProject`,
- * `ensureStatusField`, `ensureProjectFields`. The low-level GraphQL
- * mutations live in `./projects-v2-graphql.js`; this class threads the
- * parent provider's `_ctx` (which carries `projectNumber`, `projectOwner`,
- * `state`, and the shared cache) into each call so the legacy shim contract
- * is preserved.
- *
- * Extracted from `../github.js` in Story #2462 / Task #2479. Public
- * surface on `GitHubProvider` is unchanged — every project-board method
- * delegates here.
- *
- * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ * GitHub Provider — ProjectBoardGateway: threads the provider's shared
+ * `_ctx` into the Projects V2 shim.
  */
 
 import * as projects from './projects-v2-graphql.js';
@@ -20,9 +8,6 @@ import * as projects from './projects-v2-graphql.js';
 export class ProjectBoardGateway {
   /**
    * @param {{ ctx: object }} deps
-   *   `ctx` is the shared `_ctx` object the parent provider builds —
-   *   carries `projectOwner`, `projectName`, `projectNumber`,
-   *   `operatorHandle`, `cache`, `state`, and `hooks`.
    */
   constructor({ ctx } = {}) {
     this._ctx = ctx;