valent-pipeline 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valent-pipeline",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "v3 multi-agent AI pipeline for software development lifecycle",
   "type": "module",
   "bin": {

package/pipeline/orchestrators/claude-code/plan.workflow.js

@@ -148,6 +148,15 @@ if (!stories.length || !sprintId || typeof velocity !== 'number') {
   throw new Error('args must include { stories:[{storyId,projectType}], sprintId, velocity }')
 }
 
+// A candidate arrives EITHER ungroomed (needs the full groom -> size pass below) OR already groomed
+// — a leftover from a PRIOR sprint's grooming that this sprint only needs to PACK. The caller flags
+// the latter `groomed: true` and carries its `profiles` from the backlog (resolveEligibleStories
+// surfaces these as `groomedBuffer`). We groom only the ungroomed set; the buffer is folded straight
+// into the pack + return so it executes WITHOUT being re-specced or re-gated. Skipping this is what
+// stranded the buffer before: nothing drained the groomed overflow once a sprint over-groomed.
+const toGroom = stories.filter((s) => !s.groomed)
+const buffer = stories.filter((s) => s.groomed)
+
 // --- per-agent model tiers ----------------------------------------------------
 // Tiers come from pipeline-config.yaml `models` (a tier->roles map), passed in as
 // args.models by the invoking skill — a Workflow script can't read files. We invert it
@@ -230,36 +239,44 @@ phase('Groom')
 // story bounces off the profile gate and eats a re-tag + full re-review cycle. So derive once here,
 // write the backlog in a SINGLE agent (one writer => no race on the shared YAML), and reuse the same
 // profiles for the in-memory flow below so the backlog tag, UXA-skip, and sizing can never diverge.
-const tag = await agent(
-  [
-    'You are the grooming orchestrator performing **Step 0: Pre-Grooming Profile Tagging**, before any spec agent runs.',
-    '',
-    'For EACH story below: read `stories/{storyId}/story.md` (its ACs + scope) and derive its `testing_profiles` using these criteria (multiple may apply):',
-    '- `api` — owns API endpoints, backend routes, business logic, or database changes',
-    '- `ui` — owns UI components, pages, or visual elements',
-    '- `data-pipeline` — ETL, data transformation, or batch processing',
-    '- `mcp-server` — MCP server tools, handlers, or protocol work',
-    '- `library` — shared library/package (exports, packaging, versioning)',
-    '- `document-generation` — document/report template or generation pipeline work',
-    '- `iac` — infrastructure (Terraform, CloudFormation, Kubernetes, CI/CD)',
-    "Tag a profile only when the story OWNS that surface. A story that merely CONSUMES another story's API endpoint (no endpoint/DB change of its own) is NOT `api`.",
-    '',
-    `Then write \`testing_profiles: [...]\` onto each story's entry in \`${backlogPath}\` — preserve every other field and the item order. If an entry already has testing_profiles, only correct it when a required profile is missing.`,
-    '',
-    `Stories: ${JSON.stringify(stories.map((s) => s.storyId))}.`,
-    '',
-    'Return ONLY { stories: [{ storyId, testing_profiles:[...] }, ...] } as JSON, covering every story above.',
-  ].join('\n'),
-  { label: 'pre-groom-profile-tag', phase: 'Groom', schema: PROFILE_TAG_SCHEMA, model: modelFor('PERSIST') },
-)
-const profileById = new Map(
-  (tag.stories || []).map((s) => [s.storyId, Array.isArray(s.testing_profiles) ? s.testing_profiles : []]),
-)
-log(`tagged testing_profiles on ${profileById.size}/${stories.length} stories before the readiness gate`)
+// Tag only the ungroomed set — buffer stories already carry `testing_profiles` on the backlog (and
+// in args), so re-deriving them is wasted work. A pure buffer-drain sprint (nothing to groom) skips
+// this agent entirely.
+const profileById = new Map()
+if (toGroom.length) {
+  const tag = await agent(
+    [
+      'You are the grooming orchestrator performing **Step 0: Pre-Grooming Profile Tagging**, before any spec agent runs.',
+      '',
+      'For EACH story below: read `stories/{storyId}/story.md` (its ACs + scope) and derive its `testing_profiles` using these criteria (multiple may apply):',
+      '- `api` — owns API endpoints, backend routes, business logic, or database changes',
+      '- `ui` — owns UI components, pages, or visual elements',
+      '- `data-pipeline` — ETL, data transformation, or batch processing',
+      '- `mcp-server` — MCP server tools, handlers, or protocol work',
+      '- `library` — shared library/package (exports, packaging, versioning)',
+      '- `document-generation` — document/report template or generation pipeline work',
+      '- `iac` — infrastructure (Terraform, CloudFormation, Kubernetes, CI/CD)',
+      "Tag a profile only when the story OWNS that surface. A story that merely CONSUMES another story's API endpoint (no endpoint/DB change of its own) is NOT `api`.",
+      '',
+      `Then write \`testing_profiles: [...]\` onto each story's entry in \`${backlogPath}\` — preserve every other field and the item order. If an entry already has testing_profiles, only correct it when a required profile is missing.`,
+      '',
+      `Stories: ${JSON.stringify(toGroom.map((s) => s.storyId))}.`,
+      '',
+      'Return ONLY { stories: [{ storyId, testing_profiles:[...] }, ...] } as JSON, covering every story above.',
+    ].join('\n'),
+    { label: 'pre-groom-profile-tag', phase: 'Groom', schema: PROFILE_TAG_SCHEMA, model: modelFor('PERSIST') },
+  )
+  for (const s of tag.stories || []) {
+    profileById.set(s.storyId, Array.isArray(s.testing_profiles) ? s.testing_profiles : [])
+  }
+  log(`tagged testing_profiles on ${profileById.size}/${toGroom.length} stories before the readiness gate`)
+}
+if (buffer.length) log(`draining ${buffer.length} groomed buffer stor${buffer.length === 1 ? 'y' : 'ies'} (specced in a prior sprint — pack only)`)
 
 // Pipelined: spec agents don't touch code, so stories flow assembly-line through the stages.
+// Only the ungroomed set is groomed here; the already-groomed buffer skips straight to packing.
 const groomed = await pipeline(
-  stories,
+  toGroom,
   // Stage 1: REQS produces reqs-brief.md. Profiles are already derived + on the backlog (Step 0);
   // we pass them in so REQS selects the right profile-applicable sections (draft-brief.md).
   async (story) => {
@@ -314,12 +331,30 @@ const groomed = await pipeline(
         buildPrompt({ role: target, promptFile: `${target.toLowerCase()}.md`, storyId: g.storyId, taskSubject: 'Address the READINESS rejection and rewrite the affected spec.' }),
         { label: `rework:${target.toLowerCase()}:${g.storyId}`, phase: 'Groom', schema: HANDOFF_SCHEMA, model: modelFor(target) },
       )
+      // Cascade re-derivation downstream. Grooming is a derivation chain (REQS -> UXA -> QA-A): when an
+      // upstream spec is reworked, the specs derived from it are now stale and CONTRADICT the correction.
+      // Re-running only the rejection target leaves that staleness in place, so the next gate just rejects
+      // again on the downstream artifact — a guaranteed wasted reject/rework cycle per contract fix. Re-derive
+      // every dependent spec here, before re-gating, so the whole chain re-syncs in one pass.
+      const up = target.toUpperCase()
+      if (up === 'REQS' && g.profiles.includes('ui')) {
+        await agent(
+          buildPrompt({ role: 'UXA', promptFile: 'uxa.md', storyId: g.storyId, taskSubject: 'Re-derive uxa-spec.md from the reworked reqs-brief.md — the upstream brief changed during readiness rework, so re-sync the spec to it.' }),
+          { label: `cascade:uxa:${g.storyId}`, phase: 'Groom', schema: HANDOFF_SCHEMA, model: modelFor('UXA') },
+        )
+      }
+      if (up === 'REQS' || up === 'UXA') {
+        await agent(
+          buildPrompt({ role: 'QA-A', promptFile: 'qa-a.md', storyId: g.storyId, taskSubject: 'Re-derive qa-test-spec.md from the reworked upstream spec — reqs-brief/uxa-spec changed during readiness rework, so re-sync the test spec to the corrected contract.' }),
+          { label: `cascade:qa-a:${g.storyId}`, phase: 'Groom', schema: HANDOFF_SCHEMA, model: modelFor('QA-A') },
+        )
+      }
     }
   },
 )
 
 const readyStories = groomed.filter(Boolean).filter((g) => g.groomedStatus === 'groomed')
