@sjawhar/pi-envoy 11.1.0 → 11.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -7,14 +7,14 @@ description: "Use before your first dispatch command in a session: a message, co
7
7
 
8
8
  Dispatch is a record for the people who decide, never a log of your work.
9
9
 
10
- - Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives each command's rules and an example.
10
+ - Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives its rules and an example.
11
11
  - Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`). Give object and list fields as JSON.
12
12
  - Exit 1 is a refusal, 2 a usage error. A refusal lists each problem: fix them all, then call once.
13
- - `DOC_SERVICE_UNAVAILABLE` means the document is reloading and nothing was written. Wait a few seconds and repeat the call.
13
+ - `DOC_SERVICE_UNAVAILABLE`: the document is reloading, nothing was written; retry in a few seconds.
14
14
 
15
15
  ## Asks and ask blocks
16
16
 
17
- - A question about a design a document records is an ask block (a decision block) at the end of its section, at each phase:
17
+ - A design question a document records is an ask block (a decision block) at the end of its section, at each phase:
18
18
 
19
19
  ```md
20
20
  :::ask{urgency="med"}
@@ -30,37 +30,37 @@ The problem and why it matters. Recommendation: the option and its reason.
30
30
  - An open ask is the request. Do not raise it again in each message.
31
31
  - Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
32
32
  - Answer a person's reply to an open ask with `dispatch comment --reply-to-ask`; `--turn agent` for a note that needs nothing from them.
33
- - When an answer's option and text disagree, the text is the answer.
33
+ - When an answer's option and text disagree, the text wins.
34
34
  - An ask block has a block id, for `doc-edit`, and an ask id, for the ask commands. `dispatch read --ref dispatch://KEY/ask/<id>` takes either.
35
35
  - An ask reaches the issue's assignee. On an unassigned issue, name who must answer.
36
36
 
37
37
  ## Choosing what to work on
38
38
 
39
- - When you finish an issue, take the top ready issue: status `todo`, by priority and then board rank, in each project.
40
- - `todo` means specced and waiting on nothing. An issue that waits goes in `backlog`, saying on what.
39
+ - When you finish an issue, take the top ready one: `todo`, by priority then board rank, per project.
40
+ - `todo` means specced and waiting on nothing; one that waits goes in `backlog`, saying on what.
41
41
  - Hold at most three issues in flight; move the rest to `backlog`, saying where each is.
42
42
  - Never reorder the board: one agent keeps each project's order (`issue-update --before`/`--after`). If the top looks wrong, tell `notifications.role.legion-<project>-controller`.
43
43
 
44
44
  ## Issue status is yours to move
45
45
 
46
- Outside Legion, claim your issue (`dispatch claim`) and move it and your children: `in_progress` at implementation, `testing` on a production-like surface, `needs_review` while its PR waits, and `done` with `--reason` once you drove it in production. Never write the status of an issue with the `legion` label, or under one.
46
+ Outside Legion, claim your issue (`dispatch claim`) and move it and your children: `in_progress` at implementation, `testing` on a production-like surface, `needs_review` while its PR waits, `done` with `--reason` once driven in production. An issue with the `legion` label, or under one: never write its status, and claim it only as a Legion role of its tree, even when its claim reads `· not running`, as a suspended architect's does: taking it takes the tree out of the workflow.
47
47
 
48
- A claim delivers no comments: in the same turn, `dispatch issue-update --route session:<your id>` (clear with `--route ''` on release) or `envoy_subscribe notifications.dispatch.issue.<KEY>.>`. Never route such an issue.
48
+ A claim delivers no comments: that turn, `dispatch issue-update --route session:<your id>` (`--route ''` on release) or `envoy_subscribe notifications.dispatch.issue.<KEY>.>`. Never route such an issue.
49
49
 
50
50
  ## Close what you opened
51
51
 
52
- - An ask you opened is yours until it is answered or resolved. When the answer comes another way, or the design makes it moot, `dispatch resolve-ask` it in the same turn.
52
+ - An ask you opened is yours until answered or resolved. If it is answered another way or made moot, `dispatch resolve-ask` it that turn.
53
53
  - Resolve each open ask a later write names that is no longer needed; retract one a new ask replaces.
54
54
 
55
55
  ## Structure over stream
56
56
 
57
57
  - One issue per deliverable, its content the issue's document. Decisions are asks. A message only announces.
58
- - A message replies to a person, or tells them a change they must know now.
59
- - Text a person must read to decide is a section of the spec. An artifact is a real file.
58
+ - A message replies to a person or tells them what they must know now.
59
+ - Text a person must read to decide belongs in the spec. An artifact is a real file.
60
60
 
61
61
  ## Architecture components
62
62
 
63
- Attach each architectural issue to its components (`--components-json`), the root before you decompose it. Change code and `.dispatch/architecture/<id>.md` in the same review.
63
+ Attach each architectural issue to its components (`--components-json`), the root before decomposing it. Change code and `.dispatch/architecture/<id>.md` in the same review.
64
64
 
65
65
  ## References
66
66
 
@@ -66,6 +66,6 @@ Every topic starts with `notifications.`.
66
66
 
67
67
  - Send to one session with `envoy_send`, to the one session that holds a named duty with a role, and to a group with a team topic.
68
68
  - Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`; never subscribe to a role topic, because the listener forwards a role message to its holder only. A publish returns the live `holder`; an unheld role returns an error. `envoy_role_get(role=...)` finds the holder first.
69
- - For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches only the sessions subscribed when it is published (yours too, when you subscribe, unless you are a serve-port session, which receives it only through a listener run with `ENVOY_SUBSCRIBE_ALL_TOPICS=1` and never its own publish), and is not kept for a session that subscribes later. A topic outside `notifications.` is refused.
69
+ - For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches only the sessions subscribed and connected when it is published (yours too, when you subscribe, unless you are a serve-port session, which receives it only through a listener run with `ENVOY_SUBSCRIBE_ALL_TOPICS=1` and never its own publish), and is not kept for a session that subscribes later or whose connection was down. A topic outside `notifications.` is refused.
70
70
  - How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
71
71
  - In a Legion pane, the plugin claims your role at session start; read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.
@@ -53,7 +53,7 @@ envoy:
53
53
 
54
54
  It depends on where a session takes its deliveries, not on whether the topic is built in or your own.
55
55
 
56
- - A session that holds its own NATS connection (every Oh My Pi session, and a Claude Code one) receives every message published on a subject it subscribes to, whoever sent it: its own publish included, and a subagent's publish to a topic the parent subscribes to. This holds for a topic the stream keeps and for a live team topic alike.
56
+ - A session that holds its own NATS connection (every Oh My Pi session, and a Claude Code one) receives every message published on a subject it subscribes to, whoever sent it: its own publish included, and a subagent's publish to a topic the parent subscribes to. This holds for a topic the stream keeps and for a live team topic alike while it is connected. After an outage they differ: once its connection or subscription is back, the session recovers from the stream what was published meanwhile on its own inbox and on each kept topic it follows, up to 72 hours back, and is shown each message once, marked as published while its connection was down; what a team topic carried meanwhile is gone.
57
57
  - A session the listener delivers to by push, over a serve port (such as the OpenCode plugin), does not receive its own publish, and receives a team topic only through the listener that owns it when that listener runs with `ENVOY_SUBSCRIBE_ALL_TOPICS=1` (the shared hub's listener does not).
58
58
  - A role is not a subject its holder subscribes to: the listener finds the live holder and forwards the message to it, and drops the message when that holder is the message's source session.
59
59
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "11.1.0",
3
+ "version": "11.3.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {