mandrel 1.94.0 → 2.1.0

package/.agents/scripts/stories-wave-tick.js

@@ -11,7 +11,7 @@
  * emits the set of Stories safe to dispatch **on this beat** — a Story
  * becomes dispatchable the instant its own dependencies are done, under the
  * same global concurrency cap and the same file-overlap co-dispatch guard
- * the Epic path uses. There is no wave barrier: this no longer batches
+ * `lib/wave-runner/ready-set.js` applies everywhere. There is no wave barrier: this no longer batches
  * Stories into fully-draining waves; it selects continuously.
  *
  * The previous static wave-batch plan (group N must fully drain before
@@ -37,7 +37,8 @@
  *     totalStories: number,
  *     concurrencyCap: number,
  *     inFlight: number,
- *     cycleError: string | null
+ *     cycleError: string | null,
+ *     wedged: { reason, stories: [{ id, unmetBlockers }] } | null
  *   }
  *
  * The standalone loop calls this once per beat: after each Story closes it
@@ -50,11 +51,17 @@
  * `/deliver` uses — `resolveConfig` + `getRunners` reading
  * `delivery.deliverRunner.concurrencyCap` (default 3) — so a
  * `.agentrc.local.json` override is honored. A `--concurrency <n>` CLI flag
- * overrides the config-resolved value for that run only. This puts both the
- * standalone (`/deliver`) and Epic (`/deliver`) delivery paths on one
- * deterministic config source **and** one scheduling kernel.
+ * overrides the config-resolved value for that run only. This shares one
+ * deterministic config source (`delivery.deliverRunner.concurrencyCap`) and
+ * one scheduling kernel with every `/deliver` multi-Story invocation.
  *
- * On cycle detection, exits with code 2 and sets cycleError in the envelope.
+ * Exit codes: 0 ok · 1 input error · 2 dependency cycle (`cycleError`) ·
+ * 3 wedged (`wedged`) — ready is empty, nothing is in flight, and undone
+ * Stories are waiting on blockers that are not done. A cycle is a
+ * self-referential DAG the operator must fix; a wedge is a well-formed DAG
+ * whose gates cannot be satisfied from the supplied `--done` set (usually a
+ * blocker outside the delivered set that has not landed). Both are distinct
+ * from the ordinary `ready: []` that means "waiting on in-flight work".
  */
 
 import { readFileSync } from 'node:fs';
@@ -68,13 +75,20 @@ import { AGENT_LABELS } from './lib/label-constants.js';
 import { buildStoryAdjacency } from './lib/story-adjacency.js';
 import { selectReadySet } from './lib/wave-runner/ready-set.js';
 
