Decisions
Governance
Decision log (41)
| Record | Ruling | Domain | Shape | Status | Review by |
|---|---|---|---|---|---|
| GOV-0041 | The merger App keeps issues: read (GOV-0028 unchanged); the planner closes the still-open closing issues of merged PRs in its daily run | security | authoritative | in-force | 2027-02-28 |
| GOV-0040 | The department goal is done when each open Goal's capability is shown once, on real work or in a scratch-repo drill; the 10-working-day window, under-5-owner-acts budget and Dec 4 day-30 checks are dropped; owner acts are counted and reported, never a gate; the readiness review (GOV-0035) still ends it; amends GOV-0030 | product-scope | authoritative | in-force | 2027-02-28 |
| GOV-0039 | When the launcher starts a session in another org repo, it supplies CLAUDE.md and roles/<role>.md from this repo's origin/main; that repo's own CLAUDE.md still loads for its code conventions, and where the two disagree ours wins; how the files are passed in is the stage 3 builder's | architecture | authoritative | in-force | 2027-02-28 |
| GOV-0038 | The productswarm-planner App writes the org Project's Spent field with the org Projects permission it already holds, setting it from swarm spent in its daily run; no new App or host key; the engine and watcher get no Project write | security | authoritative | in-force | 2027-02-28 |
| GOV-0037 | The planted-defect gate's throwaway issue is made go by the owner's ready right after the planted PR opens, and the owner closes the PR unmerged after the reviewer's first review; if a planted PR is ever merged, the analyst opens the revert at once and the gate is a fail; GOV-0021's pass rule is unchanged | product-scope | authoritative | in-force | 2027-01-31 |
| GOV-0036 | One launcher starts sessions on go work in every org repo: launch entries carry owner/name plus number, a clone per repo, swarm launch owner/name#N, holders, opener and stop hook keyed on repo plus number; a bare #N keeps meaning this repo; built in #820's stages; one loop and one GOV-0010 ceiling for the org | architecture | authoritative | in-force | 2027-02-28 |
| GOV-0035 | The goal's readiness review is for the first outside project, unnamed until the owner names one, not the finance and scenario planner; the checklist's second-repo, private-data and correctness checks (9–20) stay as the bar; GOV-0030's done test and order are unchanged; amends GOV-0030 | product-scope | authoritative | in-force | 2027-01-31 |
| GOV-0034 | An issue that is go under GOV-0031 (an owner-opened Goal or Area above it, or the owner's most recent ready) counts as approved for GOV-0027's standing grant; the grant's other conditions stay; the merger shadows "would merge (standing grant)" for one day or 10 PRs before merging under this reading; amends GOV-0027 | security | authoritative | in-force | 2027-01-31 |
| GOV-0033 | The hosted engine gets no daily, per-mission or monthly spend total for now: per-run caps (GOV-0012) and the concurrency ceiling (GOV-0010) stay its only limits, and the Console workspace's $1,000 monthly limit is the only total; a total later needs a new spend question | spend | authoritative | in-force | 2027-01-31 |
| GOV-0032 | Adopt operating model v2 in full: GitHub is the record; the engine (webhooks, watcher, dispatcher, merger through a merge queue, hosted Desk, remote MCP server) moves to the owner's VPS; one org Project with a Product field, issue types and sub-issues is the source of truth; Area, Mission and Goal scopes with reporting contracts; a learning loop with a librarian role; a dedicated Console key ($1,000/month, caps ~$45/day, $150/mission, stop at $900); retiring PLAN.md is GOV-0031 | architecture | authoritative | in-force | 2027-01-31 |
| GOV-0031 | PLAN.md is retired; an implementation issue is go when a swarm App or the owner opened it, it sits under an open Goal or Area the owner opened (any sub-issue depth, any org repo), no blocked-by issue is open and the owner hasn't vetoed it; owner-applied ready stays a go; supersedes GOV-0026, amends GOV-0027 and GOV-0030 | governance | authoritative | in-force | 2027-02-28 |
| GOV-0030 | productswarm's goal is an AI team run like a department: a lead keeps PLAN.md's milestones with the owner, the swarm works under delegated authority, daily report and weekly check-in; done at 10 working days under 5 owner acts a day, then a readiness review for the finance planner (C); B after a named peer asks; governance is infrastructure; work cites a milestone; amends GOV-0015, GOV-0001's context | product-scope | authoritative | in-force | 2027-01-31 |
| GOV-0029 | swarm watch gains [daily] (planner writes the daily report each working day, check-in on Mondays), [ask] (owner's Ask: <role>: on the report issue starts that role once), [research] (owner's or planner's Research: starts the analyst once), and call-ins on approved-milestone issues; each has a swarm.toml switch, within GOV-0010/0012/0013; amends GOV-0009, GOV-0023 | product-scope | authoritative | in-force | 2027-01-31 |
| GOV-0028 | The productswarm-merger App holds only contents: write, pull_requests: write, checks: read, issues: read, metadata: read (no workflows, administration, actions); it is the only extra bypass actor on the main ruleset, in "pull_request" mode; CODEOWNERS and the required owner review stay; its key lives only in merger.yml's Actions secret; replaces GOV-0022's stage 3 | security | authoritative | in-force | 2027-01-31 |
| GOV-0027 | GOV-0022's merger merges a PR under an approved milestone once reviewer-approved at head, tests pass, no overstep, no protected path, under the size limit (no merge:agent); a protected-path PR once the owner approved it at head, except GOVERNANCE.md, jurisdictions.yml and workflows; shadow one day or 10 PRs; amends GOV-0022, GOV-0011 | security | authoritative | in-force | 2027-01-31 |
| GOV-0026 | An implementation issue is go when the owner's merged PLAN.md has its open milestone, a swarm App or the owner opened it, its waits-on issues are closed and the owner hasn't vetoed it (hold, close, comment); the lead opens and orders them; gov:questions keep ready/gov:ruled; amends GOV-0006 and GOV-0009 | governance | authoritative | superseded | 2027-01-31 |
| GOV-0025 | swarm watch may publish its state as the owner's gh login only by replacing the body of one [watch] issue when the state changed: no comments, labels or other writes, body from templates only, and the desk's "owner last acted" ignores those edits | security | authoritative | in-force | 2027-01-31 |
| GOV-0024 | Every swarm App is a trusted author for the Actions reviewer: AUTHORS in launcher/actions_review.py is read from identities.agents in jurisdictions.yml; scope limits stay in role prompts, the rubric and CODEOWNERS; amends GOV-0017's trust list | security | authoritative | in-force | 2027-01-31 |
| GOV-0023 | A swarm App or the owner may post Call in: <roles>: <why> on a ready issue; the watcher starts each named role once per call (no self-call, at most 2 calls per issue per day, within GOV-0010/0012/0013, swarm.toml off switch); a called-in role counts as asked in (§8) and posts one comment | product-scope | authoritative | in-force | 2027-01-31 |
| GOV-0022 | A PR merges without the owner's click only when the owner labelled its issue merge:agent and code in the reconciler, with an App no session holds, finds every condition passes (builder author, approval at head, no overstep, tests, no protected path, size); staged, shadow first; amends GOV-0006, GOV-0011, GOV-0013 | security | authoritative | in-force | 2027-01-31 |
| GOV-0021 | Reviewer requests changes only for a numbered block-list finding with evidence that the builder can fix inside the PR's issue; overstep outranks red; draft, not intent, skips review; amends GOV-0011's red and amber; eval gate is an unannounced planted-defect PR | product-scope | committee | in-force | 2027-01-31 |
| GOV-0020 | Actions reviewer runs with secrets start only from a reconciler on main that reads repo state (GOV-0017's trust list); PR events may only nudge it; amends GOV-0017's and GOV-0019's pull_request trigger; GOV-0018 unchanged | security | authoritative | in-force | 2027-01-31 |
| GOV-0019 | The Actions reviewer runs on pull_request pushes (plus workflow_dispatch), one concurrency group per PR with cancel-in-progress, never on its own reviews or comments, and skips a reviewed head; a swarm.toml switch makes swarm watch leave [review] to it; the owner commits the workflow | ci-and-workflows | authoritative | in-force | 2027-01-31 |
| GOV-0018 | The reviewer App's key moves to secrets of a default-branch-only Actions environment; the job mints a repo-only token with pull_requests: write, contents: read, issues: read; rotate if anyone but the owner changes the environment or workflow | security | authoritative | in-force | 2027-01-31 |
| GOV-0017 | Actions reviewer runs start only on pull_request for same-repo, non-draft PRs by a swarm App or the owner; a no-secrets check job gates the job with secrets; never pull_request_target, issue_comment or workflow_run on untrusted input | security | authoritative | in-force | 2027-01-31 |
| GOV-0016 | A reviewer run in GitHub Actions prints only result, subtype, num_turns and total_cost_usd to the public job log; no transcript, no artifact | security | authoritative | in-force | 2027-01-31 |
| GOV-0015 | v3 is quality evals (B) → needs-you digest (F) → GitHub Actions runs (C, reviewer first); plan only B for now, C sub-questions when their stage is next, F and C after the owner reviews B | product-scope | authoritative | in-force | 2027-01-31 |
| GOV-0014 | Sessions swarm watch starts run one-shot (claude -p) with a Stop hook on a per-role done-condition and record their cost in watch.json; owner-started sessions stay interactive | architecture | authoritative | in-force | 2027-01-31 |
| GOV-0013 | Headless runs swarm watch starts use --permission-mode auto plus --disallowedTools for gh pr merge and label edits; owner-started sessions unchanged | security | authoritative | in-force | 2027-01-31 |
| GOV-0012 | Runs swarm watch starts get --max-budget-usd from the role's spend_cap_usd plus a --max-turns ceiling, and end at either; owner-started sessions stay warn-only (GOV-0008) | security | authoritative | in-force | 2027-01-31 |
| GOV-0011 | Reviewer uses request-changes / comment / approve (approve = rubric passed, never a merge decision); swarm watch starts the builder on requested changes, at most 2 rounds per PR, then the owner | product-scope | authoritative | in-force | 2027-01-31 |
| GOV-0010 | swarm watch checks every 5 minutes, runs at most 2 loop-started sessions at once, and starts only roles with a spend_cap_usd; limits live in swarm.toml | spend | authoritative | in-force | 2027-01-31 |
| GOV-0009 | v2 is swarm watch: a local, foreground, start-only loop that starts the right session on owner-applied ready/gov:ruled and new PR heads; never stops, labels, merges or comments | product-scope | authoritative | in-force | 2027-01-31 |
| GOV-0008 | v1 spend cap is warn-only: flag "over cap" in swarm ls and the needs-you list; the launcher never stops a session without the owner | security | authoritative | in-force | 2027-01-31 |
| GOV-0007 | When the owner adds gov:ruled to a question needing a record, docs opens the ruling PR; the owner merges | governance | authoritative | in-force | 2027-01-31 |
| GOV-0006 | Owner-applied gov:ruled = decided, ready = go; sessions take only ready issues; labels count only if the owner added them | governance | authoritative | in-force | 2027-01-31 |
| GOV-0005 | v1 is a lightweight local launcher (manifest, up/ls/stop, issue handoff, spend cap, needs-you list, reviewer by default) | product-scope | authoritative | in-force | 2027-01-31 |
| GOV-0004 | GOV-0002 and GOV-0003 hold unchanged for a public repo; everything posted to GitHub is public | security | authoritative | in-force | 2026-11-30 review due soon |
| GOV-0003 | Heartbeat events go to comments on a per-session tracking issue (interim; prompt text stays local) | architecture | authoritative | in-force | 2026-11-30 review due soon |
| GOV-0002 | Heartbeat events: minimal fields, tool names, token counts; prompt text local-only, redacted, truncated | security | authoritative | in-force | 2026-11-30 review due soon |
| GOV-0001 | Follow GOVERNANCE.md for any decision outside your task | governance | authoritative | in-force | 2027-01-31 |
Open gov questions (4)
By shape: authoritative 3, advice 1 · by domain: architecture 2, dependencies 1, security 1
| Question | Domain | Shape | Blocking | Opened | Time to live | Sessions waiting |
|---|---|---|---|---|---|---|
| #936 GOV-Q: May the scratch repo's hello.py add colorama as a dependency for scratch#9? gov:ruled, ready | dependencies | advice suggested | yes | 4d ago | 2026-11-19 3d left | none |
| #991 GOV-Q: Should the Effort mix classifier be a new top-level classify/ module, with its data, recordings and reports in this public repo? (C1, #987) gov:ruled, ready | architecture | authoritative suggested | yes | 3d ago | 2026-11-27 11d left | none |
| #992 GOV-Q: Which credential, where, which model and what per-run cap for the Effort mix classifier's model calls? (R5, #987) gov:ruled, ready | security | authoritative suggested | yes | 3d ago | 2026-11-27 11d left | none |
| #1021 GOV-Q: Should the Effort mix cache (classify/cache/effort.json) carry each PR's Goal, resolved by the classifier, as #1019's schema 1 does? (#987) gov:ruled, ready | architecture | authoritative suggested | no | 2d ago | 2026-11-21 5d left | none |
Lapsed questions
None open or closed in the last 14 days.
Committees
No open committees.
Past committees
3 ended
#464 GOV-Q: What is productswarm's next bet, and what does it change about where we're headed?
Discussion #465 · convened 2026-11-05 → round 1 2026-11-05 → round 2 2026-11-05 → summary 2026-11-05 → ratified → record
| Seat | Role | Model | Evidence |
|---|---|---|---|
| proposer | planner | claude-opus-5-5 | `PRODUCT.md`, the v1–v3 records and how each version's goals turned out; what was planned and dropped (#167) |
| challenger | builder | claude-sonnet-5-5 | what was actually built and what got used afterwards, against what was planned; what was hard to build |
| domain reviewer | designer | claude-opus-5-5 | what the owner sees and does: the desk, the digest and templates, where the owner's attention goes; and what a second user would meet on day one |
§7.2 diversity met: 2 models, 3 evidence bases
| Member | Round 1 | Round 2 |
|---|---|---|
| proposer | 11-05 18:15 UTC | 11-05 19:00 UTC |
| challenger | 11-05 18:44 UTC | 11-05 19:02 UTC |
| domain reviewer | 11-05 18:50 UTC | 11-05 19:05 UTC |
no majority after round 2 · rounds used: 2 of 3 · nobody over 6 posts a day
#439 GOV-Q: What should the governance desk show the owner first, and what should it leave out?
Discussion #441 · convened 2026-11-05 → round 1 2026-11-05 → round 2 2026-11-05 → summary 2026-11-05 → ratified → record
| Seat | Role | Model | Evidence |
|---|---|---|---|
| proposer | planner | claude-opus-5-5 | open `gov:question` issues and decision records, including how long each waited for the owner; `governance/INDEX.md` |
| challenger | builder | claude-opus-5-5 | what it built, what was blocked, and where it waited on a ruling or on `ready` |
| domain reviewer | reviewer | claude-opus-5-5 | its review history, and the issues that reached the owner through overstep (GOV-0021) |
§7.2 diversity met: 1 model, 3 evidence bases
| Member | Round 1 | Round 2 |
|---|---|---|
| proposer | 11-05 15:18 UTC Option 3: owner block first, then #397's live panels | 11-05 15:23 UTC Option 3: owner block first, as amended by builder and reviewer |
| challenger | 11-05 15:19 UTC Option 3: owner block first, sorted by what it unblocks | 11-05 15:23 UTC Option 3: owner block first, as in the proposer's Round 2 list, with two precis… |
| domain reviewer | 11-05 15:22 UTC Option 3: owner block first, with oversteps at its top and every open PR shown… | 11-05 15:24 UTC Option 3: owner block first, as in the proposer's Round 2 list, with the challe… |
no majority after round 2 · rounds used: 2 of 3 · nobody over 6 posts a day
#311 GOV-Q: What should make the reviewer request changes rather than comment or approve?
Discussion #314 · convened 2026-11-04 → round 1 2026-11-04 → round 2 2026-11-04 → summary 2026-11-04 → ratified 2026-11-04 → record GOV-0021 2026-11-04
| Seat | Role | Model | Evidence |
|---|---|---|---|
| proposer | reviewer | claude-opus-5-5 | its own review history, `roles/reviewer.md`, GOV-0011 |
| challenger | builder | claude-sonnet-5-5 | the reviews it received and how it responded; GOV-0011's `[respond]` loop |
| domain reviewer | planner | claude-opus-5-5 | the B eval: `evals/README.md`, `evals/results.md` (#175's "Inputs for a committee"), the C stage 2 bar |
§7.2 diversity met: 2 models, 3 evidence bases
| Member | Round 1 | Round 2 |
|---|---|---|
| proposer | 11-04 14:18 UTC Option 3, with changes 1 and 2 (3b) | 11-04 14:23 UTC Option 3 as 3c |
| challenger | 11-04 14:20 UTC Option 3, as the proposer's 3b, plus these four amendments (3c) | 11-04 14:24 UTC Option 3 as 3c+E |
| domain reviewer | 11-04 14:22 UTC Option 3 as 3c | 11-04 14:25 UTC Option 3 as 3c+E |
dissent: proposer · rounds used: 2 of 3 · nobody over 6 posts a day