docs(roles): document FIX-LANDED protocol for clearing stand-down state#8
Open
veryviolet wants to merge 1 commit into
Open
docs(roles): document FIX-LANDED protocol for clearing stand-down state#8veryviolet wants to merge 1 commit into
veryviolet wants to merge 1 commit into
Conversation
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 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
FIX-LANDED for <task-id> stand-profile <profile>. Worktree ... carries iter-<N> changes: ...) that SK reads when deciding whether to transitiondown → free.Why
Empirically, the FSM already has a working clearance path: DEVELOPER (or TESTER) sends SK an inbox message announcing that an iter-N fix has landed in the relevant worktree, and SK then runs
greatminds stand up. SK's behavior here has been consistent across many task cycles. But the protocol was never written down — TESTER.md and DEVELOPER.md mentionstand lease/stand releasebut stop there; STAND-KEEPER.md says "after recovery, runstand up" without telling SK how to recognize recovery.In a recent nginarea session this gap caused a multi-hour stall:
*.ptrsync exclude). SK correctly transitioned the stand todownwith a detaileddown_reason."FOR THIS LEASE: load_profile(coord, 'mlgpu2'). Run mlgpu2.yaml."— wrong shape: noFIX-LANDEDsignal, references an active lease that doesn't exist while the stand isdown.greatminds stand up --profile mlgpu2. The CLI isSK-only; MAINTAINER has no override.downfor ~3 hours until DEV sent a correctly-shaped wake.This patch makes the canonical body discoverable from the three role docs that need it, and explicitly tells implementers not to route through MAINTAINER.
Design choices
FIX-LANDEDprefix as the semantic marker. Plain English so SK can pattern-match the body without a structured CLI change. A future PR could addgreatminds inbox send --kind fix-landedfor fully structured signalling, but that's a larger surface change and not needed to unblock the immediate documentation gap.grep/diffcheck is enough — the friction is intentional and prevents stray re-deploys of unfixed code if the body is fabricated.stand upaccess_control is canon-gated to SK; documenting that the override doesn't exist closes the speculative escalation path.Test plan
greatminds render-role STAND-KEEPER/TESTER/DEVELOPERincludes the new sections in the rendered bootstrap text.🤖 Generated with Claude Code