1# Safety checklist for a project
2
3What a project's AGENTS.md should state, and how to enforce each item so it
4holds when an agent forgets. Every enforcement here is a suggestion; none is
5built yet. A rule that only a brief repeats will be forgotten.
6
7- **Version control.** AGENTS.md: which VCS; in a jj repo, never `git`, not even
8 read-only. Enforce: a hook that denies `git` when the repo has `.jj`, or a
9 `git` shim on agents' PATH that refuses there.
10- **One history rewriter.** AGENTS.md: only the agent the orchestrator names
11 rewrites history. Enforce: a jj wrapper that takes a lock for rewriting
12 commands, or the orchestrator's ownership map alone.
13- **Commands that open an editor.** AGENTS.md: always `-m` or
14 `--use-destination-message`. Enforce: `JJ_EDITOR=false` in agents' env, so a
15 bare `squash` fails instead of hanging.
16- **Clean environments.** AGENTS.md: servers, tests and builds start from
17 `env -i` with their own `TMPDIR`, home and config dirs; agents check a
18 server's env (`ps eww`) before clicking anything that writes. Enforce: a
19 one-command scratch launcher that sets all of that, picks a free port, and
20 records the PID.
21- **No-touch trees.** AGENTS.md: the paths agents may read but never write (her
22 real app data, credentials, `/Applications`, installer caches). Enforce:
23 sandbox writable roots that exclude them, or a hook on writes and deletes.
24- **Processes.** AGENTS.md: signal only PIDs you started; never kill by pattern;
25 never touch her running app or its helpers. Enforce: a hook that denies
26 `pkill` and `killall`; a stop command in the scratch launcher that reads its
27 recorded PIDs.
28- **Exclusive harnesses.** AGENTS.md: which harnesses allow one run at a time.
29 Enforce: the harness takes its own lock and refuses a second run.
30- **Secrets.** AGENTS.md: no secrets in logs, output or tracked files; never
31 copy a credential into a fixture; check a credential by printing status codes
32 only. Enforce: a secret scan in the pre-publish gate.
33- **Private names.** AGENTS.md: no employer names in tracked files. Enforce: a
34 denylist check in the pre-publish gate.
35- **Model turns in tests.** AGENTS.md: Claude Haiku or Codex Luna only. Enforce:
36 the test harness rejects other model ids.
37- **Shipped-data compatibility.** AGENTS.md: synced or persisted records stay
38 two-way compatible: optional keys old decoders drop, no additions to a closed
39 union. Enforce: a test that decodes fixtures captured from shipped versions.
40- **Risky subsystems.** AGENTS.md: which subsystems need an isolated end-to-end
41 run on the exact tree plus a review before release. Enforce: the release
42 script refuses a tree without a passing run recorded for that commit.
43- **Credits.** AGENTS.md: `Assisted-by: <model>` trailers, one per model, never
44 `Co-authored-by`. Enforce: a trailer check in the pre-publish gate.
45- **Machine load.** AGENTS.md: caps on parallel builds, VMs and waits. Enforce:
46 the scratch launcher runs heavy jobs under `nice` with a job cap, and every
47 wait helper takes a timeout.
48- **Protected paths for cleanup.** AGENTS.md: what cleanup never deletes (SDKs,
49 toolchains, her data). Enforce: cleanup deletes only under recorded scratch
50 roots.