valent-pipeline 0.5.1 → 0.5.3

package/bin/cli.js

@@ -133,6 +133,17 @@ program
     await sprintPackCmd(options);
   });
 
+// resolve-eligible command (meta-loop: cross-epic candidate eligibility)
+program
+  .command('resolve-eligible')
+  .description('Deterministically resolve which pending backlog items are eligible for the next sprint (dependency chains stay together)')
+  .option('--backlog <path>', 'Backlog file (YAML/JSON); resolves its `items`')
+  .option('--stories <path>', 'Explicit item array (YAML/JSON); overrides --backlog')
+  .action(async (options) => {
+    const { resolveEligibleCmd } = await import('../src/commands/resolve-eligible.js');
+    await resolveEligibleCmd(options);
+  });
+
 // calibrate command (meta-loop: estimation-accuracy arithmetic)
 program
   .command('calibrate')

package/package.json

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

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

@@ -332,10 +332,15 @@ if (!validation.valid) {
   throw new Error(`sprint ${sprintId} plan failed validation: ${(validation.errors || []).join('; ')}`)
 }
 
-// Shaped to feed straight into sprint.workflow.js.
-const packedSet = new Set(pack.sprint_stories)
-const plannedStories = sizedStories
-  .filter((s) => packedSet.has(s.storyId))
+// Shaped to feed straight into sprint.workflow.js. Order by `pack.sprint_stories`, NOT by
+// grooming/candidate order: sprint-pack emits stories in dependency-safe order (every prerequisite
+// before its dependent) and sprint.workflow.js runs the batch SEQUENTIALLY in array order on a
+// shared branch — so a dependent must not precede its prerequisite. This is what lets a dependency
+// chain ship together in one sprint.
+const sizedById = new Map(sizedStories.map((s) => [s.storyId, s]))
+const plannedStories = pack.sprint_stories
+  .map((id) => sizedById.get(id))
+  .filter(Boolean)
   .map((s) => ({ storyId: s.storyId, projectType: s.projectType, profiles: s.profiles }))
 
 return {

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

@@ -5,15 +5,19 @@
  * by scripts/test-workflow.js. Opt-in, not the default. The Codex provider keeps the
  * markdown-skill Lead (hybrid, R3).
  *
- * The retrospective is the ONE place the meta-loop adds genuine *quality*, not just reliable
- * structure (R5): the prose retro is a fixed single pass; here the aggregate review runs
- * LOOP-UNTIL-DRY (keep reviewing until K consecutive rounds surface nothing new) followed by a
- * COMPLETENESS-CRITIC ("which pattern did we not check?"). That is the same rigor that makes
- * CRITIC's 3-pass and JUDGE the strongest existing features, applied to the learning loop.
+ * A retrospective LEARNS from what the sprint already produced — it does NOT re-review the code.
+ * Finding bugs is CRITIC/JUDGE's job, and they already did it as a gate DURING the sprint; by the
+ * time the retro runs the code has shipped, so a fresh review here is both too late to gate and a
+ * duplication of work. (An earlier design ran a loop-until-dry aggregate review + completeness-
+ * critic on opus — that bolted the pipeline's most expensive pattern onto the stage that should be
+ * the cheapest, for little value. The one genuine cross-story blind spot — seams between stories
+ * that per-story CRITIC can't see — now lives where it can still gate: the sprint-end integration
+ * gate in sprint.workflow.js.)
  *
- * Flow: calibrate (CLI) -> analyze -> aggregate-review (loop-until-dry) -> completeness-critic
- *       -> directives (agent proposes; CODE enforces impact gating + the architectural-invariant
- *          guard) -> embed (CLI).
+ * Flow: calibrate (CLI) -> synthesize (mine the sprint's OWN artifacts — CRITIC reviews, JUDGE
+ *       rejections, QA bugs, rejection-cycle/cost data — into correction directives) -> directives
+ *       gating (agent proposes; CODE enforces impact gating + the architectural-invariant guard)
+ *       -> embed (CLI). Bounded and cheap: no opus review loop.
  *
  * The deterministic pieces are NOT in this script: calibration arithmetic is
  * `node .valent-pipeline/bin/cli.js calibrate` (src/lib/sprint.js); embedding is `node .valent-pipeline/bin/cli.js db embed`.
@@ -21,21 +25,19 @@
  * GATING and INVARIANT GUARD are deterministic policy, so they are enforced HERE in code —
  * the agent only proposes; the script decides what gets applied vs. surfaced for approval.
  *
- * args: { batchNumber, sprintId?, storyOutputDirs?: string[], dryRounds?: number, maxRounds?: number, models? }
- *   sprintId present => sprint-mode (calibration runs). dryRounds = consecutive empty rounds
- *   that end the loop-until-dry (default 2). maxRounds caps it (default 5). `models` is the
- *   pipeline-config.yaml `models` tier->roles map, passed through by the invoking skill so
- *   per-agent model tiers stay config-driven (editable via `valent configure`). Omit it to use
- *   the baked-in default. See sprint.workflow.js for the full rationale.
+ * args: { batchNumber, sprintId?, storyOutputDirs?: string[], models?, reasoning? }
+ *   sprintId present => sprint-mode (calibration runs). `models` is the pipeline-config.yaml
+ *   `models` tier->roles map, passed through by the invoking skill so per-agent model tiers stay
+ *   config-driven (editable via `valent configure`). Omit it to use the baked-in default. See
+ *   sprint.workflow.js for the full rationale.
  */
 
 export const meta = {
   name: 'valent-retro',
-  description: 'Retrospective: calibrate, loop-until-dry aggregate review, gated directives, embed (Workflow)',
+  description: 'Retrospective: calibrate, synthesize directives from sprint artifacts, gate, embed (Workflow)',
   phases: [
     { title: 'Calibrate', detail: 'node .valent-pipeline/bin/cli.js calibrate (estimation accuracy, in code) — sprint mode' },
-    { title: 'Analyze', detail: 'CRITIC/QA/JUDGE batch outputs + cost' },
-    { title: 'Aggregate', detail: 'loop-until-dry 3-pass aggregate review + completeness critic (R5)' },
+    { title: 'Synthesize', detail: 'mine CRITIC/QA/JUDGE/cost artifacts -> propose correction directives' },
     { title: 'Directives', detail: 'agent proposes; code enforces impact gating + invariant guard' },
     { title: 'Embed', detail: 'node .valent-pipeline/bin/cli.js db embed (persist curated patterns)' },
   ],
@@ -43,39 +45,6 @@ export const meta = {
 
 // --- schemas (inlined) ---
 
-const FINDINGS_SCHEMA = {
-  type: 'object',
-  required: ['schema', 'findings'],
-  additionalProperties: true,
-  properties: {
-    schema: { const: 1 },
-    findings: {
-      type: 'array',
-      items: {
-        type: 'object',
-        required: ['id', 'summary'],
-        properties: {
-          id: { type: 'string' },
-          summary: { type: 'string' },
-          severity: { type: 'string' },
-          stories: { type: 'array', items: { type: 'string' } },
-        },
-      },
-    },
-  },
-}
-
-const COMPLETENESS_SCHEMA = {
-  type: 'object',
-  required: ['schema', 'gaps'],
-  additionalProperties: true,
-  // gaps = review angles NOT yet covered (e.g. "no security-boundary scan run"). Empty => complete.
-  properties: {
-    schema: { const: 1 },
-    gaps: { type: 'array', items: { type: 'string' } },
-  },
-}
-
 const DIRECTIVES_SCHEMA = {
   type: 'object',
   required: ['schema', 'directives'],
@@ -124,8 +93,6 @@ function parseArgs(x) {
 const a = parseArgs(args)
 const batchNumber = a.batchNumber
 const sprintId = a.sprintId || null
-const dryRounds = a.dryRounds ?? 2
-const maxRounds = a.maxRounds ?? 5
 if (batchNumber == null) throw new Error('args must include { batchNumber }')
 
 // --- per-agent model tiers ----------------------------------------------------
@@ -133,12 +100,11 @@ if (batchNumber == null) throw new Error('args must include { batchNumber }')
 // args.models by the invoking skill — a Workflow script can't read files. We invert it
 // to role->tier and overlay it on a baked-in default so the workflow self-hosts a sane
 // assignment even when args.models is absent. Static + args only => journal-replay safe.
-// Retro stages map to synthetic role keys (not the single RETROSPECTIVE persona) so each
-// stage can be tuned independently: the loop-until-dry aggregate review + completeness
-// critic are the genuine quality work (RETRO-REVIEW -> opus); analyze/directives are
-// lighter (RETRO -> sonnet); calibrate/embed/IO are mechanical (haiku).
+// Retro stages map to synthetic role keys (not the single RETROSPECTIVE persona) so each stage can
+// be tuned independently. The retro is learning, not review, so there is no opus tier here:
+// synthesis/judgment over existing artifacts is RETRO -> sonnet; calibrate/embed/IO are mechanical
+// (haiku). The cross-story review that used to justify opus now lives in the sprint-end gate.
 const DEFAULT_MODELS = {
-  'RETRO-REVIEW': 'opus',
   RETRO: 'sonnet',
   CALIBRATE: 'haiku', EMBED: 'haiku', PERSIST: 'haiku',
 }
@@ -185,9 +151,6 @@ const retroPrompt = (instruction, returnContract) => {
     (returnContract || 'Return your findings as the JSON object specified.')
 }
 
-// A stable de-dup key so loop-until-dry converges (don't re-count the same finding).
-const findingKey = (f) => `${(f.summary || '').toLowerCase().trim().slice(0, 80)}`
-
 // ---------------------------------------------------------------------------
 
 let calibration = null
@@ -202,93 +165,33 @@ if (sprintId) {
   log(`calibration: ${(calibration.flagged_pairs || []).length} flagged pair(s); velocity unstable=${calibration.velocity?.unstable}`)
 }
 
-phase('Analyze')
-await agent(
-  retroPrompt(
-    'Run analyze.md: read all CRITIC reviews, QA-B bug reports, JUDGE rejections, and cost data; categorize rejection/bug patterns.',
-    'Return ONLY { schema:1, findings:[{id,summary,severity,stories}] } as JSON.',
-  ),
-  { label: 'analyze', phase: 'Analyze', schema: FINDINGS_SCHEMA, model: modelFor('RETRO') },
-)
-
-phase('Aggregate')
-// LOOP-UNTIL-DRY (R5): re-run the 3-pass aggregate review until `dryRounds` consecutive
-// rounds surface nothing new, deduping against everything already seen. A simple
-// fixed-pass review (the prose behavior) misses the tail; this does not.
-const seen = new Set()
-const confirmed = []
-let dry = 0
-let round = 0
-while (dry < dryRounds && round < maxRounds) {
-  round += 1
-  const r = await agent(
-    retroPrompt(
-      `Run aggregate-review.md (round ${round}): 3-pass CRITIC-style review of the aggregate diff (last retro tag to HEAD) — ` +
-        `correctness across story boundaries, convention/pattern drift, architecture/integration. ` +
-        `Report ONLY findings not already reported in earlier rounds.`,
-      'Return ONLY { schema:1, findings:[{id,summary,severity,stories}] } as JSON.',
-    ),
-    { label: `aggregate:round-${round}`, phase: 'Aggregate', schema: FINDINGS_SCHEMA, model: modelFor('RETRO-REVIEW') },
-  )
-  const fresh = (r.findings || []).filter((f) => !seen.has(findingKey(f)))
-  if (!fresh.length) {
-    dry += 1
-    log(`aggregate round ${round}: dry (${dry}/${dryRounds})`)
-    continue
-  }
-  dry = 0
-  for (const f of fresh) seen.add(findingKey(f))
-  confirmed.push(...fresh)
-  log(`aggregate round ${round}: +${fresh.length} new finding(s) (${confirmed.length} total)`)
-}
-
-// COMPLETENESS-CRITIC (R5): ask what review angle we never ran. Each named gap gets one
-// targeted review round; anything it surfaces joins the confirmed set.
-const critic = await agent(
-  retroPrompt(
-    `We ran ${round} aggregate-review round(s) and found ${confirmed.length} finding(s). ` +
-      `What review angle was NOT covered (e.g. a modality, a security boundary, a contract surface)? ` +
-      `List only genuine gaps — empty if coverage is complete.`,
-    'Return ONLY { schema:1, gaps:["..."] } as JSON.',
-  ),
-  { label: 'completeness-critic', phase: 'Aggregate', schema: COMPLETENESS_SCHEMA, model: modelFor('RETRO-REVIEW') },
-)
-if ((critic.gaps || []).length) {
-  log(`completeness-critic surfaced ${critic.gaps.length} gap(s) — running targeted reviews`)
-  const extra = await parallel(
-    critic.gaps.map((gap, i) => () =>
-      agent(
-        retroPrompt(`Targeted aggregate review for the previously-uncovered angle: "${gap}". Report only findings not already reported.`,
-          'Return ONLY { schema:1, findings:[{id,summary,severity,stories}] } as JSON.'),
-        { label: `aggregate:gap-${i + 1}`, phase: 'Aggregate', schema: FINDINGS_SCHEMA, model: modelFor('RETRO-REVIEW') },
-      )),
-  )
-  for (const r of extra.filter(Boolean)) {
-    for (const f of (r.findings || [])) {
-      if (!seen.has(findingKey(f))) { seen.add(findingKey(f)); confirmed.push(f) }
-    }
-  }
-}
-log(`aggregate review complete: ${confirmed.length} confirmed finding(s)`)
-
-phase('Directives')
-// The agent PROPOSES directives (with impact_level + a touchesInvariant flag). The CODE
-// enforces the policy — deterministic, uncheatable — per the §5b determinism map:
+phase('Synthesize')
+// Learning, not review: one pass mines the artifacts the sprint ALREADY produced (CRITIC reviews,
+// QA-B bug reports, JUDGE rejections, rejection-cycle counts, cost data) per analyze.md, then drafts
+// correction directives per directives.md — no fresh code review, no opus loop. The agent proposes
+// directives (with impact_level + a touchesInvariant flag); the CODE below enforces the policy —
+// deterministic, uncheatable — per the §5b determinism map:
 //   - touchesInvariant      -> ARCHITECTURE-CONFLICT: never auto-applied, surfaced to the user
 //   - impact_level 'high'   -> proposal only, requires user approval
 //   - 'low' / 'medium'      -> auto-applied (medium also notifies the Lead)
 const drafted = await agent(
   retroPrompt(
-    `Run directives.md against the ${confirmed.length} confirmed finding(s)` +
-      (calibration ? ' and the calibration metrics' : '') +
-      `. For EACH proposed directive set impact_level (low|medium|high) and touchesInvariant=true if it would skip test ` +
-      `execution, allow shipping without evidence, weaken a quality gate, or exempt mandatory tests. Do NOT self-censor — ` +
-      `propose it and flag it; the orchestrator decides what gets applied.`,
+    `Run analyze.md then directives.md: read all CRITIC reviews, QA-B bug reports, JUDGE rejections, ` +
+      `rejection-cycle counts, and cost data from this sprint's story outputs; categorize the recurring ` +
+      `rejection/bug patterns; then propose correction directives for those patterns` +
+      (calibration ? ' and for the calibration metrics' : '') +
+      `. Do NOT re-review the shipped code for new bugs — that was CRITIC/JUDGE's job during the sprint; ` +
+      `your job is to learn from what they already found. For EACH proposed directive set impact_level ` +
+      `(low|medium|high) and touchesInvariant=true if it would skip test execution, allow shipping without ` +
+      `evidence, weaken a quality gate, or exempt mandatory tests. Do NOT self-censor — propose it and flag ` +
+      `it; the orchestrator decides what gets applied.`,
     'Return ONLY { schema:1, directives:[{target_agent,directive,reason,impact_level,touchesInvariant,category}] } as JSON.',
   ),
-  { label: 'draft-directives', phase: 'Directives', schema: DIRECTIVES_SCHEMA, model: modelFor('RETRO') },
+  { label: 'synthesize', phase: 'Synthesize', schema: DIRECTIVES_SCHEMA, model: modelFor('RETRO') },
 )
 
+phase('Directives')
+
 const all = drafted.directives || []
 const conflicts = all.filter((d) => d.touchesInvariant)
 const highImpact = all.filter((d) => !d.touchesInvariant && d.impact_level === 'high')
@@ -328,9 +231,7 @@ const embed = await agent(
 return {
   batchNumber,
   sprintId,
-  aggregate_findings: confirmed.length,
-  aggregate_rounds: round,
-  completeness_gaps: (critic.gaps || []).length,
+  directives_proposed: all.length,
   directives_applied: applied.length,
   directives_pending_approval: proposals.length,
   architecture_conflicts: conflicts.length,

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

@@ -59,6 +59,7 @@ export const meta = {
     { title: 'Critic', detail: 'three independent passes in parallel -> triage -> rejection loop (code-owned cap)' },
     { title: 'QA', detail: 'execute tests against real infra' },
     { title: 'Judge', detail: 'evidence-based ship decision' },
+    { title: 'Integration', detail: 'single cross-story seam review — only when >1 story touched overlapping files' },
   ],
 }
 
@@ -123,6 +124,31 @@ const FINDINGS_SCHEMA = {
   },
 }
 
+// Sprint-end cross-story seam review. Advisory: stories already passed JUDGE, so this does not
+// re-gate them — it surfaces integration findings to be filed as bugs against the affected stories.
+const INTEGRATION_SCHEMA = {
+  type: 'object',
+  required: ['schema', 'verdict', 'findings'],
+  additionalProperties: true,
+  properties: {
+    schema: { const: 1 },
+    verdict: { enum: ['clean', 'findings'] },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['summary'],
+        properties: {
+          summary: { type: 'string' },
+          severity: { enum: ['High', 'Med', 'Low'] },
+          files: { type: 'array', items: { type: 'string' } },
+          stories: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    },
+  },
+}
+
 const RESOLVED_GRAPH_SCHEMA = {
   type: 'object',
   required: ['tasks', 'skipped'],
@@ -190,7 +216,7 @@ for (const s of batch) {
 // assignment even when args.models is absent. Static + args only => journal-replay safe.
 //   gates -> opus (judgment), spec/build -> sonnet, CLI-runners/IO -> haiku.
 const DEFAULT_MODELS = {
-  READINESS: 'opus', CRITIC: 'opus', JUDGE: 'opus',
+  READINESS: 'opus', CRITIC: 'opus', JUDGE: 'opus', INTEGRATION: 'opus',
   REQS: 'sonnet', UXA: 'sonnet', 'QA-A': 'sonnet', 'QA-B': 'sonnet',
   BEND: 'sonnet', FEND: 'sonnet', DATA: 'sonnet', 'MCP-DEV': 'sonnet',
   LIBDEV: 'sonnet', DOCGEN: 'sonnet', IAC: 'sonnet', MOBILE: 'sonnet',
@@ -284,11 +310,66 @@ for (let i = 0; i < batch.length; i++) {
 
 const shippedCount = results.filter((r) => r.shipped).length
 log(`sprint complete: ${shippedCount}/${results.length} shipped`)
+
+// Sprint-end integration gate: per-story CRITIC reviews each diff in ISOLATION and never sees two
+// stories together, so cross-story SEAMS (a module touched by >1 story, mismatched integration
+// points) are its one structural blind spot. Cover it with a SINGLE bounded review — but only when
+// it could find something: >1 story shipped AND at least two of them touched an overlapping file.
+// No loop, no completeness-critic (that disproportionate apparatus was removed from the retro for
+// the same reason). Advisory only — stories already passed JUDGE, so findings are surfaced as bugs
+// to file, not a re-gate. Overlap is computed from the dev handoff `files`, so a disjoint sprint
+// (every story in its own corner of the tree) skips the gate entirely.
+const integration = await runIntegrationGate(results.filter((r) => r.shipped))
+
 return {
   shipped: results.every((r) => r.shipped),
   stories_shipped: shippedCount,
   stories_rolled_over: results.length - shippedCount,
   results,
+  integration,
+}
+
+// runIntegrationGate: returns null when not warranted (≤1 shipped story or no file overlap), else
+// the single review's structured result ({ verdict, findings }) for the orchestrator to file as bugs.
+async function runIntegrationGate(shipped) {
+  if (shipped.length < 2) return null
+
+  // Files touched by more than one shipped story = the seams worth reviewing.
+  const owners = new Map() // file -> Set(storyId)
+  for (const r of shipped) {
+    for (const f of r.files || []) {
+      if (!owners.has(f)) owners.set(f, new Set())
+      owners.get(f).add(r.storyId)
+    }
+  }
+  const overlapFiles = [...owners.entries()].filter(([, s]) => s.size > 1).map(([f]) => f)
+  if (!overlapFiles.length) {
+    log(`integration gate: skipped — ${shipped.length} stories shipped but no overlapping files`)
+    return null
+  }
+
+  log(`integration gate: ${overlapFiles.length} file(s) touched by >1 story — running single cross-story review`)
+  const result = await agent(
+    [
+      `You are **INTEGRATION**, the sprint-end cross-story seam reviewer for this batch.`,
+      ``,
+      `Per-story CRITIC reviewed each story's diff in isolation and CANNOT see two stories together.`,
+      `Review ONLY the cross-story SEAMS — the files below were each modified by more than one story`,
+      `this sprint, so that is where integration mismatches hide (incompatible signatures, ordering`,
+      `assumptions, duplicated/diverging logic, broken shared invariants).`,
+      ``,
+      `Overlapping files: ${JSON.stringify(overlapFiles)}`,
+      `Shipped stories: ${JSON.stringify(shipped.map((r) => r.storyId))}`,
+      ``,
+      `Do a SINGLE focused pass. Do NOT re-review within-story correctness (CRITIC already did) and do`,
+      `NOT hunt for unrelated issues. Report only genuine cross-story seam problems; empty if the seams`,
+      `are clean. Return ONLY { schema:1, verdict:"clean"|"findings", findings:[{summary,severity,files,stories}] } as JSON.`,
+    ].join('\n'),
+    { label: 'gate:integration', phase: 'Integration', schema: INTEGRATION_SCHEMA, model: modelFor('INTEGRATION') },
+  )
+  const findings = result.findings || []
+  log(`integration gate: ${findings.length} cross-story finding(s)`)
+  return { verdict: result.verdict, findings, overlapFiles }
 }
 
 // ===========================================================================
@@ -373,7 +454,7 @@ async function runStory(story) {
   const devFiles = builds.filter(Boolean).flatMap((b) => (Array.isArray(b.files) ? b.files : []))
   if (devFiles.length === 0) {
     log(`${storyId}: dev phase reported no files — nothing to review; skipping CRITIC/QA/JUDGE, rolling over`)
-    return { storyId, shipped: false, verdict: 'blocked', reason: 'no-dev-output', skipped: graph.skipped }
+    return { storyId, shipped: false, verdict: 'blocked', reason: 'no-dev-output', skipped: graph.skipped, files: [] }
   }
 
   phase('Critic')
@@ -386,7 +467,7 @@ async function runStory(story) {
   const decision = await runGate(storyId, 'JUDGE', 'judge.md',
     'Review evidence (tests, traceability, bugs) and make the ship decision.', 'Judge', null)
 
-  return { storyId, shipped: decision.verdict === 'pass', verdict: decision.verdict, skipped: graph.skipped }
+  return { storyId, shipped: decision.verdict === 'pass', verdict: decision.verdict, skipped: graph.skipped, files: devFiles }
 
   // --- per-story closures over storyId/devTasks ----------------------------
 

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

@@ -52,12 +52,27 @@ Loop sprints until all stories are shipped, blocked, or cancelled. Each iteratio
 **ALWAYS** read `{epic_progress_path}` and `{backlog_path}` from disk at the top of each sprint.
 
 #### 4b. Check for remaining work (cross-epic)
-Read `{backlog_path}` (all epics). If no `pending` stories with met dependencies remain:
-- all remaining `shipped`/`cancelled` → project complete, go to Step 5;
-- remaining `blocked`/`blocked-on-user` → report blockers, go to Step 5;
-- remaining `pending` but all with unmet `depends_on` → circular/missing prerequisite, report and stop.
+**Do not hand-walk the dependency graph.** Candidate eligibility is deterministic — call the
+resolver instead of deciding by hand which `depends_on` are "met":
 
-Otherwise collect the eligible pending story IDs across ALL epics whose dependencies are met (with `projectType` from config and each story's `testing_profiles`) as this sprint's candidate list.
+```
+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.
+
+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.
 
 #### 4c. Plan the sprint
 Invoke `plan.workflow.js` via the **Workflow tool**:
@@ -81,11 +96,13 @@ Workflow({
 })
 ```
 
-Runs each story sequentially through the per-story pipeline on a shared branch, rolling over any story JUDGE rejects or that trips the cap. Returns `{ shipped, stories_shipped, stories_rolled_over, results: [...] }`. Record its `runId`.
+Runs each story sequentially through the per-story pipeline on a shared branch, rolling over any story JUDGE rejects or that trips the cap. After the batch, a **sprint-end integration gate** runs a single cross-story seam review — but ONLY when >1 story shipped and at least two touched an overlapping file (otherwise it's skipped). Returns `{ shipped, stories_shipped, stories_rolled_over, results: [...], integration }`, where `integration` is `null` (not warranted) or `{ verdict, findings, overlapFiles }`. Record its `runId`.
 
 #### 4e. Update progress + re-resolve dependencies
 For each shipped story: move it to `stories_completed` with a compact one-line outcome tagged with its epic; update `total_completed` / `last_updated`; **FIFO at 80 lines** (evict oldest). Read and follow `.valent-pipeline/steps/orchestration/update-backlog-status.md`. Then **re-check whether any previously blocked stories are now unblocked** (their `depends_on` / `blocked_by_bugs` may have been resolved by what just shipped) — these become eligible for the next sprint's candidate list.
 
+If the sprint result's `integration.findings` is non-empty, file each as a `bug` backlog item (per `update-backlog-status.md`'s conditional-ship bug format) against the affected stories' epic, so the cross-story seam issue is tracked and prioritized like any other bug.
+
 #### 4f. Retrospective (mandatory, blocking)
 Invoke `retro.workflow.js`:
 
@@ -96,7 +113,7 @@ Workflow({
 })
 ```
 
-Record its `runId`. Retro runs every sprint and tightens future sizing.
+Record its `runId`. Retro runs every sprint and tightens future sizing. It **learns from the sprint's own artifacts** — calibration (CLI), one synthesis pass that mines CRITIC/JUDGE/QA/cost data into correction directives, then embed — and is bounded and cheap (no fresh code review; that is CRITIC/JUDGE's job during the sprint, and cross-story seams are covered by the sprint-end integration gate in 4d).
 
 #### 4g. Continue
 Increment `{n}` and return to Step 4a. **Do NOT ask permission to continue between sprints** — the project loop is autonomous.

package/src/commands/resolve-eligible.js

@@ -0,0 +1,49 @@
+import { readFileSync, existsSync } from 'fs';
+import { isAbsolute, join, extname } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { resolveEligibleStories } from '../lib/sprint.js';
+
+/** Read a JSON or YAML file (by extension) and return the parsed object. */
+function loadStructured(path) {
+  const abs = isAbsolute(path) ? path : join(process.cwd(), path);
+  if (!existsSync(abs)) throw new Error(`File not found: ${abs}`);
+  const raw = readFileSync(abs, 'utf-8');
+  return extname(abs).toLowerCase() === '.json' ? JSON.parse(raw) : parseYaml(raw);
+}
+
+/**
+ * `valent-pipeline resolve-eligible (--backlog <path> | --stories <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.
+ *
+ * Emits JSON: { eligible: [ids in priority order], blocked: [{ id, reason }] }.
+ *
+ * --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.
+ */
+export async function resolveEligibleCmd(options) {
+  let items;
+  try {
+    const src = options.stories || options.backlog;
+    if (!src) throw new Error('Either --backlog <path> or --stories <path> is required.');
+    const data = loadStructured(src);
+    items = Array.isArray(data) ? data : data.items;
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (!Array.isArray(items)) {
+    console.error('Error: no item list found (expected an array or an `items:` list).');
+    process.exit(1);
+  }
+
+  const result = resolveEligibleStories(items);
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(0);
+}

package/src/lib/sprint.js

@@ -97,6 +97,107 @@ export function packSprint(stories, velocity) {
   };
 }
 
+/**
+ * Cross-epic candidate eligibility for the next sprint — which pending backlog items can be
+ * groomed now. A deterministic replacement for the hand-run "collect pending stories whose
+ * dependencies are met" step in the project skills (`valent-run-project*` Step 4b).
+ *
+ * The OLD rule only surfaced a story whose prerequisites were ALREADY shipped, so a dependency
+ * chain trickled in one story per sprint (A ships, then B becomes eligible, then C...). This
+ * instead surfaces a pending story whenever its whole dependency chain is LIVE — every
+ * prerequisite is either already shipped or another pending story that is itself eligible.
+ * `packSprint` then auto-includes those prerequisites in dependency-safe order and the sprint
+ * executes them sequentially, so a chain can run together in ONE sprint (up to the velocity
+ * budget; overflow falls to the groomed buffer).
+ *
+ * Only items whose dependency chain hits a DEAD prerequisite (cancelled / blocked /
+ * blocked-on-user, or missing from the backlog) or a blocking bug that is not yet resolved are
+ * withheld — reported in `blocked` with the offending ref. Removal propagates: a dependent of a
+ * withheld story is itself withheld (the fixpoint below), so a dead prerequisite blocks its
+ * whole downstream chain.
+ *
+ * @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.
+ * @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.
+ */
+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 byId = new Map(list.map((it) => [it.id, it]));
+  const blocked = []; // { id, reason }
+  const blockedIds = new Set();
+  const recordBlocked = (id, reason) => {
+    if (blockedIds.has(id)) return;
+    blockedIds.add(id);
+    blocked.push({ id, reason });
+  };
+
+  // A blocking bug is cleared when its referenced bug item is shipped (update-backlog-status.md)
+  // or no longer present in the backlog (the entry was removed). Otherwise the dependent waits.
+  const bugBlocker = (it) => {
+    for (const bugId of it.blocked_by_bugs ?? []) {
+      const bug = byId.get(bugId);
+      if (bug && !satisfied.has(bug.status)) return bugId;
+    }
+    return null;
+  };
+
+  // Seed the eligible set with every candidate that isn't bug-blocked, then iterate to a fixpoint:
+  // drop any whose dependency chain reaches a dead/missing/withheld prerequisite, propagating the
+  // removal downstream until stable.
+  const eligible = new Set();
+  for (const it of list) {
+    if (it.status !== candidateStatus) continue;
+    const bug = bugBlocker(it);
+    if (bug) recordBlocked(it.id, `blocked by unresolved bug "${bug}"`);
+    else eligible.add(it.id);
+  }
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const id of [...eligible]) {
+      const it = byId.get(id);
+      for (const depId of depsOf(it)) {
+        const dep = byId.get(depId);
+        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)) {
+          // 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)`;
+        }
+        // else: dep is satisfied or in an in-progress status, or a still-eligible candidate -> OK.
+        if (reason) {
+          eligible.delete(id);
+          recordBlocked(id, reason);
+          changed = true;
+          break;
+        }
+      }
+    }
+  }
+
+  const priorityOf = (id) => byId.get(id)?.priority ?? Infinity;
+  const eligibleIds = [...eligible].sort(
+    (a, b) => priorityOf(a) - priorityOf(b) || String(a).localeCompare(String(b)),
+  );
+
+  return { eligible: eligibleIds, blocked };
+}
+
 /** Sample standard deviation; 0 when fewer than 2 samples. */
 function stdev(values) {
   if (values.length < 2) return 0;