Edmund change control

Last verified: 2026-07-05, against main @ fe8a1f5 (release 0.1.3).

This is the gatekeeping doc: what class of change you are making, which gate it must pass, and the rules that are never traded away. The rules exist because each was paid for — the incident column is not decoration.

0. Before you start (task setup)

[ ] Read docs/ARCHITECTURE.md before any non-trivial change (its own rule)
[ ] git status — note any uncommitted work; never clobber it
[ ] Not on main? Fine. On main? Branch NOW, before the first edit
[ ] Classify the change (§1) so you know the gate before you write code
[ ] Edit-pipeline / selection work? Plan the live repro FIRST — if you can't
    reproduce the bug, you can't prove the fix (§3, last row)

1. Classify the change, apply the gate

Classify FIRST, before writing code. The class decides the verification bar.

Notes on the gates:

• swift test (~750+ tests, ~10s) also runs automatically as a Stop hook (.claude/settings.json: swift test 2>&1 | tail -5) at the end of every turn. That is a safety net, not the gate — run it yourself before committing so the failure is yours to see, not the hook's.
• A change can be in multiple classes. Apply the union of gates. A caret fix that also moves a decoration needs test + screencapture + live repro.
• "Draws" is broad: padding, insets, colors, wrapping, fragment frames. If a human could see the diff, screenshot it.

Classification edge cases that have gone wrong before:

• "It's just an attribute change" is NOT automatically the code-logic class. If the attributes change measured geometry (font size, paragraph spacing, hidden-delimiter width), it draws AND it needs invalidateLayout(for:) — see §3.
• "It's just a restyle helper" that runs beginEditing/setAttributes on storage is edit-pipeline class if it can fire during IME composition or after a bypassed edit. When in doubt, grep for hasMarkedText guards on the sibling paths and match them.
• A test-only change is docs-class for gating purposes (nothing to screenshot), but the Stop hook still must pass — a broken test is a broken commit.
• Release-adjacent edits (Info.plist versions, CHANGELOG.md, appcast.xml, scripts/release.sh, .github/workflows/) are release class even when tiny. The v0.1.0→0.1.1 Sparkle failure came from the build script's signing step, not from app code.

2. Git discipline

From CLAUDE.md + ARCHITECTURE §12 + the repo's own history (git branch -a).

• Branch off main for every fix. Never commit straight to main. One feature/fix per branch.
• Branch prefixes actually in use (verified): fix/, feat/, feature/, docs/, chore/, uiux/, ui/, ux/, markdown/, bug/, refactor/, ci/, release/. Prefer fix/, feat/, docs/, chore/ for new work; uiux/ for visual polish; markdown/ for syntax-feature work.
• Small, logical commits; commit frequently. A commit that mixes the fix with a drive-by refactor is two commits done wrong.
• NEVER auto-push, open a PR, or merge. Only when the maintainer explicitly asks. No exceptions for "it's just docs."
• Never discard uncommitted changes. No git checkout -- ., git reset --hard, git clean on a dirty tree without explicit permission.
• Commit messages follow the observed style: fix(editor): …, docs: …, ui: …, chore: … — short imperative subject.

3. The non-negotiables

Each rule was established by an incident. Verify against the cited doc before arguing an exception.

The two incidents that shaped this table

Worth knowing as stories, because the rules read as pedantry until you see the cost:

• Delete-drift (six rounds). The hardest live problem this repo has had. A caret that drifted after deletes. Round 1 blamed IME stranding — plausible fix, shipped, recurred. Round 2 disabled remaining marked-text sources — recurred. Round 3 stopped guessing and built diagnostics (selection tracing, event logs). Round 4's diagnostics caught a drag-move deleting storage with no didChangeText — the heal was born. Round 5: the heal itself leaped the caret via a stale selection. Round 6 found the actual drift mechanism — TextKit 2's queued _fixSelectionAfterChange firing at the next endEditing — and held only because the ReproScript driver could replay the exact keystroke sequence deterministically. Five shipped fixes failed; the one preceded by a frozen repro stuck. That asymmetry IS the change-control policy for this bug class.
• Undo/redo viewport drift. Undo restored a snapshot via full recompose, which reset every fragment to a TK2 height estimate; the follow-up scroll-to-caret then landed wrong and the viewport jumped. The fix (5bb2b40) diffs the snapshot against current text and applies only the changed span with recomposeReplacing. Moral: in TK2, layout state is part of the document state you must preserve — "re-render everything" is never the safe fallback here, it is the bug.

4. Review expectations

• ARCHITECTURE.md is updated in the same PR whenever you learn something non-obvious or change an invariant. The doc's own header demands this; the gotchas in §8 all arrived this way.
• Quirks are documented as comments at the code site — the edge case, the workaround, the why. Not in commit messages, not in CLAUDE.md.
• New known issues go in ARCHITECTURE §9 with a one-line repro and a pointer to any deeper write-up in docs/.
• Big investigations (multi-round bugs) get a docs/*-investigation.md chronicle — see edmund-failure-archaeology for the pattern.

5. Pre-commit checklist (copy-paste)

The workflow that worked (ARCHITECTURE §12 + CLAUDE.md). Run it verbatim:

[ ] swift test — all green (also enforced by the Stop hook; don't rely on it)
[ ] New behavior / bug fix → a test exists that fails without the change
[ ] Draws anything? → build app, screencapture window-by-id, look at the PNG
[ ] Edit-pipeline / selection change? → live repro or soak script passed
[ ] On a branch off main (fix/…, feat/…, docs/…, chore/…), NOT on main
[ ] Diff touches only what the task needs; style matches surroundings
[ ] Learned something non-obvious? → ARCHITECTURE.md updated in this change
[ ] Quirk introduced/found? → comment at the code site
[ ] Commit is small and logical; message matches repo style (fix(scope): …)
[ ] NOT pushing, NOT opening a PR, NOT merging (unless explicitly asked)

6. Ask the maintainer first — always

Never do these unprompted; ask and wait for an explicit yes:

When NOT to use this skill

Provenance and maintenance

• Sources: CLAUDE.md (repo root), docs/ARCHITECTURE.md §1 §2 §8 §9 §12, .claude/settings.json (Stop hook), misc/before-you-release.md, misc/how-to-release.md, docs/investigations/delete-drift-investigation.md (rounds 1–6), docs/investigations/archives/callout-title-wrap-investigation.md, git log / git branch -a as of fe8a1f5 (2026-07-05).
• Commits cited were verified in git log: 5bb2b40 (diff-based undo restore), 9f99795 (round-4 heal), ae61644 (stroked-path callout icon), 1b1420a (round-6 caret re-assert).
• Two rules rest on maintainer statements rather than repo docs: the measure-from-pixels rule and the test-files/ ownership rule. If either gets written into ARCHITECTURE.md, point at it here.
• Maintain: when a new incident produces a new rule, add a row to §3 with the incident pointer in the same PR that adds the rule to ARCHITECTURE.md. When the Stop hook in .claude/settings.json changes, update §1's note.