Skip to content

Commit 7f9ae0d

Browse files
committed
docs(vrs): require quiet evented coordination
1 parent f96f925 commit 7f9ae0d

2 files changed

Lines changed: 37 additions & 0 deletions

File tree

docs/vrs/requirements.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,18 @@ accepted.
5252
deterministic st2 reconciler keeps declared local processes converged; the
5353
root observes host-local runtime health, diagnoses failures, performs bounded
5454
recovery, and escalates what it cannot resolve.
55+
- **R22 Quiet, evented coordination:** A network using minimal or default
56+
personas remains quiet while useful work proceeds. Agents coordinate only
57+
when a real event requires it: an inbox DING, a durable failure, a true
58+
blocker, a completion or decision handoff, or an explicitly declared named
59+
schedule. Once admitted, coordination is vigilant and outcome-focused until
60+
the need is cleared; chatty status loops and polling are not substitutes.
61+
Ordinary supervisors are exception handlers for failures and truly blocked
62+
work, not continuous managers of healthy work. An intentionally extended
63+
supervisor persona may declare a higher coordination cadence; CoS is one
64+
non-normative example, not a core role that st2 requires, types, or
65+
standardizes. Transport loss never blocks host-local work that does not
66+
require coordination.
5567

5668
### Must preserve delivery and launch behavior
5769

docs/vrs/spec.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,31 @@ positive declaration/template wakes, negative runtime/bus events, bounded
180180
discovery/materialization/PTY queries and writes, continuous-event starvation,
181181
and no-op desired-equals-actual behavior.
182182

183+
## Quiet, evented coordination (R22)
184+
185+
Useful work is silent by default. Presence, status, and durable plan state are
186+
inspectable facts, not invitations to send status messages or poll peers.
187+
Coordination begins only at an understandable event boundary:
188+
189+
| Admitted event | Coordination obligation |
190+
| --- | --- |
191+
| unread inbox message | DING the recipient; process or hand off the request |
192+
| durable failure or true blocker | notify the responsible supervisor; diagnose, recover, or escalate until cleared |
193+
| completion or decision | hand the outcome to the agent or principal that needs it, then become quiet |
194+
| explicitly declared named schedule | perform that named coordination; do not emulate it with an ambient chat or polling loop |
195+
196+
The inbox path follows the source contract in
197+
[DING requirements](./01-ding/requirements.md). A normal supervisor is an
198+
exception handler for failure and truly blocked work, not a continuous manager
199+
of healthy agents. An intentionally extended supervisor persona may declare a
200+
higher coordination cadence. CoS is one non-normative example only: st2 does not
201+
require or type that role, and R22 grants it no standardized authority.
202+
203+
This boundary does not define the still-open schedule grammar in DQ1; it only
204+
requires a named declared event rather than an implicit loop. A transport
205+
partition may delay coordination, but it does not stop independent host-local
206+
work or create a global availability dependency.
207+
183208
## Targeted reconciliation (R19)
184209

185210
`st2 up --materialize-only --task <host.agent.task>` resolves one exact local

0 commit comments

Comments
 (0)