docs: simplify workflow contract documentation - #102
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 724cc1b645
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| All role TOML files have workspace-write capability, but stage and flags gate writes: Sol is read-only before `SOL_FULL_TAKEOVER`, and a disabled primary remains coord-only permanently. There are at most two children, no child matching the primary model, and spawning occurs only when required by the stage. The primary thread performs atomic flush/close/rename; failure retains prior state, publishes no partial state, and performs no dependent action. This is a declarative host contract, not a runtime API, CLI, or live E2E implementation. | ||
| ## Workflow escalation state machine | ||
|
|
||
| Each task stores its state at `WORKFLOW_STATE_PATH=<ARTIFACT_DIR>/workflow-state.v1.json`, separate from the recovery registry. It records versions, stage, verdict, primary, counters, execution flags, role ownership, and `blocked_reason`. A same-task primary switch preserves these values; a new workflow resets them. |
There was a problem hiding this comment.
On a same-task primary switch, primary_model must change to the newly selected model; only the remaining workflow state is preserved. The PRIMARY_SWITCH transition and its tests explicitly update this field while preserving the others, so saying that the switch preserves all listed values—including primary—can cause a host implementing this documented contract to retain a stale primary and route coordination or the final reply incorrectly. Clarify that the primary is updated while versions, stage, verdict, counters, flags, and ownership are preserved.
Useful? React with 👍 / 👎.
1 participant
Summary
Images are intentionally unchanged because the current diagrams are the latest version.
Validation
npm test— 94/94 passednpm run check— passedgit diff --check— passedRelated: #99