mandrel 2.58.0 → 2.60.0

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -7,23 +7,23 @@
  *
  *   1. `changes[]` repair + ticket validator + file-assumption + DAG
  *   2. Draft reachability (named soft failure, exit 3)
- *   3. Split-policy partition (`assertAcceptancePartition`) + spec fold
+ *   3. Same-wave collision refusal (`assertNoWaveCollisions`) + spec fold
  *   4. Create Story issues (`type::story` + sanitized authored labels —
  *      deliberately NOT `agent::ready`), resumably via a plan fingerprint
- *   5. Upsert `story-plan-state` on every created Story; upsert `plan-summary`
- *      on the primary Story
+ *   5. Upsert the `story-plan-state` comment on every created Story — since
+ *      Story #5343 the one comment persist posts, carrying the plan summary
  *   6. Flip every Story to `agent::ready` — the terminal step, so `ready`
- *      always implies "checkpoints written"
+ *      always implies "plan comments written"
  *   7. Comment on + close the superseded `--tickets` source issues
  *      (Story #4535) — bookkeeping only; never fails the run
  *   8. Temp cleanup at terminal success + a stale-plan-dir reap
  *
  * **Why `agent::ready` moved to the end (Story #4541).** Issues used to be
- * born `agent::ready` in the creating POST while the checkpoints were
+ * born `agent::ready` in the creating POST while the plan comments were
  * written afterwards. Anything picking a Story up in that window — or after
- * a comment failure aborted the loop — read the checkpoint as `null`
- * (`story-plan-state.js` degrades missing/malformed to `null`). Creating
- * unlabelled, writing checkpoints, then flipping closes that race.
+ * a comment failure aborted the loop — found a ready Story carrying none of
+ * the operator's delivery instructions. Creating unlabelled, writing the
+ * comments, then flipping closes that race.
  *
  * **No authored risk artifact (Story #4542).** Persist neither requires nor
  * accepts a risk verdict, derives no envelope from one, and computes no
@@ -75,48 +75,48 @@ import {
   createStoryIssues,
   markStoriesReady,
 } from './story-ops.js';
-import {
-  buildPlanSummaryCommentBody,
-  buildWaveTable,
-  PLAN_SUMMARY_COMMENT_TYPE,
-} from './summary.js';
+import { buildPlanSummaryCommentBody, buildWaveTable } from './summary.js';
 import { closeSupersededTickets } from './supersede-ops.js';
-import { predictWaveSerialisation } from './wave-serialisation.js';
-
-/** Checkpoint schema version written on each Story's story-plan-state. */
-const PLAN_CHECKPOINT_SCHEMA_VERSION_V2 = 2;
+import { assertNoWaveCollisions } from './wave-collision-gate.js';
 
-/** Structured-comment type for the per-plan Story checkpoint. */
+/** Structured-comment type for the per-plan Story comment. */
 const STORY_PLAN_STATE_TYPE = 'story-plan-state';
 
 /**
- * Write the `story-plan-state` checkpoint on a Story.
+ * Write the plan comment on a Story — the **one** comment persist posts per
+ * Story (Story #5343).
+ *
+ * It carries the human plan summary: the created Story set, the delivery order
+ * and the exact deliver command. That summary used to be a second
+ * `plan-summary` comment on the primary Story only, which meant the operator's
+ * instructions lived on a different marker from the rest — and on a different
+ * ticket from four Stories out of five.
+ *
+ * **No machine payload (Story #5367).** The comment used to lead with a fenced
+ * JSON checkpoint (a persist receipt: completion time, Story count, the
+ * cohort). Nothing ever read it back — the one module that parsed it had no
+ * production importer — so the payload and its readers are gone. The
+ * `story-plan-state` marker stays: it is what makes a re-persist upsert this
+ * comment in place instead of appending a second one.
  *
  * @param {object} provider
  * @param {number} storyId
- * @param {object} state
+ * @param {string} summary Rendered plan-summary markdown. The comment exists
+ *   to carry it, so an empty summary is a caller bug rather than a degenerate
+ *   comment worth posting.
+ * @returns {Promise<void>}
  */
-export async function writeCheckpointV2(provider, storyId, state) {
+export async function writePlanSummaryComment(provider, storyId, summary) {
   if (!Number.isInteger(storyId)) {
-    throw new TypeError('writeCheckpointV2 requires a numeric storyId');
+    throw new TypeError('writePlanSummaryComment requires a numeric storyId');
+  }
+  const body = summary?.trim();
+  if (!body) {
+    throw new TypeError(
+      'writePlanSummaryComment requires a non-empty plan summary',
+    );
   }
-  const body = [
-    '### story-plan-state',
-    '',
-    '```json',
-    JSON.stringify(
-      {
-        version: PLAN_CHECKPOINT_SCHEMA_VERSION_V2,
-        storyId,
-        ...state,
-      },
-      null,
-      2,
-    ),
-    '```',
-  ].join('\n');
   await upsertStructuredComment(provider, storyId, STORY_PLAN_STATE_TYPE, body);
-  return state;
 }
 
 /**
@@ -130,7 +130,7 @@ export async function writeCheckpointV2(provider, storyId, state) {
  * the helper applied are reported alongside so the operator sees what was
  * rewritten.
  *
- * The returned freshness counts feed the posted `plan-summary`'s freshness
+ * The returned freshness counts feed the posted summary's freshness
  * line: every warning is a reference the base branch disagreed with, so it
  * counts as `stale` there rather than the comment reading "clean" on a run
  * that had something to say.
@@ -197,8 +197,9 @@ function collectTextHygieneWarnings(rawStories) {
 
 /**
  * Print every warning the run collected under one heading. The dry-run is
- * where an operator reads these; the persist prints the same list so a
- * `--chain-on-clean` run loses nothing.
+ * where an operator reads these; the persist prints the same list so the
+ * chained run loses nothing on stderr, as the chain's envelope merge keeps
+ * it from losing anything on stdout (Story #5361).
  *
  * @param {string[]} warnings
  * @returns {void}
@@ -248,7 +249,7 @@ async function runSupersedePhase(args) {
 }
 
 /**
- * Render the plan-metrics line for the **posted** `plan-summary` comment,
+ * Render the plan-metrics line for the **posted** summary section,
  * scoped to this invocation.
  *
  * The ordering hazard this closes: the ledger record for the current run is
@@ -313,7 +314,7 @@ async function renderRunScopedPlanMetricsLine({
  * writes — and the passes that scan `body.acceptance` / `body.verify` were
  * inert on the canonical top-level authoring shape as a result. Findings the
  * raw pass already reported are dropped so the same collision is not
- * announced twice per run; the rest are returned for the plan-summary
+ * announced twice per run; the rest are returned for the summary
  * comment, which is where these findings stop being a stderr line nobody
  * keeps. Every finding is advisory (Story #5312).
  *
@@ -419,56 +420,33 @@ async function enforceReachability(reachability, config) {
 }
 
 /**
- * Write the per-Story checkpoint, upsert the plan-summary comment, and flip
- * every created Story to `agent::ready`. Terminal ordering is load-bearing:
- * `agent::ready` lands last so it can honestly mean "fully persisted"
- * (Story #4541). A dry run performs none of it.
+ * Write the per-Story plan comment — one comment per Story, carrying the plan
+ * summary (Story #5343) — and flip every created Story to `agent::ready`.
+ * Terminal ordering is load-bearing: `agent::ready` lands last so it can
+ * honestly mean "fully persisted" (Story #4541). A dry run performs none of it.
  *
- * **The checkpoints fan out; the phase boundary does not** (Story #4952). The
+ * **The comments fan out; the phase boundary does not** (Story #4952). The
  * per-Story upserts are independent of one another and run under bounded
  * concurrency, but the `await` on that whole fan-out is what keeps the
- * Story #4541 invariant intact: *every* checkpoint is on its ticket before the
- * first `agent::ready` flip is issued, so `ready` still means "fully
- * persisted" and a `/mandrel-deliver` that picks a Story up cannot read a null
- * checkpoint. Concurrency inside the phase is safe; overlapping the phases is
- * the race this ordering exists to close.
+ * Story #4541 invariant intact: *every* Story carries its plan comment before
+ * the first `agent::ready` flip is issued, so `ready` still means "fully
+ * persisted" and the operator's instructions are never missing from a ticket
+ * something else may already be picking up. Concurrency inside the phase is
+ * safe; overlapping the phases is the race this ordering exists to close.
  *
  * @param {object} args
  * @returns {Promise<void>}
  */
-async function persistStoryArtifacts({
-  provider,
-  created,
-  primary,
-  summaryBody,
-}) {
-  const cohort = created.map((createdStory) => ({
-    slug: createdStory.slug,
-    id: createdStory.id,
-  }));
+async function persistStoryArtifacts({ provider, created, summaryBody }) {
   await concurrentMap(
     created,
-    (story) =>
-      writeCheckpointV2(provider, story.id, {
-        persist: {
-          completedAt: new Date().toISOString(),
-          storyCount: created.length,
-          primaryStoryId: primary.id,
-          stories: cohort,
-        },
-      }),
-    // The per-Story checkpoint upserts (Story #4952): each targets a
+    (story) => writePlanSummaryComment(provider, story.id, summaryBody),
+    // The per-Story comment upserts (Story #4952): each targets a
     // different issue and reads nothing another writes, so this loop was
     // serial only by construction — but see {@link persistStoryArtifacts}
     // for the phase ordering that is *not* incidental.
     { concurrency: FANOUT_CONCURRENCY },
   );
-  await upsertStructuredComment(
-    provider,
-    primary.id,
-    PLAN_SUMMARY_COMMENT_TYPE,
-    summaryBody,
-  );
   await markStoriesReady({ provider, created });
 }
 
@@ -543,7 +521,6 @@ function logPersistEpilogue({
  *   artifacts: {
  *     stories: Array<object>,
  *     techSpecContent?: string|null,
- *     planAcceptance?: string[]|null,
  *     planContextEnvelope?: object|null,
  *   },
  *   config?: object,
@@ -569,7 +546,6 @@ export async function runPlanPersist({
   const {
     stories: rawStories = null,
     techSpecContent = null,
-    planAcceptance = null,
     planContextEnvelope = null,
   } = artifacts ?? {};
   const {
@@ -623,21 +599,28 @@ export async function runPlanPersist({
     epicId: opts.adoptEpicId ?? null,
   });
 
-  // Split policy + inline Spec fold (Specs stay inline, never under docs/).
+  // Inline Spec fold (Specs stay inline, never under docs/).
   const seedContent = planContextEnvelope?.seed?.content ?? '';
-  const { stories: assembled } = assemblePlanStories(rawStories, {
-    sharedSpec: techSpecContent,
-    planAcceptance: planAcceptance ?? undefined,
-    sourceTicketIds,
-    // The seed this plan was authored from: an audit sweep's Single-plan seed
-    // carries the `audit-fingerprints` / `audit-semantic-keys` footers, and
-    // assembly copies them into the persisted Story bodies so the next sweep
-    // recognises what it already planned (Story #4877). Since Story #5045 this
-    // is the **fallback** — it is carried onto every Story that did not
-    // attribute its own `provenance`, which keeps an un-attributed plan exactly
-    // as recall-safe as it was. Empty for a `--tickets` run, a no-op there.
-    provenanceSource: seedContent,
-  });
+  const { stories: assembled, warnings: supersedeWarnings } =
+    assemblePlanStories(rawStories, {
+      sharedSpec: techSpecContent,
+      sourceTicketIds,
+      // The seed this plan was authored from: an audit sweep's Single-plan seed
+      // carries the `audit-fingerprints` / `audit-semantic-keys` footers, and
+      // assembly copies them into the persisted Story bodies so the next sweep
+      // recognises what it already planned (Story #4877). Since Story #5045 this
+      // is the **fallback** — it is carried onto every Story that did not
+      // attribute its own `provenance`, which keeps an un-attributed plan exactly
+      // as recall-safe as it was. Empty for a `--tickets` run, a no-op there.
+      provenanceSource: seedContent,
+    });
+
+  // Story #5342: the source ids assembly assigned to the primary Story by
+  // default. They ride the same list every other dry-run warning does, so a
+  // default-assigned supersede is visible in the output the operator already
+  // reads rather than only in the tracker afterwards.
+  warnings.push(...supersedeWarnings);
+  logWarnings(supersedeWarnings);
 
   // Stamp the `audit::*` labels the dedup corpus is listed by. Without them a
   // Story this path files is absent from the pool an indexed sweep matches
@@ -654,6 +637,31 @@ export async function runPlanPersist({
     rawFindings: validated.findings,
   });
 
+  // Story #5332 — the split gate, ahead of the first create. `buildWaveTable`
+  // needs only `{slug, title, depends_on}` and the prediction needs only the
+  // assembled bodies, so both can run before anything is written; they used
+  // to sit *after* creation, which is why the collision table could only ever
+  // be a receipt for a plan already live. The same computed value is handed
+  // to the summary rendering below rather than recomputed, so the refusal and
+  // the receipt can never disagree.
+  const waveTable = buildWaveTable(
+    stories.map((s) => ({
+      slug: s.slug,
+      title: s.title,
+      depends_on: s.depends_on,
+    })),
+  );
+
+  // Story #5265: the table says which Stories share an order; the dispatcher
+  // decides which of those actually run together. Run its own predicate over
+  // the assembled bodies — the exact artifact the tick will read back off
+  // GitHub — so an N>1 draft it would serialize is refused here, and the
+  // summary comment names the serialisation instead of promising parallelism
+  // the next tick refuses. One enumeration feeds both.
+  const waveCollisions = assertNoWaveCollisions(waveTable, stories, {
+    tempRoot: getPaths(config).tempRoot,
+  });
+
   const { created, planRunLabel, planRunLabelApplied } =
     await createStoryIssues({
       provider,
@@ -666,24 +674,6 @@ export async function runPlanPersist({
   recordAuditFilings({ stories, created, tickets: rawStories, dryRun });
 
   const primary = created[0];
-  const waveTable = buildWaveTable(
-    stories.map((s) => ({
-      slug: s.slug,
-      title: s.title,
-      depends_on: s.depends_on,
-    })),
-  );
-
-  // Story #5265: the table says which Stories share an order; the dispatcher
-  // decides which of those actually run together, and it decides on the
-  // evidence-widened footprint. Run its own predicate over the assembled
-  // bodies — the exact artifact the tick will read back off GitHub — so the
-  // comment names the serialisation instead of promising parallelism the
-  // next tick refuses. `tempRoot` is threaded for the same reason the tick
-  // threads it: the scrape must ignore this project's scratch root.
-  const waveCollisions = predictWaveSerialisation(waveTable, stories, {
-    tempRoot: getPaths(config).tempRoot,
-  });
 
   // Story #4541: `readPlanMetrics` is declared `(epicId, config)` but was
   // called with `config` first, so the ledger path resolver received the
@@ -718,12 +708,7 @@ export async function runPlanPersist({
   });
 
   if (!dryRun) {
-    await persistStoryArtifacts({
-      provider,
-      created,
-      primary,
-      summaryBody,
-    });
+    await persistStoryArtifacts({ provider, created, summaryBody });
   }
 
   // Story #5139 — the container Epic is created LAST among the writes: its

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

@@ -4,7 +4,7 @@
  * Under the Story collapse (`docs/roadmap.md` § Stage 3), `/mandrel-plan` persists
  * zero-or-more Story issues directly — no Epic parent, no reconciler tree,
  * no `deliveryShape` mode matrix. Default is **one Story**; N>1 is gated by
- * the Stage-1 split-policy validator (`assertAcceptancePartition`).
+ * the supersede partition check.
  *
  * Each Story body is the single executable document: Tech Spec stays inline
  * under `## Spec`, at whatever length the work needs (Story #5312 deleted
@@ -34,14 +34,13 @@ import {
   concurrentMap,
   FANOUT_CONCURRENCY,
 } from '../../util/concurrent-map.js';
-import { assertAcceptancePartition } from '../split-policy-validator.js';
 import {
   externalDependencyId,
   isExternalDependencyRef,
 } from './external-deps.js';
 import {
-  assertSupersedePartition,
   normalizeSupersedes,
+  resolveSupersedePartition,
 } from './supersede-ops.js';
 
 /**
@@ -158,7 +157,7 @@ const PLAN_FINGERPRINT_LENGTH = 16;
  *
  *   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
+ *      run's plan comments, 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.
@@ -514,17 +513,30 @@ function assertSharedSpecAllowed(tickets, sharedSpec) {
 
 /**
  * Assemble markdown bodies for every Story: normalize → fold spec →
- * assertAcceptancePartition → assertSupersedePartition → serialize.
+ * order by dependency → resolveSupersedePartition → serialize.
  *
- * Both partition checks run **before** any GitHub write so a mis-authored
- * plan never leaves Stories live against an inconsistent tracker.
+ * **The dependency sort runs here, once** (Story #5361). It used to run again
+ * inside the create loop, which meant "the primary Story" was derived twice
+ * from two different orderings: supersede assignment took the first *authored*
+ * Story, while the plan summary took the first *created*
+ * one. A draft whose authoring order differed from its dependency order made
+ * the `superseded-by` comment name a different Story from the summary. One
+ * sort, one ordered list threaded on to every consumer, so `stories[0]` is the
+ * only primary there is. The sort also refuses an unknown sibling or a cycle,
+ * which now fails the write-free pass rather than the first create.
+ *
+ * The partition pass runs **before** any GitHub write so a mis-authored
+ * plan never leaves Stories live against an inconsistent tracker. Story #5332
+ * retired the acceptance partition that used to run beside it: it refused
+ * only byte-identical acceptance text across siblings, and the split gate is
+ * now `assertNoWaveCollisions` in `run-plan-persist.js`, ahead of the first
+ * create.
  *
  * @param {object[]} tickets
  * @param {object} [opts]
  * @param {string|null} [opts.sharedSpec]
- * @param {string[]} [opts.planAcceptance]
  * @param {number[]} [opts.sourceTicketIds] Ids passed to `/mandrel-plan --tickets`.
- * @returns {{ stories: Array<{ slug: string, title: string, body: string, acceptance: string[], depends_on: string[], supersedes: Array<{ id: number, note: string|null }> }> }}
+ * @returns {{ stories: Array<{ slug: string, title: string, body: string, acceptance: string[], depends_on: string[], supersedes: Array<{ id: number, note: string|null }> }>, warnings: string[] }}
  */
 export function assemblePlanStories(tickets, opts = {}) {
   if (!Array.isArray(tickets) || tickets.length === 0) {
@@ -535,16 +547,16 @@ export function assemblePlanStories(tickets, opts = {}) {
 
   assertSharedSpecAllowed(tickets, opts.sharedSpec);
 
-  const stories = tickets.map(
-    (ticket) => assembleOnePlanStory(ticket, opts).story,
+  const stories = orderStoriesByDependencies(
+    tickets.map((ticket) => assembleOnePlanStory(ticket, opts).story),
   );
 
-  assertAcceptancePartition(stories, {
-    planAcceptance: opts.planAcceptance,
-  });
-  assertSupersedePartition(stories, opts.sourceTicketIds ?? []);
+  const warnings = resolveSupersedePartition(
+    stories,
+    opts.sourceTicketIds ?? [],
+  );
 
-  return { stories };
+  return { stories, warnings };
 }
 
 function orderStoriesByDependencies(stories) {
@@ -902,12 +914,13 @@ async function ensurePersistLabel({
  * 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
+ * carry it in the creating POST while the `story-plan-state` comment 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.
+ * or after a comment failure aborted the loop — found a ready Story carrying
+ * none of the operator's delivery instructions. Creation now applies
+ * `type::story` plus the sanitized authored labels only; `markStoriesReady`
+ * performs the flip as the terminal step, once every plan comment 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
@@ -1003,7 +1016,10 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
   const created = [];
   const idBySlug = new Map();
 
-  for (const story of orderStoriesByDependencies(list)) {
+  // Already in dependency order: `assemblePlanStories` sorted once, and
+  // sorting again here is what gave the run a second, disagreeing notion of
+  // which Story is primary (Story #5361).
+  for (const story of list) {
     const already = byFingerprint.get(story.fingerprint);
     if (!already) warnOnDivergentSameTitleStory(story, idsByTitle);
     if (already) {
@@ -1088,8 +1104,8 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
  * (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 `/mandrel-deliver` that picks it up cannot read a null checkpoint.
+ * lands, the Story's `story-plan-state` comment is already on the ticket, so a
+ * `/mandrel-deliver` that picks it up always has the plan summary beside it.
  *
  * Fails closed: an un-flipped Story is invisible to `/mandrel-deliver`, which is the
  * safe direction — the operator is told exactly which ids need the label.
@@ -1145,7 +1161,7 @@ export async function markStoriesReady({ provider, created }) {
   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' +
+        'plan comments but could not be flipped to agent::ready:\n' +
         `${failed.map((f) => `  - ${f}`).join('\n')}\n` +
         'They are invisible to /mandrel-deliver until the label lands. Re-run persist ' +
         '(it resumes rather than duplicating) or add the label by hand.',

package/.agents/scripts/lib/orchestration/plan-persist/summary.js

@@ -1,10 +1,14 @@
 /**
  * summary.js — plan-persist terminal summary (v2 Stage 3).
  *
- * Upserts a single `plan-summary` structured comment on the primary Story
- * at terminal success. Carries the persist receipts — including whether the
- * operator forced a review stop — and the dry-run `depends_on` ordering table
- * for the rare N>1 plan.
+ * Renders the persist receipts — the created Story set, whether the operator
+ * forced a review stop, the `depends_on` ordering table and the exact deliver
+ * command. Story #5343 moved that rendering onto the **`story-plan-state`**
+ * marker every created Story already carries: it used to be a second,
+ * primary-Story-only `plan-summary` comment, which cost one more write per
+ * plan and split the operator's reading between two markers. Story #5367
+ * deleted the machine checkpoint that shared the marker with it, so this
+ * rendering is now the whole body of the one comment persist posts.
  *
  * Story #4542 removed the risk / review-routing line: no risk level, gate
  * decision, or acceptance disposition is computed at plan time any more, so
@@ -16,11 +20,6 @@
 import { computeStoryWaves } from '../dependency-analyzer.js';
 import { renderPredictedSerialisationLines } from './wave-serialisation.js';
 
-/**
- * Structured-comment type for the persist summary.
- */
-export const PLAN_SUMMARY_COMMENT_TYPE = 'plan-summary';
-
 /**
  * Compute the dry-run wave assignment for a validated ticket set.
  *
@@ -114,7 +113,8 @@ function renderSharedEditorLines(conflictFindings) {
 }
 
 /**
- * Build the `plan-summary` structured-comment body.
+ * Build the body of each Story's `story-plan-state` comment (Story #5343;
+ * Story #5367 made it the whole body).
  *
  * @param {object} input
  * @returns {string}
@@ -169,7 +169,7 @@ export function buildPlanSummaryCommentBody({
       : '/mandrel-deliver <storyId> [<storyId> ...]';
 
   return [
-    `### 📋 Plan Summary — Story #${epicId} is \`agent::ready\``,
+    `#### 📋 Plan Summary — Story #${epicId} is \`agent::ready\``,
     '',
     `- ${ticketCount} Story ticket(s) persisted: ${storyList}.`,
     ...reviewLines,