mandrel 2.59.0 → 2.61.0

package/.agents/scripts/providers/github/blocked-by-add.js

@@ -1,51 +1,22 @@
 /**
- * GitHub Provider — shared "set native blocked-by dependency" helper.
- *
- * Story #4067 — after issue creation during Phase 8 decomposition, each
- * Story's `depends_on` graph is known as a set of sibling slugs. This
- * helper translates those slug-to-issueNumber pairs into native GitHub
- * "blocked by" dependency edges so maintainers can see blocking
- * relationships directly in the GitHub UI.
- *
- * API surface used:
- *   Read:  GET  /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
- *   Write: POST /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
- *          body: { "issue_id": <integer db id of the blocking issue> }
- *
- * Contract:
- *   - **Idempotent** — reads existing edges first; only POSTs missing ones.
- *   - **Non-fatal** — catches all errors per edge, warns, and continues.
- *     The overall function never throws; errors are returned in a summary.
- *   - **No-op on empty input** — returns immediately when no depends_on
- *     edges are present or the slug→issueNumber map is empty.
+ * GitHub Provider — writes Story `depends_on` slugs as native "blocked by"
+ * edges (`POST .../dependencies/blocked_by` with the blocker's db id).
+ * Idempotent (reads existing edges first) and non-fatal: errors are counted
+ * in the summary, never thrown.
  */
 
 import { Logger } from '../../lib/Logger.js';
 import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import { paginateRest } from './request-helpers.js';
 
