# Agent instructions — overdeck

audience: AI coding agents (codex included — this file is your entry point). Claude Code auto-loads it via the repo-root `CLAUDE.md` symlink; edit THIS file, never the symlink.

Working under `modules/harness/**` → also read `modules/harness/CLAUDE.md` (factory layout, config, permissions, tracing, tests).

## Factory reliability — MANDATORY

ANY change to factory phase, retry, gate, permission or commit behavior changes the machinery that judges every other change. MUST run `python3 -m pytest modules/harness/factory/tests/ -q` and keep it green. NEVER weaken a gate to make a run pass.

## UI work — MANDATORY

ANY change under `apps/web/src/**` or `packages/deck-ui/src/**` → read
`.claude/skills/od-ui-dev/SKILL.md` FIRST and obey it. Non-negotiable core:

- Generic primitives come from `@platform-modules/ui-primitives` FIRST (owner standing
  rule): `DataTable` for all tables, plus its other exports. deck-ui = overdeck-specific
  composition only.
- Compose existing `@overdeck/deck-ui` exports (`packages/deck-ui/src/index.ts` = the
  registry). NO hand-rolled tables/chips/menus/tooltips in apps/web.
- NEVER create a new primitive without explicit user approval — stop and report instead.
- Tokens only, both themes. Honest data — never fabricate values.
- Every deck-ui component registered in the `/design-system` gallery; barrel⊆gallery test
  and slopgate stay green — never suppress/baseline your own violations.

## Worktree isolation — MANDATORY

NEVER work in `/home/user/Projects/overdeck` itself (the shared main checkout) —
other agent sessions have uncommitted work there; `git restore`, `checkout --`/
`checkout .`, `stash push|pop|drop|clear`, `clean -f*`, `reset --hard` there
destroys it. Claim a worktree first: `~/.claude/bin/od-worktree add <slug>`,
then `cd .worktrees/<slug>` and work only there.

Enforced fail-closed, not by convention:
- Claude Code: PreToolUse hooks deny Edit/Write into the main checkout and the
  destructive git verbs above run against it.
- codex (`cdx exec`, incl. via `/ask-codex`), cursor-agent, and anything else
  launched under the agent shim chain: a `git` PATH shim blocks the same
  destructive verbs against the main checkout.

A refusal names the fix (`od-worktree add <slug>`) — run it, never retry raw.

## Verification

`pnpm --filter @overdeck/deck-ui test|typecheck`, `pnpm --filter web build|typecheck`,
collector: `bun test` in `collector/`. Playwright probes: SSE stream ⇒ `networkidle`
never fires — use `domcontentloaded` + `waitForSelector`.

## Runtime before Git — MANDATORY

Owner-facing Overdeck failure, live incident, blocked work, or laptop load fire → invoke `/od-emergency` FIRST and follow it through installed owner-visible proof. Runtime restoration MUST precede full gates, Git, queues, and review. Applies to product/UI/collector and local infra. Normal feature work with no active incident keeps branch→gate→land→deploy order.

Never cut safety floor: isolated candidate, smallest seam check, atomic rollback, exact-service scope, real installed-entrypoint proof. NEVER mutate served web output in place.

## Landing

DEFAULT: work on a branch; land via `.claude/scripts/ship.sh` (guarded trunk),
driven by the orchestrator, not you. NEVER hand-type the merge/push cascade.

DIRECT LAND — owner-authorized escape hatch for runtime-first work above, or when the land queue is the bottleneck (queue
depth stalls landing for hours). NEVER a way to skip a red gate: you own the
verification the queue would have run.

```bash
/usr/bin/git -C <worktree> -c core.hooksPath=<empty-dir> push origin HEAD:refs/heads/main
cd <repo-root> && bash packaging/deploy-local.sh   # MANDATORY — landing without deploying ships nothing
```

`/usr/bin/git` by absolute path: plain `git` is a PATH shim that reroutes `push`
into the land queue. Re-fetch and merge `origin/main` immediately before pushing —
main moves fast. A direct land skips the gate, so you own verification: run the
touched module's tests yourself and report what you did NOT verify.