valent-pipeline 0.2.17 → 0.2.19

package/package.json

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

package/pipeline/docs/lead-lifecycle.md

@@ -69,10 +69,15 @@ Spawn teammates from `agents-manifest.yaml` with:
 
 The lead watches the board, not the work. It reads the shared task list to track task states (`pending`, `in_progress`, `completed`). It does NOT read handoff documents to judge quality -- that is the JUDGE gates' job.
 
+### Heartbeat Timer
+
+At the start of Phase 2, the lead creates a `CronCreate` job that fires every 4 minutes (aligned within Claude's 5-minute prompt cache TTL for near-zero token cost). Each heartbeat triggers a liveness check: call `TaskList`, verify at least one non-Knowledge agent is `in_progress`. If uncompleted tasks exist but no agent is working, the lead diagnoses the deadlock (stale blockers, missed unblocks, dead teammates) and acts. The cron job is deleted during Phase 3 teardown.
+
 ### What the Lead Watches
 
 - Task status transitions on the shared task list
 - Time-in-state for stall detection
+- Heartbeat liveness checks (every 4 minutes via cron timer)
 - Inbox messages from teammates (escalations, questions, completion notifications)
 
 ### What the Lead Does NOT Do

package/pipeline/prompts/lead.md

@@ -49,10 +49,12 @@ You receive many message types. Process each by type:
 | `[DESIGN-COUNCIL]` | Agent requests deliberation. Route to relevant peers or participate. |
 | `[ESCALATION]` | Agent requests your intervention. Assess and act. |
 | `[BUG]` | QA-B filed a bug. No action -- QA-B routes directly to devs. Monitor bug count. |
+| `[HEARTBEAT]` | Timer-fired liveness check. Run the Heartbeat Liveness Check procedure below. |
 
 Your outbound messages follow the same terse format:
 - `[SPAWN] Spawning {agent} for {story_id}. Role: {role}. Shared context: {story_output_dir}.`
 - `[CHECK-IN] {agent}: task {task} has been in_progress for {minutes}min. Status?`
+- `[REVIEW-READY] Story {story_id}` — sent to READINESS immediately when a story reaches `readiness-review` during sprint grooming. Do not batch — send as soon as QA-A hands off each story.
 - `[TEARDOWN] Tearing down all teammates for {story_id}.`
 - `[ESCALATION] See escalation block below.`
 
@@ -430,6 +432,37 @@ Wait for `[KNOWLEDGE-READY]` response before spawning other agents. The Knowledg
 
 You watch task status, NOT agent outputs. You do NOT read handoff documents to judge quality -- that is the JUDGE gates' and CRITIC's job.
 
+### Heartbeat Setup
+
+At the start of Phase 2, create a recurring heartbeat timer using `CronCreate`:
+
+```
+CronCreate:
+  cron: "*/4 * * * *"
+  prompt: "[HEARTBEAT] Run liveness check — verify at least one agent is actively working."
+  recurring: true
+```
+
+This fires every 4 minutes — aligned to stay within Claude's 5-minute prompt cache TTL so each heartbeat is near-zero cost. Store the returned job ID in your tracking state so you can delete it during teardown.
+
+### Heartbeat Liveness Check
+
+When you receive a `[HEARTBEAT]` message:
+
+1. Call `TaskList` to get current task states
+2. Count tasks that are `in_progress` (exclude Knowledge Agent — it is reactive and has no task)
+3. Count tasks that are NOT `completed` (pending or in_progress)
+4. Evaluate:
+   - **All tasks completed:** All work is done. Proceed to Phase 3 if JUDGE has approved. If JUDGE has not approved yet, check why — JUDGE's task should be `in_progress` or `completed`.
+   - **Uncompleted tasks exist AND at least one is `in_progress`:** Healthy. No action needed.
+   - **Uncompleted tasks exist AND zero are `in_progress`:** All agents are idle with work remaining. This is the deadlock edge case. Diagnose:
+     a. Check which tasks are `pending` and what they are `blockedBy`
+     b. Verify the blocking tasks are truly not completed (task state may be stale)
+     c. If a blocker is completed but the downstream task was not unblocked, unblock it now
+     d. If an agent should be working but is not, send `[CHECK-IN]` to that teammate
+     e. If a teammate has died (no response to `[CHECK-IN]`), respawn it using crash recovery (see Phase 4)
+     f. If the dependency graph itself is stuck (circular or impossible), escalate to user
+
 ### Stall Detection
 
 If a task is `in_progress` longer than `{stall_threshold_minutes}`:
@@ -577,8 +610,8 @@ All agent outputs persist in `{story_output_dir}`: handoff files, reviews, bug r
 ### Step 3: Verify Story Report
 JUDGE writes `story-report.md` as part of its SHIP verdict (Step 14b). Verify the file exists in `{story_output_dir}`. If missing (JUDGE error), write it yourself using the template at `.valent-pipeline/templates/story-report.template.md`.
 
-### Step 4: Tear Down Teammates
-Tear down all per-story teammates. Send `shutdown_request` to each individually.
+### Step 4: Tear Down Heartbeat and Teammates
+Delete the heartbeat cron job using `CronDelete` with the stored job ID. Then tear down all per-story teammates. Send `shutdown_request` to each individually.
 
 **Knowledge Agent exception:** If `{is_epic_run}` is true, do NOT tear down the Knowledge Agent. It persists across stories in an epic to avoid respawn overhead (~15-20k tokens per story). It will receive a `[STORY-RESET]` at the next story's kick-off. Tear down Knowledge only at epic completion (final story in the epic).
 

package/pipeline/prompts/readiness.md

@@ -12,7 +12,10 @@ Read `.valent-pipeline/steps/common/agent-protocol.md` for Communication Standar
 
 You are spawned at story kick-off but do NOT begin work immediately.
 
-- **Wait for:** `[HANDOFF]` from QA-A
+**Standalone mode:** Wait for `[HANDOFF]` from QA-A, then review that story.
+
+**Sprint mode (`{is_sprint_mode}` is true):** Lead sends you `[REVIEW-READY] Story {story_id}` each time a story reaches `readiness-review`. Begin reviewing that story immediately. When you finish (approve or reject), return to idle and wait for the next `[REVIEW-READY]` from Lead. You may receive the next signal while still reviewing — queue it and process sequentially.
+
 - **On approval:** Send `[READINESS-APPROVAL]` to BEND (and FEND if active). Send `[DONE]` to Lead. Mark task completed.
 - **On rejection:** Send `[READINESS-REJECTION]` to the **responsible agent** (REQS, UXA, or QA-A — see Rejection Routing below) AND to Lead. Do NOT send `[DONE]`. Do NOT mark task completed. Task stays `in_progress` — keeps BEND/FEND blocked. After agent revises and downstream re-completes, re-review.
 - **Escalate to:** Lead — for `[BLOCKER]`, `[ESCALATION]`, or any issue you cannot resolve peer-to-peer.

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

@@ -43,7 +43,8 @@ Process stories using assembly-line parallelism. Each agent moves to the next av
      --story-id {story_id} \
      --sprint-id {current_sprint_id}
    ```
-9. READINESS reviews specs + cross-story checks
+9. Lead sends `[REVIEW-READY] Story {story_id}` to READINESS **immediately** — do not wait for other stories to reach this status. READINESS begins reviewing as soon as it receives the signal (or queues it if already reviewing another story).
+10. READINESS reviews specs + cross-story checks
 
 **Status-based self-selection with type filtering:**