valent-pipeline 0.2.21 → 0.2.22

package/package.json

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

package/pipeline/docs/prd-completion-audit-design.md

@@ -0,0 +1,132 @@
+# Design: Post-Implementation PRD Completion Audit
+
+**Status:** Proposal  
+**Scope:** Both epic and project mode  
+**Where it runs:** After all stories ship (Step 5 in valent-run-epic and valent-run-project), before writing the epic/project report.
+
+## Problem
+
+The epics-and-stories breakdown is done once, early, and may miss PRD requirements. Stories can also be cancelled or blocked during execution. There is currently no post-implementation check that verifies the full PRD was actually delivered. The existing pre-implementation readiness check (bmad-check-implementation-readiness) runs before any code is written and only validates that epics *claim* to cover FRs — it doesn't verify that shipped code actually delivers them.
+
+## Proposed Solution
+
+A new orchestration step (`sprint-prd-audit.md`) that runs at epic/project completion. It re-reads the PRD, extracts all functional requirements, and checks each against what was actually shipped — generating gap stories for anything missed.
+
+### Trigger Point
+
+Insert between the sprint loop exit and the report generation:
+
+- **valent-run-epic SKILL.md:** After Step 4 loop exits, before Step 5a (Write Epic Report)
+- **valent-run-project SKILL.md:** After Step 4 loop exits, before Step 5a (Write Project Report)
+
+### Step-by-Step Flow
+
+#### Step 1: Extract PRD Functional Requirements
+
+Read the PRD from `{prd_path}` (already a pipeline config variable). Extract every functional requirement (FR), keyed by FR number or section heading. Build a checklist:
+
+```
+FR1: [requirement text] → status: unchecked
+FR2: [requirement text] → status: unchecked
+...
+```
+
+Also extract non-functional requirements (NFRs) that have testable acceptance criteria.
+
+#### Step 2: Map Shipped Stories to FRs
+
+For each shipped story (from `{epic_progress_path}` or `{backlog_path}` where status = `shipped`):
+
+1. Read the story's `reqs-brief.md` from its output directory
+2. Extract which FRs the story claims to address (REQS agent already tags these during grooming)
+3. Mark those FRs as `covered` in the checklist
+
+For cancelled or blocked stories:
+- Extract their claimed FRs
+- Mark as `gap-cancelled` or `gap-blocked`
+
+#### Step 3: Cross-Reference with Test Evidence
+
+For each `covered` FR, verify that shipped test evidence exists:
+
+1. Query the calibration table for the covering story's test results
+2. Check that the story's QA-B test spec includes tests traceable to the FR
+3. If a FR is "covered" by a story but that story had no tests touching the FR, downgrade to `weak-coverage`
+
+#### Step 4: Generate Gap Report
+
+Produce `prd-audit-report.md` in the epic/project output directory:
+
+```markdown
+# PRD Completion Audit
+
+## Coverage Summary
+- Total FRs: {count}
+- Covered (with tests): {count}
+- Weak coverage (no direct tests): {count}
+- Gaps (cancelled/blocked story): {count}
+- Gaps (never mapped to a story): {count}
+- Coverage: {percentage}%
+
+## Gap Details
+
+### Never Mapped to a Story
+| FR | Requirement | Recommendation |
+|----|------------|----------------|
+| FR7 | [text] | Create story in epic {X} |
+
+### Lost to Cancelled/Blocked Stories
+| FR | Requirement | Original Story | Status | Recommendation |
+|----|------------|---------------|--------|----------------|
+| FR3 | [text] | KANBAN-005 | cancelled | Re-scope into new story |
+
+### Weak Coverage (no direct test evidence)
+| FR | Requirement | Covering Story | Recommendation |
+|----|------------|---------------|----------------|
+| FR9 | [text] | KANBAN-012 | Add targeted tests |
+```
+
+#### Step 5: Generate Gap Stories (Optional, User-Confirmed)
+
+If gaps exist:
+
+1. Present the gap report to the user
+2. Ask: "Generate backlog stories for {N} uncovered requirements?"
+3. If confirmed:
+   - For each gap FR, create a new story in `{backlog_path}` with:
+     - `type: story`
+     - `status: pending`
+     - `epic: {epic_id}` (or assign to most relevant epic in project mode)
+     - `title: "Implement FR{N}: {short description}"`
+     - `priority: {next available}`
+     - `source: prd-audit`
+   - Report the new story IDs
+   - These stories are available for the next epic/project run
+
+### Agent Usage
+
+This step is executed by Lead directly — no new agents needed. Lead already has access to read the PRD, backlog, story output directories, and the calibration DB. The step is read-heavy and analytical, not generative.
+
+If the PRD is large (sharded across multiple files), Lead reads all shards. Context pressure is manageable because this runs after all story agents are torn down.
+
+### Configuration
+
+Add to `pipeline-config.yaml` under `sprint:`:
+
+```yaml
+sprint:
+  prd_audit: true          # enable post-implementation PRD audit (default: true)
+  prd_audit_auto_stories: false  # auto-generate gap stories without user confirmation (default: false)
+```
+
+### Dependencies
+
+- REQS agent must tag FRs in `reqs-brief.md` during grooming (already does this)
+- PRD must use numbered/identifiable FR format (standard PRD template already requires this)
+- Calibration table must have test result data per story (already recorded during sprint review)
+
+### Open Questions
+
+1. Should the audit run per-sprint as well, or only at epic/project completion? Per-sprint would catch drift earlier but adds overhead.
+2. For project mode with multiple PRDs (one per epic), should the audit cross-reference all PRDs or just the one matching each epic?
+3. Should `weak-coverage` FRs block the epic/project completion report, or just be informational?

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

