mandrel 2.0.0 → 2.2.0

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

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

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

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

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

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

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

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

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

@@ -3,7 +3,7 @@
  *
  * Owns the remaining read-side surface that did not belong to any of the
  * earlier six gateways: the raw GraphQL shim (`graphql` / `_ghGraphql`),
- * epic enumeration (`getEpics`, `getEpic`), repository-wide label scans
+ * epic reads (`getEpic`), repository-wide label scans
  * (`listIssuesByLabel`), branch existence probes (`branchExists`), and the
  * three-strategy sub-ticket aggregator (`getSubTickets`).
  *
@@ -151,16 +151,6 @@ export class IssuesGateway {
     }));
   }
 
-  /**
-   * Historical Epic enumeration surface. Stage 5 removed the Epic type from
-   * the taxonomy; callers that have not yet collapsed their planning corpus
-   * reads receive an empty list rather than querying a deleted label.
-   */
-  /* node:coverage ignore next */
-  async getEpics(_filters = {}) {
-    return [];
-  }
-
   /**
    * @field-manifest /repos/{owner}/{repo}/issues/{n}: number, id, node_id,
    *                 title, body, labels, state

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

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

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

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

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

@@ -8,13 +8,16 @@
  *
  * The gateway is constructed with a `{ gh, owner, repo, hooks }` object so
  * cross-gateway concerns can be threaded in without bloating the constructor
- * signature. Today the only hooks the ticket surface reaches for are
- * `addSubIssue` (from the future SubIssueGateway, used by `createTicket` to
- * link a freshly-created child as a native sub-issue) and `addItemToProject`
- * (from the projects-v2 shim, used by `createTicket` to add the new issue
- * to the configured Project V2).
+ * signature. The `addItemToProject` hook (from the projects-v2 shim) adds a
+ * newly-created issue to the configured Project V2.
  *
- * Public surface: `GitHubProvider.createTicket / createIssue / getTicket /
+ * Story #4545 deleted `createTicket` and its `composeStoryBody` helper — the
+ * Epic-hierarchy write surface. It composed the exact `Epic: #N` footer that
+ * `pr-base-guard.js` hard-refuses at delivery, so the framework retained the
+ * ability to generate work it would then reject; it had no production caller
+ * (`/plan` persists through the bare `createIssue` below).
+ *
+ * Public surface: `GitHubProvider.createIssue / getTicket /
  * getTickets / updateTicket / getTicketDependencies / primeTicketCache /
  * invalidateTicket` all delegate to the same-named methods on this class.
  *
@@ -22,9 +25,7 @@
  */
 
 import { parseBlockedBy, parseBlocks } from '../../lib/dependency-parser.js';
-import { stampFrameworkVersion } from '../../lib/framework-version.js';
 import { Logger } from '../../lib/Logger.js';
-import { TYPE_LABELS } from '../../lib/label-constants.js';
 import { addIssueToBoard } from './board-add.js';
 import { createInlineTicketCache } from './cache.js';
 import { withTransientRetry } from './errors.js';
