From d3be30fed64151f101cfd0e337f7f8a3876fe166 Mon Sep 17 00:00:00 2001 From: strategist Date: Wed, 2 Sep 2026 03:06:08 -0400 Subject: [PATCH 1/2] [strategist] planning: phased delivery roadmap for RFC #4002 (re-entrant turn model) Adds docs/rfc-4002-phased-roadmap.md: compatibility contract, Phases 0-3 with measurable gates, and v5/v6 version targeting. Refs #5555, #4002. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: strategist Signed-off-by: sec-check --- docs/rfc-4002-phased-roadmap.md | 71 +++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/rfc-4002-phased-roadmap.md diff --git a/docs/rfc-4002-phased-roadmap.md b/docs/rfc-4002-phased-roadmap.md new file mode 100644 index 000000000..c0a244057 --- /dev/null +++ b/docs/rfc-4002-phased-roadmap.md @@ -0,0 +1,71 @@ +# RFC #4002 Phased Delivery Roadmap — Re-entrant Conversation-as-State Turn Model + +Status: planning (hold-gated) · Owner: strategist · Refs: #4002, #5555, #4000 + +RFC #4002 proposes making the conversation the durable state and each agent +turn a re-entrant, plain function call. It touches the core execution loop of +every agent. This document phases the delivery so partial work cannot land +against the existing model without a migration story. + +## Compatibility contract (must hold in every phase) + +A re-entrant turn MUST be able to reconstruct everything it needs from: + +1. **The conversation** — the ordered operation list (LLM call, tool-approval, + tool-execution, compaction, elicitation, max-turns, retry, subagent-sync, + hooks) persisted outside the process. +2. **A structured turn return** — each turn ends with a serializable result; + no state may be suspended in an in-process coroutine between turns. +3. **The existing session/context model** — until Phase 3, the current + in-process loop remains the default; the re-entrant path is opt-in and + must not change observable behavior for agents that do not opt in. + +Breaking changes to the turn loop require an UPGRADE.md entry (see PR #5559) +before they ship. + +## Phase 0 — Spike and state inventory (exit: written report) + +- Document hive's current agent-loop/state model and enumerate every place + in-process suspended state exists (RFC scope item 1). +- Decide the minimal state envelope for handoff (RFC scope item 3). +- Deliverable: feasibility + migration-cost report attached to #4002. +- **Gate to Phase 1:** report reviewed by a human maintainer; go/no-go + recorded on #4002. + +## Phase 1 — Contributor agents only (opt-in) + +- Prototype one contributor agent as a re-entrant turn function with fully + externalized state (RFC scope item 2). +- Contributor agents are the lowest-blast-radius fleet: sessions are short, + externally driven, and already tolerate reconnects (see #5090 flap history). +- **Gate to Phase 2:** zero regressions in contributor-agent CI for 2 + consecutive weeks; handoff exercised at least once across a process + restart in a live hive. + +## Phase 2 — Background agents (opt-in per agent) + +- Extend to scanner/quality/architect-class background agents behind a + per-agent config flag. +- Integrate #4000 (tool-approval as an explicit, ACMM-gated operation) as a + first-class operation in the turn list — it is an individual operation + within this umbrella model and should not ship separately. +- **Gate to Phase 3:** two full release cycles with the flag on for at least + three agents; durable resume verified across a spoke roll. + +## Phase 3 — Default for all agents + +- Flip the default; retain the legacy loop for one deprecation release. +- Ship operator migration guidance in UPGRADE.md at the major version + boundary where the default changes. + +## Version targeting + +Phases 0–1 are v5-compatible (opt-in, no default change). Phases 2–3 target +v6 unless the v5 GA bar (#5622) explicitly pulls them in. This RFC is not a +v5 GA blocker. + +## Out of scope + +- Queue selection / transport for cross-node handoff (decide in Phase 0). +- State-triggered hooks proposal (separate RFC; same umbrella). + From 88c6c74c0b1a0ca89fbac719ceb673d5fb8937fb Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 2 Sep 2026 21:40:33 -0400 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=96=20docs:=20align=20RFC=204002?= =?UTF-8?q?=20roadmap=20with=20dispatch=20plan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Andy Anderson --- docs/rfc-4002-phased-roadmap.md | 73 ++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 25 deletions(-) diff --git a/docs/rfc-4002-phased-roadmap.md b/docs/rfc-4002-phased-roadmap.md index c0a244057..c09b0f553 100644 --- a/docs/rfc-4002-phased-roadmap.md +++ b/docs/rfc-4002-phased-roadmap.md @@ -23,49 +23,72 @@ A re-entrant turn MUST be able to reconstruct everything it needs from: Breaking changes to the turn loop require an UPGRADE.md entry (see PR #5559) before they ship. -## Phase 0 — Spike and state inventory (exit: written report) +## Already delivered before implementation -- Document hive's current agent-loop/state model and enumerate every place - in-process suspended state exists (RFC scope item 1). -- Decide the minimal state envelope for handoff (RFC scope item 3). -- Deliverable: feasibility + migration-cost report attached to #4002. -- **Gate to Phase 1:** report reviewed by a human maintainer; go/no-go - recorded on #4002. +The investigation work is intentionally separate from rollout: + +- **Stage 1: state inventory shipped.** + [`src/docs/design/agent-turn-model.md`](../src/docs/design/agent-turn-model.md) + documents hive's current agent-loop/state model and the in-process state that + would not survive a process restart. +- **Stage 2: prototype shipped.** The isolated `pkg/turn` prototype demonstrates + a re-entrant `Step` over a serialized conversation envelope with journaled + external effects. It is not wired into the live tmux loop or contributor relay. +- **Step 3: handoff evaluation documented.** + [`src/docs/design/agent-turn-handoff.md`](../src/docs/design/agent-turn-handoff.md) + records the handoff finding: do not add a queue yet; fix/reuse durable + ownership first, and avoid creating another durable state store. + +These shipped artifacts do not change runtime behavior. They are the evidence +base for the opt-in rollout below. ## Phase 1 — Contributor agents only (opt-in) -- Prototype one contributor agent as a re-entrant turn function with fully - externalized state (RFC scope item 2). +- Wire one contributor-agent path to the re-entrant turn envelope behind an + explicit opt-in flag. - Contributor agents are the lowest-blast-radius fleet: sessions are short, externally driven, and already tolerate reconnects (see #5090 flap history). +- Validate the compatibility contract end-to-end: persisted envelope, structured + return, no suspended in-process state between turns, and no observable change + for non-opted-in agents. - **Gate to Phase 2:** zero regressions in contributor-agent CI for 2 - consecutive weeks; handoff exercised at least once across a process - restart in a live hive. + consecutive weeks; handoff exercised at least once across a process restart + in a live hive; no unreconciled ambiguous journal entry may complete as + success. -## Phase 2 — Background agents (opt-in per agent) +## Phase 2 — All background agents (opt-in per agent) -- Extend to scanner/quality/architect-class background agents behind a - per-agent config flag. +- Extend the opt-in path to every background-agent class (scanner, quality, + architect, security, guide, strategist, reviewer, and other non-contributor + scheduled/manager-driven agents). This is not a partial background rollout: + Phase 2 is the point where the whole background fleet has an opt-in path. - Integrate #4000 (tool-approval as an explicit, ACMM-gated operation) as a - first-class operation in the turn list — it is an individual operation - within this umbrella model and should not ship separately. -- **Gate to Phase 3:** two full release cycles with the flag on for at least - three agents; durable resume verified across a spoke roll. + first-class operation in the turn list — it is an individual operation within + this umbrella model and should not ship separately. +- Keep the legacy in-process loop available and default while per-agent opt-in + burns down compatibility issues. +- **Phase-2 success gate:** two full release cycles with the flag enabled for at + least three different background-agent classes, durable resume verified across + a spoke roll, and no increase in failed/duplicated external effects versus the + legacy loop. ## Phase 3 — Default for all agents - Flip the default; retain the legacy loop for one deprecation release. -- Ship operator migration guidance in UPGRADE.md at the major version - boundary where the default changes. +- Ship operator migration guidance in UPGRADE.md at the major-version boundary + where the default changes. +- Remove the legacy loop only after the deprecation release and after rollback + guidance has been exercised on a live spoke. ## Version targeting -Phases 0–1 are v5-compatible (opt-in, no default change). Phases 2–3 target -v6 unless the v5 GA bar (#5622) explicitly pulls them in. This RFC is not a -v5 GA blocker. +The delivered investigation artifacts and Phase 1 are v5-compatible +(documentation/prototype plus opt-in contributor pilot, no default change). +Phases 2–3 target v6 unless the v5 GA bar (#5622) explicitly pulls them in. +This RFC is not a v5 GA blocker. ## Out of scope -- Queue selection / transport for cross-node handoff (decide in Phase 0). +- Queue selection / transport for cross-node handoff until durable ownership is + settled. - State-triggered hooks proposal (separate RFC; same umbrella). -