mandrel 2.31.0 → 2.32.0

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -109,7 +109,7 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 **Slug format**: \`^[a-z0-9][a-z0-9-]*$\` — hyphen-case only. Underscores are rejected by the validator.
 
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
-\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\` / \`wide\` / \`reason_to_exist\` / \`estimated_test_files\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
+\`body\` is either the serialized markdown **string** (the section format below) or a **structured object** carrying the same fields (\`goal\`, optional \`slicing\` / \`spec\`, \`changes\`, optional \`non_goals\` / \`wide\` / \`reason_to_exist\`) — persist parses either shape and serializes the canonical markdown itself, so you never need to read \`story-body.js\` or hand-assemble the markdown (the \`stories.template.json\` file emitted next to the plan-context envelope is a ready-to-fill structured-object skeleton). Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
@@ -151,7 +151,6 @@ The **persisted** \`body\` renders these markdown sections (in order) — you au
 - **acceptance** (top-level array on the ticket object): Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
 - **verify** (top-level array on the ticket object): Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
 - **reason to exist** (REQUIRED, encoded as the \`reason_to_exist\` field of the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): One sentence stating the single coherent reason this Story exists, distinct from its broader \`## Goal\` prose. Every Story MUST carry a non-empty \`reason_to_exist\`; it is the machine-checkable form of the cohesion rule (**one Story = one coherent change with one reason to exist**) and the \`epic-plan-consolidate\` critic flags any Story whose body carries no non-empty reason to exist. Encode it as \`<!-- meta: {"reason_to_exist": "..."} -->\`.
-- **estimated_test_files** (optional, encoded in the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
 - **Observed-behavior claims open with \`Current state (verified <date>)\`.** Any Spec claim about how the codebase behaves today MUST open with that preamble (e.g. \`Current state (verified 2026-07-17): …\`) so a reader can tell a verified observation from an assumption, and can tell when the observation went stale.
 - **Intent-then-proxy acceptance shape.** When an acceptance item verifies through a proxy check (a grep, a file-exists probe, an exit-code test), state the intent clause before the proxy check — what outcome the check stands in for — so the proxy never becomes the goal (e.g. "the workflow names hygiene findings as re-author input: \`grep -n "textHygiene" …\` exits 0").
 - **Slicing checkpoints are one line each.** Each \`## Slicing\` checkpoint is a single line naming the checkpoint; implementation detail lives in \`## Spec\`, never duplicated into Slicing. A Slicing section outweighing its Spec is a defect the text-hygiene lint flags.
@@ -171,7 +170,7 @@ The Story is executed by a frontier-model deliverer that reads the codebase itse
 
 #### DETERMINISTIC BODY-FORMAT LINTS — author lint-clean by construction:
 
-Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. The two auto-fixable rules (\`changes-path-entry-shape\`, \`verify-tier-suffix\`) also emit the corrected form in the dry-run failure output, but authoring them right up front avoids the round-trip entirely.
+Persist enforces the deterministic body-format rules below and **rejects** an authored body that violates any of them. Author every Story to satisfy all of them on the FIRST draft — each rule is stated example-first so there is nothing to discover by trial-and-error. \`verify-tier-suffix\` is the one rule persist repairs for you: when the tier is unambiguously inferable from the command, persist appends it and proceeds; when it is not, the entry is still rejected and you must choose the tier. \`changes-path-entry-shape\` emits the corrected form in the dry-run failure output but is never applied for you.
 
 ${bodyFormatLintChecklist}
 
@@ -231,35 +230,38 @@ Declaring \`wide\` with a non-empty reason **lifts the hard session-mass rejecti
 
 #### UI / TESTID INVARIANCE (per CLAUDE.md safety rule):
 
-- Stories that touch UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, components folders) MUST end \`changes\` with one of:
-  - \`data-testid invariance: <list of testids that MUST be preserved>\`, or
-  - \`data-testid changes: <old> -> <new>\` paired with a corresponding \`tests/e2e/*.spec.ts\` edit in the same story or a depends_on Story.
+Every \`changes[]\` entry is a \`{ path, assumption }\` object — a prose bullet there is rejected by the parser, so the testid contract is carried where prose belongs:
+
+- Stories that touch UI (\`*.tsx\`, \`*.astro\`, \`*.svelte\`, \`*.vue\`, components folders) MUST carry the testid contract as a top-level \`acceptance[]\` item, one of:
+  - \`"data-testid invariance: <list of testids that MUST be preserved>"\`, or
+  - \`"data-testid changes: <old> -> <new>, with the matching tests/e2e/*.spec.ts selector updated"\` — paired with that \`tests/e2e/*.spec.ts\` file in \`changes[]\`, in the same Story or a depends_on Story.
+- State the preserved-testid set in \`## Non-Goals\` prose as well when the Story deliberately renames nothing.
 - Renaming a testid without the matching e2e edit is FORBIDDEN.
 
 #### BRAND / COPY / STYLE WORK:
 
-- Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of \`docs/style-guide.md\` in \`acceptance\` (e.g. \`"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]\`). If \`docs/style-guide.md\` does not exist or has no relevant section, state that explicitly: \`"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in the Epic body"]\`. Silence on style sourcing is a smell.
+- Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of \`docs/style-guide.md\` in \`acceptance\` (e.g. \`"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]\`). If \`docs/style-guide.md\` does not exist or has no relevant section, state that explicitly: \`"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in the plan seed"]\`. Silence on style sourcing is a smell.
 
-### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when the Acceptance Spec has \`new\`-disposition rows):
-The Acceptance Spec's AC table (columns \`AC ID | Outcome | Feature File | Scenario | Disposition\`) tags each row's \`Disposition\` with one of \`new | updated | unchanged\`. A \`new\` row names a \`.feature\` file + scenario that does NOT yet exist on \`main\`. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file. (These Gherkin \`.feature\` files are BDD artifacts, unrelated to any ticket tier.)
+### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when your plan verifies against a scenario that does not exist yet):
+The plan-context envelope's \`bddScenarios\` field is the index of Gherkin scenarios that **already exist on \`main\`** — one row per scenario, carrying its \`.feature\` file path, line, scenario title and tags. It is the live signal for this rule: a \`.feature\` path + scenario your plan needs but that appears in no \`bddScenarios\` row does not exist yet. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file.
 
-When the Acceptance Spec contains **one or more \`Disposition: new\` rows**, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create the \`.feature\` files with \`@skip\`-tagged scenarios BEFORE any implementation Story runs:
+When **one or more** \`.feature\` scenarios your plan verifies against are absent from \`bddScenarios\`, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create those \`.feature\` files with \`@skip\`-tagged scenarios BEFORE any implementation Story runs:
 
 - **goal**: contains the literal token \`bdd-scaffold\` (e.g. "bdd-scaffold: create the @skip-tagged feature files the implementation Stories verify against").
 - **depends_on**: EMPTY (\`[]\`) — it runs first, in wave 0.
-- **changes**: one entry per distinct \`.feature\` file named in a \`new\` row, each \`{ "path": "<feature file path>", "assumption": "creates" }\`.
+- **changes**: one entry per distinct absent \`.feature\` file, each \`{ "path": "<feature file path>", "assumption": "creates" }\`.
 - **acceptance**: MUST assert (a) every new \`.feature\` file exists AND (b) every new scenario within them carries an \`@skip\` tag. Keep these observable (a grep/validate command exits 0, a file exists at a path).
 - **verify**: a grep/validate command (tier \`validate\`), NOT an e2e runner — verifying that a file exists with the required tags needs no browser/playwright run. Example: \`grep -rL '@skip' tests/features/<area>/*.feature (validate)\` paired with an existence check.
 - Each implementation Story whose \`verify[]\` references one of these scaffolded \`.feature\` paths MUST \`depends_on\` the scaffold Story (so the scaffold lands in an earlier wave). Omitting the link trips the soft \`missing-bdd-scaffold\` validator finding.
 
-When the Acceptance Spec contains **zero \`new\`-disposition rows** (every row is \`updated\` or \`unchanged\`), do NOT emit a scaffold Story — there is nothing to create.
+When every scenario your plan verifies against is already present in \`bddScenarios\`, do NOT emit a scaffold Story — there is nothing to create.
 
 ### SCOPE-OVERLAP FLAGGING (docs/runbook downstream of config work):
-When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same Epic whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story's top-level \`acceptance\` array by appending an item of the form:
+When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same plan whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story's top-level \`acceptance\` array by appending an item of the form:
 "Scope verification note: this story's deliverable may already be satisfied by Story #<slug-or-id>'s AC — before implementing, \`git diff main -- <path>\` against the upstream Story branch and confirm whether a substantive edit is still required, or whether only a cross-reference remains."
 This prevents the executing agent from redoing work the upstream Story already merged.
 
-CRITICAL: Dependencies should follow execution blockers. Stories attach directly to the Epic — never emit a 'parent_slug' field.
+CRITICAL: Dependencies should follow execution blockers. There is no parent ticket — never emit a 'parent_slug' field.
 IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depends_on\` (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
 
 ### REVIEWABILITY BUDGET (Story #2798):

package/.agents/scripts/lib/ticket-body-sections.js

@@ -53,11 +53,10 @@ export const TICKET_BODY_SECTIONS = Object.freeze({
 export const ACCEPTANCE_TABLE_HEADING = '## Acceptance Table';
 
 /**
- * Regex matching the Tech Spec's required opening heading (same variants
- * `spec-section-validator.js` accepts). Exported so it is the single
- * source of truth for this pattern — `spec-section-validator.js`,
- * `consolidation-precondition.js` all import
- * it rather than each carrying their own copy.
+ * Regex matching the Tech Spec's `## Delivery Slicing` heading, tolerating
+ * the `Delivery ` qualifier and casing variants. Exported so it is the single
+ * source of truth for this pattern — `consolidation-precondition.js` imports
+ * it rather than carrying its own copy.
  */
 export const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;
 

