docs(driver-v5): expand session lifecycle workflow (maf.4)

skills/beadboard-driver/references/session-lifecycle.md

@@ -1,36 +1,173 @@
 # Session Lifecycle
 
-## 1) Start Session
+This runbook is the minimum lifecycle contract for agents using BeadBoard Driver.
 
-1. Run environment diagnosis.
-2. Run preflight.
-3. Resolve bb path and confirm `bd` availability.
-4. Generate unique session agent name.
-5. Register agent identity.
-6. Confirm you are operating in the assigned target repository.
-7. Do not change project scope (scope is user-controlled in BeadBoard UI).
+## 1) Session Start
 
-## 2) Pick and Claim Work
+1. Run preflight and discovery checks:
 
-1. `bd ready`
-2. `bd show <id>`
-3. `bd update <id> --status in_progress --claim`
+```bash
+node skills/beadboard-driver/scripts/session-preflight.mjs
+node skills/beadboard-driver/scripts/resolve-bb.mjs
+```
 
-## 3) Coordinate During Work
+2. Create or identify your agent bead first (required before claiming work):
 
-1. Reserve sensitive scopes before edits.
-2. Send structured mail for blockers and handoffs.
-3. Read and acknowledge required messages.
+```bash
+bd create --title "Agent: <name>" --type task --priority 0 --label "gt:agent,role:<role>"
+```
 
-## 4) Verify and Close
+3. Set state transitions and attach hook when work begins:
 
-1. Run required gates (typecheck/test/lint).
-2. Build readiness report with checks + artifacts.
-3. Post notes to bead.
-4. Close bead with explicit reason.
+```bash
+bd agent state <agent-bead-id> spawning
+bd agent state <agent-bead-id> running
+```
 
-## 5) Session End Hygiene
+4. Query hard memory for your domain before claim:
 
-1. Release reservations.
-2. Ensure no unresolved blocker mail is pending for your bead.
-3. Hand off context if stopping before close.
+```bash
+bd query "label=memory AND label=mem-canonical AND label=mem-hard AND status=closed"
+```
+
+## 2) Discover Work and Read Epic Context
+
+1. Find ready work:
+
+```bash
+bd ready
+```
+
+2. For child tasks, read parent epic first:
+
+```bash
+bd show <epic-id>
+bd children <epic-id>
+```
+
+3. Read full assigned bead:
+
+```bash
+bd show <bead-id>
+```
+
+## 3) Claim Correctly (`--assignee`, not `--claim`)
+
+Claim order is strict:
+1. Agent bead exists
+2. Set bead to in_progress with assignee
+3. Hook agent slot to current bead
+
+```bash
+bd update <bead-id> --status in_progress --assignee <agent-bead-id>
+bd slot set <agent-bead-id> hook <bead-id>
+bd agent state <agent-bead-id> working
+```
+
+## 4) Dependency Workflow During Execution
+
+Use dependencies to model execution order, not visual grouping.
+
+Add blocker dependency (`<blocked>` depends on `<blocker>`):
+
+```bash
+bd dep add <blocked-id> <blocker-id>
+```
+
+Add non-blocking related context link:
+
+```bash
+bd dep relate <id-a> <id-b>
+```
+
+Inspect dependency state:
+
+```bash
+bd dep list <bead-id>
+bd dep tree <bead-id>
+```
+
+## 5) BLOCKED Path (Mandatory Pattern)
+
+When blocked, do all four actions:
+
+1. State signal:
+
+```bash
+bd agent state <agent-bead-id> stuck
+```
+
+2. Coordination signal:
+
+```bash
+bb agent send --from <agent-name> --to <target-agent-or-role> --bead <bead-id> --category BLOCKED --subject "<blocker summary>" --body "<what is needed>"
+```
+
+3. Keep heartbeat while waiting:
+
+```bash
+bd agent heartbeat <agent-bead-id>
+```
+
+4. Resume cleanly once unblocked:
+
+```bash
+bd agent state <agent-bead-id> running
+bd agent state <agent-bead-id> working
+```
+
+## 6) Verification and Closure
+
+Run gates before close claims:
+
+```bash
+npm run typecheck
+npm run lint
+npm run test
+```
+
+Record evidence and close bead:
+
+```bash
+bd update <bead-id> --notes "Commands run: ... Outputs: ..."
+bd close <bead-id> --reason "<completed outcome>"
+```
+
+Detach hook when bead is complete:
+
+```bash
+bd slot clear <agent-bead-id> hook
+bd agent state <agent-bead-id> done
+```
+
+## 7) Memory Review Rule (Create vs Skip)
+
+Create/supersede canonical memory only when BOTH are true:
+- Rule is reusable across future tasks
+- Evidence exists from at least one concrete failure/recovery pattern
+
+Otherwise, record:
+
+```bash
+bd update <bead-id> --notes "Memory review: no new reusable memory."
+```
+
+If reusable and novel:
+- Create new memory decision bead
+- Link anchor + evidence via `bd dep relate`
+- Supersede old memory if replacing policy (`bd supersede <old> --with <new>`)
+
+## 8) Session End Hygiene
+
+1. Ensure no lingering hook slot:
+
+```bash
+bd slot show <agent-bead-id>
+```
+
+2. Ensure no unresolved required-ack backlog for your active work.
+3. Set end state:
+
+```bash
+bd agent state <agent-bead-id> stopped
+```