# 🤖 CARLOS working conventions

How the family builds. These conventions exist because each was learned the
hard way at least once; the incident is noted where it names the rule.

## Repo documents

- **AGENTS.md** — "how we build and the decisions we've committed to."
  Written before the code (factor V: the intent is the system — the code
  should have to argue with something). Opens with the one rule. Contains:
  settled decisions (dated, attributed, with rejected alternatives),
  named laws, the workflow, and a "Deliberately not built yet" list with the
  trigger for each deferral. One file, for every agent that reads the repo —
  not one per vendor. Older repos still carry it as CLAUDE.md; rename it to
  AGENTS.md the next time you touch one, rather than keeping two.
- **README.md** — user-facing: what it is, run it, honest trade-offs.
- **DESIGN.md** — the spec, what gets built. **PLAN.md** — why it is shaped
  this way, the roadmap.
- **docs/** — design records and briefs, written *before* the build
  ("Brainstormed with Paul; decisions recorded here"), each with a Status
  line (`built` / `approved design — not yet built`), annotated in place
  when built. The doc's decisions are binding: if one proves wrong in
  practice, stop and flag it in the PR rather than redesigning.

## Git and PR playbook

- **Worktree per session, always.** Multiple sessions (agents and humans)
  are active at once; the main checkout's uncommitted state belongs to
  another session. Never build in the main checkout — reading it is fine,
  writing is not.
- **The cadence is: worktree → branch → regular pushed commits →
  squash-merge.** Commit as you go and push every commit. The branch is
  where work in progress lives; you do not wait to be asked to put it
  there, and a session that ends with unpushed work has lost it as far as
  everyone else is concerned. Keep the PR small and focused.
- **Squash-merge to main when all three hold: the work is done, a human has
  approved it, and CI is green** (`gh pr merge --squash --delete-branch`
  on GitHub; on amadan, where the branch is the pull request,
  `amadan branch merge` makes a merge commit and `-squash` lands one
  commit; never squash by hand there, or the branch shows as deleted).
  Two of the three is not a merge — a green run on unapproved work waits,
  and an approval over a red run waits. Never commit to main. Deploy only
  merged main, and only when asked.
- **"CI green" binds once CI exists, and a new repo's early work is to
  make it exist.** A repo with no CI has no green to wait for: the
  condition is not waived, it simply has nothing to read yet, so the first
  merges of a new project land on done + approved. Standing up CI is one
  of the first work items, not a prerequisite nobody can satisfy — and it
  is the gate you already run locally, kept as one definition rather than
  a second list that drifts, so debugging CI is running it. Once the repo
  has CI all three bind absolutely and the carve-out is spent.
- Commit subjects are area-prefixed prose that says why (`web: the front
  door is a homepage — pitch left, sign-in right`; `auth: delete the
  recovery passphrase, root and branch`). Comment the why, not the what.
- Every commit carries `Co-Authored-By: Claude <model>
  <noreply@anthropic.com>`; the human is the author of record.

## Canaries

- **Every session gets its own canary; review happens on a deployed canary,
  never on localhost.** (Adopted after two sessions sharing a dev host
  produced an evening outage.) Local stacks are for automated drives only.
- On the platform, a canary is a channel: `carlos canary` deploys to
  `canary/<slug>` (a per-session dead-end rung, zero bake) and the canary
  host serves it at
  `<slug>-<app>.<sqid>.<domain>` — same rule, no box. Off-platform,
  canaries multiplex onto the devbox: own port/state/unit/TLS at
  `<branch>.<dev-host>`. Shared hosts (`prod`, the plain dev host) only ever
  carry main builds — enforced by the deploy path, not memory.
- Report the complete clickable canary URL in **every** reply while
  iterating, with a short list of what to test. The human clicks through
  mid-flight; never make them scroll back for the URL.
- Tear your canary down when the branch merges. Never echo claim links or
  secrets into the session — the prompt ledger publishes what gets typed.

## Testing

The layers, in order:

1. **`go test ./...`, `go vet ./...`, `gofmt -l .` — all clean, always.**
   Nothing lands untested; a bug fix carries its regression test. When
   gating on a test run, never pipe it — a pipe eats the exit code (a red
   suite once merged and deployed exactly this way). A guard belongs
   *inside* the test binary, never in a shell step around it — a guard a
   shell step can satisfy is a guard a shell step can be wrong about
   (one browser-required check went silently unrun for weeks).
2. **Prefer a parsing test to a browser for anything computable from
   source.** Contrast ratios computed from the token file's declarations
   (WCAG AA, both themes, no browser); network reachability rules parsed
   from the served JS; performance fixes shipped with an `EXPLAIN QUERY
   PLAN` assertion over the *exported production query string* so the
   test cannot drift from the real SQL. When a rule needs an exception,
   the allowlist entry pins the exact occurrence count, not just the
   file — a new call site inside an exempted file must still fail.
3. **JS logic DOM-free under `node --test`**, wired into `go test` via a
   small `jstest_test.go`, so one command runs everything. `node --check`
   alone is not enough — it parses as CommonJS and swallows ES-module errors
   that crash Safari; check a `.mjs` copy and load it in a real engine.
4. **uidump — dump, don't drive** (adopted by the platform console). An env-gated test (`UIDUMP_DIR` set, else
   skipped) boots the real handler in-process over `httptest`, seeds a
   fixture world rich enough that every state has a subject, signs in,
   GETs every named screen, and writes each response body to disk with
   asset paths rewritten relative so the files stand alone. An agent
   then screenshots the static files directly with headless Chrome
   (`--headless --screenshot=…`), re-shooting dark mode by stamping the
   theme attribute and mobile at a narrow window. Near-zero cost, zero
   flake, works on a display-less box; adding a screen is one map entry
   — and **"add your screen to the dump" is a checklist line in every
   plan**, or coverage rots. It renders HTML+CSS only and asserts
   nothing itself: it is the visual-review gate, not the invariant gate.
5. **Browser drives are for the residue** that needs a JS engine and
   real layout geometry — enhancement-script behaviour, popover sizing,
   overflow, theme resolution — env-gated, with assertions written as
   the named bug class they caught. Playwright, or chromedp for
   pure-Go. Passkey flows run in Chromium — the virtual authenticator
   is a CDP feature; a separate passkey-free smoke runs in WebKit,
   Safari's engine, because it breaks first. Loud on purpose: fail on
   any console error, page error, or failed request, and junk-scan
   every view for `undefined`, `null`, `[object Object]`, `NaN` — the
   bug class that renders perfectly and says nothing (a stray `null`
   *text node* included: native `append()` stringifies one). A skip is
   not a pass: report executed-vs-skipped.
6. **The merciless greps** (server-blind apps): end-to-end tests that grep
   raw SQLite bytes *and* S3 objects for plaintext content and names.
7. **After every deploy: the console check in WebKit** against the live
   host (the keymail rule) — a JS syntax error takes the whole client down
   and only a real engine sees it; WebKit specifically, because it is the
   strictest engine and Safari users hit it first.
8. **Security scan** (Aikido) before ending a work cycle; triage every
   finding; never publish over an untriaged one.

Simulation suites are the spec for convergence-critical engines (sync,
progression): any behaviour change changes the suite first. Golden vectors
pin multi-language implementations (see blueprint.md).

## Ending a session

Every session ends through the committed `/end-session` gate. The shape:

1. Clean tree — nothing uncommitted, nothing unpushed, no orphan worktrees.
2. Gates green: build, vet, gofmt, tests (unpiped), browser drives with
   executed-vs-skipped counts.
3. Security scan clean or triaged.
4. Ledgers accrued (below), reviewed word-by-word for secrets before
   publishing — never publish text you haven't read; when unsure, redact
   with an annotated `⟦redacted: category⟧` and say what and why.
5. Deploy state reported; canaries torn down or handed over.
6. A handoff report: PRs, clickable canary URLs with what to verify, open
   threads, and what was deliberately not done.

## Ledgers and transparency

The family practices radical operational transparency on a public status
site: **prompt registry** (every human prompt behind the code, whole and in
order, credentials redacted in place), **carbon tally** (token spend →
CO₂e bands, plus the boxes' share), **contributors** (humans and AI models
on one metric, from git trailers), roadmap and milestones written in member
language — what changed for a member, never how the boxes are run. Ledger
updates ship exactly like code: commit → PR → deploy. No hostnames, no
account IDs, no third-party personal data in anything published.

## AI authorship (factor X)

- Machine-authored text is marked **🤖** wherever it surfaces — visible,
  immediately before the heading or block it covers; a marker on a heading
  cascades. Never hide the 🤖 in a comment.
- A person marker (👨/👤/🧑) certifies human text: an LLM must not rewrite,
  rephrase, condense, or delete it. No marker means ambiguous — never claim
  human authorship for unmarked text.
- Disclosure extends to product: AI features are opt-in, never required,
  always disclosed, and every path works with the AI switched off — this is
  a hard constraint, not an aspiration. Nothing assumes AI stays cheap.
- Uncompiled or unverifiable code is marked (`// UNVERIFIED: written without
  an iOS toolchain`) and kept in separate commits.

## Working with the human

Patterns visible across every prompt history, useful calibration for agents:

- Directives are terse ("go", "merge", "Deploy!", "keep going until it's
  done"). Long autonomous runs are normal; write the design doc, then build
  until there's something live to click.
- Bug reports arrive as lived user experience from the live product, in
  product language. Reproduce on a canary, fix, and ask "is this flow being
  tested?" — because that question is coming.
- Product shape is given, parameters are left open ("allows edits for what,
  5 minutes? 2 minutes?") — make the judgement call and flag it.
- Sibling apps are the design vocabulary ("like Eleven's home server",
  "Woodstar's shape, copied on purpose"). Check the sibling before
  inventing.
- Calm UI: red is for danger only, no toasts, no nerdspeak in the default
  flow, buttons stay where the thumb is, feedback is inline and honest.