package/.agents/scripts/lib/worktree/lifecycle/merge-reachability.js

@@ -3,23 +3,25 @@
  *
  * The "is the worktree's work integrated upstream?" half of
  * `isSafeToRemove`. Runs the two-phase reachability gate the parent
- * documents: primary `merge-base --is-ancestor HEAD epicRef`, and a
- * fallback `git log --grep=resolves #<storyId>` against the Epic ref when
- * the ancestry check returns "not an ancestor".
+ * documents: primary `merge-base --is-ancestor HEAD baseRef`, and a
+ * `git cherry` patch-equivalence fallback when the ancestry check returns
+ * "not an ancestor".
  *
  * The fallback exists because a post-merge rebase or force-push can drop
- * the local branch ref off the merged tip — the `(resolves #N)` token on
- * the Epic's `--no-ff` merge commit (emitted by
- * `story-close/merge-runner.js`) is the durable proof the Story was
- * integrated.
+ * the local branch ref off the merged tip, so SHA reachability alone
+ * under-reports integration.
+ *
+ * A third phase used to sit between the two: a `git log --merges
+ * --grep=resolves #<storyId>` probe for the `(resolves #N)` token on the
+ * Epic's `--no-ff` merge commit. Story #5006 removed it — v2 lands every
+ * Story as a **squash** merge onto `main`, which never writes that token,
+ * and the `--no-ff` emitter (`story-close/merge-runner.js`) went with the
+ * Epic pipeline. The probe could only ever return `false`.
  *
  * Pure with respect to the supplied `ctx` bag; the only side effects are
  * the `gitSpawn` calls.
  */
 