+/**
+ * Exit code for a wedged run — deliberately distinct from the cycle exit (2)
+ * so a caller can tell "your DAG is self-referential" from "your DAG is fine
+ * but its gates can never be satisfied from this `--done` set".
+ */
+export const WEDGED_EXIT_CODE = 3;
+
 const HELP = `Usage: node .agents/scripts/stories-wave-tick.js --dag '<json>' | --dag-file <path> [--concurrency <n>] [--done <csv>] [--in-flight <n>]
 
 Continuous ready-set planner for standalone Story delivery. Consumes a
 dependency graph of Story IDs plus the live run progress and emits the set
 of Stories safe to dispatch on this beat — a Story is dispatchable the
 instant its own dependencies are done — plus the resolved per-beat
-concurrency cap and the same file-overlap guard the Epic path uses.
+concurrency cap and the same file-overlap guard as selectReadySet.
 
 Input DAG format (JSON array):
   [{ "id": 101, "dependsOn": [] }, { "id": 102, "dependsOn": [101] }]
@@ -102,13 +116,17 @@ Output envelope:
     "totalStories": 2,
     "concurrencyCap": 3,
     "inFlight": 0,
-    "cycleError": null
+    "cycleError": null,
+    "wedged": null
   }
 
 Exit codes:
   0 - Success, ready set emitted
   1 - Invalid input (missing/malformed DAG, invalid --concurrency/--in-flight/--done)
   2 - Cycle detected in dependency graph
+  3 - Wedged: ready is empty, nothing is in flight, and undone Stories are
+      waiting on blockers that are not done. Distinct from an ordinary empty
+      ready set (which means "waiting on in-flight work") and from a cycle.
 `;
 
 /**
@@ -257,7 +275,7 @@ export function parseConcurrencyOverride(raw) {
 /**
  * Resolve the per-beat concurrency cap.
  *
- * Mirrors the `/deliver` seam (`epic-deliver-prepare.js`): resolve the
+ * Mirrors the `/deliver` multi-Story seam (`helpers/deliver-story.md`): resolve the
  * project config (which deep-merges `.agentrc.local.json` over `.agentrc.json`)
  * then read `delivery.deliverRunner.concurrencyCap` via `getRunners` (default
  * 3). An explicit `override` (the `--concurrency <n>` CLI flag) wins over
@@ -322,6 +340,7 @@ export function buildReadySetEnvelope(
     concurrencyCap,
     inFlight,
     cycleError: null,
+    wedged: null,
   };
 
   if (totalStories === 0) {
@@ -365,7 +384,62 @@ export function buildReadySetEnvelope(
     globalCap: concurrencyCap,
   }).map((rec) => rec.id);
 
-  return { envelope: { ...base, ready }, exitCode: 0 };
+  // Wedge detection (Story #4540). `ready: []` is normal while work is in
+  // flight — the loop is simply waiting. But ready-empty AND nothing in
+  // flight AND undone Stories remaining means no beat can ever make
+  // progress: the run is stuck, and the previous behaviour was to return
+  // exit 0 with an empty ready set forever, indistinguishable from
+  // "waiting". Name the stuck ids and their unmet blockers.
+  //
+  // Distinct from `cycleError`/exit 2: a cycle is a self-referential DAG,
+  // whereas this is a DAG whose gates are real but unsatisfiable from the
+  // supplied `done` set (typically a blocker outside the delivered set that
+  // has not landed).
+  const wedge = detectWedge({ nodes, doneIds, ready, inFlight });
+  if (wedge) {
+    return {
+      envelope: { ...base, ready, wedged: wedge },
+      exitCode: WEDGED_EXIT_CODE,
+    };
+  }
+
+  return { envelope: { ...base, ready, wedged: null }, exitCode: 0 };
+}
+
+/**
+ * Identify a run that cannot progress: nothing dispatchable, nothing in
+ * flight, work remaining.
+ *
+ * @param {{ nodes: object[], doneIds: Set<number>, ready: number[], inFlight: number }} args
+ * @returns {{ reason: string, stories: Array<{ id: number, unmetBlockers: number[] }> }|null}
+ */
+export function detectWedge({ nodes, doneIds, ready, inFlight }) {
+  if (ready.length > 0 || inFlight > 0) return null;
+  const undone = nodes.filter((n) => !doneIds.has(n.id));
+  if (undone.length === 0) return null;
+
+  const stories = undone
+    .map((n) => ({
+      id: n.id,
+      unmetBlockers: (n.dependsOn ?? []).filter((dep) => !doneIds.has(dep)),
+    }))
+    .filter((s) => s.unmetBlockers.length > 0);
+
+  // Undone work with no unmet blockers would have been dispatched; if that
+  // is the whole set, the cap or in-flight accounting explains the empty
+  // ready set rather than a wedge.
+  if (stories.length === 0) return null;
+
+  const detail = stories
+    .map((s) => `#${s.id} ← ${s.unmetBlockers.map((d) => `#${d}`).join(', ')}`)
+    .join('; ');
+  return {
+    reason:
+      `No Story can be dispatched: nothing is in flight and ${stories.length} ` +
+      `Story(ies) are waiting on blockers that are not done — ${detail}. ` +
+      `A blocker outside the delivered set must land first, or be included in --ids.`,
+    stories,
+  };
 }
 
 /**
@@ -405,6 +479,7 @@ export function runStoriesWaveTick({
       concurrencyCap,
       inFlight: inFlightValue,
       cycleError: null,
+      wedged: null,
       inputError: message,
     },
     exitCode: 1,

package/.agents/scripts/story-plan.js

@@ -2,33 +2,17 @@
 /* node:coverage ignore file */
 
 /**
- * story-plan.js — Local `/plan` wrapper.
+ * story-plan.js — QA helper for promote round-trips and `--emit-context`
+ * envelope emission.
  *
- * Standalone counterpart to `/plan` for Stories that do **not**
- * attach to an Epic. The script is deliberately a thin CLI around the
- * pure helpers in `lib/story-plan.js`:
+ * Canonical operator planning is `plan-context.js` + `plan-persist.js` (see
+ * `.agents/workflows/plan.md`). Use this CLI only for QA promote
+ * round-trips (`--body` / `--dry-run`) or test harnesses that need the
+ * standalone envelope shape.
  *
- *   1. `--emit-context` mode — given a `--idea`/`--from-notes` seed,
- *      build the context envelope (seed, refine heuristic, persona,
- *      body template, duplicate candidates, tech-stack summary, and a
- *      corpus-aware `corpusContext` — the docs digest plus relevant
- *      existing-Epic Tech Spec excerpts, Story #4432) and print it as
- *      JSON on stdout. Logs route to stderr so the envelope is
- *      byte-clean for `JSON.parse`.
- *   2. Persist mode — given a `--body <file>` authored by the host
- *      LLM after operator confirmation, validate the shape and persist
- *      via `provider.createIssue` (which also adds the new Story to
- *      the configured Projects V2 board — Story #3822) with
- *      `type::story` + the chosen persona label, falling back to
- *      `gh issue create` when the provider lacks a createIssue
- *      analogue. Prints `Next: /single-story-deliver <id>`.
- *   3. `--dry-run` — same as persist but exits without touching
- *      GitHub. Echoes the rendered body and the `gh` argv it would
- *      have run.
- *
- * Mirrors the `/plan` pattern: deterministic Node I/O wrappers
- * with HITL gating handled by the host LLM in chat. No external LLM
- * APIs are called from this script.
+ * Operator planning:
+ *   node .agents/scripts/plan-context.js --seed "…" | --seed-file <path> | --tickets <ids>
+ *   node .agents/scripts/plan-persist.js --stories …
  */
 
 import { readFile } from 'node:fs/promises';
@@ -53,10 +37,10 @@ import {
 
 const HELP = `\
 Usage:
-  story-plan.js --emit-context (--idea "<seed>" | --from-notes <file>) \\
-    [--persona <name>] [--refine | --no-refine] [--pretty]
+  story-plan.js --emit-context (--seed "<seed>" | --seed-file <file>) \\
+    [--refine | --no-refine] [--pretty]
 
-  story-plan.js --body <file> [--persona <name>] [--dry-run]
+  story-plan.js --body <file> [--dry-run]
 
   story-plan.js --help
 
@@ -66,12 +50,11 @@ Modes:
                    draft body using the envelope and the body template.
   --body <file>    Persist a pre-authored body. Validates shape (required
                    sections, no Epic: ref, AC checklist non-empty) and
-                   calls \`gh issue create\` with type::story + persona.
+                   calls \`gh issue create\` with type::story.
   --dry-run        With --body: print the body and the gh argv that would
                    be invoked, then exit 0. No GitHub mutations.
 
 Options:
-  --persona <name>   Persona label (default: engineer).
   --refine           Force the idea-refinement hint on regardless of seed
                      length. Default heuristic: refine when seed < 200
                      chars.
@@ -80,17 +63,17 @@ Options:
 `;
 
 /**
- * Resolve the seed string from --idea or --from-notes. One of the two
+ * Resolve the seed string from --seed or --seed-file. One of the two
  * must be present in --emit-context mode.
  */
-async function resolveSeed({ idea, fromNotes }) {
-  if (idea && fromNotes) {
-    throw new Error('Pass either --idea or --from-notes, not both.');
+async function resolveSeed({ seed, seedFile }) {
+  if (seed && seedFile) {
+    throw new Error('Pass either --seed or --seed-file, not both.');
   }
-  if (idea) return idea;
-  if (fromNotes) return (await readFile(fromNotes, 'utf8')).trim();
+  if (seed) return seed;
+  if (seedFile) return (await readFile(seedFile, 'utf8')).trim();
   throw new Error(
-    '--emit-context requires --idea "<seed>" or --from-notes <file>.',
+    '--emit-context requires --seed "<seed>" or --seed-file <file>.',
   );
 }
 
@@ -147,12 +130,11 @@ async function runEmitContext({
   write = (s) => process.stdout.write(s),
 }) {
   const seed = await resolveSeed({
-    idea: values.idea,
-    fromNotes: values['from-notes'],
+    seed: values.seed,
+    seedFile: values['seed-file'],
   });
   const override = values.refine ? 'on' : values['no-refine'] ? 'off' : null;
   const refine = shouldRefine({ seed, override });
-  const persona = values.persona ?? 'engineer';
 
   // Corpus lookup uses the raw (un-defaulted) docsContextFiles list, same
   // as the `/deliver` per-Epic digest builder: `config.project` fills in
@@ -164,7 +146,7 @@ async function runEmitContext({
   // corpus digest reads the project's actual docs directory regardless
   // of the directory this CLI happens to be invoked from — matching the
   // sibling resolution pattern in
-  // epic-plan-spec/phases/authoring-context.js.
+  // planning/authoring-context.js.
   const docsRoot = path.resolve(
     PROJECT_ROOT,
     config?.project?.paths?.docsRoot ?? 'docs',
@@ -175,7 +157,7 @@ async function runEmitContext({
       loadBodyTemplate(projectRoot),
       fetchOpenStories(provider),
       readTechStackSummary(projectRoot),
-      buildCorpusContext({ seed, provider, docsContextFiles, docsRoot }),
+      buildCorpusContext({ docsContextFiles, docsRoot }),
     ]);
 
   const duplicateCandidates = rankDuplicateCandidates({
@@ -186,7 +168,6 @@ async function runEmitContext({
   const envelope = buildContextEnvelope({
     seed,
     refine,
-    persona,
     bodyTemplate,
     duplicateCandidates,
     techStack,
@@ -221,8 +202,7 @@ async function runPersist({
   }
 
   const title = extractTitle(body);
-  const persona = values.persona ?? 'engineer';
-  const labels = [TYPE_LABELS.STORY, `persona::${persona}`];
+  const labels = [TYPE_LABELS.STORY];
   const argv = renderGhArgv({ title, bodyPath, labels });
 
   if (dryRun) {
@@ -264,7 +244,7 @@ async function runPersist({
   }
 
   write(`${JSON.stringify({ issueNumber, title, labels }, null, 2)}\n`);
-  Logger.info(`Next: /single-story-deliver ${issueNumber}`);
+  Logger.info(`Next: /deliver ${issueNumber}`);
 }
 
 /* node:coverage ignore next */
@@ -272,10 +252,9 @@ async function main() {
   const { values } = parseArgs({
     options: {
       'emit-context': { type: 'boolean', default: false },
-      idea: { type: 'string' },
-      'from-notes': { type: 'string' },
+      seed: { type: 'string' },
+      'seed-file': { type: 'string' },
       body: { type: 'string' },
-      persona: { type: 'string' },
       refine: { type: 'boolean', default: false },
       'no-refine': { type: 'boolean', default: false },
       pretty: { type: 'boolean', default: false },

package/.agents/scripts/update-ticket-state.js

@@ -1,27 +1,14 @@
 /**
- * .agents/scripts/update-ticket-state.js — CLI Re-export Shim
- *
- * Thin backward-compatibility shim. The core logic has been moved to
- * `lib/orchestration/ticketing.js` as part of the SDK refactor.
- *
- * This file preserves backward compatibility for CLI usage and existing
- * testing patterns.
- *
- * Successor to the retired mandrel MCP tools. See ADR 20260424-702a in docs/decisions.md for the migration table.
+ * .agents/scripts/update-ticket-state.js — CLI entrypoint for ticket
+ * label transitions. Core logic lives in `lib/orchestration/ticketing.js`;
+ * this file is the operator-facing command surface (not a compatibility
+ * layer).
  */
 
 import { parseArgs } from 'node:util';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
-import {
-  enqueueLabel,
-  outboxPathFor,
-} from './lib/orchestration/bookkeeping-outbox.js';
-import {
-  cascadeCompletion,
-  STATE_LABELS,
-  transitionTicketState,
-} from './lib/orchestration/ticketing.js';
+import { transitionTicketState } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 
 // ── CLI Main Block ────────────────────────────────────────────────────────
@@ -33,27 +20,21 @@ if (
   const { values } = parseArgs({
     args: process.argv.slice(2),
     options: {
-      task: { type: 'string' },
       ticket: { type: 'string' },
       state: { type: 'string' },
       'remove-label': { type: 'string' },
-      buffer: { type: 'boolean' },
-      epic: { type: 'string' },
     },
     strict: false,
   });
 
-  // `--ticket` is the v5.9.0 alias for `--task` (labels can apply to any
-  // ticket type, not just Tasks). Both continue to work.
-  const idSource = values.ticket ?? values.task;
-  const ticketId = Number.parseInt(idSource, 10);
+  const ticketId = Number.parseInt(values.ticket, 10);
   const state = values.state;
   const removeLabel = values['remove-label'];
 
   if (Number.isNaN(ticketId) || (!state && !removeLabel)) {
     throw new Error(
       'Usage: node update-ticket-state.js ' +
-        '(--ticket|--task) <id> ' +
+        '--ticket <id> ' +
         '[--state <state> | --remove-label <label>]',
     );
   }
@@ -75,50 +56,18 @@ if (
       return;
     }
 
-    // Headless buffering (Epic #4476 M5): buffer an intermediate state flip to
-    // the per-Epic outbox instead of a live GitHub round-trip; finalize's
-    // bookkeeping-reconcile.js drains it once. `agent::blocked` (the HITL gate,
-    // §1.J) and `agent::done` (its cascade must run live) ALWAYS surface
-    // immediately and are never buffered. Requires --epic to locate the outbox.
-    if (
-      values.buffer &&
-      state !== STATE_LABELS.BLOCKED &&
-      state !== STATE_LABELS.DONE
-    ) {
-      const epicId = Number.parseInt(values.epic ?? '', 10);
-      if (!Number.isInteger(epicId) || epicId <= 0) {
-        throw new Error('--buffer requires --epic <id>');
-      }
-      enqueueLabel({
-        outboxPath: outboxPathFor(epicId, config),
-        ticketId,
-        state,
-      });
-      Logger.info(
-        `[State-Sync] Buffered #${ticketId} → ${state} (headless; drained at finalize)`,
-      );
-      return;
-    }
-
     Logger.info(
       `[State-Sync] Transitioning ticket #${ticketId} to ${state}...`,
     );
+    // Story #4545 — no second cascade here. `transitionTicketState` already
+    // fires the upward cascade on every transition (bulk.js registers
+    // `cascadeParentState` as transition.js's cascade runner, and the DONE
+    // branch delegates to `cascadeCompletion`), so the explicit call this
+    // used to make re-walked the same parents and re-spent the same API
+    // calls a second time on every done transition — under a Story-only
+    // model where no orchestration parent exists to find.
     await transitionTicketState(provider, ticketId, state);
 
-    if (state === STATE_LABELS.DONE) {
-      Logger.info(`[State-Sync] Cascading completion from #${ticketId}...`);
-      const cascade = await cascadeCompletion(provider, ticketId);
-      // Hoisted out of the `for...of` initializer because typhonjs-escomplex
-      // mis-parses optional chaining there (it would zero out this file's
-      // maintainability score).
-      const cascadeFailures = cascade?.failed ?? [];
-      for (const { parentId, error } of cascadeFailures) {
-        Logger.warn(
-          `[State-Sync] ⚠️  Cascade partial-failure on parent #${parentId}: ${error}`,
-        );
-      }
-    }
-
     // Optional secondary label removal alongside the state transition
     // (e.g. clear `status::blocked` when transitioning back to ready).
     if (removeLabel) {