| 1 | # State file |
| 2 | |
| 3 | One file in the repo that any session or agent can resume from. Rewrite it at |
| 4 | every wave; history lives in commits and the tracker. The contract decides |
| 5 | whether it is committed or kept out of version control. It never holds secrets |
| 6 | or account identifiers, only the paths where config lives. |
| 7 | |
| 8 | ``` |
| 9 | # <repo> state |
| 10 | |
| 11 | Updated <date, time, timezone>. main at <revision>; latest release <version | none>; |
| 12 | the owner runs <installed version | a dev build | nothing>. |
| 13 | |
| 14 | ## Contract |
| 15 | - <date>: "<the owner's words, verbatim>" → <what it allows or reserves> |
| 16 | - Budget: <policy, verbatim>, <current usage>. |
| 17 | |
| 18 | ## How work is run |
| 19 | - Gate: `<command>` (<lanes>, about <minutes> warm). Run it on the exact revision before landing. |
| 20 | - Land: <commit prefixes and trailers>, then push to <remote>/main. |
| 21 | - Release: `<command>` from `<release checkout>`; <platforms>; publishes to <where>. |
| 22 | - Agents: one workspace each under `<path>`; shared build cache `<path>`; each deletes its own scratch. |
| 23 | - Protected paths, never deleted: <SDKs, toolchains, signing material>. |
| 24 | - The owner's machines: <device>: <what you may do there>. |
| 25 | - Tracker: <url>, through <tool | read only>; issues close on <push | release>. |
| 26 | - Owner-reserved: <names, public prose, flows or features they will design>. |
| 27 | |
| 28 | ## Running now |
| 29 | | Agent | Task (issue) | Workspace | Started | Last checkpoint | |
| 30 | | --- | --- | --- | --- | --- | |
| 31 | |
| 32 | ## Finished, not landed |
| 33 | - <task>: <workspace>, <change>; <why it's waiting> |
| 34 | |
| 35 | ## Shipped, not closed |
| 36 | - #N: <in commit | in version> |
| 37 | |
| 38 | ## Decisions owed |
| 39 | 1. <question>. Options: <A> / <B>. Lean: <A>. Until answered: <what proceeds on the lean>. |
| 40 | |
| 41 | ## Queue |
| 42 | 1. <task> (#N, or a local id when there's no tracker) |
| 43 | 2. <task>: blocked on <what> | owner-reserved |
| 44 | |
| 45 | ## Recovery |
| 46 | - After a usage limit, compaction or reboot: <resume steps, which agents, where their partial work is>. |
| 47 | - Cleanup owed: <remote temp folders, VMs, registry keys>. |
| 48 | ``` |
| 49 | |
| 50 | "Running now" answers "what's running" before anyone asks. "Finished, not |
| 51 | landed" is the list that keeps finished work from being lost in a workspace |
| 52 | cleanup. "Decisions owed" replaces re-listing questions in every report. |