@@ -41,6 +41,27 @@ For each story in sprint order:
 
 If a genuine design conflict arises during execution that requires grooming-level deliberation, Lead spawns the relevant grooming agent (REQS, UXA, or QA-A) fresh via Design Council protocol. The freshly spawned agent queries Knowledge/SQLite for grooming context. Kill the temporary agent after deliberation resolves.
 
+### Mid-Sprint Pull from Groomed Buffer
+
+When all planned sprint stories have been executed and the time budget has NOT been exceeded:
+
+1. Read `{backlog_path}` for stories with status `groomed` that are not tagged with a sprint (the groomed buffer from sprint-plan.md Step 1b)
+2. If buffer is empty, proceed to sprint review
+3. If buffer has stories, pull them into the current sprint using the same packing logic as sprint-plan.md Step 1:
+   - `remaining_capacity = current_velocity - points_completed_this_sprint`
+   - Pack by priority with dependency auto-inclusion, skipping stories that don't fit (`continue`, not `break`)
+4. For each pulled story:
+   - Add `sprint: {current_sprint_id}` tag in `{backlog_path}`
+   - Set status to `sprint-planned`
+   - Add to `sprint-{n}-plan.md` Planned Stories table (mark as "pulled mid-sprint")
+   - Add to `sprint-{n}-status.yaml`
+   - Update `pipeline-state.json`: append to `stories_planned`, increment `points_planned`
+5. Execute pulled stories using the same per-story flow above (Story 2+ rules — all Phase 2 agents spawned fresh)
+6. After each pulled story ships, repeat: check time budget, check buffer, pull more if both allow
+7. When the time budget is exceeded OR the buffer is empty, proceed to sprint review
+
+This avoids starting a new sprint (with its groom/size/plan overhead) when there's already groomed work ready to execute.
+
 ### Sprint Rollover
 
 When the time budget is exceeded:
@@ -50,6 +71,7 @@ When the time budget is exceeded:
    - Reset status to `pending`
    - These stories will be picked up by the next sprint's planning phase
 3. Record rolled-over story IDs in the sprint plan artifact
+4. Groomed buffer stories that were NOT pulled retain their `groomed` status — they carry forward to the next sprint's planning phase without re-grooming
 
 ## Update Sprint State
 

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

@@ -33,15 +33,18 @@ When a candidate story depends on another `pending` story, auto-include the prer
 
 ## Step 4: Determine Groom Target Count
 
-Calculate how many stories to groom:
+Calculate how many stories to groom. We groom **2x velocity** worth to maintain a buffer — stories that don't fit the current sprint are already groomed and sized for the next one, and can be pulled into the current sprint if it finishes early.
 
 ```
 avg_points_per_story = AVG(story_points) from calibration table (last 5 sprints)
                        defaults to 5 when no history exists
-groom_target = ceil(current_velocity / avg_points_per_story)
+already_groomed = count of stories in backlog with status 'groomed' or 'sizing' (not yet sprint-planned)
+groom_target = ceil((current_velocity * 2) / avg_points_per_story) - already_groomed
 groom_target = max(groom_target, 3)  # floor of 3
 ```
 
+The `already_groomed` offset prevents re-grooming stories that were groomed in a prior sprint but not planned (the buffer from last sprint carries forward).
+
 ## Step 5: Update Sprint State
 
 Write to `pipeline-state.json`:

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

@@ -29,16 +29,22 @@ for story in groomed_stories_by_priority:
         sprint_stories.append(story)
         remaining_capacity -= story.story_points
     else:
-        break  # don't skip — priority order matters
+        continue  # skip this story, try smaller ones to fill capacity
 ```
 
+## Step 1b: Identify Groomed Buffer
+
+After packing, any groomed+sized stories that did NOT fit into the sprint remain in the **groomed buffer**. These are available for mid-sprint pull (see sprint-execute.md) without needing another groom/size cycle.
+
+Record `buffer_story_ids` = groomed stories not in `sprint_stories` (keep their `groomed` status — do NOT reset them).
+
 ## Step 2: Check if Sprint Needs More Stories
 
-If `remaining_capacity >= 1` AND there are ungroomed `pending` stories in the backlog:
+If `remaining_capacity >= 1` AND there are ungroomed `pending` stories in the backlog AND the groomed buffer is empty:
 - Return to sprint-groom.md to groom additional stories
 - Then return here to re-pack
 
-Guard: do NOT enter groom-more loop if `remaining_capacity < 1` point.
+Guard: do NOT enter groom-more loop if `remaining_capacity < 1` point or if the groomed buffer already has stories (they'll be pulled mid-sprint if needed).
 
 ## Step 3: Write Sprint Plan Artifact
 

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

@@ -14,13 +14,14 @@ Read each story's `phase-timing.md` for `total_elapsed_minutes` and count reject
 ## Step 2: Fill Sprint Summary
 
 Update `sprint-{n}-plan.md` Sprint Summary:
-- Stories shipped: count and list
+- Stories shipped: count and list (distinguish originally planned vs mid-sprint pulls)
 - Stories rolled over: count and list (if any)
-- Points shipped: sum of shipped story points
+- Points shipped: sum of shipped story points (includes mid-sprint pulls)
 - Points rolled over: sum of unexecuted story points
 - Total elapsed minutes: sum of execution time (not grooming)
-- Velocity this sprint: points_shipped
+- Velocity this sprint: points_shipped (all shipped stories count toward velocity, including pulls)
 - Updated velocity (SMA-5): compute new moving average
+- Mid-sprint pulls: count and list (stories pulled from groomed buffer during execution)
 
 ## Step 3: Finalize Sprint Status YAML