diff --git a/docs/Architecture-Build-Spec.md b/docs/Architecture-Build-Spec.md index a6f8bc6..69b5669 100644 --- a/docs/Architecture-Build-Spec.md +++ b/docs/Architecture-Build-Spec.md @@ -159,13 +159,21 @@ come back to something. Components throughout this document refer to them. arrive is a safe point, with one exception: switching is refused while intents are unresolved (A2). That keeps every pending intent owned by the active work item, so boot reconciliation (A3) stays single-item. -- **The operator can always switch; the agent may switch on its own in one case.** - When the active work item is waiting on the operator (an open gate, a pending - question, or a halt in `AWAIT_INPUT`) and other work items are ready, the agent - switches to one of them and posts a notice naming both items and why it chose - that one. An alert must not sit for hours behind an unanswered prompt. The agent - never switches away from an item that is working. The item it left stays - waiting; switching answers nothing on its behalf. +- **The operator can always switch; the agent may switch on its own in two cases,** + when other work items are ready: + - *The active item is waiting on the operator* (an open gate, a pending question, + or a halt in `AWAIT_INPUT`). An alert must not sit for hours behind an + unanswered prompt. The item it left stays waiting; switching answers nothing + on its behalf. + - *The active item has closed* (completed or abandoned). Ready work should not + sit behind an idle agent until the operator notices. + + Either way, it posts a notice naming both items and why it chose that one. The + agent never switches away from an item that is working. +- **A parked item is ready when the agent can act on it without the operator:** it + has not started yet (a duty finding, a ticket), or intake arrived while it was + parked that answers what it was waiting for (an approval, an answer, a review + comment). An item still waiting on the operator, with nothing new, is not ready. - **The model chooses which ready item to switch to.** This is one of the few judgments it is trusted with outright, because choosing grants nothing: every item still meets its own gates, and a poor choice costs time, not safety. @@ -456,7 +464,7 @@ by replaying the operational trail: |---|---| | `state.transition` | `from`, `to`, `project` | | `intent.begin` / `intent.commit` / `intent.abort` | `intent_id`, `kind` | - | `work_item.switch` | `from`, `to`, `reason`, `chosen_by` (`model` / `fallback` / `operator`) | + | `work_item.switch` | `from` (parked or closed item, or `null`), `to`, `reason`, `chosen_by` (`model` / `fallback` / `operator`) | | `gate.open` / `gate.approve` / `gate.reject` | `gate`, `rev`, `channel` | | `boot.reconcile` | `action`, per-intent verdicts | | `schema.migrate` | `from_version`, `to_version` | @@ -890,8 +898,9 @@ PR_OPEN ### B2. Requirements -- **One active project at a time** (park-and-switch, 0.2). Operator selects it; - other projects stay parked at their last position and resume where they left off. +- **One active project at a time** (park-and-switch, 0.2). The operator selects it, + or the agent switches on its own under 0.2's rules; other projects stay parked at + their last position and resume where they left off. - **Operator commands** (over transport): `use `, `approve`, `reject `, `start milestone `, `status`, `stop` (A4), plus free text during planning (forwarded to the agent as answers).