sanook-cli 0.4.0 → 0.5.1

package/skills/resilience-timeouts-retries/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: resilience-timeouts-retries
+description: Makes calls to flaky dependencies (DBs, HTTP/RPC APIs, queues) survive failure without amplifying it — bounded timeouts on connect/read/total/per-attempt, deadline propagation across the call chain, exponential backoff with FULL jitter, retry budgets/caps, circuit breakers (closed/open/half-open), bulkheads, backpressure + load-shedding (429/503 + Retry-After), and hedged requests for tail latency. Retries only idempotent ops; never retries 4xx except 408/429; library-specific for resilience4j, Polly, tenacity, failsafe-go/gobreaker, JS AbortSignal+p-retry, gRPC deadlines, and Envoy/Istio outlier-detection.
+when_to_use: User is calling a network dependency that can be slow/down (HTTP API, DB, RPC, queue) and needs it to fail fast, retry safely, or stop hammering a sick service — or is debugging retry storms, thundering-herd, hung pools, cascading timeouts. Distinct from rate-limiting (limits inbound traffic *you* receive; this protects *your* outbound calls) and async-concurrency-correctness (in-process task/lock/cancellation correctness, not network failure policy). For making the retried write itself safe, pair with idempotency-keys.
+---
+
+## When to Use
+
+Reach for this skill when your code crosses a network boundary to something that can be slow, flaky, or down:
+
+- "This call to the payments API / DB sometimes hangs forever and pins all our threads"
+- "Add retries to this HTTP/RPC client" (and you need them to not make an outage worse)
+- "One slow downstream is taking down the whole service" (cascading failure)
+- "We had a retry storm / thundering herd after the dependency recovered"
+- "Tail latency (p99) is terrible even though p50 is fine"
+- "Should we retry this 500? this timeout? this POST?"
+
+NOT this skill:
+- Limiting inbound traffic *you serve* (per-user/IP quotas, token bucket) → rate-limiting. This skill governs the *outbound* calls you make and shedding load when *you* are overwhelmed.
+- In-process deadlocks, leaked tasks, locks across `await`, channel backpressure → async-concurrency-correctness. That's correctness of concurrency; this is policy for network failure.
+- Making the operation you retry safe to run twice (dedup key, exactly-once effect) → idempotency-keys. Retry without idempotency = duplicate charges.
+- Delivering *your* outbound webhooks with retry/backoff/DLQ → deliver-webhooks (this skill is the primitive it builds on).
+
+First principle: **every retry adds load to a system that is already failing.** Default to *fewer* retries with jitter and a budget, never *more*.
+
+## Steps
+
+1. **Put a bound on every wait — no unbounded blocking, ever.** A missing timeout is the root cause of most "the whole service hung" incidents: one stuck call holds a connection/thread until the pool is empty. Set all four:
+
+   | Timeout | What it caps | Typical |
+   |---|---|---|
+   | connect | TCP/TLS handshake | 1–3s |
+   | read/socket | gap between bytes | 2–10s |
+   | per-attempt total | one try end-to-end | derived from p99 + margin |
+   | overall/deadline | whole op incl. retries | < the caller's own deadline |
+
+   Per-language: JS `fetch(url, { signal: AbortSignal.timeout(ms) })` (default fetch has NO timeout); Python `httpx.Timeout(connect=, read=, write=, pool=)` or `requests` `timeout=(connect, read)` (a bare `timeout=5` is read-only — connect can still hang); Go `http.Client{Timeout}` + a per-request `context.WithTimeout`; Java set both `connectTimeout` and `requestTimeout`. Never leave a driver/client on its infinite default.
+
+2. **Propagate a deadline (time budget), don't restart the clock per layer.** A 5s timeout at three nested layers = up to 15s of real wait. Compute an absolute deadline once at the edge and pass it down; each hop spends from the *remaining* budget. Go: pass `ctx` (carries `WithDeadline`) into every call — `ctx, _ := context.WithTimeout(parent, remaining)`. gRPC: set a **deadline** on the client call (`grpc.WithTimeout`/`context` deadline), and servers must check `ctx.Err()` / `context.Deadline()` and stop work when it's blown. Reserve a slice of the budget for retries — don't let a single attempt consume all of it.
+
+3. **Retry ONLY idempotent/safe operations.** GET/PUT/DELETE are safe; a raw POST is not — a retried "create order" can double-charge. Either restrict retries to safe verbs, or make the write idempotent with an **idempotency key** the server dedupes on (→ idempotency-keys) and only then retry it. Treat "I don't know if it ran" (timeout after send) as **possibly executed** — never blind-retry a non-idempotent write on timeout.
+
+4. **Retry the right errors, fail fast on the rest.**
+
+   | Outcome | Retry? |
+   |---|---|
+   | connection refused / reset / DNS / connect timeout | yes |
+   | read timeout (idempotent op only) | yes |
+   | 502, 503, 504 | yes |
+   | 429, 408 | yes — and honor `Retry-After` |
+   | 500 | usually no (often a deterministic bug — same input, same failure) |
+   | 400, 401, 403, 404, 409, 422 | **no** — retrying a client error just burns budget |
+
+   gRPC: retry `UNAVAILABLE`/`DEADLINE_EXCEEDED`/`RESOURCE_EXHAUSTED`; not `INVALID_ARGUMENT`/`NOT_FOUND`/`PERMISSION_DENIED`. When `Retry-After` is present, obey it instead of your backoff.
+
+5. **Back off exponentially with FULL jitter.** Fixed delays (or exponential with *no* jitter) make every client that failed at T retry in lockstep — a synchronized retry storm that re-knocks-over the recovering dependency (thundering herd). Use full jitter: `sleep = random_uniform(0, min(cap, base * 2**attempt))`.
+
+   ```python
+   delay = random.uniform(0, min(cap, base * (2 ** attempt)))  # base=0.1s, cap=10s
+   ```
+   "Equal jitter" (`half + rand(half)`) is acceptable; "no jitter" is the bug. Add `Retry-After` override when the server sent one.
+
+6. **Cap retries and add a retry budget — keep nesting from multiplying load.** Limit attempts (typically **2–3 total**, not 5+) AND a max elapsed (the overall deadline from step 2). Crucial at scale: a per-client **retry budget** (e.g. retries ≤ 10–20% of total requests). Retrying at *every* layer multiplies: 3 layers × 3 retries = 27× load on the bottom service. **Retry at exactly one layer** (usually the lowest, closest to the dependency) and have outer layers fail fast.
+
+7. **Add a circuit breaker so a dead dependency fails instantly.** Stop sending into a hole; give it room to recover. States: **closed** (pass through, count failures) → **open** (fail fast immediately, no call) → **half-open** (after a cooldown, allow a few probes; success → closed, failure → open). Trip on **error-rate over a rolling window** (e.g. >50% of ≥20 calls) rather than raw consecutive failures (less noisy under low traffic). Per-dependency breaker — never one global breaker for all downstreams.
+
+8. **Bulkhead: isolate pools so one sick dependency can't drown the rest.** Give each downstream its *own* connection pool / thread pool / semaphore with a bounded max. Without it, slow calls to dep A consume every worker and requests to healthy dep B also fail. resilience4j `Bulkhead`/`ThreadPoolBulkhead`; a per-dependency `Semaphore(N)`; separate HTTP clients with separate `maxConnsPerHost`. Bound the pool *and* the wait-for-a-slot timeout.
+
+9. **Backpressure & load-shed when *you're* the one overwhelmed.** Bounded queues only — an unbounded queue just hides the overload until OOM and inflates latency past every deadline. When the queue/pool is full, **reject early**: return `503` (or `429`) with `Retry-After` and shed load *before* doing expensive work. Fast rejection beats slow timeout. (Inbound *policy* limits → rate-limiting; this is shedding under acute overload.)
+
+10. **Choose fail-fast vs fail-open/degrade per call deliberately.** On exhausted retries / open breaker: **fail-fast** (propagate the error) for must-be-correct calls (payment authorize); **fail-open / degrade** for optional ones — return a cached/stale value, a default, or a partial response so one non-critical dep can't take down the page. Decide and document it; never default to "throw 500".
+
+11. **Hedge requests for tail latency (read-only/idempotent only).** If p99 ≫ p50, send a second (parallel) request after a delay (e.g. at the p95 latency mark), take whichever returns first, cancel the loser. Cuts tail latency at the cost of extra load — gate it (e.g. ≤5% hedged) so it doesn't amplify during an incident. gRPC supports hedging policy natively. Never hedge non-idempotent writes.
+
+12. **Use the battle-tested library, not a hand-rolled `for` loop.**
+
+    | Stack | Use | Notes |
+    |---|---|---|
+    | Java/Kotlin | **resilience4j** | `Retry` + `CircuitBreaker` + `Bulkhead` + `TimeLimiter`, composed; order matters (TimeLimiter inside Retry) |
+    | .NET | **Polly** | `ResiliencePipeline`: `AddRetry` (with jitter) + `AddCircuitBreaker` + `AddTimeout` |
+    | Python | **tenacity** or **backoff** | `@retry(wait=wait_random_exponential(max=10), stop=stop_after_attempt(3), retry=retry_if_exception_type(...))` |
+    | Go | **failsafe-go** / **sony/gobreaker** | gobreaker for the breaker; failsafe-go for retry+backoff+circuit composed |
+    | JS/TS | **p-retry** + `AbortSignal.timeout` | p-retry for backoff; `opossum` for the circuit breaker |
+    | gRPC | service-config `retryPolicy` + `hedgingPolicy` | declarative; set deadlines on the client |
+    | Mesh | **Envoy / Istio** | `retryPolicy` (`retry_on: 5xx,connect-failure,retriable-4xx`) + `numRetries` + **outlier detection** (the mesh's circuit breaker — ejects bad hosts) |
+
+    Push retry/breaker policy to the mesh (Envoy/Istio) when you can — it's per-route, consistent across languages, and observable. Keep app-level resilience for finer control (idempotency-aware retries, fallbacks).
+
+13. **Make all of it observable.** Emit metrics per dependency: attempt count, retry count, breaker state transitions, timeout count, shed/rejected count, p99 latency. A breaker that's silently open looks identical to a healthy-but-idle dependency — you must be able to see it. Alert on breaker-open and on retry-budget exhaustion.
+
+## Anti-Patterns
+
+| Anti-pattern | Why it bites | Fix |
+|---|---|---|
+| Retrying a non-idempotent POST | Double charge / duplicate record | Idempotency key (→ idempotency-keys) or don't retry |
+| Backoff with no jitter | Synchronized retry storm hammers the recovering dep | Full jitter |
+| Unbounded retries (`while`/no cap) | Burns budget, melts the dependency | Cap 2–3 + overall deadline |
+| Retries nested at every layer | 3×3×3 = 27× load multiplication | Retry at ONE layer only |
+| Retrying inside a retry (library + manual) | Hidden multiplication, double the attempts | Pick one place to own retries |
+| No timeout / infinite default | One hung call drains the whole pool → service down | Bound connect+read+total |
+| Retrying 4xx (400/401/404) | Same input, same failure — pure waste | Only retry 5xx/408/429/connect errors |
+| One global circuit breaker | One bad dep opens the breaker for all deps | Per-dependency breaker + bulkhead |
+| Unbounded queue for backpressure | Latency blows past deadlines, then OOM | Bounded queue + reject early (503/Retry-After) |
+| Same timeout at every layer | Inner timeout ≥ outer → outer fires first, inner work wasted | Propagate a shrinking deadline |

package/skills/resolve-merge-rebase-conflict/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: resolve-merge-rebase-conflict
+description: Resolves non-trivial merge, rebase, and cherry-pick conflicts by reading both sides' intent and combining hunks — handling rename/delete/add-add/binary conflicts, enabling rerere for repeats, and verifying the result builds and tests green rather than just clearing markers.
+when_to_use: A merge/rebase/cherry-pick halts on conflicts (large or semantic), or the same conflict keeps recurring. Not clean commits/PRs (git-commit-pr), intentional history editing (rewrite-git-history), or recovering lost work (recover-git-state).
+---
+
+## When to Use
+
+- "`git merge`/`git rebase`/`git cherry-pick` stopped with conflicts and I need to finish it correctly."
+- "Big conflict across many files after a long-lived branch — which side wins where?"
+- "The same conflict keeps coming back every rebase."
+- "`<<<<<<<`/`=======`/`>>>>>>>` markers everywhere and the two sides changed the *same* logic differently."
+- "rename/rename, modify/delete, add/add, or a binary asset conflicted and `--ours`/`--theirs` isn't obvious."
+
+NOT this skill:
+- Writing the commit message / opening the PR once the tree is clean → git-commit-pr
+- Deliberately reshaping history (squash, reorder, split, drop commits) when there's no conflict to resolve → rewrite-git-history
+- A rebase/merge that ate your work, detached HEAD, or you need a commit back via reflog → recover-git-state
+
+## Steps
+
+1. **Identify the operation first — `ours`/`theirs` MEANING FLIPS.** The same flag points opposite directions depending on what's running. Check `git status` (it names the op) before touching anything:
+
+   | Operation | `HEAD` / `--ours` is | `MERGE_HEAD` / `--theirs` is | Mental model |
+   |---|---|---|---|
+   | `git merge X` | your current branch | the branch X you're merging in | ours = where you are |
+   | `git rebase X` | **X (upstream)** — replayed onto | **your commit** being reapplied | **inverted**: "ours" is the base you're moving onto, "theirs" is your own change |
+   | `git cherry-pick C` | your current branch | commit C being applied | like merge |
+   | `git revert C` | your current branch | the inverse of C | like merge |
+
+   In a rebase, blindly taking `--ours` throws away *your own* work. Never run `checkout --ours/--theirs` on autopilot during a rebase.
+
+2. **Turn on zdiff3 so you can see the base.** Default `merge` style hides the common ancestor, so you can't tell which side actually changed what:
+
+   ```sh
+   git config --global merge.conflictStyle zdiff3   # adds a ||||||| base section between the two sides
+   git config --global rerere.enabled true          # record+replay resolutions (step 7)
+   ```
+
+   With zdiff3 a hunk shows `<<<<<<< ours` / `||||||| base` / `======= theirs` / `>>>>>>>`. Compare each side *against base*: the side that differs from base is the one that changed; if both differ, you must merge them by hand.
+
+3. **Survey the whole conflict before editing one file.** `git status` lists unmerged paths; `git diff --diff-filter=U` shows only conflicted hunks. Classify each path: content conflict, or a *tree* conflict (rename/delete/add). Resolve content hunks by **intent**, not by picking a side:
+   - If both sides differ from base, you almost always want **both changes combined**, not one discarded. Read what each side was trying to do, write the union that satisfies both, delete all markers.
+   - Only take one side wholesale when the other is genuinely superseded (e.g. theirs deleted a function ours merely reformatted).
+   - For a single file you've decided entirely belongs to one side: `git checkout --ours -- <path>` / `--theirs -- <path>` (remember the rebase flip), then `git add <path>`.
+
+4. **Handle tree conflicts deliberately — markers won't appear:**
+   - **modify/delete** (`deleted by us`/`deleted by them`): git can't merge a hunk into a missing file. Decide: keep the file and reapply the other side's change (`git add <path>`), or honor the delete (`git rm <path>`). Default: keep it if the surviving side still calls into it.
+   - **rename/rename** (same file renamed to two names, or both edited one rename): git leaves multiple paths. Pick the intended final name, move the merged content there, `git rm` the stray path, `git add` the keeper.
+   - **add/add** (both branches created the same path with different content): treat exactly like a content conflict — merge the two versions into one file, `git add`.
+   - **binary / generated** (images, lockfiles, compiled assets): no line merge possible. Choose a side on purpose — `git checkout --theirs -- yarn.lock && git add yarn.lock` — then **regenerate** rather than trust either copy (e.g. re-run `yarn install` / `npm install` and commit the result, never hand-stitch a lockfile).
+
+5. **Continue, don't re-stage by hand at the end.** After every conflicted path is `git add`-ed (or `git rm`-ed):
+   - merge → `git commit` (uses the prepared merge message)
+   - rebase → `git rebase --continue`
+   - cherry-pick → `git cherry-pick --continue`
+   Repeat per replayed commit — a rebase can stop again on the next commit; resolve each in turn.
+
+6. **Know the three exits.** Don't thrash a bad resolution — bail and retry with a cleaner head:
+
+   | Command | Effect | Use when |
+   |---|---|---|
+   | `--continue` | accept current resolution, proceed | you resolved correctly |
+   | `--abort` | restore the pre-operation state exactly | resolution is going sideways; start over |
+   | `--skip` | drop the current commit being applied (rebase/cherry-pick only) | this commit is already upstream / empty after resolution — **never** to dodge a hard conflict |
+
+   `git merge --abort` / `git rebase --abort` / `git cherry-pick --abort` always returns you to safety. Prefer abort + a fresh attempt over forcing a tangled hunk.
+
+7. **Let rerere kill the repeats.** With `rerere.enabled true` (step 2), git records each manual resolution and **auto-replays** it the next time the identical conflict appears — invaluable when rebasing a long branch onto a moving main, or re-running a merge. Inspect with `git rerere status`/`git rerere diff`; if rerere replayed a *wrong* prior resolution, `git rerere forget <path>` and redo it.
+
+8. **Build and test BEFORE declaring done — clearing markers is not resolving.** A tree with zero markers can still compile to wrong behavior: you may have dropped one side's logic, or combined two valid hunks into a contradiction. Run the project's real build + test (`npm test`, `cargo build && cargo test`, `pytest`, `make`) on the resolved tree. Fix failures at the merge seams, not by weakening assertions. Only then commit/continue.
+
+9. **Reduce future conflicts (avoidance > resolution).** Keep PRs small and short-lived; `git fetch && git rebase origin/main` (or merge main in) frequently so you resolve a little, often, against fresh base instead of a giant divergence later; agree on formatting (run the formatter on both sides) so whitespace/reflow doesn't manufacture conflicts.
+
+## Common Errors
+
+- **`checkout --ours`/`--theirs` during a rebase, expecting merge semantics.** The labels are inverted — `--ours` is upstream, `--theirs` is your own commit. Result: you silently delete your own changes. Confirm the op via `git status` first; in rebase, *theirs* is usually what you want to keep.
+- **Committing with conflict markers still in the file.** `<<<<<<<`/`=======`/`>>>>>>>` left behind ship as literal source and break the build. Grep the whole tree before committing (see Verify) — don't trust your eyes per-file.
+- **Default `merge` conflictStyle, guessing which side changed.** Without the `|||||||` base you can't see the common ancestor and pick wrong. Set `merge.conflictStyle=zdiff3` once, globally.
+- **Blindly taking one side to "make it go away."** `checkout --theirs` on a content conflict where both sides added needed logic drops half the work with a clean exit code. Conflicts where both differ from base almost always want the *union*.
+- **Treating modify/delete as nothing to do.** No markers appear, so it looks resolved — but you must explicitly `git add` (keep) or `git rm` (delete). Leaving it unstaged stalls `--continue`.
+- **Hand-merging a lockfile or binary.** `package-lock.json`/`yarn.lock`/`Cargo.lock` and images can't be line-merged sanely. Pick a side, then regenerate (`npm install`) or re-export — a stitched lockfile installs a phantom dependency graph.
+- **`git rebase --skip` to escape a hard conflict.** Skip *drops the entire commit*, silently losing that change. Only skip a commit already present upstream or empty after resolution; otherwise resolve it.
+- **Declaring done at zero markers without building.** A syntactically clean merge can be semantically broken (dropped branch, double-applied change). Always run build + tests on the resolved tree.
+- **rerere replaying a stale wrong resolution.** Once enabled it auto-applies your *previous* answer even if that answer was the bug. If an auto-resolved hunk looks off, `git rerere forget <path>` and redo.
+- **Resolving one conflict in a multi-commit rebase and assuming you're done.** Rebase stops per commit; `--continue` may immediately halt on the next. Loop until `git status` reports no rebase in progress.
+
+## Verify
+
+1. **No markers anywhere:** `git grep -nE '^(<{7}|={7}|>{7}|\|{7})' -- ':!*.md'` returns nothing (also catches the zdiff3 `|||||||` base line). Empty output is mandatory.
+2. **No unmerged paths:** `git status --porcelain` shows no `UU`/`AA`/`DU`/`UD`/`DD`/`AU`/`UA` entries; `git diff --diff-filter=U` is empty.
+3. **Operation actually finished:** `git status` reports no merge/rebase/cherry-pick in progress (no `.git/MERGE_HEAD`, `.git/rebase-merge`, or `CHERRY_PICK_HEAD`).
+4. **Build + tests green on the resolved tree** — the project's real commands (`npm test` / `cargo test` / `pytest` / `make`), not a marker check standing in for verification.
+5. **Both sides' intended changes are present:** diff the result against each parent and confirm neither side's needed logic was dropped. For a finished merge: `git diff HEAD^1 HEAD` (your side) and `git diff HEAD^2 HEAD` (the merged-in side). For a rebase, `git range-diff @{upstream}...HEAD` shows your commits survived intact.
+6. **rerere recorded reusable resolutions** (if conflicts may recur): `git rerere status` is clean and future identical conflicts auto-resolve.
+
+Done = zero conflict markers, no unmerged paths, the operation is complete, build + tests pass on the resolved tree, and a diff against both parents confirms each side's intended change is present.

package/skills/rewrite-git-history/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: rewrite-git-history
+description: Rewrites git history safely — interactive rebase (squash/split/reorder/reword/edit), amend, and git filter-repo/BFG to purge a committed secret or large file — using force-with-lease and explicit shared-branch safeguards.
+when_to_use: Cleaning up a feature branch before merge, purging a committed secret or large blob from all history, or splitting/squashing commits. Distinct from git-commit-pr (normal commit/PR), resolve-merge-rebase-conflict (fixing conflicts), and recover-git-state (recovering lost commits).
+---
+
+## When to Use
+
+Reach for this skill when you must **change commits that already exist**, not create new ones:
+
+- "Squash these 6 WIP commits into one before merging"
+- "Reword that commit message / fix the author/email on old commits"
+- "Split this giant commit into logical pieces"
+- "Reorder / drop a commit from my branch"
+- "I committed an API key / `.env` / a 400 MB binary — scrub it from the whole history"
+- "Amend the last commit, I forgot a file"
+
+NOT this skill:
+- Writing a normal commit message or opening a PR on un-rewritten work → git-commit-pr
+- A rebase/merge that stopped on `CONFLICT` markers → resolve-merge-rebase-conflict
+- Lost a commit/branch after a bad rebase/reset, need it back → recover-git-state
+- Moving plaintext secrets into a vault, rotating, or scanning for leaks → secrets-management (run *after* the purge here)
+
+## Steps
+
+1. **Apply the golden rule first — is this branch shared?** Rewriting changes every downstream SHA; anyone who pulled the old history gets a divergent tree and can re-push the secret you deleted.
+
+   | Branch state | Rewrite? | How to push |
+   |---|---|---|
+   | Local-only, never pushed | Yes, freely | normal `git push` (first push) |
+   | Pushed, **only you** pull it (personal feature branch) | Yes | `git push --force-with-lease` |
+   | Shared / `main` / release / others have pulled | **No — coordinate first** | announce → everyone stops → rewrite → `--force-with-lease` → everyone re-clones or `git reset --hard origin/<branch>` |
+
+   Default: rewrite only local/unshared branches. For `main`, the answer is almost always "don't" — the only exception is purging a secret, and then only with team sign-off.
+
+2. **Record the safety net before touching anything.** Copy the current tip so you can undo: `git rev-parse HEAD`, and confirm `git status` is clean — stash or commit dirty work first; rebase refuses to start otherwise. The reflog (`git reflog`) keeps the old tip ~90 days regardless, but a written-down SHA is faster.
+
+3. **Interactive rebase for squash/reword/reorder/drop/edit.** Rebase the commits *since* the base, not your whole history:
+
+   ```bash
+   git rebase -i origin/main      # or: git rebase -i HEAD~5
+   ```
+   In the todo editor, set the verb on each line (top = oldest), and **reorder by moving whole lines**:
+
+   | Verb | Effect |
+   |---|---|
+   | `pick` | keep as-is |
+   | `reword` | keep changes, edit the message |
+   | `edit` | stop here to amend content or split (step 4) |
+   | `squash` | fold into the commit above, **combine both messages** |
+   | `fixup` | fold into the commit above, **discard this message** (use for "oops typo" commits) |
+   | `drop` | delete the commit entirely (or just delete the line) |
+
+   Save and close. Resolve any conflicts (→ resolve-merge-rebase-conflict), then `git rebase --continue`. Abort cleanly at any point with `git rebase --abort` — it restores the pre-rebase tip exactly.
+
+4. **Split one commit into several.** Mark it `edit` in the rebase todo; when rebase stops on it:
+   ```bash
+   git reset HEAD^          # un-commit, keep changes in working tree (mixed reset)
+   git add -p               # stage hunk-by-hunk for the first piece
+   git commit -m "first logical change"
+   git add -p && git commit -m "second logical change"   # repeat until clean
+   git rebase --continue
+   ```
+   `git reset HEAD^` (mixed) keeps your work in the tree; never `--hard` here or you lose it.
+
+5. **Amend only the last commit** (no rebase needed): `git commit --amend` (edit message + fold staged changes), or `git commit --amend --no-edit` to silently add forgotten files. If already pushed to your own branch, follow with `git push --force-with-lease`.
+
+6. **Purge a file/secret across ALL history — `git filter-repo` (preferred, BFG fallback).** `git filter-branch` is deprecated and slow; do not use it.
+   ```bash
+   pip install git-filter-repo        # or: brew install git-filter-repo
+   # Remove a path everywhere (history rewritten in place):
+   git filter-repo --path config/secrets.yml --invert-paths
+   # Or redact a literal string/regex from every blob:
+   printf 'AKIAIOSFODNN7EXAMPLE==>REDACTED\n' > replacements.txt
+   git filter-repo --replace-text replacements.txt
+   ```
+   BFG alternative for big blobs: `bfg --delete-files '*.zip'` or `bfg --replace-text replacements.txt`, then `git reflog expire --expire=now --all && git gc --prune=now --aggressive`. `filter-repo` runs that cleanup for you and removes the `origin` remote on purpose — re-add it before pushing.
+
+7. **ROTATE the leaked secret — rewriting history does NOT un-leak it.** Anyone who cloned, any fork, any CI cache, and GitHub's own unreachable-commit cache still hold it. The history scrub is step 1 of 2; the real fix is: **revoke + reissue the key/token/password at the provider** (then → secrets-management). Treat the credential as compromised the moment it was pushed.
+
+8. **Force-push with `--force-with-lease`, never bare `--force`.**
+   ```bash
+   git push --force-with-lease origin <branch>
+   ```
+   `--force-with-lease` refuses the push if the remote moved since your last fetch — it catches the case where a teammate pushed in the meantime, which bare `--force` would silently obliterate. For a full-history purge you must push every ref: `git push --force-with-lease --all && git push --force-with-lease --tags`.
+
+## Common Errors
+
+- **Force-pushing a shared/`main` branch without coordination.** Everyone else's next pull diverges, and someone re-pushes the deleted secret. Confirm the branch is unshared (step 1) or get explicit sign-off first.
+- **Using bare `git push --force`.** Overwrites whatever is on the remote with zero safety check, including a teammate's just-pushed commits. Always `--force-with-lease`.
+- **Thinking the rewrite removed the secret.** It only removed it from *your* refs. Forks, clones, CI caches, and GitHub's cached unreachable commits still expose it — rotate the credential (step 7). This is the single most common and most damaging mistake.
+- **`git reset --hard HEAD^` when splitting a commit.** Discards the very changes you were trying to re-commit. Use `git reset HEAD^` (mixed) to keep them in the working tree.
+- **Rebasing onto the wrong base** (`HEAD~10` swallows commits already on `main`). Rebase against the tracking base, e.g. `git rebase -i origin/main`, so you only touch your own commits.
+- **Reordering by editing SHAs or text instead of moving whole lines.** The rebase todo is line-ordered; cut/paste entire lines to reorder. Editing a hash breaks the rebase.
+- **`squash` when you meant `fixup`** (or vice versa). `squash` opens an editor to combine both messages; `fixup` drops the second message. Picking wrong leaves "WIP"/"typo" text in your final message.
+- **Running `git filter-repo` on a dirty or non-fresh clone.** It refuses non-fresh clones by default for safety; work on a fresh `git clone` (or pass `--force` only when you understand why), and commit/stash everything first.
+- **Forgetting `filter-repo` dropped the remote.** It removes `origin` deliberately so you can't push to the wrong place by reflex. Re-add it (`git remote add origin <url>`) before the force-push.
+- **Letting purged objects linger.** After a manual `filter-branch`/BFG run, the blobs survive in reflog/packs until `git reflog expire --expire=now --all && git gc --prune=now`. Without it, `git cat-file` still serves the secret locally.
+
+## Verify
+
+1. **Target commits are correct.** `git log --oneline` (and `--stat`/`-p`) shows exactly the intended squash/split/reword/reorder — commit count and each message match the plan.
+2. **No unintended commits dropped.** Diff the rewritten branch against the saved pre-rewrite SHA from step 2: `git range-diff <old-sha> HEAD` (or `git diff <old-sha> HEAD` to confirm the *tree* is identical when you only re-shaped messages/structure, not content). Cross-check `git reflog` for the old tip.
+3. **Secret is gone from every ref, not just `HEAD`.** `git log --all -p -S 'AKIA'` returns nothing, and `git grep -I 'AKIA' $(git rev-list --all)` finds no hits across all history. For a removed path: `git log --all --oneline -- config/secrets.yml` is empty.
+4. **No dangling reachable copy.** After cleanup, `git rev-list --objects --all | grep <blob-sha>` is empty and `git count-objects -v` shows the pack shrank.
+5. **Credential actually rotated.** The old key returns 401/403 from the provider (not just deleted from git). If it still authenticates, you are not done.
+6. **Remote matches and was pushed safely.** `git push --force-with-lease` succeeded (not refused), and `git log origin/<branch> --oneline` equals local. Teammates on a shared branch confirmed re-sync.
+
+Done = intended commits are exactly reshaped with zero unintended drops (verified against the pre-rewrite SHA/reflog), the secret is absent from every ref and every history blob, the leaked credential is rotated and dead at the provider, and the push used `--force-with-lease` on a branch that was either unshared or coordinated.

package/skills/scaffold-cross-platform-app/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: scaffold-cross-platform-app
+description: Scaffolds React Native (Expo Router) and Flutter app shells — feature-first folder layout, typed navigation + deep links, client-store wiring (Zustand/Redux Toolkit/Riverpod/Bloc), platform-divergent code and native bridges (Expo config plugin/Flutter platform channel), token-driven theming with dark mode, and env/build-flavor tooling.
+when_to_use: Standing up or restructuring a whole React Native (Expo) or Flutter app — choosing navigation, client state, platform-conditional code, bridging a native module, theming, and build flavors. Distinct from build-native-mobile-ui (SwiftUI/Compose screens, not RN/Flutter), manage-client-server-state (server cache/data fetching), design-token-system (the token pipeline this skill consumes), and ship-mobile-app-store-release (signing + store upload).
+---
+
+## When to Use
+
+Reach for this skill when the request is about **standing up or reorganizing a whole RN/Flutter app**, not a single screen:
+
+- "Set up a new Expo app with tabs + a typed navigation stack and deep links"
+- "Start a Flutter app with go_router and Riverpod, organized by feature"
+- "Pick state management — Redux Toolkit vs Zustand / Bloc vs Riverpod — and wire it"
+- "I need iOS-only and Android-only versions of this code / an adaptive widget"
+- "Bridge a native module / write an Expo config plugin / add a Flutter platform channel"
+- "Apply our design tokens + dark mode across the app shell"
+- "Add dev/staging/prod flavors with separate env, bundle IDs, and icons"
+
+NOT this skill:
+- A **native** iOS/Android screen in SwiftUI or Jetpack Compose (not RN/Flutter) → build-native-mobile-ui
+- Building one reusable RN component in an existing tree → build-react-component
+- Server-cache, fetching, optimistic updates, query invalidation → manage-client-server-state (this skill wires *client* state only)
+- Designing the token **architecture/pipeline** (primitive/semantic tiers, Style Dictionary, W3C export) → design-token-system (this skill *consumes* the exported tokens)
+- Pixel-matching a Figma/screenshot for a screen → implement-from-design
+- Tailwind/responsive web layout → style-responsive-tailwind
+- E2E flows on the running app → write-playwright-e2e
+- Code signing, keystores, TestFlight/Play upload, phased rollout → ship-mobile-app-store-release
+- The CI workflow that calls build/sign/upload lanes (EAS/Codemagic/Fastlane in CI) → cicd-pipeline-author
+- Storing signing keys / API secrets safely → secrets-management
+
+## Steps
+
+1. **Pick the framework lane and don't drift mid-project.** Default to **Expo (managed) + Expo Router** for RN, **Flutter stable + go_router** for Dart. Go bare RN only when a dependency needs native build config the managed prebuild can't express.
+
+   | Need | RN choice | Flutter choice |
+   |---|---|---|
+   | Standard app, OTA updates, fast start | **Expo managed** + `expo-dev-client` | Flutter stable |
+   | Custom native code you control | Expo + **config plugin** (stay managed) | Flutter + plugin/FFI |
+   | Native build settings Expo can't model | bare RN (`expo prebuild` then own `ios/`,`android/`) | n/a |
+   | Routing | **Expo Router** (file-based, typed) | **go_router** (typed routes) |
+   | New project command | `npx create-expo-app@latest -t default` | `flutter create --org com.acme app` |
+
+   Reject React-Navigation-only (no router) for new apps: Expo Router *is* React Navigation underneath but gives file-based deep linking for free.
+
+2. **Lay out feature-first, not type-first.** Group by domain so a feature is one deletable folder. Avoid the top-level `screens/ components/ reducers/` split — it scatters every feature across the tree.
+
+   ```
+   src/
+     app/                 # Expo Router routes (file = route). Flutter: lib/routing/
+       (tabs)/index.tsx   # deep link: myapp://  →  /
+       (tabs)/profile.tsx
+       post/[id].tsx      # myapp://post/42
+       _layout.tsx        # Stack/Tabs + theme provider
+     features/
+       auth/  { ui/  store.ts  api.ts  types.ts }
+       feed/  { ui/  store.ts  api.ts }
+     shared/  { ui/  hooks/  theme/  lib/ }
+     platform/            # *.ios.tsx / *.android.tsx live next to use site
+   ```
+   Flutter mirror: `lib/features/<x>/{presentation,application,data,domain}`, `lib/core/theme`, `lib/routing/app_router.dart`.
+
+3. **Make routes typed and deep-linkable from day one.**
+   - **Expo Router:** enable typed routes in `app.json` → `"experiments": { "typedRoutes": true }`. Set `scheme` in `app.json` (`"scheme": "myapp"`) so `myapp://post/42` resolves; for universal/app links add `expo-router` `+native-intent` or `associatedDomains`. Nest with `_layout.tsx`: a `(tabs)` group holds `<Tabs>`, a sibling `_layout` holds a `<Stack>` for modals/detail. Navigate with `router.push({ pathname: '/post/[id]', params: { id } })` — params are type-checked.
+   - **go_router:** define routes once, use `GoRoute` + `context.goNamed('post', pathParameters: {'id': id})`. Configure `MaterialApp.router(routerConfig: appRouter)`. Deep links work via the platform `<intent-filter>` (Android) / `CFBundleURLTypes` (iOS) — wire `uriPrefix`/`scheme` to match the route table.
+
+4. **Wire client state by app shape — opinionated defaults, no "it depends":**
+
+   | App | RN | Flutter | Why |
+   |---|---|---|---|
+   | Small/medium, mostly local UI state | **Zustand** | **Riverpod** | Minimal boilerplate, no provider-tree gymnastics |
+   | Large, many devs, time-travel/devtools, strict conventions | **Redux Toolkit** | **Bloc** | Enforced structure, traceable events, predictable reducers |
+   | Server data (lists, caches, mutations) | **TanStack Query** | Riverpod `AsyncNotifier` / `dio` | Don't hand-roll cache in the store → manage-client-server-state |
+
+   Default to **Zustand** (RN) / **Riverpod** (Flutter) unless team size or audit needs push you to RTK/Bloc. **Boundary rule:** keep *server cache* out of the global store; the store holds session, auth, theme, navigation-adjacent UI state. One `store.ts`/notifier per feature; compose at app root, never one god-store.
+
+   ```ts
+   // features/auth/store.ts — Zustand slice, typed, selector-friendly
+   export const useAuth = create<AuthState>()((set) => ({
+     user: null, token: null,
+     signIn: async (c) => { const { user, token } = await api.login(c); set({ user, token }); },
+     signOut: () => set({ user: null, token: null }),
+   }));
+   // read narrowly to avoid re-renders: const user = useAuth(s => s.user)
+   ```
+
+5. **Diverge by platform with the cheapest tool that works.** Escalate only as needed:
+   - **One value differs:** `Platform.select({ ios: 12, android: 8, default: 8 })` or `Platform.OS === 'ios'`. Flutter: `Theme.of(context).platform == TargetPlatform.iOS` or `defaultTargetPlatform`.
+   - **A whole component differs:** split files — `Button.ios.tsx` / `Button.android.tsx`; import `./Button` and Metro resolves per-platform. Flutter: `Platform.isIOS ? CupertinoButton(...) : ElevatedButton(...)`, or conditional imports for web vs native.
+   - **Adaptive by design:** Flutter `Switch.adaptive`, `CupertinoIcons` on iOS; RN use a wrapper that picks the native control. Never branch on `Platform.OS` deep inside business logic — isolate divergence at the UI/platform layer.
+
+6. **Bridge native code through the framework's official channel — never patch generated folders by hand.**
+   - **Expo config plugin** (stay managed): write a plugin that mutates native config at prebuild, e.g. `withInfoPlist` / `withAndroidManifest`, register in `app.json` `"plugins": ["./plugins/with-foo"]`. For real native APIs use the **Expo Modules API** (`createModule`, Swift/Kotlin) — typed JS interface, no manual bridge boilerplate.
+   - **Bare RN:** Turbo/Native Module — declare a TS spec, run Codegen, implement on iOS (Swift/ObjC) + Android (Kotlin/Java).
+   - **Flutter platform channel:** `MethodChannel('com.acme/foo')` on Dart side; implement the matching handler in `AppDelegate.swift` and `MainActivity.kt`. Keep the channel name and method strings in one shared constants file so both sides can't drift.
+   ```dart
+   const _ch = MethodChannel('com.acme/battery');
+   Future<int> level() async => await _ch.invokeMethod<int>('getLevel') ?? -1;
+   ```
+   After any native change run `expo prebuild --clean` (Expo) or `flutter clean` and rebuild — JS/Dart hot reload will NOT pick up native edits.
+
+7. **Consume design tokens at the app shell; theme from them, don't hardcode.** Build the token source/pipeline with design-token-system; *this* step wires its output into RN/Flutter theming. One `theme/tokens.ts` (or `core/theme/tokens.dart`) holds colors/spacing/radii/typography. Build light+dark from the same tokens; resolve via system scheme.
+   - **RN:** export a `light`/`dark` theme object keyed off tokens; read `useColorScheme()`; pass to a `ThemeProvider` (or Expo Router's `<ThemeProvider value={scheme === 'dark' ? Dark : Light}>`). Never inline hex in components — pull from theme.
+   - **Flutter:** `MaterialApp(theme: lightFromTokens, darkTheme: darkFromTokens, themeMode: ThemeMode.system)`; build `ColorScheme.fromSeed(seedColor: tokens.brand)`; use `CupertinoTheme` where you ship iOS-native chrome. Dark mode = the dark token set + `themeMode`, not ad-hoc `if (isDark)` checks.
+
+8. **Set up tooling once so the app is reproducible:**
+   - **Env/flavors:** RN — `app.config.ts` reading `process.env`, build profiles in `eas.json` (`development`/`preview`/`production`), distinct `bundleIdentifier`/`package` per profile. Flutter — `--flavor dev|staging|prod` with `--dart-define-from-file=env/dev.json`, matching Xcode schemes + Android `productFlavors`. **Secrets never in `app.json`/committed `.env`** → secrets-management. **Signing certs, keystores, and store upload** are out of scope → ship-mobile-app-store-release.
+   - **Fonts/assets:** RN `expo-font` `useFonts()` (or `expo-asset` preload), gate render on loaded; Flutter declare under `pubspec.yaml` `fonts:`/`assets:`.
+   - **Types/lint:** TS `strict: true`, `eslint` + `eslint-config-expo`, `prettier`; Flutter `flutter analyze` + `flutter_lints`. Add a `typecheck` script (`tsc --noEmit`) to CI.
+   - **Fast refresh** is on by default — if it stops working, it's almost always a non-component export or a circular import, not the bundler.
+
+## Common Errors
+
+- **Type-first folders (`screens/`, `reducers/`, `components/`).** Every feature smears across the tree; deleting a feature touches 6 folders. Group by feature, share only truly shared code in `shared/`.
+- **One global store for everything including server data.** Caching API responses in Zustand/Redux means manual invalidation and stale UI. Put server cache in TanStack Query / Riverpod `AsyncNotifier`; keep the store for session/UI state.
+- **`Platform.OS` checks buried in business logic.** Divergence leaks everywhere and is untestable. Isolate it at the UI/platform layer via `.ios`/`.android` files or `Platform.select`.
+- **Editing `ios/` or `android/` by hand on a managed Expo app.** The next `prebuild` wipes it. Express native changes as a **config plugin** or Expo Module instead.
+- **Native change with no rebuild.** Hot reload/Fast Refresh only reloads JS/Dart. A new native module or channel needs `expo prebuild --clean` / `flutter clean` + a fresh native build, or you'll debug a phantom "method not found."
+- **Hardcoded hex colors / magic spacing.** Dark mode and rebrands become a find-and-replace. Pull every color/space/radius from the token theme; derive light+dark from one source.
+- **Missing `scheme` / intent-filter, so deep links silently no-op.** Set `scheme` in `app.json` (RN) and the Android `<intent-filter>` + iOS `CFBundleURLTypes` (Flutter) to match the route table, or `myapp://post/42` opens the app to the home screen.
+- **Mismatched platform-channel/method names across Dart↔native.** A typo yields a silent `MissingPluginException` at runtime. Keep channel + method strings in one shared constant referenced by both sides.
+- **Same `bundleIdentifier`/`applicationId` across flavors.** Dev and prod overwrite each other on-device and can't coexist. Give each flavor a distinct id + icon + display name.
+- **Untyped navigation params.** `router.push('/post/' + id)` loses type-checking and breaks on refactor. Enable typed routes (Expo) / named go_router routes and pass params as objects.
+
+## Verify
+
+Run on **both** an iOS simulator and an Android emulator/device — a single-platform pass proves nothing cross-platform.
+
+1. **Boots clean both OSes:** `npx expo run:ios` and `npx expo run:android` (or `flutter run -d ios` / `-d android`) start with **no red box / no exception**, app reaches the first screen.
+2. **Typed navigation + deep links:** a wrong route param fails `tsc --noEmit`/`flutter analyze`. `xcrun simctl openurl booted myapp://post/42` and `adb shell am start -a android.intent.action.VIEW -d "myapp://post/42"` both open the correct detail screen with the right id.
+3. **State wiring:** an action mutates the store and exactly the subscribed components re-render (verify with a render log/devtools); unrelated screens do not. Server data lives in the query cache, not the store.
+4. **Platform divergence resolves:** the `.ios`/`.android` (or adaptive) variant renders the native-looking control on each OS — confirm by screenshot, not assumption.
+5. **Native bridge round-trips:** call the module/channel method on both platforms and get a real value back (not `-1`/`MissingPluginException`); confirm a rebuild was done after the native edit.
+6. **Theming + dark mode:** toggle system appearance on each OS → colors/typography flip via tokens, no hardcoded color survives; no contrast regressions.
+7. **Flavors:** build `dev` and `prod` → distinct bundle id + icon + name, each reading its own env, no committed secret in the bundle.
+8. **Lint/types green:** `tsc --noEmit` + `eslint .` (or `flutter analyze`) pass with zero errors.
+
+Done = the app builds and runs on iOS *and* Android, deep links and typed nav resolve on both, state/theming/native-bridge round-trip correctly per platform, and lint + typecheck are green.

package/skills/schema-evolution-compatibility/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: schema-evolution-compatibility
+description: Evolves shared data contracts (events, API payloads, DB columns, protobuf/avro) without breaking live consumers — additive-only changes with optional+default fields, NEVER remove/rename/repurpose a field or reuse a protobuf tag / avro position (reserve them with `reserved`/aliases instead), backward vs forward vs full compatibility chosen per producer/consumer upgrade order, expand-then-contract (dual-write/dual-read) migrations for renames and type changes, and a schema registry (Confluent/Buf) wired into CI to mechanically reject incompatible diffs before merge. Tolerant reader, unknown-field preservation, and explicit versioning when a true break is unavoidable.
+when_to_use: Changing a schema that something else already reads or writes — adding/removing/renaming a field on a Kafka event, API JSON payload, protobuf/avro/JSON-Schema, or a DB column other services depend on; deciding if a change is safe to deploy and in what order; or wiring registry compat checks into CI. Distinct from design-protobuf-grpc-service (designs the IDL/RPCs from scratch; this evolves an existing one safely) and db-migration-safety (runs the ALTER without locking/downtime; this decides whether the column change breaks readers at all).
+---
+
+## When to Use
+
+Reach for this skill when a contract that *another* process already produces or consumes is changing and you must not break it mid-deploy:
+
+- "Add a field to this Kafka event / API response — will old consumers still parse it?"
+- "Rename / remove / change the type of a field that other services read"
+- "Which compatibility mode (backward/forward/full) for this Avro subject?"
+- "We reused a protobuf field number and a consumer is reading garbage"
+- "Deploy producers or consumers first? what's the safe order?"
+- "Wire `buf breaking` / Confluent compat checks into CI so bad diffs get blocked"
+- "Migrate a column/field rename with zero downtime across services"
+
+NOT this skill:
+- Designing the proto/gRPC service, message shapes, and RPCs from scratch → design-protobuf-grpc-service (this skill *evolves* an IDL that already has live readers)
+- Running the `ALTER TABLE` itself without locks/downtime (lock-free index, batched backfill, `NOT VALID` constraints) → db-migration-safety (it makes the DDL safe; this skill decides if the column change breaks consumers)
+- Designing the relational schema / normalization / keys → design-relational-schema
+- The REST/GraphQL field-type and nullability contract for one endpoint → rest-graphql-contract
+- API versioning policy, deprecation headers, pagination contracts → api-design-review / design-api-pagination
+- Validating one payload against a schema at the edge (request validation) → build-form-validation / validate-data-quality
+- Verifying producer and consumer agree via recorded pacts → contract-testing (it tests the agreement; this skill governs how the schema may change)
+- Big phased rewrite/cutover of a whole system → plan-strangler-migration
+
+## Steps
+
+1. **Pick the compatibility mode from your upgrade order — it's the whole game.** Compatibility is asymmetric and defined by *who reads data written under the other schema*:
+
+   | Mode | Guarantees | Allowed change | Upgrade FIRST |
+   |---|---|---|---|
+   | **BACKWARD** | new consumer reads data from old + new producers | **add** optional field (w/ default), **delete** optional field | **consumers** |
+   | **FORWARD** | old consumer reads data from new producer | **add** optional field, **delete** field that had a default | **producers** |
+   | **FULL** | both directions | **only** add/remove **optional fields with defaults** | either |
+   | **\*_TRANSITIVE** | same, but vs **all** prior versions not just the last | — | — |
+
+   Default to **BACKWARD** for events/topics (Confluent's default — consumers lag and replay history, so the new reader must handle old records). Use **FORWARD** when producers ship ahead of consumers. Use **FULL_TRANSITIVE** for long-lived event logs you replay from the beginning. The rule of thumb: **add a field → forward-safe; remove a field → backward-safe; do both safely → only optional+default**.
+
+2. **Additive-only is the safe default. Every new field is optional with a default — never required.** A new *required* field breaks every old producer (forward) and every old record (backward) instantly. Concretely:
+   - **JSON / JSON-Schema:** add the key, do NOT add it to `required`, give consumers a default. Keep `additionalProperties` permissive (or `unevaluatedProperties` in 2020-12) so old readers tolerate fields they don't know.
+   - **protobuf (proto3):** every field is already optional; new scalar fields default to `0`/`""`/`false`. Just append with a **fresh field number**. Use `optional` (proto3 explicit presence) when you must distinguish "unset" from "zero".
+   - **Avro:** a new field **must** carry a `"default"`, or it's neither backward- nor forward-compatible — `{"name":"x","type":["null","string"],"default":null}`. This is the #1 Avro footgun.
+
+3. **NEVER remove, rename, or repurpose a field in place — and NEVER reuse a tag/number/position.** Renaming = remove + add to every consumer; changing a field's *meaning* while keeping its name/number is the worst break because it passes schema checks but silently corrupts data. Reuse of an identifier makes old payloads decode into the wrong field. Reserve instead:
+   - **protobuf** — when you drop field `7` (name `email`), reserve both so the number and name can never be re-added:
+     ```proto
+     message User {
+       reserved 7, 9 to 11;          // numbers
+       reserved "email", "legacy_id"; // names
+       string username = 3;
+     }
+     ```
+   - **Avro** — never reuse a removed field's name; to *rename* keep the old name reachable via `"aliases": ["old_name"]` so readers using the old schema still resolve it.
+   - **JSON** — treat a removed key as permanently retired; never recycle a key name for a different type/meaning.
+
+   A type change (e.g. `int32 → string`, `string → enum`) is **not** additive even if the name stays — it's a remove-and-add. Wire-compatible widenings exist in proto (`int32`/`int64`/`uint32`/`bool` are interchangeable on the wire; `sint*`/`fixed*` are **not**) but treat them as breaking unless you've verified the exact pair.
+
+4. **For a true rename or type change, run expand → migrate → contract (dual-write/dual-read).** You cannot atomically change a field across N independently-deployed services. Phase it:
+
+   | Phase | Producer | Consumer | DB column |
+   |---|---|---|---|
+   | **1 Expand** | write BOTH `old` + `new` | still reads `old` | add `new` col, backfill, dual-write trigger |
+   | **2 Migrate** | writes both | switch reads to `new` (fallback to `old`) | — |
+   | **3 Contract** | stop writing `old`; reserve it | reads `new` only | drop `old` col (after grace + replay window) |
+
+   Each phase is independently deployable and rollback-safe. The grace window between expand and contract must exceed your **longest consumer lag + replay/retention window** (e.g. Kafka topic retention) so no in-flight or replayed record still needs the old field. The DB column drop is where db-migration-safety takes over.
+
+5. **Deploy in the order the compatibility mode dictates — getting this backwards is the classic outage.**
+   - **BACKWARD** change (added/removed optional): deploy **consumers first**, then producers. New consumers can read both shapes; once all consumers handle the new shape, flip producers.
+   - **FORWARD** change: deploy **producers first** — old consumers tolerate the new field (they ignore unknowns), then upgrade consumers to use it.
+   - **FULL**: either order, but still roll out gradually and watch dead-letter/parse-error metrics during the canary.
+   - Never deploy producer and consumer in lockstep assuming atomicity — there is always a window where mixed versions run.
+
+6. **Run a schema registry with mechanical compatibility checks, and gate CI on them.** Humans miss breaks; the registry doesn't.
+   - **Confluent Schema Registry** (Avro/Protobuf/JSON-Schema over Kafka): set per-subject mode and test the candidate before publishing — `curl -X PUT .../config/<subject> -d '{"compatibility":"BACKWARD_TRANSITIVE"}'`, then `POST .../compatibility/subjects/<subject>/versions/latest` returns `{"is_compatible": true|false}`. The Maven/Gradle `schema-registry:test-compatibility` goal does this in CI.
+   - **protobuf** → **`buf breaking --against '.git#branch=main'`** in CI; rules `FIELD_NO_DELETE` (forces `reserved`), `FIELD_SAME_TYPE`, `RESERVED_*` catch exactly the breaks above. Pair with `buf lint`.
+   - **Avro** standalone → `java -jar avro-tools` or the `avro-compatibility` checker; gate the PR.
+   - **JSON-Schema** → `json-schema-diff` / `oasdiff` (for OpenAPI) flag breaking changes.
+
+   Make the check **fail the build**, not warn. The registry's `compatibility` setting per subject is the contract; CI is the enforcement.
+
+7. **Write consumers as tolerant readers — ignore unknown fields, never hard-fail on them.** Forward compatibility depends on the *reader's* behavior as much as the schema:
+   - JSON: don't use a strict/closed deserializer that throws on unknown keys. Jackson → `@JsonIgnoreProperties(ignoreUnknown = true)` / `FAIL_ON_UNKNOWN_PROPERTIES=false`; Go `encoding/json` ignores unknowns by default (avoid `DisallowUnknownFields`); Pydantic → `model_config = ConfigDict(extra="ignore")` (NOT `"forbid"`).
+   - **Preserve, don't drop, unknown fields** on a read-modify-write path, or a round-trip through an old service silently deletes data a newer one added. protobuf keeps unknown fields by default; for JSON, capture them (`@JsonAnySetter`, `additionalProperties` map) and re-emit. This is the subtle one — a "harmless" old service in the middle of a pipeline strips new fields.
+   - Always provide a default when a field is absent; don't assume presence.
+
+8. **When a break is genuinely unavoidable, version explicitly — don't mutate in place.** Some changes (splitting one field into two, restructuring nesting, semantic redefinition) can't be made compatible. Then:
+   - **Events:** new schema = **new subject / new topic** (`orders.v2`) or an explicit `schema_version` field; run v1 and v2 in parallel; migrate consumers; retire v1 after the replay window. Never silently change `v1`'s meaning.
+   - **APIs:** new path/header version (`/v2`, `Accept: application/vnd.api.v2+json`); deprecate v1 with a sunset header and timeline.
+   Versioning is the escape hatch, not the default — additive evolution avoids a version bump for the 90% case.
+
+## Common Errors
+
+- **Adding a required field.** Breaks every old producer and every historical record at once. Fix: optional + default, always.
+- **Avro field with no `default`.** Silently fails both backward and forward compat. Fix: every Avro field added/removed needs an explicit `"default"`.
+- **Reusing a protobuf field number (or Avro position).** Old payloads decode into the wrong field — type-confused garbage that passes schema checks. Fix: `reserved` the number AND the name; only ever append fresh numbers.
+- **Renaming a field in place.** It's a delete + add to every consumer simultaneously. Fix: expand→migrate→contract, or Avro `aliases`.
+- **Repurposing a field's meaning while keeping its name.** Passes all mechanical checks, silently corrupts semantics. Fix: new field; reserve the old one.
+- **Wrong deploy order for the compat mode.** Backward change with producers-first (or forward with consumers-first) → mixed-version outage. Fix: consumers-first for backward, producers-first for forward.
+- **Strict deserializer that throws on unknown fields.** Kills forward compatibility the moment a producer adds a field. Fix: tolerant reader (`ignoreUnknown`, `extra="ignore"`, no `DisallowUnknownFields`).
+- **Dropping unknown fields on read-modify-write.** An older service in the pipeline silently erases data newer services added. Fix: preserve and re-emit unknown fields.
+- **Treating a type widening as free.** `int32→string` or `string→enum` is a break even with the same name; not all proto widenings are wire-safe. Fix: verify the exact pair or run expand→contract.
+- **No registry / CI gate.** Relying on review to catch breaks. Fix: `buf breaking` / Confluent compat check that **fails the build**.
+- **Checking only against the latest version, not all.** A change compatible with v3 but not v1 breaks replay. Fix: `*_TRANSITIVE` mode for replayable logs.
+- **Contracting before the replay/retention window passes.** Dropping the old field while replayable records still reference it. Fix: grace window > longest consumer lag + topic retention.
+
+## Verify
+
+1. **Mechanical compat check passes in CI:** `buf breaking` / Confluent `is_compatible:true` / Avro checker runs on the PR diff and **fails the build** on an incompatible change — proven by intentionally introducing a remove/rename and watching CI go red.
+2. **Old-schema read of new data, and vice versa:** serialize a record with the new schema, deserialize with the old (forward); serialize with old, read with new (backward) — both succeed, defaults fill absent fields. This is the literal compatibility definition; test it, don't assume it.
+3. **No required field added, every new field has a default:** grep the diff — new fields are optional and defaulted (`"default"` in Avro, not in JSON `required`, appended proto numbers).
+4. **Removed fields are reserved:** any dropped proto field has its number AND name in `reserved`; any renamed Avro field has `aliases`; no identifier is reused.
+5. **Tolerant reader confirmed:** feed a consumer a payload with an extra unknown field → it parses and ignores it (no exception); on read-modify-write, the unknown field survives the round-trip.
+6. **Deploy order documented and rehearsed:** the rollout plan states consumers-first (backward) or producers-first (forward), and a mixed-version canary shows zero parse errors / dead-letters during the window.
+7. **Rename via expand→contract, not in place:** the migration is staged (dual-write, switch reads, then drop + reserve) and each phase is independently rollback-safe; the old field is dropped only after the replay window.
+8. **Transitive check for replayable logs:** for an event log replayed from offset 0, compat mode is `*_TRANSITIVE` and a candidate is checked against all prior versions, not just latest.
+
+Done = the change is additive (optional + defaulted) or staged through expand→migrate→contract, no field/tag/position is ever removed-without-reserving or repurposed, the compatibility mode matches the deploy order, consumers are tolerant readers that preserve unknowns, and a schema-registry compat check fails CI on any incompatible diff — all proven by the old↔new round-trip and the red-CI test in checks 1–2.