mandrel 2.53.0 → 2.54.0

package/.agents/scripts/lib/orchestration/epic-rollup.js

@@ -40,6 +40,7 @@
  * @module lib/orchestration/epic-rollup
  * @see Story #5205
  * @see Story #5210 — fail closed on a degraded child read.
+ * @see Story #5255 — a closed child contributes no `agent::*` state.
  */
 
 import { Logger } from '../Logger.js';
@@ -58,6 +59,13 @@ import { deriveParentState } from './ticketing/bulk.js';
  * Epic carries an owner. `agent::blocked` counts: a blocked child is still
  * this operator's problem, and dropping the assignee at the moment someone
  * needs to be found would invert the signal.
+ *
+ * "Blocked" here means an **open** blocked child. `deriveParentState` stopped
+ * reading closed children's `agent::*` labels in Story #5255 — a superseded
+ * Story closed while still wearing `agent::blocked` is not someone's problem
+ * to pick up, and the stale label used to derive `agent::blocked` forever,
+ * which both held an owner on the container and pinned it open past the
+ * `derived !== DONE` bail below.
  */
 const IN_FLIGHT_STATES = new Set([
   AGENT_LABELS.EXECUTING,

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

@@ -28,6 +28,15 @@
  *      partial failure reports which tickets were and were not closed so the
  *      operator can finish by hand.
  *
+ * The close also strips the source ticket's `agent::*` label (Story #5255).
+ * A retired ticket has no agent state, and the one it kept was read as live
+ * work: `agent::blocked` is the state a Story must be in to be re-planned, so
+ * this path closes exactly the tickets carrying it, and a closed-but-blocked
+ * child pinned its container Epic open on every rollup thereafter. The
+ * derivation in `ticketing/bulk.js` now ignores closed children's labels too —
+ * that half covers the tickets already closed and the ones closed by hand;
+ * this one stops new ones being written.
+ *
  * Idempotency is keyed off the `superseded-by` structured-comment marker
  * (`upsertStructuredComment`), not a bare `postComment`, so a re-run cannot
  * double-comment.
@@ -36,6 +45,7 @@
  */
 
 import { Logger } from '../../Logger.js';
+import { AGENT_LABELS } from '../../label-constants.js';
 import {
   concurrentMap,
   FANOUT_CONCURRENCY,
@@ -55,6 +65,40 @@ const SUPERSEDED_BY_COMMENT_TYPE = 'superseded-by';
  */
 export const SUPERSEDE_CLOSE_REASON = 'not_planned';
 
+/**
+ * Every `agent::*` label, as the set the supersede close strips.
+ *
+ * A retired ticket has no agent state. `agent::done` would be the wrong
+ * substitute — the work was re-planned, never delivered — so the label is
+ * removed rather than rewritten, and the ticket ends carrying only its
+ * `type::`/domain labels and the supersede comment that explains it.
+ */
+const AGENT_STATE_LABELS = Object.freeze(Object.values(AGENT_LABELS));
+
+/**
+ * The single `updateTicket` mutation that retires a source ticket.
+ *
+ * Closing and clearing the state ride one write: two calls could leave the
+ * ticket closed but still wearing `agent::blocked`, which is the shape that
+ * pinned a container Epic open forever (Story #5255).
+ *
+ * A ticket with no `agent::*` label gets the bare close, unchanged from before
+ * that Story — `updateTicket` merges a `labels` mutation by reading the issue
+ * back, so an unconditional empty `remove` would buy a wasted round-trip per
+ * superseded ticket. `_ticketSnapshot` feeds that merge the copy
+ * `probeSourceTicket` already fetched.
+ *
+ * @param {{ labels?: unknown }} ticket The probe's fresh copy.
+ * @returns {object} Mutations for `provider.updateTicket`.
+ */
+function supersedeCloseMutations(ticket) {
+  const close = { state: 'closed', state_reason: SUPERSEDE_CLOSE_REASON };
+  const labels = Array.isArray(ticket?.labels) ? ticket.labels : [];
+  const remove = AGENT_STATE_LABELS.filter((label) => labels.includes(label));
+  if (remove.length === 0) return close;
+  return { ...close, labels: { remove }, _ticketSnapshot: ticket };
+}
+
 /**
  * Coerce one `supersedes[]` entry into `{ id, note }`.
  *
@@ -329,13 +373,22 @@ export function buildSupersedeCommentBody({
 /**
  * Resolve the live state of a source ticket.
  *
- * @returns {Promise<{ ok: true, state: string } | { ok: false, reason: string }>}
+ * The ticket itself rides along so the close can strip the `agent::*` label
+ * without a second read: `updateTicket`'s label merge takes a
+ * `_ticketSnapshot` for exactly this, and this probe has already paid for the
+ * fresh copy.
+ *
+ * @returns {Promise<{ ok: true, state: string, ticket: object } | { ok: false, reason: string }>}
  */
 async function probeSourceTicket(provider, id) {
   try {
     const ticket = await provider.getTicket(id, { fresh: true });
     if (!ticket) return { ok: false, reason: 'not-found' };
-    return { ok: true, state: String(ticket.state ?? 'open').toLowerCase() };
+    return {
+      ok: true,
+      state: String(ticket.state ?? 'open').toLowerCase(),
+      ticket,
+    };
   } catch (err) {
     return { ok: false, reason: `inaccessible: ${err.message}` };
   }
@@ -370,10 +423,7 @@ async function closeOneSupersededTicket({
         sourceTicketIds,
       }),
     );
-    await provider.updateTicket(id, {
-      state: 'closed',
-      state_reason: SUPERSEDE_CLOSE_REASON,
-    });
+    await provider.updateTicket(id, supersedeCloseMutations(probe.ticket));
     return { outcome: 'closed' };
   } catch (err) {
     return { outcome: 'failed', reason: err.message };

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

@@ -401,25 +401,59 @@ async function cascadeCompletion(provider, ticketId, opts = {}) {
  * Derive the parent `agent::*` state from the composition of its children.
  *
  * Rules (Story #2676):
- * - Any child carrying `agent::blocked` → parent should be `agent::blocked`.
+ * - Any **open** child carrying `agent::blocked` → parent should be
+ *   `agent::blocked`.
  * - Otherwise, every child is `agent::done` (or closed) → parent should be
  *   `agent::done`.
- * - Otherwise, any child carrying `agent::executing` or `agent::closing` →
- *   parent should be `agent::executing`.
+ * - Otherwise, any **open** child carrying `agent::executing` or
+ *   `agent::closing` → parent should be `agent::executing`.
  * - Otherwise (e.g. all children still `agent::ready`) → return `null` to
  *   signal "leave the parent unchanged". A parent already partway through
  *   the lifecycle MUST NOT be downgraded just because one child reverted.
  *
+ * **A closed child contributes no `agent::*` state** (Story #5255). Its label
+ * records the state it was in when it stopped, not outstanding work, and
+ * nothing clears it on the way out: a Story re-planned out of `agent::blocked`
+ * is closed as superseded still wearing that label, and the blocked rule then
+ * pinned its container Epic open forever — `epic-rollup.js` bails before its
+ * close path on any derived state other than `agent::done`, so the Epic
+ * reported `pending` every run with every child long since closed. Filtering
+ * here rather than at that one call site is what also covers a child closed by
+ * hand with a stale state label attached. The all-done branch already counted
+ * `state === 'closed'` as done, so a closed child keeps exactly that meaning
+ * and loses only its vote on the other two.
+ *
  * The function is pure and exported so the rule can be exercised in
  * isolation by unit tests without dragging the cascade I/O surface in.
  *
  * @param {Array<{ labels?: string[], state?: string }>} siblings
  * @returns {string|null} A `STATE_LABELS.*` value, or `null` for no-op.
  */
+/**
+ * The labels that still describe **live** work on this child.
+ *
+ * Empty for a closed child: its `agent::*` label records the state it stopped
+ * in, not outstanding work, and the two live-state rules in
+ * {@link deriveParentState} must not read it. The all-done rule reads the
+ * child's labels directly, so a closed child keeps counting as done.
+ *
+ * Module-level rather than another local arrow inside `deriveParentState`:
+ * the CRAP baseline keys anonymous functions positionally within their
+ * enclosing scope, so adding or removing one there renumbers every later
+ * arrow and reports the shift as drift on code that did not change.
+ *
+ * @param {{ labels?: string[], state?: string }} sibling
+ * @returns {string[]}
+ */
+function liveChildLabels(sibling) {
+  if (sibling?.state === 'closed') return [];
+  return Array.isArray(sibling?.labels) ? sibling.labels : [];
+}
+
 export function deriveParentState(siblings) {
   if (!Array.isArray(siblings) || siblings.length === 0) return null;
   const labelsOf = (s) => (Array.isArray(s?.labels) ? s.labels : []);
-  if (siblings.some((s) => labelsOf(s).includes(STATE_LABELS.BLOCKED))) {
+  if (siblings.some((s) => liveChildLabels(s).includes(STATE_LABELS.BLOCKED))) {
     return STATE_LABELS.BLOCKED;
   }
   const allDone = siblings.every(
@@ -428,8 +462,8 @@ export function deriveParentState(siblings) {
   if (allDone) return STATE_LABELS.DONE;
   const anyActive = siblings.some(
     (s) =>
-      labelsOf(s).includes(STATE_LABELS.EXECUTING) ||
-      labelsOf(s).includes(STATE_LABELS.CLOSING),
+      liveChildLabels(s).includes(STATE_LABELS.EXECUTING) ||
+      liveChildLabels(s).includes(STATE_LABELS.CLOSING),
   );
   if (anyActive) return STATE_LABELS.EXECUTING;
   return null;

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

@@ -309,8 +309,11 @@ children at both per-Story lifecycle edges — the `agent::executing` flip in
 `epicRollup` step) — which is why it holds at **N=1**, where no epilogue runs.
 
 - **Status** follows the children's composition (`deriveParentState` mapped
-  onto the board's three options): any child executing or blocked → `In
-  Progress`, every child `agent::done` or closed → `Done`. It is written
+  onto the board's three options): any **open** child executing or blocked →
+  `In Progress`, every child `agent::done` or closed → `Done`. A **closed**
+  child contributes no `agent::*` state at all — its label records where it
+  stopped, and a superseded Story closed still wearing `agent::blocked` used
+  to pin its container open forever. It is written
   **directly**, never via a label: the container carries no `agent::*` label
   by construction, which is what keeps it out of the bare `/mandrel-deliver`
   ready list.

package/.agents/workflows/helpers/plan-reference.md

@@ -598,7 +598,7 @@ link that makes the history readable.
 
 | Behaviour | Contract |
 | --- | --- |
-| Default | Comment + close every source ticket as `not_planned`. |
+| Default | Comment + close every source ticket as `not_planned`, **clearing its `agent::*` label** in the same write — a retired ticket has no agent state, and `agent::done` would claim a delivery that never happened. |
 | `--no-close-superseded` | Skips all commenting and closing. Story creation is unchanged. Use it for a genuinely partial supersede — when the plan folded in only *part* of an issue and the remainder must stay open. |
 | `--dry-run` | Posts no comment and closes nothing; reports what it would have done. |
 | Re-run | Idempotent — the comment is keyed off a `superseded-by` structured-comment marker, and an already-closed source is skipped. |

package/docs/CHANGELOG.md

@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.54.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.53.0...mandrel-v2.54.0) (2026-09-09)
+
+
+### Fixed
+
+* a closed child pins its container Epic open forever: the rollup reads its stale agent::* label, and the supersede close is what writes one ([#5255](https://github.com/dsj1984/mandrel/issues/5255)) ([#5256](https://github.com/dsj1984/mandrel/issues/5256)) ([672428f](https://github.com/dsj1984/mandrel/commit/672428f1e0fba1388a1a001d2840e7eb827b9373))
+
 ## [2.53.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.52.0...mandrel-v2.53.0) (2026-09-09)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.53.0",
+  "version": "2.54.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",