**Tags:** convex, deployment, validation, infra, footgun **Confidence:** 9.8 · **Last Used:** 2026-04-27 · **Source:** jarvis + rajdeep (merged CONVEX-DEPLOY-PARTIAL + CONVEX-VALIDATE + VERIFY-ZERO-EMITS 2026-05-09) **Rule:** Three Convex deploy verification rules consolidated: 1. **`npx convex deploy` can report ✔ Deployed while function bundle silently failed.** Schema portion goes through; functions stay pinned at last fully-successful deploy. Common cause: a later PR added an npm dep without `yarn install` happening on the deploy machine; esbuild bundle step fails silently. After ANY Convex deploy that changes function code or validators, verify by exercising the new path — call the new mutation/query via `npx convex run --prod` with a representative payload, OR check `npx convex function-spec --prod` reflects the new validator. Don't trust the green checkmark alone. If you pulled main and `convex/` touches new top-level deps, run `yarn install` BEFORE deploying. 2. **Validation changes must trace full write path.** When changing validation at ANY layer: trace form schema → submit handler → mutation args → mutation handler → db insert. Check EVERY mutation accepting the changed field. After deploy, fire a real event of the new shape and verify it lands. 3. **Zero emits for new event types in same window where related events fire = validator drift.** When a NEW event type shows 0 emits in the same window where RELATED existing events fire fine, hypothesis ranking: (1) server validator pinned at old version (high prior), (2) client `.catch` swallowing rejection silently, (3) hook subscription bug (lower prior — usually breaks ALL events on path). The asymmetry IS the signature: a true client-side bug kills BOTH old + new. Before reading hook code, check (a) the type literal is in the deployed validator (`npx convex run` with the new type → `ArgumentValidationError` = found), (b) related events on the same component path are landing in the same window. Same root-cause class as `feedback_vercel_convex_deploy_not_wired`.

**Tags:** convex, env-vars, dev-only-gates **Confidence:** 9.2 · **Last Used:** 2026-04-19 · **Source:** jarvis **Rule:** Dev-only Convex mutation gates must use a SINGLE explicit env-var opt-in like `DEV_SEED_ENABLED=1`. Trust boundary is `convex env set` access (same model as `ADMIN_SEED_SECRET`). Don't rely on `NODE_ENV`, `CONVEX_DEPLOYMENT`, or any value Convex controls.

**Tags:** convex, schema, deploy, migration, tenant-scope **Confidence:** 9.5 · **Last Used:** 2026-05-04 · **Source:** rajdeep + jarvis (merged BROS-P0 schema audit + CONVEX-TENANT-BACKFILL 2026-05-09) **Rule:** Two schema migration safety rules consolidated: 1. **Audit prod data against schema BEFORE schema-changing deploys.** Run `npx convex run --env-file .env.production.local <listAll>` and grep the result against the new validator union. If ANY existing row would fail schema validation, the PR is INCOMPLETE — it MUST include (a) a backfill mutation (idempotent, runnable post-deploy) AND (b) a "widened-during-migration" schema that accepts both old and new values during the transition. Tighten in a follow-up after backfill audit confirms zero stale rows. Schema-rename PRs that don't backfill are time bombs — green in CI but blow up the next deploy. Reviewer agent should flag any PR that changes a `v.union` of literals as INCOMPLETE if there's no companion backfill mutation. Reference: `convex/plugins.ts:backfillLegacyRequiredPlans` (BROS-P0 incident, 2026-05-04). 2. **Tenant-scope assignments need downstream backfill.** When assigning an existing broker to a new org, backfill `organizationId` on ALL downstream resources in the same transaction (cards, properties, leads, etc.) OR run a one-shot repair mutation per onboarding. `enforceTenantScope` rejects resources with `organizationId === undefined`. Reference: `convex/admin/repair.ts:backfillCardOrganizationIdForOrg`.