-/**
- * Bounded concurrency for the GitHub dependency-edge round-trips. Kept modest
- * to respect GitHub's secondary rate limits while still collapsing the wall-
- * clock latency from `sum(round-trips)` toward `sum(round-trips) / concurrency`.
- */
+/** Modest, to stay clear of GitHub's secondary rate limits. */
 const EDGE_CONCURRENCY = 5;
 
 /**
- * Fetch the existing blocked-by database ids for a given issue, **paginated
- * to exhaustion**.
- *
- * This read is the idempotency check: an edge it fails to see is re-POSTed.
- * Reading only the first page therefore made the writer non-idempotent past
- * the page boundary — every edge beyond it looked missing on every run
- * (Story #5046). `paginateRest` walks the pages and carries the shared
- * transient-retry and page-cap guards.
- *
- * Returns `[]` on any error so the caller falls back to posting the full
- * set of missing edges (worst case: a duplicate POST, which GitHub
- * handles idempotently). That non-fatal contract is deliberate and is the
- * inverse of the READ path in `lib/orchestration/resolve-stories.js`: a lost
- * write-side edge is cosmetic, a lost read-side edge removes a dispatch gate.
+ * Existing blocker db ids, paginated to exhaustion — this read is the
+ * idempotency check, so an unseen page means re-POSTed edges. Returns `[]` on
+ * error (worst case a duplicate POST): a lost write-side edge is cosmetic,
+ * unlike the read path in `resolve-stories.js`, where it drops a gate.
  *
  * @param {{ gh: object, owner: string, repo: string, issueNumber: number, paginate?: Function }} opts
  * @returns {Promise<number[]>} Database ids of the issues that currently block `issueNumber`.
@@ -74,11 +45,7 @@ async function fetchExistingBlockedBy({
 }
 
 /**
- * Set native GitHub "blocked by" dependency edges for a single issue.
- *
- * For each entry in `blockerInternalIds`, checks whether the edge already
- * exists and POSTs only the missing ones. Every individual POST failure is
- * caught, logged as a warning, and counted — the function never throws.
+ * POST only the missing edges for one issue; never throws.
  *
  * @param {{
  *   gh: object,
@@ -108,9 +75,7 @@ async function addBlockedByEdges({
   });
   const existingSet = new Set(existing);
 
-  // Partition up front so the skip count is deterministic regardless of the
-  // concurrent POST dispatch order, then POST only the missing edges in
-  // parallel under a modest cap.
+  // Partition first so the skip count doesn't depend on POST ordering.
   const missing = blockerInternalIds.filter((id) => !existingSet.has(id));
   const skipped = blockerInternalIds.length - missing.length;
 
@@ -145,16 +110,8 @@ async function addBlockedByEdges({
 }
 
 /**
- * Translate a Story's `depends_on` slug list into native GitHub "blocked
- * by" dependency edges, given the slug→issueNumber map from the reconciler
- * state and a `getTicket` hook to resolve database ids.
- *
- * Iterates every Story that has a non-empty `dependsOn` array; for each
- * depended-on slug, resolves the blocker's issue number (via the slug map),
- * then resolves the blocker's database id via `getTicket`, and calls
- * `addBlockedByEdges`. Any failure at any step is caught, logged as a
- * warning, and reflected in the returned summary — the function never
- * throws.
+ * For each Story's `dependsOn` slugs, resolve blocker issue number (slug map)
+ * then db id (`getTicket`), and add the edges. Never throws.
  *
  * @param {{
  *   stories: Array<{ slug: string, dependsOn?: string[] }>,
@@ -184,11 +141,7 @@ export async function applyBlockedByDependencies({
   let edgesFailed = 0;
   let storiesProcessed = 0;
 
-  // Process each story's GET + its POST batch under one bounded concurrentMap
-  // so the per-story round-trips overlap. Each mapper returns its own counter
-  // contribution; we sum them after the pass. The bodies swallow their own
-  // errors (per-edge try/catch + the non-fatal contract), so concurrentMap
-  // never sees a rejection and the no-throw guarantee is preserved.
+  // Mappers swallow their own errors, so concurrentMap never rejects.
   const perStory = await concurrentMap(
     stories,
     async (story) => {

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

@@ -1,30 +1,14 @@
 /**
- * GitHub Provider — shared "add issue to the Projects V2 board" helper.
- *
- * Story #3822 — single source of truth for the post-create board-add
- * step. Issues created through any create path (`createTicket`,
- * `createIssue` — which backs `/mandrel-plan` persist and the `/mandrel-plan`
- * Phase 4 Epic open) must land on the configured Projects V2 board
- * without relying on GitHub's "Auto-add to project" built-in workflow,
- * which is off by default on fresh boards and cannot be enabled via API.
- *
- * Contract:
- *   - **No-op when no project number resolves** — returns
- *     `{ added: false, reason: 'no-project-number' }` without touching
- *     the network.
- *   - **Non-fatal** — a failed add warns and returns
- *     `{ added: false, reason: 'error' }`; it never throws, so issue
- *     creation always survives a board hiccup.
- *   - **Idempotent** — the underlying `addProjectV2ItemById` mutation
- *     returns the existing item when the issue is already on the board,
- *     so re-running the helper is safe.
+ * GitHub Provider — post-create "add issue to the Projects V2 board" step.
+ * Needed because GitHub's auto-add workflow is off on fresh boards and can't
+ * be enabled via API. Never throws (issue creation survives a board failure)
+ * and is idempotent (the mutation returns an existing item).
  */
 
 import { Logger } from '../../lib/Logger.js';
 
 /**
- * Add an issue (by GraphQL `node_id`) to the configured Projects V2
- * board.
+ * No project number → no-op without network.
  *
  * @param {{
  *   nodeId: string|null|undefined,

package/.agents/scripts/providers/github/branch-protection.js

@@ -1,33 +1,14 @@
 /**
- * GitHub Provider — BranchProtectionGateway.
- *
- * Owns `getBranchProtection` / `setBranchProtection` against
- * `/repos/{owner}/{repo}/branches/{branch}/protection`. Also exports the
- * shared `isNotFoundError` predicate that `branchExists` reuses on the
- * parent provider — keeping the 404-classification logic single-sourced.
- *
- * Extracted from `../github.js` in Story #2462 / Task #2478. Public
- * surface on `GitHubProvider` is unchanged — both branch-protection
- * methods delegate here.
- *
- * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ * GitHub Provider — BranchProtectionGateway, plus the shared
+ * `isNotFoundError` predicate.
  */
 
 import { withTransientRetry } from './errors.js';
 import { parseApiJson } from './request-helpers.js';
 
 /**
- * Detect a 404 across both error surfaces:
- *
- *   - `gh-exec`-classified errors land as `GhNotFoundError`
- *     (`err.name === 'GhNotFoundError'`); the underlying stderr may carry
- *     "HTTP 404" / "not found" / "Resource not accessible".
- *   - The legacy `GithubHttpClient` produced `Error('... failed (404): ...')`
- *     strings; some tests still throw those (and submodules that still
- *     delegate to the old transport do too).
- *
- * Used by `getBranchProtection` (distinguishes "no rule exists" from
- * transport failures) and `branchExists` on the parent provider.
+ * 404 across `GhNotFoundError`, `HTTP 404`/"not found" stderr, and the
+ * legacy `failed (404)` message shape some callers still throw.
  */
 export function isNotFoundError(err) {
   if (!err) return false;
@@ -39,7 +20,6 @@ export function isNotFoundError(err) {
     /HTTP 404/i.test(stderr) ||
     /HTTP 404/i.test(message) ||
     /\bnot found\b/i.test(stderr) ||
-    // gh-exec carries the failing code on err.code for the test mock path.
     err?.code === 404
   );
 }
