forge-orkes 0.21.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.21.0",
+  "version": "0.24.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/skills/architecting/SKILL.md

@@ -68,8 +68,23 @@ Why this won.
 - {Positive consequence}
 - {Negative consequence}
 - {Future decisions this enables or blocks}
+
+## Platform & Goal Validation
+*Required for foundational/irreversible mechanisms (runtime loading, storage engine, auth model, cross-platform primitives). Omit for low-stakes single-feature decisions.*
+- **Platform reality:** Can the target platform(s) actually do this? Name the hard constraint that could forbid it (e.g. iOS code-signing forbids `dlopen` of non-bundled native code). An unvalidated "yes" here is the assumption most likely to become a dead-end years later.
+- **Goal fit:** Does this mechanism actually enable the goal it exists for, *on that platform*? (A loading mechanism for "third-party extensibility" that the platform forbids does not serve that goal there.)
+- **Carrying cost:** Count the platform-specific workarounds this mechanism requires. A high or growing count is a signal the mechanism fights the platform — record the number so it stays visible.
 ```
 
+### Framing the Option Space (before you fill in Alternatives)
+
+Enumerate options that intervene at **different layers**, not variants of one idea. For a load-cost problem, *when* you load, *whether* you load at all, *who holds the lock*, and *what it costs* are different layers; three load-*timing* options are one layer in three costumes. Always include:
+
+- the **constraint-breaker** — "eliminate the need / change the constraint / question the assumption" (e.g. static-link the dependency instead of runtime-loading it → the whole bug class cannot exist);
+- the **null option** — "do nothing".
+
+Name which assumption each option challenges. *Then* converge in Rationale. A confident-looking list of same-layer variants is the failure this guards against — breadth of the enumerator is the real safeguard, so pair this with a second perspective (or `discussing`) when the option space is wide.
+
 ## Constitutional Gate Check
 
 Before finalizing any decision, check against `.forge/constitution.md`:

package/template/.claude/skills/debugging/SKILL.md

@@ -29,7 +29,18 @@ Invoked by `orchestrating` skill when `forge_queue_commit` returns `status: conf
 4. **Test**: Run it. Capture evidence.
 5. **Eliminate**: Support or refute? Record result.
 6. **Iterate**: Next hypothesis or refine current one
-7. **Conclude**: Root cause found. Fix it.
+7. **Conclude**: Confirmation Gate passes (below) → root cause found. Fix it.
+
+## Confirmation Gate
+
+A root cause is a **commit point** — the moment a hypothesis becomes a finding that drives a fix. Run this before you write "root cause", "confirmed", "the cause", or "dominant cause" in the debug file, a commit message, or a report. Until all four hold, the claim stays labelled `hypothesis`:
+
+1. **Mechanism observed, not inferred.** The causal mechanism is directly measured — not assumed from correlation or co-occurrence. ("Event X co-occurs with the bug" is correlation, not mechanism.)
+2. **Alternatives explicitly refuted.** Each competing hypothesis is named and killed with evidence — not dismissed as "less likely". State the evidence that kills each one.
+3. **Blind-spot check (highest-value rule).** For *every absence of signal* you rely on — "0 errors", "detector silent", "watchdog never fired" — first prove the instrument **can** detect the failure mode in question. A deadline-miss detector that measures intra-callback work is structurally blind to the callback never being called; a heartbeat-keyed watchdog is blind to a hang that keeps the heartbeat fresh. **A null result from a blind instrument is not evidence.**
+4. **Falsification attempted.** A test that *could* have refuted the hypothesis was run and failed to refute it. State what that test was. If you cannot name one, you have a hypothesis, not a cause.
+
+When the gate cannot pass yet, write the claim as `hypothesis` everywhere — never `cause` / `confirmed` / `dominant`. Promote it only when 1–4 are satisfied.
 
 ## Persistent Debug File
 
@@ -123,6 +134,7 @@ Add logging before changing behavior. See what's happening before guessing.
 - **Anchoring**: Fixating on the first theory
 - **Availability bias**: Blaming the last thing changed, even if unrelated
 - **Sunk cost**: Continuing a dead-end investigation because of time spent
