From 77c37c834724692d44de57ee9c4b4ac407e4802b Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Wed, 8 Jul 2026 13:23:05 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20checkpoint-and-continue=20=E2=80=94=20s?= =?UTF-8?q?upervised=20runs=20park=20and=20advance=20(#42)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AUTONOMY.md gains the operational mechanics generalised from register_and_iterate: trigger (judgment gates only), one batched answerable-cold question per pause, awaiting-input parking with a question: pointer in active.md, continue policy (next independent step -> next task -> clean end), resume from active.md in any environment; hard blockers park as blocked, never as questions. start_dev supervised line links the section; register_and_iterate's contract now references the general pattern (single source). Ship sign-off/merge park the task, never bypass the gate. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_013UptUDNTYiB7izaQJBAKgS --- AUTONOMY.md | 43 ++++++++++++++++--- .../register_and_iterate.md | 7 ++- skills/start_dev/start_dev.md | 6 ++- 3 files changed, 46 insertions(+), 10 deletions(-) diff --git a/AUTONOMY.md b/AUTONOMY.md index 47ec36a..e07dc1f 100644 --- a/AUTONOMY.md +++ b/AUTONOMY.md @@ -39,10 +39,8 @@ Where the dev workflow stops for a human today: The difference between `safe` and `supervised` is the ship step and judgment gates: `safe` runs end-to-end to an open PR; `supervised` proceeds wherever the path is mechanical but converts each judgment gate into a batched question on -the issue and moves on (**checkpoint-and-continue** — the question is written -with enough context to answer cold, the task parks as `awaiting-input` in -`active.md`, and the session advances to the next independent step or task -rather than blocking). +the issue and moves on — **checkpoint-and-continue**, defined in its own +section below. ## Per-work-type caps @@ -67,6 +65,37 @@ evidence. - Opt-in per invocation, never ambient: no config flag, no environment variable, no "remembered" mode. +## Checkpoint-and-continue (`supervised`) + +The operational mechanics of the levels-table behaviour, generalised from +`register_and_iterate`'s proven contract (its "writes a clear question and +stops … auto-advances between tasks"): + +- **Trigger** — any judgment gate the levels table marks as a question for + `supervised`: ship sign-off, a scope/design fork the plan didn't settle, an + ambiguous classification, a FINDINGS verdict the run cannot resolve + mechanically. Mechanical stretches never pause. +- **The question** — one batched comment per pause on the task's GitHub + issue, written to be answerable cold: what was being done, the fork and the + options, the run's recommendation, and what happens on each answer. Never a + trickle of one-liners (match the conversational issue-update style). +- **Parking** — set the task's `active.md` entry to `status: awaiting-input` + and add `- question: `; push Mind. `active.md` is the + shared cross-environment state — no new store, no daemon. +- **Continue policy** — in order: the next *independent* step of the same + task (one whose outcome no pending answer can invalidate); else the next + queued task; else end the run cleanly with a summary of every parked + question. +- **Resume** — the human answers on the issue (or relaunches); any + environment reads `active.md`, finds `awaiting-input` + the question + pointer, and continues from the recorded state. +- **Hard blockers** are not questions — a thing that cannot work is written + up per the prompt's fallback clause and the task parks as blocked, exactly + as `register_and_iterate` does today. + +Ship sign-off and merge park the *task*, never bypass the gate — +checkpoint-and-continue frees the human's session, not the checkpoint. + ## The autonomous-ship gate An unattended ship (checkpoint 2 at `safe`) requires **all four legs**, no @@ -135,7 +164,9 @@ calibration, not by optimism. for `safe`, launch-acknowledgement recording (its "--auto mode" section). - `ship_library` / `ship_workspace` — the four-leg gate at step 4, stop at PR-open, validation checklist, calibration append. -- Pending from the `PyAutoMind/feature/autonomy/` series: task 5 - (checkpoint-and-continue for `supervised`), task 7 (queue runner). +- `register_and_iterate` — the origin instance of checkpoint-and-continue; + its gates now reference the general section here. +- Pending from the `PyAutoMind/feature/autonomy/` series: task 7 (queue + runner). Skills must link here rather than copying the tables. diff --git a/skills/register_and_iterate/register_and_iterate.md b/skills/register_and_iterate/register_and_iterate.md index da264fa..7332250 100644 --- a/skills/register_and_iterate/register_and_iterate.md +++ b/skills/register_and_iterate/register_and_iterate.md @@ -25,8 +25,11 @@ Prompts are paths relative to `PyAutoMind/`, organised by work type ## Autonomy contract -Runs without intervention **except** at these gates, where it writes a clear -question and stops: +This contract is the origin of, and now an instance of, the general +**checkpoint-and-continue** mechanics in +[`../../AUTONOMY.md`](../../AUTONOMY.md) — question format, `awaiting-input` +parking and resume are defined there, once. Runs without intervention +**except** at these gates, where it writes a clear question and stops: 1. **Aux/dynamic judgment** on an offending type whose classification is not obvious (non-Array attributes, callable state, known-gotcha class). diff --git a/skills/start_dev/start_dev.md b/skills/start_dev/start_dev.md index 71ec0fd..c11b9d4 100644 --- a/skills/start_dev/start_dev.md +++ b/skills/start_dev/start_dev.md @@ -40,8 +40,10 @@ activation rule in [`../../AUTONOMY.md`](../../AUTONOMY.md)): (step 5 below) and proceed straight through steps 4–7 and into `start_library`/`start_workspace` and implementation. The plan the human would have approved is on the issue for post-hoc validation. -3. **`supervised`** → judgment gates become batched issue questions - (checkpoint-and-continue, per the contract); mechanical stretches proceed. +3. **`supervised`** → judgment gates become batched issue questions and the + run advances (the contract's "Checkpoint-and-continue" section: question → + `awaiting-input` park → next independent step or task → resume from + `active.md`); mechanical stretches proceed. 4. **`human-required`** → `--auto` changes nothing; today's flow. 5. If the human acknowledged a Heart YELLOW reason set at launch, record that exact list in the task's `active.md` entry (`- heart-ack:` block) — the