mandrel 2.54.0 → 2.56.0

package/.agents/scripts/merge-baseline.js

@@ -45,13 +45,20 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-
 import { assertEnvelope } from './lib/baselines/envelope.js';
 import {
+  baselineRegenerateRemedy,
   kindFromEnvelope,
   mergeEnvelopes,
+  mergePlainBaseline,
+  plainKindFromEnvelope,
+  renderStampConflict,
 } from './lib/baselines/merge-envelopes.js';
 import { writeFile as writeEnvelopeFile } from './lib/baselines/writer.js';
+import {
+  BASELINE_MERGE_DRIVER_REMEDY,
+  ensureBaselineMergeDriver,
+} from './lib/bootstrap/baseline-merge-driver.js';
 import { spawnChild } from './lib/child-exec.js';
 import { runAsCli } from './lib/cli-utils.js';
 
@@ -144,11 +151,86 @@ function delegateToGit(basePath, oursPath, theirsPath) {
   return result.status ?? 1;
 }
 
+/**
+ * Which merge does this file get?
+ *
+ * Two families answer, and neither is "all of `baselines/*.json`":
+ *
+ *   - **Envelope kinds** — the eight kernel kinds, merged by the kind
+ *     module's own `rowIdentity` with the rollup RE-DERIVED.
+ *   - **Plain row baselines** — `cyclomatic`, `dead-exports` and
+ *     `dead-exports-production`, which are row sets with a real identity but
+ *     no kernel protocol. Until Story #5277 these fell through to
+ *     `git merge-file` even though `.gitattributes` routes them here, so the
+ *     attribute promised a row merge the driver never performed.
+ *
+ * Anything else — arch-cycles, audit-ledger, context-budget,
+ * workflow-citations — resolves `null` and is handed back to git unchanged.
+ *
+ * @param {unknown} ours
+ * @param {unknown} theirs
+ * @returns {{ kind: string, envelopeKind: boolean }|null}
+ */
+function resolveMergeTarget(ours, theirs) {
+  const envelopeKind = kindFromEnvelope(ours) ?? kindFromEnvelope(theirs);
+  if (envelopeKind) return { kind: envelopeKind, envelopeKind: true };
+  const plain = plainKindFromEnvelope(ours) ?? plainKindFromEnvelope(theirs);
+  if (plain) return { kind: plain, envelopeKind: false };
+  return null;
+}
+
+/**
+ * Serialize the merged result into `%A`. Envelope kinds go through the shared
+ * writer (which validates against the per-kind schema); plain baselines are
+ * written with the same `JSON.stringify(…, null, 2)` + trailing newline their
+ * own generators use, which is what keeps a clean merge byte-identical to a
+ * regeneration.
+ *
+ * @param {string} oursPath
+ * @param {{ envelope: object }} merged
+ * @param {boolean} isEnvelopeKind
+ */
+function writeMerged(oursPath, merged, isEnvelopeKind) {
+  if (isEnvelopeKind) {
+    writeEnvelopeFile(oursPath, merged.envelope);
+    return;
+  }
+  fs.writeFileSync(oursPath, `${JSON.stringify(merged.envelope, null, 2)}\n`);
+}
+
+/**
+ * Register the driver in this clone (`--install`).
+ *
+ * The driver script installs its own registration because the registration is
+ * the half that cannot travel: `.gitattributes` is tracked and ships with the
+ * repo, `merge.mandrel-baseline.driver` is per-clone git config and is absent
+ * in every fresh clone — silently, with git falling back to a text merge and
+ * reporting nothing. Wired into this repo's `prepare` script so `npm install`
+ * completes the registration, and idempotent so every later `prepare` is a
+ * no-op.
+ *
+ * @returns {number} Process exit code.
+ */
+function runInstall() {
+  const result = ensureBaselineMergeDriver({ projectRoot: process.cwd() });
+  if (result.config === 'failed') {
+    process.stderr.write(
+      `merge-baseline: could not register the merge driver.\n  → ${BASELINE_MERGE_DRIVER_REMEDY}\n`,
+    );
+    return 1;
+  }
+  process.stdout.write(
+    `merge-baseline: driver ${result.action} (attributes=${result.attributes}, config=${result.config}) → ${result.command}\n`,
+  );
+  return 0;
+}
+
 /**
  * @param {string[]} argv Positional arguments: %O %A %B [%P].
  * @returns {number} Process exit code.
  */
 export function runMergeBaseline(argv) {
+  if (argv.includes('--install')) return runInstall();
   const [baseArg, oursArg, theirsArg, mergedPath] = argv;
   if (!baseArg || !oursArg || !theirsArg) {
     process.stderr.write(
@@ -168,37 +250,106 @@ export function runMergeBaseline(argv) {
 
   const ours = readSide(oursPath);
   const theirs = readSide(theirsPath);
-  const base = readSide(basePath);
+  const target =
+    ours === undefined || theirs === undefined
+      ? null
+      : resolveMergeTarget(ours, theirs);
+  if (!target) return delegateToGit(basePath, oursPath, theirsPath);
 
-  const kind = kindFromEnvelope(ours) ?? kindFromEnvelope(theirs);
-  if (!kind || ours === undefined || theirs === undefined) {
-    return delegateToGit(basePath, oursPath, theirsPath);
-  }
+  return mergeResolved({
+    target,
+    base: readSide(basePath),
+    ours,
+    theirs,
+    basePath,
+    oursPath,
+    theirsPath,
+    label: mergedPath || oursPath,
+  });
+}
 
+/**
+ * Merge a file whose kind the driver DOES understand, and leave the result in
+ * `%A`. A merge that throws is handed back to git rather than half-written:
+ * the driver must never invent a result for a baseline it could not model.
+ *
+ * @param {object} ctx
+ * @returns {number} Process exit code.
+ */
+function mergeResolved({
+  target,
+  base,
+  ours,
+  theirs,
+  basePath,
+  oursPath,
+  theirsPath,
+  label,
+}) {
+  const { kind, envelopeKind: isEnvelopeKind } = target;
   let merged;
   try {
-    merged = mergeEnvelopes({ base, ours, theirs, kind });
+    merged = isEnvelopeKind
+      ? mergeEnvelopes({ base, ours, theirs, kind })
+      : mergePlainBaseline({ base, ours, theirs, kind });
   } catch (err) {
     process.stderr.write(`merge-baseline: ${kind}: ${err.message}\n`);
     return delegateToGit(basePath, oursPath, theirsPath);
   }
 
-  const rowConflicts = merged.conflicts.filter((c) => c.scope === 'row');
-  const envelopeConflicts = merged.conflicts.filter(
-    (c) => c.scope === 'envelope',
-  );
-
   // Write the canonical projection first even when conflicted: the marker
   // rendering operates on exactly the bytes a clean merge would have left,
   // so the merged remainder of a conflicted file is identical to it.
-  writeEnvelopeFile(oursPath, merged.envelope);
+  writeMerged(oursPath, merged, isEnvelopeKind);
 
   if (merged.conflicts.length === 0) {
-    assertEnvelope(merged.envelope);
+    if (isEnvelopeKind) assertEnvelope(merged.envelope);
     return 0;
   }
+  return markConflicts({ kind, merged, oursPath, label });
+}
+
+/**
+ * Report a conflicted merge and render its markers into `%A`.
+ *
+ * Both scopes get markers. An envelope-level conflict used to be reported on
+ * stderr alone, leaving a file that looked cleanly merged while git held the
+ * path unmerged — the operator had to reconstruct from scrollback which stamp
+ * disagreed.
+ *
+ * @param {{ kind: string, merged: object, oursPath: string, label: string }} ctx
+ * @returns {number} Always 1 — a conflicted merge.
+ */
+function markConflicts({ kind, merged, oursPath, label }) {
+  const rowConflicts = merged.conflicts.filter((c) => c.scope === 'row');
+  const envelopeConflicts = merged.conflicts.filter(
+    (c) => c.scope === 'envelope',
+  );
+  reportConflicts({ kind, label, rowConflicts, envelopeConflicts });
+
+  let text = fs.readFileSync(oursPath, 'utf8');
+  if (envelopeConflicts.length > 0) {
+    text = renderStampConflict(text, envelopeConflicts);
+  }
+  if (rowConflicts.length > 0) {
+    text = renderConflictMarkers(text, rowConflicts);
+  }
+  fs.writeFileSync(oursPath, text);
+  return 1;
+}
 
-  const label = mergedPath || oursPath;
+/**
+ * Report every conflict on stderr, then name the regeneration command.
+ *
+ * The regenerate line is not decoration. The merged file's rollup was derived
+ * from a row set that still carries conflict markers, so resolving the markers
+ * by hand leaves the rollup describing a tree nobody scored — the same silent
+ * wrong number the driver exists to prevent, arrived at from the other
+ * direction. Saying it here is the only place an operator sees it.
+ *
+ * @param {{ kind: string, label: string, rowConflicts: Array<object>, envelopeConflicts: Array<object> }} args
+ */
+function reportConflicts({ kind, label, rowConflicts, envelopeConflicts }) {
   for (const conflict of envelopeConflicts) {
     process.stderr.write(
       `merge-baseline: conflict ${kind} envelope key "${conflict.identity}" in ${label} — ours ${JSON.stringify(conflict.ours)}, theirs ${JSON.stringify(conflict.theirs)}\n`,
@@ -209,12 +360,11 @@ export function runMergeBaseline(argv) {
       `merge-baseline: conflict ${kind} row "${conflict.identity}" in ${label}\n`,
     );
   }
-
-  if (rowConflicts.length > 0) {
-    const text = fs.readFileSync(oursPath, 'utf8');
-    fs.writeFileSync(oursPath, renderConflictMarkers(text, rowConflicts));
-  }
-  return 1;
+  process.stderr.write(
+    `merge-baseline: ${label} is conflicted — the rollup in it was derived from ` +
+      `unresolved rows and must not be trusted. After resolving the markers, ` +
+      `regenerate it: ${baselineRegenerateRemedy(kind)}\n`,
+  );
 }
 
 function main() {
@@ -233,6 +383,10 @@ runAsCli(import.meta.url, main, {
       ['%A', 'Our version — the driver writes its result here.'],
       ['%B', 'Their version.'],
       ['%P', 'Real pathname being merged; used in conflict messages.'],
+      [
+        '--install',
+        'Register the driver in this clone (.gitattributes line + the per-clone merge.mandrel-baseline.driver config) and exit. Idempotent.',
+      ],
     ],
   },
 });

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

@@ -66,7 +66,8 @@
  * green can already have merged by the time it is observed. On red the
  * watcher disarms auto-merge and records the head SHA; on green it reads
  * the digest and adjudicates: a green on the SAME head SHA is a forbidden
- * re-run (exit 1, `agent::blocked`, `meta::framework-gap` required), while
+ * re-run (exit 1, `agent::blocked`, a `file-ci-gap.js` intake filing
+ *             required), while
  * a green on a NEW head SHA is a fix at source — the digest is retired,
  * auto-merge is re-armed, and the delivery proceeds. A delivery that never
  * went red has no digest and is untouched. Mechanism:
@@ -475,7 +476,7 @@ async function evaluateGreenWatch({
     `[pr-watch] run link: ${digest.runUrl ?? `run id ${digest.runId ?? 'unresolved'}`} — classification: ${digest.classification ?? 'unknown'}`,
   );
   logger.error?.(
-    '[pr-watch] fix the root cause and push a new commit, or file a `meta::framework-gap` issue carrying the run link and failure signature.',
+    '[pr-watch] fix the root cause and push a new commit, or — when the root cause is outside this delivery — run `node .agents/scripts/file-ci-gap.js --story <id> --verdict <verdict> --owner <bucket> --block` to file the routed, deduped intake issue.',
   );
   const outcome = await blockFn({ storyId, body });
   return {

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

@@ -15,13 +15,34 @@
  * Extracted from `../github.js` in Story #1846 / Task #1857.
  */
 
+/**
+ * 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.
+ */
 const FEATURE_DISABLED_MESSAGES = [
   'feature not available',
   'feature is not enabled',
   "field 'subissues'",
   'field "subissues"',
   'subissues is not available',
-  'sub-issues',
+  // 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.
+  'subissues field',
+  'sub_issues field',
+  'sub-issues field',
   "doesn't exist on type",
   'does not exist on type',
   'unknown field',

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

@@ -20,7 +20,7 @@ import { Logger } from '../../lib/Logger.js';
 import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import { isNotFoundError } from './branch-protection.js';
 import { classifyGithubError, withTransientRetry } from './errors.js';
-import { issueToEpic } from './mappers.js';
+import { issueToEpic, issueToTicket, subIssueNodeToTicket } from './mappers.js';
 import {
   defaultRetryWarn,
   paginateRest,
@@ -54,6 +54,32 @@ function classifySearchRetry(err) {
  */
 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.
+ */
+const PARENT_ISSUE_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
+  repository(owner: $owner, name: $repo) {
+    issue(number: $number) {
+      parent {
+        number
+        databaseId
+        id
+        title
+        body
+        state
+        labels(first: 30) { nodes { name } }
+        assignees(first: 20) { nodes { login } }
+      }
+    }
+  }
+}`;
+
 // Re-export so existing test consumers that previously imported
 // `paginateRest` from this module continue to work without an extra
 // migration step.
@@ -124,6 +150,85 @@ export class IssuesGateway {
     return issues.filter((issue) => !issue?.pull_request);
   }
 
+  /**
+   * 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.
+   *
+   * @param {{ state?: 'open'|'closed'|'all', labels?: string }} [opts]
+   * @returns {Promise<Array<object>>} Mapped tickets (`id` is the issue number).
+   * @field-manifest /repos/{owner}/{repo}/issues: number, id, node_id, title,
+   *                 body, labels, state, state_reason, assignees, html_url,
+   *                 pull_request
+   */
+  async listTicketsByLabel(opts = {}) {
+    const issues = await this.listIssuesByLabel(opts);
+    return issues.map((issue) => ({
+      ...issueToTicket(issue),
+      url: issue.html_url ?? null,
+    }));
+  }
+
+  /**
+   * 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.
+   *
+   * @param {number} number Issue number whose parent to resolve.
+   * @returns {Promise<object|null>} Mapped parent ticket, or null.
+   * @field-manifest GraphQL Issue.parent: number, id, title, body, state,
+   *                 labels.nodes.name, assignees.nodes.login
+   */
+  async getParentIssue(number) {
+    const issueNumber = Number(number);
+    if (!Number.isInteger(issueNumber) || issueNumber <= 0) return null;
+    let data;
+    try {
+      data = await withTransientRetry(
+        () =>
+          this.ghGraphql(
+            PARENT_ISSUE_QUERY,
+            { owner: this.owner, repo: this.repo, number: issueNumber },
+            { headers: { 'GraphQL-Features': 'sub_issues' } },
+          ),
+        {
+          label: `getParentIssue #${issueNumber}`,
+          onRetry: defaultRetryWarn,
+        },
+      );
+    } catch (err) {
+      Logger.warn(
+        `[GitHubProvider] parent lookup for #${issueNumber} degraded to none ` +
+          `(${err?.message ?? err}).`,
+      );
+      return null;
+    }
+    return subIssueNodeToTicket(data?.repository?.issue?.parent ?? null);
+  }
+
   /**
    * Search issues by a free-text query via the REST search API
    * (`GET /search/issues`). Deliberately REST, **not** GraphQL: transient

package/.agents/scripts/providers/github/sub-issue-add.js

@@ -150,18 +150,28 @@ export async function addSubIssueEdges({
 
 /**
  * Link child Stories to a container Epic, resolving each child's **database
- * id** from its issue number via the injected `getTicket` hook.
+ * id** from its issue number.
  *
  * Callers hold issue numbers (that is what `plan-persist` creates and what
  * an operator types); the API wants database ids. Doing the translation here
  * keeps that trap in one place instead of at every call site.
  *
+ * `knownInternalIds` short-circuits the translation for children whose
+ * database id the caller already has. `createIssue` returns `internalId` in
+ * its response, so a cohort this run just created needs no lookup at all —
+ * the `getTicket` fan-out that used to run over every child was re-reading
+ * issues the same process had created seconds earlier, one round-trip per
+ * Story, to recover a field it had already been handed and thrown away.
+ * `getTicket` stays for the children a *resumed* run adopted, whose ids came
+ * from a listing rather than a create.
+ *
  * Never throws: a child whose id cannot be resolved is counted as failed and
  * the remaining edges still go out.
  *
  * @param {{
  *   epicNumber: number,
  *   childIssueNumbers: number[],
+ *   knownInternalIds?: Map<number, number>|null,
  *   getTicket: (issueNumber: number) => Promise<{ internalId: number }>,
  *   owner: string,
  *   repo: string,
@@ -173,6 +183,7 @@ export async function addSubIssueEdges({
 export async function linkStoriesToEpic({
   epicNumber,
   childIssueNumbers,
+  knownInternalIds = null,
   getTicket,
   owner,
   repo,
@@ -182,10 +193,16 @@ export async function linkStoriesToEpic({
   const numbers = Array.isArray(childIssueNumbers) ? childIssueNumbers : [];
   if (numbers.length === 0) return { added: 0, skipped: 0, failed: 0 };
 
+  const known = knownInternalIds instanceof Map ? knownInternalIds : new Map();
   let failed = 0;
   const childInternalIds = [];
 
   for (const childNumber of numbers) {
+    const alreadyKnown = known.get(Number(childNumber));
+    if (typeof alreadyKnown === 'number') {
+      childInternalIds.push(alreadyKnown);
+      continue;
+    }
     try {
       const ticket = await getTicket(childNumber);
       const internalId = ticket?.internalId;

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

@@ -116,6 +116,8 @@ const DELEGATIONS = [
   ['graphql', 'issues.ghGraphql'],
   ['searchIssues', 'issues.searchIssues'],
   ['listIssuesByLabel', 'issues.listIssuesByLabel'],
+  ['listTicketsByLabel', 'issues.listTicketsByLabel'],
+  ['getParentIssue', 'issues.getParentIssue'],
   ['getEpic', 'issues.getEpic'],
   ['branchExists', 'issues.branchExists'],
   ['getSubTickets', 'issues.getSubTickets'],
@@ -126,6 +128,10 @@ const DELEGATIONS = [
   ['createIssue', 'tickets.createIssue'],
   ['updateTicket', 'tickets.updateTicket'],
   ['_applyLabelMutations', 'tickets._applyLabelMutations'],
+  ['getNativeSubIssues', 'subIssues.getNativeSubIssues'],
+  // The private alias predates the declared `getNativeSubIssues` port above
+  // and still has call sites; both forward to the same gateway method, so the
+  // two can never answer differently while the older name is retired.
   ['_getNativeSubIssues', 'subIssues.getNativeSubIssues'],
   ['getTicketComments', 'comments.getTicketComments'],
   ['deleteComment', 'comments.deleteComment'],

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

@@ -30,6 +30,7 @@
  *   node .agents/scripts/resolve-stories.js --ids 101-104        # inclusive range
  *   node .agents/scripts/resolve-stories.js --ids 101,102 --pretty
  *   node .agents/scripts/resolve-stories.js --ids 101 --no-native   # skip the dependencies API
+ *   node .agents/scripts/resolve-stories.js --ids 101 --allow-unlabelled
  *
  * Exit codes: 0 ok, 1 usage/resolution error.
  */
@@ -39,7 +40,7 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
-import { resolveEpicNodeId } from './lib/orchestration/epic-container.js';
+import { nativeChildReader } from './lib/orchestration/epic-container.js';
 import { expandEpicIds } from './lib/orchestration/epic-expansion.js';
 import {
   buildStoriesEnvelope,
@@ -52,7 +53,18 @@ import { createProvider } from './lib/provider-factory.js';
 import { concurrentMap } from './lib/util/concurrent-map.js';
 import { paginateRest } from './providers/github/request-helpers.js';
 
-export { buildStoriesEnvelope, parseIds, readNativeBlockedBy, toStoryRecord };
+export {
+  buildStoriesEnvelope,
+  // Re-exported, not redefined (Story #5280). The reader now lives in
+  // `epic-container.js` beside the shape it reads, so the expansion path and
+  // the rollup share one definition — the pair whose divergence makes an Epic
+  // expandable but unclosable. The name stays exported here because two test
+  // modules import it from this entrypoint.
+  nativeChildReader,
+  parseIds,
+  readNativeBlockedBy,
+  toStoryRecord,
+};
 
 /**
  * Bounded concurrency for the per-issue round-trips. Matches the edge-writer's
@@ -78,6 +90,11 @@ Options:
                  be mixed with Story ids.
   --pretty       Pretty-print the JSON envelope.
   --no-native    Skip the native blocked_by read (body edges only).
+  --allow-unlabelled
+                 Resolve a Story carrying no agent::* label. Without it such a
+                 Story is refused: the audit sweep files Stories without one on
+                 purpose, and delivering one means dispatching a worker at
+                 unenriched audit prose. Route it through /mandrel-plan first.
   --help         Show this help.
 `;
 
@@ -93,29 +110,6 @@ export function resolveStoriesProvider({
   return { provider: createProviderFn(config), config };
 }
 
-/**
- * Read an Epic's native sub-issue children as issue numbers.
- *
- * Injected into `expandEpicIds` so the lib layer stays provider-agnostic,
- * exactly as `paginate` is injected into `readNativeBlockedBy`. A provider
- * without the GraphQL surface yields `[]`, and the Epic body's checklist
- * carries the children on its own — as does an Epic carrying no resolvable
- * node id, which `resolveEpicNodeId` reports rather than letting an
- * `undefined` reach the API as a rejected `ID!` variable.
- *
- * @param {object} provider
- * @returns {(epic: object) => Promise<number[]>}
- */
-export function nativeChildReader(provider) {
-  return async (epic) => {
-    const nodeId = resolveEpicNodeId(epic);
-    if (nodeId === null) return [];
-    return (
-      provider?._getNativeSubIssues?.(nodeId, epic?.number ?? epic?.id) ?? []
-    );
-  };
-}
-
 /**
  * Fetch every requested id and map it to a Story record, failing on the first
  * id that is not a deliverable Story.
@@ -127,9 +121,10 @@ export function nativeChildReader(provider) {
  *
  * @param {object} provider
  * @param {number[]} ids
+ * @param {{ allowUnlabelled?: boolean }} [options]
  * @returns {Promise<object[]>}
  */
-export async function fetchStories(provider, ids) {
+export async function fetchStories(provider, ids, { allowUnlabelled } = {}) {
   const { ids: resolvedIds, expansions } = await expandEpicIds({
     ids,
     getTicket: (id) => provider.getTicket(id),
@@ -151,7 +146,7 @@ export async function fetchStories(provider, ids) {
       if (!issue) {
         throw new Error(`[resolve-stories] Issue #${id} was not found.`);
       }
-      return toStoryRecord(issue, id);
+      return toStoryRecord(issue, id, { allowUnlabelled });
     },
     { concurrency: FETCH_CONCURRENCY },
   );
@@ -237,19 +232,20 @@ export async function resolveForeignDone({ provider, dag, inSetIds }) {
  * stdout are injected so the whole path is unit-testable without a live
  * GitHub round-trip. Exported for testing.
  *
- * @param {{ ids: string, native?: boolean, pretty?: boolean }} args
+ * @param {{ ids: string, native?: boolean, pretty?: boolean,
+ *   allowUnlabelled?: boolean }} args
  * @param {{ provider: object, config: object, stdout?: { write(s: string): void } }} deps
  * @returns {Promise<number>}
  */
 export async function runResolveStories(
-  { ids: rawIds, native = true, pretty = false },
+  { ids: rawIds, native = true, pretty = false, allowUnlabelled = false },
   { provider, config, stdout = process.stdout },
 ) {
   const ids = parseIds(rawIds);
   const owner = config.github?.owner;
   const repo = config.github?.repo;
 
-  const stories = await fetchStories(provider, ids);
+  const stories = await fetchStories(provider, ids, { allowUnlabelled });
   const nativeEdges = native
     ? await readNativeEdges({ provider, stories, owner, repo })
     : new Map();
@@ -280,12 +276,29 @@ export async function runResolveStories(
   return 0;
 }
 
+/**
+ * Project the parsed flags onto the flow core's options object, so `main` reads
+ * as parse → help → run and the flag-name spellings live in one place.
+ *
+ * @param {Record<string, unknown>} values
+ * @returns {{ ids: string, native: boolean, pretty: boolean, allowUnlabelled: boolean }}
+ */
+function toRunOptions(values) {
+  return {
+    ids: values.ids,
+    native: values.native,
+    pretty: values.pretty,
+    allowUnlabelled: values['allow-unlabelled'],
+  };
+}
+
 async function main() {
   const { values } = parseArgs({
     options: {
       ids: { type: 'string' },
       pretty: { type: 'boolean', default: false },
       native: { type: 'boolean', default: true },
+      'allow-unlabelled': { type: 'boolean', default: false },
       help: { type: 'boolean', default: false },
     },
     // The documented opt-out is `--no-native`; without allowNegative,
@@ -308,10 +321,7 @@ async function main() {
   // headless caller can pipe this straight into stories-wave-tick.js.
   routeAllOutputToStderr();
 
-  return runResolveStories(
-    { ids: values.ids, native: values.native, pretty: values.pretty },
-    resolveStoriesProvider(),
-  );
+  return runResolveStories(toRunOptions(values), resolveStoriesProvider());
 }
 
 runAsCli(import.meta.url, main, {