+- **Instrument blindness**: Trusting a null result ("0 errors", "detector silent") from a tool that structurally cannot observe the failure mode in question. See the Confirmation Gate blind-spot check.
 
 After 3 failed hypotheses, step back and re-read symptoms from scratch.
 
@@ -137,7 +149,8 @@ After 5 hypotheses tested without root cause:
 
 When root cause found:
 1. Fix the issue
-2. Add a regression test for this specific bug
-3. Commit: `fix({scope}): {description of root cause and fix}`
-4. Move debug file to `.forge/debug/resolved/`
-5. Update `.forge/state/milestone-{id}.yml` — remove from blockers
+2. **Confirm the fix addresses the mechanism, not just the symptom.** Re-run the falsification test / repro and verify the *mechanism* identified in the Confirmation Gate is gone — not merely that the symptom stopped appearing. "I stopped seeing it" is itself a premature commit: a symptom can vanish for an unrelated reason.
+3. Add a regression test for this specific bug
+4. Commit: `fix({scope}): {description of root cause and fix}`
+5. Move debug file to `.forge/debug/resolved/`
+6. Update `.forge/state/milestone-{id}.yml` — remove from blockers

package/template/.claude/skills/discussing/SKILL.md

@@ -267,6 +267,7 @@ Re-plan? Route to `planning` with summary.
 3. **Reference user's words.** "Friday" factors into every rec.
 4. **Stop when clear.** Don't manufacture uncertainty.
 5. **Now vs later.** Flag deferrable vs blocking.