@@ -55,9 +35,8 @@ export class BranchProtectionGateway {
   }
 
   /**
-   * Inspect branch-protection state. A 404 means "no protection rule
-   * exists"; any other error propagates so the caller can distinguish
-   * "intentionally unprotected" from "transport failure."
+   * 404 → `{ enabled: false }`; other errors propagate so "unprotected" and
+   * "transport failure" stay distinct.
    *
    * @field-manifest GET /repos/{owner}/{repo}/branches/{branch}/protection:
    *                 required_status_checks, enforce_admins,
@@ -78,12 +57,9 @@ export class BranchProtectionGateway {
   }
 
   /**
-   * Set (create or merge) branch protection on `branch`. Additive on the
-   * required-status-check `contexts` list (preserves operator-added
-   * contexts), and honours optional behaviour-shifting overrides
-   * (`enforceAdmins`, `requiredApprovingReviewCount`) so the consumer-
-   * facing bootstrap can promote the framework's hands-off-pipeline
-   * stance without silently flipping operator-tuned values.
+   * Create or merge protection. `contexts` are added, never removed; other
+   * operator-tuned values are kept unless `enforceAdmins` /
+   * `requiredApprovingReviewCount` explicitly override them.
    *
    * Returns `{ created, added, existing }`.
    *
@@ -109,9 +85,6 @@ export class BranchProtectionGateway {
       ? (current.raw?.required_status_checks?.contexts ?? [])
       : [];
 
-    // Additive merge: keep every context the operator already configured
-    // and append only those the prGate suite contributes that are not yet
-    // present.
     const merged = [...existingContexts];
     const added = [];
     for (const ctx of contexts) {
@@ -121,9 +94,6 @@ export class BranchProtectionGateway {
       }
     }
 
-    // Decide whether to override behaviour-shifting fields. Explicit
-    // `undefined` from legacy callers falls through to the operator's
-    // existing values (or the create-from-scratch defaults).
     const overrideEnforceAdmins = typeof opts?.enforceAdmins === 'boolean';
     const overrideApprovalCount =
       typeof opts?.requiredApprovingReviewCount === 'number';
@@ -139,8 +109,7 @@ export class BranchProtectionGateway {
 
     let prReviews;
     if (overrideApprovalCount) {
-      // Preserve operator-set review flags (dismiss-stale, code-owners,
-      // etc.) — only the count is promoted.
+      // Keep operator review flags; only the count is promoted.
       const baseReviews = current.enabled
         ? (current.raw?.required_pull_request_reviews ?? {})
         : {};
@@ -154,8 +123,7 @@ export class BranchProtectionGateway {
         : null;
     }
 
-    // PUT requires every top-level field in the body — null disables a
-    // section.
+    // PUT requires every top-level field; null disables a section.
     const body = current.enabled
       ? {
           required_status_checks: {

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

@@ -1,18 +1,6 @@
 /**
- * GitHub Provider — per-instance ticket cache.
- *
- * One bare `Map<id, { ticket, insertedAt }>` scoped to the lifetime of a
- * single `GitHubProvider`, shared by dispatcher, reconciler, and cascade.
- * The outer TTL wrapper is deliberately omitted because `peekFresh` already
- * bounds entries by a caller-supplied `maxAgeMs`, and every other reader
- * trusts the ticket mutators (`updateTicket` / `postComment`) to call
- * `invalidate` explicitly.
- *
- * Surface is intentionally narrow: only the methods the provider itself
- * reaches for live here (`has` / `peek` / `peekFresh` / `set` /
- * `primeIfAbsent` / `primeMany` / `invalidate`).
- *
- * Extracted from `../github.js` in Story #1846 / Task #1858.
+ * GitHub Provider — per-instance ticket cache. No TTL: `peekFresh` bounds age
+ * per call, and mutators invalidate explicitly.
  *
  * @param {{ now?: () => number }} [opts]
  * @returns {{

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

@@ -1,30 +1,12 @@
 /**
- * GitHub Provider — CommentGateway.
- *
- * Owns issue-comment CRUD against `/repos/{owner}/{repo}/issues/.../comments`.
- * `postComment` is the structured-comment writer (it prepends the visible
- * type-badge); the `<!-- ap:structured-comment ... -->` marker is added by
- * the upstream `upsertStructuredComment` ticketing helper before the body
- * lands here.
- *
- * Extracted from `../github.js` in Story #2462 / Task #2480. `postComment`,
- * `getTicketComments`, and `deleteComment` on `GitHubProvider` all delegate
- * here. Story #5008 dropped the repo-wide `getRecentComments` feed — the
- * telemetry dashboard that read it was retired and nothing else polls a
- * cross-issue comment stream.
- *
- * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ * GitHub Provider — CommentGateway: issue-comment CRUD. The structured
+ * marker is added upstream by `upsertStructuredComment`; this layer adds only
+ * the visible type badge.
  */
 
 import { paginateRest, parseApiJson } from './request-helpers.js';
 
