mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -15,8 +15,9 @@
  * @module lib/orchestration/plan-persist/story-ops
  */
 
-import { randomBytes } from 'node:crypto';
-
+import { createHash } from 'node:crypto';
+import { applyBlockedByDependencies } from '../../../providers/github/blocked-by-add.js';
+import { Logger } from '../../Logger.js';
 import { AGENT_LABELS, TYPE_LABELS } from '../../label-constants.js';
 import {
   parse as parseStoryBody,
@@ -24,42 +25,142 @@ import {
 } from '../../story-body/story-body.js';
 import { assertSpecWithinBudget } from '../spec-spill.js';
 import { assertAcceptancePartition } from '../split-policy-validator.js';
+import {
+  assertSupersedePartition,
+  normalizeSupersedes,
+} from './supersede-ops.js';
+
+// Story #4540 removed PLAN_RUN_LABEL_PREFIX / normalizePlanRunId /
+// planRunLabel from here. They minted an opaque random-hex label per N>1
+// plan that nothing ever deleted, and their only external consumer was the
+// (now deleted) `--run` resolver. Sibling order survives in the
+// `blocked by #N` body footers this module already writes.
+
+/**
+ * Marker prefix for the per-Story plan fingerprint appended to every
+ * created body. `createStoryIssues` greps open `type::story` issues for
+ * `<!-- plan-story: <fingerprint> -->` to decide whether a Story already
+ * exists — the idempotency half of the resumable-create contract.
+ */
+const PLAN_FINGERPRINT_MARKER_PREFIX = 'plan-story:';
 
-/** Label prefix grouping sibling Stories from one plan run (N>1). */
-export const PLAN_RUN_LABEL_PREFIX = 'plan-run::';
+/** Length of the hex fingerprint digest. Collision-free at plan scale. */
+const PLAN_FINGERPRINT_LENGTH = 16;
 
 /**
- * Normalize a caller-supplied plan-run token. Persistence and resolution
- * share this helper so human-readable ids map to one canonical label.
+ * Compute the deterministic identity of one authored Story within a plan.
  *
- * @param {string} id
- * @returns {string}
+ * Derived from `slug` + `title` + the **assembled** body, so the fingerprint
+ * identifies the authored *content*, not merely a name. Because the marker is
+ * what `createStoryIssues` adopts on, that is the whole safety property of the
+ * resume path: a fingerprint hit means the open Story on the tracker is
+ * byte-identical to what this run would author, so adopting it instead of
+ * creating it is a genuine no-op.
+ *
+ * **Why the body is in scope.** It used to be excluded, on the rationale that
+ * creation rewrites the body to substitute real issue ids into `depends_on`
+ * footers, so a body-derived fingerprint would differ between an aborted run
+ * and its resume. That conflated two different bodies. The fingerprint is
+ * computed in `assembleOnePlanStory` over the *assembled* body — whose
+ * `depends_on` are still sibling **slugs**, and which is a pure function of
+ * `stories.json` plus the shared Spec. The id substitution happens later, and
+ * only inside `renderStoryBodyForCreate`, which produces the *posted* body.
+ * Nothing ever re-derives a fingerprint from a posted body; the lookup reads
+ * the marker that body carries. The assembled body is therefore stable across
+ * a run and its resume, and folding it in defeats no lookup.
+ *
+ * Excluding it cost two silent failures, both closed by this:
+ *
+ *   1. A later, unrelated plan that reused a slug **and** title adopted the
+ *      stale open Story — never rewriting its body or Spec, and landing this
+ *      run's checkpoints, ready-flip, and supersede comments on the wrong
+ *      issue.
+ *   2. A legitimate resume after the operator edited `stories.json` adopted
+ *      the pre-edit Story and kept its stale body, discarding the edit.
+ *
+ * With the body in scope both cases simply miss the lookup, and a correct new
+ * Story is created; only a genuinely identical Story is ever adopted.
+ *
+ * The fields are joined on NUL separators, written as the `\u0000` escape and
+ * never as a raw byte — a literal NUL would make git classify this file as
+ * binary and silently drop its diffs. NUL cannot occur in a slug, a title, or
+ * a serialized body, so the join is unambiguous: `{slug:'a-b', title:'c'}` and
+ * `{slug:'a', title:'b-c'}` cannot collide the way a hyphen or space separator
+ * would let them.
+ *
+ * @param {{ slug: string, title: string, body?: string }} story
+ * @returns {string} Hex digest.
  */
-export function normalizePlanRunId(id) {
-  const token = String(id ?? '')
-    .trim()
-    .toLowerCase()
-    .replace(/^plan-run::/, '')
-    .replace(/[^a-z0-9._-]+/g, '-');
-  if (!token) {
-    throw new Error('plan-run id requires a non-empty planRunId');
-  }
-  return token;
+export function planStoryFingerprint({ slug, title, body = '' }) {
+  return createHash('sha256')
+    .update(`${slug}\u0000${title}\u0000${body}`)
+    .digest('hex')
+    .slice(0, PLAN_FINGERPRINT_LENGTH);
 }
 
 /**
- * Build a `plan-run::<id>` label. When `id` is omitted, generates a short
- * random hex token (8 chars) suitable for a rare multi-Story plan.
+ * Render the HTML-comment marker carrying a Story's plan fingerprint. It is
+ * invisible in GitHub's rendered issue body and survives edits to every
+ * other section.
  *
- * @param {string} [id]
+ * @param {string} fingerprint
  * @returns {string}
  */
-export function planRunLabel(id) {
-  const token =
-    typeof id === 'string' && id.trim() !== ''
-      ? normalizePlanRunId(id)
-      : randomBytes(4).toString('hex');
-  return `${PLAN_RUN_LABEL_PREFIX}${token}`;
+function planFingerprintMarker(fingerprint) {
+  return `<!-- ${PLAN_FINGERPRINT_MARKER_PREFIX} ${fingerprint} -->`;
+}
+
+/**
+ * Labels the authoring pass is never allowed to set. The `agent::*` axis is
+ * the runtime's lifecycle state (persist owns the terminal `agent::ready`
+ * flip itself), `type::*` is fixed to `type::story` by the v2 hierarchy, and
+ * `persona::*` is a retired axis.
+ */
+const FORBIDDEN_LABEL_PREFIXES = Object.freeze([
+  'agent::',
+  'type::',
+  'persona::',
+]);
+
+/** GitHub's own label-name ceiling. */
+const MAX_LABEL_LENGTH = 50;
+
+/**
+ * Sanitize the author-supplied `labels[]` on a plan Story (Story #4541).
+ *
+ * The schema descriptor and the authoring prompt both ask for `labels[]`,
+ * but persist never read the field — it hard-coded its own list, so every
+ * authored label was silently discarded. Rather than keep asking for input
+ * that goes nowhere, apply it: drop the axes the runtime owns, drop
+ * malformed entries, dedupe, and always guarantee `type::story`.
+ *
+ * @param {unknown} rawLabels
+ * @param {string} slug For the dropped-label warning.
+ * @returns {string[]} Sanitized labels, always including `type::story`.
+ */
+export function sanitizeAuthoredLabels(rawLabels, slug) {
+  const kept = new Set([TYPE_LABELS.STORY]);
+  const dropped = [];
+  for (const raw of Array.isArray(rawLabels) ? rawLabels : []) {
+    const label = typeof raw === 'string' ? raw.trim() : '';
+    if (label === '' || label.length > MAX_LABEL_LENGTH) {
+      dropped.push(String(raw));
+      continue;
+    }
+    if (label === TYPE_LABELS.STORY) continue;
+    if (FORBIDDEN_LABEL_PREFIXES.some((p) => label.startsWith(p))) {
+      dropped.push(label);
+      continue;
+    }
+    kept.add(label);
+  }
+  if (dropped.length > 0) {
+    Logger.warn(
+      `[plan-persist] Story "${slug}": dropped ${dropped.length} authored ` +
+        `label(s) the runtime owns or cannot apply: ${dropped.join(', ')}.`,
+    );
+  }
+  return [...kept];
 }
 
 function bodyObjectFromTicket(ticket) {
@@ -126,8 +227,12 @@ function syncContractFieldFromTopLevel(ticket, bodyObject, field) {
  * Normalize a plan Story ticket into `{ slug, title, bodyObject }`.
  * Accepts either a serialized markdown `body` string or a structured body.
  *
+ * `supersedes[]` is a top-level-only field (Story #4535) — it is planning
+ * bookkeeping for the `--tickets` source issues, not part of the Story's
+ * executable body, so it is deliberately not serialized into the markdown.
+ *
  * @param {object} ticket
- * @returns {{ slug: string, title: string, bodyObject: object, depends_on: string[] }}
+ * @returns {{ slug: string, title: string, bodyObject: object, depends_on: string[], labels: string[], supersedes: Array<{ id: number, note: string|null }> }}
  */
 export function normalizeStoryTicket(ticket) {
   if (!ticket || typeof ticket !== 'object') {
@@ -150,8 +255,10 @@ export function normalizeStoryTicket(ticket) {
   syncContractFieldFromTopLevel(ticket, bodyObject, 'acceptance');
   syncContractFieldFromTopLevel(ticket, bodyObject, 'verify');
   const depends_on = normalizeDependsOn(ticket, bodyObject);
+  const supersedes = normalizeSupersedes(ticket, slug);
+  const labels = sanitizeAuthoredLabels(ticket.labels, slug);
 
-  return { slug, title, bodyObject, depends_on };
+  return { slug, title, bodyObject, depends_on, labels, supersedes };
 }
 
 /**
@@ -194,11 +301,15 @@ export function foldSpecIntoStoryBody(bodyObject, slug, opts = {}) {
 }
 
 function assembleOnePlanStory(ticket, opts) {
-  const { slug, title, bodyObject, depends_on } = normalizeStoryTicket(ticket);
+  const { slug, title, bodyObject, depends_on, labels, supersedes } =
+    normalizeStoryTicket(ticket);
   const { bodyObject: folded } = foldSpecIntoStoryBody(bodyObject, slug, {
     sharedSpec: opts.sharedSpec ?? null,
   });
+  // Body first: the fingerprint is an identity over the *assembled* content,
+  // so it cannot be computed until that content exists.
   const body = serializeStoryBody({ ...folded, depends_on });
+  const fingerprint = planStoryFingerprint({ slug, title, body });
   return {
     story: {
       slug,
@@ -207,6 +318,9 @@ function assembleOnePlanStory(ticket, opts) {
       bodyObject: { ...folded, depends_on },
       acceptance: Array.isArray(folded.acceptance) ? folded.acceptance : [],
       depends_on,
+      labels,
+      fingerprint,
+      supersedes,
     },
   };
 }
@@ -230,13 +344,17 @@ function assertSharedSpecAllowed(tickets, sharedSpec) {
 
 /**
  * Assemble markdown bodies for every Story: normalize → fold spec →
- * assertAcceptancePartition → serialize.
+ * assertAcceptancePartition → assertSupersedePartition → serialize.
+ *
+ * Both partition checks run **before** any GitHub write so a mis-authored
+ * plan never leaves Stories live against an inconsistent tracker.
  *
  * @param {object[]} tickets
  * @param {object} [opts]
  * @param {string|null} [opts.sharedSpec]
  * @param {string[]} [opts.planAcceptance]
- * @returns {{ stories: Array<{ slug: string, title: string, body: string, acceptance: string[], depends_on: string[] }> }}
+ * @param {number[]} [opts.sourceTicketIds] Ids passed to `/plan --tickets`.
+ * @returns {{ stories: Array<{ slug: string, title: string, body: string, acceptance: string[], depends_on: string[], supersedes: Array<{ id: number, note: string|null }> }> }}
  */
 export function assemblePlanStories(tickets, opts = {}) {
   if (!Array.isArray(tickets) || tickets.length === 0) {
@@ -254,6 +372,7 @@ export function assemblePlanStories(tickets, opts = {}) {
   assertAcceptancePartition(stories, {
     planAcceptance: opts.planAcceptance,
   });
+  assertSupersedePartition(stories, opts.sourceTicketIds ?? []);
 
   return { stories };
 }
@@ -289,16 +408,248 @@ function orderStoriesByDependencies(stories) {
 }
 
 /**
- * Create Story issues via `provider.createIssue`. Applies `type::story`,
- * `agent::ready`, and — when N>1 — a shared plan-run label.
+ * Index the open `type::story` backlog so a re-run can recognise Stories a
+ * previous, partially-failed persist already created.
+ *
+ * Two indexes come back. `byFingerprint` is the adoption key — an exact match
+ * on the authored content (see {@link planStoryFingerprint}). `idsByTitle` is
+ * only used to *warn*: it catches the near miss where a Story with this title
+ * is already open but its content differs, which is what an abandoned earlier
+ * plan or an edited `stories.json` leaves behind. Adoption deliberately does
+ * not key on it — a title is not an identity, and adopting on one would let a
+ * later unrelated plan overwrite someone else's Story.
+ *
+ * Best-effort by construction: a provider with no `listIssuesByLabel` (or a
+ * listing that errors) yields empty indexes and the create loop proceeds
+ * un-deduplicated, exactly as it did before. That degrades resume, not
+ * correctness of a first run — so it warns rather than throws.
+ *
+ * @param {object} provider
+ * @returns {Promise<{
+ *   byFingerprint: Map<string, { id: number, title: string, url?: string }>,
+ *   idsByTitle: Map<string, number[]>,
+ * }>}
+ */
+async function indexExistingStories(provider) {
+  const byFingerprint = new Map();
+  const idsByTitle = new Map();
+  if (typeof provider?.listIssuesByLabel !== 'function') {
+    Logger.warn(
+      '[plan-persist] provider does not expose listIssuesByLabel — cannot ' +
+        'check for Stories a previous persist already created. A re-run after ' +
+        'a mid-creation failure may duplicate them.',
+    );
+    return { byFingerprint, idsByTitle };
+  }
+  let issues;
+  try {
+    issues = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.STORY,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] open-Story lookup failed (${err.message}) — proceeding ` +
+        'without resume; a re-run may duplicate Stories.',
+    );
+    return { byFingerprint, idsByTitle };
+  }
+  for (const issue of Array.isArray(issues) ? issues : []) {
+    const id = Number(issue?.number ?? issue?.id);
+    if (!Number.isInteger(id)) continue;
+    const title = issue?.title ?? '';
+    if (title !== '') {
+      idsByTitle.set(title, [...(idsByTitle.get(title) ?? []), id]);
+    }
+    const body = typeof issue?.body === 'string' ? issue.body : '';
+    const match = body.match(
+      new RegExp(
+        `<!--\\s*${PLAN_FINGERPRINT_MARKER_PREFIX}\\s*([0-9a-f]+)\\s*-->`,
+      ),
+    );
+    if (!match) continue;
+    byFingerprint.set(match[1], {
+      id,
+      title,
+      url: issue.html_url ?? issue.url ?? undefined,
+    });
+  }
+  return { byFingerprint, idsByTitle };
+}
+
+/**
+ * Warn when a Story with this title is already open but did **not** match the
+ * fingerprint — i.e. its authored content differs from what this run is about
+ * to create.
+ *
+ * This is the visible half of the fingerprint tightening. Keying adoption on
+ * content means these cases correctly get a fresh Story rather than a silent
+ * stale-body adoption, but the divergent Story stays open, and a duplicate the
+ * operator never hears about is its own small trap. Naming it converts silent
+ * litter into a decision.
+ *
+ * @param {{ slug: string, title: string }} story
+ * @param {Map<string, number[]>} idsByTitle
+ */
+function warnOnDivergentSameTitleStory(story, idsByTitle) {
+  const ids = idsByTitle.get(story.title) ?? [];
+  if (ids.length === 0) return;
+  Logger.warn(
+    `[plan-persist] Story "${story.slug}": ${ids.length} open Story(ies) ` +
+      `already carry this exact title (${ids.map((id) => `#${id}`).join(', ')}) ` +
+      'but none match the authored content, so a new Story is being created ' +
+      'rather than silently adopting a stale body. If that is an abandoned ' +
+      'plan or a superseded draft, close it.',
+  );
+}
+
+/**
+ * Render the body actually posted for a Story: the assembled markdown with
+ * sibling `depends_on` slugs resolved to real issue ids, plus the invisible
+ * plan-fingerprint marker that makes the create loop resumable.
+ *
+ * @param {object} story
+ * @param {Map<string, number>} idBySlug
+ * @returns {string}
+ */
+function renderStoryBodyForCreate(story, idBySlug) {
+  const dependencyRefs = story.depends_on.map(
+    (slug) => `#${idBySlug.get(slug)}`,
+  );
+  const base =
+    dependencyRefs.length === 0
+      ? story.body
+      : serializeStoryBody(
+          { ...story.bodyObject, depends_on: dependencyRefs },
+          { includeFooter: true },
+        );
+  return `${base}\n\n${planFingerprintMarker(story.fingerprint)}`;
+}
+
+/**
+ * Mirror the plan's sibling `depends_on` edges into native GitHub `blocked_by`
+ * dependency edges (Story #4544).
+ *
+ * Ordering is authored as slugs and, until now, survived persist only as
+ * `blocked by #N` prose in the body footer. That footer stays — it is what
+ * `/deliver`'s resolver falls back on — but a native edge is the durable,
+ * machine-readable form: visible in the GitHub UI, readable without parsing
+ * markdown, and settable by an operator later for cross-run order.
+ *
+ * **Non-fatal by design, and deliberately asymmetric with the read path.** A
+ * missing native edge is cosmetic here: `renderStoryBodyForCreate` has already
+ * written the footer, so ordering is not lost when the dependencies API says
+ * no. `/deliver`'s *read* of these edges is a real dispatch gate, which is why
+ * that side fails loud. Persist reports the failure and completes.
+ *
+ * Two shape hazards this crossing has to get right, both silent if missed:
+ * `applyBlockedByDependencies` indexes `slugToIssueNumber` with property
+ * access, so the `Map` the create loop builds must be flattened to a plain
+ * object — a `Map` would yield `undefined` for every lookup, skip every edge,
+ * and (being non-fatal) report success having written nothing. And it reads
+ * `dependsOn`, not the `depends_on` the assembled Story carries.
+ *
+ * @param {object} args
+ * @param {object} args.provider
+ * @param {Array<{ slug: string, depends_on: string[] }>} args.stories
+ * @param {Map<string, number>} args.idBySlug
+ * @returns {Promise<{ edgesAdded: number, edgesSkipped: number, edgesFailed: number, storiesProcessed: number }|null>}
+ *   `null` when there was nothing to mirror or no interface to mirror through.
+ */
+async function mirrorNativeDependencyEdges({ provider, stories, idBySlug }) {
+  const withEdges = stories.filter((story) => story.depends_on.length > 0);
+  if (withEdges.length === 0) return null;
+
+  if (
+    typeof provider?.getDependencyWriteContext !== 'function' ||
+    typeof provider?.getTicket !== 'function'
+  ) {
+    Logger.warn(
+      '[plan-persist] provider exposes no getDependencyWriteContext/getTicket — ' +
+        'skipping native blocked_by edges. Ordering survives in the ' +
+        '`blocked by #N` body footers.',
+    );
+    return null;
+  }
+
+  try {
+    const { gh, owner, repo } = provider.getDependencyWriteContext();
+    const summary = await applyBlockedByDependencies({
+      stories: stories.map((story) => ({
+        slug: story.slug,
+        dependsOn: story.depends_on,
+      })),
+      slugToIssueNumber: Object.fromEntries(idBySlug),
+      getTicket: (issueNumber) => provider.getTicket(issueNumber),
+      owner,
+      repo,
+      gh,
+    });
+    if (summary.edgesFailed > 0) {
+      Logger.warn(
+        `[plan-persist] ${summary.edgesFailed} native blocked_by edge(s) could ` +
+          'not be written. Ordering survives in the `blocked by #N` body ' +
+          'footers; add the edges by hand if you want them in the GitHub UI.',
+      );
+    } else {
+      Logger.info(
+        `[plan-persist] native blocked_by edges: ${summary.edgesAdded} added, ` +
+          `${summary.edgesSkipped} already present.`,
+      );
+    }
+    return summary;
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] native blocked_by mirroring failed (${err.message}) — ` +
+        'ordering survives in the `blocked by #N` body footers.',
+    );
+    return null;
+  }
+}
+
+/**
+ * Create Story issues via `provider.createIssue`, resumably.
+ *
+ * **Stories are born without `agent::ready`** (Story #4541). They used to
+ * carry it in the creating POST while the `story-plan-state` checkpoint was
+ * upserted afterwards, so anything that picked a Story up inside that window —
+ * or after a comment failure aborted the loop — read the checkpoint as `null`.
+ * Creation now applies `type::story` plus the sanitized authored labels only;
+ * `markStoriesReady` performs the flip as the terminal step, once every
+ * checkpoint is on the ticket.
+ *
+ * **The loop is resumable, and adoption is content-keyed.** Each body carries
+ * a plan-fingerprint marker, and the open `type::story` backlog is indexed by
+ * it before the first POST. A Story whose fingerprint already exists is
+ * adopted rather than re-created, so a re-run after a 502 at story *k* of *N*
+ * completes the cohort instead of minting a second copy of `1..k-1`.
+ *
+ * The fingerprint covers the assembled body, not just slug + title, so a hit
+ * means the open Story *is* what this run would author and adoption changes
+ * nothing. A same-named Story whose content has drifted — an abandoned plan, or
+ * an edited `stories.json` — misses the lookup, gets a correct new Story, and
+ * is named in a warning. Adoption never rewrites a body, so keying it on
+ * anything weaker than content would silently ship a stale one.
+ *
+ * Story #4540 retired the `plan-run::<id>` label this used to apply when
+ * N>1. Batch identity was the wrong axis to encode: it could not express an
+ * edge to a Story planned in a different run, and ordering already lives in
+ * the `blocked by #N` footers written below — which `/deliver`'s resolver
+ * reads directly, alongside native GitHub edges, from live state.
+ *
+ * **Sibling order is mirrored into native GitHub `blocked_by` edges** once
+ * every id is known (Story #4544), so plan-created order stops depending on
+ * prose. That pass is non-fatal — see `mirrorNativeDependencyEdges`.
  *
  * @param {object} args
  * @param {object} args.provider
  * @param {ReturnType<typeof assemblePlanStories>['stories']} args.stories
  * @param {object} [args.opts]
- * @param {string} [args.opts.planRunId]
  * @param {boolean} [args.opts.dryRun=false]
- * @returns {Promise<{ created: Array<{ slug: string, id: number, url?: string, title: string }>, planRunLabel: string|null }>}
+ * @returns {Promise<{
+ *   created: Array<{ slug: string, id: number, url?: string, title: string, adopted: boolean }>,
+ *   dependencyEdges: { edgesAdded: number, edgesSkipped: number, edgesFailed: number, storiesProcessed: number }|null,
+ * }>}
  */
 export async function createStoryIssues({ provider, stories, opts = {} }) {
   if (typeof provider?.createIssue !== 'function') {
@@ -308,9 +659,6 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
   }
 
   const list = Array.isArray(stories) ? stories : [];
-  const planLabel = list.length > 1 ? planRunLabel(opts.planRunId) : null;
-  const labels = [TYPE_LABELS.STORY, AGENT_LABELS.READY];
-  if (planLabel) labels.push(planLabel);
 
   if (opts.dryRun) {
     return {
@@ -319,28 +667,40 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
         id: -(i + 1),
         title: s.title,
         url: undefined,
+        adopted: false,
       })),
-      planRunLabel: planLabel,
+      dependencyEdges: null,
     };
   }
 
+  const { byFingerprint, idsByTitle } = await indexExistingStories(provider);
   const created = [];
-  const createdBySlug = new Map();
+  const idBySlug = new Map();
+
   for (const story of orderStoriesByDependencies(list)) {
-    const dependencyRefs = story.depends_on.map(
-      (slug) => `#${createdBySlug.get(slug)}`,
-    );
-    const body =
-      dependencyRefs.length === 0
-        ? story.body
-        : serializeStoryBody(
-            { ...story.bodyObject, depends_on: dependencyRefs },
-            { includeFooter: true },
-          );
+    const already = byFingerprint.get(story.fingerprint);
+    if (!already) warnOnDivergentSameTitleStory(story, idsByTitle);
+    if (already) {
+      Logger.info(
+        `[plan-persist] resuming: Story "${story.slug}" already exists as ` +
+          `#${already.id} with byte-identical authored content ` +
+          `(plan fingerprint ${story.fingerprint}) — skipping create.`,
+      );
+      created.push({
+        slug: story.slug,
+        id: already.id,
+        title: story.title,
+        url: already.url,
+        adopted: true,
+      });
+      idBySlug.set(story.slug, already.id);
+      continue;
+    }
+
     const result = await provider.createIssue({
       title: story.title,
-      body,
-      labels: [...labels],
+      body: renderStoryBodyForCreate(story, idBySlug),
+      labels: [...story.labels],
     });
     const id = result?.id ?? result?.number;
     if (!Number.isInteger(id)) {
@@ -353,9 +713,66 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
       id,
       title: story.title,
       url: result.url,
+      adopted: false,
     });
-    createdBySlug.set(story.slug, id);
+    idBySlug.set(story.slug, id);
   }
 
-  return { created, planRunLabel: planLabel };
+  // Every id is known now — including the adopted ones a resumed run reused —
+  // so a re-run mirrors the whole cohort's edges, not just the Stories this
+  // invocation happened to POST. Re-application is idempotent.
+  const dependencyEdges = await mirrorNativeDependencyEdges({
+    provider,
+    stories: list,
+    idBySlug,
+  });
+
+  return { created, dependencyEdges };
+}
+
+/**
+ * Flip every created Story to `agent::ready` — the terminal step of persist
+ * (Story #4541).
+ *
+ * This is what makes `agent::ready` *mean* "fully persisted": by the time it
+ * lands, the Story's `story-plan-state` checkpoint is already on the ticket, so
+ * a `/deliver` that picks it up cannot read a null checkpoint.
+ *
+ * Fails closed: an un-flipped Story is invisible to `/deliver`, which is the
+ * safe direction — the operator is told exactly which ids need the label.
+ *
+ * @param {object} args
+ * @param {object} args.provider
+ * @param {Array<{ id: number, slug: string }>} args.created
+ * @returns {Promise<{ readied: number[] }>}
+ */
+export async function markStoriesReady({ provider, created }) {
+  if (typeof provider?.updateTicket !== 'function') {
+    throw new Error(
+      '[plan-persist] provider does not expose updateTicket; cannot flip ' +
+        'Stories to agent::ready.',
+    );
+  }
+  const readied = [];
+  const failed = [];
+  for (const story of created) {
+    try {
+      await provider.updateTicket(story.id, {
+        labels: { add: [AGENT_LABELS.READY] },
+      });
+      readied.push(story.id);
+    } catch (err) {
+      failed.push(`#${story.id} (${story.slug}): ${err.message}`);
+    }
+  }
+  if (failed.length > 0) {
+    throw new Error(
+      `[plan-persist] ${failed.length} Story(ies) were created with their ` +
+        'checkpoints but could not be flipped to agent::ready:\n' +
+        `${failed.map((f) => `  - ${f}`).join('\n')}\n` +
+        'They are invisible to /deliver until the label lands. Re-run persist ' +
+        '(it resumes rather than duplicating) or add the label by hand.',
+    );
+  }
+  return { readied };
 }