---
name: forge
description: |
Conditional discipline for projects hosted on a git forge (GitHub,
GitLab, Forgejo, …): branch↔PR mapping, self-contained PR prose,
review-on-forge, merge consent, and the forge audit.
Trigger when:
- Opening, updating, reviewing, or merging a pull/merge request.
- A campaign's integration branch is ready to surface on a forge.
- Auditing forge-side presence at merge-consent or campaign CLOSE.
- Prompt contains: /forge, pull request, PR body, merge request,
forge discipline, PR review, stacked PR.
---
# Forge Discipline
**Applicability is conditional.** Some projects have no forge — a bare
remote, a patch workflow, or no remote at all — and nothing here applies
to them; absence of a forge is never a violation. **When the project has
a forge, this discipline applies in full.** The test is mechanical: does
the origin remote resolve to a forge the project accepts contributions
through?
## Philosophy: the forge is the public half of the record
The flight recorder (`.ledger/`) is the *internal* durable record; the
forge is the *external* one — the only record most future readers will
ever see. The two have different audiences and MUST NOT leak into each
other: the recorder may reference forge artifacts (they are public,
permanent URLs); forge prose MUST NEVER reference process-internal
state. A PR body that cites `.scratch/`, `.ledger/`, a session link, or
a working note is broken for every reader outside the process that
wrote it — and those are all of its readers.
## 0. Tooling: MCP for forge operations, git for merges
Forge **operations** — opening/updating PRs, posting comments and
reviews, reading state — prefer the forge's **MCP server** where the
session has one connected: structured, typed calls over stringly CLI
output. The CLI (`gh`, `glab`, …) is the fallback, and plain git+HTTPS
the primitive beneath both (degrade-to-the-primitive applies: never
depend on the MCP being present). The one hard exception runs the other
way: **merges are always the git CLI** (§4, MERGE_IN_GIT) — no MCP or
API merge endpoint, ever.
## 1. Branch ↔ PR mapping
Two PR tiers, one campaign:
- **Per-node PRs.** Each finished node branch surfaces as a PR targeting
the campaign's shared integration branch — that PR is the node's
review record (findings, triage, the merge-consent trace). The merge
itself still happens in git (§4); pushing the merged shared branch is
what closes the PR.
- **One tracking PR per campaign.** The `campaign/<TOPIC>` integration
branch surfaces as a single PR against the default branch; independent
workstreams get independent branches and PRs, never one omnibus. Its
body is the campaign checklist (§2).
- **The bootstrap order is forced by the forge — follow it, never fight
it.** A PR cannot exist until its branch differs from its base, so:
1. At campaign setup, create the shared integration branch from the
baseline and PUSH it (covered by the campaign's recorded push
authorization — preflight it with the rest). Open NO PR yet.
2. When the FIRST node finishes, push its node branch and open the
first node PR, targeting the shared branch.
3. After that node's consented merge lands on the shared branch and is
pushed, the shared branch has content: NOW open the tracking PR
(draft) with its checklist body, the first item already checked.
4. Every later node repeats the rhythm of (2)–(3): node PR → consented
merge → its checklist item checked.
Opening the tracking PR at campaign start — before anything exists to
merge — is the recurring field failure this sequence exists to kill.
- **Stacked PRs** are permitted for dependent work: base each PR on its
prerequisite's branch. Know the forge's mechanics: when a base branch
merges and is deleted, the dependent PR retargets (or auto-closes as
"closed", not "merged") — when the forge misclassifies, annotate the
PR with the merge commit so the record reads correctly.
- Merged branches are deleted; the PR is the durable pointer.
## 2. PR prose — self-contained, or broken
- **The audience model, stated positively:** the forge reader is a
potential reviewer of the CODE, with zero knowledge of — and zero
interest in — how the work was produced. Exactly two questions
matter: *what is this work?* and *how do I review it?* Every sentence
must serve one of the two, and the test is applied sentence by
sentence, not file by file.
- What serves: a summary; what changed and why in terms of the
repository's own behavior and goals; DESIGN decisions with their
grounds (why this approach — never process decisions about who
approved what); what is deliberately out of scope; honest
verification status as facts about the repository (what was run, the
actual results, what wasn't run); known risks and tradeoffs.
- **The production process is never content — relevance, not secrecy.**
Councils, seats, reviewers-as-cast, campaigns, nodes, layers,
reconcile rounds, dispatch mechanics: none of it helps a reader
review the change, so none of it appears — token-free *narrative*
about the process fails the two-question test just as hard as a
leaked ID. Campaign-scale context is carried by a plain link to the
meta tracking issue (§6), never by narrative.
- **Formatting is mechanical fact, not taste:** GitHub renders single
newlines in PR/issue bodies as hard line breaks, so manually wrapped
prose renders as a staccato mess. Forge prose is SOFT-WRAPPED — one
paragraph is one logical line, blank lines separate paragraphs, and
visual structure comes from markdown (headings, lists, fences), never
from manual breaks.
- **Zero process-internal references**: no `.scratch/`, no `.ledger/`,
no sketch or session links, no "as discussed" — and no campaign-
internal identifiers (node or finding tokens): to every reader outside
the process they are dangling labels. Where context is load-bearing,
use **permalinks pinned to a commit SHA** — branch-relative links rot
when branches are deleted.
- The check is mechanical, not a memory: draft forge prose (PR bodies,
issue bodies, review summaries) in a scratch file and run
`gates/check_forge_prose.sh --files <draft>` over it before posting —
internal IDs, the process-vocabulary scan (advisory-with-override:
rewrite the sentence in substance terms, or narrow `FORGE_VOCAB_PAT`
in `.ledger/config.sh` for a genuine per-project collision), and the
hard-wrap lint, in one pass.
- **The tracking PR's body is a checklist.** After its summary prose,
one item per node PR, in schedule order, checked as each merges:
`- [x] #<node-PR-number> — <what it landed, in repository terms>`.
On GitHub use the bare `#N` reference — the forge renders the PR's
live title and state natively; on other forges use their native
reference syntax, a plain link as the primitive. Item text obeys the
same self-containment rule as everything else: describe the landing
in repository terms, never by campaign-internal node tokens.
- Verification claims in PR prose follow the same honesty rules as
commit messages: state what evaluators ran and their actual results;
never imply coverage that does not exist.
## 3. Review on the forge
Decorrelated review findings and their triage belong ON the PR, as
comments — the forge is where the review record survives:
- When adversarial or council review produces findings, post them **as
substance, in impersonal voice** — what was found in the code and its
disposition: confirmed-and-fixed (with the commit), refuted (with
grounds), deferred (with its follow-up home) — as PR comments.
"Review found X; fixed in `<sha>`" — never a cast of process actors;
the record is the finding, not the machinery that produced it.
- The triage comment is part of the merge record: a PR that merged
after review with no visible trace of that review under-documents
the merge.
## 4. Merge consent
- A PR merges only on the head's say-so, carried through the
lead-maintainer seat's affirmative merge-consent where the council is
seated ([campaign §RECONCILE](../campaign/SKILL.md)). Green checks
and approving reviews are necessary, never sufficient.
- **Merge in git; the forge observes.** Merges are performed with the
git CLI — locally, with the strategy the history actually calls for:
fast-forward when clean, an octopus when many nodes land together, a
merge commit where the narrative warrants one — then pushed; the
forge detects the merge and closes the PR itself. The forge's merge
API/button is NEVER the default: it constrains strategy to its own
shapes (squash/rebase/single-merge), manufactures commits outside the
commit gate's hygiene, and adds nothing the CLI lacks. After a CLI
merge, verify the PR state and annotate if the forge misclassified it
(closed-not-merged).
- Agents never push to protected/default branches without the head's
explicit instruction (rules.md §3 applies unchanged on forges).
- **Preflight the authorized landing.** The final head-authorized push of
an integration branch onto a long-lived default branch is a foreseeable
campaign step: ensure at campaign setup that the permission environment
allows it. If a classifier blocks it anyway, surface the block to the
head as an environment gap — the merge is never rerouted through the
forge's merge API to satisfy a classifier (MERGE_IN_GIT holds).
## 5. The forge audit
A checklist, not a ceremony — owned by the **composer**, run at two
points: alongside each merge-consent, and over the campaign's whole
forge surface at council CLOSE. The forge is the campaign's outward
communication, and communication is conducting: the composer authors
the forge surface, so the composer answers for it. The
lead-maintainer's gate is the CODE and its maintenance burden — his
attention stays on the diff, and routing this audit to him dilutes
the one review only he can give. The composer MAY delegate the
reading to a dedicated read-only reviewer when the surface is large;
the verdict and the fixes remain the composer's.
- [ ] PR prose still accurate against the *final* state of the branch
(late commits silently invalidate early summaries).
- [ ] Self-containment holds: zero process-internal references
anywhere in bodies or comments; permalinks pinned to SHAs.
- [ ] The two-question test holds sentence by sentence: everything
serves "what is this work" or "how do I review it" — no
production-process narrative, however token-free.
- [ ] `check_forge_prose.sh` passes over every body and comment
drafted this round (IDs, vocabulary, hard wraps).
- [ ] The review record is present: findings + triage visible on the
PR for every review that gated the merge.
- [ ] Forge state matches reality: merged PRs show merged (or carry
the correcting annotation); stale branches deleted; stacked PRs
correctly retargeted.
- [ ] The PR set partitions the work meaningfully — a reader can
navigate the campaign from the forge alone.
- [ ] The tracking-issue record is whole (§6): the meta issue exists,
every out-of-scope finding has its own linked issue, and every
issue body reads self-contained.
- [ ] Issue tagging holds (§7): labels follow the project's established
scheme (or the minimal logical one where none exists), and every
security-critical / correctness-critical issue carries its
criticality tag.
## 6. Campaign tracking issues
Out-of-scope findings are work the campaign discovered but will not do —
and undocumented, they evaporate with the campaign's scratch. The forge
is their durable home:
- **One meta tracking issue per campaign**, opened at campaign kickoff
alongside the tracking PR. It is the campaign's out-of-scope index —
a reader finds every deferred thread from this one issue.
- **One issue per out-of-scope finding**, opened when the finding is
classified out of scope (at a reconcile boundary or at CLOSE), written
self-contained per §2 — the finding's substance in repository terms,
never its campaign-internal ID.
- **Link them**: sub-issues of the meta issue where the forge supports
them (GitHub), plain cross-links otherwise. An unlinked issue is
filed, not indexed.
- At CLOSE, every `ACCEPTED_RISK` disposition names its issue — the
audit (§5) checks the record is whole. Acceptance without an issue is
a silent drop wearing a disposition.
## 7. Issue tagging
Labels are navigation for a future triager, not decoration — where the
forge supports them, every issue an agent opens is tagged, and the
scheme is discovered before it is invented:
- **The project's convention wins.** Before opening the first issue,
read the project's existing label set and how recent issues actually
use it (list the labels; sample a few triaged issues). An established
scheme is followed exactly — inventing a parallel taxonomy alongside a
live one is worse than no tags at all.
- **No convention → a minimal logical scheme.** Where the project has no
established usage, apply reasonable, legible tags and stay minimal:
the issue's type (bug / enhancement / documentation), its criticality
where it has one, and the component only when the project's structure
makes it obvious. A tag whose meaning a stranger cannot guess from its
name does not ship.
- **Criticality tags are MANDATORY where they apply.** An issue tracking
a security-critical or correctness-critical finding carries that tag
(`security-critical` / `correctness-critical`, or the project's
established equivalents) whenever it is opened — including every
out-of-scope finding deferred to an issue under §6. An untagged
critical issue is a mis-filed risk: it will be triaged as routine by
whoever reads the tracker next.
- **No label support → degrade to the primitive.** Where the forge lacks
labels, carry the criticality in the issue title prefix (e.g.
`[security-critical] …`) so the signal survives the missing feature.
## Prime Directives
1. **CONDITIONAL_APPLICABILITY:** No forge, no obligation. A forge,
full obligation.
2. **SELF_CONTAINED_PROSE:** Nothing process-internal ever reaches the
forge. Permalinks over lore; SHAs over branch links.
3. **REVIEW_ON_RECORD:** Reviews that gated a merge are visible on the
PR that merged.
4. **CONSENT_TO_MERGE:** Merge is a sovereignty act — the head's (via
the lead-maintainer seat where seated), never an agent's default.
5. **MERGE_IN_GIT:** Merges happen in the git CLI, then push; the forge
observes and records — it does not perform. The merge API is not an
instrument.
6. **TRACKED_OUT_OF_SCOPE:** Every out-of-scope finding gets its own
self-contained issue, linked from the campaign's meta tracking
issue. Deferral is a routing decision with a durable address, never
a silent drop.
