| name | fg-merge |
| description | Integrates a merged branch's forge content (.forge/branch/<branch>/) into .forge/. Two modes: `fg-merge` (no arg) integrates only; `fg-merge <branch>` also runs `git merge <branch>` for you first, then integrates (default branch only; on conflict it stops, leaving the conflict in place). A deterministic script (forge-merge.sh/.js) does the git-free integration — usable AI-free in CI. Use in contexts like 'forge merge', 'fg-merge <branch>', '브랜치 통합', '브랜치 forge 합쳐줘', '머지하고 통합'. |
fg-merge — integrate a branch's forge content into .forge/ (outside the loop)
This is not a stage of the forge loop. It is the integration step for branch isolation (ADR-0011): when a feature branch has been run with its forge state under .forge/branch/<branch>/ (a git-tracked, namespaced mini-root — see ${CLAUDE_PLUGIN_ROOT}/skills/fg-run/FORGE-ROOT.md), fg-merge folds that branch's permanent forge docs into the default-branch .forge/.
Language: This skill file is authored in English, but you MUST write every message shown to the user — questions, menus, status/next-step lines, and handoff text — in the user's language (detect it from the user's own messages), never mirroring this file's English. The integration summary and any conflict question are written in the user's language.
Two modes: integrate-only vs. merge-and-integrate
fg-merge has two modes, chosen by whether you pass a branch argument (ADR 260717-10a):
fg-merge (no argument) — integrate only. The default-branch .forge/ already has the branch root .forge/branch/<branch>/ present (you ran git merge <branch> yourself, or CI did). fg-merge just integrates it. This is the original behavior, and the only mode CI uses.fg-merge <branch> — merge, then integrate. For convenience, the skill runs git merge <branch> for you first, then integrates that branch's root. This runs only on the default branch (the integration target is the top-level .forge/).
The git merge runs in this skill (a Bash step), never in the core script. The deterministic forge-merge.sh/.js that does the integration never runs git — that is what keeps it usable AI-free in CI (CI does its own merge, then calls the script). Only the interactive skill, and only when given a branch argument, runs git merge. This is the bounded relaxation of ADR-0011's "fg-merge does not run git" (ADR 260717-10a); the core script's git-abstinence is unchanged.
The merge step (only when a <branch> argument is given)
Before integrating, run git merge <branch> and route on the result:
- Clean merge (or fast-forward) → git makes its merge commit; the branch root is now in the tree → proceed to integrate.
- "Already up to date" →
<branch> was merged already → skip straight to integrate (smart routing).
- Merge conflict → leave the conflict in place and STOP — do not integrate. The tree is mid-merge, and integration must never run on a dirty/conflicted tree. Tell the human (in their language): resolve the conflicts,
git commit the merge, then run fg-merge (no argument) to integrate. Do not git merge --abort — that discards their merge and forces a redo.
<branch> is not a valid git ref (e.g. the branch was deleted after a PR merge) but .forge/branch/<branch>/ is present → the work is already merged; skip the git step and integrate that root, noting the branch ref is gone (smart routing).- Neither a mergeable ref nor a present branch root → error: nothing to merge or integrate.
- Not on the default branch → stop: merge-and-integrate targets the top-level
.forge/, so it runs only on the default branch.
fg-merge does not commit the integration and does not push — exactly as in integrate-only mode. git merge makes its own merge commit; the integration changes are left uncommitted for you to review and commit (see the handoff).
If .forge/branch/<branch>/ is not present on the default branch after the merge step (or in integrate-only mode with no root at all), the script reports nothing to integrate (exit 2).
How it runs (script-backed integration)
The mechanical integration — resolving the branch root, moving ADRs (time-based IDs; an exact-ID clash takes the next free letter, no cascade renumber), folding retros/done/backlog, merging CONTEXT terms, remapping task numbers, rewriting bumped cross-references, removing the branch folder — is done by a deterministic script, not by an LLM hand-running a dozen mv/sed steps and reasoning the conflict guards in tokens (the same problem ADR-0020 fixed for fg-status and ADR-0030 for fg-done). This skill runs the script and routes on its exit code; the judgment (deciding a genuine semantic conflict, the conflict conversation, the handoff) stays here.
The script exists so the integration also works AI-free in CI (see "CI usage" below): a pipeline can run forge-merge.sh after a merge, and a non-zero exit fails the build so a human resolves it locally. Like forge-done.sh it is gate-first, non-destructive-on-refuse: it detects blocking conditions and exits non-zero before moving anything. Guarded by scripts/forge-merge.test.sh + scripts/forge-merge.parity.test.sh.
Dual dispatch (ADR-0022): prefer bash, fall back to node.
- Has bash:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/forge-merge.sh" [<branch>]
- No bash (e.g. PowerShell-blocked Windows):
node "${CLAUDE_PLUGIN_ROOT}/scripts/forge-merge.js" [<branch>] — identical behavior (exit codes, resulting .forge/ tree), guarded by the parity test.
Argument: passing <branch> selects that branch root and triggers the merge step above (git merge → integrate). Omitting it means integrate-only, letting the script resolve the root — exactly one leaf root → that one; several → it exits 6 with the list, and you ask the user which, then re-invoke. (Because merge-and-integrate always names the branch, exit 6's ambiguity only arises in integrate-only mode.)
Exit codes → routing (this is the skill's job):
| Exit | Meaning | Route |
|---|
| 0 | integrated OK (branch folder removed) | relay the integration summary + commit reminder |
| 2 | nothing to integrate (no branch root / named branch absent / empty) | say so; in integrate-only mode remind that git merge (or fg-merge <branch>) must bring the branch root in first |
| 3 | in-flight branch state (active slot · executed/ · pending quick · loop.md) | tell the human to seal/recover/resume on the branch first (fg-done / fg-run / fg-loop), then re-run |
| 4 | genuine conflict needs a human | resolve it conversationally, then re-run (see below) |
| 6 | ambiguous (several branch roots, no <branch>) | list them, ask which, re-invoke with that branch |
The script emits language-neutral tokens (SEALED … / EMPTY … / GATE_INFLIGHT … / GATE_CONFLICT … / AMBIGUOUS …) — read the token to route; write the user-facing prose in the user's language.
What the script integrates (and what it does not)
It integrates the branch root's permanent docs into the top-level .forge/:
- ADRs (
adr/*) — time-based IDs (YYMMDD-HHMMSS, or grandfathered YYMMDD-HH+letter — ADR-FORMAT.md) move as-is; an exact-ID collision with the target takes the next free letter (no cascade renumber — the #77 scheme), and the bumped ADR's cross-references are rewritten inside the moved incoming docs. retired/ moves as-is.
- Retros (
retro/*) — moved; -2 suffix on a filename collision.
- CONTEXT.md — glossary terms merged term-by-term (new terms appended; a term identical in both is a no-op).
- done/ + backlog/ — folded, with one monotonic task-number remap built across both incoming buckets against the target's markers (so history and runnable backlog stay unique).
- dropped/ — moved (never blocks integration — dropped work was deliberately abandoned).
Then it removes .forge/branch/<branch>/ (and prunes an empty slashed parent, e.g. .forge/branch/feature/).
Warn-only, never rewritten: after re-lettering a bumped ADR (its collision bump), the script greps the merge-changed non-.forge/ project files (git diff --name-only ORIG_HEAD..HEAD, best-effort) for citations of the bumped ID by its old value and warns — outside .forge/ an ADR-<id> citation can't be safely disambiguated, so the human rewrites it.
Not integrated (the two global exemptions of ADR-0011 — never branch-local): .forge/config.json and .forge/codebase/.
The conflicts the script detects (exit 3 / 4) — and the one it cannot
Gate-first: the script checks these before any mutation, so a refusal leaves the tree untouched.
- In-flight branch state (exit 3) — a
plan.md (active slot), a non-empty executed/, a loop.md (unfinished goal contract), or a quick/LOG.md whose latest result still reads pending. A sealed branch has moved its work into done/; unfinished state must be resolved on the branch first (fg-done to seal, fg-run to recover a failed task, fg-loop to finish/abandon a goal loop) — never silently discarded. Route the human there, then re-run.
- Genuine conflict (exit 4) — two mechanically-detectable cases: (a) a CONTEXT term redefined differently in the branch and the target; (b) an incoming grandfathered NNNN ADR colliding with a frozen target NNNN (the letter rule only resolves time-based IDs; a NNNN clash has no cascade to fall back on by design). Show both sides and let the human reconcile (edit the branch's doc, or the target's), then re-run. Since the script is gate-first, nothing was moved.
- The one it cannot detect — semantic ADR contradiction. "This incoming ADR contradicts a decision the default branch made in parallel" is a meaning judgment; a script cannot see it, and it does not halt on it. This is deliberate: in CI it is caught by human PR review; locally you can eyeball the incoming ADRs during this handoff. Do not pretend the script screens for it.
CI usage (AI-free)
Because the mechanical integration is a deterministic script with a clean exit-code contract, a CI job can run it after a merge with no AI:
bash scripts/forge-merge.sh "$BRANCH" # exit 0 = integrated; non-zero = a human is needed
A non-zero exit fails the build: exit 3 (in-flight) / 4 (conflict) / 6 (ambiguous) all mean "resolve locally with fg-merge, then re-push." CI never auto-resolves a semantic conflict — that is the human/PR-review boundary above. (The example workflow that wires this as a gate lives in the team-ci-workflow-merge-policy-docs task.)
Behavior
1) Decide the mode, then (if merging) run the merge step, then run the script. If a <branch> argument was given, first run the merge step above — git merge <branch>, routing on clean / already-up-to-date / conflict / deleted-ref / not-default-branch. Only a clean or already-merged result proceeds; a conflict stops here (leave it in place, do not integrate) and a not-default-branch stops here. With no argument, skip straight to integrate-only. Then resolve the branch root (explicit, or let the script enumerate and route its exit 6) and invoke the integration via dual dispatch (bash, else node). Do not hand-move files or hand-sed IDs — the script owns the integration; you own only the git merge orchestration.
2) Route on the exit code (judgment). Exit 0 → the integration summary below. Non-zero → route per the table / conflict section above and stop (nothing was moved — the script refused before mutating).
3) On a genuine conflict (exit 4), resolve conversationally — a merge-time mini fg-learn. Show the two sides (the redefined term's two bodies, or the colliding NNNN and what occupies it), ask the human how to reconcile, apply their choice to the branch/target doc, then re-run the script. Plan/doc edits are human-approved — never auto-pick a term's winning definition.
4) On success (exit 0), summarize + remind to commit. Relay what the script integrated (N ADRs, any letter bumps, retros moved, terms merged, done/backlog folded with the task-number remap, dropped preserved, branch folder removed) in the user's language, then remind the user to commit the integration result (the moved docs — any collision-bumped ADR re-lettered — plus the branch-folder deletion). In merge-and-integrate mode, note that git merge already made its merge commit, but the integration is still uncommitted — fg-merge never commits the integration, so remind them to commit it (the merge commit + the integration land as two commits, or squash them by hand). If the script printed any WARN external ref … lines, surface them: those are non-.forge/ citations of a bumped ADR the human must rewrite by hand.
fg-merge [<branch>]
│
├── no <branch> ──▶ integrate-only (branch root already merged in)
│ │ (let the script resolve the root; exit 6 if several)
│ ▼
└── <branch> given ─▶ merge step (default branch only): git merge <branch>
├── clean / already up to date ──▶ integrate
├── conflict ──▶ LEAVE in place, STOP → "resolve, commit, then fg-merge (no arg)"
├── ref gone but branch root present ──▶ skip git, integrate + note
├── nothing to merge/integrate ──▶ error
└── not on default branch ──▶ stop
▼
run forge-merge.sh (bash) | forge-merge.js (no bash) ← git-free integration, unchanged
├── exit 0 ──▶ relay integration summary → remind to commit (+ surface WARN external refs)
├── exit 2 ──▶ "nothing to integrate" (integrate-only: git merge / fg-merge <branch> first?)
├── exit 3 ──▶ in-flight on the branch → seal/recover/resume there (fg-done/fg-run/fg-loop) → re-run
├── exit 4 ──▶ genuine conflict → show both sides, human reconciles → re-run
└── exit 6 ──▶ (integrate-only) several branch roots → ask which → re-invoke with that branch
Document impact
- Writes into the target
.forge/adr/, .forge/retro/, .forge/CONTEXT.md, .forge/done/, .forge/backlog/, .forge/dropped/ (the integrated docs), and removes .forge/branch/<branch>/ — all done by the script.
- Does not touch
.forge/config.json or .forge/codebase/ (global exemptions). The core script does not run git (except a best-effort read-only git diff for the warn-only external-ref grep). The skill runs git merge only in merge-and-integrate mode (fg-merge <branch>, default branch) — never the script, never a commit, never a push (ADR 260717-10a).
- The mechanical integration is
scripts/forge-merge.sh / .js — this skill invokes it and routes; it does not hand-move files.
For the ADR/CONTEXT formats, read ${CLAUDE_PLUGIN_ROOT}/skills/fg-ask/ADR-FORMAT.md / CONTEXT-FORMAT.md (skill-relative ../fg-ask/) — do not copy them here.
