mandrel 1.58.0 → 1.60.0

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

@@ -8,26 +8,25 @@
  * Story #1848 so the verb-family split (`reads` / `state` / `bulk`) is
  * complete and the parent collapses to a pure re-export facade.
  *
- * Note on the cycle with `./state.js`: `cascadeCompletion` recursively
- * calls `transitionTicketState`, which in turn — when the cascade flag is
- * on — calls back into `cascadeCompletion`. ESM tolerates the cycle
- * because every binding is resolved at call-time. Both modules complete
- * evaluation before any of their exported functions run.
+ * Story #3995 — the single-ticket mutators (`transitionTicketState`,
+ * `toggleTasklistCheckbox`, `postStructuredComment`) moved to the leaf
+ * `./transition.js`, so this module now depends **downward** on
+ * `transition.js` and the former `state.js ↔ bulk.js` import cycle is
+ * gone. `cascadeCompletion` still recursively transitions parents via
+ * the imported `transitionTicketState`; the reverse call
+ * (`transitionTicketState → cascadeParentState`) is injected into
+ * `transition.js` by `state.js` via `registerCascadeRunner` rather than
+ * imported, which is what keeps the graph acyclic.
  */
 
 import { Logger } from '../../Logger.js';
 import { TYPE_LABELS } from '../../label-constants.js';
