rein-aharness/docs/external-metrics.md

Durable external metrics

Repository-granted runs must not dirty a checkout after acceptance. Their kaizen-compatible execution record and summary are therefore written beneath:

$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 fsynced before the summary and projection descriptors are atomically replaced and directory metadata is fsynced. 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.