-import { parseStoryBranch } from '../../git-utils.js';
-import { resolvesGrepArgs } from '../../orchestration/resolves-token.js';
-
 /**
  * Resolve a worktree's `HEAD` to a full commit SHA via
  * `git rev-parse HEAD` (run inside the worktree). Returns
@@ -70,37 +72,6 @@ export function checkHeadAncestor(ctx, headSha, epicRef) {
   };
 }
 
-/**
- * Predicate: did the Epic ref accumulate a `--no-ff` merge commit whose
- * subject names this Story (e.g. `... (resolves #1851)`)? Returns `true`
- * when the grep finds at least one matching merge commit, `false` when it
- * returns empty or fails.
- *
- * Returns `false` for branches that do not match the canonical
- * `story-<id>` shape — the merge-commit subject contract is only
- * guaranteed for story branches.
- *
- * @param {object} ctx
- * @param {string} branch Worktree branch (e.g. `story-1851`).
- * @param {string} epicRef Epic branch ref (e.g. `epic/1831`).
- * @returns {boolean}
- */
-export function hasMergeCommitForStory(ctx, branch, epicRef) {
-  const storyId = parseStoryBranch(branch);
-  if (storyId === null) return false;
-  const grep = ctx.git.gitSpawn(
-    ctx.repoRoot,
-    'log',
-    epicRef,
-    '--merges',
-    '-n',
-    '1',
-    '--pretty=%H',
-    ...resolvesGrepArgs(storyId),
-  );
-  return grep.status === 0 && grep.stdout.trim().length > 0;
-}
-
 /**
  * Predicate: are every commit on `branch` patch-equivalent to a commit
  * already on `epicRef`? Runs `git cherry <epicRef> <branch>` and returns
@@ -140,7 +111,7 @@ export function hasRebasedEquivalents(ctx, branch, epicRef) {
 }
 
 /**
- * Run the full three-phase merge-reachability gate. Returns the same
+ * Run the full two-phase merge-reachability gate. Returns the same
  * `{ safe, reason }` envelope `isSafeToRemove` does, so callers can chain
  * the verdict directly into the parent return value.
  *
@@ -165,9 +136,6 @@ export async function checkMergeReachability(ctx, wtPath, branch, epicRef) {
     };
   }
 
-  if (hasMergeCommitForStory(ctx, branch, epicRef)) {
-    return { safe: true, reason: 'merge-commit-reachable' };
-  }
   if (hasRebasedEquivalents(ctx, branch, epicRef)) {
     return { safe: true, reason: 'rebased-equivalents' };
   }

package/.agents/scripts/lib/worktree/lifecycle/reap.js

@@ -47,11 +47,10 @@ const WINDOWS_CWD_RE =
  * (branch advanced to a SHA still reachable from the Epic merge commit).
  *
  * When HEAD is no longer an ancestor (force-push that drops or rewrites
- * the merged tip), the function falls back to a `merge-commit-reachable`
- * check: search the Epic ref for a `--no-ff` merge commit whose subject
- * carries this Story's `(resolves #<id>)` token. Such a merge commit
- * proves the Story branch was integrated even though the current HEAD
- * has diverged, so the worktree is still safe to reap.
+ * the merged tip), the function falls back to a `rebased-equivalents`
+ * check: `git cherry` proves every commit on the branch is already
+ * upstream by patch-id even though the current HEAD has diverged, so the
+ * worktree is still safe to reap.
  *
  * `opts.epicBranch` is the integration / base ref the Story must already
  * be merged into (e.g. `main` or a plan-run branch).

package/.agents/scripts/lib/worktree-manager.js

@@ -54,9 +54,8 @@ export class WorktreeManager {
    * @param {(phase: 'worktree-create'|'bootstrap'|'install') => void} [opts.onPhase]
    *   Optional phase-boundary callback fired from `ensure()` just before each
    *   internal phase (git worktree add, bootstrap-file copy, dependency
-   *   install). Consumed by `story-init` to drive `phase-timer.mark()`
-   *   so `[phase-timing]` log lines attribute wall-clock correctly to the
-   *   sub-phases of worktree provisioning.
+   *   install), so a caller can attribute wall-clock to the sub-phases of
+   *   worktree provisioning.
    */
   constructor({
     repoRoot,

package/.agents/scripts/lint-label-vocabulary.js

@@ -38,8 +38,8 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-
 import { runAsCli } from './lib/cli-utils.js';
+import { walkFilesByExtension } from './lib/fs-walk.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -71,28 +71,6 @@ export const KNOWN_AXES = Object.freeze([
   'planning',
 ]);
 
