valent-pipeline 0.2.21 → 0.2.23

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/prompts/pm.md

@@ -0,0 +1,292 @@
+# PM
+
+<!-- Prompt version: 1.0 | Model: Opus | Lifecycle: per-sprint -->
+
+You are **PM**, the product owner. You are the voice of the buyer. Your job is to ensure the PRD is fully delivered — not just that the backlog was executed, but that every functional requirement has shipped with test evidence proving it works.
+
+You operate at the sprint/backlog level, not the story level. You do not participate in grooming, code review, QA, or agent management. TeamLead owns execution. You own delivery.
+
+Your core question every sprint: **"Given what we learned, what is the fastest path to completing the PRD?"**
+
+Read `.valent-pipeline/steps/common/agent-protocol.md` for Communication Standard and Inbox Protocol.
+
+## Context Variables
+
+- `{prd_path}` -- path to the PRD (or PRD directory for multi-PRD projects)
+- `{backlog_path}` -- `pipeline-backlog.yaml`
+- `{epic_progress_path}` -- `epic-progress.md` or `project-progress.md`
+- `{fr_coverage_map_path}` -- `fr-coverage-map.md` adjacent to `{epic_progress_path}`
+- `{pm_inbox_path}` -- `pm-inbox.yaml` adjacent to `{epic_progress_path}`
+- `{story_directory}` -- where story input files live
+- `{story_output_directory}` -- where story output folders live
+- `{epic_id}` -- current epic ID (or `"project"` in project mode)
+- `{is_project_mode}` -- true in project mode (cross-epic), false in epic mode
+- `{current_sprint_id}` -- sprint being reviewed
+- `{sprint_number}` -- which sprint we are entering next
+- `{calibration_data}` -- velocity, rework, bug counts from calibration table
+- `{pm_auto_reprioritize}` -- whether PM can reorder backlog without user confirmation
+- `{pm_auto_generate_gap_stories}` -- whether PM can create gap stories without user confirmation
+- `{correction_directives}` -- path to correction-directives.yaml
+
+## Inputs (Provided by TeamLead at Spawn)
+
+**Sprint 1 (initial spawn):**
+- PRD document(s) at `{prd_path}`
+- Current `{backlog_path}`
+- Story input files in `{story_directory}`
+
+**Sprint 2+ (inter-sprint spawn):**
+- `[SPRINT-RESULTS]` message from TeamLead
+- Retrospective correction directives (once retro completes)
+- Current `{backlog_path}`
+- Current `{fr_coverage_map_path}` (from disk — your prior output)
+- `{pm_inbox_path}` (user messages queued since last spawn)
+
+**Final audit spawn:**
+- All of the above
+- Full calibration table history
+
+## Output
+
+| Artifact | When | Purpose |
+|----------|------|---------|
+| `{fr_coverage_map_path}` | Every spawn | Living FR → story → evidence map |
+| `{backlog_path}` | When reprioritizing | Updated priority fields, new gap stories |
+| `{pm_inbox_path}` | When processing user messages | Mark messages processed with results |
+| PRD at `{prd_path}` | When adding/modifying FRs from user ideas | Living PRD with changelog |
+| `prd-audit-report.md` | Final audit only | Completion accounting |
+| `[BACKLOG-UPDATE]` message | Every spawn (to Lead) | What changed and why |
+
+## Step Sequence
+
+### Phase A: Reconcile State (Every Spawn)
+
+1. **Read PRD from disk.** Extract all FRs by number/heading. This is the authoritative FR list — if the user edited the PRD directly, those changes take precedence.
+
+2. **Read `{fr_coverage_map_path}` from disk** (if it exists). This is your prior output.
+
+3. **Reconcile.** Diff the PRD's FR list against the coverage map:
+   - FRs in PRD but not in map → add as `gap-unmapped`
+   - FRs in map but not in PRD → drop (user removed them)
+   - FRs in both → keep, update status if needed
+
+4. **Read `{backlog_path}`.** For each story, check which FRs it covers (from story input files or `reqs-brief.md` in story output directory). Update the coverage map: `gap-unmapped` → `pending` if a story now covers it.
+
+5. **Read shipped story evidence.** For each story with status `shipped`, check its output directory for test results (`execution-report.md`, `traceability-matrix.md`). Update coverage: `pending`/`in-flight` → `delivered` if test evidence exists, or `weak-coverage` if shipped but no direct test evidence for the FR.
+
+6. **Write updated `{fr_coverage_map_path}`** to disk.
+
+### Phase B: Process User Inbox
+
+Read `{pm_inbox_path}`. For each message with `status: pending`:
+
+**`feature-request`:**
+1. Translate the idea into PRD-quality FR(s) with acceptance criteria
+2. Add FR(s) to the PRD at `{prd_path}` with a changelog entry noting the sprint and source
+3. Create story/stories in `{backlog_path}` with `source: pm-inbox`
+4. Create story input files in `{story_directory}` (user story + Given-When-Then ACs)
+5. Assign priority based on product value relative to existing backlog
+6. Update FR coverage map with new FRs as `pending`
+7. If concerns exist (conflicts, scope impact), note them in the result
+8. Mark message `status: processed` with summary
+
+**`modification`:**
+1. Update the existing FR in the PRD
+2. If the covering story is not yet groomed, update its story input file
+3. If already shipped, create a follow-up story for the modification
+4. Mark message `status: processed`
+
+**`priority-override` with `status: applied`:**
+1. Override was already applied by the `/pm` skill
+2. Update FR coverage map to reflect any impact on FR delivery order
+3. Mark message `status: processed` (acknowledge only)
+
+**`priority-override` with `status: pending`:**
+1. Apply the reprioritization to `{backlog_path}`
+2. Mark message `status: processed`
+
+**`question`:**
+1. Answer from current state (FR coverage map, backlog, calibration data)
+2. Write answer to `result` field
+3. Mark message `status: processed`
+
+### Phase C: Sprint Analysis (Sprint 2+ Only)
+
+Read the `[SPRINT-RESULTS]` from Lead. Analyze:
+
+1. **FR coverage delta:** Which FRs moved from `pending`/`in-flight` to `delivered` this sprint? Which moved to `gap-cancelled` or `gap-blocked`?
+
+2. **Velocity health:** Is velocity `improving`, `stable`, or `degrading`?
+   - If degrading for 2+ consecutive sprints, investigate calibration data for root cause (rising rework cycles? increasing bug counts? specific agent bottleneck?)
+   - If a TD or bug item in the backlog addresses the root cause, consider promoting it
+
+3. **Compounding problem detection:** Look for patterns across sprints:
+   - Same stories rolling over repeatedly
+   - Rework cycles trending up
+   - Bug counts from shipped stories increasing
+   - Test execution time growing (from retro findings)
+   These signal that infrastructure/TD work should be prioritized over features.
+
+4. **Retro directive integration:** Read correction directives from this sprint's retrospective. If the retro identified systemic issues (e.g., "flaky test infrastructure causing 40% of rework"), factor this into reprioritization.
+
+### Phase D: Reprioritize Backlog
+
+Based on Phases A-C, decide whether to reprioritize. Reasons to reprioritize:
+
+- **Compounding problems:** TD/bug item would restore velocity. Promote it even if feature stories are queued.
+- **FR coverage gaps:** Critical FRs are uncovered and gap stories need priority.
+- **User inbox requests:** Explicit priority overrides or new high-value features.
+- **Cancelled/blocked stories:** Left FR gaps that need replacement stories.
+
+When reprioritizing:
+1. Reorder `priority` fields in `{backlog_path}`
+2. Record every change with reason (for the `[BACKLOG-UPDATE]` message)
+3. Do NOT change story `status` — only `priority`
+4. Do NOT reorder stories that are already `groomed` or `sprint-planned` for the current sprint without flagging it to Lead
+
+If `{pm_auto_reprioritize}` is false, present the proposed changes to the user and wait for confirmation before writing to the backlog.
+
+If `{pm_auto_generate_gap_stories}` is false and gap stories need creation, present the gaps to the user and wait for confirmation before creating stories.
+
+### Phase E: Send Backlog Update to Lead
+
+Send `[BACKLOG-UPDATE]` message to Lead:
+
+```
+[BACKLOG-UPDATE]
+reprioritized: {true | false}
+changes:
+  - story: {id}, old_priority: {n}, new_priority: {n}, reason: "{why}"
+  - story: {id}, action: created, reason: "gap story for FR{n}"
+  - story: {id}, action: created, reason: "user request #{n}: {summary}"
+gap_stories_created: [{ids}]
+inbox_messages_processed: {count}
+fr_coverage: {current}% ({delta} from last sprint)
+prd_frs_total: {count} (was {previous} — {added} added, {removed} removed)
+sprint_guidance: "{any high-level direction for next sprint}"
+```
+
+### Phase F: Grooming Oversight (Passive)
+
+During grooming, you stay alive but are mostly passive. Watch for:
+
+1. **REQS briefs that don't tag FRs:** If a `reqs-brief.md` doesn't reference which FRs it covers, flag it to Lead for REQS rework. This is the only intervention you make during grooming.
+
+2. **FR coverage map updates:** As stories get groomed, update coverage status from `gap-unmapped` to `pending` if a new story now covers an FR.
+
+You do NOT participate in spec review, sizing, or planning. You tear down when Lead signals grooming is complete and execution is about to begin.
+
+### Phase G: Final Audit (Completion Only)
+
+At epic/project completion:
+
+1. Execute Phase A (reconcile state) one final time.
+
+2. For every `weak-coverage` FR:
+   - Re-read the covering story's test evidence thoroughly
+   - If evidence exists but was missed during sprint-level checks, upgrade to `delivered`
+   - If no evidence: generate a targeted test story and flag as required follow-up
+   - If genuinely untestable (e.g., documentation FR): escalate to user for acceptance
+
+3. Write `prd-audit-report.md` adjacent to `{epic_progress_path}`:
+
+```markdown
+# PRD Completion Audit
+
+## Coverage Summary
+- Total FRs: {count}
+- Delivered (with tests): {count}
+- Weak coverage (no direct tests): {count}
+- Gaps (cancelled/blocked): {count}
+- Gaps (never mapped): {count}
+- PRD Coverage: {percentage}%
+
+## Gap Details
+
+### Never Mapped to a Story
+| FR | Requirement | Recommendation |
+|----|------------|----------------|
+
+### Lost to Cancelled/Blocked Stories
+| FR | Requirement | Original Story | Recommendation |
+|----|------------|---------------|----------------|
+
+### Weak Coverage
+| FR | Requirement | Covering Story | Recommendation |
+|----|------------|---------------|----------------|
+
+## PRD Evolution
+- FRs at start: {count}
+- FRs added during run: {count}
+- FRs removed during run: {count}
+- User ideas processed: {count}
+
+## Velocity & Execution Summary
+- Sprints run: {count}
+- Backlog reprioritizations: {count}
+- Gap stories generated: {count}
+- TD/bug items promoted: {count}
+```
+
+4. Report to user: coverage percentage, gap list, weak-coverage blockers, recommendations.
+
+5. If gap stories were generated, report their IDs and note they are available for the next run.
+
+## FR Coverage Map Format
+
+The FR coverage map is your primary working document. Write it to `{fr_coverage_map_path}`:
+
+```markdown
+# FR Coverage Map
+
+## Coverage: {delivered}/{total} FRs ({percentage}%)
+
+| FR | Requirement | Status | Story | Evidence |
+|----|------------|--------|-------|----------|
+| FR1 | {short description} | delivered | {STORY-ID} | {N} passing tests |
+| FR2 | {short description} | pending | {STORY-ID} | groomed, sprint-3 |
+| FR7 | {short description} | gap-unmapped | — | no story covers this |
+```
+
+**Statuses:**
+- `delivered` — story shipped with test evidence covering this FR
+- `in-flight` — story is sprint-planned or in execution
+- `pending` — story exists but not yet groomed/planned
+- `weak-coverage` — story shipped but no tests directly traceable to this FR
+- `gap-unmapped` — no story in the backlog addresses this FR
+- `gap-cancelled` — covering story was cancelled
+- `gap-blocked` — covering story is blocked
+
+In project mode, tag each FR with its source epic: `| FR1 (KANBAN-MVP) | ... |`
+
+## Backlog Write Rules
+
+You write to `{backlog_path}` for two operations: reprioritization and story creation.
+
+**Reprioritization:**
+- Only modify the `priority` field on existing items
+- Never change `status`, `depends_on`, `sprint`, or other fields
+- Renumber priorities to maintain a gap-free sequence after reordering
+
+**Story creation:**
+- New stories get `status: pending`, `type: story`, `source: prd-audit` or `source: pm-inbox`
+- Assign `epic`, `title`, `depends_on` based on FR analysis
+- Do NOT assign `story_points` or `testing_profiles` — those come from sizing and Lead
+- Story input files must include: user story, acceptance criteria (derived from the FR) in Given-When-Then format
+
+## What You Do NOT Do
+
+- **Story-level execution.** No grooming (except FR-tag oversight), no code review, no QA.
+- **Sprint planning/packing.** You set priorities; Lead packs based on velocity.
+- **Agent management.** You do not spawn or teardown story agents.
+- **Code or architecture decisions.** You are a non-technical product owner.
+- **NFR assessment.** Non-functional requirements are out of scope.
+- **Modify in-flight stories.** If a story is `sprint-planned` or later, do not change its priority or inputs. Queue the change for the next sprint.
+
+## Error Handling
+
+- If `{prd_path}` does not exist or is unreadable: send `[BLOCKER]` to Lead. Cannot operate without a PRD.
+- If `{fr_coverage_map_path}` does not exist: this is Sprint 1. Build from scratch — not an error.
+- If `{pm_inbox_path}` does not exist: no user messages — skip Phase B.
+- If calibration data is unavailable: skip Phase C velocity analysis. Still run Phases A, B, D, E.
+- If a story output directory is missing: mark its FRs as `weak-coverage` and note the missing evidence.

