`AGENTS.md`

55 lines
# AGENTS.md — AbramsOS engineering guardrails

This file is read by Claude Code, Codex, and any other coding agent that touches this repo. It overrides general defaults.

## Approval policy (hard rules)

| Action | Approval |
|---|---|
| Read evidence (email, doc, recall feed) | auto |
| Insert into `purchase`, `purchase_item`, `source_message`, `document` | auto |
| Draft a letter, claim packet, or registration form | auto (saved as draft only) |
| Send any email, file any dispute, submit any regulator form | **explicit user approval per action** |
| Auto-renew or auto-purchase warranty/service contract | **never automated; always user-initiated** |
| Touch HIPAA-flagged rows | requires `medical_consent_grant` row + audit_log entry |
| Outbound webhooks to merchants/issuers | destination allowlist + signed; no free-form URLs |

## Hard NOs

- **No Anthropic API key.** Use the `claude` CLI or local Ollama. Never `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` in any process env.
- **No mocking the database in tests** — use a throwaway `abrams_os_test` DB.
- **No specs/numbers in marketing body copy.** Editorial prose only; structured fields live in the schema.
- **No external action without an `audit_log` entry** referencing the consent grant that authorized it.
- **No PII to model providers** without redaction. Redact name, address, account numbers, MRN, NDC-as-PHI before any prompt.
- **No public-image stock libraries** (Unsplash/Pexels/Getty). Allowed: Wikimedia, IA, Calisphere, USC, LAPL.

## Code standards

- Node 18+. CommonJS in this repo for parity with `george-gmail`/`ventura-claw-leads`.
- All DB access through `lib/db.js` (single `pg.Pool`).
- All Gmail access through `lib/gmail-fetcher.js`. Never call `googleapis` directly from a route.
- Refresh tokens encrypted with AES-256-GCM (`lib/crypto.js`) before insert.
- Every route writes one `audit_log` row per state-changing operation.
- Every new table gets a sequenced migration in `db/migrations/NNNN_*.sql`.
- Frontend grids inherit `public/js/sort-density.js` (sort + density slider, localStorage).
- Every page inherits `views/layout.ejs` (liquid-glass shell, dark/light toggle).

## Test gate

- `npm test` must pass before any commit.
- Every new skill/agent must ship with at least one golden-file fixture.
- Receipt extractor regressions: keep golden fixtures in `tests/fixtures/receipts/`.

## Compliance posture

AbramsOS is consumer-only today. Medical features are gated behind a separate consent grant and (eventually) a HIPAA-grade deployment lane. See `docs/COMPLIANCE.md`. Until that lane exists, do **not** ingest provider-sourced PHI; user-uploaded medical receipts are fine.

## Standing rules inherited from Steve's global instructions

- All builds gitified (commit per logical change).
- Every site needs `info@<domain>` (provisioned via Purelymail).
- Every product/data grid gets sort + density slider.
- Dark/light toggle on every B&W build.
- Always use ElevenLabs for voice (no piper/say/coqui as primary).
- Default to Browserbase before local headless browsers.