Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

docs: feature design rules in AGENTS.md, and why Swarm's state had to be redone (#1782)

Jacob Pham5fe200789aac
diff --git a/AGENTS.md b/AGENTS.md
index 641c1cd96..bd7b72d90 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -66,3 +66,22 @@ For product names, terminology, and visible copy, follow the
Avoid starting candidates while implementation is still changing. The release
automatically reuses matching Desktop build inputs/version and otherwise builds
normally; unrelated CLI, firmware or documentation merges do not force a rebuild.
+
+# Feature design rules
+
+Details, incidents and a checklist to copy: [docs/feature-design-rules.md](docs/feature-design-rules.md).
+
+1. Every spec that stores, syncs or exposes data has a **Design** section. It answers each
+ line briefly, or says "N/A because ...":
+ - growth: what deletes it;
+ - concurrency: at what level it locks;
+ - read cost: read only what changed;
+ - scale: 10x, and the metric that warns first;
+ - compatibility: old and new clients;
+ - migration + rollback;
+ - audience: the server enforces it;
+ - identity: never use the machine owner's login;
+ - failure: nothing breaks without saying so;
+ - platforms.
+2. Review the design again when a measured limit is less than 10x away, or when the same
+ bug needs patching a second time.
diff --git a/docs/feature-design-rules.md b/docs/feature-design-rules.md
new file mode 100644
index 000000000..51ea20759
--- /dev/null
+++ b/docs/feature-design-rules.md
@@ -0,0 +1,184 @@
+# Feature design rules
+
+Ken's rules, set on 2026-10-27; [AGENTS.md](../AGENTS.md#feature-design-rules) carries the short version. This is
+the detailed version: what a good answer to each line contains, and the incidents behind it. Incident ids (D1–D12)
+point to the [post-mortem of #1755](postmortems/2026-10-27-1755-design-rework.md), which has the evidence and the
+cost of each.
+
+**Why:** Swarm had to redo its state storage (#1726) because the original design (#1405) never asked how the data
+grows, who writes concurrently, or how much a client reads per poll. 31 later PRs in seven days changed the same JSON state
+until it reached 1.16 MB and returned 500s. The first fix (#1722) only added a retry. The privacy bugs (#1748, #1751),
+old clients getting 426 (#1755) and teammates' work running as the machine owner (the Team account work) were all
+found late for the same reason: the spec had no design-check step.
+
+## Rule 1. Every spec that stores, syncs or exposes data has a Design section
+
+The Design section answers each line below briefly, or says "N/A because …". It is part of the spec, and a design
+review checks each line before build groups start. A feature added to a branch after its design was approved is a
+spec of its own and needs its own Design section; a scratchpad doc in chat is not one (D8, D9, D10).
+
+### 1. Growth: what deletes it
+
+Say what makes each record leave the active set or the database, and at what size it stops working without that.
+
+A good answer:
+- gives a lifecycle table per record (create, update, finish, lost, cancel, leave and rejoin, delete, purge,
+ recreate under the same key), with no empty cell;
+- for each archive or expiry state, lists every reader of "all records" and says what it does with the archived
+ ones.
+
+Incidents:
+- #1405's Swarm state only grew until #1726.
+- D5: `dormant` broke revocation, reports, route history and the archived list.
+- D6: a key recreated after a purge reset its version.
+
+### 2. Concurrency: at what level it locks
+
+Name the unit a write locks, and what each write reads and must guard.
+
+A good answer:
+- lists each invariant with what keeps it on every path: commands, sweeps and liveness checks, machine reports,
+ migration, rollback, and failure;
+- makes a decision taken outside a command guard what it read;
+- runs the lock table against the goal (for example "no conflicts between groups") on a thin end-to-end slice
+ before groups split.
+
+Incidents:
+- #1405 locked the whole Swarm; #1722 retried instead.
+- D7: the touch table would have brought the conflicts back.
+- D8b: a liveness loss did not guard the machine report it was judged from.
+- D9: two registrations raced.
+
+### 3. Read cost: read only what changed
+
+State, for each read path, what it may send and what it may load from the database, at a named size. A test asserts
+both. "Only what changed" includes removals: a reader must learn that something it held left.
+
+Incidents:
+- #1405 sent the full state on every poll.
+- D1: hosts missed changes that removed something.
+- D2: every host tick resent its roster.
+- D3: reads loaded 1.17–2.3 MB to send 3 KB, and a new group was needed.
+
+### 4. Scale: 10x, and the metric that warns first
+
+Say what happens at ten times today's largest case (people, agents, records, size), and which measured number shows
+the limit coming before users do. Measure it on the thin slice, not only at integration.
+
+Incidents:
+- Nothing warned before the 1.16 MB Swarm returned 500s (#1722).
+- D3: database bytes were not measured until group 6.
+- D2: host tick cost showed only in group 5's end-to-end run.
+
+### 5. Compatibility: old and new clients
+
+Say what an old client sees, what a client sees from an older or newer server during a rolling deploy, and what
+every existing reader does with a new field or state. "Every existing reader" means a search of the code, with one
+line per reader. "Not active" is not an answer.
+
+Incidents:
+- #1755: every old client got 426, so all clients had to release together.
+- D4: changes sent a kind that first loads hid during a rolling deploy.
+- D8a, D8c, D8d and D8f: `lost` was unknown to decisions, the light loader, routing and run records.
+
+### 6. Migration and rollback
+
+Give the order of deploys and migration. Say what the previous release does with every new field and state if you
+roll back. Name the production data the migration was checked against: an isolated restore of the production backup
+before the feature branch merges, or the owner's no and the read-only anomaly queries run instead. Check the rollback
+section again whenever scope grows.
+
+Incidents:
+- D10: rollback would have exposed private chats and misread lost work.
+- D11: history from deleted conversations failed the production migration after the merge.
+
+### 7. Audience: the server enforces it
+
+The server decides who can read each record, in one predicate that every read path calls. List every place a copy of
+private data can end up, and the guard on each one:
+- API reads, change feeds, stubs and tombstones;
+- notifications and mentions;
+- an agent's terminal screen and scrollback once the data is delivered to it;
+- shares, including ones made outside a Swarm;
+- the same session in another Swarm;
+- logs and stored observations;
+- what a rolled-back release would show.
+
+Incidents:
+- #1748 and #1751 (D10 and D9): private chats reached the previous release and the PM's terminal.
+- D12: a person who rejoined got a chat they could no longer read.
+- D4 and D8c: a second read path applied different filters.
+- The dormant-stub leak, which the design review caught.
+
+### 8. Identity: never use the machine owner's login
+
+Work for one person never runs as another person: not their OS account, git login, engine subscription or session.
+Say which identity each action runs as on a shared machine, and what happens when that identity is missing (refuse
+and say so, never fall back to the owner).
+
+Incident: before the Team account work (#1688–#1705), teammates' agents ran as the machine owner, with full
+permissions and the owner's git login. That was 18 of 113 agent starts in one live Swarm, 21–23 Oct (from
+`docs/plans/2026-10-24-swarm-team-account.md`).
+
+### 9. Failure: nothing breaks without saying so
+
+For each way the feature can fail (a machine offline, a session closed, a limit hit, a step refused, a write lost),
+say who notices, what the person sees, and how the record recovers. A failure state needs its lifecycle (line 1) and
+its readers (line 5) like any other.
+
+Incidents:
+- D8f: 16 lost tasks left their agents silently "busy" for good, in production.
+- D8: `lost` needed six fixes.
+- #1744 had to make refused starts fail with a reason, where before they waited in silence.
+
+### 10. Platforms
+
+Name the platforms it runs on (macOS, Windows, Linux, web, phone), and what differs or is left out on each.
+
+Incidents:
+- #1722 found a Windows-only failure: a narrow pane hid Claude Code's composer.
+- #1743 left Windows machines out of routing for now.
+
+## Rule 2. Review the design again when a limit is close or a bug comes back
+
+Review the design again, with the same ten lines, when either of these happens:
+- a measured limit is less than 10x away;
+- the same bug needs patching a second time.
+
+A retry, a cap or a second patch of the same thing is the signal, not the fix.
+
+Incidents:
+- #1722 retried a 1.16 MB Swarm. That Swarm's 195 groups were already within 13x of the 16 MB document limit
+ (about 2,500 groups, per #1726), and its write conflicts had already hit.
+- D1: the host wake-up was patched twice.
+- D5: the dormancy rule was corrected twice.
+- D8: `lost` was patched six times.
+
+## Design checklist (copy into the spec)
+
+Each line takes about a minute to check. Either the spec answers it, or says why it doesn't apply.
+
+```markdown
+## Design (docs/feature-design-rules.md)
+
+Reviewed revision: ______ Reviewer (another engine): ______ Each line: answered / N/A because …
+
+1. Growth: what deletes each record; lifecycle table, no empty cells. [ ]
+2. Concurrency: what a write locks; each invariant's keeper on every path,
+ sweeps and failures included. [ ]
+3. Read cost: per read path, bytes sent and bytes loaded at a named size, with a test;
+ removals reach readers. [ ]
+4. Scale: what happens at 10x; the metric that warns first; measured on a thin slice. [ ]
+5. Compatibility: old clients, rolling deploys, and every existing reader of each new
+ field or state (from a search of the code). [ ]
+6. Migration and rollback: order; what the previous release does with each new field;
+ checked on a production restore (or the owner's no plus anomaly queries). [ ]
+7. Audience: one server predicate on every read path; every copy of private data
+ has its guard named. [ ]
+8. Identity: what each action runs as; never the machine owner's login; refuse
+ when it's missing. [ ]
+9. Failure: who notices each failure, what the person sees, how it recovers. [ ]
+10. Platforms: where it runs, and what differs. [ ]
+
+Review again when a measured limit is under 10x away, or the same bug needs a second patch.
+```
diff --git a/docs/postmortems/2026-10-27-1755-design-rework.md b/docs/postmortems/2026-10-27-1755-design-rework.md
new file mode 100644
index 000000000..8a9269065
--- /dev/null
+++ b/docs/postmortems/2026-10-27-1755-design-rework.md
@@ -0,0 +1,294 @@
+# Post-mortem: why Swarm's state was redone, and what #1755 redid
+
+Date: 2026-10-27. Author: Theo (Builder), from the PR, commit and review records. Root cause and rules: Ken. Rules:
+[Feature design rules](../feature-design-rules.md), short version in [AGENTS.md](../../AGENTS.md#feature-design-rules).
+
+## Root cause
+
+Swarm had to redo its state storage (#1726) because the original design (#1405, merged 2026-10-19) never asked
+three questions: how the data grows, who writes concurrently, and how much a client reads per poll. The spec had no
+design-check step.
+
+- **Growth, concurrency and read cost were never designed.**
+ - Each Swarm was one MongoDB document. Its whole state was one JSON field under one revision.
+ - Every command rewrote all of it, and every client poll downloaded all of it.
+ - Finished work never left the document.
+- **Later features kept adding to it.** In the seven days after #1405, 31 PRs changed the same state model
+ (`backend/src/superTabs/model.ts`): routing, team roster, private projects, attachments, decisions, the Reviewer
+ role, owner rules, custom roles, the Leads conversation, local models, and more.
+- **It failed on 2026-10-26.** One Swarm reached 1.16 MB with 195 work groups and returned 500s on `agent.add`
+ from write conflicts (#1726). The first fix, #1722, only added retries and `503 SWARM_BUSY`. It eased the
+ symptom, not the cause.
+
+Other problems were found late for the same reason. No design step asked the question that would have caught them:
+
+| Found late | The question nobody asked |
+|---|---|
+| Private chats reaching the PM's terminal and the previous release (#1751, #1748; D9, D10 below) | audience: the server enforces it, on every copy |
+| Every old client getting 426 at release, so all clients had to update together (#1755) | compatibility: old and new clients |
+| Teammates' agents running as the machine owner, with the owner's git login: 18 of 113 agent starts in one live Swarm, 21–23 Oct. Fixed by the Team account work (#1688–#1705, `docs/plans/2026-10-24-swarm-team-account.md`). | identity: never use the machine owner's login |
+
+The twelve incidents below are the same failure inside the redo itself. #1726 did have a design and a design
+review, and that review caught six problems before any code. But the design lines that later broke were not on its
+list, and work added after approval (v1) had no design at all.
+
+## The redo: #1755
+
+#1755 merged "Swarm state by parts" (#1726) and the v1 Swarm work (Chat with PM, lost-work takeover, routing
+readiness) into main on 2026-10-27. Its design was
+[docs/design/2026-10-26-swarm-state-parts.md](../design/2026-10-26-swarm-state-parts.md), built against the spec
+[docs/plans/2026-10-26-swarm-state-parts.md](../plans/2026-10-26-swarm-state-parts.md) and its private
+conversations addendum. Groups 2–6 and the v1 groups each merged a PR into `feat/swarm-state-parts` (#1731–#1752).
+Then the branch went to main.
+
+This document lists every piece that was built and then redone or patched late because of a gap in the design. For
+each one it gives what was redone, the evidence, the gap, when it was found and what it cost. Coding slips that
+ordinary review caught are listed separately at the end. No rule cites them.
+
+All times are UTC, taken from the PR commits and the Swarm review conversations. Costs count Builder hours from the
+finding to the accepted fix, plus review rounds: verdicts that sent the work back, and the re-check that passed it.
+
+## Timeline
+
+| When (UTC) | Event |
+|---|---|
+| 26 Oct 10:16–10:55 | Design written (#1731). Design review 10:45–10:54: 1 Critical and 4 Important findings, all fixed before any code. |
+| 10:55–13:42 | Groups 2 (storage), 3 (reads, migration), 4 (Desktop), 5 (CLI) build in parallel against the design. |
+| 14:20 | Group 6's benchmark finds reads load the whole Swarm from the database. A new group, 3b, is opened. |
+| 14:46 | v1 groups start on the same branch: liveness A and B, routing readiness, Chat with PM. Their design is a scratchpad doc attached in chat. |
+| 17:34–17:45 | Whole-branch review: 2 Critical and 1 Important finding. Not safe to release. |
+| 18:29–22:34 | Final fixes C1, C2, I3 (#1748–#1751). The main merge is redone (#1747). |
+| 27 Oct 02:23 | #1755 merges into main. |
+| 03:32 | The gated migration on a restored production backup fails on deleted conversations' history. Fix #1778. |
+| 03:51 | Release. |
+| ~04:00 | Machines go offline for about 2 minutes during the CLI update. 16 tasks are marked lost, and their agents can never be assigned again. Fix #1781. |
+
+## Incidents
+
+Each incident's **Gap** names the line of the [Design section](../feature-design-rules.md) it broke: growth,
+concurrency, read cost, scale, compatibility, migration and rollback, audience, identity, failure or platforms.
+
+### D1. Hosts missed changes that removed something
+
+- **Redone:** the host form's wake-up rule. It now records the machines a group write affected, before and after
+ (`SwarmGroup.hostMachineIds`), and a settings marker on machines (`SwarmMachine.hostChangedAt`). An agent that
+ leaves a group is written again, so a later rename cannot hide its departure. Design R15 was added afterwards.
+- **Evidence:** group 3 review findings at 12:43 and 12:56. Fixes in #1733 `0c154c426` and `d9740911d`.
+- **Gap (read cost):** design 4.10 woke a host for a group whose *new* agents included one of its agents. The
+ invariant "a host sees every change that concerns its machine" was stated for additions only. Removals, and a
+ later write that replaces the marker, were never considered.
+- **Found:** group 3 review, after implementation.
+- **Cost:** 0.4 h and 3 review rounds. Two new columns and a rewrite of the commit path, all in group 2's files.
+
+### D2. Machine readings woke every host, and every tick resent the roster
+
+- **Redone:** readings no longer wake hosts (design R16). Each Swarm entry in the host form now has an etag, and a
+ host sends the etags it holds in a new POST body. Group 5 had to mirror the changed contract.
+- **Evidence:** #1733 `200ebec52` and `282ff95eb`, both "Lead's ruling after group 5's end-to-end run". #1737
+ `f13ac1673` and `a8f722a7f` mirror them in the CLI.
+- **Gap (read cost, scale):** the design said which part writes wake a host, but gave no cost budget for a host tick. Every
+ machine reports every 15 s, so every tick resent its Swarm. Nobody saw this until a real host ran end to end.
+- **Found:** group 5's end-to-end run, after groups 3 and 5 had built against the contract.
+- **Cost:** 0.6 h across two groups and 2 review rounds. One new route and a team-session allowlist entry. The
+ wire contract changed after a client had already been built against it.
+
+### D3. Reads loaded the whole Swarm from the database (group 3 to group 3b)
+
+- **Redone:** the change read and the host form. They now load only the parts they need, through a second loader
+ (`parts/light.ts`) and a new stored digest (`SwarmGroup.hostDigest`).
+- **Evidence:** the group 3b brief at 14:20, and #1745. An idle Desktop change read sent 2.8 KB but loaded 1.17 MB.
+ The host form loaded 2.3 MB to answer "unchanged", worse than main, which blocked the merge. After the fix they
+ load 45 KB and 16 KB. Group 2's PR (#1735, 12:58) had already noted that host reads "read every part (about
+ 1,150 KB from MongoDB per tick)".
+- **Gap (read cost, scale):** spec goal 3, "a poll costs what changed", was designed and measured only as bytes sent. Design
+ section 4 fixed the wire contract, but not what each read loads from the database. Group 0's benchmark measured
+ only the wire.
+- **Found:** group 6's integration benchmark, after groups 2–5 had merged.
+- **Cost:** a new group, 2.2 h (14:20–16:32), 5 commits and 3 review rounds. Group 6 reran its results. The second
+ loader then caused D4 and D8c.
+
+### D4. The second read path disagreed with the first
+
+- **Redone:** change reads now apply the known-kind rule that first loads apply. Before, a conversation of a kind
+ written by a newer release reached an older reader in changes but not in a first load.
+- **Evidence:** group 3b review at 15:42. Fix #1745 `58f5a8b13`.
+- **Gap (compatibility, audience):** read filters were written into each read path, not kept as one rule that every path calls.
+ The design listed the audience check for every path (4.4), but not the known-kind check.
+- **Found:** group 3b review.
+- **Cost:** 0.1 h and 1 review round.
+
+### D5. The new dormant flag broke code that assumed every group was loaded
+
+- **Redone:**
+ - Losing a project now loads dormant groups too, so their terminals are revoked. A second round extended this to
+ old groups with no project id.
+ - A group goes dormant only once its reports are read. This corrects design 3.6 a second time; the design review
+ had already corrected it once.
+ - The migration follows the same dormancy rule.
+ - The CLI reads a dormant group's history on demand.
+ - Desktop keeps paging older archived groups behind newer dormant ones.
+- **Evidence:**
+ - Group 2 review round 1, findings 1 and 3, and round 2. Fixes #1735 `99c0060ac` and `ebe62a97f`.
+ - #1733 `a9dbb7e86`.
+ - Group 5 review finding 2. Fix #1737 `ccdfc6f63`.
+ - Group 4 review finding 2. Fix #1734 `01c138eb3`.
+- **Gap (growth):** design ruling R3 added `dormant` and said "only the feed and first load read it". It did not
+ list the code that relied on all groups being loaded: access revocation, report wake-ups, route-history checks
+ and the archived list.
+- **Found:** reviews of groups 2, 4 and 5, after implementation.
+- **Cost:** 0.9 h and 6 review rounds across four groups. The design was corrected twice.
+
+### D6. Versions reset when a key was recreated after its tombstone was purged
+
+- **Redone:** people, agents and machines now keep their tombstones for good, compacted to the version after 7
+ days, so a recreated key continues above its old version. This corrects design ruling 6 and section 2.1.
+- **Evidence:** group 2 review round 1, finding 4. Ruling "Versions never reset, even after a purge" in #1735.
+- **Gap (growth):** the design had no lifecycle for a part's key (create, delete, purge, recreate under the same
+ key), so the purge-then-recreate path was never checked against the rule that versions never reset.
+- **Found:** group 2 review.
+- **Cost:** part of group 2's two extra rounds (D5). Both the design and the code changed.
+
+### D7. The design's touch table would have brought the conflicts back
+
+- **Redone:**
+ - A post no longer touches its recipients.
+ - A terminal turn no longer touches the person who opened the terminal.
+ - Delivery claims touch only a person sender.
+- **Evidence:** #1735 `e5d248293` and `5b130091b`, the ruling "Touching recipients made every worker's post touch
+ its Lead, and posts in different groups conflicted again", and the Reviewer's guard audit table in #1735. Group 2
+ review finding 1 (D5) was a gap in that narrowed table.
+- **Gap (concurrency):** the design's table of parts each command touches was never run against goal 1 (no
+ conflicts between groups) before groups split. Only building it showed the conflict.
+- **Found:** group 2, while building.
+- **Cost:** 0.5 h of rework, a per-change guard audit for the Reviewer, and one Important finding that came out of
+ the narrowed table.
+
+### D8. The new `lost` status was not traced through the code that reads work status
+
+The liveness design ("A Swarm that never stops") was a scratchpad doc attached in chat. It joined the branch after
+the design was approved, with no design review and a 05:00 Vietnam time deadline ("working product first"). Its brief defined
+`lost` as "not active", but did not list the code that reads work status or active work. Six fixes followed:
+
+| | What was patched | Evidence | Gap | Found | Cost |
+|---|---|---|---|---|---|
+| a | Cancelling lost work brought back a blocking "decide what to do with the worker". | liveness A review 15:29; #1742 `53908fe9e` | compatibility: decision derivation (`awaitingWorkers`) | review | 0.2 h, 1 round |
+| b | A loss decided from a machine report did not guard that report, so it could fence a live worker. | liveness A review 15:23; #1742 `05a8328a4` | concurrency: a sweep outside commands ignored the design's touch rule (3.4) | review | in a's round |
+| c | The light loader dropped the lost marker, so change reads derived a decision that first loads did not. | group 3b review 15:51; #1745 `bb907dc23` | compatibility: the second read path (D3) | review | 0.6 h, 1 round |
+| d | A lost worker became routable again after its task was cancelled or reassigned. The first fix then also refused workers that had recovered. | final review I3, 17:45; #1749 `bbd17458d`, `57410c62e` | failure: lost, then cancel, reassign, recover | final review | 1.7 h, 2 rounds |
+| e | Rolling back handed lost tasks to a release that cannot read them. | final review C2; #1748 | migration and rollback (D10) | final review | in D10 |
+| f | When liveness lost a task outside a command, the agent's running-work record was never freed. After the release, 16 lost tasks left their agents unassignable for good, even after cancel. | #1781 `54fa314a8`, `df7f62bf5`; its review found stale deliveries too | failure: "an agent has a run record exactly while it owns active work" was kept only by commands and stop receipts, not by the liveness checks | **production, after release** | 0.6 h and 2 rounds to fix; 16 agents blocked in production until it ships |
+
+**Cost:** 3.1 h of fixes and 6 review rounds before release, plus the production incident.
+
+### D9. A private chat reached a terminal that other people could watch (final review C1)
+
+- **Redone:**
+ - A native session becomes confidential once it is a Lead or a member of any private conversation, in any Swarm.
+ - Only its machine's person may observe, share, read or type into it: through Swarm shares, ordinary shares,
+ other Swarms and agent requesters.
+ - A confidential session may be registered in one Swarm only, and a new shared record makes concurrent
+ registrations conflict (`SuperTabSessionScope.confidential`).
+- **Evidence:** final review at 17:45. #1751, 10 commits starting at `b3dce532a`, last fix `d6184d911`, with five review rounds
+ at 18:52, 19:10, 19:47, 20:40 and 20:47 before Ready at 21:35. An isolated end-to-end run proved it.
+- **Gap (audience):** the addendum listed where a private conversation must not appear: first load, changes, message
+ reads, notifications, mentions and `otherProjectsWork`. Those are API routes. It did not list the copies the data
+ makes: the PM's terminal screen and scrollback once a message is delivered, shares made outside a Swarm, and the
+ same session working in another Swarm. The design review did catch one leak of this kind, dormant stubs, at
+ design time.
+- **Found:** the whole-branch review, after every group had merged.
+- **Cost:** 4.8 h (17:45–22:34) and 6 review rounds. A new schema field and a new product rule.
+
+### D10. Rollback could not represent work added after it was designed (final review C2)
+
+- **Redone:** rollback now refuses any Swarm with a private conversation or a lost task, and the recovery path is
+ to roll forward. The refusal's wording was corrected in #1750.
+- **Evidence:** #1748 `07626fe86`, #1750 `0dc9e5695`, and final review C2.
+- **Gap (migration and rollback):** design 6.4 was written before private conversations and `lost` existed in the
+ branch. Nobody asked again what the previous release does with each new field when scope grew. That release
+ checks no audience, and does not know the lost status or the lost marker.
+- **Found:** the whole-branch review.
+- **Cost:** 1 h and 1 round plus a Minor. A lasting product limit: those Swarms can only roll forward.
+
+### D11. The migration refused history from deleted conversations
+
+- **Redone:** messages of conversations deleted before the migration are kept and stay unreadable. Verification
+ still rejects anything the migration itself would lose.
+- **Evidence:** #1778 `1374a4f2d`. On an isolated restore of the production backup, 24 of 24 Swarms then
+ migrated, and 5,380 orphan messages in 7 Swarms stayed unreadable.
+- **Gap (migration and rollback):** design 6.3 required "no orphans" in the message fingerprint. That was assumed, not
+ checked against production. The dry run used synthetic Swarms made through real commands, which cannot contain
+ old anomalies. The spec's plan for a production-copy dry run had been replaced by synthetic data, pending an owner
+ ok that never came before the merge.
+- **Found:** the gated production migration, after the merge to main.
+- **Cost:** a fix during the release window. The production backend stayed on `v1.3.35_backend` until the fixed
+ image was built.
+
+### D12. Chat with PM after leaving and rejoining opened a chat the person could no longer read
+
+- **Redone:** the chat's create request is keyed by membership generation as well as account and project.
+- **Evidence:** Chat with PM review at 16:15. Fix #1746 `c1752b1dd`.
+- **Gap (audience):** the brief required one chat per account and project for life. It did not cover membership
+ ending and starting again, which changes who can read the old chat.
+- **Found:** review.
+- **Cost:** 0.25 h and 1 round.
+
+### Knock-on cost: the main merge was done twice
+
+Main was merged into the branch at 17:41 (`1a3e238bd`, reviewed on its own). D8d, D9 and D10 then landed, so the
+merge was redone at 22:35 (`21480ef97`, #1747), with its checks run again.
+
+## Totals
+
+| | Builder hours | Review rounds | Found after the groups merged |
+|---|---|---|---|
+| D1–D7, D12 (first design and its groups) | 5.0 h | 16 | D3 |
+| D8a–c (lost, before the final review) | 0.8 h | 2 | — |
+| D8d, D9, D10 (final review) | 7.5 h | 9 | all |
+| D8f, D11 (after the merge to main) | 0.6 h + release fix | 2 | all; D8f in production |
+| **Total** | **about 14 h** | **29** | |
+
+By design line:
+
+| Line | Incidents | What answering it would have required |
+|---|---|---|
+| growth | D5, D6 | a lifecycle per record, and the readers of every archived state |
+| concurrency | D7, D8b | each invariant's keeper on every path; the lock table tried on a thin slice |
+| read cost | D1, D2, D3 | bytes sent *and* loaded per read path, removals included |
+| scale | D2, D3 | the warning metric measured early, not at integration |
+| compatibility | D4, D8a, D8c | every existing reader of a new field or state |
+| migration and rollback | D8e, D10, D11 | the previous release per new field; a production restore before merge |
+| audience | D9, D12 | every copy of private data guarded by the server |
+| failure | D8d, D8f | the lost state's lifecycle and who frees what |
+| identity, platforms | none in #1755 | found elsewhere: the Team account work, and #1722's Windows pane |
+
+Rule 2 (review the design again) would have triggered on D1, D5 and D8, each patched twice or more, and on #1722
+itself. The v1 work joined the branch with no Design section, which rule 1 requires of any spec that stores data.
+That was the source of D8, D9, D10 and D12, and of the 7.5 h after the whole-branch review.
+
+## What worked
+
+- The design review with code citations found 6 issues in 9 minutes, before any code: the migration fence, private
+ stubs, finished starts, dormant reports, paging ties and owner visibility. Each would have cost a group a round
+ later.
+- Rulings recorded with "cost if wrong" made every deviation reviewable. Several incidents above were found because
+ a ruling stated its assumption.
+- Red-then-green tests in every fix kept fixes from regressing.
+
+## Coding slips (not design; no rule cites them)
+
+Ordinary review caught these, and each took one fix round:
+- **Group 2:**
+ - the dormancy sweep could revisit the same ineligible groups forever;
+ - the benchmark self-test was not adapted.
+- **Group 4:**
+ - a failed dormant fetch skipped the rest of a change read;
+ - the dormant list swallowed the update-required answer.
+- **Group 5:**
+ - updating a part changed its order;
+ - a forced full answer was ignored.
+- **Routing readiness:**
+ - query credentials were kept in repository observations;
+ - a hung git helper outlived its deadline;
+ - a failed probe counted as "cannot".
+- **C1 fix:** a race test failed when one of its two valid winners won.
+- **#1781:** stale-record repair left old deliveries claimable.