**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:** dependencies, npm, engineering-agent **Confidence:** 9.0 · **Last Used:** 2026-04-19 · **Source:** jarvis **Rule:** Every dep-touching dispatch prompt must include: *"Only install packages explicitly named in this ticket, with exact or caret version (`npm install <name>@<ver> --save`). Never run `npm install` bare. Never add unlisted packages — flag instead."* Before filing dep-upgrade tickets: `npm view <pkg> versions --json | tail -20` and pin a version that actually exists.

**Tags:** next-app-router, providers, auth-scoped-routes **Confidence:** 9.0 · **Last Used:** 2026-04-19 · **Source:** rajdeep + jarvis **Rule:** Broker OS uses a path-conditional ConvexProvider mount. ANY new route tree calling Convex hooks MUST be added to BOTH the `ConvexGate` allowlist AND the middleware auth matcher. Verify with a manual route hit before claiming the PR is done.

**Tags:** vercel, infra, multi-project, debugging **Confidence:** 9.5 · **Last Used:** 2026-04-22 · **Source:** jarvis (BROS-278) **Rule:** When a Next→Astro (or any cross-project) proxy returns 500 with EMPTY body and NO `x-matched-path` / NO `content-type`, the failure is at Vercel edge, not the application. Check upstream project's `ssoProtection`/`passwordProtection` BEFORE debugging app code: `curl https://api.vercel.com/v9/projects/<id>?teamId=<team> | jq '{ssoProtection, passwordProtection}'`. For public storefront projects fronted by a separate Next.js app, set `ssoProtection: null` — the custom-domain bypass doesn't help when proxy hops via a .vercel.app alias.

**Tags:** ui, fixtures, placeholder-leak **Confidence:** 9.0 · **Last Used:** 2026-04-19 · **Source:** rajdeep + jarvis **Rule:** When copying structure from `__fixtures__/`, `__mocks__/`, `seed/`, or `examples/`, audit every user-facing string for placeholder leaks ("Lorem ipsum", "Test Broker", "user-1234", fake phone numbers). Seed data routinely leaks to prod when copied.

**Tags:** planning, dispatch, process **Confidence:** 9.0 · **Last Used:** 2026-04-13 · **Source:** jarvis (KAPT-49 / KAPT-54) **Rule:** Before wiring any UI page to backend selectors OR writing any multi-step plan: READ `page.tsx` (or target file) and reconcile every section against the plan. The plan is hypothesis; the file is ground truth. Plans estimating >4h must include verified file enumeration via Glob, not assumption. If ANY section requires new schema that doesn't exist, STOP and escalate.

**Tags:** orchestration, judgment **Confidence:** 9.0 · **Last Used:** 2026-04-13 · **Source:** rajdeep **Rule:** When an agent overrides an explicit user decision with a stated reason (schema gap, missing dep, etc.), Jarvis MUST inspect the agent's evidence before pushing back. Default framing: "(c) inspect first, then your call (a/b)." Inspection cost is small; reversal-without-inspection cost is high.

**Tags:** agents, audit, verification **Confidence:** 9.2 · **Last Used:** 2026-04-26 · **Source:** jarvis (Bhoomi planning + STALE-FRONTMATTER 2026-04-27 merge) **Rule:** Two related verification rules: 1. **Audit dispatch prompts must demand live reads.** When dispatching an audit agent that requires deep file reads, the prompt MUST say verbatim: *"Read the file end-to-end via the Read tool. Do not summarize from any prior index. Quote exact strings and exact file:line references — if you cannot quote it from the live file, say DOES NOT EXIST. No hedged language."* Without this, agents fall back on indexed snippets and confabulate line numbers. 2. **Don't infer plan-doc status from frontmatter alone.** Before declaring a plan stale or abandoned: read its Implementation Checkpoint / Progress Tracker sections, `git log --since="<created>" --oneline` for related ticket IDs, check the actual code surfaces. Frontmatter `status: stale` is an expiry signal for review, not a delivery signal.

**Confidence:** 9.0 · **Source:** jarvis · Before pushing any commit touching `convex/`, check that Vercel's convex deploy hook is actually wired.

**Confidence:** 8.5 · **Source:** jarvis