The WAL Convention — session-durable project state
01Discipline v0.2 · status: BETA · T1 · language-neutral · OPTIONAL but preferred
02Agent sessions end, compact, and crash; a project outlives all of them.
03This convention makes session boundaries cheap by keeping the project's living state in two repository files.
04It is optional: every Discipline procedure that touches it (Sweep §4, Campaign Form §4, the shipped terraform/sweep skills) carries an explicit without-WAL branch.
05It is preferred because the alternative — resumption state scattered across commit messages and plan-status lines — degrades as a project grows.
06Adopt it when more than one session (or more than one operator) will ever touch the tree.
1. The two files
07vibevm/vibespecs/WAL.xml — the living checkpoint. Describes the current state:
a dated standing line (what landed, gate-panel state, what's next, known
issues), plus a per-session section for the active campaign.
08Two hard rules:
- 09Rewrite, not append. The WAL is a checkpoint, not a log — its lead always describes now. History lives in git; an append-only WAL rots into an archive nobody reads. (Prior standing lines may be demoted into a PRIOR-tail as they age; the git log is the authoritative per-item record.)
- The WAL is canonical. Where the WAL and any snapshot (CONTINUE, a plan's status line, a README) disagree, the WAL wins.
10CONTINUE.md (repo root) — the cold-resume snapshot. Written at session
end for whoever picks up cold: TL;DR, where work stands (branch, sync,
tree state), the active blocker and the exact action that unblocks it, the
next-steps recipe with paths and commands, non-obvious findings, and the
recent commit chain.
11Overwritten wholesale each time — staleness compounds otherwise.
12It is a snapshot; the WAL supersedes it.
2. The freshness rule
13A WAL older than 24 hours is stale: verify the recorded state against reality (branch, gates, tree) before any destructive work, and say so to the owner when the divergence matters.
14Tooling may enforce this advisorily (the pilot's project linter warns on a stale WAL); the sweep's Tier-2 drift pass checks it weekly regardless.
3. Session boundaries
- 15Session end (wind-down): update the WAL's standing line + session section; rewrite CONTINUE.md; commit both as their own topic commits. The test: a stranger with only the repository resumes without asking.
- Session resume: boot per the project's boot sequence, read the WAL, read CONTINUE.md, verify empirically, report and wait — a recorded "next step" is the candidate, not an authorisation; the owner steers.
- Mid-work checkpoints: campaigns bump the WAL at phase boundaries (Campaign Form §3–4); sweeps bump it at milestone moves (Sweep §4).
4. Without a WAL
16A project that opts out still owes the same invariant — resumption state lives in the repository, never in a session.
17The fallbacks the procedures use:
- 18a campaign PLAN carries a status line at its top, updated with each phase's commits;
- a sweep's closing commit message carries the summary, and the committed health snapshot is the trend record;
- the terraform skill's inventory registries (BROWNFIELD §3) hold what a WAL would have held about debt and intent.
19These fallbacks work; they are simply weaker — three places instead of one, no single canonical "now".
20When a without-WAL project notices it keeps re-deriving its own state, that is the signal to adopt §1.
5. Scope discipline
21The WAL records project facts.
22Machine-scoped quirks (shell behaviors, OS footguns of one contributor's box) belong in that machine's user-scoped notes or the project's boot user-override file — not in the WAL and not in the Discipline's method documents.
23Keep the three layers apart: method (this package), project (WAL/CONTINUE), machine (user-owned boot snippet).