feat: extract reforge engine into a standalone consumable flake

The forgejo-sandbox / reforge harness, lifted out of the machine config
into a host-agnostic, generic engine anyone can consume with Nix.

Two layers:
- engine (this repo) — nixosModules.reforge stands up the sandbox forge,
  provisions role accounts + tokens, enforces branch protection, and puts
  the reforge-* CLI + forgejo-mcp on PATH. Carries no project specifics.
- run config — per-project manifest/charter/agenda/issues an adopter fills
  in; scaffold one with the `reforge` flake template.

Portability fixes vs the in-config version:
- forgejo-mcp resolved from $REFORGE_MCP_BIN or PATH, never a named host
  (kills the nixosConfigurations.omni hardcode).
- all instance data + paths parameterized via REFORGE_* env, baked into the
  reforge-scripts wrappers from module options (configDir, agentsDir,
  refsDir, org, port, tokenOwner, ...).
- option namespace neutral (reforge.* not omni.packs.*); settings policies
  carry no absolute /etc/nixos paths.
- role briefs + orchestrator playbook genericized: all project specifics
  point at the charter; refs corpus optional.

Validated: nix flake check (eval) + builds of forgejo-mcp, reforge-scripts,
and a module-eval check.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

templates/reforge/README.md

@@ -0,0 +1,33 @@
+# A reforge run
+
+This directory is one reforge run's configuration. Edit the four data files,
+wire the module into a NixOS host, and drive the run. See the engine's
+`docs/reforge.md` for the full concept and lifecycle.
+
+## The four files you edit
+
+| File | What it is |
+|---|---|
+| `manifest.txt` | The repo set: pinned bases (`fork`) + placeholders (`original`), and each repo's declared target for the acceptance diff. |
+| `charter.md` | The standard every change is judged against. Seeded as `charter/README.md`; reviews cite it. |
+| `agenda.md` | What this run must address, in item-id'd groups. |
+| `issues.tsv` | The agenda as `repo\|title\|body` rows — filed as issues by `reforge-kickoff`. Keep in sync with `agenda.md`. |
+
+## Wire it up
+
+1. Edit `flake.nix`: set `tokenOwner`, point `reforge.url` at the engine.
+2. Add the module to your NixOS host: `imports = [ inputs.myreforge.nixosModules.default ];`
+3. `nixos-rebuild switch` — you now have the sandbox forge on
+   `http://localhost:3030`, provisioned role accounts, and the `reforge-*`
+   CLI on PATH.
+
+## Drive a run
+
+```bash
+reforge-smoke        # verify the toolchain + gates after a (re)build
+reforge-seed         # create repos from the manifest, seed the charter
+reforge-kickoff      # file the agenda as issues
+reforge-role security-lead     # one terminal per role …
+# or let one agent drive the whole thing:
+reforge-orchestrator           # then: "Drive Phase A to completion."
+```

templates/reforge/agenda.md

@@ -0,0 +1,32 @@
+# Run agenda — <run name>
+
+Everything this particular run must address. Group items and give each a
+short id (`A1`, `B2`, …) so issues and reviews can trace back to it. The
+machine-readable twin of this file is `issues.tsv` (what `reforge-kickoff`
+files as issues) — keep the two in sync.
+
+## A. Production-readiness
+
+- **A1** — Security audit per repo (auth, key custody, secrets, injection).
+- **A2** — Bug hunt on the critical paths.
+- **A3** — Refactor opportunities that are cheap now, expensive after
+  release (strict-from-the-start — no compatibility shims pre-launch).
+- **A4** — Test-coverage review against the charter's test harness.
+- **A5** — Synthesize `GAMEPLAN.md`: what stands between this stack and
+  production-ready, ordered, with owners. (PR into the charter repo.)
+
+## B. <project-specific arc>
+
+- *e.g. an architectural evolution the run should evaluate and stage as
+  tracked divergences in Phase B.*
+
+## C. Coherence
+
+- **C1** — Map every inter-component contract (who calls whom, over what).
+- **C2** — Check each contract against the charter's boundary principles.
+
+## Outputs (deliverables of the run)
+
+- Issues traceable to these agenda items.
+- Reviews on every PR (security + charter, plus any project lens).
+- `GAMEPLAN.md` PR'd into the charter repo.

templates/reforge/charter.md

@@ -0,0 +1,45 @@
+# Charter — <your project>
+
+This is the standard every change in the run is judged against. It is seeded
+into the forge as `@ORG@/charter` (README.md) and every review should cite
+it. Fill in the sections below; delete the guidance italics.
+
+## Mission
+
+*What is this stack, and what is the run trying to achieve? One paragraph.*
+
+## Principles (what "aligned" means)
+
+*The rules a change must respect — architecture, dependencies, boundaries,
+security posture, self-hostability, protocol choices, licensing. The
+`reviewer` role enforces these as the "charter gate", so be concrete: a
+principle a reviewer can't check is decoration.*
+
+- *e.g. No closed/hosted control-plane dependencies — everything must be
+  self-hostable.*
+- *e.g. Prefer a standard wire protocol over private in-process coupling
+  between components that might not always be colocated.*
+- *e.g. Secrets never land in code or config; demo/test gates must never be
+  reachable in a production posture.*
+
+## Intent docs (Phase A sources)
+
+*In Phase A the target repos are off-limits — roles work from recorded
+intent. List the docs that intent lives in (roadmaps, ADRs, vision notes)
+and where to find them. If a reference corpus is available, say so and note
+that its path is in `$REFORGE_REFS_DIR`.*
+
+## Test harness
+
+*How does a role run tests inside the sandbox? Name the commands, any local
+services, and what needs the human to arrange (real infra a role can't
+reach).*
+
+## Review lenses
+
+- **security-lead** — the merge gate. *List the stack-specific hotspots to
+  threat-model and the demo/env gates that must never reach production.*
+- **reviewer** — quality + charter alignment (this document).
+- *Add project-specific reviewer roles here (e.g. a protocol-conformance
+  lens). For each: add its brief as `<role>.md` in your agents dir, add its
+  username to `reforge.roles`, and describe its lens here.*

