# Doc Review: add-state-loop-lock

Reviewed docs touched by or referring to the fix.

## Files reviewed

- `CHANGELOG.md` — added `### Added — .state.loop file lock (task add-state-loop-lock)` at the top of `[unreleased]` covering R1-R7 + D-L1 through D-L6, the env-var mechanism, callsites wrapped in both scripts, the test plan, the adversarial findings, backwards-compat, stdlib-only constraint, and 447-passing count.
- `AGENTS.md` — added a `.state.lock` (v1.1) bullet under State Enforcement — Loops (v1) summarizing the lock shape, granularity, blocking-acquire behavior, env-var mechanism, and pointer to the technical doc.
- `README.md` — extended the Loop Engineering runtime paragraph with a single sentence pointing at `.state.lock` serialization with a `design/loops/technical.md §7` pointer.
- `design/loops/technical.md` §7 — added a new "Lock serialization" subsection covering the lock shape, callsites in both scripts, the env-bypass mechanism (D-L6), the re-entry forbidding audit, and the harness-contractor-loop-control implication.
- `contracts/harness-integration.md` — no edits. The A4 follow-up "forbid loop-control commands inside a tick" is deferred to a small docs-only follow-up (not a blocker); listed in the design doc. Did NOT modify the harness integration contract in this task to avoid scope-creep.
- `prompts/loop-*.md` — no edits (phase prompts are content; no locking references there).
- `scripts/install.sh` / `scripts/update.sh` / `scripts/upgrade.sh` — no edits (don't touch the lock).

## Cross-references checked

- `rg "_loop_lock|\.state\.lock|AUTOMATON_NO_LOOP_LOCK" design/ templates/ scripts/ contracts/ README.md AGENTS.md prompts/` — all hits intentional.
- `rg "fcntl|msvcrt|flock" design/loops/technical.md AGENTS.md README.md` — only intentional references in the new docs.
- The `add-loop-runner/` v1 CHANGELOG entry still says "the runner writes `.state.loop` atomically via `_write_state_loop` (tmp file then replace)" — this remains accurate (the atomic write is still in place; the lock adds a coarse mutex on top — defense-in-depth per D-L5).

## Verdict

PASS — proceed to referee.