-import { dispatchCascadeGroups, groupByAncestor } from '../cascade-grouping.js';
 import { ALL_STATES, STATE_LABELS } from './reads.js';
 import {
   postStructuredComment,
   toggleTasklistCheckbox,
   transitionTicketState,
-} from './state.js';
-
-// Re-export `groupByAncestor` so external callers that imported it from
-// the ticketing facade continue to work after the verb-family split.
-export { groupByAncestor };
+} from './transition.js';
 
 /**
  * Retry budget for transient `gh` failures (rate limit, secondary rate limit,
@@ -217,9 +216,8 @@ export function logCascadePartialFailures(ticketId, cascade) {
 
 /**
  * Per-parent body of {@link cascadeCompletion}. Pulled out so the outer
- * function can dispatch disjoint groups in parallel while each parent
- * still runs against its own captured logger, ensuring byte-identical
- * log output across serial and parallel execution paths.
+ * walk stays a thin sequential loop while the per-parent work runs under
+ * the per-parent cascade lock.
  *
  * @param {import('../../ITicketingProvider.js').ITicketingProvider} provider
  * @param {number} ticketId  - The ticket whose `agent::done` transition
@@ -293,7 +291,7 @@ async function processCascadeParentLocked(
     if (!allDone) return { cascadedTo, failed };
 
     // EXCLUSION: Epics do not auto-close via cascade. Epics close via
-    // formal /epic-deliver (its own machinery handles branch merges,
+    // formal /deliver (its own machinery handles branch merges,
     // PR-driven `Closes #N` auto-close, and a recovery transition in
     // `epic-deliver-finalize.js`).
     //
@@ -307,13 +305,6 @@ async function processCascadeParentLocked(
     // defense-in-depth path when a Story's tasklist references a
     // planning ticket directly.
     //
-    // Features auto-close via cascade. A Feature is a purely
-    // hierarchical grouping — no standalone branch, no merge step.
-    // When its last child Story closes, the Feature is complete by
-    // definition. Operators who need Feature-level AC verification
-    // should encode it in the final child Story, not rely on a manual
-    // close step.
-    //
     // 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
@@ -372,19 +363,13 @@ async function processCascadeParentLocked(
  * Then checks if parent's sub-tickets are ALL DONE.
  * If yes, transitions parent to DONE and cascades up.
  *
- * Parents are partitioned into disjoint groups by shared ancestor
- * ({@link groupByAncestor}). Groups run in parallel via `Promise.all`,
- * but parents **within** a group run strictly sequentially in input
- * order — concurrent transitions against a shared ancestor would race
- * the "all children done?" check. Within each parent, sibling reads
- * fan out via `getSubTickets(parentId, { fresh: true })` with the
- * concurrency cap (8) applied inside `getSubTickets`.
- *
- * Log output is captured per parent into a buffered logger and flushed
- * to the real {@link Logger} after all groups resolve, in the original
- * `parsedParents` order. The visible log stream is therefore
- * byte-identical to a serial baseline; only the I/O between parents in
- * disjoint groups overlaps.
+ * Parents run strictly sequentially in input order (Story #4017 —
+ * fan-out is <= 1 under the 2-tier hierarchy, so the former
+ * shared-ancestor grouping / parallel dispatch was deleted); concurrent
+ * transitions against a shared ancestor would race the "all children
+ * done?" check. Within each parent, sibling reads fan out via
+ * `getSubTickets(parentId, { fresh: true })` with the concurrency cap
+ * (8) applied inside `getSubTickets`.
  *
  * Per-parent errors are isolated: a failure updating one parent (network,
  * permission, stale ticket) never discards progress on sibling parents.
@@ -423,7 +408,7 @@ export async function cascadeCompletion(provider, ticketId, opts = {}) {
   // 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 Feature tickets stranded OPEN. The native link is
+  // 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 (
@@ -450,26 +435,19 @@ export async function cascadeCompletion(provider, ticketId, opts = {}) {
     return { cascadedTo: [], failed: [] };
   }
 
-  // Partition parents by shared ancestor (disjoint groups run in
-  // parallel; within-group parents stay sequential to avoid racing the
-  // shared ancestor's "all children done?" check), then dispatch the
-  // per-parent work via `dispatchCascadeGroups` so the buffered-flush
-  // bookkeeping lives in `cascade-grouping.js`.
-  const groups = await groupByAncestor(parsedParents, provider);
-  const results = await dispatchCascadeGroups({
-    parsedParents,
-    groups,
-    flushLogger: opts._logger ?? Logger,
-    processParent: (parentId, logger) =>
-      processCascadeParent(provider, ticketId, parentId, {
-        notify: opts.notify,
-        _logger: logger,
-      }),
-  });
-
+  // Story #4017 — under the 2-tier hierarchy a ticket has at most one
+  // parent, so the shared-ancestor grouping / parallel-group dispatch
+  // machinery was deleted. Parents (fan-out <= 1
+  // in practice; the loop stays general for the body-reference fallback)
+  // run strictly sequentially, which trivially preserves the
+  // shared-ancestor safety invariant the grouping used to enforce.
   const cascadedTo = [];
   const failed = [];
-  for (const r of results) {
+  for (const parentId of parsedParents) {
+    const r = await processCascadeParent(provider, ticketId, parentId, {
+      notify: opts.notify,
+      _logger: opts._logger,
+    });
     cascadedTo.push(...r.cascadedTo);
     failed.push(...r.failed);
   }
@@ -530,12 +508,11 @@ export function deriveParentState(siblings) {
  * recursive cascade" progress comment, Epic exclusion) are preserved
  * verbatim.
  *
- * Resilience matches {@link cascadeCompletion}: disjoint parent groups
- * run in parallel via {@link dispatchCascadeGroups}; parents within a
- * group run sequentially; the per-parent lock from
- * {@link withParentCascadeLock} prevents races on shared ancestors; and
- * per-parent errors are isolated so a sibling parent's failure does not
- * discard work on the others.
+ * Resilience matches {@link cascadeCompletion}: parents run
+ * sequentially; the per-parent lock from {@link withParentCascadeLock}
+ * prevents races on shared ancestors; and per-parent errors are
+ * isolated so a sibling parent's failure does not discard work on the
+ * others.
  *
  * @param {import('../../ITicketingProvider.js').ITicketingProvider} provider
  * @param {number} ticketId
@@ -572,21 +549,15 @@ export async function cascadeParentState(provider, ticketId, opts = {}) {
   const parsedParents = await resolveParentIds(provider, ticket, ticketId);
   if (parsedParents.length === 0) return { cascadedTo: [], failed: [] };
 
-  const groups = await groupByAncestor(parsedParents, provider);
-  const results = await dispatchCascadeGroups({
-    parsedParents,
-    groups,
-    flushLogger: opts._logger ?? Logger,
-    processParent: (parentId, logger) =>
-      processStateCascadeParent(provider, parentId, {
-        notify: opts.notify,
-        _logger: logger,
-      }),
-  });
-
+  // Story #4017 — sequential per-parent walk (fan-out <= 1 under the
+  // 2-tier hierarchy); see cascadeCompletion for the rationale.
   const cascadedTo = [];
   const failed = [];
-  for (const r of results) {
+  for (const parentId of parsedParents) {
+    const r = await processStateCascadeParent(provider, parentId, {
+      notify: opts.notify,
+      _logger: opts._logger,
+    });
     cascadedTo.push(...r.cascadedTo);
     failed.push(...r.failed);
   }

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

@@ -76,8 +76,8 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // downstream workflow steps don't have to infer install state from
   // node_modules presence.
   'story-init',
-  // Story #908 — /story-deliver upserts a `story-run-progress` snapshot
-  // on each Story per Task transition. The /epic-deliver aggregator and
+  // 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',
@@ -98,7 +98,7 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // operator can correct drift before Phase 8 decomposes from a stale
   // spec. Advisory: the run continues regardless of the report contents.
   'spec-freshness',
-  // Story #2681 — `/epic-deliver` Phase 4 epic-audit helper upserts an
+  // Story #2681 — `/deliver` Phase 4 epic-audit helper upserts an
   // `audit-results` comment on the Epic listing the per-lens findings
   // returned by the change-set audit pass. The marker was prescribed by
   // `helpers/epic-audit.md` Step 4 long before it was added to this
@@ -126,7 +126,7 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'epic-handoff',
   // Story #2899 (Epic #2880, F13) — `epic-deliver-preflight.js` upserts a
   // `delivery-preflight` comment on the Epic at the start of
-  // /epic-deliver Phase 1, surfacing estimated story count, install cost,
+  // /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.
@@ -137,7 +137,7 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // `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 /epic-deliver §2e Idle Watchdog
+  // 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`
@@ -151,6 +151,15 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // 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
+  // in place.
+  'plan-lease',
 ]);
 
 export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;
@@ -259,8 +268,8 @@ export const _structuredCommentCache = new WeakMap();
 /**
  * Build a well-formed ticket snapshot for a Story that has zero child
  * Tasks. Story #3097 (Wave-0 additive, Epic #3078 Strategy B) — the
- * 3-tier hierarchy collapses Epic → Feature → Story → Task into
- * Epic → Feature → Story, so a Story may legitimately have no Task
+ * 2-tier hierarchy collapses Epic → Story → Task into
+ * Epic → Story, so a Story may legitimately have no Task
  * children. Read-side callers that expect a `subTickets` array on the
  * Story can route through this helper to materialise an empty-children
  * snapshot without paying a provider round-trip and without risk of