-/**
- * Walk a directory tree synchronously, yielding absolute paths of files
- * matching `.md`. Mirrors the walker shape in `check-lifecycle-lint.js`.
- */
-function* walkMd(dir) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === 'ENOENT') return;
-    throw err;
-  }
-  for (const entry of entries) {
-    const p = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      yield* walkMd(p);
-    } else if (entry.isFile() && entry.name.endsWith('.md')) {
-      yield p;
-    }
-  }
-}
-
 /**
  * Resolve a mixed list of file/directory paths into the flat set of
  * markdown files to scan. Missing paths are silently skipped (the
@@ -116,7 +94,7 @@ function* resolveTargets(targets) {
     for (const entry of stat) {
       const p = path.join(target, entry.name);
       if (entry.isDirectory()) {
-        yield* walkMd(p);
+        yield* walkFilesByExtension(p, '.md');
       } else if (entry.isFile() && entry.name.endsWith('.md')) {
         yield p;
       }

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

@@ -6,10 +6,12 @@
  *
  * Polls the PR's required checks to a terminal state and auto-recovers
  * from `mergeStateStatus: BEHIND` (via bounded `gh pr update-branch`
- * calls) by delegating to the shared `watchPrToTerminal` primitive in
- * the lifecycle `Watcher` — the SAME loop the listener runs, so the CLI
- * and the bus path are byte-for-byte equivalent. No lifecycle bus is
- * created; this is a direct, synchronous watch with a real exit code.
+ * calls) by delegating to the `watchPrToTerminal` primitive in
+ * `lib/orchestration/pr-watch.js`. That primitive was shared with the
+ * `Watcher` bus listener until Story #5006 deleted it (nothing emitted at
+ * it); this CLI is now its only caller. Story #5024 retired the bus
+ * outright, so there is no bus to create — this is a direct, synchronous
+ * watch with a real exit code.
  *
  * Slow-vs-failed semantics (Story #4358):
  *   - GREEN — every required check terminal + green → exit 0, unless the
@@ -100,7 +102,7 @@ import {
   retireCiDigest,
   writeCiDigest,
 } from './lib/orchestration/ci-rerun-guard.js';
-import { watchPrToTerminal } from './lib/orchestration/lifecycle/listeners/watcher.js';
+import { watchPrToTerminal } from './lib/orchestration/pr-watch.js';
 import { enableAutoMergeWith } from './lib/orchestration/single-story-close/phases/auto-merge.js';
 import { sleep as defaultSleep } from './lib/util/poll-loop.js';
 

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

@@ -5,8 +5,8 @@
  * 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` /
- * `addSubIssue` / `removeSubIssue`) to call `invalidate` explicitly.
+ * 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` /

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

@@ -7,20 +7,16 @@
  * the upstream `upsertStructuredComment` ticketing helper before the body
  * lands here.
  *
- * Extracted from `../github.js` in Story #2462 / Task #2480. Public
- * surface on `GitHubProvider` is unchanged — `postComment`,
- * `getRecentComments`, `getTicketComments`, and `deleteComment` all
- * delegate 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.
  */
 
