diff --git a/AGENTS.md b/AGENTS.md index 4b66d9ba..2d92c356 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -118,14 +118,28 @@ from `AbstractNDArray`; `.array` returns the raw `numpy.ndarray` / `jax.Array`. - [`docs/agents/jax_and_decorators.md`](docs/agents/jax_and_decorators.md) — decorator system, `xp` backend pattern, and the `jax.jit` boundary. -## Clean state - -Never rewrite history on a repo with a remote (no `git init` over a tracked -tree, no force-push to `main`, no rebasing pushed shared branches). To reset a -dirty tree the only correct sequence is: - -```bash -git fetch origin -git reset --hard origin/main -git clean -fd -``` + +## Never rewrite history + +NEVER perform these operations on any repo with a remote: + +- `git init` in a directory already tracked by git +- `rm -rf .git && git init` +- Commit with subject "Initial commit", "Fresh start", "Start fresh", "Reset + for AI workflow", or any equivalent message on a branch with a remote +- `git push --force` to `main` (or any branch tracked as `origin/HEAD`) +- `git filter-repo` / `git filter-branch` on shared branches +- `git rebase -i` rewriting commits already pushed to a shared branch + +If the working tree needs a clean state, the **only** correct sequence is: + + git fetch origin + git reset --hard origin/main + git clean -fd + +This applies equally to humans, local Claude Code, cloud Claude agents, Codex, +and any other agent. The "Initial commit — fresh start for AI workflow" pattern +that appeared independently on origin and local for three workspace repos is +exactly what this rule prevents — it costs ~40 commits of redundant local work +every time it happens. +