siloqy/prod/docs/BEADS_PASS_TRACKER_EVALUATION.md

# BEADS as PASS Tracker — Evaluation & Recommendation

**Author:** pi_nvnemo (UV Overseer)  
**Date:** 2026-07-08  
**Context:** UV_OVERSEER_CHARTER__PI.md §6 task — evaluate beads vs bus+doc for PASS board

---

## Current State

| Tracker | Status |
|---------|--------|
| **h5i bus** | Active — dispatch, ACK, status updates |
| **Status doc** | Not yet created (charter says "track PASSes on the bus + a short status doc") |
| **beads** | Installed, `.beads/` exists at repo root (prefix `dp`), 1 existing PRODGREEN issue |

---

## What Beads Gives Us Over Bus+Doc

| Capability | h5i Bus + Doc | Beads |
|------------|---------------|-------|
| **Dependency graph** | Manual (doc) | Native (`br dep add`, `br graph`) |
| **Task hierarchy** | Flat (doc sections) | Epic → child beads (parent/child) |
| **State machine** | Manual (doc) | Enforced (open → in_progress → closed) |
| **Acceptance criteria** | Doc prose | Structured fields (`acceptance_criteria`, `test_command`) |
| **Audit trail** | Bus history + doc edits | Immutable JSONL + SQL + `br audit` |
| **Handoff protocol** | Informal | Formal (`br audit --message`, `br ready`) |
| **Multi-agent isolation** | Bus channels | Separate workspace per refactor stream |
| **Low-skill agent onboarding** | Ad-hoc | Bounded task template + dependency chain |
| **Query/Filter** | grep/awk | `br ready`, `br list`, `br status`, SQL |
| **Backup/Sync** | Git + manual | `br sync`, `br backup` |

**Verdict:** Beads adds **structured task management** that the bus+doc lacks — critical for multi-PASS dependency chains (PASS-P → PASS-A → PASS-S → PASS-B/X).

---

## PASS → Bead Mapping

| PASS | Bead Type | Suggested ID | Parent |
|------|-----------|--------------|--------|
| **PASS-P** (Pulse Landing) | Epic | `UV_PASS-P` | — |
| ├─ Copy `prod/uv_pulse_host/` | Task | `UV_PASS-P.1` | `UV_PASS-P` |
| ├─ Add `.gitignore` (exclude `target/`) | Task | `UV_PASS-P.2` | `UV_PASS-P` |
| ├─ Cert conveyor commit | Task | `UV_PASS-P.3` | `UV_PASS-P` |
| ├─ Soak DARK + TUI heartbeat | Task | `UV_PASS-P.4` | `UV_PASS-P` |
| **PASS-A** (Account Region) | Epic | `UV_PASS-A` | — |
| ├─ Phase 0: Contracts + in-mem | Task | `UV_PASS-A.1` | `UV_PASS-A` |
| ├─ Phase 1: Real shm + hardened reader | Task | `UV_PASS-A.2` | `UV_PASS-A` |
| ├─ Phase 2: ASEx publish | Task | `UV_PASS-A.3` | `UV_PASS-A` |
| ├─ Phase 3: Capital provider | Task | `UV_PASS-A.4` | `UV_PASS-A` |
| **PASS-S** (Sizing Seam) | Epic | `UV_PASS-S` | — |
| **PASS-B** (Host Brain) | Epic | `UV_PASS-B` | — |
| **PASS-X** (Tick Exits) | Epic | `UV_PASS-X` | — |

**Dependency Chain:**
```
UV_PASS-P → UV_PASS-A → UV_PASS-S → UV_PASS-B → UV_PASS-X
```

---

## Smallest Viable Setup

```bash
# 1. Create dedicated UV workspace (isolate from PRODGREEN)
mkdir -p /mnt/dolphinng5_predict/uv/.beads
export BEADS_DIR=/mnt/dolphinng5_predict/uv/.beads

# 2. Initialize
br where  # confirms workspace

# 3. Create PASS-P epic + children
br create --title "PASS-P: Pulse Landing" --type epic --id UV_PASS-P
br create --title "Copy prod/uv_pulse_host/ from /mnt/vp-PASS9" --parent UV_PASS-P --type task --acceptance "Directory copied, target/ excluded" --test "ls prod/uv_pulse_host/ && ! ls prod/uv_pulse_host/target/" --id UV_PASS-P.1
br create --title "Add .gitignore excluding target/" --parent UV_PASS-P --type task --acceptance "target/ ignored by git" --test "git check-ignore prod/uv_pulse_host/target/" --id UV_PASS-P.2
br create --title "Cert conveyor commit + integrator review" --parent UV_PASS-P --type task --acceptance "Commit on main, integrator signed" --test "git log --oneline -1 prod/uv_pulse_host/" --id UV_PASS-P.3
br create --title "Soak DARK + TUI heartbeat + STALE" --parent UV_PASS-P --type task --acceptance "TUI renders live rate/AGE/STALE, RSS flat ≥4h" --test "TUI smoke test + log review" --id UV_PASS-P.4

# 4. Link to bus for dispatch notifications
# (beads = source of truth; bus = real-time signal)
```

---

## Recommendation

**ADOPT BEADS for PASS tracking** with the following protocol:

1. **Beads = Source of Truth** — all PASS state, dependencies, acceptance criteria, audit trail
2. **h5i Bus = Real-time Signal** — dispatch, ACK, status pings, escalation (what we already do)
3. **Status Doc = Snapshot** — auto-generated from beads weekly or on demand (`br status > PASS_BOARD.md`)

**Migration Path:**
- Week 1: Create UV workspace, populate PASS-P + PASS-A epics/children
- Week 1: Run dual-track (beads + bus) — validate no drift
- Week 2: Deprecate manual status doc; auto-generate from `br status`

**Why not bus+doc alone?** The PASS chain has 5 epics with 15+ children, strict dependencies, and must survive agent rotation. Beads enforces what the charter demands: "keep a live board; chase stalls; escalate blocked specs."

---

## Next Action

If approved: I'll initialize `/mnt/dolphinng5_predict/uv/.beads`, populate PASS-P epic + children, and link dispatch messages to bead IDs.