-log(`groomed ${readyStories.length}/${stories.length} stories`)
+log(`groomed ${readyStories.length}/${toGroom.length} stories`)
 
 phase('Size')
 // Each story is sized by every estimator whose profile is present; story_points = the sum.
@@ -395,11 +430,26 @@ if (!validation.valid) {
 // `groomed: true` — these stories were fully specced + passed the READINESS gate during grooming
 // above, and their reqs-brief/uxa-spec/qa-test-spec are on disk. sprint.workflow.js reads this flag
 // and SKIPS its Spec + Readiness phases, so execution doesn't redundantly re-spec and re-gate.
-const sizedById = new Map(sizedStories.map((s) => [s.storyId, s]))
+// Metadata for EVERY packable story: the ones groomed this run (sizedStories) AND the pre-existing
+// groomed buffer (from args). sprint-pack reads the whole backlog, so `pack.sprint_stories` can name
+// buffer stories too — they must be returned with their projectType/profiles or sprint.workflow.js
+// has nothing to execute. (Building this only from sizedStories is exactly what silently dropped the
+// buffer before: packed + tagged sprint-planned, but never handed downstream.)
+const metaById = new Map(sizedStories.map((s) => [s.storyId, { projectType: s.projectType, profiles: s.profiles }]))
+for (const b of buffer) {
+  if (!metaById.has(b.storyId)) {
+    metaById.set(b.storyId, { projectType: b.projectType, profiles: Array.isArray(b.profiles) ? b.profiles : [] })
+  }
+}
+const missingMeta = pack.sprint_stories.filter((id) => !metaById.has(id))
+if (missingMeta.length) {
+  log(`⚠ packed but NOT executable — no projectType/profiles passed for: ${missingMeta.join(', ')}. ` +
+    `These are groomed in the backlog but were not handed to plan as candidates or buffer; they will be ` +
+    `tagged sprint-planned yet skipped this sprint. Pass them (with profiles) via groomedBuffer.`)
+}
 const plannedStories = pack.sprint_stories
-  .map((id) => sizedById.get(id))
-  .filter(Boolean)
-  .map((s) => ({ storyId: s.storyId, projectType: s.projectType, profiles: s.profiles, groomed: true }))
+  .filter((id) => metaById.has(id))
+  .map((id) => ({ storyId: id, projectType: metaById.get(id).projectType, profiles: metaById.get(id).profiles, groomed: true }))
 
 return {
   sprintId,

package/pipeline/orchestrators/claude-code/sprint.workflow.js

@@ -636,12 +636,28 @@ async function runStory(story) {
 
     phase('Readiness')
     await runGate(storyId, 'READINESS', 'readiness.md', 'Validate the spec chain (reqs/uxa/qa) is implementation-ready.',
-      'Readiness', (verdict) => {
+      'Readiness', async (verdict) => {
         const target = verdict.rejectionTarget || 'REQS'
-        return spawn(target, `${target.toLowerCase()}.md`, 'Address the READINESS rejection and rewrite the affected spec.', {
+        await spawn(target, `${target.toLowerCase()}.md`, 'Address the READINESS rejection and rewrite the affected spec.', {
           label: `rework:${target.toLowerCase()}:${storyId}`,
           phase: 'Readiness',
         })
+        // Cascade re-derivation downstream. Spec is a derivation chain (REQS -> UXA -> QA-A): when an
+        // upstream spec is reworked, the specs derived from it are now stale and contradict the correction.
+        // Re-running only the rejection target leaves that staleness in place, so the next gate just rejects
+        // again on the downstream artifact — a guaranteed wasted reject/rework cycle. Re-derive every dependent
+        // spec here, before re-gating, so the chain re-syncs in one pass. Mirrors plan.workflow.js.
+        const up = target.toUpperCase()
+        if (up === 'REQS' && has('uxa')) {
+          await spawn('UXA', 'uxa.md', 'Re-derive uxa-spec.md from the reworked reqs-brief.md — the upstream brief changed during readiness rework, so re-sync the spec to it.', {
+            label: `cascade:uxa:${storyId}`, phase: 'Readiness',
+          })
+        }
+        if (up === 'REQS' || up === 'UXA') {
+          await spawn('QA-A', 'qa-a.md', 'Re-derive qa-test-spec.md from the reworked upstream spec — reqs-brief/uxa-spec changed during readiness rework, so re-sync the test spec to the corrected contract.', {
+            label: `cascade:qa-a:${storyId}`, phase: 'Readiness',
+          })
+        }
       })
   }
 

package/skills/valent-run-epic-workflow/SKILL.md

@@ -56,7 +56,11 @@ Loop sprints until no pending epic stories with met dependencies remain. Each it
 **ALWAYS** read `{epic_progress_path}` and `{backlog_path}` from disk at the top of each sprint. Never trust in-context memory.
 
 #### 4b. Check for remaining work
-Filter `{backlog_path}` by `{epic_id}`. If no `pending` stories with met dependencies remain, exit the loop → Step 5. Collect the eligible pending story IDs (with `projectType` from config and each story's `testing_profiles`) into a candidate list for this sprint.
+Filter `{backlog_path}` by `{epic_id}`, then split the unfinished stories two ways:
+- **ungroomed** (`status: pending`) with met dependencies → need grooming.
+- **groomed buffer** (`status: groomed`, not yet `sprint-planned`/`shipped`) → already specced + readiness-passed in a prior sprint that over-groomed; they only need **packing, not re-grooming**.
+
+If **both** are empty, exit the loop → Step 5. Otherwise build this sprint's candidate list from both: each ungroomed id with its `projectType` (from config); each groomed-buffer id with its `projectType`, its `testing_profiles` (from the backlog entry), and `groomed: true`. (Surfacing the groomed buffer is essential — without it a sprint that grooms more than its velocity packs strands the overflow and the epic loop exits early with stories unbuilt.)
 
 #### 4c. Plan the sprint
 Invoke `plan.workflow.js` via the **Workflow tool**:
@@ -64,11 +68,18 @@ Invoke `plan.workflow.js` via the **Workflow tool**:
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/plan.workflow.js',
-  args: { stories: [{ storyId, projectType }, ...candidates], sprintId: '{epic_id}-sprint-{n}', velocity: {sprint.initial_velocity_points or current calibrated velocity}, models: <config.models or omit>, reasoning: <config.reasoning or omit> }
+  args: {
+    stories: [
+      ...ungroomed.map(id => ({ storyId: id, projectType: '<project.type>' })),
+      ...groomedBuffer.map(id => ({ storyId: id, projectType: '<project.type>', profiles: [/* backlog testing_profiles */], groomed: true })),
+    ],
+    sprintId: '{epic_id}-sprint-{n}', velocity: {sprint.initial_velocity_points or current calibrated velocity},
+    models: <config.models or omit>, reasoning: <config.reasoning or omit>,
+  }
 })
 ```
 
-It grooms, sizes (calibrated Fibonacci), packs to velocity, and validates — returning `{ sprintId, stories: [{ storyId, projectType, profiles }, ...] }`. Record its `runId`.
+It grooms only the ungroomed stories, sizes them (calibrated Fibonacci), packs the whole groomed backlog (buffer + newly groomed) to velocity, and validates — returning `{ sprintId, stories: [{ storyId, projectType, profiles, groomed }, ...], buffer_story_ids }`. **Always pass the groomed buffer** (with `groomed: true` + `profiles`); plan packs it without re-grooming, and logs `⚠ packed but NOT executable` for any packed story whose metadata wasn't supplied. Record its `runId`.
 
 #### 4d. Execute the sprint
 Feed the planned batch straight into `sprint.workflow.js`:

package/skills/valent-run-project-workflow/SKILL.md

@@ -61,20 +61,20 @@ resolver instead of deciding by hand which `depends_on` are "met":
 node .valent-pipeline/bin/cli.js resolve-eligible --backlog {backlog_path}
 ```
 
-It emits `{ eligible: [ids in priority order], blocked: [{ id, reason }] }`. A pending story is
-**eligible** when its whole dependency chain is live — a prerequisite that is itself a pending,
-eligible story is **INCLUDED in this sprint's candidate list**, not deferred to a later sprint.
-That is the point: `plan.workflow.js` packs the chain together (`sprint-pack` orders prerequisites
-before dependents and buffers anything over velocity), and `sprint.workflow.js` runs the batch
-sequentially on a shared branch — so a dependency chain ships together in one sprint, capacity
-permitting. A story is **blocked** (withheld) only when a prerequisite is `cancelled` /
-`blocked` / `blocked-on-user` / missing, or a blocking bug is unresolved.
+It emits `{ eligible, groomedBuffer, blocked }`. **`eligible`** = ungroomed work whose whole
+dependency chain is live — a prerequisite that is itself an eligible candidate is **INCLUDED in this
+sprint**, not deferred (`plan.workflow.js` packs the chain together and `sprint.workflow.js` runs it
+sequentially on a shared branch, so a chain ships in one sprint, capacity permitting). **`groomedBuffer`**
+= stories already specced + readiness-passed in a PRIOR sprint that groomed more than its velocity
+could pack; they only need **packing, not re-grooming**. A story is **blocked** (withheld) only when a
+prerequisite is `cancelled` / `blocked` / `blocked-on-user` / missing, or a blocking bug is unresolved.
 
 Interpret the output:
-- `eligible` is non-empty → these IDs are this sprint's candidate list. Pair each with its
-  `projectType` (from config) and `testing_profiles` for Step 4c.
-- `eligible` is empty and every remaining item is `shipped`/`cancelled` → project complete, go to Step 5.
-- `eligible` is empty but `blocked` is non-empty → report the blocked stories with their reasons, go to Step 5.
+- `eligible` **or** `groomedBuffer` is non-empty → there is work this sprint; build the candidate list
+  for Step 4c. Pair each `eligible` id with its `projectType` (from config); pair each `groomedBuffer`
+  id with its `projectType` **and** its `testing_profiles` read from the backlog entry.
+- both `eligible` and `groomedBuffer` empty, every remaining item `shipped`/`cancelled` → project complete, go to Step 5.
+- both empty but `blocked` is non-empty → report the blocked stories with their reasons, go to Step 5.
 
 #### 4c. Plan the sprint
 Invoke `plan.workflow.js` via the **Workflow tool**:
@@ -82,11 +82,24 @@ Invoke `plan.workflow.js` via the **Workflow tool**:
 ```js
 Workflow({
   scriptPath: '.valent-pipeline/orchestrators/claude-code/plan.workflow.js',
-  args: { stories: [{ storyId, projectType }, ...candidates], sprintId: 'project-sprint-{n}', velocity: {sprint.initial_velocity_points or current calibrated velocity}, models: <config.models or omit>, reasoning: <config.reasoning or omit> }
+  args: {
+    stories: [
+      // ungroomed candidates — plan grooms, sizes, then packs these:
+      ...eligible.map(id => ({ storyId: id, projectType: '<project.type>' })),
+      // groomed buffer — plan packs these as-is (NO re-groom). MUST carry profiles + groomed:true:
+      ...groomedBuffer.map(id => ({ storyId: id, projectType: '<project.type>', profiles: [/* backlog testing_profiles */], groomed: true })),
+    ],
+    sprintId: 'project-sprint-{n}', velocity: {sprint.initial_velocity_points or current calibrated velocity},
+    models: <config.models or omit>, reasoning: <config.reasoning or omit>,
+  }
 })
 ```
 
-Returns `{ sprintId, stories: [{ storyId, projectType, profiles }, ...] }`. Record its `runId`.
+**Always include the `groomedBuffer` stories** (each with `groomed: true` and its `profiles`) alongside
+any ungroomed candidates — that is what drains the buffer. plan grooms only the ungroomed ones, packs
+the whole groomed backlog up to velocity (buffer + newly groomed), and returns just the packed batch.
+A buffer story omitted here is packed but silently skipped — plan now logs `⚠ packed but NOT executable`
+if that happens. Returns `{ sprintId, stories: [{ storyId, projectType, profiles, groomed }, ...], buffer_story_ids }`. Record its `runId`.
 
 #### 4d. Execute the sprint
 Feed the planned batch straight into `sprint.workflow.js`:

package/src/commands/resolve-eligible.js

@@ -16,12 +16,16 @@ function loadStructured(path) {
  *
  * Deterministic cross-epic candidate eligibility for the next sprint (src/lib/sprint.js). Replaces
  * the hand-run "collect pending stories whose dependencies are met" step in the project skills.
- * A pending story is eligible when its whole dependency chain is live (every prerequisite is
- * shipped OR another pending+eligible story), so a dependency chain can be groomed and packed
- * into ONE sprint — packSprint orders the prerequisites first and the sprint executes them
- * sequentially. Stories withheld by a dead/missing prerequisite or unresolved bug are reported.
+ * A story is eligible when its whole dependency chain is live (every prerequisite is shipped OR
+ * another eligible candidate), so a dependency chain can be groomed and packed into ONE sprint —
+ * packSprint orders the prerequisites first and the sprint executes them sequentially. Stories
+ * withheld by a dead/missing prerequisite or unresolved bug are reported.
  *
- * Emits JSON: { eligible: [ids in priority order], blocked: [{ id, reason }] }.
+ * Emits JSON: { eligible, groomedBuffer, blocked }. `eligible` = pending work that still needs
+ * grooming (feed to plan.workflow.js); `groomedBuffer` = already-specced stories left over from a
+ * prior sprint's grooming, ready to pack without re-grooming; `blocked` = [{ id, reason }]. Both
+ * id lists are priority-ordered. Surfacing `groomedBuffer` is what lets the project loop drain a
+ * groomed backlog across sprints instead of stalling once nothing is left `pending`.
  *
  * --backlog reads a backlog file and resolves its `items`. --stories reads an explicit array of
  * items (JSON or YAML); both forms tolerate either an array or an `items:` list.

package/src/lib/sprint.js

@@ -143,24 +143,38 @@ export function packSprint(stories, velocity) {
  * withheld story is itself withheld (the fixpoint below), so a dead prerequisite blocks its
  * whole downstream chain.
  *
+ * Candidate = remaining work eligible for the next sprint. That is BOTH ungroomed work (`pending`,
+ * which still needs grooming) AND already-groomed work waiting in the buffer (`groomed`, already
+ * specced+sized — it only needs packing). Before this, only `pending` counted: once a sprint
+ * groomed more stories than its velocity could pack, the overflow (now `groomed`) became invisible
+ * to the resolver and the project loop stalled with that work stranded. The eligible set is split
+ * on return so the caller can route each bucket correctly (groom the `eligible`, pack the
+ * `groomedBuffer`).
+ *
  * @param {Array} items - backlog items: { id, status, depends_on|dependencies, blocked_by_bugs,
- *        priority }. `type` is irrelevant here — any item in `candidateStatus` is a candidate.
+ *        priority }. `type` is irrelevant here — any item in a candidate status is a candidate.
  * @param {object} [opts]
  *   - satisfiedStatuses: statuses that satisfy a dependency (default ['shipped'])
  *   - deadStatuses: statuses that permanently block a dependent (default
  *     ['cancelled','blocked','blocked-on-user'])
- *   - candidateStatus: status of items considered as candidates (default 'pending')
- * @returns {{ eligible: string[], blocked: Array<{ id: string, reason: string }> }}
- *   `eligible` is ascending-priority ordered (lower number first; missing priority last, ties by
- *   id) so the downstream groom/size/pack sees the most important work first. A prerequisite in
- *   an in-progress status (neither shipped, dead, nor still `pending`) is treated as
- *   already-moving and does NOT block — only genuinely dead/missing/pending-but-withheld deps do.
+ *   - candidateStatuses: statuses considered as candidates (default ['pending','groomed']).
+ *     `candidateStatus` (a single string) is still accepted for back-compat and wins when given.
+ *   - groomedStatus: the candidate status that means "already specced, pack-ready" (default
+ *     'groomed') — eligible items in this status are returned in `groomedBuffer`, not `eligible`.
+ * @returns {{ eligible: string[], groomedBuffer: string[], blocked: Array<{ id, reason }> }}
+ *   `eligible` (still needs grooming) and `groomedBuffer` (pack-ready) are each ascending-priority
+ *   ordered (lower number first; missing priority last, ties by id). A prerequisite in an
+ *   in-progress status (neither shipped, dead, nor a still-eligible candidate) is treated as
+ *   already-moving and does NOT block — only genuinely dead/missing/withheld-candidate deps do.
  */
 export function resolveEligibleStories(items, opts = {}) {
   const list = Array.isArray(items) ? items : [];
   const satisfied = new Set(opts.satisfiedStatuses ?? ['shipped']);
   const dead = new Set(opts.deadStatuses ?? ['cancelled', 'blocked', 'blocked-on-user']);
-  const candidateStatus = opts.candidateStatus ?? 'pending';
+  const groomedStatus = opts.groomedStatus ?? 'groomed';
+  const candidateStatuses = new Set(
+    opts.candidateStatus != null ? [opts.candidateStatus] : opts.candidateStatuses ?? ['pending', groomedStatus],
+  );
 
   const byId = new Map(list.map((it) => [it.id, it]));
   const blocked = []; // { id, reason }
@@ -186,7 +200,7 @@ export function resolveEligibleStories(items, opts = {}) {
   // removal downstream until stable.
   const eligible = new Set();
   for (const it of list) {
-    if (it.status !== candidateStatus) continue;
+    if (!candidateStatuses.has(it.status)) continue;
     const bug = bugBlocker(it);
     if (bug) recordBlocked(it.id, `blocked by unresolved bug "${bug}"`);
     else eligible.add(it.id);
@@ -202,7 +216,7 @@ export function resolveEligibleStories(items, opts = {}) {
         let reason = null;
         if (!dep) reason = `depends on "${depId}" which is missing from the backlog`;
         else if (dead.has(dep.status)) reason = `depends on "${depId}" which is ${dep.status}`;
-        else if (dep.status === candidateStatus && !eligible.has(depId)) {
+        else if (candidateStatuses.has(dep.status) && !eligible.has(depId)) {
           // Prerequisite is a candidate that has itself been withheld — chain is dead upstream.
           reason = `depends on "${depId}" which is not eligible (its own prerequisites are unmet)`;
         }
@@ -222,7 +236,12 @@ export function resolveEligibleStories(items, opts = {}) {
     (a, b) => priorityOf(a) - priorityOf(b) || String(a).localeCompare(String(b)),
   );
 
-  return { eligible: eligibleIds, blocked };
+  // Split the eligible set by grooming-readiness: already-groomed items go to the buffer (the
+  // caller packs them as-is), everything else still needs grooming. Both stay priority-ordered.
+  const groomedBuffer = eligibleIds.filter((id) => byId.get(id)?.status === groomedStatus);
+  const needsGrooming = eligibleIds.filter((id) => byId.get(id)?.status !== groomedStatus);
+
+  return { eligible: needsGrooming, groomedBuffer, blocked };
 }
 
 /** Sample standard deviation; 0 when fewer than 2 samples. */