Serious Coding Runbook

CANON v1.1.0 — Léo 2026-07-31 (@team make the runbook canon, Buzz 919fb719)

Open in Obsidian: this note.
Deep link: obsidian://open?vault=lgl&file=AI%2FAgents%2FCraft%2FSerious%20Coding%20Runbook

What it is

Default path for serious coding on Léo's stack — no new runtime. Composes Buzz, herdr, Kanban (optional), Obsidian/Jared progress homes, TDD/CI, and existing review skills.

Layers: Harness (repo/tools/ownership) · Loop (impl → evidence → review → fix) · Graph (who may run next).

Roles

Ownership law: never modify files in someone else's work unless they ask. Ideas → Obsidian / Buzz; owner edits the tree.

When to use

Primary law = risk and boundary, not file count. >3 files is a heuristic only.

Cold-start checklist (normative — not standalone-sufficient for high-risk)

1. Roles clear: Q dispatch · K impl · D review · Léo ship/device authority
2. Preflight: one canonical progress home + versioned done-when + dirty-tree record
3. Graph: preflight → impl(+evidence packet) → review(D) → ship/device-write/human-accept as gated
4. Packet: thick handoff every edge (full or immutable revision + exact delta). Thin pings refused
5. Evidence: loop on tests/CI/runtime/human bars — never on confidence
6. Verdicts: APPROVED → next gate · REQUEST_CHANGES → fix round · BLOCK → stop. Spec FAIL cannot ship
7. Damper (Léo): escalate when severity/count fails to improve or Q judges little/no progress. Soft ~2/~5 advisory only — not hard abort. Q unsure → Léo
8. Safety: never delete/reset/stash/history-rewrite without explicit Léo; no shared writable worktree; secrets → Bitwarden/tmpfs; dumps → manifest only
9. Gates: exact artifact hash + commit; executor verifies before act; re-exec of done gate REFUSED. Integrity ≠ authorization. Device rollback = CURRENT state, proven before write
10. Envelope: ACTION_ID · TASK_ID · STATE_REV · commit/range · SHA(s) · status · expected state — Q owns STATE_REV; Buzz is notification only

Default graph (happy path)

preflight → plan? → impl(+evidence) → standards(Q) → review(D)
  APPROVED → merge? / device_write? / deploy? → runtime_verify? → human_accept?
  REQUEST_CHANGES → fix_N(K) → re-evidence → re-review
  little/no progress (Q damper) → escalate(Léo)

Device-write is a first-class gate, not "ship". Four separate events: technical approval · device-write · runtime verify · human accept.

Action vocabulary (one only)

CLOSED → OPEN → CLAIMED → EXECUTED → CLOSED

Review lease is separate: READY_FOR_REVIEW rev=N → freeze → D REVIEWING → verdict / SUPERSEDED N→N+1. Do not use READY as an action-gate state.

Crossed messages — the expensive lesson (2026-07-31)

Empirical worked example (also in references/default-graph.md). Mistakes are the instructive part.

What happened: three crossed-message incidents under multi-seat load. In the worst one, Kepler executed a device action against a gate revoked ~63 seconds earlier — late wake / stale snapshot, not bad intent. Integrity of the bytes was fine; the authorization window had closed.

What held: Daedalus's two-phase lease barrier (freeze → claim → act only while gate still OPEN for that rev). It refused a false positive from Kepler's own watcher. Desired failure mode: noisy sensors, quiet actuators.

Skill files

bash ~/.hermes/shared/skills/software-development/serious-coding-runbook/references/validate.sh

Standing notes (agents)

• [[AI/Agents/Kepler/2026-07-31-serious-coding-runbook]] — Kepler lane
• [[AI/Agents/Daedalus/2026-07-31-serious-coding-runbook]] — Daedalus lane

Out of scope (still proposed / separate Léo call)

• Buzz CAS action ledger tooling
• Stage A/B firmware narrative as a second worked example (optional)

Origin

Harness/loop/graph discussion mapped onto the Q/K/D stack (2026-07-25+). Full seat vet 2026-07-31 through fix-rounds 1 → 1e (SRB-1101–1107, K1–K7, damper, envelope).