-// Structured-comment badge — preserved verbatim from the legacy
-// `./github/comments.js`. The upstream `upsertStructuredComment` ticketing
-// helper prepends the `<!-- ap:structured-comment ... -->` marker before
-// the body reaches `postComment`; this badge is the visible header
-// consumers (Slack notifier, dashboard) grep for. Keeping the emoji + bold
-// marker stable is what makes the round-trip with structured-comment
-// detection work across the rewrite.
+// Visible headers downstream consumers grep for — keep them byte-stable.
 const TYPE_BADGES = {
   progress: '🔄 **Progress**',
   friction: '⚠️ **Friction**',
@@ -48,10 +30,7 @@ export class CommentGateway {
   }
 
   /**
-   * All comments on a single ticket. Used by the upstream
-   * `findStructuredComment` ticketing helper, which greps each comment
-   * body for the `<!-- ap:structured-comment type="..." -->` marker — so
-   * the per-comment `body` field must round-trip verbatim.
+   * `body` must round-trip verbatim: structured-comment lookup greps it.
    *
    * @field-manifest /repos/{owner}/{repo}/issues/{n}/comments:
    *                 id, body, created_at, user
@@ -63,11 +42,6 @@ export class CommentGateway {
     );
   }
 
-  /**
-   * Delete a comment by id. Called by `upsertStructuredComment` before
-   * posting the replacement, so the in-place semantics hold even though
-   * the underlying GitHub API has no native upsert.
-   */
   async deleteComment(commentId) {
     await this._gh.api({
       method: 'DELETE',
@@ -76,13 +50,8 @@ export class CommentGateway {
   }
 
   /**
-   * Post a comment on an issue. When `payload.type` matches a known
-   * structured-comment kind, prepend the visible type-badge so operators
-   * see the same header the old client produced.
-   *
-   * Accepts either `{ body, type }` (canonical) or a bare string (legacy
-   * shape exercised by `tests/lib/github-provider.test.js` and a handful
-   * of direct callers under `notify.js`).
+   * Accepts `{ body, type }` or a bare string; a known `type` gets its badge
+   * prepended.
    *
    * @field-manifest POST /repos/{owner}/{repo}/issues/{n}/comments:
    *                 id (returned for the caller's `commentId`)
@@ -99,8 +68,6 @@ export class CommentGateway {
       body: { body },
     });
     const comment = parseApiJson(result);
-    // Posting a comment mutates the ticket's comment thread. Invalidate so
-    // the next `getTicketComments` / `getTicket` reflects the new comment.
     if (typeof this._hooks.invalidateTicket === 'function') {
       this._hooks.invalidateTicket(ticketId);
     }

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

@@ -1,18 +1,6 @@
 /**
- * GitHub Provider — gateway composition helper.
- *
- * Pulled out of `../github.js` in Story #2462 / Task #2481 so the parent
- * file can stay under the thin-composer LOC ceiling. This module owns the
- * mechanical wiring: it builds each gateway, threads the hooks that
- * cross-link them, and constructs the shared `_ctx` object the projects-v2
- * shim reads from.
- *
- * The provider holds the public surface; this helper holds the wiring.
- * Splitting the two keeps the composer file readable and reviewable as a
- * delegation manifest rather than a constructor-shaped wall of new-up
- * calls.
- *
- * @see Story #2462 — Split GitHubProvider god class into seven composed gateways.
+ * GitHub Provider — gateway wiring: builds each gateway, cross-links them
+ * via hooks, and builds the shared `_ctx` the projects-v2 shim reads.
  */
 
 import { BranchProtectionGateway } from './branch-protection.js';
@@ -26,11 +14,7 @@ import * as projects from './projects-v2-graphql.js';
 import { SubIssueGateway } from './sub-issues.js';
 import { TicketGateway } from './tickets.js';
 
-/**
- * Wire every gateway onto `provider` and attach the shared `_ctx` object.
- * Mutates the provider in place — the constructor passes `this` in and
- * lets this helper own the wiring decisions.
- */
+/** Mutates `provider` in place. */
 export function composeGateways(provider) {
   const p = provider;
   const ghDeps = { gh: p._gh, owner: p.owner, repo: p.repo };

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

@@ -1,35 +1,17 @@
 /**
- * GitHub Provider — error classifier + sub-issues GraphQL shape.
+ * GitHub Provider — error classifier, the shared transient-retry loop, and
+ * the 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 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` 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.
+ * `classifyGithubError` buckets errors as `feature-disabled` / `permission` /
+ * `transient` / `permanent`. Transient rules run before the 401/403
+ * permission rule because a secondary rate limit arrives as HTTP 403.
  */
 
 /**
- * Needles that mean "this API surface does not exist here", not "this call
- * failed". Every one names a *schema* fact — an absent GraphQL field, a
- * disabled feature — so a match is a settled answer no retry can improve.
- *
- * The bare `sub-issues` needle used to sit in this list and had to go: it
- * matches the endpoint's own name, so any error that merely *mentions* the
- * surface classified as `feature-disabled`. A secondary rate limit delivered
- * as `HTTP 403: API rate limit exceeded while fetching sub-issues` is the live
- * case — genuinely transient, but bucketed here it bypassed
- * `withTransientRetry` entirely and the Epic rollup read the burst as "this
- * repo has no sub-issues", degrading to the body checklist on a read that
- * would have succeeded a second later. The narrower `subissues` spellings
- * below still catch the real schema errors, because GraphQL names the field
- * without the hyphen.
+ * Schema facts (absent field, disabled feature) no retry can change. Never
+ * add a bare `sub-issues` needle: it matches the endpoint name, so a rate
+ * limit "while fetching sub-issues" would skip retry; GraphQL spells the
+ * field without the hyphen.
  */
 const FEATURE_DISABLED_MESSAGES = [
   'feature not available',
@@ -37,9 +19,7 @@ const FEATURE_DISABLED_MESSAGES = [
   "field 'subissues'",
   'field "subissues"',
   'subissues is not available',
-  // The field, never the endpoint. `<x> field` cannot appear in "while
-  // fetching sub-issues", which is what makes these safe to keep after the
-  // bare needle's removal.
+  // `<x> field` names the field, never the endpoint.
   'subissues field',
   'sub_issues field',
   'sub-issues field',
@@ -69,27 +49,12 @@ const TRANSIENT_MESSAGES = [
 
 const PERMISSION_MESSAGES = ['unauthorized', 'forbidden', 'permission'];
 
-// Network/connectivity blips that the gh-CLI path surfaces on `err.stderr`
-// (Go HTTP errors, e.g. `dial tcp ...: i/o timeout`) and the direct `fetch`
-// path surfaces as `TypeError: fetch failed` with the real reason on
-// `err.cause` (e.g. `ETIMEDOUT`, `ENOTFOUND`). Folded in from the former
-// `transient-retry.js` predicate (Story #4298) so the single canonical
-// classifier retries the **union** of transient HTTP statuses/codes AND
-// transient network errors. The `\b50[234]\b` alternative also catches a
-// bare 502/503/504 surfaced only in an error message string (no `.status`).
+// Connectivity blips: gh-CLI puts Go HTTP errors on stderr; `fetch` puts the
+// reason on `err.cause`. `\b50[234]\b` catches a status present only in text.
 const TRANSIENT_NETWORK_RE =
   /i\/o timeout|dial tcp|TLS handshake timeout|connection reset|connection refused|temporary failure|could not resolve host|no such host|network is unreachable|socket hang up|fetch failed|ConnectTimeoutError|UND_ERR_CONNECT_TIMEOUT|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|\b50[234]\b/i;
 
-/**
- * True when an error looks like a retryable network/connectivity blip.
- * Scans the union of fields both transport paths populate (`stderr`,
- * `message`, `code`, and the nested `cause.message` / `cause.code` the
- * `fetch` path uses). Module-private — folded in from the former
- * `transient-retry.js` predicate (Story #4298) and consumed only by
- * `classifyGithubError` below; its behavior is exercised through that public
- * classifier rather than as a standalone export (keeps the dead-export gate
- * green — nothing outside this module imports it).
- */
+/** Scans stderr, message, code and `cause.*` from both transport paths. */
 function isTransientNetworkError(err) {
   const hay = [
     err?.stderr,
@@ -112,11 +77,7 @@ function matchesAny(haystack, needles) {
 const GH_STDERR_STATUS_RE = /\bHTTP (\d{3})\b/i;
 
 /**
- * The captured `gh` stderr, or `''` when the error carries none.
- *
- * Its own function so {@link extractErrorFields} keeps the cyclomatic weight it
- * had before stderr became a classification input — the field is read twice
- * there, and inlining the guard twice is what pushed the CRAP ratchet.
+ * Separate function to keep {@link extractErrorFields}'s complexity down.
  *
  * @param {unknown} err
  * @returns {string}
@@ -126,13 +87,7 @@ function stderrText(err) {
 }
 
 /**
- * Recover the HTTP status from a `gh`-CLI failure's stderr.
- *
- * The `fetch` transport sets `err.status`; the `gh` transport does not — it
- * has only an exit code, and puts the status in the text it printed. Without
- * this, every `gh`-path failure reached the status rules as `undefined` and a
- * 403 or a 429 was indistinguishable from an unclassifiable error (Story
- * #5210).
+ * The `gh` transport has no `err.status`, only the status printed on stderr.
  *
  * @param {unknown} stderr
  * @returns {number|undefined}
@@ -144,19 +99,9 @@ function statusFromStderr(stderr) {
 }
 
 /**
- * Extract `{ lower, detail, status, code }` from an error in the shape
- * `gh-exec` throws. Pure — exported style for unit-testability without
- * instantiating the provider. Defensive on shape: errors arrive as `Error`
- * objects, plain `{message,status,code}` bags, or non-Errors stringified into
- * `String(err)`.
- *
- * `lower` is the message alone. `detail` is the message **plus** any captured
- * `stderr`, and is what the keyword rules read: on the `gh` path the message
- * is the classified summary (`gh-exec: gh exited with code 1`) and every
- * actionable word — the status line, `secondary rate limit`, the missing
- * GraphQL field — lives only on stderr. Matching the keyword lists against the
- * message alone is what flattened a retryable 403 to `permanent` and let the
- * Epic rollup treat a rate-limit burst as a settled answer (Story #5210).
+ * Pure. `detail` is message + stderr and is what keyword rules must read: on
+ * the `gh` path the message is only `gh exited with code 1` and every
+ * actionable word (status, rate limit, missing field) lives on stderr.
  */
 export function extractErrorFields(err) {
   const message = typeof err.message === 'string' ? err.message : String(err);
@@ -164,8 +109,6 @@ export function extractErrorFields(err) {
   const lower = message.toLowerCase();
   return {
     lower,
-    // Unconditional concatenation: with no stderr this is the message plus a
-    // trailing space, which every `includes` rule below reads identically.
     detail: `${lower} ${stderr.toLowerCase()}`,
     status:
       typeof err.status === 'number' ? err.status : statusFromStderr(stderr),
@@ -173,19 +116,16 @@ export function extractErrorFields(err) {
   };
 }
 
-/** Pure predicate: HTTP status that signals "transient — retry-eligible". */
 export function isTransientStatus(status) {
   if (status === 429) return true;
   return typeof status === 'number' && status >= 500;
 }
 
-/** Pure predicate: error code/message signals "transient — retry-eligible". */
 export function isTransientByCodeOrMessage(code, lower) {
   if (TRANSIENT_CODES.has(code)) return true;
   return matchesAny(lower, TRANSIENT_MESSAGES);
 }
 
-/** Pure predicate: HTTP status / message signals "permission denied". */
 export function isPermissionSignal(status, lower) {
   if (status === 401 || status === 403) return true;
   return matchesAny(lower, PERMISSION_MESSAGES);
@@ -193,52 +133,18 @@ export function isPermissionSignal(status, lower) {
 
 export function classifyGithubError(err) {
   if (!err) return 'permanent';
-  // `GhExecTimeoutError` (from `lib/gh-exec.js`) carries a message of the
-  // shape `"gh-exec: gh <args> exceeded <N>ms"` — no transient keyword and
-  // no `.status` / `.code`. Match by `err.name` to avoid a circular import
-  // between this module and `lib/gh-exec.js`. Story #2860.
+  // Matched by name to avoid a circular import with `lib/gh-exec.js`.
   if (err.name === 'GhExecTimeoutError') return 'transient';
-  // Every keyword rule below reads `detail` (message + stderr), never `lower`
-  // alone: the `gh` transport carries its reason exclusively on stderr, so a
-  // message-only match sees nothing but the exit code. Rule ORDER is
-  // load-bearing and unchanged — a secondary rate limit is delivered as HTTP
-  // 403, so the transient rules must stay ahead of the permission rule or it
-  // would bucket as 'permission' and never retry.
+  // Rule order is load-bearing: every transient rule precedes permission.
   const { detail, status, code } = extractErrorFields(err);
   if (matchesAny(detail, FEATURE_DISABLED_MESSAGES)) return 'feature-disabled';
   if (isTransientStatus(status)) return 'transient';
   if (isTransientByCodeOrMessage(code, detail)) return 'transient';
-  // Union with the former `transient-retry.js` predicate (Story #4298):
-  // retry on network/connectivity blips the status/code checks above miss
-  // (e.g. a `dial tcp ... i/o timeout` on `err.stderr` from the gh-CLI path,
-  // or `ECONNREFUSED` / `ENETUNREACH`). Checked before the permission rule so
-  // a transient network failure never masquerades as a permanent denial.
   if (isTransientNetworkError(err)) return 'transient';
   if (isPermissionSignal(status, detail)) return 'permission';
   return 'permanent';
 }
 
-// ---------------------------------------------------------------------------
-// Transient-retry helper (Story #2852; unified in Story #4298)
-// ---------------------------------------------------------------------------
-//
-// The single canonical `withTransientRetry` for the GitHub provider. Story
-// #4298 collapsed the former two divergent same-named implementations (this
-// one + the network-only one in the deleted `transient-retry.js`) into this
-// one primitive. Its default classifier (`classifyGithubError`) is the
-// **union** predicate — it retries on transient HTTP statuses/codes AND on
-// transient network/connectivity errors — so every former consumer of either
-// module keeps (or gains) its prior retry coverage with no shim.
-//
-// 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 /mandrel-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.
-
 export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
   maxAttempts: 6,
   baseDelayMs: 500,
@@ -247,14 +153,8 @@ export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
 });
 
 /**
- * Run `fn` with jittered exponential backoff on transient GitHub errors.
- * `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.
- *
- * `sleep` and `random` are injectable so tests can drive deterministic
- * retry paths without real-world timing.
+ * The provider's single retry primitive: jittered exponential backoff; only
+ * a `'transient'` classification retries, anything else throws at once.
  *
  * @template T
  * @param {() => Promise<T>} fn
@@ -310,9 +210,6 @@ export async function withTransientRetry(fn, opts = {}) {
   throw lastErr;
 }
 
-// ---------------------------------------------------------------------------
-// Sub-issues GraphQL shapes
-// ---------------------------------------------------------------------------
 export const SUB_ISSUES_QUERY = `query($id: ID!, $cursor: String) {
   node(id: $id) {
     ... on Issue {