mandrel 1.62.0 → 1.64.0

package/.agents/scripts/lib/story-body/story-body.js

@@ -355,6 +355,96 @@ function splitSections(markdown) {
   return { sections, footer, preamble };
 }
 
+// ---------------------------------------------------------------------------
+// Parser — per-section sub-parsers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the minimal {@link ParseResult} returned for a legacy string body —
+ * markdown that carries no recognised structured section. The goal falls
+ * back to the preamble text (or the whole trimmed input), `depends_on` is
+ * still recovered from the footer, and all section arrays are empty.
+ *
+ * @param {string} input - The original markdown string.
+ * @param {string} preamble - Text before the first heading (from splitSections).
+ * @param {string} footer - Footer block text (from splitSections).
+ * @returns {ParseResult}
+ */
+function parseLegacyStringBody(input, preamble, footer) {
+  const warnings = [
+    'legacy-string-body: no structured sections found; returning minimal body from preamble text.',
+    'test-surface-unestimated: estimated_test_files not present.',
+  ];
+  const body = {
+    goal: preamble || input.trim(),
+    changes: [],
+    acceptance: [],
+    verify: [],
+    references: [],
+    wide: null,
+    depends_on: extractBlockedBy(footer),
+    estimated_test_files: null,
+  };
+  return {
+    body,
+    warnings,
+    info: {
+      hasGoalSection: false,
+      hasChangesSection: false,
+      hasAcceptanceSection: false,
+      hasVerifySection: false,
+      hasReferencesSection: false,
+      isLegacyStringBody: true,
+    },
+  };
+}
+
+/**
+ * Parse the `## Goal` section: join its non-empty content lines into a
+ * single one-line goal string.
+ *
+ * @param {string[]} lines - Raw content lines under the heading.
+ * @returns {string}
+ */
+function parseGoalSection(lines) {
+  return lines
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+/**
+ * Parse a `## Changes` / `## References` section into a list of
+ * `PathEntry | string` entries. List markers are stripped, blank entries are
+ * dropped, and each surviving entry is normalized via {@link parsePathEntry}
+ * (which appends `legacy-path-entry` warnings for bare-string bullets).
+ *
+ * @param {string[]} lines - Raw content lines under the heading.
+ * @param {string[]} warnings - Mutable warnings sink.
+ * @returns {Array<PathEntry|string>}
+ */
+function parsePathEntrySection(lines, warnings) {
+  const entries = [];
+  for (const line of lines) {
+    const stripped = stripListMarker(line);
+    if (!stripped) continue;
+    const entry = parsePathEntry(stripped, warnings);
+    if (entry !== null) entries.push(entry);
+  }
+  return entries;
+}
+
+/**
+ * Parse a plain bullet-list section (`## Acceptance` / `## Verify`) into a
+ * list of trimmed strings, dropping blank entries.
+ *
+ * @param {string[]} lines - Raw content lines under the heading.
+ * @returns {string[]}
+ */
+function parseTextListSection(lines) {
+  return lines.map((l) => stripListMarker(l)).filter(Boolean);
+}
+
 // ---------------------------------------------------------------------------
 // Parser
 // ---------------------------------------------------------------------------
@@ -414,84 +504,20 @@ export function parse(input) {
     !hasVerifySection;
 
   if (isLegacyStringBody) {
-    // Extract depends_on from footer even for legacy bodies.
-    const dependsOn = extractBlockedBy(footer);
-    warnings.push(
-      'legacy-string-body: no structured sections found; returning minimal body from preamble text.',
-    );
-    warnings.push(
-      'test-surface-unestimated: estimated_test_files not present.',
-    );
-    const body = {
-      goal: preamble || input.trim(),
-      changes: [],
-      acceptance: [],
-      verify: [],
-      references: [],
-      wide: null,
-      depends_on: dependsOn,
-      estimated_test_files: null,
-    };
-    return {
-      body,
-      warnings,
-      info: {
-        hasGoalSection: false,
-        hasChangesSection: false,
-        hasAcceptanceSection: false,
-        hasVerifySection: false,
-        hasReferencesSection: false,
-        isLegacyStringBody: true,
-      },
-    };
+    return parseLegacyStringBody(input, preamble, footer);
   }
 
-  // --- Parse goal ---
-  const goalLines = sections.get('goal') ?? [];
-  const goal = goalLines
-    .map((l) => l.trim())
-    .filter(Boolean)
-    .join(' ');
-
-  // --- Parse changes ---
-  const changeLines = sections.get('changes') ?? [];
-  const changes = [];
-  for (const line of changeLines) {
-    const stripped = stripListMarker(line);
-    if (!stripped) continue;
-    const entry = parsePathEntry(stripped, warnings);
-    if (entry !== null) changes.push(entry);
-  }
-
-  // --- Parse acceptance ---
-  const acceptanceLines = sections.get('acceptance') ?? [];
-  const acceptance = acceptanceLines
-    .map((l) => stripListMarker(l))
-    .filter(Boolean);
-
-  // --- Parse verify ---
-  const verifyLines = sections.get('verify') ?? [];
-  const verify = verifyLines.map((l) => stripListMarker(l)).filter(Boolean);
-
-  // --- Parse references (optional) ---
-  const referenceLines = sections.get('references') ?? [];
-  const references = [];
-  for (const line of referenceLines) {
-    const stripped = stripListMarker(line);
-    if (!stripped) continue;
-    const entry = parsePathEntry(stripped, warnings);
-    if (entry !== null) {
-      // References MUST be object form (canonical).
-      if (typeof entry === 'string') {
-        // Already warned as legacy-path-entry; keep as string for now.
-        references.push(entry);
-      } else {
-        references.push(entry);
-      }
-    }
-  }
-
-  // --- Parse footer ---
+  const goal = parseGoalSection(sections.get('goal') ?? []);
+  const changes = parsePathEntrySection(
+    sections.get('changes') ?? [],
+    warnings,
+  );
+  const acceptance = parseTextListSection(sections.get('acceptance') ?? []);
+  const verify = parseTextListSection(sections.get('verify') ?? []);
+  const references = parsePathEntrySection(
+    sections.get('references') ?? [],
+    warnings,
+  );
   const dependsOn = extractBlockedBy(footer);
 
   // --- Recover wide / estimated_test_files from the meta block ---

package/.agents/scripts/providers/github/blocked-by-add.js

@@ -0,0 +1,252 @@
+/**
+ * GitHub Provider — shared "set native blocked-by dependency" helper.
+ *
+ * Story #4067 — after issue creation during Phase 8 decomposition, each
+ * Story's `depends_on` graph is known as a set of sibling slugs. This
+ * helper translates those slug-to-issueNumber pairs into native GitHub
+ * "blocked by" dependency edges so maintainers can see blocking
+ * relationships directly in the GitHub UI.
+ *
+ * API surface used:
+ *   Read:  GET  /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
+ *   Write: POST /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
+ *          body: { "issue_id": <integer db id of the blocking issue> }
+ *
+ * Contract:
+ *   - **Idempotent** — reads existing edges first; only POSTs missing ones.
+ *   - **Non-fatal** — catches all errors per edge, warns, and continues.
+ *     The overall function never throws; errors are returned in a summary.
+ *   - **No-op on empty input** — returns immediately when no depends_on
+ *     edges are present or the slug→issueNumber map is empty.
+ */
+
+import { Logger } from '../../lib/Logger.js';
+import { concurrentMap } from '../../lib/util/concurrent-map.js';
+import { parseApiJson } from './request-helpers.js';
+
+/**
+ * Bounded concurrency for the GitHub dependency-edge round-trips. Kept modest
+ * to respect GitHub's secondary rate limits while still collapsing the wall-
+ * clock latency from `sum(round-trips)` toward `sum(round-trips) / concurrency`.
+ */
+const EDGE_CONCURRENCY = 5;
+
+/**
+ * Fetch the existing blocked-by issue numbers for a given issue.
+ *
+ * Returns `[]` on any error so the caller falls back to posting the full
+ * set of missing edges (worst case: a duplicate POST, which GitHub
+ * handles idempotently).
+ *
+ * @param {{ gh: object, owner: string, repo: string, issueNumber: number }} opts
+ * @returns {Promise<number[]>} Database ids of the issues that currently block `issueNumber`.
+ */
+async function fetchExistingBlockedBy({ gh, owner, repo, issueNumber }) {
+  try {
+    const result = await gh.api({
+      method: 'GET',
+      endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
+    });
+    const data = parseApiJson(result);
+    if (!Array.isArray(data)) return [];
+    return data.map((item) => item?.id).filter((id) => typeof id === 'number');
+  } catch (err) {
+    Logger.warn(
+      `[blocked-by-add] Could not fetch existing blocked-by for #${issueNumber}: ${err.message}`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Set native GitHub "blocked by" dependency edges for a single issue.
+ *
+ * For each entry in `blockerInternalIds`, checks whether the edge already
+ * exists and POSTs only the missing ones. Every individual POST failure is
+ * caught, logged as a warning, and counted — the function never throws.
+ *
+ * @param {{
+ *   gh: object,
+ *   owner: string,
+ *   repo: string,
+ *   issueNumber: number,
+ *   blockerInternalIds: number[],
+ * }} opts
+ * @returns {Promise<{ added: number, skipped: number, failed: number }>}
+ */
+async function addBlockedByEdges({
+  gh,
+  owner,
+  repo,
+  issueNumber,
+  blockerInternalIds,
+}) {
+  if (blockerInternalIds.length === 0) {
+    return { added: 0, skipped: 0, failed: 0 };
+  }
+
+  const existing = await fetchExistingBlockedBy({
+    gh,
+    owner,
+    repo,
+    issueNumber,
+  });
+  const existingSet = new Set(existing);
+
+  // Partition up front so the skip count is deterministic regardless of the
+  // concurrent POST dispatch order, then POST only the missing edges in
+  // parallel under a modest cap.
+  const missing = blockerInternalIds.filter((id) => !existingSet.has(id));
+  const skipped = blockerInternalIds.length - missing.length;
+
+  const perEdge = await concurrentMap(
+    missing,
+    async (blockerId) => {
+      try {
+        await gh.api({
+          method: 'POST',
+          endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
+          body: { issue_id: blockerId },
+        });
+        return { added: 1, failed: 0 };
+      } catch (err) {
+        Logger.warn(
+          `[blocked-by-add] Failed to add blocked-by edge #${issueNumber} ← blocker(id=${blockerId}): ${err.message}`,
+        );
+        return { added: 0, failed: 1 };
+      }
+    },
+    { concurrency: EDGE_CONCURRENCY },
+  );
+
+  let added = 0;
+  let failed = 0;
+  for (const r of perEdge) {
+    added += r.added;
+    failed += r.failed;
+  }
+
+  return { added, skipped, failed };
+}
+
+/**
+ * Translate a Story's `depends_on` slug list into native GitHub "blocked
+ * by" dependency edges, given the slug→issueNumber map from the reconciler
+ * state and a `getTicket` hook to resolve database ids.
+ *
+ * Iterates every Story that has a non-empty `dependsOn` array; for each
+ * depended-on slug, resolves the blocker's issue number (via the slug map),
+ * then resolves the blocker's database id via `getTicket`, and calls
+ * `addBlockedByEdges`. Any failure at any step is caught, logged as a
+ * warning, and reflected in the returned summary — the function never
+ * throws.
+ *
+ * @param {{
+ *   stories: Array<{ slug: string, dependsOn?: string[] }>,
+ *   slugToIssueNumber: Record<string, number>,
+ *   getTicket: (issueNumber: number) => Promise<{ internalId: number }>,
+ *   owner: string,
+ *   repo: string,
+ *   gh: object,
+ * }} opts
+ * @returns {Promise<{
+ *   edgesAdded: number,
+ *   edgesSkipped: number,
+ *   edgesFailed: number,
+ *   storiesProcessed: number,
+ * }>}
+ */
+export async function applyBlockedByDependencies({
+  stories,
+  slugToIssueNumber,
+  getTicket,
+  owner,
+  repo,
+  gh,
+}) {
+  let edgesAdded = 0;
+  let edgesSkipped = 0;
+  let edgesFailed = 0;
+  let storiesProcessed = 0;
+
+  // Process each story's GET + its POST batch under one bounded concurrentMap
+  // so the per-story round-trips overlap. Each mapper returns its own counter
+  // contribution; we sum them after the pass. The bodies swallow their own
+  // errors (per-edge try/catch + the non-fatal contract), so concurrentMap
+  // never sees a rejection and the no-throw guarantee is preserved.
+  const perStory = await concurrentMap(
+    stories,
+    async (story) => {
+      const deps = Array.isArray(story.dependsOn) ? story.dependsOn : [];
+      if (deps.length === 0) {
+        return { added: 0, skipped: 0, failed: 0, processed: 0 };
+      }
+
+      const storyIssueNumber = slugToIssueNumber[story.slug];
+      if (typeof storyIssueNumber !== 'number') {
+        Logger.warn(
+          `[blocked-by-add] No issue number for story slug "${story.slug}"; skipping depends_on edges.`,
+        );
+        return { added: 0, skipped: 0, failed: 0, processed: 0 };
+      }
+
+      let failed = 0;
+      const blockerInternalIds = [];
+
+      for (const depSlug of deps) {
+        const blockerIssueNumber = slugToIssueNumber[depSlug];
+        if (typeof blockerIssueNumber !== 'number') {
+          Logger.warn(
+            `[blocked-by-add] depends_on slug "${depSlug}" (from "${story.slug}") has no mapped issue number; skipping edge.`,
+          );
+          failed++;
+          continue;
+        }
+        try {
+          const blocker = await getTicket(blockerIssueNumber);
+          if (typeof blocker?.internalId !== 'number') {
+            Logger.warn(
+              `[blocked-by-add] Blocker #${blockerIssueNumber} ("${depSlug}") has no internalId; skipping edge.`,
+            );
+            failed++;
+            continue;
+          }
+          blockerInternalIds.push(blocker.internalId);
+        } catch (err) {
+          Logger.warn(
+            `[blocked-by-add] Could not resolve blocker "${depSlug}" (#${blockerIssueNumber}): ${err.message}`,
+          );
+          failed++;
+        }
+      }
+
+      if (blockerInternalIds.length === 0) {
+        return { added: 0, skipped: 0, failed, processed: 1 };
+      }
+
+      const result = await addBlockedByEdges({
+        gh,
+        owner,
+        repo,
+        issueNumber: storyIssueNumber,
+        blockerInternalIds,
+      });
+      return {
+        added: result.added,
+        skipped: result.skipped,
+        failed: failed + result.failed,
+        processed: 1,
+      };
+    },
+    { concurrency: EDGE_CONCURRENCY },
+  );
+
+  for (const r of perStory) {
+    edgesAdded += r.added;
+    edgesSkipped += r.skipped;
+    edgesFailed += r.failed;
+    storiesProcessed += r.processed;
+  }
+
+  return { edgesAdded, edgesSkipped, edgesFailed, storiesProcessed };
+}

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

@@ -77,7 +77,7 @@ export function composeStoryBody({
 }) {
   const head = typeof body === 'string' ? body : '';
   const lines = ['---', `parent: #${parentId}`];
-  if (epicId !== undefined && epicId !== null && epicId !== parentId) {
+  if (epicId !== undefined && epicId !== null) {
     lines.push(`Epic: #${epicId}`);
   }
   if (dependencies.length > 0) {

package/.agents/scripts/single-story-init.js

@@ -36,7 +36,7 @@
  * @see .agents/workflows/helpers/single-story-deliver.md
  */
 
-import { spawnSync } from 'node:child_process';
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { parseSprintArgs } from './lib/cli-args.js';
@@ -109,12 +109,25 @@ const progress = Logger.createProgress('single-story-init', { stderr: true });
  * ripple into the single-story-sweep planner, which is intentionally out
  * of scope for the callers-only provider migration.
  *
+ * Story #4073: the `spawnImpl` seam injects the `spawnSync` boundary so the
+ * runner's success/error handling can be unit-tested without a live `gh`
+ * binary. It defaults to `child_process.spawnSync` (mirroring the
+ * `spawnImpl` seam in `lib/gh-exec.js` and the `runner` seam in
+ * `lib/bootstrap/gh-preflight.js`), so the production CLI path is unchanged.
+ * The synchronous `spawnSync` shape is preserved deliberately — the
+ * candidate-filter loop in `executeCleanup` is synchronous, so converting
+ * this to the async `lib/gh-exec.js` facade would ripple into the
+ * single-story-sweep planner.
+ *
  * @param {string} cwd Repo root used as the default spawn cwd.
+ * @param {typeof defaultSpawnSync} [spawnImpl] Injectable spawn boundary —
+ *   defaults to `child_process.spawnSync`. Tests pass a fake to assert the
+ *   error/exit-code handling without spawning a real child process.
  * @returns {(args: string[], opts?: { cwd?: string }) => string}
  */
-export function makeGhRunner(cwd) {
+export function makeGhRunner(cwd, spawnImpl = defaultSpawnSync) {
   return (args, opts) => {
-    const result = spawnSync('gh', args, {
+    const result = spawnImpl('gh', args, {
       cwd: opts?.cwd ?? cwd,
       encoding: 'utf-8',
       shell: false,

package/.agents/workflows/audit-architecture.md

@@ -129,6 +129,14 @@ legitimately have no layered architecture to guard.
 
 ## Step 2: Analysis Dimensions
 
+For every finding you surface, grade **Impact** on a High / Medium / Low axis
+reflecting the severity of the architectural risk (how much correctness,
+maintainability, or testability the gap erodes), independent of the
+**Category** effort axis — a Quick Win can still be High Impact, and a
+Structural Change can be Medium. As a loose default, Quick Wins typically land
+High (cheap to fix, real payoff) and Structural Changes Medium/High, but grade
+Impact on the risk itself rather than deriving it mechanically from Category.
+
 Evaluate the gathered context against the following clean code dimensions:
 
 1. **Over-Engineering & Abstractions:** Identify "dry-run" complexity, premature
@@ -294,6 +302,7 @@ marked `n/a`.]
 
 ### [Short Title of the Issue]
 
+- **Impact:** [High | Medium | Low]
 - **Category:** [Quick Win | Structural Change]
 - **Dimension:** [e.g., Cognitive Load & Nesting | Testable Surface (Humble-Object Boundary) | Automated Architecture Guardrails]
 - **Current State:** [The specific file/function and why it is problematic]

package/.agents/workflows/helpers/deliver-stories.md

@@ -192,7 +192,18 @@ Each Agent call:
 1. Names the Story ID and instructs the child to invoke
    [`helpers/single-story-deliver`](single-story-deliver.md)
    for that Story.
-2. States the **return contract** (see § 2c).
+2. States the **return contract** (see § 2c) and the **no-park rule**: the
+   child MUST drive the close → CI-watch → merge-confirm → `agent::done`
+   sequence to a terminal state *within its own turn* and end **only** by
+   returning the § 2c JSON object. The auto-merge wait is an
+   internally-blocking step (`gh pr checks --watch` blocks the turn), **not**
+   a reason to suspend and hand back. A child that ends its turn with
+   free-form prose and an unconfirmed merge (e.g. "I'll wait for the
+   background watch task…") has violated the contract — the wave loop cannot
+   advance, and the Story strands at `agent::closing` (the Story #1553 /
+   PR #1554 failure mode). There is no "pending" return status: the child
+   returns `done` (merge confirmed), `blocked` (transitioned + friction
+   posted), or `failed`.
 3. Reminds the child of the **non-interactive contract**: no clarifying
    questions — if stuck, transition to `agent::blocked`, post a
    `friction` comment, and exit non-zero.
@@ -209,7 +220,8 @@ Agent call has returned a result (success, blocked, or failed).
 
 ### 2c. Per-Story return contract
 
-Each child returns:
+Each child ends its turn by returning **exactly one** JSON object — never
+free-form prose:
 
 ```json
 {
@@ -223,6 +235,16 @@ Each child returns:
 }
 ```
 
+The status enum is **closed** — `done`, `blocked`, or `failed`. There is no
+"pending" / "waiting" status, because the close-phase auto-merge wait is
+**not** a returnable suspension: the child blocks on `gh pr checks --watch`
+*inside its own turn*, confirms the merge, flips `agent::done`, and only then
+returns `status: "done"`. A child that returns prose instead — parking on the
+CI wait with an unconfirmed merge — breaks the wave loop's ability to advance
+and leaves the Story at `agent::closing` (Story #1553 / PR #1554). The
+single-homed restatement of this no-park rule for the child's own perspective
+is [`single-story-deliver.md` § Step 7](single-story-deliver.md#return-contract).
+
 ### 2d. Wave outcome handling
 
 After every Story in a wave returns:

package/.agents/workflows/helpers/single-story-deliver.md

@@ -336,6 +336,26 @@ coverage rounding, platform-conditional branches, and timing-sensitive
 tests routinely drift between the two. The agent owns the green-CI
 outcome, not just the push.
 
+> **The auto-merge wait is an internally-blocking step, not a reason to end
+> your turn.** This is the single most important contract of this workflow,
+> and the seam where a worker most often misbehaves: it delivers up to arming
+> auto-merge, then ends its turn with **free-form prose** — e.g. "I'll wait
+> for the background watch task to complete" or "the next event will be its
+> completion notification" — leaving the merge unconfirmed and the Story
+> stranded at `agent::closing` (observed on Story #1553 / PR #1554). **Do not
+> do this.** `gh pr checks <prNumber> --watch` *blocks the current turn* until
+> CI resolves — that is the mechanism by which you wait. You MUST keep your
+> turn alive across the wait: watch → (fix + push + re-watch on red) → confirm
+> the merge (Step 5) → flip `agent::done` → run the post-merge steps → and
+> only then return the terminal JSON status contract (Step 4 of
+> [`deliver-stories.md` § 2c](deliver-stories.md), mirrored in
+> [§ Return contract](#return-contract) for the standalone caller). The CI
+> wait NEVER terminates your turn; **only** a confirmed-`MERGED` PR (→
+> `status: "done"`), an `agent::blocked` transition (→ `status: "blocked"`),
+> or an unrecoverable failure (→ `status: "failed"`) does. Ending your turn
+> with prose and an unconfirmed merge is a contract violation — it is the very
+> bug this workflow exists to prevent.
+
 After `single-story-close.js` succeeds, enter the watch + fix loop:
 
 ```bash
@@ -348,7 +368,9 @@ When the watch exits:
   still at `agent::closing` with its issue OPEN at this point (Step 3
   deferred the `agent::done` flip). The `Closes #<id>` footer closes the
   Story issue when the merge lands; Step 5 confirms the merge and Step 5.5
-  flips the Story to `agent::done`. Proceed to Step 5.
+  flips the Story to `agent::done`. **Proceed to Step 5 within the same
+  turn** — do not end your turn here. Green CI is the *start* of the
+  merge-confirm sequence, not a terminal state (see Step 7's no-park rule).
 - **Any check ✗** — diagnose, fix, and push a new commit on
   `story-<storyId>`, then re-watch. Auto-merge stays enabled across
   retries; no need to re-arm it. The Story stays at `agent::closing`
@@ -582,6 +604,67 @@ cleanup.
 
 ---
 
+## Step 7 — Return contract (**required when dispatched as a sub-agent**) {#return-contract}
+
+When this workflow runs as a per-Story sub-agent (dispatched by `/deliver`
+via [`deliver-stories.md` § 2a/2c](deliver-stories.md)), the **only**
+acceptable way to end your turn is to **return a single terminal JSON status
+object** — never free-form prose:
+
+```json
+{
+  "storyId": <number>,
+  "status": "done" | "blocked" | "failed",
+  "phase": "init|implementing|closing|blocked|done",
+  "branchDeleted": <boolean>,
+  "blockerCommentId": <string|null>,
+  "detail": "<one-liner: what changed + what was verified, e.g. PR #N merged>",
+  "renderedBody": "<terminal Story body>"
+}
+```
+
+This is the same envelope [`deliver-stories.md` § 2c](deliver-stories.md)
+mandates; this section is its single-homed restatement for the standalone
+worker so the contract is self-contained when this workflow is the entry
+point.
+
+**The auto-merge wait does not produce a fourth status.** There is no
+"pending" or "waiting" terminal — the CI/auto-merge wait is handled
+*internally* by blocking on `gh pr checks --watch` (Step 4) and confirming
+the merge (Step 5). You return **only** when you have reached a genuinely
+terminal state:
+
+- **`status: "done"`** — the PR is confirmed `state: "MERGED"` (Step 5),
+  the Story carries `agent::done`, and Steps 5.5 / 6 have run. `phase: "done"`,
+  `branchDeleted: true`.
+- **`status: "blocked"`** — you transitioned the Story to `agent::blocked`
+  and posted a `friction` comment (acceptance self-eval block in Step 1a, a
+  base-sync conflict, or an operator-blocking CI failure / Anti-Thrashing
+  stop in Step 4). `phase: "blocked"`, `blockerCommentId` set.
+- **`status: "failed"`** — an unrecoverable failure outside the blocked
+  protocol. `phase` reflects where it died.
+
+A turn that ends with prose ("I'll wait for the watch task…", "the next event
+will be its completion notification…") and an **unconfirmed merge** is a
+**contract violation** (the Story #1553 / PR #1554 failure mode): the parent
+wave loop cannot distinguish "still working" from "done but silent", and the
+Story strands at `agent::closing`. If you genuinely cannot confirm the merge,
+that is a `blocked` or `failed` outcome with the JSON contract above — not a
+prose hand-off.
+
+> **Handoff discipline — report state, not process.** Populate the envelope
+> with essential terminal state only (mirroring the fields
+> `single-story-close.js` / `story-phase.js` already emit). Do not narrate the
+> steps you took, and do not prescribe how the next stage should work. Prose
+> process commentary only bloats the hydrated prompt
+> (`delivery.maxTokenBudget` elision). When run **interactively** (no parent
+> aggregator), this JSON envelope is optional — relay terminal state to the
+> operator in prose instead — but the **no-park rule still holds**: never end
+> an interactive turn with an unconfirmed merge either; block on the watch,
+> confirm, and report the merged outcome.
+
+---
+
 ## Idempotence
 
 - `single-story-init.js` re-prints the same `workCwd` without recreating

package/README.md

@@ -163,7 +163,7 @@ Deeper reference material lives in `docs/` rather than inline here:
 - [`.agents/docs/workflows.md`](.agents/docs/workflows.md) — slash-command
   index (auto-generated from the workflow set).
 - [`docs/CHANGELOG.md`](docs/CHANGELOG.md) — release history.
-- [`AGENTS.md`](AGENTS.md) — repository onboarding, the two-package release
+- [`AGENTS.md`](AGENTS.md) — repository onboarding, the single-package release
   topology, PAT / npm-token setup, and major-version policy. Releases are
   automated by `release-please`: land Conventional Commits on `main` and it
   opens a combined `chore: release main` PR that squash-merges itself once