# ADR-002: State Storage on Orphan Git Branch

**Status:** Accepted
**Date:** 2026-01

## Context

Josh-sync needs persistent state to track what has already been synced (last-synced commit SHAs, timestamps, status). This prevents re-syncing unchanged content and enables incremental operation. The state must survive CI runner teardown — runners are ephemeral containers.

### Alternatives considered

1. **File in the repo**: Commit a state JSON file to the monorepo. Every sync run creates a commit, polluting history. Race conditions when multiple sync jobs run concurrently.

2. **External database/KV store**: Redis, SQLite, or a cloud KV service. Adds an infrastructure dependency. Credentials and connectivity to manage.

3. **CI artifacts/cache**: Platform-specific (GitHub Actions cache, Gitea cache). Not portable across CI platforms. Expiry policies vary.

4. **Orphan git branch**: A branch with no parent relationship to the main history. Stores JSON files in a simple `<target>/<branch>.json` layout. Pushed to origin, so it survives runner teardown. No external dependencies — uses git itself.

## Decision

Store sync state as JSON files on an orphan branch (`josh-sync-state`) in the monorepo.

### Storage layout

```
origin/josh-sync-state/
  <target>/<branch>.json       # sync state per target/branch
  <target>/onboard.json        # onboard workflow state (v1.1+)
```

### Implementation

- `read_state()`: `git fetch origin josh-sync-state && git show origin/josh-sync-state:<key>.json`
- `write_state()`: Uses `git worktree` to check out the orphan branch in a temp directory, writes JSON, commits, and pushes. This avoids touching the main working tree.

## Consequences

**Positive:**
- Zero external dependencies — only git
- Portable across CI platforms (Gitea Actions, GitHub Actions, local)
- Human-readable JSON files — easy to inspect and debug
- Atomic updates via git commit + push
- Natural namespacing via directory structure

**Negative:**
- Concurrent writes can race (mitigated by concurrency groups in CI workflows)
- `git worktree` adds complexity to the write path
- State branch appears in `git branch -a` output (minor clutter)
- Push failures on the state branch are non-fatal (logged as warning, sync still succeeds)