---
id: STATE-ADR-002
type: architecture-decision-record
title: "Use Forge commits, never another machine's checkout, as the cluster repository boundary"
status: accepted
owner: state-hub
date: "2026-09-04"
deciders:
  - operator
  - state-hub
related:
  - STATE-WP-0081
  - STATE-WP-0083
  - STATE-WP-0084
  - STATE-WP-0086
---

# Use Forge commits as the cluster repository boundary

## Context

The former consistency sweep mounted an operator home directory into the
production State Hub pod. The cluster therefore saw stale checkouts, wrote
root-owned files into human workspaces, inherited a personal SSH identity, and
could not distinguish an absent work record from an out-of-date disk.

Repository files remain authoritative, but a local checkout is only one
machine's observation of those files. It is not a cross-machine transport.

## Decision

Workstation agents commit and push repository authority to Forgejo. Cluster
infrastructure reads a named, verified Forge commit into ephemeral storage.
Neither side reads or writes the other side's checkout.

`local_path` and `host_paths` remain compatibility/observation fields for tools
running on the named host. They must not select central reconciliation input.
Central reconciliation records both the expected and derived commit and refuses
the projection if they differ.

Cluster Forge access uses a workload service identity whose credential is
obtained through Kubernetes authentication to OpenBao. Personal SSH directories
and home-directory hostPaths are prohibited.

## Consequences

- A workstation change is invisible centrally until it is committed and pushed.
- A cluster result is attributable to an exact Forge commit.
- Temporary clones and credentials may be discarded after reconciliation.
- Offline writes use the explicit edge outbox; shared disks are not a fallback.
- Scripts needing repository contents locally resolve the current host's
  `host_paths` entry and must fail clearly when no checkout is present.

## Verification

- The live State Hub pod has no operator-home or SSH hostPath.
- `rmgr sync --push` verifies `primary/railliance01` and exact commit equality.
- `docs/evidence/repository-registry-audit-20260904.json` records no active
  repository without a remote and no stale Gitea remote.