docs: add Self-Review Discipline section to CLAUDE.md

Honest retro from this PR: review bots (Codex, CodeRabbit) surfaced
~13 valid findings; my own self-reviews surfaced ~3–4. Bots aren't
magic — they run adversarial checks consistently. The agent
guidelines didn't tell future sessions to do the same.

Adds a new "Self-Review Discipline" section between Principles and
Port Rules, covering the six specific blindspots this PR kept hitting:

1. Adversarial input sweep — what inputs would break this regex/
   substitution/tokenizer?
2. Emit/parse symmetry — does my parse accept every shape my emit
   produces?
3. Pass-interaction check — does my new pass compose cleanly with
   every existing pass in the pipeline?
4. Unforgeable sentinels — per-call nonce for any placeholder mapped
   back to structured data.
5. Divergence budget — enforce the 2-divergence-per-sync cap against
   myself, not just externally.
6. The Codex pre-ship question — "what would Codex find right now?"

Also cross-links from UPSTREAM_SYNC.md "How to land a divergence"
since divergence code is the highest-risk surface for these
blindspots.

https://claude.ai/code/session_01XE1bMoQ5BjCvgi1iLGKKhG

Author: claude

CLAUDE.md

@@ -64,6 +64,50 @@ All thread IDs follow: `{adapter}:{channel}:{thread}`
 3. **No two tests should verify the same thing.** Duplicates inflate counts
    without catching more bugs.
 
+## Self-Review Discipline
+
+Review bots (Codex, CoderRabbit) outperformed agent self-review ~3× on recent
+PRs — not because they're magic, but because they run adversarial checks
+consistently. Run these yourself *before* declaring code ready. They target
+the specific blindspots that have cost us silent bugs.
+
+1. **Adversarial input sweep.** For every regex, substitution, or tokenization
+   pass you add, enumerate ~5 inputs that could break it:
+   - empty input, single-char input
+   - input containing the marker/sentinel your code produces (forgery)
+   - input containing each delimiter your pattern uses
+   - the pattern appearing in unintended contexts (code spans, quoted strings)
+   - very long input, odd unicode, PUA code points
+
+2. **Emit/parse symmetry.** If you add `X → Y` (emit), verify your `Y → X`
+   (parse) accepts every `X` the emit might produce. Every URL scheme, every
+   label shape, every edge case (empty / relative / None). Asymmetry between
+   emit and parse is a common source of silent data loss.
+
+3. **Pass-interaction check.** When inserting a new transformation pass into
+   a pipeline (markdown parsing, stripping, rendering), walk through every
+   existing pass: does yours break any? do any break yours? does ORDER
+   matter? Example: a link-strip inserted after code-stripping corrupts code
+   content containing link syntax.
+
+4. **Unforgeable sentinels.** Any placeholder token that later code maps
+   back to structured data must carry a per-call nonce
+   (`secrets.token_hex(n)`). Fixed tokens like `\ue000LINK0\ue000` can be
+   forged by user input. Also tolerate out-of-range / unrecognized
+   sentinels without raising — fall back to literal text.
+
+5. **Divergence budget.** `docs/UPSTREAM_SYNC.md` sets a max of **2
+   divergences per sync**. Enforce this against yourself. A 3rd divergence
+   = stop and ask whether this is still a sync or becoming a fork. Document
+   every divergence in the non-parity table, add a breadcrumb at the code
+   site, write a regression test that would fail if someone "fixes" the
+   divergence back to upstream.
+
+6. **The Codex pre-ship question.** Before declaring ready, ask yourself:
+   "What would Codex find in this code right now?" Be adversarial. If the
+   honest answer is "probably X," test X first. Don't wait for a bot to
+   file it.
+
 ## Port Rules (TS → Python)
 
 See docs/UPSTREAM_SYNC.md for the full 15-hazard guide. Key patterns:

docs/UPSTREAM_SYNC.md

@@ -111,6 +111,10 @@ the rules below before adding one.
    back to upstream's behavior. The test's docstring should cite the reason.
 5. **CHANGELOG entry** under a "Python-specific (divergence from upstream)"
    subsection.
+6. **Run the self-review adversarial checks** from
+   [CLAUDE.md § Self-Review Discipline](../CLAUDE.md#self-review-discipline).
+   Divergence code is exactly the kind of novel, Python-specific logic that
+   bot reviewers consistently find bugs in — catch them yourself first.
 
 ### Review signal