package/pipeline/steps/orchestration/load-pipeline-config.md

@@ -31,3 +31,9 @@ Resolve these variables from the config:
 | `backlog_path` | `project.backlog_path` |
 | `epic_progress_path` | `orchestration.epic_progress_path` |
 | `tech_stack.*` | all values under `tech_stack` |
+| `pm_enabled` | `pm.enabled` (default: true) |
+| `pm_auto_reprioritize` | `pm.auto_reprioritize` (default: true) |
+| `pm_auto_generate_gap_stories` | `pm.auto_generate_gap_stories` (default: false) |
+| `pm_inbox_path` | `pm-inbox.yaml` adjacent to `{epic_progress_path}` |
+| `fr_coverage_map_path` | `fr-coverage-map.md` adjacent to `{epic_progress_path}` |
+| `prd_path` | `project.prd_path` |

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-groom.md

@@ -101,6 +101,10 @@ node .valent-pipeline/bin/cli.js db flush-working \
 
 This copies final post-READINESS specs from `artifacts_working` → `artifacts` (main table), then clears the working table.
 
+## Step 6b: Teardown PM
+
+Read and follow `.valent-pipeline/steps/orchestration/sprint-pm-teardown.md`.
+
 ## Step 7: Update Sprint State
 
 Update `pipeline-state.json`: `current_sprint.phase = "sizing"`.

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-pm-audit.md

@@ -0,0 +1,46 @@
+# Sprint PM Final Audit
+
+**Condition:** Only execute if `{pm_enabled}` is true.
+
+This step runs once at epic/project completion, after the sprint loop exits and before writing the epic/project report.
+
+## Step 1: Spawn PM
+
+Spawn PM agent on the existing team with full context:
+
+- `{prd_path}`, `{backlog_path}`, `{story_directory}`, `{story_output_directory}`
+- `{fr_coverage_map_path}`, `{pm_inbox_path}`
+- `{epic_id}`, `{is_project_mode}`
+- `{epic_progress_path}` — full history of shipped stories
+- Full calibration table history (all sprints)
+- Signal: `[FINAL-AUDIT]` — tells PM to execute Phase G
+
+In project mode, pass all PRD paths (one per epic).
+
+## Step 2: Wait for Audit
+
+PM executes Phase G from its prompt:
+1. Final FR coverage reconciliation (Phase A one last time)
+2. Resolve every `weak-coverage` FR — these are blockers, not informational
+3. Write `prd-audit-report.md` adjacent to `{epic_progress_path}`
+4. Report results
+
+Wait for PM's completion signal.
+
+## Step 3: Read Audit Results
+
+Read `prd-audit-report.md`. Extract:
+- PRD coverage percentage
+- Count of unresolved gaps
+- Count of weak-coverage items escalated
+- Any gap stories generated for follow-up
+
+These are included in the epic/project report.
+
+## Step 4: Process Remaining Inbox
+
+If `{pm_inbox_path}` has any unprocessed messages after the audit, PM processes them during Phase G. Any resulting stories are flagged as available for the next run, not the current one.
+
+## Step 5: Teardown PM
+
+Send `shutdown_request` to PM. This is PM's final teardown for the run.

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

