mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -3,7 +3,10 @@ import { detectCycle } from '../Graph.js';
 import { gitSpawn } from '../git-utils.js';
 
 import { Logger } from '../Logger.js';
-import { parse as parseStoryBody } from '../story-body/story-body.js';
+import {
+  parse as parseStoryBody,
+  StoryBodyParseError,
+} from '../story-body/story-body.js';
 import { validateStoryFileAssumptions } from './file-assumptions.js';
 import {
   computeConflictFindings,
@@ -11,14 +14,9 @@ import {
 } from './ticket-validator-conflicts.js';
 import {
   computeSizingFindings,
-  DEFAULT_TASK_SIZING,
   renderHardFindingError,
 } from './ticket-validator-sizing.js';
 
-// Re-exported for callers that want the constants without reaching into the
-// sizing helper module directly.
-export { DEFAULT_TASK_SIZING };
-
 /**
  * Regex matching code-asset paths the freshness gate cares about. The three
  * roots — `.agents/scripts`, `lib`, and `tests` — cover the executable surface
@@ -48,6 +46,95 @@ function collectPathsFromText(text, paths) {
   }
 }
 
+/**
+ * Parse a Story's serialized markdown body, translating a
+ * `StoryBodyParseError` into a `ValidationError` that names the offending
+ * **section** and **entry** (Story #4541).
+ *
+ * `StoryBodyParseError` already carries `field` (the section the parser was
+ * reading) and `raw` (the entry text that failed); this lifts both into an
+ * operator-legible message and a structured `violation` payload so an
+ * authoring loop can point at the exact bullet instead of re-deriving it
+ * from a downstream freshness miss.
+ *
+ * @param {object} story Story whose `body` is a non-empty markdown string.
+ * @returns {object} The structured body.
+ * @throws {ValidationError} `code: 'story-body-unparseable'`.
+ */
+function parseStoryBodyOrThrow(story) {
+  try {
+    return parseStoryBody(story.body).body;
+  } catch (err) {
+    if (!(err instanceof StoryBodyParseError)) throw err;
+    const slug = story.slug ?? '<unknown>';
+    const section = err.field ?? 'body';
+    const entry = err.raw ?? null;
+    const entryLine = entry === null ? '' : `\n      entry: ${entry}`;
+    const violation = { slug, section, entry, reason: err.message };
+    const error = new ValidationError(
+      `Cross-Validation Failed: Story "${slug}" has an unparseable body — ` +
+        `the ## ${section} section could not be read: ${err.message}` +
+        `${entryLine}\n\nFix the offending entry; this is a malformed body, ` +
+        'not a stale path reference.',
+      { violations: [violation] },
+    );
+    error.code = 'story-body-unparseable';
+    error.violations = [violation];
+    throw error;
+  }
+}
+
+/**
+ * Refuse the plan when any Story's serialized body cannot be parsed, before
+ * either git-probe gate runs (Story #4541). Ordering matters: the freshness
+ * gate consults `body.changes` for its net-new whitelist, so an unparseable
+ * body used to reach the operator as a freshness miss naming declared paths.
+ *
+ * @param {{ tickets: object[] }} opts
+ * @throws {ValidationError} `code: 'story-body-unparseable'` on the first
+ *   offending Story.
+ */
+function assertStoryBodiesParse({ tickets }) {
+  for (const story of (tickets ?? []).filter((t) => t.type === 'story')) {
+    if (typeof story.body !== 'string' || story.body.trim().length === 0) {
+      continue;
+    }
+    parseStoryBodyOrThrow(story);
+  }
+}
+
+/**
+ * Resolve every acceptance line a Story declares, across both authoring
+ * shapes (Story #4541).
+ *
+ * The canonical shape is a **serialized string body** with the criteria at
+ * the ticket's **top level** — the machine contract persist syncs into the
+ * body. `validateAcceptanceSubjectPrefix` used to read `body.acceptance` on
+ * an object body only, so on every real plan it scanned nothing and the gate
+ * silently passed. Union both sources (deduplicated) so the gate fires on
+ * whichever surface the author used.
+ *
+ * @param {object} story
+ * @returns {string[]}
+ */
+function resolveAcceptanceLines(story) {
+  const lines = new Set();
+  if (Array.isArray(story?.acceptance)) {
+    for (const item of story.acceptance) lines.add(String(item ?? ''));
+  }
+  const body = story?.body;
+  let bodyAcceptance = null;
+  if (typeof body === 'string' && body.trim().length > 0) {
+    bodyAcceptance = parseStoryBodyOrThrow(story).acceptance;
+  } else if (body !== null && typeof body === 'object') {
+    bodyAcceptance = body.acceptance;
+  }
+  if (Array.isArray(bodyAcceptance)) {
+    for (const item of bodyAcceptance) lines.add(String(item ?? ''));
+  }
+  return [...lines];
+}
+
 function collectTaskPathReferences(task) {
   const paths = new Set();
   const body = task.body;
@@ -87,7 +174,7 @@ function collectTaskPathReferences(task) {
  *    path out of the prose.
  * 3. **Object form** — `{ path: "<path>", assumption: "creates" | ... }`,
  *    introduced by Story #2636 as the canonical declaration shape and
- *    documented in `epic-plan-decompose-author/SKILL.md`. The path is
+ *    documented in `lib/templates/decomposer-prompts.js`. The path is
  *    trusted verbatim.
  *
  * Only `body.changes` (and `body.references`) is consulted —
@@ -105,15 +192,16 @@ function collectTaskChangesPaths(task) {
   // arrays before scanning. Without this, a string body causes the
   // object-form branch below to fall through on every item, leaving the
   // freshness gate blind to declared paths.
+  //
+  // Story #4541: a parse failure is NOT swallowed here. Swallowing it
+  // returned an empty whitelist, so a single malformed `## Changes` entry
+  // surfaced downstream as "files do not exist at main" naming the very
+  // paths the Story *had* declared — a misdiagnosis that cost two authoring
+  // round-trips. `assertStoryBodiesParse` runs before the freshness gate and
+  // owns that failure with a named error; the throw here is the same error
+  // for any caller that drives `validateAcFreshness` directly.
   if (typeof body === 'string' && body.trim().length > 0) {
-    let parsed;
-    try {
-      parsed = parseStoryBody(body).body;
-    } catch {
-      // Unparseable body — no paths to whitelist; the freshness gate will
-      // catch any real references in the text scan below.
-      return paths;
-    }
+    const parsed = parseStoryBodyOrThrow(task);
     for (const arrName of ['changes', 'references']) {
       const arr = parsed[arrName];
       if (!Array.isArray(arr)) continue;
@@ -312,11 +400,16 @@ const SUBJECT_PREFIX_RE = /Commit subject begins with ['"`]([^'"`]+):['"`]/g;
  * the form `baseline-refresh` is rejected because no Conventional-Commits
  * type starts with that token.
  *
- * Only `body.acceptance[]` is scanned; `body.goal` / `body.verify` /
+ * Only acceptance criteria are scanned; `body.goal` / `body.verify` /
  * `body.changes` are not commit-subject prescriptions by convention and
  * scanning them would surface false positives from prose that happens to
  * quote a forbidden prefix while explaining why it's forbidden.
  *
+ * Both authoring shapes are covered (Story #4541): the canonical top-level
+ * `acceptance[]` on a serialized string body, and the pre-serialize
+ * `body.acceptance[]` object shape. Scanning only the latter made the gate
+ * inert on every real plan.
+ *
  * @param {object}   opts
  * @param {object[]} opts.tickets - Validated ticket hierarchy.
  * @throws {ValidationError} when one or more Story acceptance items
@@ -329,11 +422,7 @@ export function validateAcceptanceSubjectPrefix({ tickets }) {
   const violations = [];
   const stories = (tickets ?? []).filter((t) => t.type === 'story');
   for (const story of stories) {
-    const body = story.body;
-    if (body === null || typeof body !== 'object') continue;
-    if (!Array.isArray(body.acceptance)) continue;
-    for (const item of body.acceptance) {
-      const line = String(item ?? '');
+    for (const line of resolveAcceptanceLines(story)) {
       // Reset the global regex between iterations.
       SUBJECT_PREFIX_RE.lastIndex = 0;
       let match = SUBJECT_PREFIX_RE.exec(line);
@@ -386,8 +475,8 @@ function renderMissLine({ slug, path }) {
  * The returned tickets array carries two extra non-array properties:
  *   - `findings` — structured sizing findings (hard + soft) keyed by the
  *     three-layer sizing model. The bounded re-decomposition loop in
- *     `epic-plan-decompose` reads `findings.filter(f => f.severity === 'hard')`
- *     to decide whether to re-prompt.
+ *     `/plan` reads `findings.filter(f => f.severity === 'hard')` to decide
+ *     whether to re-prompt.
  *   - `errors`   — human-readable strings, one per hard finding. Non-empty
  *     `errors[]` is the AC-visible "block normalization" signal; the legacy
  *     hierarchy/cycle/freshness checks continue to throw, so callers that
@@ -399,7 +488,7 @@ function renderMissLine({ slug, path }) {
  * @param {string}                     [opts.baseBranchRef] - When set, runs `validateAcFreshness` against this ref.
  * @param {Function}                   [opts.gitRunner]     - Optional git probe override.
  * @param {string}                     [opts.cwd]           - Repo cwd (forwarded to the freshness gate).
- * @param {object}                     [opts.taskSizing]    - Override the three-layer sizing thresholds. Defaults to `DEFAULT_TASK_SIZING`.
+ * @param {object}                     [opts.modelCapacity] - Programmatic override of `DEFAULT_MODEL_CAPACITY` (tests only — not read from `.agentrc.json`).
  * @param {object}                     [opts.conflictPolicy] - Severity controls for cross-Story conflict findings.
  * @param {boolean}                    [opts.conflictPolicy.failOnSharedEditors=false]          - Upgrade `shared-editor` findings to `hard`.
  * @param {boolean}                    [opts.conflictPolicy.requireExplicitCrossStoryDeps=false] - Upgrade `implicit-cross-story-dep` findings to `hard`.
@@ -545,6 +634,14 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
 
   assertAcyclic(slugAdjacency);
 
+  // Story #4541 — refuse an unparseable Story body up front, with a named
+  // error pointing at the offending section + entry. Must precede both the
+  // subject-prefix scan and the freshness gate: each parses the body, and
+  // the freshness gate's net-new whitelist comes from `body.changes`, so a
+  // malformed body used to surface as a stale-path miss naming the paths the
+  // Story had legitimately declared.
+  assertStoryBodiesParse({ tickets });
+
   // Reject any Task acceptance item that prescribes a non-Conventional-Commits
   // subject prefix (e.g. legacy "Commit subject begins with 'baseline-refresh:'"
   // from pre-Epic-#2501 planner output). Runs before the freshness gate so
@@ -614,7 +711,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
 
   const sizingFindings = computeSizingFindings({
     stories,
-    sizing: opts.taskSizing,
+    capacity: opts.modelCapacity,
   });
   // Cross-Story path-conflict pass observes the story-level depends_on
   // graph. Findings are appended to the same `findings` array consumed by
@@ -653,6 +750,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
 
 // Internal helpers exposed for unit tests; not part of the public surface.
 export const _internal = {
+  assertStoryBodiesParse,
   indexTicketsBySlug,
   assertAllTicketsAreStories,
   assertEveryStoryHasInlineContract,

package/.agents/scripts/lib/orchestration/ticketing/bulk.js

@@ -20,7 +20,6 @@
  */
 
 import { Logger } from '../../Logger.js';
-import { TYPE_LABELS } from '../../label-constants.js';
 import { ALL_STATES, STATE_LABELS } from './reads.js';
 import {
   postStructuredComment,
@@ -290,30 +289,6 @@ async function processCascadeParentLocked(
     );
     if (!allDone) return { cascadedTo, failed };
 
-    // EXCLUSION: Epics do not auto-close via cascade. Epics close via
-    // formal /deliver (its own machinery handles branch merges,
-    // PR-driven `Closes #N` auto-close, and a recovery transition in
-    // `epic-deliver-finalize.js`).
-    //
-    // Legacy planning tickets (pre-#4324 `context::*` artifacts on
-    // historical Epics) DO close via cascade (Story #1951): leaving
-    // them open as native sub-issues of the Epic blocks GitHub from
-    // honoring the Epic's `Closes #N` footer. New Epics carry their
-    // planning content on the Epic body itself, so this branch is
-    // purely a legacy-hygiene path.
-    //
-    // Reuse the parentSnapshot from the idempotency check above — it is
-    // a fresh read (cache was invalidated before the getTicket call) and
-    // the parent's type label is invariant within a single cascade lock
-    // hold, so a second getTicket is wasteful and redundant.
-    const isEpic = parentSnapshot.labels.includes(TYPE_LABELS.EPIC);
-    if (isEpic) {
-      logger.warn(
-        `[Ticketing] Cascade reached Epic #${parentId}. Skipping auto-close (Epics close via the operator's PR merge).`,
-      );
-      return { cascadedTo, failed };
-    }
-
     // Retry the parent transition on transient `gh` failures (rate limit,
     // 5xx, transport timeouts). Permanent failures fall through to the
     // outer catch on the first attempt so the operator sees the real
@@ -382,7 +357,7 @@ async function processCascadeParentLocked(
  *   unset so the module-level {@link Logger} is used.
  * @returns {Promise<{ cascadedTo: number[], failed: Array<{ parentId: number, error: string }> }>}
  */
-export async function cascadeCompletion(provider, ticketId, opts = {}) {
+async function cascadeCompletion(provider, ticketId, opts = {}) {
   const ticket = await provider.getTicket(ticketId);
 
   // Determine if this ticket is agent::done
@@ -390,43 +365,14 @@ export async function cascadeCompletion(provider, ticketId, opts = {}) {
     return { cascadedTo: [], failed: [] };
   }
 
+  // Story #4545 — one strategy, not three. The `parent: #N` body footer and
+  // the native sub-issue link were both written by `createTicket`, the
+  // Epic-hierarchy write surface deleted in the same Story; with no writer,
+  // the body regex could only ever miss and the native lookup could only
+  // ever spend an API call to learn the same. The operator-settable `blocks`
+  // annotation is the one parent edge that can still exist.
   const { blocks: parentIds } = await provider.getTicketDependencies(ticketId);
-
-  // Fallback: parse `parent: #NNN` from the body when `blocks` syntax isn't used (C-5).
-  let parsedParents = parentIds;
-  if (!parsedParents || parsedParents.length === 0) {
-    const parentMatch = ticket.body
-      ? [...ticket.body.matchAll(/parent:\s*#(\d+)/gi)]
-      : [];
-    parsedParents = parentMatch.map((m) => Number.parseInt(m[1], 10));
-  }
-
-  // Story #2982 — third fallback: GitHub's native Sub-Issues API. The
-  // resume reconciler can strip the `parent: #N` orchestrator footer
-  // from a Story body (see Issue 2 in #2982); without the body marker
-  // the cascade silently returned `{ cascadedTo: [], failed: [] }` and
-  // left intermediate parent tickets stranded OPEN. The native link is
-  // independent of body text, so consult it when the first two
-  // strategies came back empty.
-  if (
-    parsedParents.length === 0 &&
-    typeof provider._getNativeParent === 'function' &&
-    ticket.nodeId
-  ) {
-    try {
-      const nativeParent = await provider._getNativeParent(
-        ticket.nodeId,
-        ticketId,
-      );
-      if (typeof nativeParent === 'number') {
-        parsedParents = [nativeParent];
-      }
-    } catch (err) {
-      Logger.warn(
-        `[cascadeCompletion] native parent lookup failed for #${ticketId}: ${err.message}`,
-      );
-    }
-  }
+  const parsedParents = Array.isArray(parentIds) ? parentIds : [];
 
   if (parsedParents.length === 0) {
     return { cascadedTo: [], failed: [] };
@@ -562,22 +508,18 @@ export async function cascadeParentState(provider, ticketId, opts = {}) {
 }
 
 /**
- * Resolve the parent issue ids for a ticket: native `blocks:` dependency
- * annotations first, then `parent: #NNN` body references as a fallback.
- * Mirrors the resolution path used by {@link cascadeCompletion}.
+ * Resolve the parent issue ids for a ticket from its `blocks:` dependency
+ * annotations. Mirrors the resolution path used by {@link cascadeCompletion}
+ * — see there for why the `parent: #NNN` body fallback is gone (Story #4545).
  *
  * @param {import('../../ITicketingProvider.js').ITicketingProvider} provider
- * @param {object} ticket
+ * @param {object} _ticket
  * @param {number} ticketId
  * @returns {Promise<number[]>}
  */
-async function resolveParentIds(provider, ticket, ticketId) {
+async function resolveParentIds(provider, _ticket, ticketId) {
   const { blocks: parentIds } = await provider.getTicketDependencies(ticketId);
-  if (Array.isArray(parentIds) && parentIds.length > 0) return parentIds;
-  const parentMatch = ticket?.body
-    ? [...ticket.body.matchAll(/parent:\s*#(\d+)/gi)]
-    : [];
-  return parentMatch.map((m) => Number.parseInt(m[1], 10));
+  return Array.isArray(parentIds) ? parentIds : [];
 }
 
 /**

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -12,7 +12,8 @@
  */
 
 import { AGENT_LABELS } from '../../label-constants.js';
-import { WAVE_MARKER_RE } from '../wave-marker.js';
+
+const WAVE_MARKER_RE = /^wave-([0-9]{1,3})-(start|end)$/;
 
 /**
  * Canonical agent-state label triad used by every state mutator. Kept on
@@ -23,7 +24,7 @@ export const STATE_LABELS = {
   READY: AGENT_LABELS.READY,
   EXECUTING: AGENT_LABELS.EXECUTING,
   // Story #2144 — intermediate state held by a Story between successful
-  // close-preflight and a confirmed merge into `epic/<id>`. Included in
+  // close-preflight and a confirmed Story PR merge into `main`. Included in
   // the state enum so `transitionTicketState` can apply the label via
   // the canonical one-state-at-a-time path (which removes every other
   // `agent::*` label in the same call) and so the read-side `ALL_STATES`
@@ -72,35 +73,24 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'verification-results',
   'retro',
   'retro-partial',
+  // v2 Story closeout — actionable follow-ups from friction signals
+  'follow-ups',
+  // v2 plan-run epilogue artifacts (posted on the primary Story)
+  'plan-run-audit-roster',
+  'plan-run-sibling-coherence',
   'epic-run-state',
   'epic-run-progress',
   'epic-plan-state',
   'parked-follow-ons',
-  'dispatch-manifest',
-  // Story #566 — per-phase wall-clock summary posted by story-close
-  // and consumed by the epic-runner progress reporter to surface median /
-  // p95 phase timings across completed stories.
+  // Story #566 — per-phase wall-clock summary posted by single-story-close.js.
   'phase-timings',
   // Story #831 — story-init upserts a `story-init` comment that
   // surfaces `dependenciesInstalled` (and the underlying installStatus) so
   // downstream workflow steps don't have to infer install state from
   // node_modules presence.
   'story-init',
-  // Story #908 — /deliver upserts a `story-run-progress` snapshot
-  // on each Story per Task transition. The /deliver aggregator and
-  // the epic-runner progress reporter both read this comment to derive
-  // Story-level state without re-fetching ticket labels.
-  'story-run-progress',
-  // Story #1123 — analyze-execution.js upserts perf summaries at close
-  // time. Story-mode posts `story-perf-summary` on each Story; Epic-mode
-  // posts `epic-perf-report` on the Epic. Both replace the legacy
-  // per-Task `friction` fan-out and the standalone `phase-timings`
-  // surface (Epic #1030).
-  'story-perf-summary',
-  'epic-perf-report',
-  // Story #2128 — Phase 6 Epic Clarity Gate. `epic-plan-clarity.js` upserts
-  // a `clarity-gate-update` comment on the Epic when the operator approves
-  // a sharpened body rewrite, recording the persistence event for audit.
+  // Story #2128 — Phase 6 Epic Clarity Gate (CLI retired). Historical
+  // `clarity-gate-update` comments may still exist on older tickets.
   'clarity-gate-update',
   // Story #2635 — Tech Spec freshness check. `plan-persist.js`
   // upserts a `spec-freshness` comment on the Epic listing any
@@ -126,40 +116,34 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // ticket. Re-invocations upsert the same marker rather than appending
   // duplicates.
   'epic-handoff',
-  // Story #2899 (Epic #2880, F13) — `epic-deliver-preflight.js` upserts a
-  // `delivery-preflight` comment on the Epic at the start of
-  // /deliver Phase 1, surfacing estimated story count, install cost,
+  // Story #2899 (Epic #2880, F13) — the deleted `epic-deliver-preflight.js`
+  // upserted a `delivery-preflight` comment on the Epic at the start of
+  // pre-v2 Epic `/deliver` Phase 1, surfacing estimated story count, install cost,
   // wave count, GitHub API request volume, Claude quota burn, and any
   // threshold breaches against `delivery.preflight.max*`. One entry per
   // Epic; re-runs replace prior content.
   'delivery-preflight',
-  // Story #3062 (Epic #3051) — `wave-tick.js` upserts a
+  // Story #3062 (Epic #3051) — the deleted `wave-tick.js` upserted a
   // `recurring-failure-class` comment on the Epic when the cross-Story
   // detector finds two or more Stories that hit the same `failedGate` in
   // `close-validate.end`. One entry per Epic; re-ticks with the same
   // findings upsert in place (`upsertStructuredComment` diffs by body).
   'recurring-failure-class',
-  // Story #3061 (Epic #3051) — the /deliver §2e Idle Watchdog
-  // subsection instructs the parent host LLM to upsert a `wave-stall`
-  // comment on the Epic whenever an in-flight Story has been silent for
-  // longer than the configured cadence. `wave-tick.js --check-idle`
-  // emits the matching envelope; registering the kind here is what makes
+  // Story #3061 (Epic #3051) — the pre-v2 `/deliver` idle-watchdog prose
+  // instructed the parent host LLM to upsert a `wave-stall` comment on the
+  // Epic whenever an in-flight Story had been silent for longer than the
+  // configured cadence. The deleted `wave-tick.js --check-idle` CLI emitted
+  // the matching envelope; registering the kind here keeps historical
   // the documented remediation actually executable
   // (assertValidStructuredCommentType would otherwise throw).
   'wave-stall',
-  // Story #3873 (Epic #3865) — `plan-persist.js` upserts a `risk-verdict`
-  // comment on the Epic at persist time, recording the planner-authored,
-  // schema-validated risk verdict and the planningRisk envelope derived
-  // from it (`deriveRiskEnvelope`). One entry per Epic; re-plans upsert in
-  // place. Schema: `.agents/schemas/risk-verdict.schema.json`.
-  'risk-verdict',
-  // Story #4019 — `epic-plan-lease-guard.js` upserts a `plan-lease`
-  // comment on the Epic at lease-acquire time, recording the claiming
-  // operator and the claim timestamp. `/plan` emits no
-  // `story.heartbeat`, so this claim-time is the liveness signal that
-  // makes the documented `--steal` contract decidable: a foreign claim
-  // older than the lease TTL is reclaimed automatically; a fresh one
-  // refuses with the claim age. One entry per Epic; re-acquires upsert
+  // Story #4019 — the plan-tier lease guard upserts a `plan-lease`
+  // comment at lease-acquire time, recording the claiming operator and the
+  // claim timestamp. Nothing emits a per-run liveness beat, so this
+  // claim-time is the only age signal a reader has when reasoning about the
+  // documented `--steal` contract. The guard itself fails closed regardless
+  // (it anchors liveness to `now`), so a stranded claim is cleared with
+  // `--steal`, not by TTL expiry. One entry per ticket; re-acquires upsert
   // in place.
   'plan-lease',
   // Story #4415 (Epic #4406) — the feedback-loop graduators
@@ -171,15 +155,21 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // `graduator="audit-results|code-review"` attr so the two graduators
   // upsert independent comments; re-runs upsert in place.
   'cross-repo-deferred',
-  // Epic #4474 (PR3) — `plan-persist.js` upserts a single `plan-summary`
-  // comment on the Epic at terminal persist success, carrying the risk /
-  // routing / freshness / healthcheck receipts and the dry-run wave table
-  // as closing text. Replaces the retired plan-time `dispatch-manifest`
-  // comment (whose claimed consumer did not exist — the live manifest is
-  // written at deliver time by `wave-record-io.js`) and the Phase 12
-  // notify round-trip. One entry per Epic; a --force/--resume re-persist
-  // upserts in place.
+  // Epic #4474 (PR3) / v2 Stage 3 — `plan-persist.js` upserts a single
+  // `plan-summary` comment on the primary Story at terminal persist
+  // success, carrying risk / routing receipts and the depends_on order
+  // table. One entry per plan; a re-persist upserts in place.
   'plan-summary',
+  // v2 Stage 3 — flat Story persist checkpoint on every created Story
+  // (replaces epic-plan-state for new plans). plan-summary stays primary-only.
+  'story-plan-state',
+  // Story #4535 — `plan-persist.js` upserts a `superseded-by` comment on
+  // each `/plan --tickets` source issue at persist time, naming the single
+  // Story that claims it (plus any per-supersede note the plan authored),
+  // immediately before closing the issue as `not_planned`. Keying off this
+  // marker rather than a bare `postComment` is what makes a re-run
+  // non-double-commenting. One entry per source issue.
+  'superseded-by',
 ]);
 
 export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;
@@ -265,8 +255,8 @@ export function structuredCommentMarker(type, attrs = null) {
  * recent `findStructuredComment` / `upsertStructuredComment` call.
  * Story #1795 — every Epic run owns its process for the duration of
  * the run, so a single seed-then-reuse window saves one
- * `getTicketComments` per repeat upsert on the hot path (wave-level
- * `story-run-progress`, `wave-N-end`, etc).
+ * `getTicketComments` per repeat upsert on the hot path (`story-init`,
+ * `verification-results`, etc).
  *
  * Lifecycle:
  *   - First call to `findStructuredComment(provider, t, type, attrs)`
@@ -352,8 +342,8 @@ export function structuredCommentCacheKey(ticketId, type, attrs) {
  * array returned by the most recent `provider.getTicketComments(ticketId)`
  * call. Story #2465 — `findStructuredComment` is invoked back-to-back for
  * different `type` discriminators against the same ticket (e.g.
- * `story-run-progress` + `epic-run-progress` + a `friction` probe during
- * an Epic-close wave). Without this cache each lookup pays a full
+ * `story-init` + `verification-results` + a `friction` probe during a
+ * single close). Without this cache each lookup pays a full
  * pagination round-trip even when the prior call already fetched the
  * same comments. The structured-comment-id cache short-circuits *repeat*
  * lookups for the same `(type, attrs)` tuple but does not help across

package/.agents/scripts/lib/orchestration/ticketing/transition.js

@@ -37,6 +37,10 @@ import {
   eventSeverity,
   renderTransitionMessage,
 } from '../../notifications/notifier.js';
+import {
+  emitRuntimeFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../../observability/runtime-friction.js';
 import { ColumnSync } from '../column-sync.js';
 import {
   ALL_STATES,
@@ -145,11 +149,11 @@ async function loadTicketSnapshot(provider, opts, ticketId) {
 /**
  * Mirror the post-flip label set onto the GitHub Projects v2 Status
  * column. Story #2548 — wiring this here makes every caller of
- * `transitionTicketState` (story-init, story-close, story-phase,
- * the LabelTransitioner lifecycle listener, the update-ticket-state CLI,
- * batch transitions) update the board automatically. Prior to #2548 the
- * sync was only wired from the epic-runner against the Epic ticket, so
- * Stories and Tasks never had their `agent::executing` /
+ * `transitionTicketState` (`single-story-init.js`, `single-story-close.js`,
+ * `story-phase.js`, the LabelTransitioner lifecycle listener, the
+ * update-ticket-state CLI, batch transitions) update the board automatically.
+ * Prior to #2548 the sync was only wired from the deleted epic-runner against
+ * the Epic ticket, so Stories and Tasks never had their `agent::executing` /
  * `agent::blocked` flips reflected on the board.
  *
  * Best-effort: a project-board misconfig, missing scope, or transient
@@ -279,6 +283,46 @@ function dispatchTransitionNotification(args) {
   });
 }
 
+/**
+ * Emit a runtime-derived `friction` signal when a ticket parks at
+ * `agent::blocked` (Story #4578). No-op for every other target state.
+ *
+ * Why here: `agent::blocked` is the single runtime HITL pause point
+ * (`.agents/instructions.md` § 1.J), and this is its canonical mutator — so
+ * one hook catches every block regardless of which path drove it (the
+ * `merge.unlanded` and `merge.flip-failed` paths in
+ * `single-story-close/phases/confirm-merge.js`, the review-block path, an
+ * operator's `update-ticket-state.js`, a Story worker giving up). Before
+ * this, a block was only ever a *label* — it left no trace in the friction
+ * stream the retro reads, so a run could park a worker and still produce a
+ * zero-signal roll-up.
+ *
+ * This is also why the terminal-envelope hook deliberately skips `blocked`
+ * (see `frictionForTerminal`): the two would otherwise count one incident
+ * twice.
+ *
+ * Best-effort and awaited: `emitRuntimeFriction` swallows its own failures
+ * and resolves `false`, so this can neither throw nor block the transition.
+ * It is awaited rather than fire-and-forget because CLI entry points exit
+ * via `process.exit` as soon as `main` resolves (`cli-utils.runAsCli` with
+ * `propagateExitCode`), which would discard a still-pending append.
+ *
+ * @param {number} ticketId
+ * @param {string} newState
+ * @param {{ config?: object }} opts
+ * @returns {Promise<void>}
+ */
+async function emitBlockedFriction(ticketId, newState, opts) {
+  if (newState !== STATE_LABELS.BLOCKED) return;
+  await emitRuntimeFriction({
+    storyId: ticketId,
+    category: RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED,
+    tool: 'transitionTicketState',
+    details: { toState: newState },
+    config: opts?.config,
+  });
+}
+
 /**
  * Transitions a ticket's label to the new state.
  * Removes other agent:: state labels.
@@ -361,6 +405,10 @@ export async function transitionTicketState(
     _ticketSnapshot: ticketSnapshot,
   });
 
+  // Story #4578 — derive a friction signal from the block, at the point the
+  // runtime already knows. Best-effort; never blocks the transition.
+  await emitBlockedFriction(ticketId, newState, opts);
+
   // Story #2548 — mirror the new state onto the Projects v2 Status
   // column. Best-effort; never blocks the transition.
   // Story #3645 — thread the DIP seam so callers can inject a stub.
@@ -460,14 +508,25 @@ export async function toggleTasklistCheckbox(
 /**
  * Post a structured comment to a ticket.
  *
+ * Returns whatever the provider's `postComment` resolved to (Story #4543).
+ * Previously the result was swallowed, which made it impossible for a caller
+ * to reference the comment it had just written — the terminal envelope's
+ * `blocked.frictionCommentId` pointer needs exactly that, so an operator can
+ * be sent straight to the remediation instead of told to go find it. Callers
+ * that don't need the id simply ignore the return, so this is additive.
+ *
+ * The shape is provider-defined and may be `undefined` for providers that do
+ * not surface one; callers must treat the id as best-effort.
+ *
  * @param {import('../../ITicketingProvider.js').ITicketingProvider} provider
  * @param {number} ticketId
  * @param {'progress'|'friction'|'notification'} type
  * @param {string} payload
+ * @returns {Promise<unknown>} The provider's `postComment` result.
  */
 export async function postStructuredComment(provider, ticketId, type, payload) {
   assertValidStructuredCommentType(type);
-  await provider.postComment(ticketId, {
+  const posted = await provider.postComment(ticketId, {
     type,
     body: payload,
   });
@@ -475,4 +534,5 @@ export async function postStructuredComment(provider, ticketId, type, payload) {
   // `findStructuredComment` against this ticket re-fetches and sees the
   // freshly-posted comment.
   invalidateRawCommentsCache(provider, ticketId);
+  return posted;
 }

package/.agents/scripts/lib/orchestration/ticketing.js

@@ -26,7 +26,6 @@
 export {
   __resetParentCascadeLocks,
   __setCascadeRetryDelays,
-  cascadeCompletion,
   logCascadePartialFailures,
 } from './ticketing/bulk.js';
 // Re-export the read surface.