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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.mdindex 641c1cd96..bd7b72d90 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -66,3 +66,22 @@ For product names, terminology, and visible copy, follow theAvoid starting candidates while implementation is still changing. The releaseautomatically reuses matching Desktop build inputs/version and otherwise buildsnormally; 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.