forge-orkes 0.75.0 → 0.79.0

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

@@ -312,6 +312,22 @@ Deferred issues triage: Glob `.forge/deferred-issues/*.md` (else legacy `.forge/
 - **Fix-now** → route to `planning` fix mode before completing milestone
 - **Dismiss** → set `status: dismissed` + `dismissed_reason` in the issue's file (or the legacy file)
 
+Close-the-loop triage (advisory — never blocks): catches shipped-but-still-open GitHub issues. Forge produces resolution artifacts (ADRs, desire-paths, CHANGELOG/commits) that cite the issue they resolve, but nobody circles back to close the issue — the open list accumulates already-done work. This step cross-references those artifacts against **open** issues and surfaces likely-resolved ones for the operator to close. **Detect-and-surface only — NEVER auto-close** (closing a GitHub issue is outward-facing → operator confirmation, agent safety rules).
+
+1. **Gate / degrade first.** Resolve `forge.upstream_repo` from `project.yml`. If absent, OR `gh` not on PATH, OR `gh auth status` fails, OR offline → **skip the whole step** (at most one log line: *"close-the-loop: gh unavailable — skipped"*). Never blocks reviewing or completion. (Same posture as `forge/desire-paths-review.md`'s resolve→check-gh→offer and notion-integration's advisory-everywhere.)
+2. **Collect resolution-intent `#N` refs produced THIS milestone** (milestone-scoped default — cheap, fires when the artifact is fresh):
+   - **ADRs** authored/touched this milestone whose `**Context source:**` / `resolves` / `closes` line cites `forge#N` (or the `…/issues/N` URL). **Exclude bare supersession / see-also mentions** — a *"Superseded by ADR-021 ([forge#19](…))"* note references #19, it does not resolve it. Only resolution-intent lines count.
+   - **desire-path** files with `resolves_issue: N`.
+   - **CHANGELOG / commit** lines landed this milestone with `closes|fixes|resolves #N`.
+   Scope by this milestone's git range / this milestone's artifacts — prose-directed grep, no executable.
+3. **Intersect cited ∩ still-open.** `gh issue view N --json state,title` each; **keep only `state == OPEN`**. An `#N` gh can't resolve (nonexistent / transferred / errors on that call) OR reports CLOSED → **no candidate** (surface only gh-confirmed-open — zero false positives). Skip any `#N` with a `.forge/state/issue-loop/declined/{N}.yml` marker (glob first — mirrors the desire-path `declined/` skip).
+4. **Surface survivors** (existing triage idiom): *"**Close-the-loop** ({N}): 1. #N '{title}' — looks resolved by {artifact} — close it? [y/N]"*.
+   - **y** (or "close") → **do NOT close autonomously.** Print the exact command for the operator to run (or to approve Forge running as an explicit per-action step): `gh issue close N --comment "Resolved by {artifact} ({ref}). Closing via Forge close-the-loop."`
+   - **N** (or "still open") → write `.forge/state/issue-loop/declined/{N}.yml` (`{issue: N, declined_at: <ISO date>, reason: "<one line>"}`; create the dir if absent) so it is not re-nagged. The marker is inert once the issue actually closes (gh stops returning it as open).
+5. **Optional full sweep** (operator-invoked, natural language — no new command): if the operator asks *"run a full close-the-loop sweep"* / *"check for orphaned issues"*, run steps 1–4 over **all** open issues × **all** shipped resolution artifacts repo-wide (not just this milestone), same rules + `declined/` markers. This is the periodic-cleanup path; the milestone-scoped default stays quiet.
+
+Zero candidates → silent (the common case). This step is **advisory — it never gates milestone completion** (see Gates).
+
 ## Step 7: Backlog + Route
 
 ### Backlog
@@ -371,6 +387,7 @@ Idempotent: a backlog with no terminal items and all-canonical statuses is left
 - **Security/arch critical** -> soft gate (accept risk)
 - **Warnings** -> advisory
 - **Refactoring** -> never block
+- **Close-the-loop** -> advisory, never blocks (detect-and-surface only; never auto-closes)
 
 Report = audit trail.
 

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

@@ -119,6 +119,25 @@ Rebase now? (each / list-only / skip)
 - **list-only / skip** → print the commands; the operator runs them at a safe stopping point.
 - Gitignored carve-outs (`.mcp.json`, experimental hooks) are not carried by a rebase — whenever layer (b) re-synced anything, add: each worktree must re-run `experimental/{pkg}/install.sh`.
 
+### e. Primary-checkout weld (`core.hooksPath`)
+
+Runs on every upgrade (registry and Dev Mode alike) — the bin syncs the `.forge/git-hooks/` body, but `core.hooksPath` is per-clone git config the bin never touches (issue #21, ADR-031). Wire it with the **detect + warn, never clobber** policy — identical to `initializing` Finalize step 8. Main checkout only (`git rev-parse --git-dir` == `--git-common-dir`; from a worktree, skip — the primary checkout owns the config):
+
+```bash
+want=".forge/git-hooks"
+cur=$(git config --get core.hooksPath 2>/dev/null || true)
+if [ -z "$cur" ] || [ "$cur" = "$want" ]; then
+  git config core.hooksPath "$want"   # repo-relative → resolves inside every worktree
+  echo "[Forge] core.hooksPath → $want (primary-checkout weld active)."
+else
+  echo "[Forge] core.hooksPath is already '$cur' (Husky/lefthook?). NOT overwriting — the"
+  echo "        primary-checkout pre-commit backstop is inactive. Chain .forge/git-hooks/pre-commit"
+  echo "        into your existing hooks dir to keep the weld, or accept PreToolUse-only coverage."
+fi
+```
+
+Idempotent — re-running an upgrade that already wired it is a silent no-op. **WHY repo-relative + never-clobber:** same reasons as `initializing` step 8 (worktree-resolvable path; a consumer's Husky/lefthook must never be silently disabled).
+
 ## Dev Mode (`/upgrading dev` — explicit only)
 
 Local-clone sync for developing Forge itself: test framework changes in a project without publishing to npm. Presence of `.forge/dev-source` NEVER selects this mode — only the explicit `dev` argument does.
@@ -141,7 +160,7 @@ Dev mode syncs from a checkout, so it keeps file-classification semantics — **
 
 - **Framework-owned** (`.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.forge/FORGE.md`) → overwrite when different. Ownership is per top-level **unit** — a skill DIR under `.claude/skills/`, a flat agent FILE under `.claude/agents/`: a unit the template doesn't ship (user-authored, vendored-parity, or an opt-in experimental skill) is **preserved, never deleted**; only stale files *inside* a still-shipped skill dir are cleaned. Experimental skills additionally get the staleness pass below.
 - **Template-only** (`.forge/templates/**`, `.forge/migrations/**`, `.forge/adapters/**`, `.forge/gitignore` → `.forge/.gitignore`) → overwrite; `.forge/FORGE.md` lands BEFORE the CLAUDE.md pass.
-- **Additive** (`.claude/hooks/**` incl. `tests/`, `.claude/rules/**`, `.forge/checks/**`) → add + overwrite template-shipped files, never delete local extras, `chmod +x` synced `*.sh`.
+- **Additive** (`.claude/hooks/**` incl. `tests/`, `.claude/rules/**`, `.forge/checks/**`, `.forge/git-hooks/**`) → add + overwrite template-shipped files, never delete local extras, `chmod +x` synced `*.sh` (and the extensionless git hooks under `.forge/git-hooks/`).
 - **Import-managed** `CLAUDE.md` → the bin's `ensureClaudeMdImport()` cases verbatim; user content outside a forge section is never modified.
 - **Merge-owned** `.claude/settings.json` → `forge.*` keys + additive hook-group wiring only; stamp `forge.version` last.
 - **Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements/`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
@@ -150,11 +169,12 @@ Render the same report shape as the default path, with `Source: {path}` instead
 
 ### Post-sync layers
 
-Re-use layers (a)–(d) with dev-derived inputs — this is the one mode that computes them itself, since there is no engine JSON:
+Re-use layers (a)–(e) with dev-derived inputs — this is the one mode that computes them itself, since there is no engine JSON:
 
 - **(a) Migrations** — the data-driven Detection loop: select freshly-synced guides `.forge/migrations/{v}-*.md` where `installed < v <= source` (semver on the PRE-stamp installed version), run each guide's `## Detection` bash block from the project root; `MIGRATE` on stdout → the layer-(a) prompt with the text after `MIGRATE —` as the reason; no output → `{v}: no action`; block errors → `{v}: detection error (skipped)`, never abort the loop. Range bookkeeping is implicit: once `forge.version` is stamped, crossed guides fall out of the next run's range — no ledger.
 - **(b) Experimental staleness** — diff installed non-template skill dirs against `{source}/packages/create-forge/experimental/*/source/skills/{name}/`; stale → the layer-(b) offer with `{source}` as the source path.
 - **(c) Codex** — presence glob (`.agents/` / `.codex/`) → the layer-(c) offer.
 - **(d) Worktrees** — `git worktree list --porcelain` filtered to `refs/heads/forge/m-*`, main checkout only (`git rev-parse --git-dir` == `--git-common-dir`; from a worktree, skip and say so) → the layer-(d) offer.
+- **(e) Primary-checkout weld** — wire `core.hooksPath` with the detect+warn+never-clobber policy above (main checkout only). Same behavior in Dev Mode as on the registry path.
 
 Same consent gates, same report lines as the registry path.

package/template/.forge/FORGE.md

@@ -59,6 +59,8 @@ Where worktrees live and what they're named — single source of truth, base con
 
 **Recorded path is authoritative once set** — `lifecycle.worktree_path` (milestone) / `runtime.worktree` (stream) is read verbatim, never re-derived; changing `worktree_root` affects only new worktrees; move a live worktree only with `git worktree move` + update the record. No recorded path → resolve from the convention. `forge` boot and `chief-of-staff` adoption **validate advisorily**: recorded path outside the resolved root → warn (never block, never move); an explicit `worktree_root` is honored.
 
+**Primary checkout is welded to the default branch — all tiers** ([ADR-031](../docs/decisions/ADR-031-weld-primary-checkout-to-default-branch.md)). Its HEAD is shared across concurrent sessions; a `checkout -b` there silently redirects others' commits. Enforced (`git-dir == git-common-dir` scoped, never touches worktrees): `.claude/hooks/protect-primary-checkout.sh` (PreToolUse — denies branch create/switch/detach + hard-reset) + `.forge/git-hooks/pre-commit` (off-default-commit backstop; wired per-clone by `initializing`/`upgrading` via repo-relative `core.hooksPath`, detect+warn+never-clobber). Branch work: `.forge/bin/new-worktree.sh <slug>`. Escape: `ALLOW_MAIN_BRANCHING=1`.
+
 **`orchestration.worktree_hydrate`** (optional, `project.yml`; forge#18) lists superproject-relative paths to required-but-gitignored artifacts (e.g. `.mcp.json`) a fresh worktree's tracked-only checkout lacks. Copy is guarded `source-exists && dest-absent` — never overwrites, never `git add`s, so the secret stays untracked in both trees. Applied by `orchestrating` at creation and re-asserted idempotently in `executing`'s Workspace Prerequisites, covering worktrees of any origin. Omit ⇒ no propagation. The per-worktree runtime counterpart of the install-time carve-out propagation below (State Ownership § Stable shared).
 
 ## Workflow Tiers
@@ -99,7 +101,7 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | Break work into tasks with gates | `planning` | Standard, Full |
 | Build with deviation rules + atomic commits | `executing` | All |
 | Prove work delivers on goals (+ M9 e2e validation gate; captures the Human Verification Gate sign-off) | `verifying` | Standard, Full |
-| Audit health + catalog refactoring (+ M9 e2e audits; hard-blocks completion on the Human Verification Gate) | `reviewing` | Standard, Full |
+| Audit health + catalog refactoring (+ M9 e2e audits; hard-blocks completion on the Human Verification Gate) + close-the-loop (surface resolved-but-open issues) | `reviewing` | Standard, Full |
 | Small scoped fix | `quick-tasking` | Quick |
 | Rapid disposable UI mockup behind an alpha flag (no verify/review gate) | `prototyping` | Prototyping |
 | UI with design system | `designing` | When UI |
@@ -195,18 +197,19 @@ State lives in `.forge/`. One line per artifact; protocol detail lives in the na
 - `design-system.md` — component mapping table
 - `requirements/m{N}.yml` — per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. **FR/DEF/NFR ids are globally unique across all milestone files** — reserve via the ID Reservation Protocol before writing. M9 e2e gate fields (`e2e`, `observable_outcome`, `validated`, hash) lazy-migrate; absent ⇒ `false`.
 - `roadmap.yml` — phases, milestones, dependencies
-- `state/index.yml` — DERIVED milestone registry, **git-ignored render-on-read cache** (0.53.0): regenerated at every boot by Rollup 1.0 (`forge` SKILL Step 1.0) from the milestone files; never committed, never hand-edited, never written by worktree agents; absent on a fresh clone (the project sentinel is `project.yml`). Rows carry the derived `release_state`.
+- `state/index.yml` — DERIVED milestone registry, **git-ignored render-on-read cache** (0.53.0): regenerated at every boot from the milestone files by the **`forge-state-rollup.sh` SessionStart hook** (issue #22; skills only *read* it); never committed, never hand-edited. Rendered in any checkout (gitignored local write), but worktree agents never write *committed* derived-source state; absent on a fresh clone (sentinel is `project.yml`). Rows carry the derived `release_state`.
 - **Derived `release_state`** ([ADR-024](../docs/decisions/ADR-024-merged-validated-fold.md)) — `{unmerged, merged, validated}` computed at rollup by `.claude/hooks/forge-release-fold.sh` (git-only, offline; the fold binary is the only source — agent prose never re-derives it), never stored. Validation binding via `forge.validation_event`: `in_session_signoff` (default; absent ⇒ this) or `promotion_approval` (CI-signed `promotion/{sha}` tag). Inert until a repo opts in; full spec in ADR-024 + the fold header.
 - `state/milestone-{id}.yml` — per-milestone cursor (**single source of truth**): position, decisions, blockers. One owner at a time.
-- `state/desire-paths/` — append-only framework-usage observations, one file per observation, `scope: project|framework` (absent ⇒ project); occurrence counts derived by globbing. **`forge` boot is the single review owner** — surfaces groups at 3+, persists declines (no re-nag), routes `framework`-scope signals upstream ([ADR-012](../docs/decisions/ADR-012-upstream-desire-path-feedback-channel.md)); `verifying` captures but never surfaces.
+- `state/desire-paths/` — append-only framework-usage observations, one file per observation, `scope: project|framework` (absent ⇒ project); occurrence counts derived by globbing. **`forge` boot is the single review owner** — surfaces groups at 3+, persists declines (no re-nag), routes `framework`-scope signals upstream ([ADR-012](../docs/decisions/ADR-012-upstream-desire-path-feedback-channel.md)); `verifying` captures but never surfaces. An issue-sourced entry SHOULD carry a back-reference (`resolves_issue: N`; ADRs use `**Context source:** forge#N`) — close-the-loop keys off it.
 - `context.md` — active locked decisions + deferred ideas (≤12 KB); history archives to `context-archive.md`
-- `streams/active.yml` — DERIVED Project Chief traffic map, git-ignored render-on-read cache — see Stream Rollup below ([ADR-015](../docs/decisions/ADR-015-derived-stream-registry.md))
+- `streams/active.yml` — DERIVED Project Chief traffic map, git-ignored render-on-read cache, rendered by the same `forge-state-rollup.sh` hook — see Stream Rollup below ([ADR-015](../docs/decisions/ADR-015-derived-stream-registry.md))
 - `streams/{stream}.yml` (+ `brief.md`, `packages/{id}.yml`) — per-stream **source of truth**: coordination lifecycle, ownership, shared surfaces, blockers, merge readiness, optional `stream.milestone` link (milestone-backed streams omit workflow phase — the rollup reads it from the milestone)
 - `research/milestone-{id}.md` — dated immutable findings snapshot
 - `phases/milestone-{id}/{phase}-{name}/plan-{NN}.md` — task plans with must_haves frontmatter (`{id}`=milestone, `{phase}`=phase# verbatim, `{name}`=kebab, `{NN}`=seq)
 - `refactor-backlog.yml` — refactoring catalog worked via quick-tasking; status vocab `pending | in_progress | done | dismissed | deferred`; terminal items auto-archive to `refactor-backlog-archive.yml` on the next reviewing/quick-tasking write
 - `releases.yml` — append-only version-reservation registry (Version Reservation Protocol)
 - `reservations.yml` — append-only id-reservation audit trail + cross-machine floor (ID Reservation Protocol); `forge-reserve compact` (R104) moves dropped rows verbatim to `reservations-archive.yml`, retaining each kind's max + a 14-day tail
+- `state/issue-loop/declined/{N}.yml` — append-only close-the-loop decline markers; `reviewing` writes one when the operator declines a surfaced resolved-but-open issue (no re-nag). Inert once the issue closes.
 - `archive/milestone-{id}/` — archived milestone artifacts (archive-delete)
 - `prototypes/{slug}.md` — resumable disposable-mockup state (`exploring | parked | graduated | discarded`); terminal → `prototypes/archive/`. Single-owner, one driver. See `Skill(prototyping)`.
 
@@ -216,7 +219,7 @@ State lives in `.forge/`. One line per artifact; protocol detail lives in the na
 
 ### Stream Rollup
 
-`active.yml` is a pure projection — regenerated, never hand-edited — by a deterministic, idempotent **join**: per-stream files contribute coordination state; active milestones contribute `phase` (any active milestone with no stream file gets a derived `implicit` row — coverage is computed, not maintained); `merge_queue` derives from `merge.readiness: ready`. A **step-0 completed-stream auto-close sweep** runs first: a milestone-backed stream whose milestone is `complete`, not yet `closed`, with no live worktree is auto-closed — a done-and-merged milestone can never leave a zombie "ready to merge" row. Run by the main/orchestrator session at `forge` boot and `chief-of-staff` Show/Sync; worktrees never write it; milestone Rollup 1.0 runs **first** (the join reads the fresh `index.yml`). **Numbered procedure: the ADR-015 addendum.** Because each field has exactly one source and coverage is computed, two-registry drift cannot occur — supersedes the old advisory Registry Drift Check.
+`active.yml` is a pure projection by a deterministic, idempotent **join**: per-stream files contribute coordination state; active milestones contribute `phase` (any active milestone with no stream file gets a derived `implicit` row — coverage is computed, not maintained); `merge_queue` derives from `merge.readiness: ready`. A **step-0 completed-stream auto-close sweep** runs first: a milestone-backed stream whose milestone is `complete`, not yet `closed`, with no live worktree is auto-closed (no zombie "ready to merge" rows). Rendered by the same `forge-state-rollup.sh` hook (above) at boot and at `chief-of-staff` Show/Sync / mid-session milestone CRUD; it runs Rollup 1.0 **first** (the join reads the fresh `index.yml`), and confines the committed-source sweep to the main checkout. **Numbered procedure: the ADR-015 addendum.** Each field has exactly one source and coverage is computed, so two-registry drift cannot occur.
 
 ### State Commit Protocol
 

package/template/.forge/bin/new-worktree.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# One-command worktree for any commit-producing task (issue #21, ADR-031).
+#
+#   bash .forge/bin/new-worktree.sh <slug> [base-ref]
+#
+# Creates {worktree_root}/{slug} on branch forge/{slug} off origin/main (or [base-ref]).
+# The primary checkout's HEAD never moves — that is the whole point of the weld: branch
+# work lives in worktrees, each with its own independent HEAD, so concurrent sessions
+# never clobber each other's commits.
+#
+# worktree_root follows the FORGE.md Worktree Convention: `orchestration.worktree_root`
+# from .forge/project.yml, default `../<repo-basename>-worktrees/`. Relative paths resolve
+# against the repo root; absolute / ~ honored verbatim.
+
+set -euo pipefail
+
+SLUG=${1:?usage: new-worktree.sh <slug> [base-ref]}
+BASE=${2:-origin/main}
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+REPO_BASE=$(basename "$REPO_ROOT")
+
+# Resolve worktree_root from project.yml (light grep — no yaml dependency). The value
+# lives under an `orchestration:` block as `worktree_root: <path>`.
+WT_ROOT_CFG=$(grep -E '^[[:space:]]*worktree_root:' "$REPO_ROOT/.forge/project.yml" 2>/dev/null \
+  | head -1 | sed -E 's/^[[:space:]]*worktree_root:[[:space:]]*//; s/^["'\'']//; s/["'\'']$//; s/[[:space:]]*(#.*)?$//' || true)
+
+if [ -z "$WT_ROOT_CFG" ]; then
+  WORKTREE_ROOT="$(dirname "$REPO_ROOT")/${REPO_BASE}-worktrees"
+else
+  case "$WT_ROOT_CFG" in
+    /*)   WORKTREE_ROOT="$WT_ROOT_CFG" ;;                         # absolute — verbatim
+    "~"*) WORKTREE_ROOT="${WT_ROOT_CFG/#\~/$HOME}" ;;             # ~ — expand
+    *)    WORKTREE_ROOT="$REPO_ROOT/$WT_ROOT_CFG" ;;              # relative — against repo root
+  esac
+fi
+
+# Slashes in the slug become dashes in the directory name; the branch keeps the slash.
+DIR_NAME=$(printf '%s' "$SLUG" | tr '/' '-')
+WT_PATH="$WORKTREE_ROOT/$DIR_NAME"
+BRANCH="forge/$SLUG"
+
+if [ -e "$WT_PATH" ]; then
+  echo "✋ $WT_PATH already exists. Pick another slug or remove it first (git worktree remove)." >&2
+  exit 1
+fi
+
+mkdir -p "$WORKTREE_ROOT"
+# Best-effort refresh of origin/main so the worktree starts from current main; offline-safe.
+git fetch origin main --quiet 2>/dev/null || true
+git worktree add -b "$BRANCH" "$WT_PATH" "$BASE"
+
+echo ""
+echo "✅ Worktree ready"
+echo "   path:   $WT_PATH"
+echo "   branch: $BRANCH (from $BASE)"
+echo ""
+echo "   cd \"$WT_PATH\""
+echo ""
+echo "Reminders: run your install step after entering (worktrees don't share deps);"
+echo "the primary checkout stayed on its default branch — that is intentional."

package/template/.forge/bin/tests/new-worktree.test.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Scratch-repo tests for .forge/bin/new-worktree.sh (issue #21, ADR-031).
+#
+# Builds a throwaway repo with a committed HEAD, runs the helper (base ref = HEAD so no
+# network is needed), and asserts the worktree dir + branch it creates. Self-cleans. Run:
+#   ./.forge/bin/tests/new-worktree.test.sh
+# Prints `ALL PASS` and exits 0 iff every case passes; non-zero on any failure.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/../new-worktree.sh"
+[ -x "$HELPER" ] || { printf 'FATAL: helper not executable: %s\n' "$HELPER" >&2; exit 1; }
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+pass() { PASSED=$((PASSED + 1)); }
+fail() { FAILED=$((FAILED + 1)); printf '  FAIL: %s\n' "$1" >&2; }
+
+# A repo named so its default worktree_root is predictable: <base>-worktrees next to it.
+new_repo() {
+  local d="$ROOT/$1"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" symbolic-ref HEAD refs/heads/main
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name tester
+  mkdir -p "$d/.forge"
+  : > "$d/seed"
+  git -C "$d" add -A && git -C "$d" commit -qm init
+  printf '%s\n' "$d"
+}
+
+# ── Case 1: default worktree_root, simple slug ───────────────────────────────────
+R="$(new_repo proj)"
+( cd "$R" && "$HELPER" myslug HEAD ) >/dev/null 2>&1 || true
+WT="$ROOT/proj-worktrees/myslug"
+if [ -d "$WT" ]; then pass; else fail "case1: worktree dir not created at $WT"; fi
+br=$(git -C "$WT" branch --show-current 2>/dev/null || true)
+if [ "$br" = "forge/myslug" ]; then pass; else fail "case1: branch is '$br', want forge/myslug"; fi
+
+# ── Case 2: re-running the same slug errors (dir exists) ─────────────────────────
+if ( cd "$R" && "$HELPER" myslug HEAD ) >/dev/null 2>&1; then
+  fail "case2: duplicate slug should have errored (exit non-zero)"
+else
+  pass
+fi
+
+# ── Case 3: slug with a slash → dashed dir, slashed branch ───────────────────────
+R2="$(new_repo proj2)"
+( cd "$R2" && "$HELPER" feat/thing HEAD ) >/dev/null 2>&1 || true
+WT2="$ROOT/proj2-worktrees/feat-thing"
+if [ -d "$WT2" ]; then pass; else fail "case3: dashed dir not created at $WT2"; fi
+br2=$(git -C "$WT2" branch --show-current 2>/dev/null || true)
+if [ "$br2" = "forge/feat/thing" ]; then pass; else fail "case3: branch is '$br2', want forge/feat/thing"; fi
+
+# ── Case 4: configured relative worktree_root honored ────────────────────────────
+R3="$(new_repo proj3)"
+printf 'orchestration:\n  worktree_root: .wt\n' > "$R3/.forge/project.yml"
+git -C "$R3" add -A && git -C "$R3" commit -qm cfg
+( cd "$R3" && "$HELPER" wtslug HEAD ) >/dev/null 2>&1 || true
+WT3="$R3/.wt/wtslug"
+if [ -d "$WT3" ]; then pass; else fail "case4: configured worktree_root .wt not honored (want $WT3)"; fi
+
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+if [ "$FAILED" -eq 0 ]; then printf 'ALL PASS\n'; exit 0; fi
+exit 1

package/template/.forge/git-hooks/pre-commit

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Backstop for the primary-checkout branch weld (issue #21, ADR-031).
+#
+# Refuses commits made in the PRIMARY checkout while HEAD is not the default branch
+# (or is detached). The Claude PreToolUse hook (.claude/hooks/protect-primary-checkout.sh)
+# blocks branch create/switch at the source; this git hook catches anything that slips
+# past it — humans, non-agent tools, cd-inside-compound-command races — at the moment
+# damage would occur: a commit landing on a branch some other concurrent session owns.
+#
+# Linked worktrees are unaffected (git-dir != git-common-dir there — their own HEAD is
+# the whole point). Commits ON the default branch in the primary checkout remain allowed
+# by design — Forge's own state-sync commits land there.
+#
+# Default branch is resolved dynamically (main/master + init.defaultBranch), never
+# hardcoded. Fails OPEN on any git-probe error (a hook must not wedge commits on its own
+# malfunction). Exit 0 = allow the commit; exit 1 = abort it.
+#
+# Activate once per clone (done by initializing / upgrading):
+#   git config core.hooksPath .forge/git-hooks
+# Escape hatch (deliberate, human use): ALLOW_MAIN_BRANCHING=1 git commit ...
+
+set -uo pipefail
+
+[ "${ALLOW_MAIN_BRANCHING:-0}" = "1" ] && exit 0
+
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null) || exit 0
+COMMON_DIR=$(git rev-parse --git-common-dir 2>/dev/null) || exit 0
+GIT_DIR_ABS=$(cd "$GIT_DIR" 2>/dev/null && pwd) || exit 0
+COMMON_DIR_ABS=$(cd "$COMMON_DIR" 2>/dev/null && pwd) || exit 0
+
+# Linked worktree → its own HEAD; branch commits are the whole point. Allow.
+[ "$GIT_DIR_ABS" != "$COMMON_DIR_ABS" ] && exit 0
+
+# Default-branch set (dynamic — mirrors protect-primary-checkout.sh).
+DEFAULT_BRANCHES="main master"
+GIT_DEFAULT=$(git config --get init.defaultBranch 2>/dev/null || true)
+[ -n "$GIT_DEFAULT" ] && DEFAULT_BRANCHES="$DEFAULT_BRANCHES $GIT_DEFAULT"
+
+BRANCH=$(git branch --show-current 2>/dev/null || true)
+
+if [ -z "$BRANCH" ]; then
+  echo "✋ Commit blocked: detached HEAD in the primary checkout." >&2
+  echo "   Return to the default branch (git checkout main) or move this work to a worktree:" >&2
+  echo "   bash .forge/bin/new-worktree.sh <slug>" >&2
+  echo "   Human escape hatch: ALLOW_MAIN_BRANCHING=1 git commit ..." >&2
+  exit 1
+fi
+
+for b in $DEFAULT_BRANCHES; do
+  [ "$BRANCH" = "$b" ] && exit 0   # on the default branch → allowed (state-sync commits land here)
+done
+
+echo "✋ Commit blocked: the primary checkout must stay on the default branch (you are on '$BRANCH')." >&2
+echo "   Another concurrent session may own this branch — committing here is how work gets clobbered." >&2
+echo "   Branch work belongs in a worktree: bash .forge/bin/new-worktree.sh <slug>" >&2
+echo "   Human escape hatch: ALLOW_MAIN_BRANCHING=1 git commit ..." >&2
+exit 1

package/template/.forge/git-hooks/tests/pre-commit.test.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Scratch-repo scenario tests for .forge/git-hooks/pre-commit (issue #21 backstop).
+#
+# Each scenario builds a throwaway repo (and, where needed, a linked worktree), then
+# invokes the pre-commit hook directly from the target dir and asserts its exit code
+# (0 = commit allowed, 1 = commit aborted). No real `git commit` is needed — invoking
+# the hook is deterministic and fast. Self-cleans on exit. Run:
+#   ./.forge/git-hooks/tests/pre-commit.test.sh
+# Prints `ALL PASS` and exits 0 iff every scenario passes; non-zero on any failure.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HOOK="$SCRIPT_DIR/../pre-commit"
+[ -x "$HOOK" ] || { printf 'FATAL: pre-commit not executable: %s\n' "$HOOK" >&2; exit 1; }
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+
+new_repo() {
+  local d="$ROOT/$1" br="${2:-main}"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" symbolic-ref HEAD "refs/heads/$br"
+  [ "$br" != "main" ] && git -C "$d" config init.defaultBranch "$br"
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name tester
+  : > "$d/seed"
+  git -C "$d" add -A && git -C "$d" commit -qm init
+  printf '%s\n' "$d"
+}
+
+# run_hook <dir> [env-assignment] — run the pre-commit FROM <dir>, return its exit code.
+run_hook() {
+  local dir="$1" envset="${2:-}"
+  if [ -n "$envset" ]; then
+    ( cd "$dir" && env "$envset" "$HOOK" >/dev/null 2>&1 )
+  else
+    ( cd "$dir" && "$HOOK" >/dev/null 2>&1 )
+  fi
+  return $?
+}
+
+# assert <desc> <expected-exit> <dir> [env]
+assert() {
+  local desc="$1" want="$2" dir="$3" envset="${4:-}"
+  local got
+  run_hook "$dir" "$envset"; got=$?
+  if [ "$got" -eq "$want" ]; then
+    PASSED=$((PASSED + 1))
+  else
+    FAILED=$((FAILED + 1))
+    printf '  FAIL: %s (got exit %s, want %s)\n' "$desc" "$got" "$want" >&2
+  fi
+}
+
+ALLOW=0
+BLOCK=1
+
+# ── Scenario 1: primary checkout on the default branch → commit allowed ──────────
+P="$(new_repo primary)"
+assert "primary on main: commit allowed" "$ALLOW" "$P"
+
+# ── Scenario 2: primary checkout on a feature branch → commit blocked ────────────
+git -C "$P" checkout -q -b feature
+assert "primary on feature branch: commit blocked" "$BLOCK" "$P"
+
+# ── Scenario 5 (escape hatch, on the feature branch): allowed ───────────────────
+assert "escape hatch on feature branch: commit allowed" "$ALLOW" "$P" "ALLOW_MAIN_BRANCHING=1"
+git -C "$P" checkout -q main   # back home for later worktree add
+
+# ── Scenario 3: detached HEAD in the primary checkout → blocked ─────────────────
+D="$(new_repo detached)"
+git -C "$D" checkout -q --detach
+assert "primary detached HEAD: commit blocked" "$BLOCK" "$D"
+
+# ── Scenario 4: linked worktree on a feature branch → allowed ────────────────────
+WT="$ROOT/primary-wt"
+git -C "$P" worktree add -q -b wtbranch "$WT" >/dev/null 2>&1
+assert "linked worktree on feature branch: commit allowed" "$ALLOW" "$WT"
+
+# ── Bonus: master-default repo on master → allowed; on a branch → blocked ────────
+M="$(new_repo master-primary master)"
+assert "master-default on master: commit allowed" "$ALLOW" "$M"
+git -C "$M" checkout -q -b feat
+assert "master-default on feature branch: commit blocked" "$BLOCK" "$M"
+
+# ── Summary ──────────────────────────────────────────────────────────────────────
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+if [ "$FAILED" -eq 0 ]; then
+  printf 'ALL PASS (incl. escape hatch)\n'
+  exit 0
+fi
+exit 1

package/template/.forge/migrations/0.77.0-state-rollup-executable.md

@@ -0,0 +1,120 @@
+# Migration Guide: State rollup made mechanical (Forge 0.77.0)
+
+Applies to projects upgrading to 0.77.0 or later. State Rollup 1.0 and the
+Stream Rollup (ADR-015 addendum) — previously advisory skill prose that an
+agent had to remember to run at boot — are now an executable,
+`.claude/hooks/forge-state-rollup.sh`, invoked mechanically by a `SessionStart`
+hook. A boot session can no longer skip the render and fall back to reading a
+stale `.forge/state/index.yml` / `.forge/streams/active.yml` cache, or
+hand-reconstruct the registries from memory — the exact failure mode filed as
+issue #22.
+
+`/upgrading` ships the new hook file (`.claude/hooks/forge-state-rollup.sh`)
+like any other framework file. It does **not** wire the `SessionStart`
+registration, because `.claude/settings.json` is a **user-owned file** —
+upgrades never overwrite it (FORGE.md → State Ownership, "Stable shared"
+class notes settings.json is gitignored-carve-out territory, propagated only
+via explicit installer steps, never blanket overwrite). Without this
+migration's one manual step, the hook ships but is never invoked: the
+executable exists, nothing mechanically triggers it.
+
+Projects that ran `initializing` fresh on 0.77.0+ (or already carry the
+`SessionStart` block from an earlier partial adoption) need nothing further.
+
+## Prerequisites
+
+1. On the new version's framework files (`npx forge-orkes upgrade`, or the
+   `upgrading` skill) — so `.claude/hooks/forge-state-rollup.sh` and
+   `.claude/hooks/forge-release-fold.sh` are present and executable.
+2. Working tree clean or changes committed — this migration edits
+   `.claude/settings.json`, a tracked file.
+
+## Detection
+
+Keyed on **the executable existing (or the version already at/above 0.77.0)
+while the SessionStart wiring is absent** — the shipped-but-unwired gap. Uses
+`jq` to inspect `.claude/settings.json`'s `hooks.SessionStart` array for an
+entry referencing `forge-state-rollup`; degrades to a plain-text grep if `jq`
+is not installed. Silent in a non-Forge / non-git tree, silent once the hook
+is wired:
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+[ -x .claude/hooks/forge-state-rollup.sh ] || exit 0
+
+settings=".claude/settings.json"
+[ -f "$settings" ] || {
+  echo "MIGRATE — forge-state-rollup.sh is present but $settings does not exist; add it with the SessionStart hook below"
+  exit 0
+}
+
+if command -v jq >/dev/null 2>&1; then
+  wired="$(jq -r '
+    (.hooks.SessionStart // []) as $entries
+    | [$entries[].hooks[]?.command // "" | select(contains("forge-state-rollup"))]
+    | length > 0
+  ' "$settings" 2>/dev/null)"
+  if [ "$wired" != "true" ]; then
+    echo "MIGRATE — $settings has no SessionStart hook referencing forge-state-rollup.sh; the executable shipped but nothing mechanically triggers it"
+  fi
+else
+  if ! grep -q "forge-state-rollup" "$settings" 2>/dev/null; then
+    echo "MIGRATE — $settings has no reference to forge-state-rollup.sh (jq unavailable, ran plain-text check); add the SessionStart hook below"
+  fi
+fi
+```
+
+## Migration steps
+
+### 1. Add the SessionStart hook block
+
+Open `.claude/settings.json` and add (or merge into) a `hooks.SessionStart`
+array entry:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/forge-state-rollup.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/forge-state-rollup.sh\" || true"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If `hooks.SessionStart` already has other entries (e.g. from a project-local
+customization), append this object to the existing array rather than
+replacing it. If `hooks` exists but has no `SessionStart` key yet, add the key
+alongside the existing `PreToolUse`/`PostToolUse` blocks.
+
+The `[ -x ... ] && ... || true` guard means the hook is a no-op — never a
+boot failure — on any checkout where the script is absent or not executable
+(SessionStart hooks are non-blocking; `forge-state-rollup.sh` itself also
+always exits 0).
+
+### 2. Commit the settings change
+
+```bash
+git add .claude/settings.json
+git commit -m "chore(forge): wire forge-state-rollup SessionStart hook (0.77.0)"
+```
+
+## Validation
+
+- Start a new session, or run `/clear` — the boot summary line should include
+  `[forge-state-rollup] rendered index.yml (…) …` (plus an `active.yml` clause
+  if `.forge/streams/` exists), confirming the hook actually ran.
+- `jq '.hooks.SessionStart' .claude/settings.json` prints a non-null array
+  containing the `forge-state-rollup` command, not `null`.
+- Re-running the Detection block above now prints nothing (exits silently) —
+  the gap is closed.
+- `.forge/state/index.yml` and `.forge/streams/active.yml` (if applicable)
+  exist on disk and are fresh — their mtimes update on every boot, since the
+  hook re-renders unconditionally.

package/template/.forge/migrations/0.78.0-weld-primary-checkout.md

@@ -0,0 +1,66 @@
+# Migration Guide: Weld the primary checkout to the default branch (Forge 0.78.0)
+
+Applies to projects installed before 0.78.0. This milestone (issue #21, ADR-031) welds the primary checkout to its default branch across ALL tiers: a PreToolUse guard denies branch create/switch there, a tracked git `pre-commit` backstop refuses off-default commits there, and a `new-worktree` helper teaches the right path. The `/upgrading` run that installed this guide already synced the hook bodies (`.claude/hooks/protect-primary-checkout.sh`, `.forge/git-hooks/pre-commit`, `.forge/bin/new-worktree.sh`) and merged the settings.json wiring; the one remaining per-clone step is the `core.hooksPath` wiring, which `/upgrading` applies with a detect+warn+never-clobber policy.
+
+## Prerequisites
+
+1. Nothing to hand-edit — the upgrade sync + the `/upgrading` `core.hooksPath` layer ARE the migration.
+2. If you use Husky / lefthook / a pre-commit framework (i.e. `core.hooksPath` is already set), the wiring will NOT overwrite it — you'll get a warning and can chain `.forge/git-hooks/pre-commit` into your existing hooks dir, or accept PreToolUse-only coverage.
+
+## Detection
+
+Prints `MIGRATE` when the primary-checkout weld is not fully wired: the PreToolUse guard is absent from `settings.json`, OR the tracked pre-commit backstop is missing, OR `core.hooksPath` is not pointing at `.forge/git-hooks`. Silent + exit 0 when fully wired.
+
+```bash
+migrate=""
+# (1) PreToolUse guard wired in settings.json?
+if [ -f .claude/settings.json ]; then
+  if ! grep -q 'protect-primary-checkout' .claude/settings.json 2>/dev/null; then
+    migrate="guard not wired in settings.json"
+  fi
+fi
+# (2) tracked pre-commit backstop present?
+if [ ! -f .forge/git-hooks/pre-commit ]; then
+  migrate="${migrate:+$migrate; }pre-commit backstop missing (.forge/git-hooks/pre-commit)"
+fi
+# (3) core.hooksPath wired to our dir? (advisory — /upgrading applies this)
+cur=$(git config --get core.hooksPath 2>/dev/null || true)
+if [ "$cur" != ".forge/git-hooks" ]; then
+  migrate="${migrate:+$migrate; }core.hooksPath not '.forge/git-hooks' (currently '${cur:-unset}')"
+fi
+if [ -n "$migrate" ]; then
+  echo "MIGRATE — primary-checkout weld incomplete: $migrate"
+fi
+```
+
+## Migration steps
+
+### 1. Re-run the upgrade / initialize
+
+- `/upgrading` on 0.78.0+ framework files syncs the hooks, merges the settings.json guard group, and applies the `core.hooksPath` wiring layer (detect+warn+never-clobber). The run that installed this guide already did the file sync; the `core.hooksPath` layer is what completes the weld.
+- On a brand-new project, `initializing` Finalize wires `core.hooksPath` as part of setup.
+
+### 2. If `core.hooksPath` was already set (Husky/lefthook)
+
+The wiring will not overwrite it. To keep the pre-commit weld active, chain the Forge hook into your existing hooks directory — e.g. add to your `pre-commit`:
+
+```bash
+# run the Forge primary-checkout backstop, if present
+[ -x .forge/git-hooks/pre-commit ] && .forge/git-hooks/pre-commit || true
+```
+
+Or accept PreToolUse-only coverage: Claude sessions are still guarded by `protect-primary-checkout.sh`; only the human/CI backstop is inactive.
+
+### 3. Verify
+
+From the primary checkout on the default branch:
+
+```bash
+# guard denies branch create (exit 2) — run it directly against a payload:
+printf '{"tool_input":{"command":"git checkout -b probe"},"cwd":"'"$(git rev-parse --show-toplevel)"'"}' \
+  | .claude/hooks/protect-primary-checkout.sh; echo "exit=$? (expect 2 in the PRIMARY checkout)"
+# pre-commit allows on the default branch:
+.forge/git-hooks/pre-commit; echo "exit=$? (expect 0 on the default branch)"
+```
+
+All branch work now goes through `bash .forge/bin/new-worktree.sh <slug>`. Escape hatch for deliberate human branching: `ALLOW_MAIN_BRANCHING=1`.

package/template/.forge/templates/state/desire-path.yml

@@ -7,6 +7,9 @@ type: ""                              # recurring_friction | agent_struggle | us
 date: ""                              # ISO 8601 date the observation was made, e.g. "2026-07-23"
 milestone: ""                         # milestone id, or a short label for non-milestone work (e.g. "quick-task (...)")
 scope: project                        # project | framework — absent ⇒ project (this repo only; framework ⇒ upstream-eligible per ADR-012)
+# resolves_issue: 26                 # OPTIONAL — GitHub issue number this observation's fix resolves. The
+#                                    # close-the-loop check (reviewing) keys off it to surface the issue as
+#                                    # likely-closable once the fix ships. Omit when the observation resolves no issue.
 suggestion_target: ""                 # the file/skill this observation would change if acted on
 note: >
   What was observed — concrete enough that a future review can judge recurrence