Gate AI code changes with enforced review and human approval

ForgeGate

A control system for Claude Code. It lets AI help build software quickly, but with guardrails:
one task at a time, clear boundaries, required tests, independent review, and human approval before
anything important is committed or merged.

What is ForgeGate?

ForgeGate is a safety and project-management layer for Claude Code. Instead of asking an AI to write
code and hoping it behaves, ForgeGate turns the work into a controlled process: define the task, set the
boundaries, have the AI do the work, then require independent review, testing, and human approval before
anything important happens.

It is built for people who want the speed of AI-assisted coding without losing control. ForgeGate keeps the
AI focused on one approved task at a time, prevents it from wandering into unrelated files, records what
happened, runs the checks itself, and stops at the right gates before commits, pull requests, or merges.

In plain English: it makes Claude Code act less like a loose chatbot and more like a disciplined engineering
team - developer, reviewer, scope/safety officer, and project manager - with an approval process built in.
The goal is not just faster coding; it is trustworthy AI-assisted software development: clear scope, clean
evidence, safer changes, fewer surprises, and a human still in charge of every major decision.

The two pieces

The contract is one-directional: Claude Code consumes Forge Core, never the reverse. Core is the source
of truth; the AI surface is a convenience layer over it.

The governed loop

One ticket flows through a fixed pipeline and stops at the commit gate. Nothing is improvised, and the
orchestrator trusts Core's verdicts - never an agent's narrative.

