**Tags:** convex, concurrency, schema, race-conditions **Confidence:** 9.0 · **Last Used:** 2026-04-27 · **Source:** reviewer (Opus, KAPT-92 PR #20 round-2) **Rule:** Convex per-document OCC serializes UPDATEs (read+patch on the same `_id`), but cannot detect two concurrent handlers both INSERTING different documents for the same logical key (e.g. same `senderKey`). Two flows racing first-time creation produce two rows; subsequent `.first()` lookups return non-deterministic results and split telemetry. Mitigations in order of strength: 1. **Lock-doc pattern with predictable `_id`** — full immunity. Insert a sentinel doc keyed on the logical id; the second handler's insert fails on `_id` collision. 2. **Defensive recheck inside the insert branch** — query by logical key right before insert, early-return on conflict. Reduces (does not eliminate) the race window. 3. **Deduplication cron** — accept the race, recover via a periodic dedup job. Pragmatic when concurrent creates are rare. The CAS-on-update guard is necessary but NOT sufficient — it only protects flows where a row already exists.

**Tags:** engineering-agent, worktree, sandbox, env-files **Confidence:** 9.5 · **Last Used:** 2026-04-26 · **Source:** jarvis (merged ENG-WORKTREE + ENG-FRESH-BUILD + ENG-PARALLEL-CHECKOUT 2026-04-27) **Rule:** Three worktree rules consolidated: 1. **Path inside main repo.** Force the worktree path INSIDE the main repo (`<repo>/.worktrees/<branch>/`). Pass it explicitly in dispatch prompts — Claude Code's sandbox blocks sibling directories. 2. **Fresh install + env files first.** `git worktree add` doesn't carry gitignored files. Before dispatching: `cp .env.local .env.production.local .vercel/project.json .mcp.json` from main clone, then `yarn install`. Convex `deploy` needs both `.env.local` and `.env.production.local` (the latter holds CONVEX_DEPLOY_KEY for prod). Dispatch prompt must require: "ONLY declare 'pre-existing fail' after a clean install fails to fix the build" — pre-existing fails without an install pass are agent laziness. 3. **No foreign checkout on a dirty tree.** If you're editing in `~/my_work/<repo>` and another agent / cmux tab runs `git checkout <other-branch>` mid-edit, your unstaged edits get carried OUT of your branch. They reappear "reverted" on the next checkout. For ANY non-trivial multi-file edit, work in an isolated worktree and commit early — the moment a logical chunk passes typecheck. Don't let edits live in the working tree across an audit/build/run cycle.

**Tags:** workflow, git, stacked-prs, parallel-dispatch **Confidence:** 9.5 · **Last Used:** 2026-04-28 · **Source:** rajdeep correction (merged BROS-405/406 + V12 2026-05-09) **Rule:** Two stacked-PR rules consolidated: 1. **Stack on previous PR's tip, not stale main.** When dispatching parallel work as part of a multi-PR phase (Phase B, etc.), every parallel branch stacks on the previous PR's branch tip — NEVER orphan off stale main. Until the underlying PR merges, the canonical "tip" for downstream work is its branch head, not main. Before `git worktree add`, check git log on the latest stack tip and use IT as the base. If main has advanced meanwhile, merge main into the stack tip first, THEN stack downstream off the merged result. Bonus: collapse 2+ tightly coupled stacked PRs into one squashed merge — saves merge ceremony when the dependency is real. 2. **Squash-merge with `git rebase --onto`.** When the underlying PR squash-merges, downstream branches need rebasing: `git rebase --onto origin/main HEAD~N` where N = commits unique to the downstream branch. Otherwise the squashed tip shows as duplicate work.

**Tags:** pipeline, broker-os **Confidence:** 9.0 · **Last Used:** 2026-05-05 · **Source:** rajdeep **What went wrong:** Codex kept waiting on GitHub/Vercel CI contexts even though the failing contexts were caused by external payment/build-rate-limit state, not branch correctness, and Rajdeep had asked to finish the merge. **Rule:** Separate code-signal checks from external-account checks. If local verification passed, relevant GitHub code checks are green or owner-waived, and remaining contexts are clearly billing/rate-limit/payment infrastructure failures, do not keep polling. State the external failure, merge with the appropriate explicit waiver/admin path when Rajdeep asks, then update Plane and handoff with the reason.

**Tags:** git, session **Confidence:** 9.5 · **Last Used:** 2026-04-01 · **Source:** rajdeep **What went wrong:** Session 1 CRM fixes lost when Session 2 switched branches over uncommitted work. **Rule:** Every session ends with clean `git status` across all repos touched. Run `git status --short` before writing the handoff. Commit or stash remaining work. "NOT committed yet" in a handoff is a bug, not a note.

**Tags:** git, vercel, monorepo, deployment **Confidence:** 9.0 · **Last Used:** 2026-04-23 · **Source:** rajdeep + live prod (merged GIT-REBASE + PROC-MONOREPO-DEPLOY 2026-04-27) **Rule:** Two related deploy rules: 1. **Always rebase before push.** `git pull --rebase origin main && git push`. Prevents diverged-branch conflicts from VPS auto-commits. Group fixes into fewer pushes — each push = a Vercel build. 2. **Monorepo deploys via git push, not `vercel --prod`.** For monorepos with separate Vercel projects per workspace (e.g., Next.js root + Astro `apps/public`), prefer `git push` + Git Integration auto-deploy. `vercel --prod` only deploys the root project; git push fires a deploy for EVERY linked project whose root directory has changes. Wait ~90-120s and verify both preview URLs.

**Tags:** diagnosis, debugging-discipline, root-cause, dns **Confidence:** 9.2 · **Last Used:** 2026-04-22 · **Source:** rajdeep + BROS-278 (merged VERIFY-DIAG-LIVE + VERIFY-INTERMITTENT + VERIFY-DNS-CACHE 2026-04-27) **Rule:** Three diagnosis rules consolidated: 1. **Run inspection commands immediately.** For deploy/env/infra failures, run the inspection command IMMEDIATELY (`vercel env ls`, `convex env list`, `npm ls <pkg>`) — not "here's a command for you to run." Compare against a working reference (another PR, main branch). Theory is hypothesis; a command is evidence. 2. **"Intermittent / cold start / flaky" are hypotheses, not diagnoses.** When prod returns 5xx even ONCE on a customer-facing path, dig until you have either (a) deterministic reproduction with root cause, OR (b) proof of stochasticity (timing data, retry stats, infra signals). Cache-bust query strings (`?_=$(date +%s%N)`) are essential — bare requests serve cached responses and hide upstream failures. Empty response body + missing content-type → failure at platform edge, not app: check upstream protection settings BEFORE reading code. 3. **Mind external cache lag.** When a customer removes DNS records, plan for up to 30 min Vercel verification lag independent of customer-side propagation. Vercel's `/v6/domains/.../config` caches via Google DoH up to TTL. Check `curl 'https://dns.google/resolve?name=<domain>&type=AAAA' | jq`. Don't spam `/verify`; let TTL drain. Communicate ETA to customer based on TTL, not `dig`-against-public-resolvers.

**Tags:** branding, canonical-sources **Confidence:** 9.0 · **Last Used:** 2026-04-19 · **Source:** rajdeep **Rule:** When wiring contact info, support URLs, social handles, brand colors, or ANY "canonical fact": grep for the canonical source file FIRST (`src/lib/brand.ts`, `src/config/contact.ts`). User-provided values are inputs to verify against the canon, not authority to override it. Also: grep for builder DEFINITIONS not just call sites when migrating URL shapes.