docs(runbooks): what a squash merge lands — two surfaces, one composition, measured on nine merges (TASK-223)

A squash merge composes one message from two surfaces: the squash-message
subject box (seeded with the PR title) and the branch's commit messages. The PR
body is not an input. Measured on the nine PRs this pod landed between
09:08:43Z and 09:19:20Z on 2026-09-30, by recomputing the expected message from
the PR title and the branch commits and comparing it to main character for
character.

- 1 commit: subject = `<subject box> (#N)`; body = that commit's message minus
  its first line.
- 2+ commits: same subject; body = per commit, `* <full subject>`, blank line,
  then the commit body.

Subject matched the default (PR title + ` (#N)`) in 8 of 9; body matched the
composition in 9 of 9, an 8-commit PR included.

#2031 is the exception that shows the box is editable: its title ended
`(TASK-204 late delta)` and the landed subject is the commit's own subject with
` (#N)` appended.

The body is the surface that bites, and amending the tip does not amend earlier
commits — measured on #2049, whose merge message today carries commit 1's
retracted `split('@media (prefers-reduced-motion')[1]` framing at line 13 and
its retraction at line 58.

Also recorded because the doc quotes them: `gh pr view --json commits` truncates
headlines (17 of these 22 commits, every one to 69 characters plus an ellipsis,
the longest intact being 72), and `git log -1 --format=%B <merge>` is the only
reader that shows what main says.

Scope: this is the message, not the tree. Fidelity of what landed to what was
reviewed stays rule 32's patch-id comparison; the tree/origin check is rule 49.

Author: lilyshen0722

docs/runbooks/what-a-squash-lands.md

@@ -0,0 +1,100 @@
+# What a squash merge lands
+
+A squash merge writes **one** commit to main, and its message is composed from
+two surfaces: the **squash-message subject** (a text box in the merge dialog,
+seeded with the PR title) and the **branch's commit messages**. The PR *body* is
+not an input to it. Both halves below were measured against the nine PRs this pod
+landed between 09:08:43Z and 09:19:20Z on 2026-09-30, by recomputing the expected
+message from the PR title and the branch commits and comparing it to what main
+carries, character for character.
+
+## The composition
+
+| PR shape | landed subject | landed body |
+|---|---|---|
+| **1 commit** | `<subject box>` + ` (#N)` | that commit's message **minus its first line** |
+| **2+ commits** | `<subject box>` + ` (#N)` | per commit, in order: `* <full commit subject>`, a blank line, then that commit's message body |
+
+The subject box is seeded with the **PR title**, so the default is
+`<PR title> (#N)` — true in 8 of the 9. The body matched this composition
+**exactly in 9 of 9**, single-commit and 8-commit PRs included.
+
+| PR | commits | landed subject | landed body |
+|---|---|---|---|
+| #2015 | 1 | title + `(#2015)` | the commit body |
+| #2017 | 3 | title + `(#2017)` | 3 bullets + bodies |
+| #2024 | 2 | title + `(#2024)` | 2 bullets + bodies |
+| #2031 | 1 | **the COMMIT subject** + `(#2031)` | the commit body |
+| #2043 | 8 | title + `(#2043)` | 8 bullets + bodies |
+| #2045 | 3 | title + `(#2045)` | 3 bullets + bodies |
+| #2046 | 1 | title + `(#2046)` | the commit body |
+| #2048 | 1 | title + `(#2048)` | the commit body |
+| #2049 | 2 | title + `(#2049)` | 2 bullets + bodies |
+
+## #2031 is the one that shows the box is editable
+
+Its PR title was `… the concurrency discriminator is the run, not the SHA
+(TASK-204 late delta)`. The landed subject is `… the concurrency
+discriminator is the run, not the SHA (#2031)` — the commit's own subject, with
+GitHub's ` (#N)` still appended. So the presser can overwrite the subject box,
+and ` (#N)` is added to whatever sits in it. One in nine — and the practical
+reading runs the other way from the usual one: **do not assume the PR title is
+what landed.** Read the merge commit.
+
+## Why the body is the surface that bites
+
+A claim that must not land is fixed on **both** surfaces — the PR title (the
+subject) **and every commit message that carries it** (the body). Nothing else
+reaches either: a PR *body* edit is not an input to the composition at all, and a
+PR comment reaches neither.
+
+**Amending the tip does not amend earlier commits.** Measured on #2049, whose
+branch carried two commits with the tip amended to retract an over-claim: main's
+merge message today carries both texts, side by side —
+
+```
+line 13: `split('@media (prefers-reduced-motion')[1]` is 865 lines / 33,883 characters
+line 58: right; calling it "fiction about the code" was the wrong reason, and is retracted.
+```
+
+— the retracted framing in commit 1's body and its retraction in commit 2's, in
+one message. `git log -1 --format=%B <merge>` is the only reader that shows
+this. The PR page shows the current branch state, which is what the author last
+saw; main shows what landed.
+
+## Checking what landed — and what will land
+
+```bash
+PR=2049
+M=$(git log --format=%H --grep="(#$PR)\$" -1 origin/main)   # the merge commit
+git log -1 --format=%s "$M"      # the landed subject
+git log -1 --format=%B "$M"      # the landed body — the surface main reads
+gh pr view "$PR" --json title -q .title                     # the seeded subject
+gh api repos/Team-Commonly/commonly/commits/<oid> -q .commit.message   # lossless branch message
+```
+
+Two instrument notes, both measured. `gh pr view <N> --json commits -q
+'.commits[] | .messageHeadline'` is **lossy**: across the nine PRs' 22 commits,
+17 headlines ended in `…` and every one of those measured exactly 70 characters
+(69 plus the ellipsis), while the longest intact one is 72 — so the cut lands
+somewhere between, and the projection counts commits faithfully while quoting
+them wrongly. Read the commit object above for the text itself; the branch
+commits survive the branch deletion inside the PR record. The second note is the
+one that matters here: this is the same class as the PR page, a summary that is
+right about the shape and wrong about the words. And the composition is a fact about the
+**message** only: whether what landed is what was reviewed is a separate
+measurement — the patch-id comparison in rule 32 of
+`docs/development/review-checklist.md`, and the tree/origin check in rule 49.
+
+## Habits this buys
+
+- **Before a press:** the PR title is one of two surfaces; the commit list is the
+  other. Read both. A commit-message fix moves the head and so costs a re-stamp
+  (rule 44); a title edit does not.
+- **After a merge:** `git log -1 --format=%B <merge>` answers "what does main
+  say"; the PR page answers "what did the branch say last".
+- **A landed-and-wrong message cannot be unlanded.** A follow-up commit puts a
+  correction next to it, which is a different artifact from a fix — the remedy
+  that works is the one taken before the press.
+- **Never cite a PR title as a landing claim.** #2031 is the counterexample that
+  cost nothing; the same mechanism with a wrong title is the one that does.