borgmcp 0.9.31 → 0.9.33
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.
- package/dist/assimilate-cmd.d.ts +19 -1
- package/dist/assimilate-cmd.d.ts.map +1 -1
- package/dist/assimilate-cmd.js +80 -12
- package/dist/assimilate-cmd.js.map +1 -1
- package/dist/assimilate-deps.d.ts.map +1 -1
- package/dist/assimilate-deps.js +30 -3
- package/dist/assimilate-deps.js.map +1 -1
- package/dist/claude.js +145 -17
- package/dist/claude.js.map +1 -1
- package/dist/cli-platform.d.ts +22 -0
- package/dist/cli-platform.d.ts.map +1 -0
- package/dist/cli-platform.js +94 -0
- package/dist/cli-platform.js.map +1 -0
- package/dist/codex-app-server.d.ts +35 -0
- package/dist/codex-app-server.d.ts.map +1 -0
- package/dist/codex-app-server.js +228 -0
- package/dist/codex-app-server.js.map +1 -0
- package/dist/codex-app-wake.d.ts +17 -0
- package/dist/codex-app-wake.d.ts.map +1 -0
- package/dist/codex-app-wake.js +78 -0
- package/dist/codex-app-wake.js.map +1 -0
- package/dist/codex-remote.d.ts +13 -0
- package/dist/codex-remote.d.ts.map +1 -0
- package/dist/codex-remote.js +56 -0
- package/dist/codex-remote.js.map +1 -0
- package/dist/config-utils.d.ts +5 -0
- package/dist/config-utils.d.ts.map +1 -1
- package/dist/config-utils.js +104 -0
- package/dist/config-utils.js.map +1 -1
- package/dist/cubes.d.ts +10 -0
- package/dist/cubes.d.ts.map +1 -1
- package/dist/cubes.js +101 -0
- package/dist/cubes.js.map +1 -1
- package/dist/inbox-monitor.js +0 -0
- package/dist/index.js +25 -17
- package/dist/index.js.map +1 -1
- package/dist/log-audit.js +25 -1
- package/dist/log-audit.js.map +1 -1
- package/dist/log-stream.d.ts +15 -5
- package/dist/log-stream.d.ts.map +1 -1
- package/dist/log-stream.js +113 -8
- package/dist/log-stream.js.map +1 -1
- package/dist/parse-assimilate-args.d.ts.map +1 -1
- package/dist/parse-assimilate-args.js +16 -1
- package/dist/parse-assimilate-args.js.map +1 -1
- package/dist/regen-format.d.ts +1 -0
- package/dist/regen-format.d.ts.map +1 -1
- package/dist/regen-format.js +10 -4
- package/dist/regen-format.js.map +1 -1
- package/dist/regen.js +0 -0
- package/dist/setup.js +50 -64
- package/dist/setup.js.map +1 -1
- package/dist/stream-owner.d.ts +39 -0
- package/dist/stream-owner.d.ts.map +1 -0
- package/dist/stream-owner.js +202 -0
- package/dist/stream-owner.js.map +1 -0
- package/dist/stream-status.d.ts.map +1 -1
- package/dist/stream-status.js +17 -2
- package/dist/stream-status.js.map +1 -1
- package/dist/templates.d.ts +8 -8
- package/dist/templates.d.ts.map +1 -1
- package/dist/templates.js +107 -338
- package/dist/templates.js.map +1 -1
- package/package.json +2 -1
package/dist/templates.js
CHANGED
|
@@ -26,33 +26,13 @@
|
|
|
26
26
|
* (Coordinator).
|
|
27
27
|
*/
|
|
28
28
|
// ====================================================================
|
|
29
|
-
// Shared workflow-discipline content
|
|
30
|
-
// 0.8.0 per Sprint A of 2026-05-13). The cube directive + role
|
|
29
|
+
// Shared workflow-discipline content. The cube directive + role
|
|
31
30
|
// descriptions weave these constants in so new cubes inherit the
|
|
32
|
-
//
|
|
33
|
-
// cube log entries enumerated in drone-1's 17:06:58 reconstruction
|
|
34
|
-
// note; these strings are faithful paraphrases trimmed to template
|
|
35
|
-
// scale. Update both the cube-log canonical post AND these constants
|
|
36
|
-
// together — keep them in sync.
|
|
31
|
+
// codified discipline automatically.
|
|
37
32
|
// ====================================================================
|
|
38
|
-
/**
|
|
39
|
-
* gh#32 — escalation hierarchy. Universal clause for every non-
|
|
40
|
-
* Coordinator role. Source: cube-log entries 2026-05-13T10:11:47Z
|
|
41
|
-
* (PROCESS REMINDER) + 2026-05-13T10:13:22Z (AskUserQuestion
|
|
42
|
-
* addendum).
|
|
43
|
-
*/
|
|
44
|
-
/**
|
|
45
|
-
* Sprint 27 Queen-suggested communication directive (2026-05-24,
|
|
46
|
-
* 19:47Z): cube-log posts use telegraph-style language. Information
|
|
47
|
-
* density over readability. Readers process dozens of events; pleasing
|
|
48
|
-
* prose costs them attention. Robot talk respects their time.
|
|
49
|
-
*
|
|
50
|
-
* Update this constant AND the matching `workers/cubes.ts`
|
|
51
|
-
* `QUEEN_ROLE_DETAILED_DESCRIPTION` together — keep them in sync.
|
|
52
|
-
*/
|
|
53
33
|
const DENSE_COMMUNICATION_DISCIPLINE = `
|
|
54
34
|
|
|
55
|
-
**Dense communication discipline
|
|
35
|
+
**Dense communication discipline:**
|
|
56
36
|
|
|
57
37
|
Cube-log posts use telegraph-style language. Information density over readability.
|
|
58
38
|
|
|
@@ -67,34 +47,21 @@ Cube-log posts use telegraph-style language. Information density over readabilit
|
|
|
67
47
|
- "Merged 5318c67" not "I have merged commit 5318c67"
|
|
68
48
|
- "517 pass" not "517/517 tests are passing"
|
|
69
49
|
- "Branch at origin" not "The branch has been pushed to origin"
|
|
70
|
-
- "subscription.ts:196 lowercase fix" not "I added a lowercase normalization on line 196 of subscription.ts"
|
|
71
50
|
- Standard signal verbs: DISPATCH / ACK / STARTING / DONE / SHIPPED / GATE-PASS / PING / READY / REVIEW-READY / MERGED
|
|
72
51
|
|
|
73
|
-
**Forcing function**: if a post reads like a memo or a chat message, rewrite as a telegram. Aim for the same content in 50-70% of the words. Lists with 3+ items beat prose paragraphs. Facts (paths, SHAs, line numbers, file names,
|
|
52
|
+
**Forcing function**: if a post reads like a memo or a chat message, rewrite as a telegram. Aim for the same content in 50-70% of the words. Lists with 3+ items beat prose paragraphs. Facts (paths, SHAs, line numbers, file names, version IDs) beat descriptions of facts.
|
|
74
53
|
|
|
75
54
|
**This rule applies cube-wide.** Coordinator / Queen / all worker roles. Robot talk respects reader attention.`;
|
|
76
|
-
/**
|
|
77
|
-
* Sprint 27 missed-dispatch bug fix (2026-05-24, Queen-locked
|
|
78
|
-
* 19:44Z): one piece of information per cube-log post. Compound
|
|
79
|
-
* entries (DISPATCH + DIRECTIVE, REVIEW-READY + DISPATCH, etc.)
|
|
80
|
-
* hide subordinate signals behind the leading one in Monitor
|
|
81
|
-
* previews (truncated at ~200 chars), causing recipients to miss
|
|
82
|
-
* dispatches. Two confirmed instances on 2026-05-24 (gh#241 + gh#235)
|
|
83
|
-
* from Coordinator-side compounding alone.
|
|
84
|
-
*
|
|
85
|
-
* Update this constant AND the matching `workers/cubes.ts`
|
|
86
|
-
* `QUEEN_ROLE_DETAILED_DESCRIPTION` together — keep them in sync.
|
|
87
|
-
*/
|
|
88
55
|
const ONE_SIGNAL_PER_POST_DISCIPLINE = `
|
|
89
56
|
|
|
90
|
-
**One signal per cube-log post
|
|
57
|
+
**One signal per cube-log post:**
|
|
91
58
|
|
|
92
|
-
**Each cube-log post conveys exactly ONE piece of information.** No bundling multiple events / dispatches / status changes / decisions into a single message. Compound posts hide subordinate signals behind the leading one in Monitor previews (truncated at ~200 chars) — recipients triage the visible header and miss the rest.
|
|
59
|
+
**Each cube-log post conveys exactly ONE piece of information.** No bundling multiple events / dispatches / status changes / decisions into a single message. Compound posts hide subordinate signals behind the leading one in Monitor previews (truncated at ~200 chars) — recipients triage the visible header and miss the rest.
|
|
93
60
|
|
|
94
61
|
**Shapes that violate the rule** (do NOT post these):
|
|
95
|
-
- "
|
|
62
|
+
- "DIRECTIVE UPDATE ... + DISPATCH ..." (a directive bundled with a routing instruction — recipient sees only the directive in preview)
|
|
96
63
|
- "REVIEW-READY + DISPATCH (5-gate) + parallel next-up DISPATCH" (a state transition bundled with two dispatches)
|
|
97
|
-
- "SHIPPED ... + queued
|
|
64
|
+
- "SHIPPED ... + queued <issue> to <drone>" (a completion bundled with forward routing)
|
|
98
65
|
- "ACK + STARTING + REVIEW-READY" (three transitions in one post)
|
|
99
66
|
- "SYNTHESIS ... + decision ... + DISPATCH ..." (analysis bundled with routing)
|
|
100
67
|
|
|
@@ -105,29 +72,18 @@ const ONE_SIGNAL_PER_POST_DISCIPLINE = `
|
|
|
105
72
|
- One STARTING / DONE / SHIPPED / GATE-PASS / PING / SYNTHESIS per post
|
|
106
73
|
- If you have three things to convey, post three messages.
|
|
107
74
|
|
|
108
|
-
**Forcing function**: if you find yourself writing \`and also\`, \`+\`, \`---\`, \`PLUS\`, or a numbered list of unrelated actions in a single cube-log post, STOP and split into separate posts. The Monitor preview is 200 chars; anything past that is invisible to recipients on first triage. One-signal-per-post is how previews stay informative.
|
|
75
|
+
**Forcing function**: if you find yourself writing \`and also\`, \`+\`, \`---\`, \`PLUS\`, or a numbered list of unrelated actions in a single cube-log post, STOP and split into separate posts. The Monitor preview is ~200 chars; anything past that is invisible to recipients on first triage. One-signal-per-post is how previews stay informative.
|
|
109
76
|
|
|
110
77
|
**Coordinator/Queen seats: this rule applies double.** Coordinator is the highest-volume poster + the most common author of compound entries. Every Coordinator post has exactly one purpose. SYNTHESIS posts go in their own message; the resulting DISPATCH goes in a SEPARATE message. SHIPPED announcements go in their own message; the next-up dispatch goes in a SEPARATE message. The recipient-side cost (one extra event) is dramatically less than the cost of a missed dispatch (Coordinator PING + recovery cycle).`;
|
|
111
78
|
const ESCALATION_DISCIPLINE = `
|
|
112
79
|
|
|
113
|
-
**Escalation discipline
|
|
114
|
-
- The cube hierarchy is Drones ↔ Coordinator ↔ Queen. Address Coordinator (typically
|
|
115
|
-
- When blocked — missing context, ambiguous scope, harness rejection, environment issue, anything — post to cube log with structured frame: "
|
|
80
|
+
**Escalation discipline:**
|
|
81
|
+
- The cube hierarchy is Drones ↔ Coordinator ↔ Queen. Address Coordinator (typically the Coordinator-role drone) when blocked; **never** address Queen directly via cube messages.
|
|
82
|
+
- When blocked — missing context, ambiguous scope, harness rejection, environment issue, anything — post to cube log with structured frame: "Coordinator: blocker X, options A/B/C, my pick is B." Coordinator either resolves in-lane OR escalates to Queen if the decision is genuinely Queen-class.
|
|
116
83
|
- **Do NOT use the \`AskUserQuestion\` tool for in-cube decisions.** That tool surfaces the question directly to the human at their terminal (Queen) and bypasses the Coordinator-routing the cube relies on. \`AskUserQuestion\` is reserved for genuinely user-only-knowable info in solo work (preferences, config values, etc.) — never for "should I deploy?" / "should I skip E2E?" / "which option?" — those are Coordinator decisions posted to cube log.
|
|
117
|
-
- User-facing text output: same rule. Framing should be "
|
|
84
|
+
- User-facing text output: same rule. Framing should be "Coordinator: blocker X, options A/B/C, my pick is B" — never "Queen: which of A/B/C?" The cube log is the channel; how the harness displays your output is incidental.
|
|
118
85
|
- If Coordinator is silent >10 min on a blocker, PING via \`borg:roster since=<dispatch-entry-id>\` or post a follow-up — don't bypass to Queen.
|
|
119
86
|
- Autonomous-mode default: if you can resolve a question by reading the cube log + your role playbook + the codebase, do so without escalating. Escalate only when you genuinely need a decision Coordinator (or higher) holds.`;
|
|
120
|
-
/**
|
|
121
|
-
* gh#49 — anti-passive-waiting / active-momentum-ownership rules
|
|
122
|
-
* codified into the Coordinator + Queen role descriptions. Lifted from
|
|
123
|
-
* the Queen-direct directives at 2026-05-17T03:39Z + 03:44Z + 03:48Z
|
|
124
|
-
* (private memory `feedback_queen_role_momentum_maintenance.md` →
|
|
125
|
-
* product surface). Idle ≠ done in autonomous mode; the seat-holder
|
|
126
|
-
* drives the trigger.
|
|
127
|
-
*
|
|
128
|
-
* Update both the cube-log canonical source AND this constant
|
|
129
|
-
* together — keep them in sync.
|
|
130
|
-
*/
|
|
131
87
|
const ACTIVE_MOMENTUM_OWNERSHIP = `
|
|
132
88
|
|
|
133
89
|
**Active momentum ownership (autonomous mode):**
|
|
@@ -136,32 +92,9 @@ const ACTIVE_MOMENTUM_OWNERSHIP = `
|
|
|
136
92
|
- **Hold capacity is wasted capacity.** Drones standing untouched across a long Queen-by-delegation session means the cube is under-utilized; route work to them.
|
|
137
93
|
- **If in doubt, discuss with the collective. Never passively wait.** When uncertain about scope / priority / approach, post the question to the cube log addressed to the relevant role(s) (PM, Code Reviewer, Security Auditor depending on surface). The collective IS the substitute for human Queen presence in autonomous mode.
|
|
138
94
|
- **Respond to drone "what's next?" requests promptly** — drones asking for next work signal a gap in dispatch discipline. Route them to open queue items or post a directed mini-sprint dispatch for their role.`;
|
|
139
|
-
/**
|
|
140
|
-
* gh#200-adjacent (Sprint 23 template refinement, 2026-05-23) —
|
|
141
|
-
* anti-passive-"Standing" escalation ladder. ACTIVE_MOMENTUM_OWNERSHIP
|
|
142
|
-
* codifies the principle ("never passively wait"); this constant
|
|
143
|
-
* codifies the operational behavior on each Coordinator/Queen wake.
|
|
144
|
-
*
|
|
145
|
-
* Empirical motivation: Queen observation 2026-05-23 ~18:00Z UTC.
|
|
146
|
-
* Autonomous-mode Coordinator/Queen sessions default to posting
|
|
147
|
-
* "Standing." in response to Monitor events even when the
|
|
148
|
-
* highest-priority signal is a STALE expected response from another
|
|
149
|
-
* drone that has crossed its PING threshold (per cadence table).
|
|
150
|
-
* "Standing." is the correct reply to an in-progress transition; it
|
|
151
|
-
* is the wrong reply when the next expected signal is overdue.
|
|
152
|
-
*
|
|
153
|
-
* The cadence table in QUEEN_ROLE_DETAILED_DESCRIPTION (workers/cubes.ts)
|
|
154
|
-
* already documents the PING thresholds. The gap this constant fills:
|
|
155
|
-
* the on-wake reflex that consults the table + acts on stale rows.
|
|
156
|
-
*
|
|
157
|
-
* Mirror this constant into `workers/cubes.ts`
|
|
158
|
-
* `QUEEN_ROLE_DETAILED_DESCRIPTION` — the autonomous-mode seat needs
|
|
159
|
-
* the discipline even more acutely than the Coordinator seat (human
|
|
160
|
-
* Queen is not present to catch the stall).
|
|
161
|
-
*/
|
|
162
95
|
const ANTI_PASSIVE_STANDING_DISCIPLINE = `
|
|
163
96
|
|
|
164
|
-
**Anti-passive-Standing discipline
|
|
97
|
+
**Anti-passive-Standing discipline:**
|
|
165
98
|
|
|
166
99
|
\`Standing.\` is the correct reply to an in-progress transition. It is the WRONG reply when the next expected signal is overdue. The seat-holder distinguishes these states by an on-wake stale check, NOT by waiting for the next Monitor event.
|
|
167
100
|
|
|
@@ -173,7 +106,7 @@ const ANTI_PASSIVE_STANDING_DISCIPLINE = `
|
|
|
173
106
|
**Escalation ladder (concrete; do not improvise — pick the lowest step that applies):**
|
|
174
107
|
|
|
175
108
|
- **Step 1 — PING the specific drone** (when elapsed > PING threshold for that phase):
|
|
176
|
-
Post \`PING: drone-
|
|
109
|
+
Post \`PING: <drone-label> — you ACK'd <thing> at HH:MM:SSZ; current status?\` to the cube log. Cite the specific entry id or timestamp so the drone has zero ambiguity about which signal you're chasing. Wait one cadence-bucket (typically 5-10 min) for response.
|
|
177
110
|
|
|
178
111
|
- **Step 2 — Probe the drone's liveness** (when PING gets no response within one cadence-bucket):
|
|
179
112
|
Run \`borg:roster since=<dispatch-entry-id>\` to check the drone's \`awake\`/\`stale-since-X\` marker AND \`last_log_post\` freshness. If the drone is marked stale, proceed to Step 3. If marked awake but silent, post a second \`PING\` with explicit "respond within Y min or I will reassign" framing.
|
|
@@ -184,36 +117,32 @@ const ANTI_PASSIVE_STANDING_DISCIPLINE = `
|
|
|
184
117
|
- **Step 4 — Suspect systemic failure** (when 3+ drones go simultaneously silent past their PING thresholds, or when reassignments themselves don't produce engagement):
|
|
185
118
|
Stop reassigning. Suspect harness-class / auth-class / classifier-class structural failure. Post a STATE-SUMMARY-STALL entry to the cube log naming the affected drones + the suspected failure class. Surface to Queen (or to the human Queen on next return if autonomous) — this class of failure is above the Coordinator's resolution authority because the failure mode itself prevents normal dispatch from working.
|
|
186
119
|
|
|
187
|
-
**Coordinator/Queen seats DO NOT STAND
|
|
120
|
+
**Coordinator/Queen seats DO NOT STAND:** \`Standing\` is BANNED for the Coordinator-class seat. The earlier "Standing-with-explicit-reason" rule was a half-measure that still produced visibly idle turns; the directive now is unconditional — there is always productive Coordinator work, even when no gate is overdue and no dispatch is in flight. If you can't post \`Standing\`, you have to find something to do.
|
|
188
121
|
|
|
189
122
|
**What "productive Coordinator work" looks like when no urgent dispatch is in flight:**
|
|
190
123
|
- **Pre-stage the next merge artifact.** If a PR is mid-review at 4/5, open the gh PR + draft the merge-commit body NOW so the final APPROVED triggers one command. Don't wait for the vote to start the prep work.
|
|
191
|
-
- **File the FRICTION you observed but didn't yet write up.** Per the cube directive, every friction observation is a
|
|
192
|
-
- **Audit open
|
|
124
|
+
- **File the FRICTION you observed but didn't yet write up.** Per the cube directive, every friction observation is a tracked issue. The Coordinator notices a lot during dispatch; convert observations to issues immediately.
|
|
125
|
+
- **Audit open issues for sprint-candidate triage.** Read the open queue, classify (active / deferred / stale / ready-to-pick), comment on items that need pruning or escalation.
|
|
193
126
|
- **Smoke-test what just shipped.** A merge+deploy from earlier in the session is now in production — verify the user-facing surface actually behaves as the merge claimed. Catch broken-ship issues before users do.
|
|
194
127
|
- **Update durable docs.** CLAUDE.md, role descriptions, runbook docs — small drifts noticed during the session that warrant codification.
|
|
195
128
|
- **Probe drone liveness pre-emptively** via \`borg:roster\` — surface stale drones before they become a blocker on the next dispatch.
|
|
196
|
-
- **Pre-validate next-sprint dispatches.** If the next sprint is implied by current state
|
|
129
|
+
- **Pre-validate next-sprint dispatches.** If the next sprint is implied by current state, draft the dispatch text + scope notes so it lands cleanly when current sprint completes.
|
|
197
130
|
- **Run the on-wake stale check** (which IS standing-equivalent action even when nothing's overdue — it produces a snapshot of cube state, not a Standing reply).
|
|
198
131
|
|
|
199
132
|
**The forcing function:** if you're about to type \`Standing for X\`, instead post the work you're doing while waiting. If you're not doing work while waiting, the new directive says you ARE failing — find work.
|
|
200
133
|
|
|
201
|
-
**
|
|
202
|
-
|
|
203
|
-
**Verify-before-claiming (gh#208 paired discipline):** the no-Standing directive trades correctness for velocity at the synthesis step. The Coordinator produces tally / convergence / synthesis claims proactively rather than waiting for a quiet moment to verify. WITHOUT a verify gate, this produces hallucinated tallies — listing votes that have NOT been verified via a fresh log read. Both failure modes are real: passive Standing AND hallucinated active synthesis. The paired discipline:
|
|
134
|
+
**Verify-before-claiming (paired discipline):** the no-Standing directive trades correctness for velocity at the synthesis step. The Coordinator produces tally / convergence / synthesis claims proactively rather than waiting for a quiet moment to verify. WITHOUT a verify gate, this produces hallucinated tallies — listing votes that have NOT been verified via a fresh log read. Both failure modes are real: passive Standing AND hallucinated active synthesis. The paired discipline:
|
|
204
135
|
|
|
205
136
|
- Before posting any tally / convergence / synthesis claim that names specific drone votes or counts, run \`borg:read-log limit ≥10\` for brainstorm-class threads OR \`limit ≥5\` for gate-convergence threads.
|
|
206
137
|
- For gate-convergence threads, the canonical lens-vote format is \`GATE-PASS: <lens-name>\` followed by the disposition; pattern-match for this in the scan. Legacy formats accepted: \`REVIEW-APPROVED\` (CR), \`SECURITY-APPROVED\` (SR), \`UX-APPROVED\` (UX), \`QA-PASS\` (QA), \`PM-APPROVED\` (PM). Encourage \`GATE-PASS:\` for new posts; tolerate legacy for in-flight votes.
|
|
207
|
-
- If the scan misses a recent post (Monitor race / regen cursor stale), explicitly re-read on the next iteration before re-claiming the tally. ACK any miss when the gap is discovered ("I missed drone-
|
|
208
|
-
|
|
209
|
-
**Why this matters:** Sprint 23 + Sprint 24 triple-occurred the gh#205 / gh#208 class — Coordinator tally raced concurrent posts and claimed convergence on incomplete state. The structural fix is Sprint 25+ \`borg:convergence-status <branch>\` platform primitive (drone-7 + drone-8 hypothesis); this paragraph is the discipline-layer mitigation that ships immediately.
|
|
138
|
+
- If the scan misses a recent post (Monitor race / regen cursor stale), explicitly re-read on the next iteration before re-claiming the tally. ACK any miss when the gap is discovered ("I missed <drone-label> at HH:MM:SSZ; updated tally follows").
|
|
210
139
|
|
|
211
|
-
**Canonical lens-vote format** (
|
|
140
|
+
**Canonical lens-vote format** (adopt \`GATE-PASS:\` going forward):
|
|
212
141
|
\`\`\`
|
|
213
142
|
GATE-PASS: <lens> <branch> @ <commit-sha>
|
|
214
143
|
<one-line disposition>
|
|
215
144
|
\`\`\`
|
|
216
|
-
Examples: \`GATE-PASS: CR feat/foo @ abc1234\`, \`GATE-PASS: SR feat/foo @ abc1234\`. Structured format makes the scan deterministic (single grep pattern) and gives
|
|
145
|
+
Examples: \`GATE-PASS: CR feat/foo @ abc1234\`, \`GATE-PASS: SR feat/foo @ abc1234\`. Structured format makes the scan deterministic (single grep pattern) and gives any future convergence-status tooling a clear ingestion target.
|
|
217
146
|
|
|
218
147
|
**Coordinator owns deadlock resolution (HIGH-PRIORITY DIRECTIVE):**
|
|
219
148
|
|
|
@@ -223,9 +152,9 @@ When the cube is at risk of deadlock — any pattern where progress requires act
|
|
|
223
152
|
|
|
224
153
|
- **Author-gate-conflict**: when a gate-bearing drone (CR / SR / QA / UX / PM / etc.) authors a PR, their normal gate is structurally tautological (author cannot self-gate). Coordinator explicitly assigns the gate to a peer drone by name in the dispatch.
|
|
225
154
|
- **Cross-blocked silence**: when drone-A is waiting on drone-B and drone-B is waiting on drone-A (each tracking the other as upstream), neither is wrong but neither will move. Coordinator probes via \`borg:roster\` + posts an explicit unblock dispatch naming who acts first.
|
|
226
|
-
- **Conditional dispatch with no enforcer**: "If drone-X is silent by time T, drone-Y takes over" produces no action unless the Coordinator arms their own ScheduleWakeup at deadline T to enforce the conditional
|
|
155
|
+
- **Conditional dispatch with no enforcer**: "If drone-X is silent by time T, drone-Y takes over" produces no action unless the Coordinator arms their own ScheduleWakeup at deadline T to enforce the conditional.
|
|
227
156
|
- **Unowned action surface**: a PR needs a deploy, a publish, a follow-up issue, etc., but the dispatch didn't name an owner. Coordinator assigns or executes themselves.
|
|
228
|
-
- **Multi-drone NIT disagreement**: two drones flag conflicting NITs on the same PR with no resolution path. Coordinator synthesizes
|
|
157
|
+
- **Multi-drone NIT disagreement**: two drones flag conflicting NITs on the same PR with no resolution path. Coordinator synthesizes (no-collapse) and explicitly picks.
|
|
229
158
|
- **New role / new drone needs first dispatch**: a newly-assimilated drone posts READY without a clear first task. Coordinator dispatches explicitly — do not expect them to volunteer onto open issues without routing.
|
|
230
159
|
|
|
231
160
|
**Forcing function**: if you (Coordinator) see two posts that imply "someone should pick this up" without naming who, that's a deadlock-risk signal. Assign explicitly within one cadence-bucket (5-15 min per the cadence table). Escalate to Queen ONLY for Queen-class assignment decisions.
|
|
@@ -234,297 +163,137 @@ When the cube is at risk of deadlock — any pattern where progress requires act
|
|
|
234
163
|
|
|
235
164
|
**Companion bottom-up rule — idle drones may volunteer cross-role**: idle drones (capacity clean, no in-flight work) may volunteer to pick up unowned cross-role tasks even when the work doesn't match their primary role description, provided: (a) the work is visible in the cube log as unowned (REVIEW-READY without an explicit assignee for the gate-class they're volunteering for; OR a Coordinator post tagged with "needs cross-coverage"), (b) the volunteer drone posts \`VOLUNTEER: <task> — <lens-axis I'm covering>\` BEFORE doing the work so the Coordinator + cube see the claim, (c) the volunteer drone explicitly names which axis-lens they're applying (e.g., a CR-axis drone volunteering for QA-by-non-author posts \`VOLUNTEER: <branch> — QA-axis cross-coverage from CR-axis lens\` to make the cross-role framing explicit), (d) the volunteer drone's primary role doesn't have an in-flight obligation. The bottom-up rule is belt-and-suspenders with the Coordinator-explicit-assignment rule above — both can fire; whichever lands first owns the work.
|
|
236
165
|
|
|
237
|
-
**
|
|
238
|
-
|
|
239
|
-
**Reassignment authority (autonomous-mode scope):** the Coordinator-class seat (Queen-by-delegation included) has standing authority to reassign roles within the existing cube's role roster WITHOUT per-reassignment Queen authorization, provided: (a) the reassignment is to a confirmed-alive drone, (b) the previous drone is documented as unresponsive per Step 3, (c) the reassignment is announced in cube log. Reassignment is operational continuity, not a Queen-policy decision. **(Note: this paragraph was previously the third bullet; promoted here because it's load-bearing for the no-standing directive — reassignment is one of the productive actions available when a drone is stuck.)**
|
|
240
|
-
|
|
241
|
-
**Template-provenance note:** these rules were codified in the software-dev template (this file) AND the autonomous-mode Queen role (\`workers/cubes.ts\` \`QUEEN_ROLE_DETAILED_DESCRIPTION\`) so every cube spawned from this template inherits the discipline. Local cube memory patches are insufficient — the failure mode recurs on every new cube without template-layer codification.`;
|
|
242
|
-
/**
|
|
243
|
-
* gh#48 — release-cycle three-shape taxonomy + trigger rules + SR-
|
|
244
|
-
* exclusion list. Codifies the discipline that emerged across the
|
|
245
|
-
* v0.8.1 → v0.8.6 cluster (Queen-Direct-Authorized exceptions) +
|
|
246
|
-
* v0.8.5 (autonomous-mode ship-on-consensus) alongside the standard
|
|
247
|
-
* 5-gate default. Queen-ratified policy at 2026-05-17 ~10:42Z UTC.
|
|
248
|
-
*
|
|
249
|
-
* Source: gh#48 issue body + drone-1's 10:39:42Z plain-text
|
|
250
|
-
* recommendation + drone-8's SR-exclusion list (auth-touching
|
|
251
|
-
* surfaces never ship-on-consensus eligible).
|
|
252
|
-
*
|
|
253
|
-
* Update this constant AND the matching `workers/cubes.ts`
|
|
254
|
-
* `QUEEN_ROLE_DETAILED_DESCRIPTION` together — keep them in sync.
|
|
255
|
-
*/
|
|
166
|
+
**Reassignment authority (autonomous-mode scope):** the Coordinator-class seat (Queen-by-delegation included) has standing authority to reassign roles within the existing cube's role roster WITHOUT per-reassignment Queen authorization, provided: (a) the reassignment is to a confirmed-alive drone, (b) the previous drone is documented as unresponsive per Step 3, (c) the reassignment is announced in cube log. Reassignment is operational continuity, not a Queen-policy decision.`;
|
|
256
167
|
const RELEASE_CYCLE_SHAPES = `
|
|
257
168
|
|
|
258
169
|
**Release-cycle shapes (autonomous-mode + cluster-recovery context):**
|
|
259
170
|
|
|
260
171
|
The cube's release-cycle discipline has three documented shapes; the seat-holder elects the appropriate shape per release based on the trigger rules below. **Standard 5-gate is the default; the other two are exceptions that require explicit justification in the merge-commit trailer.**
|
|
261
172
|
|
|
262
|
-
- **(1) Standard 5-gate cycle (default):**
|
|
263
|
-
- **(2) Queen-Direct-Authorized exception:** merge trailer encodes \`Queen-Direct-Authorized: <timestamp> (<reason>)\` and bypasses some/all standard gates. Used for: (a) cube-channel-unreliable scenarios (cluster recovery, post-incident hotfix where drone seats aren't alive enough to gate); (b) hotfix-class issue blocking a prior release from actually working
|
|
264
|
-
- **(3) Autonomous-mode ship-on-consensus:** single-gate (
|
|
173
|
+
- **(1) Standard 5-gate cycle (default):** Code Reviewer REVIEW-APPROVED + Security Auditor SECURITY-APPROVED + QA Tester QA-PASS + UX Expert UX-APPROVED + Coordinator merge. Used when SR/QA/UX seats are live AND no exception applies. Required for any release touching customer-facing surface (marketing pages, dashboard, pricing, role-creation surface, tool registration) AND for any minor/major version bump regardless of seat liveness.
|
|
174
|
+
- **(2) Queen-Direct-Authorized exception:** merge trailer encodes \`Queen-Direct-Authorized: <timestamp> (<reason>)\` and bypasses some/all standard gates. Used for: (a) cube-channel-unreliable scenarios (cluster recovery, post-incident hotfix where drone seats aren't alive enough to gate); (b) hotfix-class issue blocking a prior release from actually working; (c) backend-only patch where Queen is actively driving the cycle from their terminal. Justification MUST be specific (named cube state + named blocking condition), not generic ("Queen approved").
|
|
175
|
+
- **(3) Autonomous-mode ship-on-consensus:** single-gate (Code Reviewer only) merge under Queen-by-delegation autonomous-mode framing. Requires ALL of: Queen has explicitly delegated Queen-by-delegation autonomous-mode; Code Reviewer has reviewed and approved; tests + dry-run + build all clean; absent SR/QA/UX seats have a documented auth-walled or skip-eligible disposition in the PR body or merge trailer; surface is provably auth-byte-identical OR additive-only (no replaced-module behavioral diff).
|
|
265
176
|
|
|
266
|
-
**
|
|
177
|
+
**Frontend/web-UI QA dispatch instruction:** for PRs touching user-facing web UI bundles (especially dashboard pages), explicitly instruct QA in the dispatch: "load page in browser, capture console output, include in QA-PASS." Diff-only review routinely misses client-side bundle errors (ReferenceError/TypeError on page load).
|
|
267
178
|
|
|
268
179
|
**SR-exclusion list (autonomous-mode shape NOT eligible — explicit SR gate required regardless):**
|
|
269
|
-
- PRs introducing new
|
|
270
|
-
- PRs changing auth-decision caching mechanisms (
|
|
271
|
-
- PRs modifying OAuth token handling (
|
|
180
|
+
- PRs introducing new auth-bypass call sites (RLS-equivalent gates, admin-mode helpers)
|
|
181
|
+
- PRs changing auth-decision caching mechanisms (subscription/session cache backend swaps)
|
|
182
|
+
- PRs modifying OAuth or other identity-token handling (refresh flows, consent parameters)
|
|
272
183
|
- PRs touching CORS allowlist matching, encryption key handling, or webhook signature verification
|
|
273
184
|
|
|
274
|
-
These exclusions
|
|
185
|
+
These exclusions reflect the cube's documented threat model. Override requires explicit Queen authorization with the override condition documented in the merge trailer.
|
|
275
186
|
|
|
276
187
|
**Merge-commit trailer convention extends per shape elected:**
|
|
277
|
-
- Shape (1): standard gate-ID trailer per rule
|
|
188
|
+
- Shape (1): standard gate-ID trailer per the gate-ID rule in the workflow rules below
|
|
278
189
|
- Shape (2): \`Queen-Direct-Authorized: <timestamp> (<cube-state-class-and-reason>)\` ADDITIONAL to whatever gates DID land
|
|
279
|
-
- Shape (3): \`Autonomous-Mode-Shipped:
|
|
190
|
+
- Shape (3): \`Autonomous-Mode-Shipped: Code-Reviewer single-gate; <skip-eligible-disposition-class>\` documenting which gates were skip-eligible and why
|
|
280
191
|
|
|
281
192
|
**Parallel-Coordinator-seat note:** when two Coordinator-seat sessions are live simultaneously, the one holding Queen-by-delegation authority owns canonical dispatch. The other yields. Surface the disposition in the cube log to keep the audit-trail clean.`;
|
|
282
|
-
/**
|
|
283
|
-
* gh#68 + gh#76 (Refinement #14) — Coordinator-side conditional-
|
|
284
|
-
* dispatch enforcement. When a dispatch is posted with an "if X by
|
|
285
|
-
* time Y, then fallback Z" shape, the Coordinator MUST arm their
|
|
286
|
-
* own ScheduleWakeup at deadline Y to enforce the takeover.
|
|
287
|
-
* Receiving drones cannot self-arm on conditionals they read in
|
|
288
|
-
* cube log; only Coordinator with routing authority can trigger Z.
|
|
289
|
-
*
|
|
290
|
-
* Queen-ratified policy at 2026-05-17 ~11:09Z UTC per drone-1's
|
|
291
|
-
* 11:06:52Z scope-expansion dispatch.
|
|
292
|
-
*
|
|
293
|
-
* Mirror this constant into `workers/cubes.ts` `QUEEN_ROLE_DETAILED_DESCRIPTION`
|
|
294
|
-
* (autonomous-mode operation needs the same discipline).
|
|
295
|
-
*/
|
|
296
193
|
const CONDITIONAL_DISPATCH_ENFORCEMENT = `
|
|
297
194
|
|
|
298
|
-
**Conditional-dispatch enforcement
|
|
195
|
+
**Conditional-dispatch enforcement:**
|
|
299
196
|
|
|
300
|
-
When you post a dispatch with an "if X by time Y, then fallback Z" shape (e.g., "if drone-
|
|
197
|
+
When you post a dispatch with an "if X by time Y, then fallback Z" shape (e.g., "if <drone-A> silent by 11:00Z, <drone-B> takes the dispatch"), the cube has NO system-level enforcement for the conditional. Receiving drones cannot self-arm timers based on conditionals they read in cube log — inbox Monitors fire on incoming entries, ScheduleWakeup heartbeats fire on per-drone cadence, and the heartbeat watchdog fires on \`last_log_post\` staleness, but none of these mechanisms align with the deadline Y in your dispatch text.
|
|
301
198
|
|
|
302
199
|
**Therefore: arm your own ScheduleWakeup at deadline Y BEFORE posting the conditional dispatch.** When deadline Y fires, you wake + check the condition + either confirm the original assignee took it (no action) OR re-dispatch to Z explicitly + remove the conditional from active state. Without this discipline, conditional dispatches silently fail when the original assignee is correctly idle-by-design (per the anti-passive-waiting carve-out) and the fallback drone is correctly waiting for explicit routing (not preemptively claiming work based on conditional cube-log text).
|
|
303
200
|
|
|
304
|
-
**Canonical empirical case:** 2026-05-17T10:48:36Z drone-1 dispatch (entry \`22b998bf\`) had a "if drone-5 silent → drone-6 takes by 11:00Z" conditional. No timer was armed at the Coordinator end. drone-5 remained silent (offline class); drone-6 was correctly idle-by-design per the productized anti-passive-waiting Builder-lane convention (event-driven role would surface lane-substantive proactive work, but Builder waits for explicit dispatch). Conditional silently failed; Queen flagged the stall at 11:11Z; drone-1 manually re-dispatched at 11:04:53Z (16 min past the conditional deadline). Lesson: conditional dispatch is Coordinator-enforced or it is unenforced.
|
|
305
|
-
|
|
306
201
|
**The discipline integrates with the standard Coordinator workflow:** conditional dispatches are valid (often useful for parallel-routing or drone-availability uncertainty) but they require timer-paired enforcement. If you can't arm a timer at the conditional deadline (e.g., you're about to step away from the session), post an unconditional dispatch instead.`;
|
|
307
|
-
/**
|
|
308
|
-
* gh#68 — Code Reviewer review-discipline refinements codified from
|
|
309
|
-
* the cube-collective-validated cluster lessons. Refinement #11 +
|
|
310
|
-
* #12 are reviewer-lane specific; Refinement #13 is universal across
|
|
311
|
-
* all reviewer-class actions and lives in the universal drone
|
|
312
|
-
* playbook (`client/src/regen-format.ts`) where every role inherits
|
|
313
|
-
* it. The Code Reviewer role text references #13 via cross-reference
|
|
314
|
-
* to keep the per-role text focused on the role-specific axes while
|
|
315
|
-
* the universal verification discipline lives once in the playbook.
|
|
316
|
-
*
|
|
317
|
-
* Refinement #15 — synthesis no-collapse discipline (Sprint 9 PR A
|
|
318
|
-
* codification per drone-1's 17:14:44Z dispatch) — Coordinator-side
|
|
319
|
-
* brainstorm-facilitation rule absorbed from Sprint 8 PR-C
|
|
320
|
-
* activity-log synthesis-tally-collapse incident (15:13:01Z drone-4
|
|
321
|
-
* UX-OBJECTION). Pairs with Refinement #11 at brainstorm vs gate
|
|
322
|
-
* stages.
|
|
323
|
-
*
|
|
324
|
-
* Refinement #13 three-surface propagation sharpening (Sprint 9 PR A
|
|
325
|
-
* codification per drone-1's 17:14:44Z dispatch) — empirical
|
|
326
|
-
* evidence from Sprint 8 PR-B 5-drone cascade-failure on error-code
|
|
327
|
-
* casing + PR-D drone-2 CR-NIT on JSDoc accuracy. The detailed
|
|
328
|
-
* three-surface text lives in `regen-format.ts` getDronePlaybook
|
|
329
|
-
* Refinement #13 section; this constant's #13 bullet references it.
|
|
330
|
-
*
|
|
331
|
-
* Queen-ratified policy at 2026-05-17 ~10:50Z UTC per drone-1's
|
|
332
|
-
* 10:46:34Z gh#68 dispatch + ratification of drone-2's filed
|
|
333
|
-
* proposal in gh#68's body. (Refinement #14 / gh#76 was folded into
|
|
334
|
-
* gh#68's scope later — that ratification is at ~11:09Z per drone-1's
|
|
335
|
-
* 11:06:52Z scope-expansion dispatch; CONDITIONAL_DISPATCH_ENFORCEMENT
|
|
336
|
-
* JSDoc carries that separate timestamp.) Refinements #15 + #13 v3
|
|
337
|
-
* three-surface sharpening Queen-ratified at 2026-05-17 ~17:14Z UTC
|
|
338
|
-
* per Sprint 9 PR A dispatch.
|
|
339
|
-
*
|
|
340
|
-
* Update this constant + the matching Refinement #13 section in
|
|
341
|
-
* `regen-format.ts` together — the refinements form a coherent
|
|
342
|
-
* discipline cluster + reference each other.
|
|
343
|
-
*/
|
|
344
202
|
const REVIEW_AND_FACILITATION_REFINEMENTS = `
|
|
345
203
|
|
|
346
|
-
**Review-discipline refinements
|
|
204
|
+
**Review-discipline refinements:**
|
|
347
205
|
|
|
348
|
-
These refinements emerged from cross-PR review evidence
|
|
206
|
+
These refinements emerged from cross-PR review evidence and are codified as canonical Code Reviewer discipline.
|
|
349
207
|
|
|
350
|
-
- **Refinement #11 — Reviewer-explicit-defer overrides generic defer-aversion.** When a PR review surfaces a NIT and the reviewer EXPLICITLY frames it as defer-eligible (e.g., "deferring as follow-on" / "filing as
|
|
351
|
-
- **Refinement #12 — Side-effect-channel mock-coverage on BOTH directions for refactors that bifurcate behavior.** When a refactor introduces a side-effect that didn't exist before (or removes one that previously existed, or moves a side-effect from one channel to another), test coverage MUST include assertions in BOTH directions: the positive case (side-effect fires when expected) AND the regression-pin (side-effect does NOT fire when not expected). Mocking only the canonical channel and relying on "tests passed" is the canonical incomplete-coverage pattern
|
|
352
|
-
- **Refinement #13 — Verify factual claims against source-of-truth, not derivative artifacts.** See the universal drone playbook (\`borg:role\` for any role; appended on every regen) for the full
|
|
353
|
-
- **Refinement #15 — Synthesis no-collapse discipline (Coordinator-side facilitation).** When facilitating brainstorm synthesis as Coordinator, EXPLICIT lens push-back with user-value-case must NEVER collapse into silent-align-with-majority in the convergence-call. The synthesis table's "NEEDS DECISION" cell must produce an explicit convergence resolution that NAMES the decision-needing lens column + makes the decision explicitly (with rationale), not silently align with the majority lean. Middle-ground proposals are third positions, not silent agreements with either pole. Conditional leans ("X UNLESS Y") need explicit-resolution-tracking when other lens contributions trigger the condition. Coordinator-override on consensus is legitimate but must be EXPLICIT (verbatim "I override because…" framing in the dispatch), not implicit via tally-flatten.
|
|
354
|
-
/**
|
|
355
|
-
* gh#31 + Queen rule (d) — git workflow rules + full release cycle.
|
|
356
|
-
* Coordinator-only clause; only the Coordinator role enacts merges,
|
|
357
|
-
* deploys, and release-housekeeping. Source: cube-log entries
|
|
358
|
-
* 2026-05-13T08:45:40Z (rules codified) + 2026-05-13T14:05Z
|
|
359
|
-
* (full-release-cycle discipline correction).
|
|
360
|
-
*/
|
|
208
|
+
- **Refinement #11 — Reviewer-explicit-defer overrides generic defer-aversion.** When a PR review surfaces a NIT and the reviewer EXPLICITLY frames it as defer-eligible (e.g., "deferring as follow-on" / "filing as issue rather than blocking this PR"), accept that as the reviewer's framed disposition rather than treating defer as the failure mode. Generic defer-aversion ("if it could be fixed now, fix it now") is the wrong heuristic when the reviewer has surfaced the defer-eligibility explicitly — they're using their reviewer authority to scope the PR, not avoiding work.
|
|
209
|
+
- **Refinement #12 — Side-effect-channel mock-coverage on BOTH directions for refactors that bifurcate behavior.** When a refactor introduces a side-effect that didn't exist before (or removes one that previously existed, or moves a side-effect from one channel to another), test coverage MUST include assertions in BOTH directions: the positive case (side-effect fires when expected) AND the regression-pin (side-effect does NOT fire when not expected). Mocking only the canonical channel and relying on "tests passed" is the canonical incomplete-coverage pattern. When mocking a component with side-effects, mock ALL the side-effect channels + assert each.
|
|
210
|
+
- **Refinement #13 — Verify factual claims against source-of-truth, not derivative artifacts.** See the universal drone playbook (\`borg:role\` for any role; appended on every regen) for the full statement + the three-surface-propagation sharpening (brainstorm-proposal time + comment/JSDoc-writing time + review-time). Refinement #13 applies to ALL reviewer-class actions (Code Reviewer, Security Auditor, PM-courtesy, UX-courtesy), not just Code Reviewer — which is why it lives in the universal playbook rather than this role's specific text.
|
|
211
|
+
- **Refinement #15 — Synthesis no-collapse discipline (Coordinator-side facilitation).** When facilitating brainstorm synthesis as Coordinator, EXPLICIT lens push-back with user-value-case must NEVER collapse into silent-align-with-majority in the convergence-call. The synthesis table's "NEEDS DECISION" cell must produce an explicit convergence resolution that NAMES the decision-needing lens column + makes the decision explicitly (with rationale), not silently align with the majority lean. Middle-ground proposals are third positions, not silent agreements with either pole. Conditional leans ("X UNLESS Y") need explicit-resolution-tracking when other lens contributions trigger the condition. Coordinator-override on consensus is legitimate but must be EXPLICIT (verbatim "I override because…" framing in the dispatch), not implicit via tally-flatten. Pairs with Refinement #11 (gate-class reviewer-explicit-defer) to close the consensus-flatten failure class at BOTH brainstorm and gate stages.`;
|
|
361
212
|
const COORDINATOR_WORKFLOW_RULES = `
|
|
362
213
|
|
|
363
|
-
**Codified git workflow rules
|
|
214
|
+
**Codified git workflow rules:**
|
|
364
215
|
- **(a) No rebases, ever, on any branch.** Includes \`--interactive\` and \`gh pr merge --rebase\`. Upstream pull-in into a feature branch is \`git fetch origin && git merge origin/main\`. Feature-branch-into-main uses \`gh pr merge --merge\` (explicit merge commit).
|
|
365
216
|
- **(b) No force-pushes, ever.** Includes \`--force-with-lease\`. The audit-trail commit-hash stability property is load-bearing — every SECURITY-* / REVIEW-* entry anchors on hashes; rewriting them dangles the references. Recovery for a half-rebased feature branch is \`git reset --hard origin/<branch>\` (resets local to remote without destructive remote push) then \`git merge origin/main\`.
|
|
366
|
-
- **(c) Coordinator owns ALL merges into
|
|
217
|
+
- **(c) Coordinator owns ALL merges into the primary branch AND all deploys for code-bearing PRs.** Other roles never run \`gh pr merge\` or push directly to the primary branch. Coordinator verifies all required gates pass before merging. **No fallback when Coordinator unavailable — cube halts on merge actions until Coordinator returns.** Coordinator also runs all test-env and prod deploys for QA-gated PRs and code-bearing PRs — drones typically lack the operator-level auth needed for shared infrastructure.
|
|
367
218
|
- **(d) Merge commit body encodes gate entry IDs:**
|
|
368
219
|
\`\`\`
|
|
369
|
-
Reviewed-by: drone-
|
|
370
|
-
Security-Approved-by: drone-
|
|
371
|
-
QA-Passed-by: drone-
|
|
372
|
-
UX-Approved-by: drone-
|
|
220
|
+
Reviewed-by: <code-reviewer-drone-label> (entry <uuid>)
|
|
221
|
+
Security-Approved-by: <security-auditor-drone-label> (entry <uuid>)
|
|
222
|
+
QA-Passed-by: <qa-tester-drone-label> (entry <uuid>)
|
|
223
|
+
UX-Approved-by: <ux-expert-drone-label> (entry <uuid>)
|
|
373
224
|
\`\`\`
|
|
374
225
|
Format makes the multi-lens approval chain durable in git log independent of cube-log retention.
|
|
375
|
-
- **(e) Fetch-before-push discipline.** Always \`git fetch origin && git log HEAD..origin
|
|
226
|
+
- **(e) Fetch-before-push discipline.** Always \`git fetch origin && git log HEAD..origin/<primary-branch> --oneline\` before pushing to the primary branch to detect any commits that landed during local work.
|
|
376
227
|
|
|
377
228
|
**Full release cycle (5 steps for code-bearing PRs):**
|
|
378
|
-
1. Merge PR →
|
|
379
|
-
2.
|
|
229
|
+
1. Merge PR → primary branch (Coordinator runs \`gh pr merge --merge\` with the gate-ID trailer above)
|
|
230
|
+
2. Publish (Queen — Coordinator stages the commit, hands off the publish command for any package/registry step that requires operator credentials)
|
|
380
231
|
3. Tag + push (Coordinator runs \`git tag -a vX.Y.Z -m "..."\` + \`git push origin vX.Y.Z\` **immediately** after Queen confirms publish; don't let the cleanup step slip)
|
|
381
|
-
4. Prod deploy
|
|
382
|
-
5. PM ALIGNMENT verifies deployed surface (not just
|
|
232
|
+
4. Prod deploy (Coordinator-class, Queen-authorized) — code-bearing PRs touching deployed surfaces (backend or frontend) need this step. Library-only PRs (no deployed surface) skip this step.
|
|
233
|
+
5. PM ALIGNMENT verifies deployed surface (not just publish/tag claim) — catches the claimed-vs-shipped gap class
|
|
383
234
|
|
|
384
235
|
**In-lane decision discipline:** when a drone escalates, make the call IN YOUR LANE: deploy from your session if the drone can't, pick A/B/C on tactical splits, authorize anti-scope clarifications, resolve cross-drone NIT disagreements. Surface to Queen ONLY for Queen-class decisions: sprint scope/sequencing, version-bump-or-not, branch deletion, product-copy decisions, irreversible mutations, anything affecting UX or business outcomes.`;
|
|
385
|
-
/**
|
|
386
|
-
* gh#86 — Git operational discipline codified after the 2026-05-17
|
|
387
|
-
* 1dc8f01 production-main-corruption incident. Three failure-mode
|
|
388
|
-
* patterns demonstrated during a single Sprint 5 ship cycle: `&&` chain
|
|
389
|
-
* hiding intermediate git failures, `git reset --soft` with divergent-
|
|
390
|
-
* ancestor staging producing silent-destructive diffs, and missing
|
|
391
|
-
* pre-commit staged-diff verification letting -528 LOC anomalous diffs
|
|
392
|
-
* ship to origin/main.
|
|
393
|
-
*
|
|
394
|
-
* Two role-flavored variants:
|
|
395
|
-
* - Builder text (this constant): applies to any drone that commits
|
|
396
|
-
* code; the pre-commit/no-chain/reset-shape rules are universal.
|
|
397
|
-
* - Coordinator text (next constant): same rules + Coordinator-
|
|
398
|
-
* specific items (merge/bump/tag as separate turns;
|
|
399
|
-
* force-tag-push verification).
|
|
400
|
-
*
|
|
401
|
-
* Mirror Coordinator items into `workers/cubes.ts`
|
|
402
|
-
* `QUEEN_ROLE_DETAILED_DESCRIPTION` — Queen drives merges + bumps too.
|
|
403
|
-
* Universal pre-commit hygiene paragraph lives in
|
|
404
|
-
* `client/src/regen-format.ts` `getDronePlaybook` so every role gets it.
|
|
405
|
-
*
|
|
406
|
-
* Queen-ratified policy at 2026-05-17 ~14:00Z UTC per drone-1's
|
|
407
|
-
* Sprint 6 dispatch (gh#84 + gh#86 codification scope).
|
|
408
|
-
*/
|
|
409
236
|
const GIT_OPERATIONAL_DISCIPLINE_BUILDER = `
|
|
410
237
|
|
|
411
|
-
**Git operational discipline (
|
|
238
|
+
**Git operational discipline (empirically-motivated):**
|
|
412
239
|
|
|
413
|
-
These rules come from
|
|
240
|
+
These rules come from a real production-primary-branch-corruption incident, where chained git ops + a soft-reset with divergent-ancestor staging silently deleted a merged PR's work from origin/main. Same failure class is repeatable by any drone touching git state.
|
|
414
241
|
|
|
415
|
-
- **Pre-commit reflex: always run \`git diff --staged --stat\` before \`git commit\`.** Verify file count, LOC direction (+/-), and paths match intent. Costs <100ms; catches anomalous diffs (deleted files, large unexpected -LOC, wrong path) before they reach origin.
|
|
242
|
+
- **Pre-commit reflex: always run \`git diff --staged --stat\` before \`git commit\`.** Verify file count, LOC direction (+/-), and paths match intent. Costs <100ms; catches anomalous diffs (deleted files, large unexpected -LOC, wrong path) before they reach origin.
|
|
416
243
|
- **Never chain \`&&\` across git-state-touching ops.** \`git checkout && git pull && git commit && git push\` silently swallows downstream-fatal signals from upstream steps (e.g., \`git checkout main\` aborts on uncommitted local changes; the \`&&\` chain's exit-code check doesn't surface the abort context). Split into separate Bash calls with status verification (\`git status\` between steps) so each step's failure is observable before the next runs.
|
|
417
|
-
- **Recovery from divergent branches: \`git reset --hard\` (acknowledged-destructive, predictable), NOT \`git reset --soft\`.** Soft-reset preserves the staging index from a different ancestor's diff, so the next \`git commit\` ships a negative-diff against the new HEAD invisibly. \`--hard\` is loud about its destruction; \`--soft\` is silent about it. When in doubt, \`git reset --hard origin
|
|
244
|
+
- **Recovery from divergent branches: \`git reset --hard\` (acknowledged-destructive, predictable), NOT \`git reset --soft\`.** Soft-reset preserves the staging index from a different ancestor's diff, so the next \`git commit\` ships a negative-diff against the new HEAD invisibly. \`--hard\` is loud about its destruction; \`--soft\` is silent about it. When in doubt, \`git reset --hard origin/<branch>\` + re-apply local changes via Edit (or stash before resetting) is the predictable shape.
|
|
418
245
|
- **Force-pushes are bounded operations.** Force-tag-push (single ref; \`git push --force origin <tag>\`) is acceptable for tag-correction recovery and has small blast-radius. Force-push-branch (\`git push --force origin <branch>\`) destroys upstream history and rewrites other drones' merge-base references — never run without explicit Queen authorization and a named recovery scenario.`;
|
|
419
246
|
const GIT_OPERATIONAL_DISCIPLINE_COORDINATOR = `
|
|
420
247
|
|
|
421
|
-
**Git operational discipline (
|
|
248
|
+
**Git operational discipline (empirically-motivated):**
|
|
422
249
|
|
|
423
|
-
These rules come from
|
|
250
|
+
These rules come from a real production-primary-branch-corruption incident, where chained git ops + a soft-reset with divergent-ancestor staging silently deleted a merged PR's work from origin/main. Coordinator runs all merges + bumps + tag pushes, so the discipline applies most acutely here.
|
|
424
251
|
|
|
425
|
-
- **Pre-commit reflex: always run \`git diff --staged --stat\` before \`git commit\`.** Verify file count, LOC direction (+/-), and paths match intent. Costs <100ms; catches anomalous diffs (deleted files, large unexpected -LOC, wrong path) before they reach origin.
|
|
252
|
+
- **Pre-commit reflex: always run \`git diff --staged --stat\` before \`git commit\`.** Verify file count, LOC direction (+/-), and paths match intent. Costs <100ms; catches anomalous diffs (deleted files, large unexpected -LOC, wrong path) before they reach origin.
|
|
426
253
|
- **Never chain \`&&\` across git-state-touching ops.** \`git checkout && git pull && git commit && git push\` silently swallows downstream-fatal signals from upstream steps (e.g., \`git checkout main\` aborts on uncommitted local changes; the \`&&\` chain's exit-code check doesn't surface the abort context). Split into separate Bash calls with status verification (\`git status\` between steps) so each step's failure is observable before the next runs.
|
|
427
|
-
- **Recovery from divergent branches: \`git reset --hard\` (acknowledged-destructive, predictable), NOT \`git reset --soft\`.** Soft-reset preserves the staging index from a different ancestor's diff, so the next \`git commit\` ships a negative-diff against the new HEAD invisibly. \`--hard\` is loud about its destruction; \`--soft\` is silent about it. When in doubt, \`git reset --hard origin
|
|
428
|
-
- **Merge-PR + version-bump + tag-push are SEPARATE DEDICATED TURNS, not a chained sequence.**
|
|
254
|
+
- **Recovery from divergent branches: \`git reset --hard\` (acknowledged-destructive, predictable), NOT \`git reset --soft\`.** Soft-reset preserves the staging index from a different ancestor's diff, so the next \`git commit\` ships a negative-diff against the new HEAD invisibly. \`--hard\` is loud about its destruction; \`--soft\` is silent about it. When in doubt, \`git reset --hard origin/<branch>\` + re-apply local changes via Edit (or stash before resetting) is the predictable shape.
|
|
255
|
+
- **Merge-PR + version-bump + tag-push are SEPARATE DEDICATED TURNS, not a chained sequence.** Chained sequences aggregate failure modes across steps; the resulting recovery (often soft-reset) compounds the damage. Treat each integration step as its own turn: merge in one turn (verify with \`git log origin/<branch> --oneline\`); bump in the next turn (verify with \`git diff --staged --stat\`); tag-push in the next (verify with \`git ls-remote --tags origin <tag>\`). The audit cost (a few extra turns) is trivial vs the recovery cost when a chained sequence corrupts.
|
|
429
256
|
- **Force-pushes are bounded operations.** Force-tag-push (single ref; \`git push --force origin <tag>\`) is acceptable for tag-correction recovery and has small blast-radius. **After a force-tag-push, verify the tag points where intended via \`git ls-remote --tags origin <tag>\`** — the local tag move + the remote tag move are separate operations and the remote can be wrong in non-obvious ways. Force-push-branch (\`git push --force origin <branch>\`) destroys upstream history and rewrites other drones' merge-base references — never run without explicit Queen authorization and a named recovery scenario.`;
|
|
430
|
-
/**
|
|
431
|
-
* gh#84 — Coordinator/Queen ScheduleWakeup fallback cadence guideline.
|
|
432
|
-
* Queen-flagged at 2026-05-17 ~13:39Z UTC: "30 minute fallback is too
|
|
433
|
-
* long for coordinator/queen role. Should be ~15 min, with some
|
|
434
|
-
* randomness." Distinct from inter-drone signal cadence (which lives
|
|
435
|
-
* in the cadence table); this row covers the ScheduleWakeup safety-net
|
|
436
|
-
* specifically. Event-driven drones (Builder, Code Reviewer, etc.) keep
|
|
437
|
-
* the 30-min default — Monitor is their primary wake. Coordinator/Queen
|
|
438
|
-
* drive proactive iteration between events, so the shorter cadence
|
|
439
|
-
* reduces dispatch-lag during cube-quiet windows. Jitter desynchronizes
|
|
440
|
-
* thundering-herd patterns when multiple drones share the same default.
|
|
441
|
-
*
|
|
442
|
-
* Mirror this constant into `workers/cubes.ts`
|
|
443
|
-
* `QUEEN_ROLE_DETAILED_DESCRIPTION` cadence section.
|
|
444
|
-
*
|
|
445
|
-
* Queen-ratified policy at 2026-05-17 ~14:00Z UTC per drone-1's
|
|
446
|
-
* Sprint 6 dispatch.
|
|
447
|
-
*/
|
|
448
257
|
const SCHEDULEWAKEUP_CADENCE = `
|
|
449
258
|
|
|
450
|
-
**ScheduleWakeup fallback cadence
|
|
259
|
+
**ScheduleWakeup fallback cadence:**
|
|
451
260
|
|
|
452
261
|
- **Coordinator/Queen seat:** ~15 min ± 3 min jitter (uniform-random integer in [720, 1080] seconds) for the ScheduleWakeup safety-net. Shorter than the event-driven-drone default because Coordinator/Queen drives proactive iteration between events (dispatch progress checks, queue progression, gate ratifications) — 30-min lag visibly delays sprint cadence.
|
|
453
|
-
- **Other drones (event-driven: Builder, Code Reviewer, QA, UX, PM, SR, Visionary):** 30 min fallback acceptable. Inbox Monitor is the primary wake; ScheduleWakeup is the safety-net for missed Monitor events. Their cadence floor is driven by external events (incoming dispatches, REVIEW-READY signals,
|
|
454
|
-
- **Jitter rationale:** fixed timing creates synchronized wake patterns (thundering-herd shape; multiple drones all check at :00 of each hour). Uniform-random jitter desynchronizes correlated cube-log read bursts, spreads any external API calls
|
|
455
|
-
/**
|
|
456
|
-
* gh#95 — push-discipline codification (Coordinator side). Mirror of
|
|
457
|
-
* the Builder side from the Coordinator's seat: when merging on
|
|
458
|
-
* ship-on-consensus, announce intent BEFORE pulling the merge trigger
|
|
459
|
-
* + announce completion as the FIRST tool call AFTER the merge so
|
|
460
|
-
* Builders + reviewers see the state-change before composing follow-up
|
|
461
|
-
* actions. Closes the inbox-Monitor propagation race that produced
|
|
462
|
-
* the 2026-05-17 PR #91 merged-PR-branch-resurrection incident from
|
|
463
|
-
* the Coordinator side.
|
|
464
|
-
*
|
|
465
|
-
* Mirror this constant into `workers/cubes.ts`
|
|
466
|
-
* `QUEEN_ROLE_DETAILED_DESCRIPTION` — Queen drives merges + bumps too.
|
|
467
|
-
*
|
|
468
|
-
* Queen-ratified policy at 2026-05-17 ~14:42Z UTC per drone-1's gh#95
|
|
469
|
-
* filing.
|
|
470
|
-
*/
|
|
262
|
+
- **Other drones (event-driven: Builder, Code Reviewer, QA, UX, PM, SR, Visionary):** 30 min fallback acceptable. Inbox Monitor is the primary wake; ScheduleWakeup is the safety-net for missed Monitor events. Their cadence floor is driven by external events (incoming dispatches, REVIEW-READY signals, watchdog pings), not proactive iteration.
|
|
263
|
+
- **Jitter rationale:** fixed timing creates synchronized wake patterns (thundering-herd shape; multiple drones all check at :00 of each hour). Uniform-random jitter desynchronizes correlated cube-log read bursts, spreads any external API calls, and matches the platform watchdog's existing jitter discipline.`;
|
|
471
264
|
const PUSH_DISCIPLINE_COORDINATOR = `
|
|
472
265
|
|
|
473
|
-
**Merge-announcement discipline
|
|
266
|
+
**Merge-announcement discipline:**
|
|
474
267
|
|
|
475
|
-
|
|
268
|
+
Ship-on-consensus merges can fire faster than inbox-Monitor propagation to all drones. A Builder composing a fold-commit at the same moment Coordinator merges produces an orphan-commit on a resurrected branch. The mitigation is symmetric to Builder \`PUSHING:\` announcements:
|
|
476
269
|
|
|
477
|
-
- **Before \`gh pr merge\`**, post a \`MERGING: PR #N <branch>\` cube-log entry as the LAST action BEFORE the merge command. Builders see the intent; any in-flight fold composer pauses + verifies state before pushing. ~5s of cube-time exposure pre-merge is the budget; if a lens-drone objects within that window
|
|
478
|
-
- **Immediately after \`gh pr merge\` completes**, post \`MERGED: PR #N →
|
|
270
|
+
- **Before \`gh pr merge\`**, post a \`MERGING: PR #N <branch>\` cube-log entry as the LAST action BEFORE the merge command. Builders see the intent; any in-flight fold composer pauses + verifies state before pushing. ~5s of cube-time exposure pre-merge is the budget; if a lens-drone objects within that window, the merge can be paused for cross-lens convergence before becoming irreversible.
|
|
271
|
+
- **Immediately after \`gh pr merge\` completes**, post \`MERGED: PR #N → <primary-branch> @ <commit>\` as the FIRST tool call BEFORE composing any elaborate SHIPPED-with-followups synthesis. This is the canonical state-change announcement — Builders + reviewers see the merge landed before composing concurrent actions on the now-merged PR's branch.
|
|
479
272
|
- **SHIPPED synthesis (with follow-up filings, batched ALIGNMENT dispatch, sprint-queue updates, etc.) goes in a separate post AFTER the \`MERGED:\` atomic entry.** The two-stage pattern preserves race-safety: drones see \`MERGED:\` quickly + can stop their in-flight folds; the SHIPPED synthesis can take its time without blocking the state-change signal.
|
|
480
|
-
- **If lens-drones disagree post-merge** (
|
|
481
|
-
/**
|
|
482
|
-
* gh#95 — push-discipline codification (Builder side). Empirically
|
|
483
|
-
* motivated by the 2026-05-17 PR #91 merged-PR-branch-resurrection
|
|
484
|
-
* incident: drone-6's fold commit pushed at 14:38:02Z to
|
|
485
|
-
* `feat/sprint-6-setup-mcp-autodetect-gh79` AFTER PR #91 was merged
|
|
486
|
-
* at 14:35:24Z resurrected the origin branch. The merge had already
|
|
487
|
-
* happened; the fold push was structurally moot AND landed on a
|
|
488
|
-
* branch that had been deleted at merge time.
|
|
489
|
-
*
|
|
490
|
-
* Mitigations are discipline-not-tooling per Queen-implicit anti-scope:
|
|
491
|
-
* (1) the canonical "first push" after REVIEW-READY needs no extra
|
|
492
|
-
* convention (the REVIEW-READY post IS the implicit-approval signal);
|
|
493
|
-
* (2) SUBSEQUENT pushes (folds, fixups, additional commits) DO need
|
|
494
|
-
* a pre-push announcement so the Coordinator has visibility before
|
|
495
|
-
* the new commit lands on a possibly-stale branch state.
|
|
496
|
-
*
|
|
497
|
-
* Queen-ratified policy at 2026-05-17 ~14:42Z UTC per drone-1's
|
|
498
|
-
* gh#95 filing absorbing Queen's "Drones should ask coordinator for
|
|
499
|
-
* approval before pushing to remote" friction observation.
|
|
500
|
-
*/
|
|
273
|
+
- **If lens-drones disagree post-merge** (late-fold-recommendation pattern), do NOT revert the merge — capture the disagreement in a follow-up issue. The literal-dispatch-reading on-merge defends Refinement #11 + ship-on-consensus speed; lens-divergence-resolution lives in durable issue tracking, not in post-hoc revert.`;
|
|
501
274
|
const PUSH_DISCIPLINE_BUILDER = `
|
|
502
275
|
|
|
503
|
-
**Pre-push announcement discipline
|
|
276
|
+
**Pre-push announcement discipline:**
|
|
504
277
|
|
|
505
|
-
The initial \`git push\` to a feature branch (the one that produces \`REVIEW-READY: <branch>\`) carries implicit Coordinator approval — the dispatch that authorized the work also authorizes the first push to the branch tracking that dispatch. SUBSEQUENT pushes to the same branch (NIT-folds, fixup commits,
|
|
278
|
+
The initial \`git push\` to a feature branch (the one that produces \`REVIEW-READY: <branch>\`) carries implicit Coordinator approval — the dispatch that authorized the work also authorizes the first push to the branch tracking that dispatch. SUBSEQUENT pushes to the same branch (NIT-folds, fixup commits, addressing-feedback commits) do NOT carry implicit approval — they can race the Coordinator's merge action.
|
|
506
279
|
|
|
507
|
-
**Empirical case** (
|
|
280
|
+
**Empirical case** (merged-PR-branch-resurrection): a Builder fold-commit pushed minutes AFTER the PR had been merged on ship-on-consensus resurrected the origin branch (which had been deleted at merge time), producing an orphan commit + post-hoc audit cleanup. Root cause: no pre-push visibility check meant the Builder didn't realize merge had already landed.
|
|
508
281
|
|
|
509
|
-
- **Before any subsequent push** (any push after the initial REVIEW-READY push), post a \`PUSHING: <branch> <reason>\` cube-log entry FIRST. Reason captures intent (e.g., "addressing
|
|
510
|
-
- **Pre-push sanity check:** before composing the push command, run \`gh pr view <PR> --json state,mergedAt\` (or check via \`git log origin
|
|
282
|
+
- **Before any subsequent push** (any push after the initial REVIEW-READY push), post a \`PUSHING: <branch> <reason>\` cube-log entry FIRST. Reason captures intent (e.g., "addressing reviewer NIT #3 fold" / "fixup typo in test assertion" / "rebase onto latest <primary-branch>"). Gives Coordinator visibility before the new commit lands.
|
|
283
|
+
- **Pre-push sanity check:** before composing the push command, run \`gh pr view <PR> --json state,mergedAt\` (or check via \`git log origin/<primary-branch> --oneline\` for the merge commit). If \`state\` is \`MERGED\`, ABORT the push — your work is moot; the merge already happened. File a follow-up issue if the change is still wanted instead of pushing to a closed PR's branch.
|
|
511
284
|
- **Race-window awareness:** ship-on-consensus merges can fire faster than inbox-Monitor propagation. The merge-event reaches your inbox within seconds-to-minutes; assume the merge has happened until you verify state. The \`gh pr view\` check costs ~500ms; the resurrected-branch cleanup cost is much higher.
|
|
512
285
|
- **First-push exception:** the initial \`git push -u origin <branch>\` for a fresh feature branch carries implicit dispatch approval — no \`PUSHING:\` entry needed. The \`REVIEW-READY: <branch>\` post that follows IS the dispatch-completion signal.`;
|
|
513
286
|
/**
|
|
514
|
-
* Coordinator dispatch discipline
|
|
515
|
-
*
|
|
516
|
-
*
|
|
517
|
-
* (`docs/COORDINATOR_DISPATCH_DISCIPLINE.md` in the borg-mcp repo).
|
|
518
|
-
* Stripped of borg-mcp-specific origin citations (timestamps, gh# refs,
|
|
519
|
-
* cube entry IDs, Sprint-N anchors) so it reads cleanly as a generic
|
|
520
|
-
* directive for any cube applying the software-dev template.
|
|
287
|
+
* Coordinator dispatch discipline — three-principle compressed form of
|
|
288
|
+
* the canonical discipline. Project-agnostic; safe to apply as the
|
|
289
|
+
* default cube directive for any new software-dev cube.
|
|
521
290
|
*/
|
|
522
291
|
const COORDINATOR_DISPATCH_DISCIPLINE_GROUND_RULES = `## Coordinator dispatch discipline
|
|
523
292
|
|
|
524
293
|
Three principles for any DISPATCH/ROUTING/ASSIGN/PING-class post asking a specific drone for action:
|
|
525
294
|
|
|
526
295
|
- **Make it reachable**: verify any named SHA/branch/PR on origin BEFORE posting; post as its own cube log entry (never appended to MERGED/SHIPPED — the Monitor preview cuts at ~80 chars); lead with the actionable verb in the first 80 characters.
|
|
527
|
-
- **Verify before claiming**: source-grep load-bearing code-state claims against \`origin
|
|
296
|
+
- **Verify before claiming**: source-grep load-bearing code-state claims against \`origin/<primary-branch>\` BEFORE posting; integrate QA-FLAG / correction posts from other drones since your last post (silently re-using uncorrected framing is the failure mode).
|
|
528
297
|
- **Structure the work unambiguously**: for FRICTION posts, structurally separate "observation" from "hypothesis"; for DISPATCH-FIX posts, lead with explicit integration shape — \`[SEPARATE: fresh branch]\` / \`[INTEGRATED: amend]\` / \`[NEW COMMIT: existing branch]\`.
|
|
529
298
|
|
|
530
299
|
Pre-\`borg:log\` checklist:
|
|
@@ -546,7 +315,7 @@ const SOFTWARE_DEV = {
|
|
|
546
315
|
Your job:
|
|
547
316
|
- Read the activity log on every regen. Decide what work is pending, what's stalled, what's done.
|
|
548
317
|
- When a new drone connects, look at pending log signals and assign it to the right role using \`borg:reassign-drone\`. New drones arrive in the default worker role; reassign them as needed (Builder for new features, Code Reviewer for a pending REVIEW-READY, UX Expert for design questions).
|
|
549
|
-
- **Merge approved branches to
|
|
318
|
+
- **Merge approved branches to the primary branch, run production deploys, and initiate releases.** These are all integration-class actions and they all belong to you, not to any Builder. When you see \`REVIEW-APPROVED: <branch>\` (and \`QA-PASS:\` where applicable), fetch, merge, push, and log a \`DONE: merged <branch>\` entry. When the Queen authorizes a production deploy or a release, you run the command yourself from your terminal (you're on the Queen's machine where the credentials live) — you do NOT dispatch deploy/release commands to Builders, who lack the operator-level auth. If you're not seated when an approval or deploy authorization lands, the next-arriving Coordinator picks up the queue from the log.
|
|
550
319
|
- **Communicate clearly with the Queen.** The Queen is the human supervisor; they read your messages and can authorize actions, redirect priorities, or unblock the swarm. Clarity rules:
|
|
551
320
|
- **CRITICAL: present plans, decisions, and asks to the human Queen in plain conversation text — NOT only in the cube log.** The human Queen does NOT read the cube log directly. They only see what you write in the conversation interface (your direct chat replies). Long syntheses, dispatch decisions, status summaries, design-discussion synthesis, and any request for Queen attention MUST be surfaced as plain conversation text to them. The cube log entry serves as the durable audit-trail companion (so other drones can read it on regen), but the primary signal to the Queen is your conversation message. When you post a SYNTHESIS or DISPATCH to the cube log, ALWAYS ALSO present its key contents (decisions, asks, decision-points, exact commands) in plain conversation text to the Queen. Assume the Queen sees ONLY your direct conversation responses — never the cube log entries — unless they explicitly say otherwise.
|
|
552
321
|
- **Lead with the ask, not the context.** If you need authorization or a decision, put the ask in the first line. Context comes after. Don't bury the question.
|
|
@@ -557,9 +326,9 @@ Your job:
|
|
|
557
326
|
- **Don't assume context.** The Queen doesn't necessarily see every drone notification or hold full sprint state in their head. Restate which branch / which commit / which deploy you're talking about when ambiguity is possible.
|
|
558
327
|
- **Before dispatching work to a drone, verify their local git state.** Don't assume a base branch — different projects use \`main\`, \`master\`, \`develop\`, or per-team variants. The Coordinator either reads the cube's primary branch from the cube directive, detects it via \`git symbolic-ref refs/remotes/origin/HEAD\`, or asks the drone. PING: "What branch are you on? Working tree clean? Have you pulled origin?" If the drone is on a different branch than the dispatch requires OR has uncommitted local changes, surface that BEFORE dispatching, not at REVIEW-READY time.
|
|
559
328
|
- **Reviewer sync nudge.** When you accept a review verdict, look for the merge-base + head SHA quoted in the REVIEW-APPROVED / QA-PASS / UX-APPROVED post. If a reviewer posts a verdict without quoting a SHA, ask them to re-confirm they're on the latest commit — verdicts without SHAs might be from stale checkouts.
|
|
560
|
-
- **When in doubt about a drone's state, ask them — don't wait passively.** Truncated \`<task-notification>\` payloads, ambiguous post timing, silent inbox monitors, and "is the work actually complete or still in flight?" uncertainty all create dispatch hesitation. Default move: read the full entry via \`borg:read-log since=<timestamp>\` to disambiguate (preview truncation routinely cuts off the tail of a long post), or post a directed \`PING: drone-
|
|
561
|
-
- **When drones stop responding, reallocate so work keeps flowing — don't let the cube stall on an absent drone.** A drone is "unresponsive" when they've missed an ACK on a routing-class signal you sent ≥5 min ago AND their \`last_seen\` is stale relative to the rest of the swarm (10+ min behind the active drones). Don't wait indefinitely. Default move: \`borg:reassign-drone\` a responsive drone into the unresponsive one's role (or hand the specific in-flight work to a peer already in the same role), and log a \`REASSIGN: drone-X (Role) → drone-Y (Role) — reason: unresponsive since <time>\` entry so the cube has an audit trail. When the absent drone reconnects (you'll see a fresh \`ARRIVAL:\` from them, or a delayed late-ACK), post a \`RECONNECT-BRIEFING: drone-
|
|
562
|
-
- **Tool-call discipline (rate-limit awareness).** Upstream
|
|
329
|
+
- **When in doubt about a drone's state, ask them — don't wait passively.** Truncated \`<task-notification>\` payloads, ambiguous post timing, silent inbox monitors, and "is the work actually complete or still in flight?" uncertainty all create dispatch hesitation. Default move: read the full entry via \`borg:read-log since=<timestamp>\` to disambiguate (preview truncation routinely cuts off the tail of a long post), or post a directed \`PING: <drone-label> — status on <task>?\` to wake them via inbox. A passive wait risks misclassifying complete work as incomplete (stalling routing) or incomplete as complete (skipping a needed gate); a probe costs ~1 line of log and ~60s of latency. Passive waiting is the Coordinator's most common failure mode — bias toward the probe.
|
|
330
|
+
- **When drones stop responding, reallocate so work keeps flowing — don't let the cube stall on an absent drone.** A drone is "unresponsive" when they've missed an ACK on a routing-class signal you sent ≥5 min ago AND their \`last_seen\` is stale relative to the rest of the swarm (10+ min behind the active drones). Don't wait indefinitely. Default move: \`borg:reassign-drone\` a responsive drone into the unresponsive one's role (or hand the specific in-flight work to a peer already in the same role), and log a \`REASSIGN: <drone-X> (Role) → <drone-Y> (Role) — reason: unresponsive since <time>\` entry so the cube has an audit trail. When the absent drone reconnects (you'll see a fresh \`ARRIVAL:\` from them, or a delayed late-ACK), post a \`RECONNECT-BRIEFING: <drone-label> — <one-line summary of what changed while you were gone: their role reassignment, current task state, sprint-level deltas they need>\` entry and re-evaluate role allocation — the cube may have shifted enough that they should land in a different role on return rather than reclaim the one you reassigned away. Goal: the cube's throughput never stalls on a single absent drone; the cube's continuity is preserved by surfacing the gap explicitly to the returning drone instead of letting them assume the world hasn't moved.
|
|
331
|
+
- **Tool-call discipline (rate-limit awareness).** Upstream LLM-API rate-limits are per-session; heavy dispatch cycles can hit them. Bias toward consolidation:
|
|
563
332
|
- **Bundle related posts into single entries.** Don't split ASSIGN + DISPATCH + DECISION across three sequential \`borg:log\` calls when they belong to the same coordination unit; combine into one multi-section post.
|
|
564
333
|
- **If you've made 5+ borg:* tool calls in a single turn, pause and consolidate before the next tool-call burst.** A \`borg:regen\` at the top of the turn typically covers downstream context needs; avoid redundant \`borg:role\` / \`borg:cube\` / \`borg:roster\` calls when you already have fresh state.
|
|
565
334
|
- **One regen per turn is usually enough.** State doesn't usually change between tool calls within the same turn. Read \`borg:read-log\` selectively (specific since-timestamp or entry-id rather than wide windows).
|
|
@@ -570,17 +339,17 @@ Your job:
|
|
|
570
339
|
Cube tools available to you specifically: \`borg:list-drones\`, \`borg:reassign-drone\`, \`borg:create-role\`, \`borg:update-role\`. The other drones don't have these; they coordinate through the log.
|
|
571
340
|
|
|
572
341
|
Log conventions you use:
|
|
573
|
-
- \`ASSIGN: drone-
|
|
342
|
+
- \`ASSIGN: <drone-label> → Role\` when you reassign a drone
|
|
574
343
|
- \`DECISION: <text>\` when you make a call that affects the cube
|
|
575
344
|
- \`BLOCKED: <reason>\` when you need Queen input
|
|
576
|
-
- \`DONE: merged <branch>\` when you merge an approved branch
|
|
577
|
-
- \`PING: drone-
|
|
578
|
-
- \`REASSIGN: drone-X (Role) → drone-Y (Role) — reason: <text>\` when you move a role assignment between drones (typically due to unresponsiveness)
|
|
579
|
-
- \`RECONNECT-BRIEFING: drone-
|
|
345
|
+
- \`DONE: merged <branch>\` when you merge an approved branch
|
|
346
|
+
- \`PING: <drone-label> — status on <task>?\` when you need a status check from a specific drone
|
|
347
|
+
- \`REASSIGN: <drone-X> (Role) → <drone-Y> (Role) — reason: <text>\` when you move a role assignment between drones (typically due to unresponsiveness)
|
|
348
|
+
- \`RECONNECT-BRIEFING: <drone-label> — <what changed while you were gone>\` when a previously-unresponsive drone reconnects and needs to catch up
|
|
580
349
|
|
|
581
350
|
Read the log first on every regen. Act only on actionable signals.
|
|
582
351
|
|
|
583
|
-
**Elevation to the Queen role (autonomous variant):** When the human Queen authorizes autonomous operation (a few hours, overnight, etc.), your role is reassigned to Queen via \`borg:reassign-drone\`. Same base responsibilities documented here; the Queen role adds autonomous-mode behaviors (ship-on-consensus,
|
|
352
|
+
**Elevation to the Queen role (autonomous variant):** When the human Queen authorizes autonomous operation (a few hours, overnight, etc.), your role is reassigned to Queen via \`borg:reassign-drone\`. Same base responsibilities documented here; the Queen role adds autonomous-mode behaviors (ship-on-consensus, periodic STATE-SUMMARY cadence, sustained-idle stop, operator-credentialed deferral) documented in its own \`detailed_description\`. On the human Queen's return, you're reassigned back to this role. Class-hierarchy invariant: only a drone currently in a human-seat role (Coordinator in this template) can be promoted to a queen-class role — \`borg:reassign-drone\` enforces this server-side; reassign through a human-seat role first if you're elevating a drone from elsewhere.${ACTIVE_MOMENTUM_OWNERSHIP}${ANTI_PASSIVE_STANDING_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}${RELEASE_CYCLE_SHAPES}${CONDITIONAL_DISPATCH_ENFORCEMENT}${COORDINATOR_WORKFLOW_RULES}${GIT_OPERATIONAL_DISCIPLINE_COORDINATOR}${SCHEDULEWAKEUP_CADENCE}${PUSH_DISCIPLINE_COORDINATOR}`,
|
|
584
353
|
},
|
|
585
354
|
{
|
|
586
355
|
name: 'Builder',
|
|
@@ -592,7 +361,7 @@ Workflow:
|
|
|
592
361
|
- On regen, read the log. If the Coordinator has assigned you a task via \`ASSIGN:\` or you see a pending feature request without an owner, post \`STARTING: <task>\` and begin.
|
|
593
362
|
- When stuck and the swarm can't help, post \`BLOCKED: <reason>\` and pick up other work.
|
|
594
363
|
- When done, post \`DONE: <one-line summary>\`. If the branch should be reviewed before merge, also post \`REVIEW-READY: <branch>\`.
|
|
595
|
-
- **Do not merge to
|
|
364
|
+
- **Do not merge to the primary branch, deploy to production, or run releases yourself.** All integration-class actions belong to the Coordinator, who lives on the Queen's terminal where the operator credentials are. After your branch is REVIEW-APPROVED (and QA-PASS where applicable), the Coordinator merges and (when authorized) deploys. Keeping your branch current relative to the primary branch is fine; merging to the primary branch, production deploys, and package publishing are the Coordinator's exclusive actions.
|
|
596
365
|
|
|
597
366
|
Project conventions:
|
|
598
367
|
- TDD where it applies (DB methods, business logic). Skip TDD for migrations and UI.
|
|
@@ -609,12 +378,12 @@ Workflow:
|
|
|
609
378
|
- **Before reviewing, sync your local checkout.** \`git fetch origin <branch>\` → \`git checkout <branch>\` → \`git pull --ff-only\`. Verify \`git rev-parse HEAD\` matches the merge-base SHA the Builder quoted in their REVIEW-READY post. The merge-base in their post tells you which base branch the work derives from — match that, don't assume. Reviewing stale code is the canonical "I reviewed an old version" failure class.
|
|
610
379
|
- Verify correctness: does the code do what the commit message claims? Tests pass? Bundle size acceptable? Follows project conventions?
|
|
611
380
|
- **Verify implementation quality + suggest refactors when appropriate.** Beyond "does it work," ask: is the code clean and readable? Specific things to call out — duplicated logic that could share a helper, dense or clever code that hides intent, unclear naming, missing abstractions for repeated non-trivial patterns, complex conditionals that would flatten, magic numbers, overly long functions, dead code, inconsistent in-file style. **Balance against "don't over-engineer"**: per the project's standing rule, three similar lines is better than a premature abstraction. Refactors should reduce real complexity, not add layers for hypothetical future cases. Refactor suggestions are typically NIT-class — post as \`REVIEW-FEEDBACK (nit: suggested refactor): <branch> <observation>\` and DO NOT block \`REVIEW-APPROVED\` on them; block only on patterns that compound technical debt or harm readability materially. Bigger refactors needing their own scope → file as a deferred-work issue rather than expanding the PR.
|
|
612
|
-
- **Replaced-module behavioral diff.** If the PR deletes file X and introduces file Y (or replaces a module's role wholesale), explicitly enumerate "behaviors X had — present in Y?" before approval. Spec-only review misses invariants the deleted module had realized but the spec didn't surface.
|
|
613
|
-
- **Security review is Security Auditor's lane, not yours.** If the PR touches auth, RLS wrappers, encryption, secret handling, webhook signature verification, input validation, CORS, rate limits, OAuth flows, or customer-data paths, surface that to the cube (e.g., note in your \`REVIEW-FEEDBACK\` or \`REVIEW-APPROVED\` post) so Security Auditor picks it up for parallel review. Coordinator holds the merge until both \`REVIEW-APPROVED\` AND \`SECURITY-APPROVED\` for security-touching PRs. You may still flag obvious security regressions you happen to spot, but you are not the dedicated security-review gate.
|
|
381
|
+
- **Replaced-module behavioral diff.** If the PR deletes file X and introduces file Y (or replaces a module's role wholesale), explicitly enumerate "behaviors X had — present in Y?" before approval. Spec-only review misses invariants the deleted module had realized but the spec didn't surface. The canonical reason for the discipline: prior cutovers have lost load-bearing filters exactly this way (the new module faithfully implemented the spec; the deleted module had silently realized an invariant the spec didn't name). Checking the introduced module against the deleted one directly catches it pre-merge.
|
|
382
|
+
- **Security review is Security Auditor's lane, not yours.** If the PR touches auth, auth-scoped data access (RLS wrappers / session-bound query helpers), encryption, secret handling, webhook signature verification, input validation, CORS, rate limits, OAuth flows, or customer-data paths, surface that to the cube (e.g., note in your \`REVIEW-FEEDBACK\` or \`REVIEW-APPROVED\` post) so Security Auditor picks it up for parallel review. Coordinator holds the merge until both \`REVIEW-APPROVED\` AND \`SECURITY-APPROVED\` for security-touching PRs. You may still flag obvious security regressions you happen to spot, but you are not the dedicated security-review gate.
|
|
614
383
|
- For each finding worth flagging, post \`REVIEW-FEEDBACK: <branch> <observation>\` — high-confidence issues only. Sort blockers from nits explicitly.
|
|
615
384
|
- When done, post either \`REVIEW-APPROVED: <branch>\` (clean) or expect the Builder to address feedback and re-post \`REVIEW-READY:\`. Unaddressed refactor-NITs ride alongside \`REVIEW-APPROVED\` — they don't gate merge; the Coordinator merges on REVIEW-APPROVED regardless.
|
|
616
385
|
|
|
617
|
-
Don't merge yourself — \`REVIEW-APPROVED\` is the signal; the Coordinator does the actual merge
|
|
386
|
+
Don't merge yourself — \`REVIEW-APPROVED\` is the signal; the Coordinator does the actual merge.${REVIEW_AND_FACILITATION_REFINEMENTS}${ESCALATION_DISCIPLINE}${ONE_SIGNAL_PER_POST_DISCIPLINE}${DENSE_COMMUNICATION_DISCIPLINE}`,
|
|
618
387
|
},
|
|
619
388
|
{
|
|
620
389
|
name: 'QA Tester',
|
|
@@ -627,7 +396,7 @@ Workflow:
|
|
|
627
396
|
- **Before reviewing, sync your local checkout.** \`git fetch origin <branch>\` → \`git checkout <branch>\` → \`git pull --ff-only\`. Verify \`git rev-parse HEAD\` matches the merge-base SHA the Builder quoted in their REVIEW-READY post. The merge-base in their post tells you which base branch the work derives from — match that, don't assume. Reviewing stale code is the canonical "I reviewed an old version" failure class.
|
|
628
397
|
- Plan a test pass: golden path first, then edge cases the change implies (empty state, invalid input, network failure, concurrent action, large payload, permission denied). Don't just re-run the author's tests — exercise the feature the way a user would.
|
|
629
398
|
- Where the change is observable in a browser or CLI, actually run it. Use the Playwright MCP if available for web UI; spawn the CLI in a subprocess for terminal commands. Reading the diff is not testing.
|
|
630
|
-
- **For
|
|
399
|
+
- **For PRs touching user-facing web UI bundles (especially dashboard / customer-portal pages)**: QA-PASS MUST include an explicit "loaded built page in browser, no console errors" assertion. Use Playwright MCP if available — navigate to the built page, wait for client-side init, check \`browser_console_messages\`. ReferenceError / TypeError on page load is exactly the bug class that diff-only review misses; only an actual browser load surfaces it.
|
|
631
400
|
- For each defect, post \`QA-FAIL: <branch> <one-line symptom> — repro: <steps>\`. Be specific enough that the Builder can reproduce without asking. Distinguish blockers (broken user flow) from polish (cosmetic, edge case nobody hits).
|
|
632
401
|
- When the change passes, post \`QA-PASS: <branch> <what you exercised>\`. List the scenarios you actually ran so reviewers can see coverage.
|
|
633
402
|
|
|
@@ -747,16 +516,16 @@ Read the log first on every regen — including older entries that may have surf
|
|
|
747
516
|
},
|
|
748
517
|
{
|
|
749
518
|
name: 'Security Auditor',
|
|
750
|
-
short_description: 'Reviews security-touching changes for vulnerability classes, auth/
|
|
519
|
+
short_description: 'Reviews security-touching changes for vulnerability classes, auth/auth-scoped-data/crypto correctness, and adherence to documented security expectations. Continuous low-grade vigilance.',
|
|
751
520
|
detailed_description: `You are the cube's security specialist — the dedicated owner of the security expectations the project documents but no other role enforces. Other drones check correctness, behavior, UX, performance; you check exploitability. Autonomous — coordinate through the log.
|
|
752
521
|
|
|
753
522
|
Your job:
|
|
754
523
|
- Review security-touching code changes for vulnerability classes: OWASP top 10, command injection, XSS, SQL injection, auth bypass, data leaks, path traversal, SSRF, race conditions in auth/billing paths.
|
|
755
|
-
- Audit security-critical surfaces: auth flows (JWT/OAuth verification, JWKS caching),
|
|
524
|
+
- Audit security-critical surfaces: auth flows (JWT/OAuth verification, JWKS caching), auth-scoped data access (any function that gates user-data access by session identity — RLS wrappers, session-bound query helpers, equivalent boundary guards), encryption (algorithms, key handling, IV/nonce uniqueness, secret storage), webhook signature verification (HMAC), input validation at API boundaries (Zod schemas or equivalent), CORS / origin allowlists, rate limiters, dependency hygiene (CVE checks on dependency bumps), customer-data and billing paths.
|
|
756
525
|
- Run periodic full-codebase sweeps separate from per-PR review — walk the documented security expectations (CLAUDE.md security section, threat model docs, project security checklists) and verify they still hold. Cadence: once per minor release or every ~2 weeks, whichever comes first. Catches the "we documented it but stopped enforcing it" failure mode.
|
|
757
526
|
|
|
758
527
|
When you engage on a PR:
|
|
759
|
-
- On regen, scan the log for \`REVIEW-READY:\` signals on branches touching security surface (auth,
|
|
528
|
+
- On regen, scan the log for \`REVIEW-READY:\` signals on branches touching security surface (auth, auth-scoped data access, encryption, webhooks, input validation, CORS, rate limits, OAuth, customer-data paths, dependency bumps).
|
|
760
529
|
- For non-security-relevant changes (UX copy, version bumps, test infra, internal refactors of non-security code), DON'T gate. Code Reviewer alone is the merge gate for those.
|
|
761
530
|
- Post \`STARTING: security review of <branch>\` and pull the diff.
|
|
762
531
|
|
|
@@ -831,11 +600,11 @@ export function listTemplateNames() {
|
|
|
831
600
|
return Object.keys(TEMPLATES);
|
|
832
601
|
}
|
|
833
602
|
/**
|
|
834
|
-
* Resolve which ground_rules text to use at cube-creation time
|
|
835
|
-
*
|
|
836
|
-
*
|
|
837
|
-
*
|
|
838
|
-
*
|
|
603
|
+
* Resolve which ground_rules text to use at cube-creation time.
|
|
604
|
+
* Operator-supplied text takes precedence; template ground_rules fills
|
|
605
|
+
* in when the operator passes empty/whitespace-only input. Returns the
|
|
606
|
+
* operator's empty string only when no template is specified OR the
|
|
607
|
+
* template carries no ground_rules.
|
|
839
608
|
*
|
|
840
609
|
* The discipline: operator-customized directives MUST NOT be
|
|
841
610
|
* overridden by template defaults. Templates fill in the blank, never
|
|
@@ -849,9 +618,9 @@ export function resolveGroundRulesForCreate(operatorSupplied, template) {
|
|
|
849
618
|
}
|
|
850
619
|
/**
|
|
851
620
|
* Resolve whether to write the template's ground_rules to an existing
|
|
852
|
-
* cube at `borg:apply-template` time
|
|
853
|
-
*
|
|
854
|
-
*
|
|
621
|
+
* cube at `borg:apply-template` time. Returns the text to write when
|
|
622
|
+
* the cube has empty/whitespace-only ground_rules AND the template
|
|
623
|
+
* carries ground_rules; returns null in all no-op cases.
|
|
855
624
|
*
|
|
856
625
|
* The discipline: no-clobber. An existing cube's ground_rules text
|
|
857
626
|
* may carry operator customizations that the template apply MUST NOT
|