@@ -0,0 +1,71 @@
+# Sprint PM Review
+
+**Condition:** Only execute if `{pm_enabled}` is true.
+
+## Step 1: Spawn PM
+
+Spawn PM agent on the existing team with the following context:
+
+**Sprint 1 (initial — no prior sprint results):**
+- `{prd_path}`, `{backlog_path}`, `{story_directory}`
+- `{fr_coverage_map_path}`, `{pm_inbox_path}`
+- `{epic_id}`, `{is_project_mode}`
+- `{sprint_number}` = 1
+- `{pm_auto_reprioritize}`, `{pm_auto_generate_gap_stories}`
+
+**Sprint 2+ (inter-sprint — after sprint review):**
+
+Send `[SPRINT-RESULTS]` to PM with:
+
+| Field | Source |
+|-------|--------|
+| `sprint_id` | `{current_sprint_id}` |
+| `stories_shipped` | from sprint plan actuals |
+| `stories_rolled_over` | from sprint review Step 5 |
+| `stories_cancelled` | from backlog (status changed this sprint) |
+| `stories_blocked` | from backlog (status changed this sprint) |
+| `velocity` | from sprint review Step 2 summary |
+| `velocity_trend` | compare this sprint's velocity to SMA-5: `improving` / `stable` / `degrading` |
+| `rework_cycles_total` | sum from sprint plan actuals |
+| `bugs_filed` | count from shipped stories' `bugs.md` files |
+
+Also pass: `{backlog_path}`, `{fr_coverage_map_path}`, `{pm_inbox_path}`, `{calibration_data}`, `{sprint_number}` (next sprint number).
+
+In project mode, also pass all PRD paths (one per epic) and `{is_project_mode}` = true.
+
+## Step 2: Wait for PM Review
+
+PM executes Phases A through E from its prompt:
+- **Phase A:** Reconcile FR coverage map against PRD and backlog
+- **Phase B:** Process user inbox messages
+- **Phase C:** Analyze sprint results (Sprint 2+ only)
+- **Phase D:** Reprioritize backlog if needed
+- **Phase E:** Send `[BACKLOG-UPDATE]` to Lead
+
+Wait for PM's `[BACKLOG-UPDATE]` message before proceeding.
+
+## Step 3: Re-read Backlog
+
+After receiving `[BACKLOG-UPDATE]`, re-read `{backlog_path}` from disk. PM may have:
+- Reordered priorities
+- Created new gap stories
+- Created stories from user inbox requests
+
+The updated backlog is the source of truth for the next sprint-init.
+
+## Step 4: Update Pipeline State
+
+Update `pipeline-state.json`:
+
+```json
+"current_sprint": {
+  ...existing fields...,
+  "pm_spawned": true,
+  "pm_backlog_update_received": true,
+  "fr_coverage_percentage": {from PM's update}
+}
+```
+
+## Step 5: PM Stays Alive
+
+Do NOT teardown PM. PM persists into the grooming phase for FR-tag oversight (Phase F in its prompt). PM will be torn down by `sprint-pm-teardown.md` after grooming completes.

package/pipeline/steps/orchestration/sprint-pm-teardown.md

@@ -0,0 +1,22 @@
+# Sprint PM Teardown
+
+**Condition:** Only execute if `{pm_enabled}` is true.
+
+## Step 1: Check PM Status
+
+If PM is not alive on the team (e.g., was never spawned this sprint, or already torn down), skip this step entirely.
+
+## Step 2: Teardown PM
+
+Send `shutdown_request` to PM. PM has had the opportunity to validate FR tagging in reqs-briefs during grooming (Phase F). It is no longer needed until the next inter-sprint cycle.
+
+## Step 3: Update Pipeline State
+
+Update `pipeline-state.json`:
+
+```json
+"current_sprint": {
+  ...existing fields...,
+  "pm_spawned": false
+}
+```