sanook-cli 0.4.0 → 0.5.0

package/skills/recover-git-state/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: recover-git-state
+description: Recovers lost or broken git state — restores dropped commits/branches/stashes via reflog and fsck, pins a regression with git bisect, and safely undoes a bad reset/rebase/merge with revert or reset --soft/--mixed/--hard — without destroying still-recoverable objects.
+when_to_use: Work appears gone after a reset --hard, bad rebase, deleted branch, dropped stash, or detached HEAD, or you need to pin which commit introduced a bug. NOT intentional history editing (rewrite-git-history), conflict-marker resolution (resolve-merge-rebase-conflict), or diagnosing a non-git code failure (debug-root-cause).
+---
+
+## When to Use
+
+Reach for this when work *appears* gone or HEAD landed somewhere wrong — the commits almost always still exist as unreachable objects:
+
+- "I lost my commits" / "my branch is empty" after a `reset --hard`, bad `rebase`, or force-fetch
+- "I deleted the wrong branch" (`git branch -D feature`)
+- "I'm in detached HEAD and made commits — did I lose them?"
+- "I `git stash drop`'d / `stash pop`'d into a conflict and lost a stash"
+- "Which commit broke this?" — a regression to pin across a known-good..bad range
+- A merge/rebase/`reset` made things worse and you want it back exactly as it was
+
+NOT this skill:
+- *Intentionally* rewriting history (squash, reword, rebase to clean up, strip a secret) → rewrite-git-history
+- Resolving the conflict markers from an in-progress merge/rebase/cherry-pick → resolve-merge-rebase-conflict
+- The code itself is failing (test/crash/wrong output) and git history is fine → debug-root-cause
+- The file was never committed and isn't in any stash → git can't recover it; check editor local history / backups
+
+## Steps
+
+1. **STOP and snapshot before touching anything.** Recovery commands can themselves overwrite refs. Freeze current state so you can't make it worse:
+   ```bash
+   git stash list; git status; git log --oneline -5   # what do we actually have?
+   git branch _backup_$(date +%s)                       # pin current HEAD as a named ref
+   ```
+   Never run `reset --hard`, `checkout`, `rebase`, or `gc` until you've located the SHA you want back.
+
+2. **Find the lost SHA — reflog is the safety net.** Every move of HEAD (and of each branch) is logged for ~90 days, even after `reset --hard` or branch deletion:
+   ```bash
+   git reflog                       # every HEAD move: HEAD@{0}, HEAD@{1}, ...
+   git reflog show feature          # moves of one branch ref specifically
+   git reflog --date=relative | grep -iE 'commit|reset|rebase|checkout'
+   ```
+   The entry *just before* the bad operation is your target (e.g. `HEAD@{2}` = "before the reset"). Copy its SHA.
+
+3. **Recover by creating a ref — never `checkout` a loose SHA bare.** Pick the action by what you lost:
+
+   | Lost | Command | Note |
+   |---|---|---|
+   | A deleted branch | `git branch feature <sha>` | `<sha>` from `git reflog show feature` or `fsck` |
+   | Commits after a `reset --hard` | `git reset --hard HEAD@{1}` | moves current branch back; **discards** anything since |
+   | Commits, but keep current work | `git branch rescue <sha>` | safe — inspect/`cherry-pick` from `rescue`, then delete it |
+   | Detached-HEAD commits | `git branch keep <sha>` *before* you `checkout` away | bare checkout-away orphans them |
+
+   Default to `git branch rescue <sha>` — it's non-destructive. Use `reset --hard HEAD@{n}` only when you're sure everything after it is garbage.
+
+4. **Recover a dropped/popped stash via fsck.** A dropped stash isn't in `reflog` but lives as an unreachable commit:
+   ```bash
+   git fsck --no-reflog --unreachable | grep commit | awk '{print $3}' \
+     | xargs -I{} git log -1 --format='%H %ci %s' {} | grep -i 'WIP on'
+   git stash apply <sha>            # or: git branch stash_recovered <sha>
+   ```
+   A stash commit's subject starts with `WIP on <branch>:`. `git fsck --lost-found` also drops them under `.git/lost-found/`.
+
+5. **Undo by audience: published → `revert`, local → `reset`.** This is the one rule that prevents a second disaster:
+
+   | Situation | Use | Why |
+   |---|---|---|
+   | Bad commit already pushed / shared | `git revert <sha>` | adds an inverse commit — no history rewrite, safe for collaborators |
+   | Local mistake, want it gone | `git reset` (see below) | rewrites your local branch; never on shared history |
+
+   `reset` mode, decided by where you want the changes to land:
+   - `--soft HEAD~1` → undo the commit, keep changes **staged** (re-commit cleanly)
+   - `--mixed HEAD~1` (default) → undo commit, keep changes in **working tree**, unstaged
+   - `--hard HEAD~1` → undo commit **and discard** the changes — destructive; only after step 1's backup
+
+6. **Restore working-tree files (not commits) with `git restore`.** Discarded edits or a wrong file version:
+   ```bash
+   git restore path/to/file              # revert working-tree file to HEAD (uncommitted edits gone)
+   git restore --source=<sha> file       # pull one file's content from a specific commit
+   git restore --staged path             # unstage only (keep working-tree edits)
+   ```
+   `git checkout -- file` is the old spelling; prefer `restore`.
+
+7. **Pin a regression with `git bisect`.** Binary-search the first bad commit across a known-good..bad range:
+   ```bash
+   git bisect start
+   git bisect bad                 # current HEAD is broken
+   git bisect good v1.4.0         # last known-good tag/sha
+   # git checks out the midpoint; test it, then mark good/bad and repeat
+   git bisect good   # or: git bisect bad
+   ```
+   Automate it — let git drive every step with an exit-coded script:
+   ```bash
+   git bisect run ./test.sh       # script: exit 0 = good, 1..124 = bad, 125 = skip (untestable)
+   ```
+   When done it prints `<sha> is the first bad commit`. **Always** `git bisect reset` to return to your original HEAD.
+
+8. **Run `git gc` only after you've recovered and verified.** Unreachable objects survive until garbage collection. Don't run `git gc --prune=now` or `git reflog expire` while a recovery is pending — that's what permanently deletes the SHAs you're hunting.
+
+## Common Errors
+
+- **`checkout`ing a loose SHA, making commits, then leaving — they're orphaned again.** Always `git branch <name> <sha>` *first*; commit onto a real ref.
+- **`reset --hard HEAD@{1}` to "go back," wiping current uncommitted work.** `--hard` discards the working tree. Stash or `git branch _backup` first (step 1); use `git branch rescue` instead when unsure.
+- **`reflog` is empty / "ambiguous argument".** You're in a fresh clone or a different repo — reflog is per-local-clone and not pushed. Use `git fsck --lost-found` to find unreachable commits by content instead.
+- **`revert`ing a merge commit fails or reverts the wrong side.** Pass the parent: `git revert -m 1 <merge-sha>` (mainline = parent 1). Reverting a merge has its own re-merge gotcha; for shared history that's still safer than rewriting.
+- **`stash pop` hit a conflict and you assumed the stash was lost.** A *conflicted* `pop` does **not** drop the stash — it's still in `git stash list`. Resolve, then `git stash drop`.
+- **Ran `git gc` / `git reflog expire --expire=now --all` and now the SHA is gone.** Pruning deleted the unreachable objects. Recover the ref *before* any gc; check `.git/lost-found/` and cloned mirrors.
+- **`bisect` mislabels because the build is broken at some midpoints.** Have the script `exit 125` (skip) for uncompilable commits so bisect routes around them instead of falsely marking bad.
+- **Forgot `git bisect reset`.** You're left in detached HEAD on a midpoint commit, confusing later work. Reset returns you to the pre-bisect branch.
+- **Using `reset` to undo *pushed* commits, then force-pushing.** Rewrites shared history and breaks teammates. On published commits use `git revert`; rewriting is rewrite-git-history's job, not a recovery.
+
+## Verify
+
+Recovery is complete and correct when:
+
+1. **The recovered ref points at the right tree.** `git diff <known-good-sha> <recovered-ref>` is empty (or shows exactly the intended delta) — confirms you grabbed the right SHA, not a neighbor.
+2. **The expected commits are reachable.** `git log --oneline <recovered-ref>` shows the commits that were "lost," and `git status` is clean (no surprise staged/modified files).
+3. **A recovered stash applied cleanly.** `git stash show -p <sha>` matches the work you expected; after `apply` the files contain the WIP changes.
+4. **An `undo` did what its audience requires.** After `revert`: a new inverse commit exists and `git log` history is intact (nothing rewritten). After `reset`: `git status` shows the changes in the intended state (staged for `--soft`, unstaged for `--mixed`, gone for `--hard`).
+5. **Bisect named one culprit and cleaned up.** Output ended with `<sha> is the first bad commit`, `git show <sha>` plausibly explains the regression, and `git bisect reset` returned HEAD to the starting branch (`git status` confirms the original branch, not detached).
+6. **Nothing was pruned mid-recovery.** No `git gc`/`reflog expire` ran before the ref was secured; the `_backup` branch from step 1 still exists as a fallback.
+
+Done = the recovered commits/branch/stash are on a named ref whose tree matches the known-good SHA (`git diff` empty), any undo matched its published-vs-local audience (revert vs reset mode), and bisect (if used) named the first bad commit with `git bisect reset` leaving HEAD on the original branch.

