valent-pipeline 0.2.18 → 0.2.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valent-pipeline",
-  "version": "0.2.18",
+  "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,6 +49,7 @@ 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}.`
@@ -431,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}`:
@@ -578,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).