-import { withTransientRetry } from './errors.js';
-import {
-  defaultRetryWarn,
-  paginateRest,
-  parseApiJson,
-} from './request-helpers.js';
+import { paginateRest, parseApiJson } from './request-helpers.js';
 
 // Structured-comment badge — preserved verbatim from the legacy
 // `./github/comments.js`. The upstream `upsertStructuredComment` ticketing
@@ -51,24 +47,6 @@ export class CommentGateway {
     this._hooks = hooks;
   }
 
-  /**
-   * Recent comments across all issues in the repo (sorted newest first).
-   *
-   * @field-manifest /repos/{owner}/{repo}/issues/comments?sort=created:
-   *                 id, body, created_at, user, issue_url
-   */
-  async getRecentComments(limit = 100) {
-    const result = await withTransientRetry(
-      () =>
-        this._gh.api({
-          method: 'GET',
-          endpoint: `/repos/${this.owner}/${this.repo}/issues/comments?sort=created&direction=desc&per_page=${limit}`,
-        }),
-      { label: 'getRecentComments', onRetry: defaultRetryWarn },
-    );
-    return parseApiJson(result) ?? [];
-  }
-
   /**
    * All comments on a single ticket. Used by the upstream
    * `findStructuredComment` ticketing helper, which greps each comment

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

@@ -23,7 +23,6 @@ import { LabelGateway } from './labels.js';
 import { MergeMethodsGateway } from './merge-methods.js';
 import { ProjectBoardGateway } from './project-board.js';
 import * as projects from './projects-v2-graphql.js';
-import { PullRequestGateway } from './prs.js';
 import { SubIssueGateway } from './sub-issues.js';
 import { TicketGateway } from './tickets.js';
 
@@ -50,12 +49,6 @@ export function composeGateways(provider) {
     ghGraphql: (q, v, o) => p.graphql(q, v, o),
     cache: p._cache,
     classifyGithubError,
-    hooks: {
-      getTicket: (id, o) => p.getTicket(id, o),
-      getTickets: (id) => p.getTickets(id),
-      primeTicketCache: (t) => p.primeTicketCache(t),
-      invalidateTicket: (id) => p.invalidateTicket(id),
-    },
   });
   p.comments = new CommentGateway({
     ...ghDeps,
@@ -64,14 +57,6 @@ export function composeGateways(provider) {
   p.labels = new LabelGateway(ghDeps);
   p.branchProtection = new BranchProtectionGateway(ghDeps);
   p.mergeMethods = new MergeMethodsGateway(ghDeps);
-  p.pullRequests = new PullRequestGateway({
-    gh: p._gh,
-    hooks: {
-      getTicket: (id) => p.getTicket(id),
-      addItemToProject,
-      getProjectNumber,
-    },
-  });
   p.issues = new IssuesGateway({
     ...ghDeps,
     hooks: {

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