valent-pipeline 0.2.21 → 0.2.23

package/pipeline/docs/pm-agent-design.md

@@ -0,0 +1,880 @@
+# Design: Product Manager (PM) Agent
+
+**Status:** Proposal  
+**Scope:** Both epic and project mode  
+**Model:** Opus  
+**Lifecycle:** Per-sprint (spawns with retrospective, lives through grooming, tears down before execution)
+
+## Problem
+
+Three related gaps in the current pipeline:
+
+1. **PRD completion is unverified.** The epics-and-stories breakdown happens once, early, and may miss requirements. Stories get cancelled or blocked during execution. Nobody checks whether the shipped work actually delivers the full PRD. The existing pre-implementation readiness check validates that stories *claim* to cover FRs — it doesn't verify that shipped code delivers them.
+
+2. **Backlog priority is static across sprints.** Priority is set once during `valent-setup-backlog` and never revisited. When sprints reveal compounding problems (flaky tests degrading velocity, tech debt items creating cascading failures), the pipeline correctly logs them but nobody reprioritizes. TeamLead executes the backlog as ordered — that's the right behavior for an execution lead, but it means TD and bug items sit unprioritized while feature stories keep shipping into a degrading codebase.
+
+3. **The PRD is a frozen input, not a living document.** New ideas, scope changes, and user feedback discovered during the run have no structured path into the pipeline. The PRD is written once before implementation and never updated. There's no way for the user to say "I want to add X" mid-run and have it flow through requirements → stories → backlog in a controlled way.
+
+All three problems share a root cause: nobody owns the *product outcome* across sprints. TeamLead owns execution. PM owns delivery.
+
+## Proposed Solution
+
+A new long-lived agent (`PM`) that operates as the product owner. PM's core question is: **"given what we learned this sprint, what's the fastest path to completing the PRD?"**
+
+PM is a peer to TeamLead. It has equivalent authority — it can reprioritize the backlog, but must coordinate with TeamLead because infrastructure/TD items sometimes need to take precedence over features (and vice versa). The relationship is collaborative, not hierarchical.
+
+### Responsibilities
+
+#### 1. PRD Coverage Tracking (Living FR Map)
+
+PM maintains `fr-coverage-map.md` in the epic/project output directory. This is a living document, updated after every sprint, that maps every PRD functional requirement to its delivery status.
+
+```markdown
+# FR Coverage Map
+
+## Coverage: 14/18 FRs (78%)
+
+| FR | Requirement | Status | Story | Evidence |
+|----|------------|--------|-------|----------|
+| FR1 | User can create board | delivered | KANBAN-003 | 4 passing tests |
+| FR2 | User can add columns | delivered | KANBAN-004 | 3 passing tests |
+| FR3 | Drag-and-drop cards | in-flight | KANBAN-012 | sprint-3 planned |
+| FR7 | Export to CSV | gap-unmapped | — | no story covers this |
+| FR9 | Real-time sync | gap-cancelled | KANBAN-005 | story cancelled sprint-2 |
+| FR11 | Audit logging | weak-coverage | KANBAN-008 | shipped, no direct tests |
+```
+
+**Statuses:**
+- `delivered` — story shipped with test evidence covering this FR
+- `in-flight` — story is planned or in current sprint
+- `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
+
+#### 2. Inter-Sprint Backlog Reprioritization
+
+After each sprint review + retrospective, PM reviews:
+
+- **Sprint outcomes:** what shipped, what didn't, what took longer than expected
+- **Velocity trend:** is velocity stable, improving, or degrading?
+- **Calibration data:** rework cycles, actual-vs-estimated ratios, bug counts
+- **Retrospective findings:** correction directives, recurring patterns
+- **FR coverage map:** which FRs are still uncovered, which are at risk
+
+PM then reprioritizes the backlog for the next sprint. This means reordering `priority` fields in `pipeline-backlog.yaml`. Examples:
+
+- Flaky tests caused 3 stories to take 2x longer → promote the TD item that fixes the test infrastructure
+- A cancelled story left FR7 uncovered and FR7 is a core requirement → create or promote a replacement story
+- Velocity is trending down and the retro identified test debt as the cause → deprioritize lower-value features, promote TD fixes
+- An FR marked `weak-coverage` has no direct tests → inject a targeted test story or bump the covering story's follow-up
+
+#### 3. Gap Story Generation
+
+When PM identifies FRs with no story coverage (`gap-unmapped`) or lost coverage (`gap-cancelled`, `gap-blocked`):
+
+1. Create new stories in `pipeline-backlog.yaml` with:
+   - `type: story` (or `type: bug` if it's a regression)
+   - `status: pending`
+   - `epic: {relevant_epic_id}`
+   - `source: prd-audit`
+   - `title: "Implement FR{N}: {short description}"`
+   - Priority assigned relative to other pending work (PM's judgment call)
+2. Create corresponding story input files in `{story_directory}`
+
+#### 4. Living PRD & User Idea Intake
+
+The PRD is no longer a frozen input document. PM owns it as a living artifact and is the single entry point for product changes.
+
+**User → PM message queue:**
+
+The user can queue messages for PM at any time during the run — including during sprint execution when PM is not alive. Messages are written to `pm-inbox.yaml` in the epic/project output directory:
+
+```yaml
+messages:
+  - id: 1
+    timestamp: 2026-04-06T14:30:00Z
+    from: user
+    content: "I want to add keyboard shortcuts for all board actions"
+    status: pending
+
+  - id: 2
+    timestamp: 2026-04-06T15:45:00Z
+    from: user
+    content: "CSV export should also support JSON format"
+    status: pending
+```
+
+When PM spawns at the start of each inter-sprint cycle, it reads `pm-inbox.yaml` and processes pending messages:
+
+1. **Flesh out the idea** — PM translates the user's informal request into PRD-quality requirement language (FR number, acceptance criteria, scope boundaries)
+2. **Update the PRD** — PM adds the new requirement(s) to the PRD document, clearly marked as additions with the sprint they were introduced
+3. **Create stories** — PM generates backlog stories for the new FRs, with appropriate dependency chains
+4. **Prioritize** — PM slots the new stories into the backlog at the right priority, considering the existing roadmap and FR coverage gaps
+5. **Update FR coverage map** — new FRs start as `pending` (story exists) or `gap-unmapped` (if the idea needs more breakdown first)
+6. **Mark processed** — update message status to `processed` with a summary of what was created
+
+```yaml
+  - id: 1
+    timestamp: 2026-04-06T14:30:00Z
+    from: user
+    content: "I want to add keyboard shortcuts for all board actions"
+    status: processed
+    processed_sprint: sprint-3
+    result: "Added FR19-FR21 to PRD. Created KANBAN-018 (priority 12). Depends on KANBAN-003."
+```
+
+This means the user never needs to manually edit the PRD, create stories, or figure out where new work fits in the backlog. They just describe what they want, and PM handles the formalization.
+
+**PRD change tracking:**
+
+PM adds a changelog section to the PRD when it makes modifications:
+
+```markdown
+## PRD Changelog
+| Sprint | Change | FRs Added/Modified | Source |
+|--------|--------|-------------------|--------|
+| sprint-3 | Added keyboard shortcuts | FR19, FR20, FR21 | user request #1 |
+| sprint-3 | Expanded export formats | FR7 modified | user request #2 |
+```
+
+#### 5. PRD Completion Audit (Epic/Project Completion)
+
+At the end of the run, PM produces `prd-audit-report.md` — the final accounting of PRD delivery:
+
+```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 |
+|----|------------|---------------|----------------|
+
+## Velocity & Execution Summary
+- Sprints run: {count}
+- Backlog reprioritizations: {count}
+- Gap stories generated: {count}
+- TD/bug items promoted: {count}
+```
+
+### Touchpoints in the Sprint Loop
+
+PM activates at three points in the existing orchestration flow:
+
+#### Before Sprint 1 (Initial Review)
+
+After `valent-setup-backlog` creates the initial backlog but before the first `sprint-init`:
+
+1. PM reads the PRD (`{prd_path}`) and extracts all FRs
+2. PM reads the backlog and maps each story to the FRs it covers (using story input files and `reqs-brief.md` if grooming has occurred)
+3. PM builds the initial `fr-coverage-map.md`
+4. PM validates that the backlog's priority ordering reflects product value — the vertical-slice ordering from setup is a good starting point, but PM may adjust based on FR criticality
+5. PM flags any FRs with no story coverage (gap-unmapped) and generates gap stories if needed
+
+#### Between Sprints (Post-Review Reprioritization)
+
+PM spawns alongside Retrospective after sprint review. The flow becomes:
+
+```
+sprint-review → [PM SPAWN + retrospective] → PM REVIEW → sprint-init → sprint-groom (PM alive) → [PM TEARDOWN] → sprint-execute
+```
+
+1. TeamLead spawns PM with sprint results: shipped stories, rolled-over stories, cancelled/blocked stories, velocity, calibration summary
+2. PM and Retrospective run concurrently — PM reads sprint data while retro analyzes patterns
+3. PM reads retro correction directives once retrospective completes
+4. PM updates `fr-coverage-map.md` with new delivery data
+5. PM reads calibration data to assess execution health (rework trends, velocity trend, bug counts)
+6. PM reprioritizes `pipeline-backlog.yaml` if needed
+7. PM generates gap stories for any newly uncovered FRs
+8. PM sends `[BACKLOG-UPDATE]` to TeamLead: what changed and why
+9. TeamLead proceeds to sprint-init, sprint-groom — PM stays alive during grooming to validate FR tagging in reqs-briefs as REQS produces them
+10. PM tears down before sprint execution begins
+
+#### At Epic/Project Completion (Final Audit)
+
+After the sprint loop exits, before writing the epic/project report:
+
+1. PM spawns one final time
+2. PM performs final FR coverage reconciliation
+3. PM assesses all `weak-coverage` FRs — these are **blockers**, not informational. PM represents the buyer: "shipped but unproven" is not acceptable. PM must either:
+   - Confirm test evidence exists (downgrade was wrong, re-check)
+   - Generate a targeted test story and flag it as required follow-up work
+   - Escalate to user if the FR is genuinely untestable
+4. PM writes `prd-audit-report.md`
+5. PM reports to user: PRD coverage percentage, gap details, weak-coverage blockers, recommendations
+6. PM tears down
+
+### Communication Protocol
+
+PM and TeamLead communicate via structured messages at defined handoff points. PM does NOT participate in story-level execution — it operates at the sprint/backlog level.
+
+**TeamLead → PM (after sprint review):**
+```
+[SPRINT-RESULTS]
+sprint_id: {id}
+stories_shipped: [{ids}]
+stories_rolled_over: [{ids}]  
+stories_cancelled: [{ids}]
+stories_blocked: [{ids}]
+velocity: {points}
+velocity_trend: {improving | stable | degrading}
+rework_cycles_total: {count}
+bugs_filed: {count}
+retro_correction_directives: [{summary}]
+```
+
+**PM → TeamLead (before next sprint):**
+```
+[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}"
+gap_stories_created: [{ids}]
+fr_coverage: {percentage}%
+sprint_guidance: "{any high-level direction for next sprint}"
+```
+
+### Agent Manifest Entry
+
+```yaml
+agents:
+  pm:
+    name: PM
+    model: opus
+    lifecycle: per-sprint
+    role: "Product owner — tracks PRD completion, reprioritizes backlog between sprints, generates gap stories"
+    prompt_template: .valent-pipeline/prompts/pm.md
+    reads_from: [prd, pipeline-backlog.yaml, epic-progress.md, sprint-plan, calibration-table, fr-coverage-map.md, story-reqs-briefs, pm-inbox.yaml]
+    writes_to: [fr-coverage-map.md, prd-audit-report.md, pipeline-backlog.yaml, prd, pm-inbox.yaml]
+```
+
+### Configuration
+
+Add to `pipeline-config.yaml`:
+
+```yaml
+pm:
+  enabled: true                    # enable PM agent (default: true)
+  auto_reprioritize: true          # PM can reorder backlog without user confirmation (default: true)
+  auto_generate_gap_stories: false # auto-create gap stories without user confirmation (default: false)
+  prd_path: "{project.prd_path}"   # PRD location (already exists in project config)
+```
+
+### What PM Does NOT Do
+
+- **Story-level execution:** PM does not participate in grooming, sizing, code review, or QA. That's TeamLead and the story agents.
+- **Sprint planning/packing:** PM sets priorities; TeamLead packs the sprint based on velocity and those priorities.
+- **Agent management:** PM does not spawn or tear down story agents. That's TeamLead.
+- **Code decisions:** PM is a non-technical product owner. It reasons about requirements, priorities, and coverage — not implementation approach.
+- **Technical debt assessment:** PM can promote TD items based on their impact on velocity, but evaluating *what* the TD fix should be is not PM's role. A future technical owner agent may handle that.
+
+### Lifecycle
+
+PM is **not** a fully persistent agent. It spins up and tears down each sprint to avoid wasting context sitting idle during story execution.
+
+**Sprint 1 (initial):**
+1. **Spawn** after backlog is loaded, before sprint-init
+2. **Active:** Build initial FR coverage map, validate backlog priorities, flag unmapped FRs, generate gap stories
+3. **Stay alive** through sprint grooming (can validate FR coverage as stories get specced by REQS)
+4. **Teardown** before sprint execution begins
+
+**Sprint 2+ (inter-sprint):**
+1. **Spawn** alongside Retrospective agent after sprint review
+2. **Active:** Receive sprint results, update FR coverage map, read calibration/retro data, reprioritize backlog, generate gap stories
+3. **Stay alive** through grooming (same reason — validates FR tagging in reqs-briefs)
+4. **Teardown** before sprint execution begins
+
+**Final audit:**
+1. **Spawn** after the sprint loop exits
+2. **Active:** Final FR coverage reconciliation, write `prd-audit-report.md`, assess weak-coverage items
+3. **Teardown** after reporting to user
+
+This lifecycle means PM's context is fresh each sprint — it reads state from disk (FR coverage map, backlog, calibration table) rather than accumulating story-level noise. Its working memory resets, but its working documents persist on disk.
+
+### Context Pressure
+
+PM's context stays lean because:
+- It lives only during review/grooming phases, not execution
+- It doesn't read agent output files (code diffs, critic reviews, etc.)
+- It reads structured summaries: sprint results, calibration data, backlog YAML, FR coverage map
+- The FR coverage map is its primary working document — a compact table persisted to disk
+- Fresh spawn each sprint means no context accumulation across sprints
+
+### Dependencies
+
+- PRD must use numbered/identifiable FR format (standard PRD template already requires this)
+- REQS agent must tag FRs in `reqs-brief.md` during grooming (already does this)
+- Calibration table must have per-sprint data (already recorded during sprint review)
+- TeamLead must send structured sprint results to PM (new handoff)
+
+### PRD Handling by Mode
+
+- **Epic mode:** Single PRD (from `{prd_path}`). One FR coverage map scoped to that epic's requirements.
+- **Project mode:** Cross-references ALL PRDs across all epics. PM maintains one unified FR coverage map that spans the full project. Each FR is tagged with its source epic/PRD so gaps can be routed to the right epic for story generation.
+
+### Weak Coverage as a Blocker
+
+`weak-coverage` FRs **block** epic/project completion. PM represents the buyer — "we shipped it but can't prove it works" is not a deliverable. At the final audit, PM must resolve every `weak-coverage` item before the run is considered complete (generate test stories, verify evidence was missed, or escalate to user).
+
+### Resolved Design Decisions
+
+1. **Per-sprint lifecycle (not persistent):** PM spins up with retrospective, stays alive through grooming, tears down before execution. Fresh context each sprint, state persisted to disk.
+2. **Cross-PRD in project mode:** PM reads all PRDs, maintains unified FR map. Single PRD in epic mode.
+3. **Weak-coverage blocks completion:** PM treats unproven FRs as gaps that need resolution, not informational notes.
+4. **Living PRD, not frozen input:** PM owns the PRD as a living document. New scope flows through PM via a message queue — PM formalizes ideas into PRD requirements, creates stories, and prioritizes them. Scope creep is not a concern because PM *is* the controlled scope change mechanism.
+5. **User override:** If the user disagrees with PM's reprioritization, PM defers to the user and records the override reason in `pm-inbox.yaml` for future context. This lets PM learn the user's priorities over time and avoid repeating overridden judgment calls.
+6. **NFR tracking deferred:** NFRs are not tracked by PM. A future technical owner agent may handle non-functional requirements. PM focuses on functional requirements that represent product value to the buyer.
+
+### Resolved Design Decisions (continued)
+
+7. **Inbox delivery via `/pm` skill:** A `/pm` skill appends user messages to `pm-inbox.yaml`. This is the cleanest UX — the user types `/pm I want keyboard shortcuts` and the message is queued for PM's next spawn.
+8. **PRD reconciliation, not exclusive ownership:** PM re-reads the PRD from disk every time it spawns and reconciles its FR coverage map against what it finds. If the user manually removed FRs, PM drops them from tracking. If new FRs appeared, PM picks them up. The on-disk PRD is always authoritative. PM is the *preferred* channel for PRD changes, but the user can edit directly and PM adapts.
+9. **PM can push back on ideas:** When processing inbox messages, PM can flag concerns — "this conflicts with FR3," "this duplicates existing coverage in KANBAN-008," "this is a significant scope expansion that will add ~2 sprints." PM formalizes the idea regardless but includes its assessment in the processed message and in the PRD changelog. The user can override by queuing a follow-up message or adjusting priority directly.
+
+---
+
+## Implementation Details
+
+### A. `/pm` Skill Specification
+
+**File:** `valent-pipeline/skills/valent-pm/SKILL.md`
+
+```yaml
+---
+name: valent-pm
+description: 'Queue a message for the PM agent. Use when the user says "/pm" followed by a product idea, priority change, or question for the product manager.'
+argument-hint: '<message>'
+---
+```
+
+#### Purpose
+
+Allows the user to communicate with PM at any time — including during sprint execution when PM is not alive. Messages are persisted to `pm-inbox.yaml` and processed when PM next spawns.
+
+#### Execution Steps
+
+##### Step 1: Load Pipeline Config
+
+Read `.valent-pipeline/pipeline-config.yaml` to resolve `{pm_inbox_path}` (defaults to `pm-inbox.yaml` adjacent to `{epic_progress_path}`).
+
+If `pm.enabled` is `false`, respond: "PM agent is disabled. Enable it in pipeline-config.yaml under `pm.enabled`."
+
+##### Step 2: Parse the User Message
+
+The argument is free-form text. The user might say:
+
+- `/pm I want to add keyboard shortcuts for all board actions`
+- `/pm CSV export should also support JSON format`
+- `/pm Reprioritize KANBAN-015 above KANBAN-010, the sync feature is more critical than filtering`
+- `/pm What's the current PRD coverage?`
+
+Classify the message type:
+
+| Type | Description | Example |
+|------|------------|---------|
+| `feature-request` | New functionality or scope expansion | "I want to add keyboard shortcuts" |
+| `priority-override` | Explicit reprioritization request | "Move KANBAN-015 above KANBAN-010" |
+| `modification` | Change to an existing FR or story | "CSV export should also support JSON" |
+| `question` | Query about PRD state, coverage, or priorities | "What's the current PRD coverage?" |
+
+##### Step 3: Append to Inbox
+
+Read `{pm_inbox_path}`. If it doesn't exist, create it with an empty `messages:` list.
+
+Append the new message:
+
+```yaml
+  - id: {next_sequential_id}
+    timestamp: {ISO-8601}
+    from: user
+    type: {classified_type}
+    content: "{user's original message}"
+    status: pending
+```
+
+##### Step 4: Acknowledge
+
+Respond to the user with confirmation:
+
+- **If PM is currently alive** (pipeline is between sprints or in grooming): "Message queued for PM. PM is active and will process it shortly."
+- **If PM is not alive** (during sprint execution): "Message queued for PM. PM will process it at the start of the next sprint cycle."
+- **For questions when PM is not alive:** Also provide a quick answer by reading `fr-coverage-map.md` directly (the skill can answer coverage questions without PM being alive, since the data is on disk).
+
+##### Step 5: Handle Priority Overrides Immediately
+
+For `priority-override` messages, the skill also writes the override directly to `pipeline-backlog.yaml` if the referenced stories exist. This is the one message type that takes effect immediately rather than waiting for PM to spawn — the user's explicit priority call should not wait a full sprint cycle.
+
+After writing, mark the inbox message with `status: applied` instead of `pending`, so PM knows the override was already executed and just needs to update its FR coverage map accordingly.
+
+```yaml
+  - id: 3
+    timestamp: 2026-04-06T16:00:00Z
+    from: user
+    type: priority-override
+    content: "Move KANBAN-015 above KANBAN-010"
+    status: applied
+    applied_changes:
+      - story: KANBAN-015, old_priority: 14, new_priority: 9
+      - story: KANBAN-010, old_priority: 9, new_priority: 10
+```
+
+---
+
+### B. PM Prompt Template Design
+
+**File:** `.valent-pipeline/prompts/pm.md`
+
+```markdown
+# 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`
+- `{pm_inbox_path}` — `pm-inbox.yaml`
+- `{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're entering next
+- `{calibration_data}` — velocity, rework, bug counts from calibration table
+
+## Inputs (Provided by TeamLead at Spawn)
+
+**Sprint 1 (initial spawn):**
+- PRD document(s)
+- Current `pipeline-backlog.yaml`
+- Story input files (for FR mapping)
+
+**Sprint 2+ (inter-sprint spawn):**
+- `[SPRINT-RESULTS]` message from TeamLead (see Communication Protocol)
+- Retrospective correction directives (once retro completes)
+- Current `pipeline-backlog.yaml`
+- Current `fr-coverage-map.md` (from disk — PM's prior output)
+- `pm-inbox.yaml` (user messages queued since last spawn)
+
+**Final audit spawn:**
+- All of the above
+- Full calibration table history
+
+## Outputs
+
+| Artifact | When | Purpose |
+|----------|------|---------|
+| `fr-coverage-map.md` | Every spawn | Living FR → story → evidence map |
+| `pipeline-backlog.yaml` | When reprioritizing | Updated priority fields, new gap stories |
+| `pm-inbox.yaml` | When processing user messages | Mark messages processed with results |
+| PRD document | 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 TeamLead) | 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.md` 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 `pipeline-backlog.yaml`.** 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.
+
+### Phase B: Process User Inbox
+
+Read `{pm_inbox_path}`. For each message with `status: pending`:
+
+1. **`feature-request`:**
+   - Translate the idea into PRD-quality FR(s) with acceptance criteria
+   - Add FR(s) to the PRD with a changelog entry noting the sprint and source
+   - Create story/stories in `{backlog_path}` with `source: pm-inbox`
+   - Create story input files in `{story_directory}`
+   - Assign priority based on product value relative to existing backlog
+   - Update FR coverage map with new FRs as `pending`
+   - If concerns exist (conflicts, scope impact), note them in the result
+   - Mark message `status: processed` with summary
+
+2. **`modification`:**
+   - Update the existing FR in the PRD
+   - If the covering story is not yet groomed, update its story input file
+   - If already shipped, create a follow-up story for the modification
+   - Mark message `status: processed`
+
+3. **`priority-override` with `status: applied`:**
+   - Override was already applied by the `/pm` skill
+   - Update FR coverage map to reflect any impact on FR delivery order
+   - Mark message `status: processed` (acknowledge only)
+
+4. **`priority-override` with `status: pending`:**
+   - Apply the reprioritization to `{backlog_path}`
+   - Mark message `status: processed`
+
+5. **`question`:**
+   - Answer from current state (FR coverage map, backlog, calibration data)
+   - Write answer to `result` field
+   - Mark message `status: processed`
+
+### Phase C: Sprint Analysis (Sprint 2+ Only)
+
+Read the `[SPRINT-RESULTS]` from TeamLead. 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 are signals 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 TeamLead
+
+### Phase E: Send Backlog Update to TeamLead
+
+Send `[BACKLOG-UPDATE]` message to TeamLead:
+
+```
+[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, PM stays alive but is mostly passive. PM watches for:
+
+1. **REQS briefs that don't tag FRs:** If a `reqs-brief.md` doesn't reference which
+   FRs it covers, PM flags it to Lead for REQS rework. This is the only intervention
+   PM makes during grooming.
+
+2. **FR coverage map updates:** As stories get groomed, PM can update coverage status
+   from `gap-unmapped` to `pending` if a new story now covers an FR.
+
+PM does NOT participate in spec review, sizing, or planning. It tears down when
+TeamLead signals grooming is complete and execution is about to begin.
+
+### Phase G: Final Audit (Completion Only)
+
+At epic/project completion, PM runs a full reconciliation:
+
+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` (see Responsibility #5 in design above)
+4. Report to user with: 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
+
+## Backlog Write Rules
+
+PM writes 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`
+- PM assigns `epic`, `title`, `depends_on` based on FR analysis
+- PM does 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)
+
+## 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; TeamLead 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 (future technical owner).
+- **Modify stories that are in-flight.** If a story is `sprint-planned` or later, do not
+  change its priority or inputs. Queue the change for the next sprint.
+```
+
+---
+
+### C. Integration Changes to `valent-run-epic` and `valent-run-project`
+
+Both SKILL.md files need the same structural changes. The sprint loop gains PM spawn/teardown steps, and the completion flow gains the final audit.
+
+#### Changes to `valent-run-epic/SKILL.md`
+
+##### New Step 3b: Initial PM Review (after Step 3, before Step 4)
+
+Insert after "Step 3: Initialize or Resume Epic Progress" and before "Step 4: Sprint Loop":
+
+```markdown
+### Step 3b: Initial PM Review
+
+If `pm.enabled` is true in pipeline config:
+
+1. Spawn PM agent on the team (`valent-{epic_id}`) with context:
+   - `{prd_path}`, `{backlog_path}`, `{story_directory}`, `{epic_id}`
+   - `{fr_coverage_map_path}` = adjacent to `{epic_progress_path}`
+   - `{pm_inbox_path}` = adjacent to `{epic_progress_path}`
+   - `{sprint_number}` = 1
+2. PM executes Phase A (reconcile state) and Phase B (process inbox)
+3. PM builds initial `fr-coverage-map.md`
+4. PM sends `[BACKLOG-UPDATE]` — may reprioritize or create gap stories
+5. Re-read `{backlog_path}` after PM's update (PM may have added stories)
+6. PM stays alive — will be present during grooming (Phase F)
+```
+
+##### Modified Step 4f: Sprint Planning (add PM teardown)
+
+After sprint planning completes, add:
+
+```markdown
+If PM is alive, send `shutdown_request` to PM. PM tears down before execution.
+```
+
+##### Modified Step 4h: Sprint Review (add PM spawn)
+
+After the retrospective completes (existing Step 4h), add:
+
+```markdown
+If `pm.enabled` is true and pending stories remain:
+1. Spawn PM agent on the team with context:
+   - `[SPRINT-RESULTS]` message with sprint outcomes
+   - `{pm_inbox_path}`, `{fr_coverage_map_path}`, `{backlog_path}`
+   - `{calibration_data}` from sprint review
+   - `{sprint_number}` = next sprint number
+2. PM executes Phases A through E (reconcile, inbox, analysis, reprioritize, update)
+3. Re-read `{backlog_path}` after PM's `[BACKLOG-UPDATE]`
+4. PM stays alive for grooming oversight (Phase F)
+5. Proceed to Step 4a (next sprint loop iteration)
+```
+
+##### Modified Step 5: Epic Complete (add final audit)
+
+Insert before "Step 5a: Write Epic Report":
+
+```markdown
+#### Step 5 (pre): PM Final Audit
+
+If `pm.enabled` is true:
+
+1. Spawn PM agent one final time with context:
+   - All sprint history, full calibration table, final backlog state
+   - `{fr_coverage_map_path}`, `{pm_inbox_path}`, `{prd_path}`
+2. PM executes Phase G (final audit)
+3. PM writes `prd-audit-report.md` adjacent to `{epic_progress_path}`
+4. PM reports weak-coverage blockers and gap stories to user
+5. Teardown PM
+6. Include PM's audit summary in the epic report (Step 5a)
+```
+
+#### Changes to `valent-run-project/SKILL.md`
+
+The changes are identical in structure to `valent-run-epic`, with these differences:
+
+- **Team name:** `valent-project` instead of `valent-{epic_id}`
+- **PRD handling:** PM reads ALL PRDs across all epics (from each epic's `{prd_path}` or a project-level PRD directory). Pass `{is_project_mode}` = true so PM builds a unified cross-epic FR coverage map.
+- **Step 3b context:** Include the cross-epic dependency map so PM can factor inter-epic dependencies into priority decisions.
+- **FR tagging in coverage map:** Each FR is tagged with its source epic so gap stories route to the correct epic.
+
+##### New Step 3b: Initial PM Review
+
+Same as epic mode, except:
+
+```markdown
+### Step 3b: Initial PM Review
+
+If `pm.enabled` is true in pipeline config:
+
+1. Spawn PM agent on the team (`valent-project`) with context:
+   - All PRD paths (one per epic, or project-level PRD directory)
+   - `{backlog_path}`, `{story_directory}`, `{is_project_mode}` = true
+   - `{fr_coverage_map_path}` = adjacent to `{epic_progress_path}`
+   - `{pm_inbox_path}` = adjacent to `{epic_progress_path}`
+   - `{sprint_number}` = 1
+   - Cross-epic dependency map from Step 2
+2. PM builds unified cross-epic FR coverage map
+3. PM sends `[BACKLOG-UPDATE]` — may reprioritize across epics or create gap stories
+4. Re-read `{backlog_path}` after PM's update
+5. PM stays alive for grooming oversight
+```
+
+Steps 4f, 4h, and 5 follow the same pattern as epic mode.
+
+#### Changes to `sprint-review.md`
+
+Add PM spawn trigger after Step 6 (retrospective):
+
+```markdown
+## Step 6b: Spawn PM (if enabled)
+
+If `pm.enabled` is true and the sprint loop will continue (unshipped stories remain):
+
+Spawn PM on the existing team with `[SPRINT-RESULTS]`:
+
+| Field | Source |
+|-------|--------|
+| `sprint_id` | `{current_sprint_id}` |
+| `stories_shipped` | from sprint plan actuals |
+| `stories_rolled_over` | from Step 5 |
+| `stories_cancelled` | from backlog (status changed this sprint) |
+| `stories_blocked` | from backlog (status changed this sprint) |
+| `velocity` | from Step 2 summary |
+| `velocity_trend` | compare this sprint's velocity to SMA-5 |
+| `rework_cycles_total` | sum from sprint plan actuals |
+| `bugs_filed` | count from shipped stories' bugs.md files |
+
+PM runs concurrently with any remaining retrospective wrap-up. TeamLead waits for
+PM's `[BACKLOG-UPDATE]` before proceeding to next sprint-init.
+```
+
+#### Changes to `sprint-groom.md`
+
+Add PM teardown trigger at grooming completion:
+
+```markdown
+## Step N (new): Teardown PM
+
+After all stories in the grooming batch have passed READINESS (or the grooming
+phase is complete):
+
+If PM is alive on the team, send `shutdown_request` to PM. PM has had the
+opportunity to validate FR tagging in reqs-briefs during grooming. It is no
+longer needed until the next inter-sprint cycle.
+```
+
+#### Changes to `agents-manifest.yaml`
+
+Add PM to the agents section:
+
+```yaml
+  pm:
+    name: PM
+    model: opus
+    lifecycle: per-sprint
+    role: "Product owner — tracks PRD completion, reprioritizes backlog between sprints, generates gap stories, maintains living PRD"
+    prompt_template: .valent-pipeline/prompts/pm.md
+    reads_from: [prd, pipeline-backlog.yaml, epic-progress.md, sprint-plan, calibration-table, fr-coverage-map.md, story-reqs-briefs, pm-inbox.yaml]
+    writes_to: [fr-coverage-map.md, prd-audit-report.md, pipeline-backlog.yaml, prd, pm-inbox.yaml]
+    spawned_by: lead
+    spawn_trigger: inter-sprint  # Lead spawns PM after sprint review + retro
+```
+
+#### Changes to `pipeline-config.yaml`
+
+Add PM configuration section:
+
+```yaml
+pm:
+  enabled: true                    # enable PM agent (default: true)
+  auto_reprioritize: true          # PM can reorder backlog without user confirmation (default: true)
+  auto_generate_gap_stories: false # auto-create gap stories without user confirmation (default: false)
+```
+
+No new `prd_path` config needed — it already exists under `project`.
+
+#### Changes to `load-pipeline-config.md`
+
+Add PM context variables to the resolution list:
+
+```markdown
+- `{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}`
+```
+
+#### Changes to `pipeline-state.json`
+
+Add PM tracking to the sprint state:
+
+```json
+"current_sprint": {
+  ...existing fields...,
+  "pm_spawned": false,
+  "pm_backlog_update_received": false,
+  "fr_coverage_percentage": null
+}
+```
+
+This allows crash recovery to know whether PM has already run for this sprint cycle. If `pm_spawned` is true but `pm_backlog_update_received` is false, Lead re-spawns PM on recovery.