amadan
Shipping cadence, and colour allocation is order-independent
Paul's call, 2026-08-30: everything on a worktree on a branch, regular commits pushed as they land, squash-merge to main only when the work is done, approved — including the highest-capability-model review pass — and CI is actually green. Any one of the three missing means it does not merge. Also from ui-guidelines-52: colour allocation must be a pure function of a canonically ordered key set rather than of arrival order. Resolving displacement by "who arrived later" means two clients viewing the same sheet allocate differently, so the same person is green for one viewer and blue for another and both trust it. Order by member id. The avoid set is in their API rather than worked around caller-side, so collisions happen only past the set's capacity.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01APtNStXDZ5H2fAc1ZuGqtS
2 files changed,
+37
−0
AGENTS.md+24 −0docs/superpowers/specs/2026-08-30-sheets-design.md+13 −0
diff --git a/AGENTS.md b/AGENTS.md| index 3636d66..801585d 100644 |
| --- a/AGENTS.md |
| +++ b/AGENTS.md |
| @@ -61,6 +61,30 @@ always welcome on top. |
| --- |
| +## Shipping cadence — RULED 2026-08-30 by Paul |
| + |
| +**Everything happens on a worktree, on a branch.** Never directly on |
| +`main`, and never in the primary checkout. |
| + |
| +1. **Worktree per session.** One isolated workspace per piece of work. |
| +2. **Branch per piece of work**, cut from current `main`. |
| +3. **Commit regularly and push to the branch.** Small commits that tell the |
| + story, pushed as they land — not one heroic commit at the end. A branch |
| + that only exists locally is work nobody can see or recover. |
| +4. **Squash-merge to `main`** when, and only when, all three hold: |
| + - the work is **done** — not "done except", |
| + - it is **approved** — including the §Review pass by the |
| + highest-capability model available, |
| + - **CI is green** — actually green, checked, not assumed. |
| + |
| +Any one of the three missing means it does not merge. "CI was green |
| +before the last push" is not CI being green. |
| + |
| +Review happens on a **deployed canary**, never localhost. Shared hosts only |
| +ever run merged `main`. |
| + |
| +--- |
| + |
| ## Intent before code |
| CARLOS's first principle: the design doc precedes the build, and its |
diff --git a/docs/superpowers/specs/2026-08-30-sheets-design.md b/docs/superpowers/specs/2026-08-30-sheets-design.md| index 397dc6b..843c7be 100644 |
| --- a/docs/superpowers/specs/2026-08-30-sheets-design.md |
| +++ b/docs/superpowers/specs/2026-08-30-sheets-design.md |
| @@ -500,6 +500,19 @@ paint under a user fill, and a selected or frozen cell sits on something |
| else again. We pass what the cell actually sits on and the gate asserts the |
| pair against that exact colour. |
| +**Allocation is a pure function of a canonically ordered key set, never of |
| +arrival order** (ui-guidelines-52, 2026-08-30). If displacement resolves by |
| +"who arrived later", two clients viewing the same sheet allocate differently |
| +— the same person is green for one viewer and blue for another, and both |
| +trust it. With six people in a sheet that is a visible and confusing bug. |
| +Order by member id and displace within that order. The `avoid` set is a |
| +parameter of the API rather than a caller-side workaround, so collisions |
| +occur only past the set's capacity — the honest limit rather than an |
| +accident. |
| + |
| +Stability of a person's colour is **best-effort by design; separation is the |
| +hard guarantee.** |
| + |
| **Second entry point: distinguishable-colour allocation.** Contrast- |
| correctness and perceptual separation are different guarantees, so allocation |
| is its own function — hash a stable identity into the bounded hue set with a |