From 14cecbc321c9802ff3b8688e8a8013eb4b43742b Mon Sep 17 00:00:00 2001 From: violet Date: Thu, 28 May 2026 16:37:00 +0300 Subject: [PATCH] docs(roles): document FIX-LANDED protocol for clearing stand-down state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Empirically, STAND-KEEPER clears a `down` stand via `greatminds stand up` only after receiving an inbox wake whose body carries semantic "fix landed" content from DEVELOPER or TESTER. This protocol was not documented in any role doc, and the resulting discoverability gap caused multi-hour stalls when implementers sent misshaped wakes (e.g. "FOR THIS LEASE: load_profile..." while there was no active lease) and then asked MAINTAINER to override the SK-only `stand up` CLI. This patch documents the canonical `FIX-LANDED` body shape in three places: - STAND-KEEPER.md: SK reads the body verbatim, verifies the worktree path, then transitions. Explicitly states SK should ignore bare wake pings and lease-shaped wakes while down — that friction is what prevents stray re-deploys of unfixed code. - TESTER.md / DEVELOPER.md: holders / implementers learn the canonical body shape and are told NOT to route to MAINTAINER — `stand up` is SK-only and MAINTAINER has no override. Pure documentation change. No CLI surface or schema modified. Co-Authored-By: Claude Opus 4.7 --- src/greatminds/data/roles/DEVELOPER.md | 19 +++++++++++++++++ src/greatminds/data/roles/STAND-KEEPER.md | 26 +++++++++++++++++++++-- src/greatminds/data/roles/TESTER.md | 21 ++++++++++++++++++ 3 files changed, 64 insertions(+), 2 deletions(-) diff --git a/src/greatminds/data/roles/DEVELOPER.md b/src/greatminds/data/roles/DEVELOPER.md index c1d2718..0056bed 100644 --- a/src/greatminds/data/roles/DEVELOPER.md +++ b/src/greatminds/data/roles/DEVELOPER.md @@ -21,6 +21,25 @@ DEVELOPER implements backend/product-code tasks planned by ARCHITECT-PLANNER. 5. For `plan.stand_required: true`, files a stand request with `greatminds stand request ... --evidence-for `. 6. Records any stand request id/result/caveat in the implementation block. + + **If a prior iter put the stand in `down`** because of a + playbook bug your iter-N fix resolves: after the fix is in + your worktree, send STAND-KEEPER a wake with the canonical + `FIX-LANDED` body shape (SK reads the body verbatim and will + then run `stand up` on its next tick — `greatminds stand up` + is SK-only): + + ```bash + greatminds inbox send STAND-KEEPER --kind wake \ + --task \ + --body "FIX-LANDED for stand-profile . \ + Worktree .worktrees//coordination/stand-profiles/.yaml \ + carries iter- changes: . Please \ + greatminds stand up --reason 'iter- fix landed for '." + ``` + + Don't ask MAINTAINER to clear the stand — `stand up` is gated + to STAND-KEEPER and MAINTAINER has no override. 7. If blocked only by named external dependencies: `greatminds task append-block blocked --id --field dependencies=/.yaml,... --field resume_to=feature_dev` diff --git a/src/greatminds/data/roles/STAND-KEEPER.md b/src/greatminds/data/roles/STAND-KEEPER.md index 362fd18..8daddff 100644 --- a/src/greatminds/data/roles/STAND-KEEPER.md +++ b/src/greatminds/data/roles/STAND-KEEPER.md @@ -89,8 +89,30 @@ gone. The singleton stand is driven by `coordination/.stand/state.yaml`. `preparing` lease on a later tick. 5. **On deploy or infra failure:** run `greatminds stand down --reason "profile failed: "`, naming - the failed profile step. Queue processing pauses. - After recovery, run `greatminds stand up --reason ""`. + the failed profile step. Queue processing pauses until you run + `greatminds stand up`. While the stand is `down`, **do not act + on bare wake pings or wakes that describe a lease** — there is + no active lease to deploy, and re-running an unfixed playbook + would just re-fail. + + **Clearing the `down` state.** Run `greatminds stand up --reason + ""` only after receiving an inbox message whose body + carries an explicit *fix-landed* signal from the implementer + (DEVELOPER) or the holder (TESTER / EXPLORER). The canonical + body shape is: + + > `FIX-LANDED for stand-profile . Worktree + > .worktrees//coordination/stand-profiles/.yaml + > carries iter- changes: . Please + > greatminds stand up --reason "iter- fix landed for ".` + + Verify the worktree carries the named change (a quick `grep` + or `diff` is enough — you do not need to re-deploy yet), then + transition with `stand up`. If the body lacks the `FIX-LANDED` + prefix or doesn't name a worktree path you can verify, ignore + the message — the stand stays `down` until a properly-shaped + signal arrives. This intentional friction is what prevents a + stray wake from re-running unfixed code. 6. **Never release the holder's active lease.** TESTER or EXPLORER runs `greatminds stand release --lease-id --result pass|fail|partial` after its own probes. diff --git a/src/greatminds/data/roles/TESTER.md b/src/greatminds/data/roles/TESTER.md index 535a2d1..407babc 100644 --- a/src/greatminds/data/roles/TESTER.md +++ b/src/greatminds/data/roles/TESTER.md @@ -51,6 +51,27 @@ tests block. only in the product task's `tests` block. The old `stand_requests/` -> `stand_wip/` -> `stand_done/` path is removed from the active workflow. + + **When the stand sits in `down`** (e.g. a prior deploy hit a + playbook bug and you've bounced the task to DEVELOPER for a fix): + wait for DEV's inbox info that iter-N has landed. Then, if you + want to drive the recovery yourself, send STAND-KEEPER a wake + with the canonical `FIX-LANDED` body shape: + + ```bash + greatminds inbox send STAND-KEEPER --kind wake \ + --task \ + --body "FIX-LANDED for stand-profile . \ + Worktree .worktrees//coordination/stand-profiles/.yaml \ + carries iter- changes: . Please \ + greatminds stand up --reason 'iter- fix landed for '." + ``` + + `greatminds stand up` is SK-only — TESTER cannot call it + directly. The wake's `FIX-LANDED` body is what SK reads to know + the state is safe to clear. Bare wake pings or wakes that talk + about an active lease are not enough; SK will (correctly) ignore + them while the stand is `down`. 6. For `plan.stand_required: true`: - waits for its lease to become ready via SK's inbox-info, - probes the stand directly and records lease-based stand evidence,