valent-pipeline 0.5.4 → 0.5.6

package/package.json

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

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

@@ -101,6 +101,7 @@ const PACK_SCHEMA = {
     buffer_story_ids: { type: 'array', items: { type: 'string' } },
     points_planned: { type: 'integer' },
     remaining_capacity: { type: 'integer' },
+    over_budget: { type: 'boolean' },
   },
 }
 
@@ -291,10 +292,14 @@ const sized = await parallel(
           }),
           { label: `estimate:${est.toLowerCase()}:${g.storyId}`, phase: 'Size', schema: ESTIMATE_SCHEMA, model: modelFor(est) },
         )),
-    ).then((ests) => ({
-      ...g,
-      points: ests.filter(Boolean).reduce((sum, e) => sum + (e.points || 0), 0),
-    }))
+    ).then((ests) => {
+      // Each estimator sizes the WHOLE story from its surface's lens (BEND sees the full story,
+      // IAC sees the full story), so the points are the MAX single estimate — NOT the sum.
+      // Summing double-counts shared scaffolding: a 2-profile story is not twice the work, and
+      // summing systematically over-points multi-profile stories until they exceed velocity.
+      const vals = ests.filter(Boolean).map((e) => e.points || 0)
+      return { ...g, points: vals.length ? Math.max(...vals) : 0 }
+    })
   }),
 )
 const sizedStories = sized.filter(Boolean)
@@ -313,10 +318,13 @@ phase('Pack')
 // Deterministic greedy packing happens in code (src/lib/sprint.js), invoked via the CLI.
 const pack = await agent(
   `Run exactly: \`node .valent-pipeline/bin/cli.js sprint-pack --velocity ${velocity} --backlog ${backlogPath}\` ` +
-    `in the project root and return its stdout JSON verbatim (fields: sprint_stories, buffer_story_ids, points_planned, remaining_capacity).`,
+    `in the project root and return its stdout JSON verbatim (fields: sprint_stories, buffer_story_ids, points_planned, remaining_capacity, over_budget).`,
   { label: 'sprint-pack', phase: 'Pack', schema: PACK_SCHEMA, model: modelFor('PACK') },
 )
 log(`packed ${pack.sprint_stories.length} stories (${pack.points_planned} pts); buffer: ${pack.buffer_story_ids.length}`)
+if (pack.over_budget) {
+  log(`⚠ sprint ${sprintId} is OVER BUDGET: the highest-priority story exceeds velocity ${velocity} and was planned alone — consider splitting it (${pack.points_planned} pts vs ${velocity} velocity)`)
+}
 
 phase('Validate')
 // Write the human plan + machine status artifacts, tag the backlog, then cross-check in code.

package/pipeline/steps/orchestration/sprint-init.md

@@ -19,9 +19,14 @@ node .valent-pipeline/bin/cli.js db query-velocity
 ```
 
 **Velocity rules:**
-- **Sprint 1:** Use `{sprint_initial_velocity}` from config (default: 60 points)
-- **Sprint 2-4:** Average points shipped across all completed sprints
-- **Sprint 5+:** Simple moving average of the last 5 sprints (older data ages out)
+
+Velocity is your *capacity* — how many points you can ship when capacity is the binding constraint. Only **capacity-constrained** sprints carry that signal. A **supply-constrained** sprint (one that shipped everything eligible with capacity to spare — it ran out of groomed/eligible work, not out of capacity) reflects how much work *existed*, not how much you *could do*, so counting it would falsely ratchet velocity down. Each sprint's status YAML summary records its `constraint:` (`capacity` or `supply`) — see sprint-review.md Step 2.
+
+- **Sprint 1:** Use `{sprint_initial_velocity}` from config (default: 60 points).
+- **Later sprints:** Moving average of `points_shipped` over **capacity-constrained sprints only** — exclude every `constraint: supply` sprint.
+  - 2-4 capacity-constrained sprints available: average their `points_shipped`.
+  - 5+ available: SMA of the last 5 capacity-constrained sprints (older data ages out).
+- **If no capacity-constrained sprint has happened yet** (e.g. early sprints were all supply-constrained because the backlog is a dependency chain): keep `{sprint_initial_velocity}`. **Never lower velocity based on a supply-constrained sprint** — this is the failure that drives a healthy initial velocity down to a tiny number after one small starter story.
 
 Record: `current_velocity = {value}` points.
 

package/pipeline/steps/orchestration/sprint-plan.md

@@ -12,9 +12,17 @@ node .valent-pipeline/bin/cli.js sprint-pack --velocity {current_velocity} --bac
 ```
 
 It emits JSON: `sprint_stories` (packed, in dependency-safe order), `buffer_story_ids`