templates/reforge/flake.nix

@@ -0,0 +1,51 @@
+{
+  description = "A reforge run configuration (manifest + charter + agenda), wiring the reforge engine as a NixOS module.";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+    # The reforge engine. Point this at wherever the engine lives — the
+    # aiolabs Forgejo by default; a GitHub mirror works the same way.
+    reforge.url = "git+https://git.atitlan.io/aiolabs/claude-forgejo-sandbox";
+    reforge.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs =
+    { self, nixpkgs, reforge }:
+    {
+      # Import this module into your NixOS host's module list. It turns on
+      # the sandbox forge and points it at THIS directory as the run config
+      # (manifest.txt / charter.md / agenda.md / issues.tsv live here).
+      #
+      #   # in your host config:
+      #   imports = [ inputs.myreforge.nixosModules.default ];
+      #
+      # Then `nixos-rebuild switch`, and you get the reforge-* CLI on PATH.
+      # See the engine's docs/reforge.md for the run lifecycle.
+      nixosModules.default =
+        { ... }:
+        {
+          imports = [ reforge.nixosModules.reforge ];
+
+          reforge = {
+            enable = true;
+            configDir = ./.;
+
+            # The local account that owns the generated token files and
+            # launches the per-role agent sessions. CHANGE THIS.
+            tokenOwner = "youruser";
+
+            # Roles to provision (one agent session each). There must be a
+            # brief <agentsDir>/<role>.md for every role here.
+            # roles = [ "backend-dev" "frontend-dev" "security-lead" "reviewer" ];
+
+            # Uncomment to customize the role briefs / orchestrator playbook
+            # instead of using the engine's generic ones:
+            # agentsDir = ./agents;
+
+            # Optional read-only reference corpus agents may cite:
+            # refsDir = "/home/youruser/refs";
+          };
+        };
+    };
+}

templates/reforge/issues.tsv

@@ -0,0 +1,10 @@
+# Agenda-as-issues — filed by reforge-kickoff into the sandbox repos.
+#   repo|title|body
+# ('#' and blank lines ignored; body is single-line markdown). Titles should
+# carry the agenda item id for traceability. `repo` must exist in the forge
+# (charter, the working repo, or a manifest repo).
+#
+# ── EXAMPLE ROWS (replace with your agenda) ───────────────────────────
+charter|[A5] Synthesize GAMEPLAN.md|Collect the release criteria emerging from the A1-A4 issues across all repos and synthesize the run's game plan: what stands between this stack and production-ready, ordered, with owners. Deliverable: a PR adding GAMEPLAN.md to this repo. Phase A rules apply.
+hello|[A1] Security audit at the seeded base|Audit the seeded base for the usual hotspots (auth, secrets, input handling, dependencies). File findings as sub-issues or a checklist here. Phase A rules apply: work from recorded intent; the target repo is off-limits.
+myapp|[scaffold] Rebuild from recorded intent|Phase A epic: scaffold this component per the charter + agenda. Break into sub-issues before implementing. Phase A rules apply.

templates/reforge/manifest.txt

@@ -0,0 +1,25 @@
+# Reforge run manifest — read by reforge-seed and reforge-compare.
+#
+#   name|kind|upstream|base_ref|target_url|target_ref
+#
+# kind      fork     = sandbox repo seeded from `upstream` at `base_ref`
+#           original = empty placeholder repo (your own software)
+# base_ref  branch, tag, or commit SHA of the upstream to seed as `main`.
+#           "auto" = upstream default-branch tip — convenient for exploring,
+#           NOT reproducible: pin every fork before a real run.
+# target_*  the known working state (real repo + branch) the run must
+#           reproduce byte-for-byte. NEVER pushed into the sandbox — only
+#           reforge-compare reads it, and reforge-fetch-targets mirrors it
+#           for Phase B. "-" = not declared (compare skips the repo).
+#
+# Changing base_ref does not re-seed an existing repo (seeding is
+# skip-if-pushed) — reset the sandbox first (reforge-reset reset).
+#
+# ── EXAMPLE ROWS (replace with your stack) ────────────────────────────
+# A fork seeded from a pinned upstream commit, no target declared yet:
+hello|fork|https://github.com/octocat/Hello-World|7fd1a60b01f91b314f59955a4e4d4e80d8edf11d|-|-
+
+# Your own software: an empty placeholder to rebuild from recorded intent.
+# Declare a target once you have a known-working branch to converge to:
+myapp|original|-|-|-|-
+# myapp|original|-|-|git@github.com:you/myapp|main