claude-forgejo-sandbox/docs/reforge.md

# Reforge — stack-rebuild simulations

**A reforge is a controlled simulation in which a role-isolated agent team
rebuilds a software stack from pinned clean bases to byte-for-byte parity
with a declared target — the known working state — coordinating entirely
through a local forge (issues, branches, PRs, enforced independent review),
exactly as a real development team would.**

The infrastructure is the forgejo sandbox (docs/architecture.md); this doc
is the concept and the lifecycle.

## What it actually is

Several familiar practices, fused:

- **A disaster-recovery drill for the codebase.** Proves the stack can be
  re-derived from public upstream bases plus recorded intent — bus-factor
  insurance for software whose value lives partly in accumulated,
  under-documented decisions.
- **A review retrofit.** Every line of the stack re-passes through a
  security gate and a charter-alignment gate that didn't exist when it was
  first written. Code that "works in production" earns its bill of health
  instead of inheriting it.
- **An insight harvest.** The issues, review comments, and rejections
  produced during the rebuild are findings about the *real* stack, free of
  production pressure. They are first-class artifacts, archived with every
  run.
- **Adjacent to clean-room reimplementation**, but inverted: the target is
  declared and diffed against, rather than hidden. Fidelity is measured, not
  hoped for.

## A run's input parameters

A simulation is fully specified by five things — everything else is
*produced by* the run, not fed into it. All five live in your run config dir
(`reforge.configDir`), so a run's parameters are reproducible by checkout:

1. **The repo list** — which pieces of the stack are in scope
   (`manifest.txt` rows).
2. **The charter** — the standard changes are judged against (`charter.md`,
   seeded as the `charter` repo).
3. **Each repo's starting condition** — the pinned base it is seeded at
   (`base_ref`; for original software: empty).
4. **Each repo's ending condition** — the target state it must reach
   byte-for-byte (`target_url` + `target_ref`).
5. **The agenda** — what this particular run must address (`agenda.md`,
   seeded as `charter/AGENDA.md`, filed as issues from `issues.tsv` at
   kickoff).

## Disclosure policy (staged visibility)

The end conditions are a functioning **proof of concept** — the run exists
to find its bugs, refactor opportunities, and distance from production
*before release*. To keep the findings honest, what the role sessions may
see is staged:

- **Phase A — guided rebuild, end-state blind.** Roles work from intent, not
  answers: the charter + agenda (in-forge) and whatever intent docs the
  charter points to. The target repos are off-limits; issues and design
  decisions produced in this phase reflect what the team would build from
  the recorded intent.
- **Phase B — end-state visible, convergence *and* evolution.** Targets are
  opened to the roles (as source-stripped local mirrors — see below). Phase
  B has **two** objectives: (1) converge each repo to its target (compare
  script as the gate), re-derived through gated PRs so every line re-passes
  the security + charter gate; and (2) **evolve toward the vision** — carry
  the Phase-A findings forward as *tracked divergences* (approved issue +
  gated PR + manifest-target bump; never silent drift) that move the stack
  toward the charter. Fixes the target does not contain are *parked open*
  (do-not-merge, kept visible as remediation), never closed.
- **Comparing ambition levels.** To see the result of each *scope* of
  evolution, build them as separate runs from ONE shared parity baseline:
  reach parity → archive the baseline → drive one scope to completion →
  archive it → restore the baseline and drive the next. The archives are the
  comparison corpus: identical inputs, divergent ambition.
- **Both phases:** targets are never pushed into the sandbox. Only the
  compare script touches them mechanically, and only the **operator** runs
  it (roles and the orchestrator are barred from the real remotes). Phase B
  visibility is provided by `reforge-fetch-targets`, which clones each
  target into a source-stripped local mirror (`~/reforge-targets/<repo>`,
  git metadata removed → no remote, no push path) that roles read as the
  end-state.

The human decides when Phase A has produced enough independent signal to
open Phase B — that switch is a log-worthy moment of the run.

## Vocabulary

| Term | Meaning |
|---|---|
| **simulation / run** | One full pass: reset → seed → rebuild → compare → archive |
| **base** | The pinned upstream state a fork is seeded from (`base_ref` in the manifest) |
| **target** | The known working state (real repo + branch) the run must reproduce byte-for-byte |
| **manifest** | `manifest.txt` — repo set, bases, targets |
| **acceptance** | `reforge-compare` reporting IDENTICAL for every targeted repo |
| **archive** | Cold tarball of the full forge state (repos + issues + PRs + reviews) per run |

