# CLAUDE.md — Agent Operational Rules (AEGIS CYBER)

This file holds **agent operational discipline** for working in this repo — tool-usage efficiency
rules, distinct from the twenty-two AEGIS security-governance Standing Agent Rules (those live
verbatim in `docs/regulatory/STANDING_AGENT_RULES.md`, with a pointer index in `replit.md`).

## OR-1 — `bash` timeout discipline (always include it; budget generously for slow ops)

**Tool:** the shell command-execution tool (`bash`). **Parameter:** `timeout` (milliseconds).

1. **`timeout` is REQUIRED and has NO default — always include it on EVERY `bash` call.**
   Omitting it produces an immediate validation rejection (`timeout — Field required`) and forces a
   redo: a wasted forget-and-retry cycle. (Verified against this project's own session transcript —
   8 `Field required` rejection occurrences.)

2. **Budget a generous timeout toward the 120000 ms (2-minute) maximum for known-slow operations.**
   On this repo that includes: `tsc` / TypeScript typecheck (large project — routinely exceeds short
   limits), prod-SQL joins (neondb round-trip latency), and recursive `grep` / `find` scans. Too short
   a value causes an `exit code 124` (command-timed-out) failure and another redo. For a heavy op,
   prefer running it to a file in the background and polling, or narrowing scope (targeted `rg`), over
   re-running repeatedly at a slightly-higher timeout.

**Not the issue (red-herring inoculation):** `restart_workflow`'s `workflow_timeout` is **optional**
with a **30 s default** — omitting it is harmless (it just uses 30; a longer value such as 60–90 s only
helps slow boots). The log-fetch tools (`fetch_deployment_logs`, `refresh_all_logs`) take **no** timeout
parameter at all. The required-timeout / forget-and-retry friction is **`bash` only**.

**Reversibility (mirrors the Standing-Rules commitment):** if a rule here produces friction without
proportionate value, surface it and retire it with the same explicit process as its addition.

## OR-2 — Typed API queries (the #52 "close-the-class" convention; enforced by a baseline ratchet)

**Why.** The F4 defect class: a `useQuery<any>` (or a bare `useQuery(...)`, which infers `any`) reading a
field the server never sends renders a **silent** blank/`0`/`"unknown"` — no compile error, ships
undetected. Four such bugs shipped and were later caught only by eye (safety-rails kill-switch fields,
uganda sovereignty rules, backups summary, system-pulse threats). Typing the query against the server's
actual response shape turns every such mismatch into a `tsc` error (`TS2339`), so it can't ship.

**The convention.**
1. **Every API response shape lives in `shared/api-types.ts`** — one source of truth both sides import.
2. **The server function that answers a route returns that type** (`getRules(): SovereigntyRule[]`), so a
   server-side field rename is a compile error there.
3. **The client types the query against the same import** — `useQuery<SovereigntyRule[]>(...)`, never
   `useQuery<any[]>` — so a client read of a non-existent field is a compile error there.
   Divergence on **either** side fails `tsc`. (Feasibility: the client already resolves `@shared/*`.)

**New queries MUST be typed.** Do not add `useQuery<any>` / `useQuery<any[]>` / bare `useQuery(`.

**Enforcement — baseline ratchet (`scripts/check-untyped-queries.mjs`).** Counts the untyped-query class
across `client/src`; **fails if the total exceeds the baseline** (currently **172**, the legacy backlog).
A new untyped query pushes the count over baseline → fail. Retrofitting a surface **lowers** the count →
**lower the `BASELINE` constant** to lock the gain. It is a ratchet: **down only, never raised to pass.**
The baseline number *is* the burn-down list (Tier-2 = keep lowering it). It counts only the untyped class,
so a legitimate `useQuery<RealType>` is never flagged.

- Wired into **`npm run check`** (runs after `tsc`) — the standing verify gate.
- Enforced at **push** by a committed hook: `scripts/hooks/pre-push`. **Activate once per clone:**
  `git config core.hooksPath scripts/hooks`.
- (No CI workflow — deliberately held; the verify gate + pre-push hook are the enforcement surface.)