feat(runtime): enforce governed mutation boundaries

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a06ba0-10aa-7ea0-b20a-4f3fac39efe9

docs/external-metrics.md

@@ -0,0 +1,36 @@
+# Durable external metrics
+
+Repository-granted runs must not dirty a checkout after acceptance. Their
+kaizen-compatible execution record and summary are therefore written beneath:
+
+```text
+$REIN_AHARNESS_STATE_DIR/execution-metrics/<repository-id>/<agent-id>/
+```
+
+When the explicit state variable is absent, the runtime uses
+`$XDG_STATE_HOME/rein-aharness` or `~/.local/state/rein-aharness`. Repository
+and agent directory names are SHA-256-derived identifiers rather than caller
+text. Directories are mode `0700`; records and lock files are mode `0600`.
+
+Each directory contains:
+
+- `executions.jsonl`: append-only kaizen `ExecutionRecord` values;
+- `summary.json`: regenerated aggregate metrics; and
+- `projection.json`: repository id/name, agent name, and intended consuming
+  path `.kaizen/metrics/<agent>`.
+
+Writes serialize on a process-safe lock. The execution record is flushed and
+`fsync`ed before the summary and projection descriptors are atomically replaced
+and directory metadata is `fsync`ed. Replaying the same transaction identity
+regenerates the derived files without adding a duplicate ledger record. Failure
+to persist this evidence makes a granted run unsuccessful; granted execution
+cannot opt out with `--no-metrics`.
+
+Projection is a separate repository mutation. This harness does not copy these
+files back automatically, because doing so would invalidate the accepted clean
+post-state. A future kaizen-owned projection lane may consume
+`projection.json`, copy `executions.jsonl` and `summary.json` to the declared
+target, and commit them under its own explicit repository grant. Until that
+lane exists, the external files are the durable source of truth for granted
+runs. Grant-absent compatibility runs continue to write repository-local
+metrics directly.