package/skills/remediate-web-vulnerabilities/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: remediate-web-vulnerabilities
+description: Fixes specific web vulnerability classes — SQL/command injection, XSS, CSRF, SSRF, IDOR/broken access, insecure deserialization — by applying the canonical hardening (parameterized queries, args-array exec, context-aware output encoding + CSP, SameSite + synchronizer tokens, egress allowlists, per-owner authorization, safe deserialization) and proving each fix with a regression test that replays the exploit.
+when_to_use: A specific vuln was found (review, scan, pentest) or an input/output path needs proactive hardening. Distinct from security-review (finds and reports vulns, does not fix), design-authorization-model (authZ architecture, not a single IDOR patch), and defend-llm-prompt-injection (LLM/prompt-specific, not classic web).
+---
+
+## When to Use
+
+- "We got a finding for SQL injection / XSS / SSRF — fix it"
+- "A pentest flagged IDOR on `GET /orders/:id` — anyone can read any order"
+- "Sanitize this user input before it hits the shell / the DB / the page"
+- "Harden this URL-fetch endpoint so it can't hit our metadata service"
+- "Stop us deserializing untrusted JSON/pickle/YAML into objects"
+- Proactively hardening a newly added input or output path before ship
+
+NOT this skill:
+- *Finding* and reporting vulns in a diff (no specific one yet) → security-review
+- Designing the overall authZ model (roles, policies, tenancy) instead of patching one missing ownership check → design-authorization-model
+- Prompt injection / tool-abuse / jailbreaks against an LLM → defend-llm-prompt-injection
+- Stress-finding *new* input bugs by mutation/fuzzing → fuzz-dynamic-security-test
+- Moving plaintext secrets out of code/IaC and rotating them → secrets-management
+- WAF rules / managed rulesets at the edge as a *compensating* control → setup-cdn-edge-waf (a WAF is defense-in-depth, never the fix)
+
+Fix the **class, not the instance**: when you find one concatenated query, grep the codebase and fix every sibling. A WAF rule or input blocklist is a band-aid — remove the unsafe construct.
+
+## Steps
+
+1. **Identify the class, then apply its canonical fix.** Do not invent ad-hoc escaping — each class has one correct construct:
+
+   | Class | Root cause | Canonical fix (do this) | Never (the band-aid) |
+   |---|---|---|---|
+   | **SQLi** | String-built query | Parameterized query / bound params; ORM with bindings | Escaping quotes, blocklisting `'`/`;`/`--` |
+   | **Command injection** | Shell-interpreted string | No shell: exec with **args array**; allowlist binaries/flags | `escapeshellarg`-then-concat into `sh -c` |
+   | **XSS** | Untrusted data in HTML | Framework auto-escaping + **context-aware** encoding + CSP; sanitize HTML with DOMPurify | Regex strip of `<script>`, `innerHTML` of user data |
+   | **CSRF** | Ambient cookie auth | `SameSite=Lax/Strict` + **synchronizer token** on state-changers | Checking `Referer` only |
+   | **SSRF** | User-controlled fetch URL | **Allowlist** dest hosts; block link-local/metadata/private ranges; pin resolved IP | Blocklisting `localhost`/`127.0.0.1` strings |
+   | **IDOR / broken access** | authN ≠ authZ | Authorize **every object by owner/tenant**, server-side, on the resolved row | Hiding the ID in the UI; UUIDs as "security" |
+   | **Insecure deserialization** | Untrusted bytes → objects | Don't deserialize untrusted data; use data-only formats (JSON) + schema validate | `pickle.loads`, `yaml.load`, Java native, `unserialize()` on input |
+
+2. **SQLi — parameterize, never concatenate.** Pass user data as bound parameters so it is never parsed as SQL. Identifiers (table/column names) can't be parameters — allowlist them against a fixed set.
+
+   ```python
+   # BAD: db.execute(f"SELECT * FROM users WHERE email = '{email}'")
+   db.execute("SELECT * FROM users WHERE email = %s", (email,))           # psycopg
+   # ORM: User.query.filter_by(email=email)   # SQLAlchemy binds automatically
+   # Dynamic column: pick from an allowlist, don't interpolate the raw value
+   ALLOWED = {"name", "created_at"}
+   if sort not in ALLOWED: raise ValueError("bad sort column")            # reject, don't interpolate
+   ```
+
+3. **Command injection — drop the shell, pass an args array.** The shell is the vuln; `shell=True` / `sh -c` / `os.system` interpret metacharacters. Pass argv as a list so the OS execs the binary directly with no parsing.
+
+   ```python
+   # BAD: subprocess.run(f"convert {path} out.png", shell=True)
+   subprocess.run(["convert", path, "out.png"], shell=False, check=True)   # path is one argv element, never re-parsed
+   ```
+   If a value must be a flag, allowlist it (`if mode not in {"fast","hq"}: reject`). Never build a flag string from user input.
+
+4. **XSS — encode for the output context, add CSP, sanitize HTML only with a vetted lib.** Escaping for HTML body ≠ for an attribute ≠ for JS ≠ for a URL. Let the template engine auto-escape (Jinja `autoescape`, React `{}` text nodes) and don't defeat it (`| safe`, `dangerouslySetInnerHTML`, `v-html`, `innerHTML`). If you must render user HTML, run it through **DOMPurify** first:
+
+   ```js
+   el.textContent = userInput;                       // default: text, auto-safe
+   el.innerHTML = DOMPurify.sanitize(userHtml);      // ONLY when HTML is required
+   // Never build href/src from raw input — reject non-http(s) schemes (blocks javascript:)
+   ```
+   Add a strict CSP as defense-in-depth: `Content-Security-Policy: default-src 'self'; object-src 'none'; base-uri 'none'` — no `unsafe-inline`/`unsafe-eval`. CSP is a second wall, not the fix.
+
+5. **CSRF — `SameSite` cookies + synchronizer token.** Set session cookies `SameSite=Lax` (or `Strict`), `Secure`, `HttpOnly`. For every state-changing request (`POST/PUT/PATCH/DELETE`), require a per-session CSRF token (double-submit cookie or server-stored), compared with a constant-time check. Pure token-auth APIs (`Authorization: Bearer`, no cookies) are not CSRF-prone — don't bolt tokens onto those.
+
+6. **SSRF — allowlist egress, block internal ranges, fetch the pinned IP.** If the destination is user-controlled, default-deny:
+   - Allowlist the exact hostnames/domains you intend to reach; reject everything else.
+   - Resolve the host, then **reject** `127.0.0.0/8`, `::1`, `10/8`, `172.16/12`, `192.168/16`, `169.254.0.0/16` (link-local → cloud metadata `169.254.169.254`), `fc00::/7`, and `0.0.0.0`.
+   - Resolve once, validate that IP, and connect to **that IP** (pass it explicitly / pin it) to kill DNS-rebinding TOCTOU.
+   - Disable redirects, or re-validate the target on each hop. Never follow a redirect to an unvalidated host.
+
+7. **IDOR / broken access — authorize every object by owner, server-side.** Authentication tells you *who*; you still must check *they own this row*. Scope the query or assert ownership on the resolved object — never trust an ID from the request as proof of access.
+
+   ```python
+   # BAD: order = Order.get(request.params["id"])   # any id -> anyone's order
+   order = Order.get(id=request.params["id"], owner_id=current_user.id)    # scope to caller
+   if order is None: raise NotFound()   # 404, not 403 — don't confirm the row exists
+   ```
+   This is the single-instance patch. If you're (re)designing roles/policies/multi-tenancy, that's design-authorization-model.
+
+8. **Insecure deserialization — never deserialize untrusted bytes.** Object-deserializers (`pickle`, `yaml.load`, Java `ObjectInputStream`, PHP `unserialize`, .NET `BinaryFormatter`) can execute code or instantiate arbitrary types. Accept only data formats and validate against a schema:
+
+   ```python
+   # BAD: obj = pickle.loads(body)   /   data = yaml.load(body)
+   data = json.loads(body)              # data only, no code execution
+   yaml.safe_load(body)                 # if YAML is required
+   Payload.model_validate(data)         # pydantic: enforce shape/types
+   ```
+   If signed objects are unavoidable, verify an HMAC over the bytes *before* deserializing.
+
+9. **Sweep the class and write the regression test.** Grep for every sibling of the fixed pattern (`grep -rn "shell=True"`, `f"SELECT`, `innerHTML =`, `pickle.loads`, `yaml.load(`, `dangerouslySetInnerHTML`). Then write a test that sends the **actual exploit payload** and asserts it no longer triggers (Verify).
+
+## Common Errors
+
+- **Escaping/blocklisting instead of parameterizing.** Quote-escaping and `'`/`;` blocklists are bypassable (unicode, comments, encoding). Use bound parameters — fix the construct.
+- **`shell=True` "but I escaped it".** `escapeshellarg`-then-concat still goes through the shell and gets bypassed. Pass an argv array with `shell=False`; no shell, no metacharacters.
+- **Sanitizing on input, rendering elsewhere.** Input sanitization can't know the output context. Encode at the point of output (HTML vs attr vs JS vs URL); store data raw.
+- **Trusting a custom XSS regex.** Hand-rolled HTML filters miss `onerror=`, `javascript:`, SVG, mutation XSS. Use DOMPurify; never `innerHTML` raw input.
+- **CSP with `unsafe-inline`/`unsafe-eval`.** Negates the protection against injected `<script>`. Use nonces/hashes; if you can't, you haven't fixed the XSS — CSP was only the backstop.
+- **SSRF fix that blocks strings, not IPs.** Blocking `"localhost"` misses `0`, `0x7f.1`, `[::1]`, decimal IPs, and DNS-rebinding. Resolve and check the **IP** against CIDR ranges, then connect to that resolved IP.
+- **Following redirects after SSRF validation.** Validated host 302-redirects to `169.254.169.254`. Disable redirects or re-validate every hop.
+- **IDOR "fixed" by switching to UUIDs / hiding the ID.** Obscurity isn't authorization. The fix is the server-side owner/tenant check on the resolved object.
+- **Adding authN where authZ is missing.** Logged-in ≠ authorized for *this* object. Scope the lookup to the caller.
+- **`yaml.load` left as the "safe" one.** Plain `yaml.load` constructs arbitrary objects. Use `yaml.safe_load`. Likewise `pickle`/`BinaryFormatter`/`unserialize` on input are never safe — switch to JSON + schema.
+- **Fixing the reported instance, leaving the class.** The scanner found one; the same pattern lives in ten other files. Grep and fix all, or it regresses next sprint.
+- **Calling a WAF rule the fix.** A blocked payload at the edge while the unsafe code remains is unfixed — the next encoding gets through. WAF is defense-in-depth (setup-cdn-edge-waf), not remediation.
+
+## Verify
+
+A fix is proven only when an automated test reproduces the original exploit and asserts it's now inert:
+
+1. **SQLi:** Send `' OR '1'='1` / `'; DROP TABLE--` as the input → response is a normal empty/auth-fail result, no extra rows, no error leaking SQL; query log shows it ran as a bound parameter.
+2. **Command injection:** Send `; id`, `$(id)`, `` `id` ``, `| cat /etc/passwd` as the value → no extra process runs, no command output in the response; a sentinel file the payload tries to create does not exist.
+3. **XSS:** Submit `<img src=x onerror=alert(1)>` and `javascript:alert(1)` → response renders them as **escaped text** (`<img...`), not live markup; assert the raw `<script>`/`onerror` byte sequence is absent from the HTML. Confirm the `Content-Security-Policy` header is present and free of `unsafe-inline`.
+4. **CSRF:** Replay a state-changing `POST` with a valid session cookie but **no/forged** CSRF token → rejected (`403`); the same request with a valid token → succeeds.
+5. **SSRF:** Request each blocked target — `http://169.254.169.254/`, `http://127.0.0.1`, `http://[::1]`, a decimal-IP form, and a host that 30x-redirects to `169.254.169.254` → all rejected before any socket to an internal range opens; only an explicitly allowlisted host returns `200`. Assert the connection to the internal range was never opened.
+6. **IDOR:** As user A, request user B's object ID → `404` (not the row, not a `403` that confirms existence); as the owner → `200`. Run it for every object-scoped route you touched.
+7. **Deserialization:** Feed a malicious pickle/`!!python/object` YAML/gadget payload → rejected at schema validation, no object instantiated, no code executed (sentinel side-effect absent).
+8. **Class sweep:** The grep for the unsafe construct returns zero remaining hits in app code (excluding the test fixtures that hold the payloads).
+
+Done = the exploit-replay test for the fixed class **failed before** the change and **passes after**, the canonical construct (not a blocklist/WAF rule) is in place, the class-wide grep is clean, and no Critical regression remains.

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.