| 1 | # Safety checklist for a project |
| 2 | |
| 3 | What a project's AGENTS.md should state, and how to enforce each item so it |
| 4 | holds when an agent forgets. Every enforcement here is a suggestion; none is |
| 5 | built 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. |