@@ -43,70 +44,6 @@ import {
  */
 const SEARCH_PAGE_CAP = 10;
 
-/**
- * Compose the final markdown body for a created ticket. Under the 2-tier
- * hierarchy (Epic → Story), `body` is always a string supplied
- * by the caller (the decomposer, the spec planner, or the reconciler-apply
- * engine). This helper appends the canonical orchestrator footer
- * (`parent: #<n>` / `Epic: #<m>` / `blocked by #<x>`) byte-stable with the
- * format consumers (manifest, close-gate, dispatcher) parse.
- *
- * Story #3186 — inlined here when the Task-tier body-renderer helpers
- * were retired. The structured-body (object) path is gone: Stories carry
- * inline `acceptance[]` / `verify[]`
- * arrays on the Story body authored by the decomposer; there is no
- * server-side rendering of a four-section payload at create time.
- *
- * Story #4382 — this is also where a Story body is stamped, once, with the
- * running Mandrel framework version and authoring date (hidden `mandrel_version`
- * / `authored_at` meta field + a visible `> 🏷️ Authored with Mandrel …`
- * marker) via {@link stampFrameworkVersion}. The stamp is immutable: a body
- * that already carries a version (e.g. a reconciler re-create) is preserved
- * verbatim. The `stamp` override exists for deterministic tests; production
- * callers omit it so the running version and today's date are used.
- *
- * @param {{
- *   body: string,
- *   parentId: number,
- *   epicId?: number,
- *   dependencies?: number[],
- *   stamp?: { version?: string, authoredAt?: string } | false,
- * }} opts
- * @returns {string}
- *
- * Story #3958 — this is the single owner of the `blocked by #N` footer.
- * Callers (the reconciler-apply create path, the spec planner) pass
- * resolved dependency issue numbers via `dependencies` and supply a body
- * WITHOUT any pre-appended footer. A caller that also appends a
- * `blocked by` block to `body` would double every dependency line.
- */
-export function composeStoryBody({
-  body,
-  parentId,
-  epicId,
-  dependencies = [],
-  stamp,
-}) {
-  const rawHead = typeof body === 'string' ? body : '';
-  // `stamp === false` → footer-only recomposition: the caller (the reconciler
-  // UPDATE/diff path) owns stamp preservation itself and must NOT introduce a
-  // fresh authoring stamp, which would churn or bump the version on every
-  // reconcile. Every other call is a create — stamp once (immutably).
-  const head =
-    stamp === false ? rawHead : stampFrameworkVersion(rawHead, stamp ?? {});
-  const lines = ['---', `parent: #${parentId}`];
-  if (epicId !== undefined && epicId !== null) {
-    lines.push(`Epic: #${epicId}`);
-  }
-  if (dependencies.length > 0) {
-    lines.push('');
-    for (const dep of dependencies) {
-      lines.push(`blocked by #${dep}`);
-    }
-  }
-  return `${head}\n\n${lines.join('\n')}`;
-}
-
 export class TicketGateway {
   /**
    * @param {{
@@ -114,7 +51,6 @@ export class TicketGateway {
    *   owner: string,
    *   repo: string,
    *   hooks?: {
-   *     addSubIssue?: (parentNumber: number, childNodeId: string) => Promise<unknown>,
    *     addItemToProject?: (nodeId: string) => Promise<unknown>,
    *     getProjectNumber?: () => number|null,
    *   },
@@ -314,81 +250,10 @@ export class TicketGateway {
   // ---------------------------------------------------------------------------
 
   /**
-   * Create a new issue. Renders the body via the inline `composeStoryBody`
-   * helper so the `parent: #N` / `Epic: #M` / `blocked by #X` footer is
-   * consistent across creators.
-   *
-   * After the POST, opportunistically link the child as a native sub-issue
-   * (via the `addSubIssue` hook — retried internally on the sub-issue
-   * gateway) and add it to the configured Project V2 (best-effort —
-   * failures warn but do not fail the create).
-   *
-   * @field-manifest POST /repos/{owner}/{repo}/issues: number, id, node_id,
-   *                 html_url
-   */
-  /* node:coverage ignore next */
-  async createTicket(parentId, ticketData) {
-    const epicId = ticketData.epicId || parentId;
-    const renderedBody = composeStoryBody({
-      body: ticketData.body ?? '',
-      parentId,
-      epicId,
-      dependencies: ticketData.dependencies ?? [],
-    });
-
-    // Inject TYPE_LABELS.STORY so a spec that omits the labels array cannot
-    // produce an unlabeled, undispatchable Story. Dedupe to avoid duplicates
-    // when the caller already carries the label.
-    const callerLabels = ticketData.labels ?? [];
-    const labels = callerLabels.includes(TYPE_LABELS.STORY)
-      ? callerLabels
-      : [TYPE_LABELS.STORY, ...callerLabels];
-    const result = await this._gh.api({
-      method: 'POST',
-      endpoint: `/repos/${this.owner}/${this.repo}/issues`,
-      body: {
-        title: ticketData.title,
-        body: renderedBody,
-        labels,
-      },
-    });
-    const issue = parseApiJson(result);
-    this._listCache.clear();
-
-    let subIssueLinked = false;
-    let subIssueError = null;
-    try {
-      if (typeof this._hooks.addSubIssue === 'function') {
-        await this._hooks.addSubIssue(parentId, issue.node_id);
-        subIssueLinked = true;
-      }
-    } catch (err) {
-      subIssueError = err;
-    }
-
-    await addIssueToBoard({
-      nodeId: issue.node_id,
-      issueNumber: issue.number,
-      getProjectNumber: this._hooks.getProjectNumber,
-      addItemToProject: this._hooks.addItemToProject,
-    });
-
-    return {
-      id: issue.number,
-      internalId: issue.id,
-      nodeId: issue.node_id,
-      url: issue.html_url,
-      subIssueLinked,
-      subIssueError,
-    };
-  }
-
-  /**
-   * Create a **bare** issue — no `parent: #N` footer composition and no
-   * sub-issue link. Serves the standalone create paths that bypass
-   * `createTicket`'s Story-shaped body rendering: the `/plan`
-   * persist step and the `/plan` Phase 4 Epic open
-   * (`openEpicFromOnePager`'s `createIssue` port).
+   * Create a **bare** issue — no footer composition and no sub-issue link.
+   * Since Story #4545 this is the *only* create path: `/plan` persist and the
+   * `/plan` Phase 4 Epic open (`openEpicFromOnePager`'s `createIssue` port)
+   * both route through it.
    *
    * After the POST, the new issue is added to the configured Project V2
    * board via the shared `addIssueToBoard` helper (Story #3822) —
@@ -396,6 +261,17 @@ export class TicketGateway {
    * so board membership never depends on GitHub's "Auto-add to project"
    * built-in workflow.
    *
+   * The POST is wrapped in `withTransientRetry` (Story #4541) so it absorbs
+   * the same 502/429/ECONNRESET blips the read surfaces already do. It used
+   * to post bare, which made a single transient failure at story *k* of *N*
+   * abort `/plan` persist with `1..k-1` already live on the tracker.
+   *
+   * Retry alone is not sufficient for that failure mode — a POST whose
+   * response is lost would double-create on the retry — so the caller
+   * (`plan-persist`'s `createStoryIssues`) carries the idempotency half via
+   * a plan fingerprint it looks up before creating. Retry narrows the
+   * window; the fingerprint closes it.
+   *
    * @field-manifest POST /repos/{owner}/{repo}/issues: number, id, node_id,
    *                 html_url
    *
@@ -410,11 +286,15 @@ export class TicketGateway {
    * }>}
    */
   async createIssue({ title, body, labels = [] }) {
-    const result = await this._gh.api({
-      method: 'POST',
-      endpoint: `/repos/${this.owner}/${this.repo}/issues`,
-      body: { title, body, labels },
-    });
+    const result = await withTransientRetry(
+      () =>
+        this._gh.api({
+          method: 'POST',
+          endpoint: `/repos/${this.owner}/${this.repo}/issues`,
+          body: { title, body, labels },
+        }),
+      { label: `createIssue "${title}"`, onRetry: defaultRetryWarn },
+    );
     const issue = parseApiJson(result);
     this._listCache.clear();
 

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

@@ -80,9 +80,23 @@ export class GitHubProvider extends ITicketingProvider {
     return this._memoizedToken;
   }
 
-  /* node:coverage ignore next */
-  async listIssues(filters = {}) {
-    return this.getEpics(filters);
+  /**
+   * The identifiers a native dependency-edge writer needs, handed over as an
+   * explicit interface (Story #4544).
+   *
+   * `providers/github/blocked-by-add.js` talks to the dependencies REST API
+   * directly, so it needs the `gh` facade plus `owner`/`repo` — none of which
+   * the `ITicketingProvider` surface exposes. Its caller lives in the
+   * orchestration layer (`plan-persist/story-ops.js`), and the alternative was
+   * for that caller to reach through `provider._gh` — a private-by-convention
+   * field — from outside this module. Naming the hand-off here keeps the
+   * coupling declared and greppable instead of incidental: the provider
+   * decides what it lends out, and the field stays private.
+   *
+   * @returns {{ gh: object, owner: string, repo: string }}
+   */
+  getDependencyWriteContext() {
+    return { gh: this._gh, owner: this.owner, repo: this.repo };
   }
 
   static isInsufficientScopes(err) {
@@ -100,7 +114,6 @@ const DELEGATIONS = [
   ['graphql', 'issues.ghGraphql'],
   ['searchIssues', 'issues.searchIssues'],
   ['listIssuesByLabel', 'issues.listIssuesByLabel'],
-  ['getEpics', 'issues.getEpics'],
   ['getEpic', 'issues.getEpic'],
   ['branchExists', 'issues.branchExists'],
   ['getSubTickets', 'issues.getSubTickets'],
@@ -108,12 +121,10 @@ const DELEGATIONS = [
   ['getTickets', 'tickets.getTickets'],
   ['getTicket', 'tickets.getTicket'],
   ['getTicketDependencies', 'tickets.getTicketDependencies'],
-  ['createTicket', 'tickets.createTicket'],
   ['createIssue', 'tickets.createIssue'],
   ['updateTicket', 'tickets.updateTicket'],
   ['_applyLabelMutations', 'tickets._applyLabelMutations'],
   ['_getNativeSubIssues', 'subIssues.getNativeSubIssues'],
-  ['_getNativeParent', 'subIssues.getNativeParent'],
   ['addSubIssue', 'subIssues.addSubIssue'],
   ['removeSubIssue', 'subIssues.removeSubIssue'],
   ['reconcileSubIssueLinks', 'subIssues.reconcileSubIssueLinks'],

package/.agents/scripts/quality-preview.js

@@ -35,18 +35,25 @@ import {
  * present without a value. Returns `null` when the flag is absent so callers
  * can fall through to the gate scripts' own diff defaults.
  *
+ * **Last occurrence wins** (Story #4603). `npm run <alias> -- --changed-since <base>`
+ * appends the operator's flag *after* any flag baked into the npm script, so a
+ * first-wins scan silently discarded the operator's base and compared against
+ * the script's hardcoded one instead — reporting a false green for a branch the
+ * gate had never actually scored. Last-wins matches the convention every
+ * mainstream CLI parser follows for repeated scalar flags, and makes the
+ * npm-alias passthrough behave the way its callers already assume.
+ *
  * @param {string[]} argv
  * @returns {string | null}
  */
 export function parseChangedSinceArg(argv) {
+  let resolved = null;
   for (let i = 0; i < argv.length; i += 1) {
-    if (argv[i] === '--changed-since') {
-      const next = argv[i + 1];
-      if (next && !next.startsWith('--')) return next;
-      return 'HEAD';
-    }
+    if (argv[i] !== '--changed-since') continue;
+    const next = argv[i + 1];
+    resolved = next && !next.startsWith('--') ? next : 'HEAD';
   }
-  return null;
+  return resolved;
 }
 
 /**