valent-pipeline 0.5.1 → 0.5.2

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.2",
   "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/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**:

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;