mandrel 1.68.0 → 1.69.0

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -15,11 +15,28 @@ import {
  * 2-tier is the only published hierarchy after Story #4041 removed the
  * Feature tier: the prompt emits Stories only (direct Epic children) and
  * asks the planner to carry acceptance/verify as top-level ticket arrays.
+ *
+ * **Single source of the prompt body (Story #4162).** This module is the sole
+ * carrier of the full decomposer system-prompt body. The
+ * `epic-plan-decompose-author` SKILL no longer embeds a second verbatim copy —
+ * it references this rendered prompt (delivered to the host LLM in the
+ * `systemPrompt` field of the authoring context envelope built by
+ * `epic-plan-decompose/phases/context.js`) instead, so the two surfaces cannot
+ * drift. A guard test (`tests/ticket-decomposer.test.js`) fails if the SKILL
+ * re-grows a full copy of the prompt preamble.
+ *
+ * **Token-budget sizing input (Story #4162).** `maxTokenBudget` is the real
+ * one-pass delivery envelope (the task-prompt hydration cap surfaced into the
+ * authoring envelope by `context.js`, Story #3875). It is threaded into the
+ * rendered prompt as a sizing input so the planner sizes Stories against the
+ * envelope a single agent can actually deliver in one pass, rather than leading
+ * with the file-count proxy alone.
  */
 export function renderDecomposerSystemPrompt({
   maxTickets = LIMITS_DEFAULTS.maxTickets,
+  maxTokenBudget = LIMITS_DEFAULTS.maxTokenBudget,
 } = {}) {
-  return render2TierPrompt({ maxTickets });
+  return render2TierPrompt({ maxTickets, maxTokenBudget });
 }
 
 /**
@@ -28,7 +45,7 @@ export function renderDecomposerSystemPrompt({
  * on the Story body so the executing agent has everything it needs in one
  * ticket. Thematic grouping lives as prose in the Epic body / Tech Spec.
  */
-function render2TierPrompt({ maxTickets }) {
+function render2TierPrompt({ maxTickets, maxTokenBudget }) {
   // Sizing thresholds are sourced from the single DEFAULT_TASK_SIZING constant
   // (ticket-validator-sizing.js) so the prompt and the validator cannot drift.
   const { softFiles, hardFiles, maxAcceptance, softAcceptanceCount } =
@@ -103,6 +120,7 @@ The serialized \`body\` string renders these markdown sections (in order):
 - **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals.
 - **acceptance** (top-level array on the ticket object): Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
 - **verify** (top-level array on the ticket object): Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
+- **reason to exist** (REQUIRED, encoded as the \`reason_to_exist\` field of the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): One sentence stating the single coherent reason this Story exists, distinct from its broader \`## Goal\` prose. Every Story MUST carry a non-empty \`reason_to_exist\`; it is the machine-checkable form of the cohesion rule (**one Story = one coherent change with one reason to exist**) and the \`epic-plan-consolidate\` critic flags any Story whose body carries no non-empty reason to exist. Encode it as \`<!-- meta: {"reason_to_exist": "..."} -->\`.
 - **estimated_test_files** (optional, encoded in the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
 
 #### STORY SIZING — COHESION FIRST (the numeric ceiling is only a backstop):
@@ -111,7 +129,9 @@ The serialized \`body\` string renders these markdown sections (in order):
 
 The primary question is **cohesion, not count**: *is this one coherent change with one reason to exist?* File count cannot tell a trivial ${softFiles}-file rename from a hard 3-file parser+caller+config change — so lead with the change's reason, not its size.
 
-- **One Story = one coherent change with one reason to exist.** If you cannot state that reason in a sentence, the Story is probably two Stories — or two Stories that should be one.
+**Size against the real one-pass delivery envelope.** Each Story is delivered and self-verified by a single agent in one pass, whose context is capped by the delivery token budget \`maxTokenBudget = ${maxTokenBudget}\` tokens (the task-prompt hydration cap). Use that envelope — not the file count alone — as the leading sizing input: a Story is correctly sized when one agent can hold its full change, acceptance, and verification in a single pass within \`maxTokenBudget\`. The numeric file thresholds below are a coarse backstop on top of this envelope, not the primary signal.
+
+- **One Story = one coherent change with one reason to exist.** If you cannot state that reason in a sentence, the Story is probably two Stories — or two Stories that should be one. State that sentence explicitly in the Story's \`reason_to_exist\` meta field (see STORY BODY RULES) so the consolidate critic can check it.
 - ${singleConsumerRule}
 - **Split independent, parallelizable work** into sibling Stories — but only when the pieces genuinely have separate reasons to exist.
 - **Declare \`wide\` with a one-line reason when a change is legitimately broad** (a cohesive cutover that spans many files for one reason). Declaring \`wide\` lifts the hard file-width ceiling — see below.

package/.agents/scripts/lib/wave-runner/ready-set.js

@@ -0,0 +1,295 @@
+/**
+ * lib/wave-runner/ready-set.js — the path-agnostic ready-set scheduling
+ * core.
+ *
+ * This module is the scheduling kernel both the Epic and standalone
+ * delivery paths dispatch through. It replaces wave-*batch* selection
+ * (group N must fully drain before group N+1 opens) with *continuous*,
+ * dependency-driven selection: a Story becomes dispatchable the instant
+ * **its own** dependencies are satisfied, regardless of whether unrelated
+ * Stories in some nominal wave are still running. There is no false
+ * barrier — a Story C that depends only on a done Story A is selected even
+ * while an unrelated Story B is still pending.
+ *
+ * It is deliberately **path-agnostic and side-effect-free**: it neither
+ * reads GitHub, the lifecycle ledger, nor a checkpoint, and it dispatches
+ * nothing. Callers supply the live Story records (already fetched), the
+ * resolved `inFlight` count, and the `globalCap`, and receive back the set
+ * of Stories that are safe to dispatch on this beat. Later Stories wire the
+ * Epic / standalone adapters on top of this core; this Story ships the core
+ * alone and does not modify `tick.js` or `stories-wave-tick.js`.
+ *
+ * Three exports:
+ *   - `classifyStory(story)` — live-label classifier mapping a Story
+ *     record's labels + issue state to one of `done | blocked | executing |
+ *     ready`. Mirrors the done-predicate `tick.js` already uses
+ *     (`agent::done` OR closed issue) so a Story closed manually through
+ *     the GitHub UI is recognised as done.
+ *   - `storiesOverlap(a, b)` — the file-overlap co-dispatch guard: true
+ *     when two Stories' declared file footprints intersect. Two Stories
+ *     that would touch the same file MUST NOT be dispatched onto parallel
+ *     `story-<id>` branches in the same beat (they would race the same
+ *     path and produce a merge conflict at close).
+ *   - `selectReadySet({ stories, doneIds, inFlight, globalCap })` — the
+ *     scheduler. Returns the deterministic, overlap-free set of ready
+ *     Stories, capped at `globalCap − inFlight`.
+ *
+ * Adjacency is re-derived from the supplied records via the shared
+ * `buildStoryAdjacency` builder (`lib/story-adjacency.js`) — the same
+ * `blocked by #NNN` / `dependencies[]` source order the dispatch manifest
+ * and the existing wave wrappers use — so this core never disagrees with
+ * the manifest about what depends on what.
+ *
+ * @module lib/wave-runner/ready-set
+ */
+
+import { AGENT_LABELS } from '../label-constants.js';
+import { buildStoryAdjacency } from '../story-adjacency.js';
+
+/**
+ * @typedef {object} StoryRecord
+ * @property {number|string} [id]      Story id (preferred).
+ * @property {number} [number]         Story id (GitHub issue-number shape).
+ * @property {string} [title]
+ * @property {string} [body]           Used by `buildStoryAdjacency` to parse
+ *   `blocked by #NNN` / `depends on #NNN` references.
+ * @property {string[]} [labels]       Live `agent::*` labels.
+ * @property {string} [state]          GitHub issue state (`open` | `closed`).
+ * @property {Array<number|string>} [dependencies] Explicit dependency ids.
+ * @property {Array<number|string>} [dependsOn]     Operator-DAG dependency ids.
+ * @property {string[]} [files]        Declared file footprint (one of the
+ *   accepted footprint shapes — see `storyFootprint`).
+ * @property {string[]} [changes]      Alternate footprint shape.
+ * @property {Array<{path?: string}>} [changeset] Alternate footprint shape.
+ */
+
+/** @typedef {'done'|'blocked'|'executing'|'ready'} StoryClass */
+
+/**
+ * Normalize a Story record's id to a positive integer, or `null` when it is
+ * absent / non-integer. Accepts both the ticket shape (`id`) and the raw
+ * GitHub issue shape (`number`), matching `buildStoryAdjacency`.
+ *
+ * @param {StoryRecord|number|string} story
+ * @returns {number|null}
+ */
+export function storyIdOf(story) {
+  if (typeof story === 'number') {
+    return Number.isInteger(story) && story > 0 ? story : null;
+  }
+  const raw = story?.id ?? story?.number;
+  const id = Number(raw);
+  return Number.isInteger(id) && id > 0 ? id : null;
+}
+
+/**
+ * Classify a Story from its **live** labels and issue state.
+ *
+ * Precedence (highest first):
+ *   1. `done`      — carries `agent::done` OR the issue is `state === 'closed'`.
+ *                    The closed-state arm aligns with `tick.js#isStoryDone`
+ *                    so a Story closed manually in the GitHub UI (issue
+ *                    closed, label not flipped) still reads as done and is
+ *                    never re-dispatched.
+ *   2. `blocked`   — carries `agent::blocked`.
+ *   3. `executing` — carries `agent::executing` OR `agent::closing` (both
+ *                    are in-flight: an executing or closing Story occupies a
+ *                    slot and must not be re-dispatched).
+ *   4. `ready`     — none of the above; the Story is eligible for dispatch
+ *                    once its dependencies are satisfied.
+ *
+ * `done` wins over every in-progress label so a stale `agent::executing`
+ * left behind on an issue that has since closed never masks completion.
+ *
+ * @param {StoryRecord} story
+ * @returns {StoryClass}
+ */
+export function classifyStory(story) {
+  const labels = Array.isArray(story?.labels) ? story.labels : [];
+  if (labels.includes(AGENT_LABELS.DONE) || story?.state === 'closed') {
+    return 'done';
+  }
+  if (labels.includes(AGENT_LABELS.BLOCKED)) return 'blocked';
+  if (
+    labels.includes(AGENT_LABELS.EXECUTING) ||
+    labels.includes(AGENT_LABELS.CLOSING)
+  ) {
+    return 'executing';
+  }
+  return 'ready';
+}
+
+/**
+ * Extract a Story's declared file footprint as a normalized set of path
+ * strings. Accepts the three footprint shapes a Story record can carry:
+ *
+ *   - `files: string[]`                         — explicit footprint.
+ *   - `changes: string[]`                       — string-array sketch.
+ *   - `changeset: Array<{ path }>` /            — object-array sketch (the
+ *     `changes: Array<{ path }>`                   `{ path, assumption }`
+ *                                                  shape from a Story body).
+ *
+ * Paths are trimmed; empty / non-string entries are dropped. A Story with
+ * no declared footprint yields an empty set, which (by `storiesOverlap`'s
+ * contract) means it overlaps with nothing and is never withheld by the
+ * co-dispatch guard.
+ *
+ * @param {StoryRecord} story
+ * @returns {Set<string>}
+ */
+export function storyFootprint(story) {
+  const out = new Set();
+  const push = (entry) => {
+    const path =
+      typeof entry === 'string'
+        ? entry
+        : typeof entry?.path === 'string'
+          ? entry.path
+          : null;
+    if (!path) return;
+    const trimmed = path.trim();
+    if (trimmed) out.add(trimmed);
+  };
+  if (Array.isArray(story?.files)) for (const e of story.files) push(e);
+  if (Array.isArray(story?.changes)) for (const e of story.changes) push(e);
+  if (Array.isArray(story?.changeset)) for (const e of story.changeset) push(e);
+  return out;
+}
+
+/**
+ * File-overlap co-dispatch guard. Returns `true` when two Stories' declared
+ * file footprints intersect on at least one path — meaning they would race
+ * the same file if dispatched onto parallel `story-<id>` branches in the
+ * same beat. Two Stories that overlap MUST NOT both appear in one dispatch
+ * set; one is withheld until the other clears.
+ *
+ * An empty footprint on either side means "no known overlap" → `false`. A
+ * Story that declares no files is therefore never withheld by this guard.
+ *
+ * @param {StoryRecord} a
+ * @param {StoryRecord} b
+ * @returns {boolean}
+ */
+export function storiesOverlap(a, b) {
+  const fa = storyFootprint(a);
+  if (fa.size === 0) return false;
+  const fb = storyFootprint(b);
+  if (fb.size === 0) return false;
+  for (const path of fa) {
+    if (fb.has(path)) return true;
+  }
+  return false;
+}
+
+/**
+ * Select the set of Stories safe to dispatch on this beat.
+ *
+ * Algorithm (continuous, dependency-driven — no wave barrier):
+ *
+ *   1. **Adjacency.** Re-derive `Map<id, depIds[]>` from the supplied
+ *      records via `buildStoryAdjacency`. The `dropForeign` flag controls
+ *      how a dependency on an id **outside** the supplied set is treated:
+ *      - `dropForeign: false` (default, standalone-path semantics) — the
+ *        foreign dependency still gates the dependent: an absent dependency
+ *        is treated as not-yet-done and withholds the dependent until it
+ *        completes (preserves the operator-DAG contract).
+ *      - `dropForeign: true` (Epic-path semantics) — a foreign edge is
+ *        pruned so the DAG stays closed over the scheduled Story set. An
+ *        Epic's Stories depend only on siblings, so a `blocked by #N` whose
+ *        target is out-of-scope (a foreign id, or a typo) must be dropped,
+ *        not treated as a permanent unsatisfiable gate — otherwise the
+ *        dependent Story is never schedulable and the run silently strands
+ *        it. This matches `build-wave-dag.js`, which builds the Epic
+ *        wave DAG with the same default-`dropForeign` builder.
+ *   2. **Done set.** Union the caller-supplied `doneIds` with every record
+ *      that classifies as `done` (live label / closed issue). A Story's
+ *      dependency counts as satisfied iff it is in this union.
+ *   3. **Eligibility.** A Story is *eligible* when it classifies as `ready`
+ *      (not done / blocked / executing) **and** every one of its
+ *      dependencies is in the done set. This is the no-false-barrier
+ *      property: C depending only on A is eligible the instant A is done,
+ *      even while an unrelated B is still pending.
+ *   4. **Capacity.** The dispatch set never exceeds `slots = max(0,
+ *      globalCap − inFlight)`. `inFlight` is the caller's count of Stories
+ *      already occupying a slot (executing / closing / dispatched-not-yet-
+ *      labelled). When `slots <= 0`, the result is empty.
+ *   5. **Overlap guard.** Greedily admit eligible Stories in ascending-id
+ *      order, skipping any whose file footprint overlaps an
+ *      already-admitted Story (`storiesOverlap`). A withheld Story stays
+ *      eligible and is naturally re-considered on the next beat once its
+ *      overlapping peer has cleared.
+ *
+ * The result is deterministic: eligible Stories are considered in
+ * ascending-id order, so the same inputs always yield the same set.
+ *
+ * @param {object} args
+ * @param {StoryRecord[]} args.stories  Live Story records in scope.
+ * @param {Array<number|string>|Set<number|string>} [args.doneIds]
+ *   Ids the caller already knows are done (e.g. from a prior beat). Merged
+ *   with records that classify as done.
+ * @param {number} [args.inFlight=0]    Count of Stories already occupying a
+ *   slot. Subtracted from `globalCap` to compute remaining capacity.
+ * @param {number} args.globalCap       Hard ceiling on total concurrent
+ *   Stories.
+ * @param {boolean} [args.dropForeign=false] Adjacency closure policy (see
+ *   step 1 above). `false` keeps a foreign dependency as a gate
+ *   (standalone / operator-DAG semantics); `true` prunes foreign edges so
+ *   the DAG stays closed over the scheduled set (Epic semantics).
+ * @returns {StoryRecord[]} The dispatch set: a subset of `stories`,
+ *   ascending by id, overlap-free, length ≤ `globalCap − inFlight`.
+ */
+export function selectReadySet({
+  stories,
+  doneIds = [],
+  inFlight = 0,
+  globalCap,
+  dropForeign = false,
+} = {}) {
+  const records = Array.isArray(stories) ? stories : [];
+  const cap = Number.isInteger(globalCap) ? globalCap : 0;
+  const inFlightCount =
+    Number.isInteger(inFlight) && inFlight > 0 ? inFlight : 0;
+  const slots = Math.max(0, cap - inFlightCount);
+  if (slots <= 0 || records.length === 0) return [];
+
+  // Step 1 — adjacency keyed by id. The `dropForeign` policy decides whether
+  // a dependency on an id outside the supplied set gates the dependent
+  // (false) or is pruned (true). See the JSDoc above for the per-path
+  // rationale.
+  const adjacency = buildStoryAdjacency(records, { dropForeign });
+
+  // Step 2 — done set = caller-supplied ids ∪ records that classify done.
+  const done = new Set();
+  for (const raw of doneIds instanceof Set ? doneIds : (doneIds ?? [])) {
+    const id = Number(raw);
+    if (Number.isInteger(id)) done.add(id);
+  }
+  const byId = new Map();
+  for (const rec of records) {
+    const id = storyIdOf(rec);
+    if (id === null) continue;
+    byId.set(id, rec);
+    if (classifyStory(rec) === 'done') done.add(id);
+  }
+
+  // Step 3 — eligible: ready AND all dependencies done. Ascending id for
+  // deterministic admission order.
+  const eligibleIds = [];
+  for (const id of [...byId.keys()].sort((a, b) => a - b)) {
+    const rec = byId.get(id);
+    if (classifyStory(rec) !== 'ready') continue;
+    const deps = adjacency.get(id) ?? [];
+    if (deps.every((dep) => done.has(dep))) eligibleIds.push(id);
+  }
+
+  // Steps 4 + 5 — greedily admit up to `slots`, skipping file-overlap
+  // collisions against the already-admitted set.
+  const selected = [];
+  for (const id of eligibleIds) {
+    if (selected.length >= slots) break;
+    const rec = byId.get(id);
+    if (selected.some((picked) => storiesOverlap(picked, rec))) continue;
+    selected.push(rec);
+  }
+  return selected;
+}