+6. **Widen before narrowing.** Before converging on an approach, put options that intervene at *different layers* on the table — including the constraint-breaker ("change or eliminate the constraint") and "do nothing" — not three variants of one idea. Name the assumption each challenges, then pick. (Foundational/structural decisions formalize this in `architecting`'s option-space framing + Platform & Goal Validation.)
 
 ## Anti-Patterns
 

package/template/.claude/skills/executing/SKILL.md

@@ -105,6 +105,16 @@ feat(auth-01): implement JWT-based login
 - Include integration test for login flow
 ```
 
+## Version Bump Protocol
+
+When a task bumps the project version (`package.json` etc.) or adds a CHANGELOG entry:
+
+1. **Read the reserved number from `.forge/releases.yml`** — write ONLY the version this milestone reserved (Version Reservation Protocol, FORGE.md). Never invent a number at delivery.
+2. **No reservation? Reserve now** (planning predated the registry): `git pull`, take `max(version) + bump-level`, append one `{milestone, version, bump, reserved_at, summary}` entry, **commit + push the reservation BEFORE editing the version file** so a parallel session sees it taken.
+3. **Then** write the version + CHANGELOG entry in the normal atomic commit.
+
+This is what stops two parallel milestone sessions from grabbing the same number or clobbering each other's version edit — the registry, not the file, is the source of truth for "what number is mine."
+
 ## Multi-Agent Claim Convention [Experimental — M10]
 
 **Trigger:** active milestone state has `lifecycle.worktree_mode: active` (set by `orchestrating` skill). If absent or any other value → skip this section entirely; single-agent behavior unchanged.

package/template/.claude/skills/forge/SKILL.md

@@ -205,7 +205,13 @@ Tier + state → invoke via `Skill` tool. All phases use `Skill()`.
 
 **CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
-**Experimental:** if user invokes `orchestrating` skill (M10) and repo has it installed (`.claude/skills/orchestrating/` present + MCP server + claim-check hook), route through it **before** `executing` to bootstrap multi-agent worktree. Skill is opt-in per ADR-001; absent install → fall through to standard routing.
+**Experimental — M10 orchestration (auto-routes when installed).** Installing M10 *is* the consent: `forge` then auto-routes Standard/Full work through `orchestrating` **before** `executing` — no separate invocation to remember. Route through `Skill(orchestrating)` first when **all** hold:
+- **Installed:** `.claude/skills/orchestrating/` present + `forge-orchestrator` in `.mcp.json` + `.claude/hooks/forge-claim-check.sh` present.
+- **Not opted out:** `orchestration.auto` in `project.yml` ≠ `false` (absent = on; install = consent per ADR-001).
+- **Tier is Standard or Full.** Quick never auto-orchestrates (a worktree per typo is the wrong trade).
+- **Not already in a session:** active milestone has no `lifecycle.worktree_mode: active|degraded` (don't re-bootstrap inside a live session).
+
+`orchestrating` bootstrap stays the safety net — incompatible repo → it refuses, writes `worktree_mode: refused`, and `forge` continues single-agent. Absent install → standard routing. Manual `Skill(orchestrating)` still works for explicit control; set `orchestration.auto: false` in `project.yml` to opt back out.
 
 ### Auto-Routing (Always Deterministic)
 

package/template/.claude/skills/planning/SKILL.md

@@ -381,6 +381,7 @@ Done when approved.
 ## Handoff
 
 1. **Persist** -- plans `.forge/phases/`, reqs `.forge/requirements/m{N}.yml`, roadmap `.forge/roadmap.yml`, context `.forge/context.md`
-2. **State** -- `current.status` = `executing` in `.forge/state/milestone-{id}.yml`
-3. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after planning — m{N} {phase-name}"` (scoped; never `git add .`).
-4. *"Plan written and synced. `/clear` then `/forge` to continue."*
+2. **Reserve version (if delivery bumps the version)** -- if any plan in this milestone will bump `package.json`/the project version, append ONE entry to `.forge/releases.yml` (Version Reservation Protocol, FORGE.md): pull first, set `version` = highest reserved `max()` bumped by this change's semver level, append `{milestone, version, bump, reserved_at, summary}`. **Never edit prior entries.** No version bump in scope → skip. Surface the reserved number to the user.
+3. **State** -- `current.status` = `executing` in `.forge/state/milestone-{id}.yml`
+4. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after planning — m{N} {phase-name}"` (scoped; never `git add .`). The `releases.yml` reservation rides in this commit — **push it** so a parallel session sees the number taken before they reserve.
+5. *"Plan written and synced. `/clear` then `/forge` to continue."*

package/template/.claude/skills/quick-tasking/SKILL.md

@@ -70,8 +70,9 @@ Invoked via forge routing (mid-workflow or refactor-backlog item with milestone
 
 1. Read `.forge/state/milestone-{id}.yml` for current position
 2. Follow standard workflow (above)
-3. After commit: update `milestone-{id}.yml` — advance the `current` cursor if the task moved position and set `current.last_updated`; log deviations if any Rule 1-3 applied. Do **not** write a progress percent (derived on read by `forge`) and do **not** write `index.yml` (derived). Then **state-sync commit**: `git add .forge/` && `git commit -m "chore(forge): sync state after quick-task — m{N}"` (scoped; never `git add .`).
-4. Report: fix description, files changed, current position
+3. **If this task worked a refactor-backlog item:** in `.forge/refactor-backlog.yml` set that item's `status: done`, write `completed` (today, ISO) + `completed_by` (commit sha / one-line), THEN run the same **compaction-on-write** as `reviewing` Step 7 → "Status vocab + compaction-on-write" (normalize statuses → archive terminal items to `.forge/refactor-backlog-archive.yml` → leave only actionable items). Compaction is idempotent. (See reviewing Step 7 for the canonical rule — not repeated here.) This closes the loop: a worked item leaves the working backlog instead of lingering as `pending`.
+4. After commit: update `milestone-{id}.yml` — advance the `current` cursor if the task moved position and set `current.last_updated`; log deviations if any Rule 1-3 applied. Do **not** write a progress percent (derived on read by `forge`) and do **not** write `index.yml` (derived). Then **state-sync commit**: `git add .forge/` && `git commit -m "chore(forge): sync state after quick-task — m{N}"` (scoped; never `git add .`).
+5. Report: fix description, files changed, current position
 
 ### Without Milestone
 

package/template/.claude/skills/reviewing/SKILL.md

@@ -333,6 +333,21 @@ Missing? Create from `.forge/templates/refactor-backlog.yml`.
 
 **When deferring an individual refactor item** (status flipped to `deferred`, as opposed to milestone-wide defer which goes through the forge skill): write `deferred_at` (ISO date today) and `deferred_reason` (one-line) siblings to `status: deferred`. Pre-existing items without these fields parse fine — lazy migration. These feed the `deferred` aggregator skill.
 
+### Status vocab + compaction-on-write
+
+**Canonical status vocab — the ONLY allowed values:** `pending | in_progress | done | dismissed | deferred`. Actionable = `pending|in_progress|deferred`. Terminal = `done|dismissed`.
+
+**Normalization map** (apply before any write): `completed`,`complete`,`closed` → `done`; `wont_fix`,`stale` → `dismissed`. Any other non-canonical value (`null`, free text, `promoted_to_m{N}`, …) → leave in place, surface for human triage in the review output (`"Backlog has {N} item(s) with unrecognized status — triage"`). Never silently drop.
+
+**Compaction-on-write** — run EVERY time you write the backlog, after appending new items:
+1. Normalize statuses via the map above.
+2. Move every terminal (`done|dismissed`) item — full record, intact — by **append** to `.forge/refactor-backlog-archive.yml` (create with a one-line header if absent: `# Forge Refactor Backlog — Archive (resolved/dismissed items). Append-only.`).
+3. Remove those items from `.forge/refactor-backlog.yml` so the working file holds only actionable + un-triaged items.
+
+Idempotent: a backlog with no terminal items and all-canonical statuses is left byte-unchanged. No item is ever lost — terminal items relocate, they are not deleted.
+
+**Size-gate check (advisory).** After compaction, if the working file still exceeds the FORGE.md size gate (150 KB), emit: `"Refactor backlog over size gate ({size}) even after compaction — {N} actionable items. Consider triaging stale pending items or promoting a cluster to Standard tier. Advisory — does not block."` (A busy project with hundreds of unworked pending items legitimately trips this; the signal is "triage the actionable backlog", not "archiving failed".)
+
 ### Route
 
 **HEALTHY/WARNINGS (accepted):** set `current.status: complete` in `milestone-{id}.yml`, then regenerate `index.yml` via the `forge` **Rollup** (do not hand-edit index). *"Milestone [{name}] complete. {N} backlog items."* Beads: `bd complete`.

package/template/.claude/skills/upgrading/SKILL.md

@@ -227,6 +227,45 @@ Migrate now? (yes/no/show guide)
 
 `upgrading` never moves phase dirs directly — migration runs via `quick-tasking`.
 
+### Pre-0.22.0 unbounded refactor-backlog
+
+Run from project root (backlog present only):
+
+```bash
+F=.forge/refactor-backlog.yml
+[ -f "$F" ] || exit 0
+kb=$(( $(wc -c < "$F") / 1024 ))
+terminal=$(grep -cE 'status:[[:space:]]*(done|dismissed|completed|complete|closed|wont_fix|stale)' "$F")
+noncanon=$(grep -oE 'status:[[:space:]]*[A-Za-z_]+' "$F" \
+  | grep -vE 'status:[[:space:]]*(pending|in_progress|done|dismissed|deferred)$' | wc -l)
+# bloat if: kb > 150  OR  terminal > 0  OR  noncanon > 0
+```
+
+Surface the prompt when `kb > 150` OR `terminal > 0` OR `noncanon > 0`, printing the three detected numbers:
+
+```
+Refactor-backlog compaction available (Forge 0.22.0)
+────────────────────────────────────────────────────
+Pre-0.22.0 the refactor backlog was append-only — resolved items were never
+pruned and statuses drifted (completed/complete/closed/wont_fix/stale + junk).
+0.22.0 archives terminal items to .forge/refactor-backlog-archive.yml and
+enforces the canonical vocab (pending|in_progress|done|dismissed|deferred).
+
+Detected: {kb} KB · {terminal} terminal item(s) · {noncanon} non-canonical status(es).
+A migration guide is available at: .forge/migrations/0.22.0-backlog-compaction.md
+(canonical: https://github.com/Attuned-Media/forge/blob/main/docs/migrations/0.22.0-backlog-compaction.md)
+
+Migrate now? (yes/no/show guide)
+```
+
+- **yes** → invoke `quick-tasking` skill, hand it the migration guide as the task definition (snapshot item count, normalize statuses, split actionable/terminal/triage, archive terminal items to `.forge/refactor-backlog-archive.yml`, rewrite the working file, verify item-count conservation before committing).
+- **show guide** → read and display the file, then re-ask
+- **no** → note in upgrade report. The backlog keeps growing and statuses stay drifted until migrated; reviewing/quick-tasking will compact on their next write regardless, but a bloated file lingers until then. Recommend running before the next review cycle.
+
+No-op guarantee: detection exits clean (no prompt) when the backlog is absent, under the gate, has zero terminal items, and all statuses are canonical. (Pending-item count is **not** a trigger — a busy-but-clean backlog is left alone.)
+
+`upgrading` never edits the backlog directly — migration runs via `quick-tasking`.
+
 ### Future migrations
 
 Add new detection blocks here for each Forge version that changes file layout. Pattern:

package/template/.forge/FORGE.md

@@ -17,6 +17,7 @@ All phases: **invoke via `Skill` tool**, never native behavior. `planning` → `
 5. **Verify goals, not tasks.** "Does it work?" > "Did we finish checklist?"
 6. **Never forget.** `.forge/state/` persists across sessions. Milestones concurrent. Beads-compatible.
 7. **Pave desire paths.** Repeated deviations/corrections = signal → evolve framework.
+8. **Disconfirm before commit.** Before locking a diagnosis, a solution, or a foundational choice, run the cheap pass that could break it. A conclusion reached without an attempt to refute it is a hypothesis, not a finding. Enforced at the three commit points: `debugging` (Confirmation Gate), `discussing`/`architecting` (option-space framing), `architecting` (Platform & Goal Validation).
 
 ## Workflow Tiers
 
@@ -72,6 +73,7 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | `requirements/m{N}.yml` | 50 KB/file | Prevents scope creep |
 | `plan.md` | 30 KB | Keeps executor context <50% |
 | `constitution.md` | 10 KB | Gates must be scannable |
+| `refactor-backlog.yml` | 150 KB | Working backlog stays scannable; terminal items archive to `refactor-backlog-archive.yml` (advisory — flags, never blocks) |
 
 ### Fresh Agent Pattern
 Task touches 20+ files or complex subsystem → spawn fresh executor with isolated context. Prevents context rot.
@@ -135,7 +137,9 @@ State lives in `.forge/`:
 - `context.md` — Locked decisions + deferred ideas (discuss phase)
 - `research/milestone-{id}.md` — Research findings snapshot (dated, immutable)
 - `phases/milestone-{id}/{phase}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter (`{id}`=milestone, `{phase}`=phase# preserved verbatim, `{name}`=kebab, `{NN}`=seq)
-- `refactor-backlog.yml` — Refactoring catalog, worked via quick-tasking
+- `refactor-backlog.yml` — Refactoring catalog (actionable items only), worked via quick-tasking. Canonical status vocab: `pending | in_progress | done | dismissed | deferred`. Terminal items auto-archive on the next reviewing/quick-tasking write (compaction-on-write).
+- `refactor-backlog-archive.yml` — Append-only terminal-item archive (`done`/`dismissed`); keeps the audit trail out of the working backlog.
+- `releases.yml` — Append-only version-reservation registry (cross-session coordination point; see Version Reservation Protocol)
 - `archive/milestone-{id}/` — Archived milestone artifacts (archive-delete)
 
 **Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions. Can be deferred (frozen in place) or archive-deleted.
@@ -161,6 +165,17 @@ State-sync commits are separate from per-task code commits (which stay atomic du
 - `index.yml` is **regenerated by rollup** (read every `milestone-*.yml` → rewrite the registry) by the main/orchestrator session — on `forge` resume and at `orchestrating` teardown. The rollup is deterministic + idempotent, so it **is** the reconcile step — never a hand-merge.
 - Same-milestone parallel work is out of scope, guarded by the M10 claim layer.
 
+### Version Reservation Protocol
+
+The project version + CHANGELOG slot are **shared resources** — when two milestones run in parallel sessions, each independently bumping `package.json`/version and adding a CHANGELOG entry collides. `.forge/releases.yml` removes the number from per-milestone scope.
+
+- **Reserve early, at planning.** When a milestone's delivery will bump the version, the `planning` skill appends ONE entry to `.forge/releases.yml`: `{milestone, version, bump, reserved_at, summary}`. The reserved version = highest `version:` in the file bumped by the change's semver level (capability → minor; fix/doc → patch — see version-bump criteria below).
+- **Append-only — never edit prior entries.** Distinct lines = no cross-session conflict. Commit + push the reservation BEFORE editing the version file, so a parallel session pulls and sees the number taken.
+- **Delivery never invents a number.** The `executing`/delivery step writes only the version reserved in `releases.yml`, then its CHANGELOG entry. If no reservation exists (milestone planned before this file), it reserves at delivery: pull, take `max() + bump`, append, push, then write.
+- **Race resolution.** Two near-simultaneous reservations: the second push rebases onto the first (append-only → clean), re-reads `max()`, takes the next number.
+
+**Version-bump criteria (0.x projects):** patch (`0.x.y`) = bug fix, doc tweak, sync-only, refinement. Minor (`0.x.0`) = new skill/agent/routing-row/auto-trigger/state-artifact/capability. Major (`x.0.0`) = post-1.0 breaking change. Default to minor when in doubt — a capability addition shipped as a patch drifts the version away from truth.
+
 ## Deviation Rules
 
 **Full definitions:** `.claude/agents/executor.md`.

package/template/.forge/migrations/0.22.0-backlog-compaction.md

@@ -0,0 +1,186 @@
+# Migration Guide: Refactor-Backlog Compaction (Forge 0.22.0)
+
+Applies to projects whose `.forge/refactor-backlog.yml` has grown unbounded
+(terminal items never pruned) and/or has drifted off the canonical status
+vocabulary.
+
+## Why
+
+Before 0.22.0 the refactor backlog was **append-only** — the `reviewing` skill
+added items (`Next ID = max + 1`) but nothing ever removed resolved ones. Over a
+project's life, `done`/`dismissed` items accumulate forever, and the `status`
+field drifts into synonyms (`completed`, `complete`, `closed`) and junk
+(`null`, free text). One real project reached **9,256 lines / 439 items**, of
+which only ~220 were actionable — the rest was resolved-item sediment.
+
+Per Article XI (context is sacred), the working backlog must stay scannable. A
+multi-thousand-line YAML file is a context tax on every `reviewing`/`deferred`
+read and is impossible to triage by hand.
+
+0.22.0 keeps the working file **actionable-only**: terminal items move to an
+append-only archive, and statuses are normalized to a single vocabulary.
+
+## What changes
+
+- Terminal items (`done` | `dismissed`) move — full record intact — to
+  `.forge/refactor-backlog-archive.yml` (append-only).
+- Statuses normalize to the canonical set:
+  `pending | in_progress | done | dismissed | deferred`.
+- The working `.forge/refactor-backlog.yml` keeps only **actionable**
+  (`pending | in_progress | deferred`) and any **un-triaged** items.
+
+## What does NOT change
+
+- **No item is deleted.** Terminal items are relocated to the archive, not
+  dropped. The full record (`completed`, `completed_by`, `dismissed_reason`,
+  dates) is preserved — the audit trail just lives out of the working file.
+- **IDs are stable.** `R042` stays `R042` in whichever file it lands in.
+- **Actionable items are content-stable** apart from status normalization
+  (a legacy `completed` only ever appears on a terminal item, so actionable
+  items are typically byte-unchanged).
+- **`deferred` items stay in the working file** with their `deferred_at` /
+  `deferred_reason` — they are actionable (awaiting a revisit), not terminal.
+
+## Status normalization map
+
+Apply before splitting. Fold each legacy value to its canonical equivalent:
+
+| Legacy value(s) | Canonical |
+|-----------------|-----------|
+| `completed`, `complete`, `closed` | `done` |
+| `wont_fix`, `stale` | `dismissed` |
+| `pending`, `in_progress`, `done`, `dismissed`, `deferred` | (unchanged) |
+| anything else (`null`, `RegistrationStatus`, free text, `promoted_to_m{N}`) | **TRIAGE** |
+
+A `TRIAGE` value is **never** auto-resolved. Leave the item in the working file
+and surface it for a human decision: *"{N} item(s) have an unrecognized status —
+triage."* Silently dropping or guessing is forbidden.
+
+## Detection
+
+Bloat/drift exists if the file is over the 150 KB size gate, OR any terminal
+item is present, OR any non-canonical status appears:
+
+```bash
+F=.forge/refactor-backlog.yml
+[ -f "$F" ] || { echo "no backlog — no-op"; exit 0; }
+kb=$(( $(wc -c < "$F") / 1024 ))
+terminal=$(grep -cE 'status:[[:space:]]*(done|dismissed|completed|complete|closed|wont_fix|stale)' "$F")
+noncanon=$(grep -oE 'status:[[:space:]]*[A-Za-z_]+' "$F" \
+  | grep -vE 'status:[[:space:]]*(pending|in_progress|done|dismissed|deferred)$' | wc -l)
+echo "size=${kb}KB terminal=$terminal noncanon=$noncanon"
+# bloat if: kb > 150  OR  terminal > 0  OR  noncanon > 0
+```
+
+A clean backlog (under the gate, zero terminal, all-canonical) prints
+`size=… terminal=0 noncanon=0` → **no-op**. The detector keys off bloat that
+compaction actually fixes, **not** the count of pending items — a busy-but-clean
+backlog is left alone.
+
+## ⚠️ Environment gotcha (read before scripting)
+
+The Bash tool runs **zsh**, where `$BASH_REMATCH` / `=~` capture groups **do not
+populate** — a regex-capture loop written for bash silently produces empty
+captures and can corrupt output. Two rules:
+
+1. **Prefer a single-pass YAML-aware split over per-line regex.** This migration
+   relocates list items between two YAML files — operate on whole item blocks,
+   not field-by-field string surgery.
+2. If you must use `=~` capture, **wrap the loop in `bash -c '…'`** so it runs
+   under bash, not zsh.
+
+And the cardinal rule from prior migrations: **verify item count before == after
++ archived.** If the totals don't conserve, STOP and recover from git.
+
+## Procedure
+
+### 1. Secure current state first
+
+```bash
+git add .forge/refactor-backlog.yml
+git commit -m "chore(forge): secure backlog before 0.22.0 compaction"
+```
+
+### 2. Snapshot the original item count
+
+```bash
+N_BEFORE=$(grep -cE '^[[:space:]]*-?[[:space:]]*id:' .forge/refactor-backlog.yml)
+echo "items before: $N_BEFORE"
+```
+
+### 3. Normalize statuses
+
+Fold synonyms per the map above (`completed`/`complete`/`closed` → `done`;
+`wont_fix`/`stale` → `dismissed`). Record any value that is still non-canonical
+after normalization as the **TRIAGE** set — do not change it.
+
+### 4. Split into three buckets
+
+Walk the item list once and bucket each item by its (normalized) status:
+
+- **actionable** → `pending | in_progress | deferred`
+- **terminal** → `done | dismissed`
+- **triage** → anything else (unrecognized)
+
+Operate on whole item blocks (an item starts at `- id:` and runs until the next
+`- id:` or EOF). Preserve every field verbatim.
+
+### 5. Write the archive
+
+Append the **terminal** bucket (full records) to
+`.forge/refactor-backlog-archive.yml`. Create it if absent with a header:
+
+```yaml
+# Forge Refactor Backlog — Archive (resolved/dismissed items). Append-only.
+# Items relocated here by compaction; full record preserved for audit trail.
+items:
+```
+
+### 6. Rewrite the working file
+
+Rewrite `.forge/refactor-backlog.yml` with the **actionable + triage** buckets
+only (triage stays visible until a human resolves it). Keep the template header.
+
+### 7. Verify conservation — the hard gate
+
+```bash
+A=$(grep -cE '^[[:space:]]*-?[[:space:]]*id:' .forge/refactor-backlog.yml)        # actionable + triage
+B=$(grep -cE '^[[:space:]]*-?[[:space:]]*id:' .forge/refactor-backlog-archive.yml) # archived (subtract its template example if any)
+echo "working=$A archived=$B  sum=$((A+B))  before=$N_BEFORE"
+```
+
+`working + archived` **must equal** `N_BEFORE`. If it does not, **STOP** — do not
+commit; `git checkout .forge/refactor-backlog.yml` and investigate (a malformed
+item block failed to parse).
+
+### 8. Commit
+
+```bash
+git add .forge/refactor-backlog.yml .forge/refactor-backlog-archive.yml
+git commit -m "chore(forge): compact refactor backlog — archive terminal items (0.22.0)"
+```
+
+## After migration
+
+- The working file may still exceed the 150 KB gate if the project has hundreds
+  of genuinely-unworked `pending` items. That is a legitimate **triage** signal
+  ("work or dismiss stale items / promote a cluster to Standard tier"), **not** a
+  failed migration. Compaction archives resolved items; it does not invent triage
+  decisions about open ones.
+- From here on, `reviewing` Step 7 and `quick-tasking` compact on every write —
+  the backlog stays bounded without re-running this migration.
+
+## Rollback
+
+The whole operation is one commit over two files. `git revert <sha>` (or
+`git checkout <pre-migration-sha> -- .forge/refactor-backlog.yml` and delete the
+archive) fully reverses it — nothing was destroyed.
+
+## Notes
+
+- Idempotent: re-running on an already-compacted backlog archives nothing and
+  leaves the working file byte-unchanged.
+- The `upgrading` skill (Step 7) detects bloat/drift after an upgrade and offers
+  to run this migration via `quick-tasking`. It never edits the backlog directly.
+- Canonical copy of this guide:
+  https://github.com/Attuned-Media/forge/blob/main/docs/migrations/0.22.0-backlog-compaction.md

package/template/.forge/releases.yml

@@ -0,0 +1,29 @@
+# Forge Release Registry — version reservations across concurrent milestones
+#
+# PURPOSE: remove the version number + CHANGELOG slot from per-milestone scope so
+# two milestones running in parallel sessions never collide on your project's
+# version or pick the same number. This is the coordination point both sessions
+# read and append to.
+#
+# COMMITTED + APPEND-ONLY. Each milestone appends exactly ONE entry when it
+# reserves its version (at planning, or at delivery if planning predates this
+# file). Appending — never editing prior entries — is what keeps two sessions
+# from conflicting: distinct lines, no contention. Commit and push the
+# reservation so a parallel session pulls and sees numbers already taken.
+#
+# RULE: the next free version = highest `version:` in this file, bumped by the
+# change's semver level (capability = minor; fix/doc = patch). Delivery NEVER
+# writes a project version that is not reserved here first.
+#
+# RACE NOTE: reserve EARLY (at planning), commit + push the reservation BEFORE
+# editing the version. If two sessions reserve near-simultaneously, the second
+# push rebases onto the first (append-only → no conflict) and re-reads max() to
+# take the next number.
+
+releases: []
+# Example entry shape (delete this comment once you add a real one):
+#   - milestone: 1
+#     version: "0.2.0"
+#     bump: minor
+#     reserved_at: "YYYY-MM-DD"
+#     summary: "one-line description of the milestone"

package/template/.forge/templates/refactor-backlog.yml

@@ -1,8 +1,13 @@
-# Forge Refactor Backlog
-# Auto-managed by the refactoring skill. Items added after milestone audits.
-# Work items via quick-tasking (effort: quick) or Standard tier (effort: standard).
+# Forge Refactor Backlog — actionable items only.
+# Auto-managed by the reviewing skill. Items added after milestone audits;
+# worked via quick-tasking (effort: quick) or Standard tier (effort: standard).
 #
-# Status vocab: pending | in_progress | done | dismissed | deferred
+# Status vocab (the ONLY allowed values): pending | in_progress | done | dismissed | deferred
+#   Actionable = pending | in_progress | deferred   Terminal = done | dismissed
+# Compaction-on-write: every reviewing/quick-tasking write normalizes statuses and
+#   moves terminal items (full record) to .forge/refactor-backlog-archive.yml, so this
+#   file holds only actionable items. No item is deleted — terminal items relocate.
+#   Legacy synonyms are normalized: completed/complete/closed → done; wont_fix/stale → dismissed.
 # Optional fields (lazy migration — only required on entries set to status: deferred going forward):
 #   deferred_at: ISO date when status flipped to deferred
 #   deferred_reason: one-line why; revisited when status changes