flowchart TD
    A[Preflight: validate + dry-run + clean-tree] --> L{forge lock acquire<br/>atomic, owner-keyed}
    L -- LOCK_HELD / LOCK_MALFORMED --> X[Stop before any mutation]
    L -- acquired --> B[Emit Core-owned active-ticket fence]
    B --> C[Branch + checkpoint]
    C --> D[Engineer: TDD, edits only allowed_paths]
    D --> E[Independent verify: run the ticket's verify_commands]
    E --> F[Scope guard: diff vs the path fence]
    F --> G[Semantic verifier + Scope verifier]
    G --> H[PM: PASS / CORRECT / ESCALATE<br/>Core-pinned decision_id]
    H -- CORRECT (cap 3, lock held) --> D
    H -- PASS --> I[Ledger append -> run-report -> owner-checked release]
    H -- ESCALATE --> J[Evidence run-report -> owner-checked release]
    I --> K[Commit gate: handoff + STOP. No commit.]
    J --> Y[Recovery brief + STOP. Evidence preserved.]

Every agent output is captured verbatim and validated by Core (forge parse-agent) before the run
continues - malformed output halts, it is never repaired. The PM's decision_id is assigned by Core from
a per-epic ledger and cross-checked, so it can't be invented or duplicated. On PASS the run produces a
Core-owned, schema-validated forge-run-report/v1 whose safety fields are typed false, then stops for a
human.

Architecture

flowchart LR
    subgraph CC[Claude Code surface]
      W1[/forge-run-ticket/]
      WF[workflow-backed runner]
      CMDS[thin wrappers:<br/>validate / status / import / dry-run]
      HOOK[four-class permissions hook]
    end
    subgraph CORE[Forge Core — deterministic CLI]
      SCHEMA[schema + validate]
      ORCH[orchestrator: packets / dispatch / decision-id / lock / ledger]
      AGENTS[agent-output validate + ingest]
      GUARD[path-fence guard]
      RR[run-report v1]
    end
    W1 --> CORE
    WF --> CORE
    CMDS --> CORE
    HOOK -. governs Bash git/gh .-> W1
    HOOK -. governs Bash git/gh .-> WF

Core vs. orchestrator is the load-bearing split. Core (src/) is deterministic, typed, unit-tested
TypeScript. The orchestrators (a Markdown command and a workflow script) are the only components that dispatch
agents, run git, and pause at gates - and they own no governance logic: no gate computation, no
decision-id assignment, no schema validation, no path-fence decisions, no safety attestation. They call Core
for all of it.

Two repos, kept distinct. FORGE_REPO locates the CLI; the target repo (the project being modified)
is resolved from the Claude Code session's git root and pinned via --repo-root. They coincide only for
ForgeGate self-runs; for any other project they differ, which is what makes ForgeGate usable on external repos.

What's shipped

Everything below exists today, is unit-tested (784 tests / 45 files, green in CI), and has been exercised
through the governed loop.

Governance engine (Forge Core)

• Contract model - epic / sprint / ticket as YAML + Markdown, with strict Zod schemas at every boundary.
• validate - read-only contract integrity + readiness + auto-escalation checks. A hard precondition for execution; modifies nothing.
• run --dry-run - selects the next ready ticket and reports gate, branch, dependency reasoning, and escalation state. Read-only.
• active-ticket - emits the Core-owned forge-active-ticket/v1 fence (absolute repo_root, paths, branch) that the guard and run-report consume.
• packets / dispatch - deterministic per-role dispatch context and specs for engineer, semantic verifier, scope verifier, and PM. Registered subagent type when available; verbatim injected-charter fallback otherwise - never an improvised prompt.
• parse-agent - validates structured agent output (YAML or JSON) against the role schema. Malformed output is rejected, never repaired. With --out, Core also writes the validated canonical artifact to .forge/ itself (validate-then-write, with .forge/-segment containment) - so persistence of a role output is a Core fs write, never a generic agent stamping a verdict.
• Core-pinned decision_id - assigned monotonically from a per-epic ledger; the PM echoes it verbatim and Core cross-checks. Duplication and renumbering are structurally impossible.
• run-report write - Core-owned forge-run-report/v1. Safety fields (committed, pushed, pr_opened, merged, status_write_back, journal_written) are typed z.literal(false) - the v1 thesis lives in the type system, so it can't be flipped without a v2 bump.
• importer - normalizes a legacy sprint folder into the canonical contract; writes TODO placeholders rather than inventing ambiguous fields (a human-completion draft).
• repo snapshot - hook-free, read-only repo facts (head, branch, clean state, changed files, ahead-of-base) computed via internal git, so the workflow runner reads repo state without shelling git through the permissions hook.

Agent workflow

• One governed self-run - engineer → independent verify → scope guard → semantic verifier → scope verifier → PM, stopping at the commit gate.
• Verbatim capture protocol - one action per step: dispatch → wait → capture byte-for-byte → parse-agent → continue only on success. No pre-writing, summarizing, reconstructing, composing, or batching. Lock-tested so the discipline can't silently drift.
• Independent verification - the orchestrator re-runs the ticket's verify_commands itself; it never trusts the engineer's claim.
• Anti-theater verifiers - verdicts must cite concrete evidence; "looks good" is invalid; the PM may not PASS over a REJECT without a recorded override + human escalation.

Permissions substrate (the prevent layer)

• Four-class Claude Code permissions hook (PreToolUse, Bash) - judges every git/gh command by intent:
  • Class 1 - read-only / local git → allow (status, diff, log, show, rev-parse, branch list, fetch, pull --ff-only, switch <branch>).
  • Class 2 - explicit-path staging → allow (git add <path>; ./-A/glob denied).
  • Class 3 - reversible PR workflow → allow (git push -u origin <feature-branch>, gh pr create|view|checks).
  • Class 4 - destructive / outward / approval-gated → deny (force-push, push-to-main, reset --hard, branch delete, merge/rebase, gh pr merge, gh api mutation, restore/checkout -- <path>, clean, and any complex/dynamic/obfuscated git/gh form). Non-git/gh commands pass through. Fail-closed.
  • A forge-* runner agent is restricted to read-only git only (L3).
• Human bypass is explicit: !-prefixed commands run in the human's own shell and bypass the agent hook - that is the human gate for commit / branch-create / merge.

Cross-run concurrency (epic locking)

• Core epic-lock primitive - atomic exclusive-create (O_EXCL / wx): the create is the mutual exclusion, so there is no check-then-act TOCTOU. Typed forge-lock/v1 record keyed by run_id.
• forge lock acquire | release | status - real defaultLockIo filesystem binding; owner-checked release; report-only stale verdict (never clears or steals); malformed locks fail closed.
• forge lock break - human-gated stale-lock recovery, same-host provably-dead PID only (--confirm-run-id echo + --yes; CAS re-read before clear). A fresh/live lock can never be broken (LOCK_NOT_STALE); a TTL-only / heartbeat-only / cross-host lock is refused (LOCK_LIVENESS_UNPROVEN). Heartbeat/TTL/cross-host recovery remain future work.
• Both orchestrators are wired to it - the command runner (/forge-run-ticket) and the workflow-backed runner both acquire before any mutation, hold across correction cycles, and release owner-checked on PASS / terminal outcomes.
• Atomic / CAS decisions-ledger append - defense-in-depth: ledger appends can't duplicate or clobber decisions under concurrent interleavings, even if the lock is bypassed.

Workflow-backed runner & scratch isolation

• Two orchestrators, one lock. Alongside the Markdown /forge-run-ticket command there is a workflow-backed runner (workflows/forge-run-ticket.workflow.js), live-proven end-to-end through its own harness with real agents and a real lock. Both runners are serialized by the same epic lock.
• OS-temp scratch launch. Workflows are launched from a Forge-owned OS-temp scratch cwd via scripts/launch-workflow.mjs; a fail-closed launch-cwd gate (PREFLIGHT_LAUNCH_CWD_UNSAFE, before any mutation) makes a repo-launched workflow run impossible by design, so the harness's scratch capture can never land inside a repo.
• Crash-path owner-release. An unhandled workflow failure releases the lock owner-checked and returns a typed UNHANDLED_WORKFLOW_FAILURE (outward_action_taken: false, human_gate_required: true) - never an orphaned lock.
• Core-owned role-output persistence. The runner persists each role output through forge parse-agent <role> --json-stdin --out (Core validates, then writes), so no generic agent ever issues a verdict-stamping write. An in-context proof in the hook-less launcher substrate (3 independent runs, 0 classifier denials) confirmed the migrated path persists every role output - including the previously-blocked verifier verdict - cleanly.

Human-gated delivery

• Stops at the commit gate. On PASS it prints the handoff (changed files, verification summary, PM decision, a proposed status transition, a suggested commit message and git add/git commit) and stops. It never commits.
• No auto push / PR / merge. No status write-back. No journal write. All deliberately out of scope for v1.
• Failed runs preserve evidence - write the run-report, leave branch + tree intact, produce a recovery brief with suggested (not executed) cleanup.

CI / green-tree protection

• GitHub Actions CI on every PR and push to main - Node 22, pinned pnpm@10.33.0, frozen install → typecheck → test. The green-tree invariant is machine-backed.

Quickstart

pnpm install
pnpm build
node dist/cli.js validate docs/epics/forge-self-improvement      # read-only contract validation
node dist/cli.js run docs/epics/forge-self-improvement --dry-run  # preview the next ready ticket

The CLI subcommands are read-only and safe from a plain terminal. For the full orchestration loop, run
/forge-run-ticket <epic-path> inside Claude Code - the interactive entry point that dispatches the agents
and pauses at the commit gate.

Command reference

forge validate <epic-path> [--json]            Read-only contract validation. Default mode writes
                                               .forge/validation-report.json; --json prints JSON, writes nothing.

forge status <epic-path>                       Summarize epic id, sprint ids, ticket counts, finding totals.

forge run <epic-path> --dry-run [--json]       Read-only execution preview: next ready ticket, dependency
                                               reasoning, paths, verify commands, effective gate, proposed
                                               branch, and the agent chain that WOULD run. (Live run is the
                                               orchestrator's job, not a CLI subcommand.)

forge import --from-existing <legacy> --out <epic-root> [--dry-run] [--json]
                                               Normalize a legacy sprint folder into the canonical contract.
                                               Output dir must be empty/absent (no --force). Source untouched.

forge packets <epic-path> [--repo-root <p>]    Deterministic run-packet set for the next ready ticket.

forge dispatch <engineer|semantic-verifier|scope-verifier> <epic-path> [--repo-root <p>]
                                               Build one agent's dispatch spec {role, subagent_type, mode, prompt}.
forge dispatch pm <epic-path> [--assigned-decision-id <D-NNN>] [--engineer-output <f> --semantic-output <f>
                              --scope-output <f> --facts <f.json>] [--repo-root <p>]
                                               Re-validate upstream outputs + facts, embed them verbatim, and
                                               render the Core-pinned decision_id into the PM prompt.

forge ledger append <epic> --decision-id <D-NNN> --ticket <ticket> --branch <branch>
                                               Atomic/CAS append to the per-epic decisions ledger.

forge lock acquire <epic> --run-id <id> --session-id <s> --ticket <t> --branch <b> --repo-root <r>
forge lock release <epic> --run-id <id>
forge lock status  <epic> [--heartbeat-ttl-ms <n>] [--acquire-ttl-ms <n>]
                                               Cross-run epic lock. Acquire = atomic exclusive-create
                                               (LOCK_HELD on collision, never overwrites). Release = owner-checked
                                               by run_id (LOCK_FOREIGN/LOCK_ABSENT). Status = report-only stale
                                               verdict (never clears or steals). Fail-closed throughout.

forge parse-agent <role> (--file <p> | --stdin | --json-file <p> | --json-stdin) [--expected-decision-id <D-NNN>]
                                               Validate structured agent output against the role schema.
forge agent-schema <role>                      Emit the JSON Schema for a role's structured output.

forge active-ticket <epic-path> [--json] [--repo-root <p>]
                                               Emit the Core-owned forge-active-ticket/v1 fence.

forge guard paths [--active <active-ticket.json>] [--json] [--repo-root <p>]
                                               Deterministic, read-only check that the worktree stays inside the
                                               active ticket's fence. Exit 0 inside, 1 on violation, 2 usage.

forge run-report write <epic-path> --repo-root <p> --result PASS|ESCALATE --ticket-title <s>
                       --checkpoint-base <sha> --checkpoint-head <sha> --guard-result <s> --guard-exit <n>
                       --gate-declared <g> --gate-effective <g> --gate-human-required <true|false> [...]
                                               Write the Core-owned forge-run-report/v1 (safety fields typed false).

forge verify-install                           Read-only install-currency check: compare this checkout's
                                               commands/ + agents/ against the installed copies under ~/.claude.

The v1 safety model

Forge v1 is intentionally conservative and human-gated. The guarantees:

• One ticket per run. Exactly one ready ticket is selected and run.
• Stops at the commit gate. It never commits, pushes, opens a PR, or merges.
• No status write-back, no journal write. A run never mutates the contract's ticket status or JOURNAL.md/DECISIONS.md. (Completed tickets may still read status: pending on disk - expected for now; trust git/PRs for ground truth.)
• The engineer edits only allowed_paths. The diff is independently scope-checked against the fence.
• .forge/ runtime artifacts are gitignored (active-ticket.json, lock.json, run-report.json, decisions-ledger.json, captured agent outputs, reports).
• Cross-run serialization by epic lock. A second run on the same epic fails closed at the atomic acquire, before any mutation.
• Failed runs preserve evidence and leave the tree intact.

How "safe" is enforced - be precise

ForgeGate's safety comes from distinct layers, and it's worth knowing which prevents vs. which detects:

The honest one-liner: Core attests, the guard detects, the permissions hook prevents, and the human approves.
No layer here claims full autonomy or unsupervised readiness.

⚠️ Operator safety: Claude Code safe mode

The "prevents" layer above is a Claude Code customization, and safe mode can disable it. Launching Claude Code
with --safe-mode (or with CLAUDE_CODE_SAFE_MODE set) can disable customizations - including the permissions
hook - so a governed ForgeGate run started from a safe-mode session can silently lose the mechanical prevent
layer.

Operator rule: do not run /forge-run-ticket or a governed Forge workflow from a safe-mode session. If safe
mode is enabled, exit and relaunch Claude Code normally before running ForgeGate orchestration. This is
documentation only - automated detection is deferred. See
docs/claude-code-safe-mode-operator-note.md.

Not autonomous / not magic

Forge structures Claude Code work and enforces discipline; it does not take over responsibility. The
human stays accountable for what gets committed, pushed, or merged. v1 always stops at the commit gate.

Cross-run concurrency & locking

Two runs on the same epic must not both proceed - they would race on the decisions ledger and overwrite each
other's evidence. ForgeGate closes this with a Core-owned epic lock:

• Acquire is the gate. forge lock acquire atomically creates <epic>/.forge/lock.json (O_EXCL/wx).
  The create is the mutual exclusion - there is no separate existence check, so no check-then-act window. A
  collision returns LOCK_HELD and never overwrites the holder.
• Release is owner-checked. Only the run that holds the matching run_id can release; a foreign/absent/
  malformed result is reported, never force-cleared.
• Both orchestrators are serialized by it - the command runner and the workflow-backed runner acquire
  before any mutation (active-ticket emission, checkpoint, dispatch), hold across all correction cycles, and
  release on PASS or terminal outcome.
• The CAS ledger append is defense-in-depth - even if the lock were bypassed, a decision can't be
  duplicated or clobbered. With both runners holding the lock, this backstop sits behind real primary
  serialization.
• Stale recovery is human-gated. forge lock status reports a stale/foreign/malformed verdict but never
  clears, breaks, or steals. forge lock break adds a deliberate, human-gated recovery path for a same-host,
  provably-dead PID holder only (--confirm-run-id echo + --yes, CAS re-read before clear); a live lock can
  never be broken. Heartbeat/TTL/cross-host recovery remains future work.

Honest status: both runners are wired to the lock and live-proven - the command runner and the
workflow-backed runner have each exercised real acquire/release end-to-end through their own harness with real
agents. The remaining concurrency work (evidence-ownership / run_id, worktree / shared-state) is on the roadmap.

Install & setup

ForgeGate is installed from a checkout - there is no published package yet. Both setup lanes end with a
verify-install currency check; the install is "done" only once the installed ~/.claude copies are
confirmed current.

# Clone (or pull an existing checkout), then:
pnpm install
pnpm build                          # emit dist/
pnpm install-commands               # commands/*.md → ~/.claude/commands/, agents/*.md → ~/.claude/agents/
node dist/cli.js verify-install     # confirm installed copies match this checkout (exit 0 = current)
export FORGE_REPO=$(pwd)            # PowerShell: setx FORGE_REPO "<path>"

If verify-install reports any file stale/missing, re-run pnpm install-commands then re-check. See
docs/adopting-forgegate-in-a-project.md for using ForgeGate
against an external repo.

CLI resolution. Each wrapper invokes node "${FORGE_REPO}/scripts/run-forge-cli.mjs" <subcommand>, which
resolves the CLI as: $FORGE_BIN → forge on PATH → local-dev pnpm -C <repo> forge. Set FORGE_REPO
(or pnpm link --global) so the wrappers can find the CLI. FORGE_REPO only locates the CLI - it is never
the project a ticket modifies.

Develop

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm forge validate <epic-path>             # dev run via tsx
node dist/cli.js validate <epic-path>       # built binary

Workflow runs: the OS-temp scratch launch (operator procedure)

The Claude Code harness's Bash output-capture wrapper writes TEMP*_out / TEMP*_err scratch pairs into the
subagent process cwd - the directory the claude session was started from - below charter and workflow
command-shape control (a charter rule alone was live-proven insufficient). The enforceable, live-proven
prevention is launch-cwd placement: ForgeGate workflow runs are launched from a Forge-owned scratch
directory under the OS temp root, so harness scratch can only ever land somewhere ForgeGate owns and later
deletes. Starting the session elsewhere and cd-ing later is proven ineffective - the session cwd is
immutable mid-session, and Agent/Workflow subagents anchor to the launch cwd.

Two layers make this real:

• Launcher (operational): scripts/launch-workflow.mjs creates the per-run scratch cwd, mints
  runId/sessionId, runs the pre/post TEMP* scans, writes gitignored evidence, and cleans up only its own
  scratch. It never launches Claude and never shells git (repo facts come from forge repo snapshot via the
  CLI resolver).
• Workflow gate (enforcement, strict): workflows/forge-run-ticket.workflow.js requires the
  launcher-declared scratchCwd expectation in args and verifies the observed launch cwd through a non-git
  bridge probe before checkpoint, lock acquire, branch use, active-ticket emission, or any mutation. An
  unsafe (or unverifiable) launch escalates the dedicated typed code PREFLIGHT_LAUNCH_CWD_UNSAFE with
  outward_action_taken: false - no lock is acquired and nothing is written. By design this makes a ForgeGate
  workflow run launched from inside a repo working tree impossible.

Procedure

# 1. Prepare (from your normal shell, any cwd): creates the per-run scratch dir under the OS temp
#    root, mints run identity, runs the PRE-run TEMP* scan (session repo + target repo + scratch),
#    and writes gitignored evidence (the scratch dir + <session-repo>/.forge/launch-evidence/).
node <forge-checkout>/scripts/launch-workflow.mjs prepare \
  --session-repo <abs-forge-checkout> --target-repo <abs-target-repo> --epic <abs-epic-path>

# 2. Launch: open a NEW terminal, cd INTO the printed scratch dir, and start `claude` FROM it.
#    This placement IS the prevention.

# 3. Run: in that session, invoke the Workflow tool on
#    <forge-checkout>/workflows/forge-run-ticket.workflow.js with EXACTLY the emitted
#    workflow_args JSON (repoRoot / epic / forgeBin / runId / sessionId / scratchCwd).

# 4. Post-run scan: re-scan the same three locations and record the result in the evidence.
node <forge-checkout>/scripts/launch-workflow.mjs post-scan --session-repo <abs-forge-checkout> --run-id <runId>

# 5. Cleanup (hygiene only): removes ONLY the Forge-owned scratch dir. The prevention claim is
#    launch-cwd placement (step 2) — never this removal.
node <forge-checkout>/scripts/launch-workflow.mjs cleanup --session-repo <abs-forge-checkout> --run-id <runId>

Windows path behavior. The scratch dir resolves under %TEMP% (e.g.
C:\Users\<you>\AppData\Local\Temp\forge-launch-<runId>); all emitted paths are absolute, realpath-resolved,
and forward-slash normalized; the workflow's launch-cwd comparison is Windows-aware (separator and case
normalization), so C:\Users\… and c:/users/… compare equal. POSIX temp roots ($TMPDIR, /tmp) are
handled the same way.

Verdict depth. A run used as a scratch-placement verdict must reach the guard + agent-schema bridge
stages; a preflight-only run is INCONCLUSIVE (the scratch producer is the agent output-capture wrapper,
which a preflight-only run barely exercises).

Hook posture. A scratch-launched session does not load ForgeGate's project-local permissions hook
(hooks load from the launch directory). Such sessions are restricted to launch-and-prove actions only: no
outward git/gh actions, no source edits - and no outward action of any kind without explicit human approval.

Agent charters

The Forge roles are Claude Code subagent charters in agents/ (installed to ~/.claude/agents/). They declare
the human/agent contract: role, inputs, governance to read, hard prohibitions, a structured output schema,
escalation behavior, and anti-theater rules.

Dispatch model. When the harness exposes registered forge-<role> subagent types, dispatch uses them
directly (mode: registered). Otherwise it falls back to the general-purpose agent with the tracked charter
injected verbatim (mode: injected-charter) - never an improvised prompt. Either way the prompt pins
repo_root and cwd discipline.

Roadmap

Sequenced roughly by priority. Nothing here is committed; it's the honest "what's next."

Near-term - finish the concurrency story

• Stale-lock recovery beyond v1 - forge lock break already recovers a same-host, provably-dead PID holder; a heartbeat updater (to make heartbeat_ts live), then TTL-only and cross-host recovery, are the remaining steps.
• Evidence ownership / run_id enforcement - tie active-ticket, run-report, orchestrator-facts, and captured evidence to the owning run.
• Worktree / shared-state architecture - prevent per-worktree .forge state from fragmenting shared lock/ledger provenance.

Delivery & automation

• Sentinel-gated gh pr merge - an approval-file-gated merge path in its own ticket (deferred follow-up).
• Command/workflow parity review - keep the two runners behaviourally aligned as each evolves.

Adoption & operations

• External-repo pilot sequence once concurrency is fully closed.
• Operator guides - permissions-hook behavior; "how to recover from lock held / malformed / stale" (after stale UX exists).
• Install/update lifecycle for commands, agents, and (if they become installable) workflows.

Developer experience

• Escalation keyword matcher - make it negation-aware so harmless prose ("do not delete X") doesn't trip auto-escalation.
• Tighter protocol tests where command/workflow behavior lives in Markdown or workflow JS.
• Reduce friction around hook-denied-but-safe operations without weakening the safety model.
• Continue adopting Claude Code primitives (subagents, skills, hooks, permissions, typed workflow schemas) only where they measurably improve safety - MCP / Agent SDK only if they add controlled, deterministic value, not novelty.

Explicitly out of scope for v1

Full autonomy, auto-commit/push/PR/merge, status write-back, journal automation, multi-ticket loops, and any
orchestrator autonomy without explicit human approval. Each needs a deliberate scope discussion before it
becomes real.

Design docs

The reasoning behind the system lives in docs/. Key entry points:

• one-ticket-orchestration-design.md - the core orchestration design.
• forge-run-ticket-design.md - the interactive command runner.
• path-fence-guard.md - the deterministic scope guard + example git hook.
• cross-run-concurrency-discovery.md - the locking/ledger trust seam.
• workflow-backed-runner-design.md · workflow-era-architecture-audit.md - the workflow runner and how it relates to the command runner.
• permissions-policy-discovery.md - the four-class permissions model.
• adopting-forgegate-in-a-project.md - running ForgeGate against an external repo.

Epic contracts (the system dogfooding itself) live under docs/epics/.

Principles

• The core is real, typed, unit-tested code - never prompt logic.
• forge validate is a hard, read-only precondition for any execution.
• One responsibility per module (schema, validate/*, orchestrator/*, guard, run-report, cli).
• Schemas at trust boundaries; types inside. Determinism is sacred - Core never invents metadata, repairs agent output, or auto-commits.
• Honest over impressive: an ESCALATE with preserved evidence beats a forced green. The README does not overclaim, by design.