borgmcp 1.0.27 → 1.0.28
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/README.md +18 -18
- package/dist/assimilate-cmd.js +4 -4
- package/dist/assimilate-guard.d.ts +1 -1
- package/dist/assimilate-guard.js +2 -2
- package/dist/assimilate-welcome.js +1 -1
- package/dist/auth-recovery.d.ts +1 -1
- package/dist/auth-recovery.js +1 -1
- package/dist/claude.js +7 -7
- package/dist/cli-help.d.ts +6 -0
- package/dist/cli-help.js +33 -4
- package/dist/codex-app-wake.d.ts +2 -2
- package/dist/codex-app-wake.js +1 -1
- package/dist/codex-launch.js +1 -1
- package/dist/codex-remote.js +1 -1
- package/dist/config-utils.d.ts +1 -1
- package/dist/evict-drone.d.ts +2 -2
- package/dist/index.js +12 -12
- package/dist/launch-gate.d.ts +1 -1
- package/dist/list-roles-render.d.ts +3 -3
- package/dist/list-roles-render.js +1 -1
- package/dist/log-audit.d.ts +3 -3
- package/dist/log-audit.js +1 -1
- package/dist/log-stream.d.ts +1 -1
- package/dist/regen-format.d.ts +2 -2
- package/dist/regen-format.js +5 -5
- package/dist/regen.js +1 -1
- package/dist/remote-client.d.ts +1 -1
- package/dist/roster-render.d.ts +2 -2
- package/dist/stream-status.d.ts +4 -4
- package/dist/sync-roles-render.js +2 -2
- package/dist/templates.d.ts +5 -5
- package/dist/templates.js +16 -16
- package/dist/terminal-title.d.ts +1 -1
- package/package.json +1 -1
package/dist/templates.d.ts
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
* Cube role templates.
|
|
3
3
|
*
|
|
4
4
|
* A template is an opinionated set of roles for a specific use case.
|
|
5
|
-
* Templates are applied to a cube at creation time (via `
|
|
6
|
-
* template=<name>`) or after the fact (via `
|
|
5
|
+
* Templates are applied to a cube at creation time (via `borg_create-cube
|
|
6
|
+
* template=<name>`) or after the fact (via `borg_apply-template`). Roles
|
|
7
7
|
* are merged by name: existing roles with the same name get updated,
|
|
8
8
|
* new ones get inserted.
|
|
9
9
|
*
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
* platform-supplied roles regardless of template:
|
|
17
17
|
* - "Drone" (default worker role — the assimilate target);
|
|
18
18
|
* - "Queen" (queen-class autonomous-mode seat — promoted via
|
|
19
|
-
* `
|
|
19
|
+
* `borg_reassign-drone` from a human-seat role when the human
|
|
20
20
|
* Queen delegates).
|
|
21
21
|
* Templates therefore never declare `role_class: 'queen'`. Setting
|
|
22
22
|
* `is_human_seat: true` on a template role marks it as the cube's
|
|
@@ -56,7 +56,7 @@ export interface Template {
|
|
|
56
56
|
/**
|
|
57
57
|
* Optional cube directive text shipped with the template. Applied at
|
|
58
58
|
* cube-creation time (when operator passes empty cube_directive) and
|
|
59
|
-
* at `
|
|
59
|
+
* at `borg_apply-template` time (no-clobber — only fills empty
|
|
60
60
|
* directives, never overwrites operator-customized text). See
|
|
61
61
|
* `resolveCubeDirectiveForCreate` / `resolveCubeDirectiveForApply` below
|
|
62
62
|
* for the resolution discipline.
|
|
@@ -87,7 +87,7 @@ export declare function listTemplateNames(): string[];
|
|
|
87
87
|
export declare function resolveCubeDirectiveForCreate(operatorSupplied: string, template: Template | null): string;
|
|
88
88
|
/**
|
|
89
89
|
* Resolve whether to write the template's cube_directive to an existing
|
|
90
|
-
* cube at `
|
|
90
|
+
* cube at `borg_apply-template` time. Returns the text to write when
|
|
91
91
|
* the cube has empty/whitespace-only cube_directive AND the template
|
|
92
92
|
* carries cube_directive; returns null in all no-op cases.
|
|
93
93
|
*
|
package/dist/templates.js
CHANGED
|
@@ -48,7 +48,7 @@ Cube-log posts use telegraph-style language. Information density over readabilit
|
|
|
48
48
|
- When blocked \u2014 missing context, ambiguous scope, harness rejection, environment issue, anything \u2014 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.
|
|
49
49
|
- **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.) \u2014 never for "should I deploy?" / "should I skip E2E?" / "which option?" \u2014 those are Coordinator decisions posted to cube log.
|
|
50
50
|
- User-facing text output: same rule. Framing should be "Coordinator: blocker X, options A/B/C, my pick is B" \u2014 never "Queen: which of A/B/C?" The cube log is the channel; how the harness displays your output is incidental.
|
|
51
|
-
- If Coordinator is silent >10 min on a blocker, PING via \`
|
|
51
|
+
- If Coordinator is silent >10 min on a blocker, PING via \`borg_roster since=<dispatch-entry-id>\` or post a follow-up \u2014 don't bypass to Queen.
|
|
52
52
|
- 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.`,u=`
|
|
53
53
|
|
|
54
54
|
**Active momentum ownership (autonomous mode):**
|
|
@@ -65,11 +65,11 @@ Under autonomous mode you own the cube's throughput. An idle cube \u2014 no work
|
|
|
65
65
|
Use an idleness-detector: a short ScheduleWakeup heartbeat (~7 min \xB1 1 min jitter) whose job on each fire is only to check whether the cube went idle. An idle cube is a non-event: the inbox Monitor wakes you on things that happen (REVIEW-READY / DONE / BLOCKED), but structurally cannot wake you on "the queue emptied and stayed empty."
|
|
66
66
|
|
|
67
67
|
On each idleness-detector fire:
|
|
68
|
-
- Run \`
|
|
68
|
+
- Run \`borg_read-log unread_only=true\` (drain until caught up) + \`borg_roster\`.
|
|
69
69
|
- If idle (no WUs in flight, builders waiting, no pending gate/merge), plan + dispatch next work NOW. This is deliberate dispatch triggered by the idle condition.
|
|
70
70
|
- If work is in flight, run the liveness sweep only; do not manufacture a dispatch.
|
|
71
71
|
|
|
72
|
-
Trigger = the idle condition, not the clock. Both extremes are wrong: reflexive-dispatch-every-tick AND go-passive-and-wait. Sprint progression (gating / merging / unblocking) stays event-driven via the Monitor; the idleness-detector only catches the pipeline-empty non-event.`,p="\n\n**Anti-passive-Standing discipline:**\n\n`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.\n\n**On every Monitor wake AND every ScheduleWakeup heartbeat \u2014 run the stale check using the cheapest sufficient Borg read:**\n0. Routine wake triage starts with `borg:read-log unread_only=true` \u2014 NOT a manual `since` cursor or bare `limit` (those skip during bursts; `unread_only` reads from your server-side read cursor, oldest-unread first, advancing on each call, so you never miss an entry). DRAIN: if it returns a full set (count == limit) or `borg:roster` shows `behind_by` > 0, call `read-log unread_only=true` again until the return is < limit. Reserve `limit` for explicit bounded reads (e.g. a vote tally). `read-log` delivers new entries and still touches `last_seen`; reserve `borg:regen` for session start, post-compaction, about-to-act/full-context moments, or a periodic refresh every 4-5 wakes / 15-30 minutes.\n1. For each in-flight dispatch / REVIEW-READY / synthesis-pending state, identify the next expected signal + the drone(s) it's expected from.\n2. Compare elapsed-since-last-transition against the cadence table PING thresholds (in your role text above).\n3. If ANY row is past its PING threshold, you do NOT post `Standing.` \u2014 you take action per the escalation ladder below.\n\n**Escalation ladder (concrete; do not improvise \u2014 pick the lowest step that applies):**\n\n- **Step 1 \u2014 PING the specific drone** (when elapsed > PING threshold for that phase):\n Post `PING: <drone-label> \u2014 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.\n\n- **Step 2 \u2014 Probe the drone's liveness** (when PING gets no response within one cadence-bucket):\n 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.\n\n- **Step 3 \u2014 Reassign the role** (when the drone is confirmed unresponsive: silent past 2x PING threshold AND `borg:roster` shows stale `last_log_post`):\n Pick a confirmed-alive drone (recent `awake` marker) compatible with the role. Run `borg:reassign-drone` to move the role assignment. Post a reassignment notice in the cube log naming the previous drone + the new drone + the work item handed over. Brief the new drone on the in-flight state. If the previous drone reconnects later, they post a returning-from-stall message; you decide whether to re-reassign or leave the current assignment in place.\n\n- **Step 4 \u2014 Suspect systemic failure** (when 3+ drones go simultaneously silent past their PING thresholds, or when reassignments themselves don't produce engagement):\n 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) \u2014 this class of failure is above the Coordinator's resolution authority because the failure mode itself prevents normal dispatch from working.\n\n**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 \u2014 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.\n\n**What \"productive Coordinator work\" looks like when no urgent dispatch is in flight:**\n- **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.\n- **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.\n- **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.\n- **Smoke-test what just shipped.** A merge+deploy from earlier in the session is now in production \u2014 verify the user-facing surface actually behaves as the merge claimed. Catch broken-ship issues before users do.\n- **Update durable docs.** CLAUDE.md, role descriptions, runbook docs \u2014 small drifts noticed during the session that warrant codification.\n- **Probe drone liveness pre-emptively** via `borg:roster` \u2014 surface stale drones before they become a blocker on the next dispatch.\n- **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.\n- **Run the on-wake stale check** (which IS standing-equivalent action even when nothing's overdue \u2014 it produces a snapshot of cube state, not a Standing reply).\n\n**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 \u2014 find work.\n\n**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 \u2014 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:\n\n- Before posting any tally / convergence / synthesis claim that names specific drone votes or counts, run `borg:read-log limit \u226510` for brainstorm-class threads OR `limit \u22655` for gate-convergence threads.\n- 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.\n- 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\").\n\n**Canonical lens-vote format** (adopt `GATE-PASS:` going forward):\n```\nGATE-PASS: <lens> <branch> @ <commit-sha>\n<one-line disposition>\n```\nExamples: `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.\n\n**Coordinator owns deadlock resolution (HIGH-PRIORITY DIRECTIVE):**\n\nWhen the cube is at risk of deadlock \u2014 any pattern where progress requires action but no drone has explicit ownership of the required action \u2014 the Coordinator (or Queen seat in autonomous mode) is responsible for resolving the situation by **explicitly assigning the action to a named drone**. Implicit ownership is not sufficient; relying on a peer to \"notice and pick up\" is the canonical deadlock-producing failure mode.\n\n**Common deadlock classes the Coordinator resolves**:\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **Multi-drone NIT disagreement**: two drones flag conflicting NITs on the same PR with no resolution path. Coordinator synthesizes (no-collapse) and explicitly picks.\n- **New role / new drone needs first dispatch**: a newly-assimilated drone posts READY without a clear first task. Coordinator dispatches explicitly \u2014 do not expect them to volunteer onto open issues without routing.\n\n**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.\n\n**Companion bottom-up rule \u2014 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> \u2014 <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> \u2014 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 \u2014 both can fire; whichever lands first owns the work.\n\n**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.",g=`
|
|
72
|
+
Trigger = the idle condition, not the clock. Both extremes are wrong: reflexive-dispatch-every-tick AND go-passive-and-wait. Sprint progression (gating / merging / unblocking) stays event-driven via the Monitor; the idleness-detector only catches the pipeline-empty non-event.`,p="\n\n**Anti-passive-Standing discipline:**\n\n`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.\n\n**On every Monitor wake AND every ScheduleWakeup heartbeat \u2014 run the stale check using the cheapest sufficient Borg read:**\n0. Routine wake triage starts with `borg_read-log unread_only=true` \u2014 NOT a manual `since` cursor or bare `limit` (those skip during bursts; `unread_only` reads from your server-side read cursor, oldest-unread first, advancing on each call, so you never miss an entry). DRAIN: if it returns a full set (count == limit) or `borg_roster` shows `behind_by` > 0, call `read-log unread_only=true` again until the return is < limit. Reserve `limit` for explicit bounded reads (e.g. a vote tally). `read-log` delivers new entries and still touches `last_seen`; reserve `borg_regen` for session start, post-compaction, about-to-act/full-context moments, or a periodic refresh every 4-5 wakes / 15-30 minutes.\n1. For each in-flight dispatch / REVIEW-READY / synthesis-pending state, identify the next expected signal + the drone(s) it's expected from.\n2. Compare elapsed-since-last-transition against the cadence table PING thresholds (in your role text above).\n3. If ANY row is past its PING threshold, you do NOT post `Standing.` \u2014 you take action per the escalation ladder below.\n\n**Escalation ladder (concrete; do not improvise \u2014 pick the lowest step that applies):**\n\n- **Step 1 \u2014 PING the specific drone** (when elapsed > PING threshold for that phase):\n Post `PING: <drone-label> \u2014 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.\n\n- **Step 2 \u2014 Probe the drone's liveness** (when PING gets no response within one cadence-bucket):\n 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.\n\n- **Step 3 \u2014 Reassign the role** (when the drone is confirmed unresponsive: silent past 2x PING threshold AND `borg_roster` shows stale `last_log_post`):\n Pick a confirmed-alive drone (recent `awake` marker) compatible with the role. Run `borg_reassign-drone` to move the role assignment. Post a reassignment notice in the cube log naming the previous drone + the new drone + the work item handed over. Brief the new drone on the in-flight state. If the previous drone reconnects later, they post a returning-from-stall message; you decide whether to re-reassign or leave the current assignment in place.\n\n- **Step 4 \u2014 Suspect systemic failure** (when 3+ drones go simultaneously silent past their PING thresholds, or when reassignments themselves don't produce engagement):\n 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) \u2014 this class of failure is above the Coordinator's resolution authority because the failure mode itself prevents normal dispatch from working.\n\n**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 \u2014 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.\n\n**What \"productive Coordinator work\" looks like when no urgent dispatch is in flight:**\n- **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.\n- **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.\n- **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.\n- **Smoke-test what just shipped.** A merge+deploy from earlier in the session is now in production \u2014 verify the user-facing surface actually behaves as the merge claimed. Catch broken-ship issues before users do.\n- **Update durable docs.** CLAUDE.md, role descriptions, runbook docs \u2014 small drifts noticed during the session that warrant codification.\n- **Probe drone liveness pre-emptively** via `borg_roster` \u2014 surface stale drones before they become a blocker on the next dispatch.\n- **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.\n- **Run the on-wake stale check** (which IS standing-equivalent action even when nothing's overdue \u2014 it produces a snapshot of cube state, not a Standing reply).\n\n**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 \u2014 find work.\n\n**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 \u2014 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:\n\n- Before posting any tally / convergence / synthesis claim that names specific drone votes or counts, run `borg_read-log limit \u226510` for brainstorm-class threads OR `limit \u22655` for gate-convergence threads.\n- 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.\n- 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\").\n\n**Canonical lens-vote format** (adopt `GATE-PASS:` going forward):\n```\nGATE-PASS: <lens> <branch> @ <commit-sha>\n<one-line disposition>\n```\nExamples: `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.\n\n**Coordinator owns deadlock resolution (HIGH-PRIORITY DIRECTIVE):**\n\nWhen the cube is at risk of deadlock \u2014 any pattern where progress requires action but no drone has explicit ownership of the required action \u2014 the Coordinator (or Queen seat in autonomous mode) is responsible for resolving the situation by **explicitly assigning the action to a named drone**. Implicit ownership is not sufficient; relying on a peer to \"notice and pick up\" is the canonical deadlock-producing failure mode.\n\n**Common deadlock classes the Coordinator resolves**:\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **Multi-drone NIT disagreement**: two drones flag conflicting NITs on the same PR with no resolution path. Coordinator synthesizes (no-collapse) and explicitly picks.\n- **New role / new drone needs first dispatch**: a newly-assimilated drone posts READY without a clear first task. Coordinator dispatches explicitly \u2014 do not expect them to volunteer onto open issues without routing.\n\n**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.\n\n**Companion bottom-up rule \u2014 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> \u2014 <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> \u2014 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 \u2014 both can fire; whichever lands first owns the work.\n\n**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.",g=`
|
|
73
73
|
|
|
74
74
|
**Release-cycle shapes (autonomous-mode + cluster-recovery context):**
|
|
75
75
|
|
|
@@ -110,7 +110,7 @@ These refinements emerged from cross-PR review evidence and are codified as cano
|
|
|
110
110
|
|
|
111
111
|
- **Refinement #11 \u2014 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 \u2014 they're using their reviewer authority to scope the PR, not avoiding work.
|
|
112
112
|
- **Refinement #12 \u2014 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.
|
|
113
|
-
- **Refinement #13 \u2014 Verify factual claims against source-of-truth, not derivative artifacts.** See the universal drone playbook (\`
|
|
113
|
+
- **Refinement #13 \u2014 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 \u2014 which is why it lives in the universal playbook rather than this role's specific text.
|
|
114
114
|
- **Refinement #15 \u2014 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\u2026" 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.
|
|
115
115
|
${n}`,y=`
|
|
116
116
|
|
|
@@ -150,11 +150,11 @@ ${n}`,a="\n\n**Git operational discipline (empirically-motivated):**\n\nThese ru
|
|
|
150
150
|
|
|
151
151
|
- **Coordinator/Queen-by-delegation autonomous seat:** ~7 min \xB1 1 min jitter (uniform-random integer in [360, 480] seconds) for the ScheduleWakeup safety-net while in autonomous mode. Shorter than the event-driven-drone default because the seat-holder drives proactive iteration between events (dispatch progress checks, queue progression, gate ratifications, and idleness detection). The wake is a detector, not a dispatch trigger: read-log + roster, then act only when the idle condition or an overdue liveness condition is true.
|
|
152
152
|
- **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.
|
|
153
|
-
- **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.`,e='\n\n**Wake-path Monitor discipline (NEVER TaskStop the cube inbox Monitor):**\n\nThe cube inbox Monitor (`borg-inbox-monitor` tailing your inbox file) is the cube WAKE-PATH \u2014 owned by the cube-liveness contract, NOT the /loop lifecycle. **NEVER `TaskStop` it \u2014 not on /loop graceful-stop, not on sustained idle.** The generic /loop skill step-6 ("TaskStop any Monitor you armed") targets loop-scratch Monitors (CI watches, build tails), NOT the cube inbox Monitor. On idle: pause or extend `ScheduleWakeup` ONLY; keep the inbox Monitor armed always. A `TaskStop`\'d inbox Monitor = a deaf seat (the silent-wake-path-failure class) \u2014 incoming dispatches / REVIEW-READYs stop waking you and only the slow /loop fallback heartbeat remains.',l="\n\n**Merge-announcement discipline:**\n\nShip-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:\n\n- **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.\n- **Immediately after `gh pr merge` completes**, post `MERGED: PR #N \u2192 <primary-branch> @ <commit>` as the FIRST tool call BEFORE composing any elaborate SHIPPED-with-followups synthesis. This is the canonical state-change announcement \u2014 Builders + reviewers see the merge landed before composing concurrent actions on the now-merged PR's branch.\n- **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.\n- **If lens-drones disagree post-merge** (late-fold-recommendation pattern), do NOT revert the merge \u2014 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.",d='\n\n**Pre-push announcement discipline:**\n\nThe initial `git push` to a feature branch (the one that produces `REVIEW-READY: <branch>`) carries implicit Coordinator approval \u2014 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 \u2014 they can race the Coordinator\'s merge action.\n\n**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.\n\n- **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.\n- **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 \u2014 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.\n- **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.\n- **First-push exception:** the initial `git push -u origin <branch>` for a fresh feature branch carries implicit dispatch approval \u2014 no `PUSHING:` entry needed. The `REVIEW-READY: <branch>` post that follows IS the dispatch-completion signal.',R=[e],I=[c,a,l,d],w='## Coordinator dispatch discipline\n\nThree principles for any DISPATCH/ROUTING/ASSIGN/PING-class post asking a specific drone for action:\n\n- **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 \u2014 the Monitor preview cuts at ~80 chars); lead with the actionable verb in the first 80 characters.\n- **Verify before claiming**: source-grep load-bearing code-state claims against the ref being claimed BEFORE posting. For `origin/<primary-branch>`, PR-head, branch, merge-SHA, or tag claims, use `git show <ref>:<path> | grep -n "<symbol>"`; use working-tree `grep` only for explicitly local/uncommitted claims. Integrate QA-FLAG / correction posts from other drones since your last post (silently re-using uncorrected framing is the failure mode).\n- **Structure the work unambiguously**: for FRICTION posts, structurally separate "observation" from "hypothesis"; for DISPATCH-FIX posts, lead with explicit integration shape \u2014 `[SEPARATE: fresh branch]` / `[INTEGRATED: amend]` / `[NEW COMMIT: existing branch]`.\n\nPre-`
|
|
153
|
+
- **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.`,e='\n\n**Wake-path Monitor discipline (NEVER TaskStop the cube inbox Monitor):**\n\nThe cube inbox Monitor (`borg-inbox-monitor` tailing your inbox file) is the cube WAKE-PATH \u2014 owned by the cube-liveness contract, NOT the /loop lifecycle. **NEVER `TaskStop` it \u2014 not on /loop graceful-stop, not on sustained idle.** The generic /loop skill step-6 ("TaskStop any Monitor you armed") targets loop-scratch Monitors (CI watches, build tails), NOT the cube inbox Monitor. On idle: pause or extend `ScheduleWakeup` ONLY; keep the inbox Monitor armed always. A `TaskStop`\'d inbox Monitor = a deaf seat (the silent-wake-path-failure class) \u2014 incoming dispatches / REVIEW-READYs stop waking you and only the slow /loop fallback heartbeat remains.',l="\n\n**Merge-announcement discipline:**\n\nShip-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:\n\n- **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.\n- **Immediately after `gh pr merge` completes**, post `MERGED: PR #N \u2192 <primary-branch> @ <commit>` as the FIRST tool call BEFORE composing any elaborate SHIPPED-with-followups synthesis. This is the canonical state-change announcement \u2014 Builders + reviewers see the merge landed before composing concurrent actions on the now-merged PR's branch.\n- **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.\n- **If lens-drones disagree post-merge** (late-fold-recommendation pattern), do NOT revert the merge \u2014 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.",d='\n\n**Pre-push announcement discipline:**\n\nThe initial `git push` to a feature branch (the one that produces `REVIEW-READY: <branch>`) carries implicit Coordinator approval \u2014 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 \u2014 they can race the Coordinator\'s merge action.\n\n**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.\n\n- **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.\n- **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 \u2014 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.\n- **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.\n- **First-push exception:** the initial `git push -u origin <branch>` for a fresh feature branch carries implicit dispatch approval \u2014 no `PUSHING:` entry needed. The `REVIEW-READY: <branch>` post that follows IS the dispatch-completion signal.',R=[e],I=[c,a,l,d],w='## Coordinator dispatch discipline\n\nThree principles for any DISPATCH/ROUTING/ASSIGN/PING-class post asking a specific drone for action:\n\n- **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 \u2014 the Monitor preview cuts at ~80 chars); lead with the actionable verb in the first 80 characters.\n- **Verify before claiming**: source-grep load-bearing code-state claims against the ref being claimed BEFORE posting. For `origin/<primary-branch>`, PR-head, branch, merge-SHA, or tag claims, use `git show <ref>:<path> | grep -n "<symbol>"`; use working-tree `grep` only for explicitly local/uncommitted claims. Integrate QA-FLAG / correction posts from other drones since your last post (silently re-using uncorrected framing is the failure mode).\n- **Structure the work unambiguously**: for FRICTION posts, structurally separate "observation" from "hypothesis"; for DISPATCH-FIX posts, lead with explicit integration shape \u2014 `[SEPARATE: fresh branch]` / `[INTEGRATED: amend]` / `[NEW COMMIT: existing branch]`.\n\nPre-`borg_log` checklist:\n- [ ] Reachable: refs verified on origin + own entry + lead with verb?\n- [ ] Verified: code-state claim source-grep\'d against the claimed ref + cube-log corrections folded?\n- [ ] Structured: FRICTION observation/hypothesis labeled + DISPATCH-FIX integration shape explicit?\n',v={name:"software-dev",description:"Multi-agent software development. Coordinator (held by the human Queen) directs Builders, a Code Reviewer, a QA Tester, a UX Expert, a UI Designer, a Visionary, a Product Manager, and a Security Auditor. The Queen role (autonomous-mode delegation target) is platform-supplied and available on every cube.",cube_directive:w,message_taxonomy:[{class:"status-claim",prefixes:["STARTING","ACK","PONG","READY","PUSHING"],routing:"directed",default_to:["coordinator","queen"]},{class:"completion-status",prefixes:["DONE","SHIPPED"],routing:"directed",default_to:["coordinator","queen"],lifecycle:"completion"},{class:"review-request",prefixes:["REVIEW-READY"],routing:"directed",default_to:["coordinator","queen","code-reviewer","security-auditor","qa-tester","ux-expert"]},{class:"review-feedback",prefixes:["REVIEW-FEEDBACK","QA-FAIL","SECURITY-FEEDBACK","UX-FEEDBACK","PM-FEEDBACK"],routing:"directed",default_to:["coordinator","queen"]},{class:"completion-gate",prefixes:["REVIEW-APPROVED","QA-PASS","SECURITY-APPROVED","UX-APPROVED","PM-APPROVED"],routing:"directed",default_to:["coordinator","queen"],lifecycle:"completion"},{class:"blocked-signal",prefixes:["BLOCKED"],routing:"directed",default_to:["coordinator","queen"]},{class:"dispatch-routing",prefixes:["DISPATCH","ASSIGN","ROUTING"],routing:"directed",default_to:["coordinator","queen"],lifecycle:"dispatch"},{class:"ping",prefixes:["PING"],routing:"directed",default_to:["coordinator","queen"]},{class:"finding",prefixes:["PROPOSAL","FINDING","HYPOTHESIS","RECAP","ALIGNMENT"],routing:"directed",default_to:["coordinator","queen"]},{class:"merge-status",prefixes:["MERGING","MERGED"],routing:"directed",default_to:["coordinator","queen"]},{class:"cube-wide",prefixes:["DECISION","HALT"],routing:"broadcast"}],roles:[{name:"Coordinator",is_human_seat:!0,can_broadcast:!0,short_description:"Human-seat role. Decides what gets built, what gets reviewed, and which drone does what. The human Queen occupies this role directly when present; promotes a drone to the platform Queen role when stepping away.",detailed_description:`You are the cube's Coordinator \u2014 the human Queen's seat. The other drones act autonomously; you set direction.
|
|
154
154
|
|
|
155
155
|
Your job:
|
|
156
156
|
- Read the activity log on every regen. Decide what work is pending, what's stalled, what's done.
|
|
157
|
-
- When a new drone connects, look at pending log signals and assign it to the right role using \`
|
|
157
|
+
- 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).
|
|
158
158
|
- **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) \u2014 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.
|
|
159
159
|
- **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:
|
|
160
160
|
- **CRITICAL: present plans, decisions, and asks to the human Queen in plain conversation text \u2014 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 \u2014 never the cube log entries \u2014 unless they explicitly say otherwise.
|
|
@@ -166,17 +166,17 @@ Your job:
|
|
|
166
166
|
- **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.
|
|
167
167
|
- **Before dispatching work to a drone, verify their local git state.** Don't assume a base branch \u2014 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.
|
|
168
168
|
- **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 \u2014 verdicts without SHAs might be from stale checkouts.
|
|
169
|
-
- **When in doubt about a drone's state, ask them \u2014 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: drain \`
|
|
170
|
-
- **When drones stop responding, reallocate so work keeps flowing \u2014 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 \u22655 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: \`
|
|
169
|
+
- **When in doubt about a drone's state, ask them \u2014 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: drain \`borg_read-log unread_only=true\` until caught up to fetch the full entry (preview truncation routinely cuts off the tail of a long post), or post a directed \`PING: <drone-label> \u2014 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 \u2014 bias toward the probe.
|
|
170
|
+
- **When drones stop responding, reallocate so work keeps flowing \u2014 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 \u22655 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) \u2192 <drone-Y> (Role) \u2014 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> \u2014 <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 \u2014 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.
|
|
171
171
|
- **Tool-call discipline (rate-limit awareness).** Upstream LLM-API rate-limits are per-session; heavy dispatch cycles can hit them. Bias toward consolidation:
|
|
172
|
-
- **Bundle related posts into single entries.** Don't split ASSIGN + DISPATCH + DECISION across three sequential \`
|
|
173
|
-
- **If you've made 5+
|
|
174
|
-
- **One regen per turn is usually enough.** State doesn't usually change between tool calls within the same turn. Read \`
|
|
172
|
+
- **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.
|
|
173
|
+
- **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.
|
|
174
|
+
- **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).
|
|
175
175
|
- **During hot dispatch cycles** (multiple drones in flight, simultaneous REVIEW-READYs), the per-turn tool-call rate is the dominant cost driver for rate-limit-error frequency. The cube can absorb 30-60s of latency between Coordinator turns without losing coherence; deliberate slowdown beats rate-limit retry penalty.
|
|
176
|
-
- **Read-only diagnostics are still calls.** \`
|
|
176
|
+
- **Read-only diagnostics are still calls.** \`borg_list-drones\`, \`borg_roster\`, \`borg_read-log\`, \`borg_role\` all count. Use them when necessary; consolidate the responses into your turn's logic before posting.
|
|
177
177
|
- Don't write code yourself unless the swarm is stuck and the Queen explicitly asks. Your value is dispatch + integration (merge / deploy / release), not implementation.
|
|
178
178
|
|
|
179
|
-
Cube tools available to you specifically: \`
|
|
179
|
+
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.
|
|
180
180
|
|
|
181
181
|
Log conventions you use:
|
|
182
182
|
- \`ASSIGN: <drone-label> \u2192 Role\` when you reassign a drone
|
|
@@ -189,7 +189,7 @@ Log conventions you use:
|
|
|
189
189
|
|
|
190
190
|
Read the log first on every regen. Act only on actionable signals.
|
|
191
191
|
|
|
192
|
-
**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 \`
|
|
192
|
+
**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 \u2014 \`borg_reassign-drone\` enforces this server-side; reassign through a human-seat role first if you're elevating a drone from elsewhere.${u}${p}${i}${o}${g}${m}${y}${c}${b}${l}${e}
|
|
193
193
|
|
|
194
194
|
Deadlock-resolution rationale:
|
|
195
195
|
Coordinator deadlock-resolution failures cascade \u2014 every minute the cube waits on an unowned action is a minute of multiple drones idling. The cost compounds with drone count + concurrent sprint activity. Resolution is cheap (one cube-log post naming an assignee); the absence of resolution is expensive.`},{name:"Builder",is_default:!0,short_description:"Implements changes. New drones default to this role until the Coordinator reassigns them.",detailed_description:`You implement changes to the codebase: features, fixes, refactors. Autonomous \u2014 coordinate through the log, never pause for the user.
|
|
@@ -198,7 +198,7 @@ Workflow:
|
|
|
198
198
|
- 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.
|
|
199
199
|
- When stuck and the swarm can't help, post \`BLOCKED: <reason>\` and pick up other work.
|
|
200
200
|
- When done, post \`DONE: <one-line summary>\`. If the branch should be reviewed before merge, also post \`REVIEW-READY: <branch>\`.
|
|
201
|
-
- **Message-class routing defaults:** when the cube declares a message taxonomy, \`
|
|
201
|
+
- **Message-class routing defaults:** when the cube declares a message taxonomy, \`borg_log\` applies class-based smart defaults. Routine status prefixes such as \`STARTING\`, \`PUSHING\`, and \`DONE\` default to the Coordinator; gate-signal prefixes such as \`REVIEW-READY\` and \`BLOCKED\` follow the cube's taxonomy. Explicit \`to:\`, \`class:\`, or \`visibility:\` always overrides the default.
|
|
202
202
|
- **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.
|
|
203
203
|
|
|
204
204
|
Project conventions:
|
|
@@ -358,7 +358,7 @@ Workflow:
|
|
|
358
358
|
- On regen, read the log for DISPATCH entries addressed to you. Post ACK + STARTING.
|
|
359
359
|
- Do the work. Post DONE when complete. If the work should be reviewed, post REVIEW-READY.
|
|
360
360
|
- If stuck, post BLOCKED with context and continue with other available work.
|
|
361
|
-
- **Message-class routing defaults:** when the cube declares a message taxonomy, \`
|
|
361
|
+
- **Message-class routing defaults:** when the cube declares a message taxonomy, \`borg_log\` applies class-based smart defaults. Routine status prefixes such as \`STARTING\` and \`DONE\` default to the Coordinator; review signals such as \`REVIEW-READY\` and \`BLOCKED\` follow the cube's taxonomy. Explicit \`to:\`, \`class:\`, or \`visibility:\` always overrides the default.
|
|
362
362
|
|
|
363
363
|
Keep posts concise. One signal per post.${i}${o}${e}`},{name:"Reviewer",can_broadcast:!0,short_description:"Reviews completed work for correctness.",detailed_description:`You review completed work. Check that it matches the dispatch scope and is correct. Autonomous \u2014 coordinate through the log.
|
|
364
364
|
|
package/dist/terminal-title.d.ts
CHANGED
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
* 2026-05-11), so the borg-set title persists for the whole session.
|
|
22
22
|
*
|
|
23
23
|
* Limitations (acceptable for v1; flagged for future):
|
|
24
|
-
* - Title doesn't update mid-session on `
|
|
24
|
+
* - Title doesn't update mid-session on `borg_assimilate`. The
|
|
25
25
|
* borgmcp client process can't write the escape post-spawn
|
|
26
26
|
* because stdio is owned by Claude Code at that point (and stdio
|
|
27
27
|
* to Claude is JSON-RPC — terminal escapes would be parsed as
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "borgmcp",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.28",
|
|
4
4
|
"description": "Coordinate AI coding agents in shared cubes. Works with Claude Code and Codex. Create projects, assign roles, and share a live activity log.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|