-(groomed but not packed — the mid-sprint pull buffer, see Step 1b), `points_planned`, and
-`remaining_capacity`. Only `groomed` stories are eligible; lower `priority` number = higher
-priority; a groomed prerequisite is auto-included before its dependent when it fits the budget.
+(groomed but not packed — the mid-sprint pull buffer, see Step 1b), `points_planned`,
+`remaining_capacity`, and `over_budget`. Only `groomed` stories are eligible; lower `priority`
+number = higher priority; a groomed prerequisite is auto-included before its dependent when it
+fits the budget.
+
+**If `over_budget` is `true`:** no story fit the velocity budget, so the highest-priority groomed
+story (plus its groomed prerequisites) was planned ALONE and `points_planned` exceeds velocity
+(`remaining_capacity` is negative). This is the anti-stall path — the sprint still makes progress.
+Surface it to the user: this story is larger than a full sprint and is a **split candidate** — note
+it in the sprint plan and consider asking REQS to break it into smaller stories before a future run.
+Do NOT treat the negative `remaining_capacity` as room to groom more stories.
 
 Use this output directly for Steps 1b–8. If the backlog isn't the right input shape, pass an
 explicit story array with `--stories <path>` instead of `--backlog`.

package/pipeline/steps/orchestration/sprint-review.md

@@ -20,7 +20,11 @@ Update `sprint-{n}-plan.md` Sprint Summary:
 - Points rolled over: sum of unexecuted story points
 - Total elapsed minutes: sum of execution time (not grooming)
 - Velocity this sprint: points_shipped (all shipped stories count toward velocity, including pulls)
-- Updated velocity (SMA-5): compute new moving average
+- **Sprint constraint:** classify this sprint so the next sprint-init calibrates velocity correctly:
+  - `capacity` — capacity was the binding constraint: stories were left in the groomed buffer or rolled over (more eligible work existed than fit), OR the plan was over-budget (a single oversized story planned alone). These sprints count toward velocity.
+  - `supply` — supply was the binding constraint: the sprint shipped all eligible/groomed work with capacity to spare (groomed buffer empty AND positive `capacity_remaining` at plan time). These sprints do NOT count toward velocity (they measure available work, not capacity).
+  Record as `constraint:` in the status YAML summary.
+- Updated velocity (SMA-5): recompute the moving average over **capacity-constrained sprints only** (see sprint-init.md Step 2). A `supply`-constrained sprint must not lower velocity.
 - Mid-sprint pulls: count and list (stories pulled from groomed buffer during execution)
 
 ## Step 3: Finalize Sprint Status YAML

package/pipeline/steps/orchestration/sprint-size.md

@@ -34,8 +34,9 @@ For each story with status `groomed`:
    - `iac` in profiles → send to IAC
    Multiple profiles can be active (e.g., `[api, data-pipeline]` sends to both BEND and DATA).
 4. Agents write estimation files (`{agent}-estimation.md`)
-5. **Record points:** sum all agent estimates for the story.
-   `story_points = sum of all agent estimates received`
+5. **Record points:** take the **maximum** single estimate, NOT the sum.
+   `story_points = max of all agent estimates received`
+   Each estimator sizes the *whole* story from its surface's lens (BEND sizes the entire story, IAC sizes the entire story), so their estimates overlap on shared scaffolding. Summing double-counts that overlap and systematically over-points multi-profile stories until they exceed velocity. The max is the best-informed single read. (If you believe two surfaces carry genuinely independent, non-overlapping work, flag it for the Lead rather than silently summing.)
 6. Update story's `story_points` field in `{backlog_path}`
 
 ## Step 3: Update Sprint State

package/pipeline/templates/sprint-status.template.yaml

@@ -54,3 +54,4 @@ summary:  # filled post-sprint
   total_elapsed_minutes: null
   velocity_this_sprint: null
   velocity_sma5: null
+  constraint: null  # capacity | supply — only `capacity` sprints count toward velocity (see sprint-review.md Step 2)

package/src/board/public/app.js

@@ -90,9 +90,16 @@ function statusKind(status, column) {
 /* ---------- Chips ----------------------------------------------------------------------- */
 function statusChip(story) {
   const k = statusKind(story.status, story.column);
-  return h('span', { class: `chip chip--status ${k.cls}`, title: `status: ${k.label}` },
+  // When the status was inferred from on-disk artifacts (backlog status lags an in-flight groom),
+  // mark it so the board reads honestly: a dotted chip + a title explaining the real backlog state.
+  const inferred = story.status_source === 'artifacts';
+  const title = inferred
+    ? `status: ${k.label} (inferred from artifacts — backlog still says ${story.backlog_status || 'pending'})`
+    : `status: ${k.label}`;
+  return h('span', { class: `chip chip--status ${k.cls}${inferred ? ' chip--inferred' : ''}`, title },
     h('span', { class: 'chip__icon', 'aria-hidden': 'true' }, k.icon),
     k.label,
+    inferred ? h('span', { class: 'chip__inferred-mark', 'aria-hidden': 'true', title: 'inferred' }, '~') : null,
   );
 }
 

package/src/board/public/styles.css

@@ -457,6 +457,11 @@ body {
 .chip--status.is-idle { color: var(--ink-muted); background: var(--idle-soft); border-color: transparent; }
 .chip--status.is-warn { color: var(--warn); background: var(--warn-soft); border-color: transparent; }
 
+/* Inferred status — derived from on-disk artifacts because the backlog status lags an active
+   groom. Dashed outline + a faint "~" mark signals "best-effort, not yet persisted". */
+.chip--status.chip--inferred { border: 1px dashed currentColor; }
+.chip__inferred-mark { opacity: 0.6; font-weight: 600; margin-left: 1px; }
+
 /* ---------- Backlog list ---------------------------------------------------------------- */
 .backlog {
   max-width: 1100px;

package/src/lib/board.js

@@ -60,6 +60,30 @@ export function columnForStatus(status) {
   return STATUS_TO_COLUMN.get(status) || 'other'
 }
 
+/**
+ * Grooming artifacts, most-advanced phase first. Their presence means a story is mid-groom even
+ * when the backlog `status` still says `pending` — the Workflow path (plan.workflow.js) grooms
+ * the batch in-memory and only persists `status: groomed` at the very end, so the backlog status
+ * lags reality during a live groom (and there is often no pipeline-state.json at all). The board
+ * is a projection, so it infers the grooming phase from the artifacts the groom agents have
+ * already written, exactly as it overlays the live current_story over a lagging backlog.
+ */
+const GROOMING_ARTIFACT_STATUS = [
+  ['readiness-review.md', 'readiness-review'],
+  ['qa-test-spec.md', 'test-case-development'],
+  ['uxa-spec.md', 'ux-spec'],
+  ['reqs-brief.md', 'requirements-spec'],
+]
+
+/** The most-advanced grooming status implied by present artifacts, or null if none. */
+export function inferGroomingStatus(artifacts) {
+  if (!Array.isArray(artifacts)) return null
+  for (const [file, status] of GROOMING_ARTIFACT_STATUS) {
+    if (artifacts.includes(file)) return status
+  }
+  return null
+}
+
 /** Story points, tolerating either field name (matches sprint.js `pointsOf`). */
 function pointsOf(item) {
   const p = item.points ?? item.story_points
@@ -74,10 +98,29 @@ function depsOf(item) {
 /** Normalize one backlog item into a board story (stable shape regardless of input quirks). */
 function normalizeStory(item, artifactsByStory) {
   const id = item.id
-  const status = item.status || 'pending'
+  const backlogStatus = item.status || 'pending'
+  const artifacts = (artifactsByStory && artifactsByStory[id]) || []
+
+  // Reflect an in-flight groom the backlog status hasn't caught up to: if a story still reads
+  // `pending` (its column would be Backlog) but grooming artifacts already exist on disk, surface
+  // the inferred grooming phase so it shows in Grooming instead of sitting in Backlog. An explicit
+  // forward status (groomed/sprint-planned/development/…/shipped) always wins — only `pending` is
+  // upgraded, and `status_source` records that the status was derived, not read from the backlog.
+  let status = backlogStatus
+  let statusSource = 'backlog'
+  if (columnForStatus(backlogStatus) === 'backlog') {
+    const inferred = inferGroomingStatus(artifacts)
+    if (inferred) {
+      status = inferred
+      statusSource = 'artifacts'
+    }
+  }
+
   return {
     id,
     status,
+    backlog_status: backlogStatus,
+    status_source: statusSource,
     column: columnForStatus(status),
     depends_on: depsOf(item),
     points: pointsOf(item),
@@ -88,7 +131,7 @@ function normalizeStory(item, artifactsByStory) {
     active: false, // set true below if it matches current_story
     phase: null, // overlaid from current_story when active
     branch: null,
-    artifacts: (artifactsByStory && artifactsByStory[id]) || [],
+    artifacts,
     cost: null, // { tokens, agent_ms, invocations, roles:[...] } when an audit report is supplied
   }
 }

package/src/lib/sprint.js

@@ -31,13 +31,19 @@ function depsOf(story) {
  * @param {Array} stories - candidate stories: { id, points|story_points, priority, depends_on, status }
  * @param {number} velocity - capacity in story points
  * @returns {{ sprint_stories: string[], buffer_story_ids: string[], points_planned: number,
- *             remaining_capacity: number, velocity: number }}
+ *             remaining_capacity: number, velocity: number, over_budget: boolean }}
  *
  * Only `groomed` stories are eligible (matches the source). Lower `priority` number = higher
  * priority; missing priority sorts last. A prerequisite is auto-included only when it is also
  * `groomed` and fits the remaining budget — deps already `shipped`/done are assumed satisfied
  * and silently skipped, exactly as the prose specifies.
  *
+ * Anti-stall: if no story fits the budget at all (the smallest groomed story is larger than the
+ * whole velocity), the highest-priority groomed story is planned ALONE — with its groomed
+ * prerequisites pulled in first — accepting an over-budget sprint (`over_budget: true`,
+ * `remaining_capacity` may go negative). This prevents an oversized story from stalling the
+ * project forever; the planner should surface it as a split candidate.
+ *
  * Preserved quirk: if a story's dependency chain does not fully fit, the deps already added
  * for it stay in the sprint (capacity is not rolled back) and the dependent is skipped. This
  * matches the source pseudocode; `validateSprint` is the safety net for ordering consistency.
@@ -85,6 +91,26 @@ export function packSprint(stories, velocity) {
     // else: skip this story, try smaller ones to fill capacity
   }
 
+  // Anti-stall: if NOTHING fit the budget but groomed work exists, the smallest eligible story is
+  // larger than the entire velocity. Returning an empty sprint would stall the project forever
+  // (that story can never be packed, so the loop never progresses). Plan the highest-priority
+  // groomed story alone — pulling in its groomed prerequisites first so order stays dependency-safe
+  // — accepting an over-budget sprint. `over_budget` is flagged so the planner can surface
+  // "this story exceeds velocity; planned alone — consider splitting it."
+  let overBudget = false;
+  if (sprintStories.length === 0 && byPriority.length > 0) {
+    const forceAdd = (story) => {
+      if (inSprint.has(story.id)) return;
+      for (const depId of depsOf(story)) {
+        const dep = byId.get(depId);
+        if (dep && dep.status === 'groomed' && !inSprint.has(depId)) forceAdd(dep);
+      }
+      add(story);
+    };
+    forceAdd(byPriority[0]);
+    overBudget = true;
+  }
+
   const buffer = groomed.filter((s) => !inSprint.has(s.id)).map((s) => s.id);
   const pointsPlanned = sprintStories.reduce((sum, id) => sum + pointsOf(byId.get(id)), 0);
 
@@ -94,6 +120,7 @@ export function packSprint(stories, velocity) {
     points_planned: pointsPlanned,
     remaining_capacity: remaining,
     velocity,
+    over_budget: overBudget,
   };
 }