## The contract (invariants of a real run)

1. **Bases are pinned.** No `auto` refs in the manifest — two seedings must
   produce the same starting point.
2. **Targets are declared but never pushed into the sandbox.** Only the
   compare script touches them; content parity is judged on trees, not
   history — the simulation re-derives the tree through its own PR history.
3. **All change flows through PRs.** Direct push to `main` is blocked
   everywhere; only `security-lead`'s approval unlocks a merge; the
   `reviewer` holds quality + charter alignment.
4. **Acceptance is mechanical.** The run is done when the compare script
   exits 0 — byte-for-byte, no "close enough". The targets are a PoC, so
   parity includes reproducing its bugs: **findings become issues, not
   divergence.** A truly justified divergence is an approved issue *plus* a
   manifest-target update, never a silent drift.
5. **Findings are first-class deliverables.** Issues traceable to agenda
   items, reviews on every PR, and a `GAMEPLAN.md` (PR'd into the charter
   repo) stating what stands between the stack and production-ready.
6. **Runs are never destroyed, only closed.** `reset` archives before it
   wipes; archives are the corpus future runs (and the real stack) learn
   from.

## Lifecycle

```
0. pin      edit manifest.txt in your config dir        (bases + targets)
1. reset    reforge-reset reset <run-name>
            (archives the previous simulation, wipes to zero, reprovisions
             users/tokens/org — then get the new admin UI password from
             /var/lib/forgejo-sandbox/admin-password)
2. seed     reforge-seed
3. kickoff  reforge-kickoff
            (files issues.tsv as [item-id]-tagged issues; roles start in
            Phase A, end-state blind)
4. rebuild  role sessions do the work — one terminal per role:
            reforge-role <role>
            issues to plan, branches + PRs to change, reviews to gate;
            human opens Phase B when Phase A's signal is banked
5. compare  reforge-compare
            iterate 4 ⇄ 5 until every targeted repo is IDENTICAL
6. harvest  GAMEPLAN.md PR'd into charter; issues reviewed + triaged against
            the real stack; **refine these instruction sources** (this doc,
            the agent briefs, the agenda, the scripts) with what the run
            taught — the simulation is meant to improve every iteration
7. close    reforge-reset backup <run-name>
            (or go straight to the next run's reset, which archives too)
```

Archives: `/var/lib/forgejo-sandbox-archive/<name>-<stamp>.tar.gz`; restore
any of them with `reforge-reset restore <tarball>`.

## Autonomous mode (an agent as orchestrator)

Steps 3–5 (kickoff → rebuild → compare) can be driven by an agent itself
instead of a human rotating tabs. The **orchestrator** does the operator
job — schedule, route, judge convergence, checkpoint — and launches fresh
headless role sessions for all real work. Isolation is preserved because it
coordinates only through the forge, **by issue/PR number, never by
content**; it never reviews or implements.

```
reforge-orchestrator
# then: "Drive Phase A to completion, stopping at the A->B boundary."
```

Playbook: `agents/orchestrator.md` (seeded as the session's CLAUDE.md).
Policy: `scripts/settings/orchestrator-settings.json`.

Design properties that make this safe to let run:

- **The gate is structural, not enforced by the orchestrator.** Admin can't
  push through branch protection (verified), the orchestrator's policy
  denies `curl`/`git push`/`reset`, and the forge MCP exposes no
  branch-protection tool — so the worst a runaway orchestrator does is file
  bad issues/PRs, never merge unreviewed code to a target.
- **Merges are gated, not bypassed.** It merges via `merge_pull_request`
  only a PR already carrying a security-lead APPROVED review.
- **Sequential role turns** — one actor at a time, no forge races.
- **Auditable** — it keeps a "Run log — orchestrator" issue in charter, one
  line per scheduling/judgment call.
- **Human-stop at Phase A → B** — the one consequential, hard-to-reverse
  judgment is handed back, not taken autonomously.

Caveats, stated honestly:

- Nested headless turns cost real tokens and compound; give it a bounded
  instruction ("Phase A only") and watch the run log.
- Model non-determinism compounds across many turns: the *inputs* (pins,
  charter, agenda) are reproducible, but the *trajectory* is not. Treat each
  autonomous run as one sample — archive it, and you can compare two runs
  from identical inputs.
- For a clean "how does it do from scratch" run, restore a
  post-kickoff/pre-work archive first (reset → seed → kickoff → `backup
  run-N-kickoff-clean`), then launch the orchestrator against that.