forge-orkes 0.77.0 → 0.79.0

package/bin/create-forge.js

@@ -124,6 +124,24 @@ function makeHookScriptsExecutable(hooksDir) {
   try { walk(hooksDir); } catch { /* best-effort */ }
 }
 
+/**
+ * Make the tracked git hooks under .forge/git-hooks/ executable (issue #21 / ADR-031).
+ * These are git hooks (pre-commit, …) with NO .sh extension, so makeHookScriptsExecutable
+ * (which only chmods *.sh) misses them — chmod them explicitly. Best-effort; never throws.
+ * NOTE: this function deliberately does NO `git config core.hooksPath` — per-clone wiring
+ * (with the Husky/lefthook conflict warning) is owned by the initializing/upgrading skills,
+ * not the installer, which stays git-config-free and runs unattended in CI.
+ */
+function makeGitHooksExecutable(forgeDir) {
+  const gitHooksDir = path.join(forgeDir, 'git-hooks');
+  if (!fs.existsSync(gitHooksDir)) return;
+  for (const entry of fs.readdirSync(gitHooksDir, { withFileTypes: true })) {
+    if (entry.isFile() && !entry.name.startsWith('.')) {
+      try { fs.chmodSync(path.join(gitHooksDir, entry.name), 0o755); } catch { /* best-effort */ }
+    }
+  }
+}
+
 /**
  * Additively sync a framework-managed `.claude/` dir into an existing project on
  * upgrade (ADR-017/018). Copies/updates the template's files, but NEVER deletes
@@ -498,6 +516,7 @@ async function install() {
   const srcForge = path.join(templateDir, '.forge');
   const destForge = path.join(targetDir, '.forge');
   const forgeCount = copyDirRecursive(srcForge, destForge);
+  makeGitHooksExecutable(destForge); // extensionless git hooks (.forge/git-hooks/pre-commit)
   console.log(`  Installed .forge/templates/ (${forgeCount} files)`);
 
   // npm strips files literally named `.gitignore` from the published tarball, so
@@ -858,6 +877,14 @@ async function upgrade() {
   //    protected set (.forge/checks/**) can guard them. Additive for the same
   //    reason as above: never delete a project-local extra check.
   upgradeAdditiveDir('.forge/checks', results);
+  // 2-git-hooks. Sync the tracked git hooks (issue #21 / ADR-031: the primary-checkout
+  //    weld pre-commit backstop). Tracked at .forge/git-hooks/ for the same reason as
+  //    .forge/checks/ — .claude/hooks/ is commonly gitignored, and a git hook must be
+  //    tracked to run for humans/CI. Additive; then chmod the extensionless hooks
+  //    (upgradeAdditiveDir only +x's *.sh). Per-clone core.hooksPath wiring is the
+  //    initializing/upgrading skills' job, NOT the installer's — see makeGitHooksExecutable.
+  upgradeAdditiveDir('.forge/git-hooks', results);
+  makeGitHooksExecutable(path.join(targetDir, '.forge'));
 
   // 2a. Confirm stale framework-file removals before deleting (R066a). Defaults
   //     to yes (cleanup is the normal case); auto-confirms when non-interactive

package/experimental/m10/README.md

@@ -55,7 +55,7 @@ Idempotent — re-running emits warnings instead of errors.
 If you'd rather see exactly what changes:
 
 1. Copy `source/mcp-server/` → `<target>/.forge/.mcp-server/`
-2. Copy `source/hooks/forge-claim-check.sh`, `source/hooks/forge-claim-check-doctor.sh`, `source/hooks/forge-session-id.sh`, and `source/hooks/forge-branch-guard.sh` → `<target>/.claude/hooks/` (`chmod +x`)
+2. Copy `source/hooks/forge-claim-check.sh`, `source/hooks/forge-claim-check-doctor.sh`, `source/hooks/forge-session-id.sh`, and `source/hooks/protect-primary-checkout.sh` → `<target>/.claude/hooks/` (`chmod +x`)
 3. Copy `source/skills/orchestrating/` → `<target>/.claude/skills/orchestrating/`
 4. Merge `forge-orchestrator` entry into `<target>/.mcp.json`:
    ```json
@@ -71,12 +71,12 @@ If you'd rather see exactly what changes:
      { "hooks": [{ "type": "command", "command": ".claude/hooks/forge-session-id.sh" }] }
    ]
    ```
-   Also add the branch-discipline guardrail under `PreToolUse`:
+   Also add the primary-checkout guardrail under `PreToolUse`:
    ```json
    { "matcher": "Bash",
-     "hooks": [{ "type": "command", "command": ".claude/hooks/forge-branch-guard.sh" }] }
+     "hooks": [{ "type": "command", "command": ".claude/hooks/protect-primary-checkout.sh" }] }
    ```
-   The SessionStart hook captures the Claude session id (claim identity); without it the enforcement gate fail-opens (ADR-007). The branch-guard protects the shared main HEAD when worktrees are active (ADR-008) — orchestration-agnostic, independent of the claim layer.
+   The SessionStart hook captures the Claude session id (claim identity); without it the enforcement gate fail-opens (ADR-007). The primary-checkout guard welds the primary checkout to the default branch — all branch work happens in worktrees (issue #21, ADR-031) — orchestration-agnostic, independent of the claim layer. It supersedes the old forge-branch-guard.sh (ADR-008) and folds in its hard-reset protection.
 6. `cd <target>/.forge/.mcp-server && npm install`
 
 ## Verify

package/experimental/m10/install.sh

@@ -72,7 +72,7 @@ echo
 # Step 3: copy hooks
 echo "==> Hooks → .claude/hooks/"
 do_or_say "mkdir -p '$TARGET/.claude/hooks'"
-for h in forge-claim-check.sh forge-claim-check-doctor.sh forge-session-id.sh forge-branch-guard.sh; do
+for h in forge-claim-check.sh forge-claim-check-doctor.sh forge-session-id.sh protect-primary-checkout.sh; do
   if [[ -f "$TARGET/.claude/hooks/$h" ]]; then
     say "skip: $h already exists"
   else
@@ -161,21 +161,22 @@ else
 fi
 echo
 
-# Step 6c: register branch-discipline guardrail (PreToolUse on Bash). Orchestration-
-# agnostic — protects the shared main HEAD whenever >1 worktree exists.
-echo "==> .claude/settings.json branch-guard hook"
-BG_CMD='.claude/hooks/forge-branch-guard.sh'
+# Step 6c: register the primary-checkout branch weld (PreToolUse on Bash). Welds the
+# primary checkout to the default branch — all branch work happens in worktrees (issue
+# #21). Orchestration-agnostic; supersedes the old forge-branch-guard.sh.
+echo "==> .claude/settings.json primary-checkout guard hook"
+BG_CMD='.claude/hooks/protect-primary-checkout.sh'
 if [[ ! -f "$SETTINGS" ]]; then
-  say "[dry-run] settings.json not yet created — branch-guard would be added alongside the others"
+  say "[dry-run] settings.json not yet created — primary-checkout guard would be added alongside the others"
 elif jq -e --arg cmd "$BG_CMD" '.hooks.PreToolUse[]?.hooks[]? | select(.command == $cmd)' "$SETTINGS" >/dev/null 2>&1; then
-  say "skip: forge-branch-guard.sh hook already registered"
+  say "skip: protect-primary-checkout.sh hook already registered"
 else
   if [[ $DRY_RUN -eq 0 ]]; then
     tmp=$(mktemp)
-    jq '.hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":".claude/hooks/forge-branch-guard.sh"}]}]' "$SETTINGS" > "$tmp"
+    jq '.hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":".claude/hooks/protect-primary-checkout.sh"}]}]' "$SETTINGS" > "$tmp"
     mv "$tmp" "$SETTINGS"
   fi
-  say "appended branch-guard PreToolUse(Bash) hook entry"
+  say "appended primary-checkout guard PreToolUse(Bash) hook entry"
 fi
 echo
 

package/experimental/m10/source/hooks/protect-primary-checkout.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Weld the primary checkout to the default branch — deny branch create/switch there.
+#
+# PreToolUse(Bash) hook. Exit 2 (+ JSON permissionDecision:deny) = block. Exit 0 = allow.
+#
+# WHY: the primary checkout's HEAD is shared mutable state across every concurrent
+# Claude session running in that directory. One session running `git checkout -b`
+# silently redirects every OTHER session's subsequent commits onto its branch — an
+# invisible clobber that surfaces later as wrong-branch commits, contaminated PRs,
+# stranded milestone state, or dropped history (issue #21: 3 confirmed incidents —
+# m85's 12-commit drop, m62's stranded phase commits, a Quick-tier checkout -b that
+# contaminated a concurrent PR). Branch work belongs in worktrees, which each own
+# their own HEAD.
+#
+# Scope: fires ONLY in the primary checkout (git-dir == git-common-dir). Linked
+# worktrees are unaffected (their git-dir differs). Unlike the dormant
+# forge-branch-guard.sh this supersedes, the branch weld is UNCONDITIONAL — it fires
+# even when no sibling worktree exists yet, because the second session's worktree is
+# typically created AFTER the offending `checkout -b`. This hook also folds in the
+# one distinct protection the old guard provided: denying a hard-reset in the primary
+# checkout while sibling worktrees are branched off it (the history-rewrite class).
+#
+# Default branch is resolved dynamically (main/master + init.defaultBranch), never
+# hardcoded — Forge ships to repos on any default branch.
+#
+# Fails OPEN (exit 0 / allow) on any malfunction (no jq, empty command, non-git cwd,
+# git probe error) — a guard must never wedge the agent on its own failure.
+#
+# Escape hatch (deliberate, human use): ALLOW_MAIN_BRANCHING=1
+
+set -uo pipefail
+
+emit_deny() {
+  local reason="${1//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
+  exit 2
+}
+
+[ "${ALLOW_MAIN_BRANCHING:-0}" = "1" ] && exit 0
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+[ -z "$COMMAND" ] && exit 0
+
+# Normalize the cheapest whitespace-substitution evasion (`git checkout$IFS-b`) to a
+# real space before matching. A string matcher on an un-expanded shell command can
+# never be complete against expansion — the pre-commit backstop is the sound layer —
+# but closing the trivial $IFS trick keeps the PreToolUse layer honest.
+COMMAND=$(printf '%s' "$COMMAND" | sed -E 's/\$\{?IFS\}?/ /g')
+
+# Git allows global options BEFORE the subcommand: `git -c k=v checkout`,
+# `git --no-pager switch`, `git -C <path> -p checkout`, etc. The guard must tolerate
+# ANY run of them, not just a single `-C <path>` — otherwise `git -c x=y checkout -b`
+# sails past (issue #21 regression). GITPRE matches `git` + zero-or-more global options
+# (a `-x`/`--long`/`--long=val`/`-C <path>`/`-c <kv>` token, each optionally taking the
+# next word as its value) up to the subcommand.
+GITPRE='git[[:space:]]+((-[A-Za-z]|--[A-Za-z-]+)(=[^[:space:]]+)?[[:space:]]+([^-][^[:space:]]*[[:space:]]+)?)*'
+
+# Fast path: only inspect commands that touch checkout/switch/reset at all. Anything
+# else exits immediately WITHOUT any git probe (keeps the hook cheap on every Bash call).
+printf '%s' "$COMMAND" | grep -qE "${GITPRE}(checkout|switch|reset)([[:space:]]|\$)" || exit 0
+
+# Resolve which repo dir the command targets: honor `git -C <path>`, else the hook cwd.
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+[ -z "$CWD" ] && CWD=$(pwd)
+# Honor a GLOBAL `git -C <path>` (before the subcommand) only. Isolate the pre-subcommand
+# segment first so `switch -C`/`checkout -C` (create-force, AFTER the subcommand) is never
+# mistaken for a target-dir option.
+PRE=$(printf '%s' "$COMMAND" | sed -E 's/[[:space:]](checkout|switch|reset)[[:space:]].*$//')
+GC_PATH=$(printf '%s' "$PRE" | grep -oE '(^|[[:space:]])-C[[:space:]]+[^[:space:]]+' | head -1 | awk '{print $2}' || true)
+# A flag-shaped -C value (e.g. `-C --foo`) is not a real target dir → ignore it.
+case "$GC_PATH" in -*) GC_PATH="" ;; esac
+TARGET_DIR="${GC_PATH:-$CWD}"
+
+GIT_DIR=$(git -C "$TARGET_DIR" rev-parse --git-dir 2>/dev/null) || exit 0
+COMMON_DIR=$(git -C "$TARGET_DIR" rev-parse --git-common-dir 2>/dev/null) || exit 0
+GIT_DIR_ABS=$(cd "$TARGET_DIR" 2>/dev/null && cd "$GIT_DIR" 2>/dev/null && pwd) || exit 0
+COMMON_DIR_ABS=$(cd "$TARGET_DIR" 2>/dev/null && cd "$COMMON_DIR" 2>/dev/null && pwd) || exit 0
+
+# In a linked worktree git-dir != git-common-dir → branch ops are fine there.
+[ "$GIT_DIR_ABS" != "$COMMON_DIR_ABS" ] && exit 0
+
+# ── Default-branch set (dynamic — mirrors block-dangerous-commands.sh) ───────────
+# Seed main+master, add the configured init.defaultBranch. A switch/checkout TO any
+# of these names is "returning home" and always allowed.
+DEFAULT_BRANCHES="main master"
+GIT_DEFAULT=$(git -C "$TARGET_DIR" config --get init.defaultBranch 2>/dev/null || true)
+[ -n "$GIT_DEFAULT" ] && DEFAULT_BRANCHES="$DEFAULT_BRANCHES $GIT_DEFAULT"
+is_default_branch() {
+  for b in $DEFAULT_BRANCHES; do [ "$1" = "$b" ] && return 0; done
+  return 1
+}
+
+DENY_MSG="Blocked: the primary checkout's HEAD stays on the default branch — branch create/switch here silently redirects every other concurrent session's commits onto your branch (recurring clobber, issue #21). Do branch work in a worktree: bash .forge/bin/new-worktree.sh <slug> (or git worktree add). To operate on an existing worktree from here, use git -C <worktree-path>. Human escape hatch: ALLOW_MAIN_BRANCHING=1."
+
+# ── 1) Branch creation / orphan / detach / track: always deny in primary checkout ──
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}checkout[[:space:]]+((-[a-zA-Z]*[bB][a-zA-Z]*|--orphan|--detach|--track)([[:space:]=]|\$))"; then
+  emit_deny "$DENY_MSG"
+fi
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}switch[[:space:]]+((-[cC]|--create|--force-create|--orphan|--detach|--track)([[:space:]=]|\$))"; then
+  emit_deny "$DENY_MSG"
+fi
+
+# ── 2) hard/keep/merge reset in the primary checkout while worktrees are branched ──
+# Folded from the superseded forge-branch-guard.sh: a reset that rewrites HEAD +
+# working tree here can drop verified work committed under sibling worktrees. Gated
+# on >1 worktree (unlike the branch weld, which is unconditional).
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}reset[[:space:]]+(--hard|--keep|--merge)([[:space:]]|\$)"; then
+  wt_count=$(git -C "$TARGET_DIR" worktree list 2>/dev/null | wc -l | tr -d ' ')
+  if [ "${wt_count:-1}" -gt 1 ]; then
+    emit_deny "Refusing to move the shared primary HEAD via reset — $wt_count worktrees are branched off it (the 'burned twice' history-rewrite failure, issue #21). Reset inside a worktree, or stop the other sessions first. Human escape hatch: ALLOW_MAIN_BRANCHING=1."
+  fi
+  exit 0   # single-worktree hard-reset is the operator's own business — allow.
+fi
+
+# ── 3) checkout/switch to a ref other than the default branch ───────────────────
+# Only checkout/switch move HEAD to a ref. A reset that reached this far (--soft /
+# --mixed, or a hard/keep/merge reset in a single-worktree repo) is not a branch move
+# off the default → allow it and stop.
+printf '%s' "$COMMAND" | grep -qE "${GITPRE}(checkout|switch)([[:space:]]|\$)" || exit 0
+
+# `git checkout <ref> -- <paths>` and `git checkout -- <paths>` never move HEAD →
+# allow anything containing a ` -- ` pathspec separator.
+printf '%s' "$COMMAND" | grep -qE '[[:space:]]--([[:space:]]|$)' && exit 0
+
+# Extract the first non-flag argument after checkout/switch. Strip everything up to and
+# including the subcommand keyword — whatever git global options preceded it (`-c`,
+# `--no-pager`, `-C <path>`, …) are consumed by the greedy prefix. The trailing separator
+# is optional so a BARE `git checkout` (no target) yields empty ARGS → allowed below.
+ARGS=$(printf '%s' "$COMMAND" | sed -E 's/.*[[:space:]](checkout|switch)([[:space:]]+|$)/ /' | head -1)
+FIRST_REF=""
+for word in $ARGS; do
+  case "$word" in
+    -*) continue ;;                     # flags (creation flags already denied above)
+    \;|\&\&|\|\||\||\&) break ;;        # end of this git command
+    *) FIRST_REF="$word"; break ;;
+  esac
+done
+
+# Bare `git checkout`/`git switch` (no target) is a no-op/error → allow.
+[ -z "$FIRST_REF" ] && exit 0
+
+# Returning home (default branch) or file-restore forms → allow. Any other ref → deny.
+case "$FIRST_REF" in
+  HEAD|.) exit 0 ;;                      # file restore forms
+  *) is_default_branch "$FIRST_REF" && exit 0 || emit_deny "$DENY_MSG" ;;
+esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.77.0",
+  "version": "0.79.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/hooks/protect-primary-checkout.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Weld the primary checkout to the default branch — deny branch create/switch there.
+#
+# PreToolUse(Bash) hook. Exit 2 (+ JSON permissionDecision:deny) = block. Exit 0 = allow.
+#
+# WHY: the primary checkout's HEAD is shared mutable state across every concurrent
+# Claude session running in that directory. One session running `git checkout -b`
+# silently redirects every OTHER session's subsequent commits onto its branch — an
+# invisible clobber that surfaces later as wrong-branch commits, contaminated PRs,
+# stranded milestone state, or dropped history (issue #21: 3 confirmed incidents —
+# m85's 12-commit drop, m62's stranded phase commits, a Quick-tier checkout -b that
+# contaminated a concurrent PR). Branch work belongs in worktrees, which each own
+# their own HEAD.
+#
+# Scope: fires ONLY in the primary checkout (git-dir == git-common-dir). Linked
+# worktrees are unaffected (their git-dir differs). Unlike the dormant
+# forge-branch-guard.sh this supersedes, the branch weld is UNCONDITIONAL — it fires
+# even when no sibling worktree exists yet, because the second session's worktree is
+# typically created AFTER the offending `checkout -b`. This hook also folds in the
+# one distinct protection the old guard provided: denying a hard-reset in the primary
+# checkout while sibling worktrees are branched off it (the history-rewrite class).
+#
+# Default branch is resolved dynamically (main/master + init.defaultBranch), never
+# hardcoded — Forge ships to repos on any default branch.
+#
+# Fails OPEN (exit 0 / allow) on any malfunction (no jq, empty command, non-git cwd,
+# git probe error) — a guard must never wedge the agent on its own failure.
+#
+# Escape hatch (deliberate, human use): ALLOW_MAIN_BRANCHING=1
+
+set -uo pipefail
+
+emit_deny() {
+  local reason="${1//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
+  exit 2
+}
+
+[ "${ALLOW_MAIN_BRANCHING:-0}" = "1" ] && exit 0
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+[ -z "$COMMAND" ] && exit 0
+
+# Normalize the cheapest whitespace-substitution evasion (`git checkout$IFS-b`) to a
+# real space before matching. A string matcher on an un-expanded shell command can
+# never be complete against expansion — the pre-commit backstop is the sound layer —
+# but closing the trivial $IFS trick keeps the PreToolUse layer honest.
+COMMAND=$(printf '%s' "$COMMAND" | sed -E 's/\$\{?IFS\}?/ /g')
+
+# Git allows global options BEFORE the subcommand: `git -c k=v checkout`,
+# `git --no-pager switch`, `git -C <path> -p checkout`, etc. The guard must tolerate
+# ANY run of them, not just a single `-C <path>` — otherwise `git -c x=y checkout -b`
+# sails past (issue #21 regression). GITPRE matches `git` + zero-or-more global options
+# (a `-x`/`--long`/`--long=val`/`-C <path>`/`-c <kv>` token, each optionally taking the
+# next word as its value) up to the subcommand.
+GITPRE='git[[:space:]]+((-[A-Za-z]|--[A-Za-z-]+)(=[^[:space:]]+)?[[:space:]]+([^-][^[:space:]]*[[:space:]]+)?)*'
+
+# Fast path: only inspect commands that touch checkout/switch/reset at all. Anything
+# else exits immediately WITHOUT any git probe (keeps the hook cheap on every Bash call).
+printf '%s' "$COMMAND" | grep -qE "${GITPRE}(checkout|switch|reset)([[:space:]]|\$)" || exit 0
+
+# Resolve which repo dir the command targets: honor `git -C <path>`, else the hook cwd.
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+[ -z "$CWD" ] && CWD=$(pwd)
+# Honor a GLOBAL `git -C <path>` (before the subcommand) only. Isolate the pre-subcommand
+# segment first so `switch -C`/`checkout -C` (create-force, AFTER the subcommand) is never
+# mistaken for a target-dir option.
+PRE=$(printf '%s' "$COMMAND" | sed -E 's/[[:space:]](checkout|switch|reset)[[:space:]].*$//')
+GC_PATH=$(printf '%s' "$PRE" | grep -oE '(^|[[:space:]])-C[[:space:]]+[^[:space:]]+' | head -1 | awk '{print $2}' || true)
+# A flag-shaped -C value (e.g. `-C --foo`) is not a real target dir → ignore it.
+case "$GC_PATH" in -*) GC_PATH="" ;; esac
+TARGET_DIR="${GC_PATH:-$CWD}"
+
+GIT_DIR=$(git -C "$TARGET_DIR" rev-parse --git-dir 2>/dev/null) || exit 0
+COMMON_DIR=$(git -C "$TARGET_DIR" rev-parse --git-common-dir 2>/dev/null) || exit 0
+GIT_DIR_ABS=$(cd "$TARGET_DIR" 2>/dev/null && cd "$GIT_DIR" 2>/dev/null && pwd) || exit 0
+COMMON_DIR_ABS=$(cd "$TARGET_DIR" 2>/dev/null && cd "$COMMON_DIR" 2>/dev/null && pwd) || exit 0
+
+# In a linked worktree git-dir != git-common-dir → branch ops are fine there.
+[ "$GIT_DIR_ABS" != "$COMMON_DIR_ABS" ] && exit 0
+
+# ── Default-branch set (dynamic — mirrors block-dangerous-commands.sh) ───────────
+# Seed main+master, add the configured init.defaultBranch. A switch/checkout TO any
+# of these names is "returning home" and always allowed.
+DEFAULT_BRANCHES="main master"
+GIT_DEFAULT=$(git -C "$TARGET_DIR" config --get init.defaultBranch 2>/dev/null || true)
+[ -n "$GIT_DEFAULT" ] && DEFAULT_BRANCHES="$DEFAULT_BRANCHES $GIT_DEFAULT"
+is_default_branch() {
+  for b in $DEFAULT_BRANCHES; do [ "$1" = "$b" ] && return 0; done
+  return 1
+}
+
+DENY_MSG="Blocked: the primary checkout's HEAD stays on the default branch — branch create/switch here silently redirects every other concurrent session's commits onto your branch (recurring clobber, issue #21). Do branch work in a worktree: bash .forge/bin/new-worktree.sh <slug> (or git worktree add). To operate on an existing worktree from here, use git -C <worktree-path>. Human escape hatch: ALLOW_MAIN_BRANCHING=1."
+
+# ── 1) Branch creation / orphan / detach / track: always deny in primary checkout ──
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}checkout[[:space:]]+((-[a-zA-Z]*[bB][a-zA-Z]*|--orphan|--detach|--track)([[:space:]=]|\$))"; then
+  emit_deny "$DENY_MSG"
+fi
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}switch[[:space:]]+((-[cC]|--create|--force-create|--orphan|--detach|--track)([[:space:]=]|\$))"; then
+  emit_deny "$DENY_MSG"
+fi
+
+# ── 2) hard/keep/merge reset in the primary checkout while worktrees are branched ──
+# Folded from the superseded forge-branch-guard.sh: a reset that rewrites HEAD +
+# working tree here can drop verified work committed under sibling worktrees. Gated
+# on >1 worktree (unlike the branch weld, which is unconditional).
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}reset[[:space:]]+(--hard|--keep|--merge)([[:space:]]|\$)"; then
+  wt_count=$(git -C "$TARGET_DIR" worktree list 2>/dev/null | wc -l | tr -d ' ')
+  if [ "${wt_count:-1}" -gt 1 ]; then
+    emit_deny "Refusing to move the shared primary HEAD via reset — $wt_count worktrees are branched off it (the 'burned twice' history-rewrite failure, issue #21). Reset inside a worktree, or stop the other sessions first. Human escape hatch: ALLOW_MAIN_BRANCHING=1."
+  fi
+  exit 0   # single-worktree hard-reset is the operator's own business — allow.
+fi
+
+# ── 3) checkout/switch to a ref other than the default branch ───────────────────
+# Only checkout/switch move HEAD to a ref. A reset that reached this far (--soft /
+# --mixed, or a hard/keep/merge reset in a single-worktree repo) is not a branch move
+# off the default → allow it and stop.
+printf '%s' "$COMMAND" | grep -qE "${GITPRE}(checkout|switch)([[:space:]]|\$)" || exit 0
+
+# `git checkout <ref> -- <paths>` and `git checkout -- <paths>` never move HEAD →
+# allow anything containing a ` -- ` pathspec separator.
+printf '%s' "$COMMAND" | grep -qE '[[:space:]]--([[:space:]]|$)' && exit 0
+
+# Extract the first non-flag argument after checkout/switch. Strip everything up to and
+# including the subcommand keyword — whatever git global options preceded it (`-c`,
+# `--no-pager`, `-C <path>`, …) are consumed by the greedy prefix. The trailing separator
+# is optional so a BARE `git checkout` (no target) yields empty ARGS → allowed below.
+ARGS=$(printf '%s' "$COMMAND" | sed -E 's/.*[[:space:]](checkout|switch)([[:space:]]+|$)/ /' | head -1)
+FIRST_REF=""
+for word in $ARGS; do
+  case "$word" in
+    -*) continue ;;                     # flags (creation flags already denied above)
+    \;|\&\&|\|\||\||\&) break ;;        # end of this git command
+    *) FIRST_REF="$word"; break ;;
+  esac
+done
+
+# Bare `git checkout`/`git switch` (no target) is a no-op/error → allow.
+[ -z "$FIRST_REF" ] && exit 0
+
+# Returning home (default branch) or file-restore forms → allow. Any other ref → deny.
+case "$FIRST_REF" in
+  HEAD|.) exit 0 ;;                      # file restore forms
+  *) is_default_branch "$FIRST_REF" && exit 0 || emit_deny "$DENY_MSG" ;;
+esac

package/template/.claude/hooks/tests/protect-primary-checkout.test.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Scratch-repo test suite for .claude/hooks/protect-primary-checkout.sh (issue #21).
+#
+# Each case builds a throwaway git repo (and, where needed, a linked worktree), pipes
+# a PreToolUse JSON payload to the hook, and asserts the exit code. Exit 2 = deny,
+# exit 0 = allow. No network, no fixtures. Self-cleans on exit. Run:
+#   ./.claude/hooks/tests/protect-primary-checkout.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)"
+HOOK="$SCRIPT_DIR/../protect-primary-checkout.sh"
+[ -x "$HOOK" ] || { printf 'FATAL: hook not executable: %s\n' "$HOOK" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { printf 'FATAL: jq required\n' >&2; exit 1; }
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+
+# new_repo <name> [default-branch] — fresh repo with one commit. Prints its path.
+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> <command> [env-assignment] — pipes a payload, returns the hook exit code.
+run_hook() {
+  local dir="$1" cmd="$2" envset="${3:-}"
+  local payload
+  payload=$(jq -nc --arg c "$cmd" --arg d "$dir" '{tool_input:{command:$c},cwd:$d}')
+  if [ -n "$envset" ]; then
+    printf '%s' "$payload" | env "$envset" "$HOOK" >/dev/null 2>&1
+  else
+    printf '%s' "$payload" | "$HOOK" >/dev/null 2>&1
+  fi
+  return $?
+}
+
+# assert <desc> <expected-exit> <dir> <command> [env]
+assert() {
+  local desc="$1" want="$2" dir="$3" cmd="$4" envset="${5:-}"
+  local got
+  run_hook "$dir" "$cmd" "$envset"; got=$?
+  if [ "$got" -eq "$want" ]; then
+    PASSED=$((PASSED + 1))
+    # printf '  PASS: %s\n' "$desc"
+  else
+    FAILED=$((FAILED + 1))
+    printf '  FAIL: %s (got exit %s, want %s)\n' "$desc" "$got" "$want" >&2
+  fi
+}
+
+DENY=2
+ALLOW=0
+
+# ── Primary checkout: DENY branch creation / orphan / detach / track ──────────────
+P="$(new_repo primary)"
+assert "primary: checkout -b denies"                "$DENY" "$P" "git checkout -b feature"
+assert "primary: checkout -B denies"                "$DENY" "$P" "git checkout -B feature"
+assert "primary: switch -c denies"                  "$DENY" "$P" "git switch -c feature"
+assert "primary: switch -C denies"                  "$DENY" "$P" "git switch -C feature"
+assert "primary: switch --create denies"            "$DENY" "$P" "git switch --create feature"
+assert "primary: checkout --orphan denies"          "$DENY" "$P" "git checkout --orphan gh-pages"
+assert "primary: checkout --detach denies"          "$DENY" "$P" "git checkout --detach"
+assert "primary: checkout --track denies"           "$DENY" "$P" "git checkout --track origin/x"
+assert "primary: checkout other-branch denies"      "$DENY" "$P" "git checkout somebranch"
+assert "primary: switch other-branch denies"        "$DENY" "$P" "git switch somebranch"
+
+# ── Global-option bypass regression (review m-49 F1/F2): git global options before ──
+# the subcommand must NOT slip the guard. These were live bypasses before the fix.
+assert "primary: -c global opt + checkout -b denies" "$DENY" "$P" "git -c core.editor=vi checkout -b evil"
+assert "primary: --no-pager + checkout -b denies"    "$DENY" "$P" "git --no-pager checkout -b evil"
+assert "primary: -p + checkout -b denies"            "$DENY" "$P" "git -p checkout -b evil"
+assert "primary: multi -c + switch -c denies"        "$DENY" "$P" "git -c a=b -c c=d switch -c evil"
+assert "primary: \$IFS substitution + -b denies"     "$DENY" "$P" "git checkout\$IFS-b evil"
+assert "primary: -c global opt + checkout main allows" "$ALLOW" "$P" "git -c x=y checkout main"
+
+# ── The UNCONDITIONAL delta: deny even with NO sibling worktree (P has exactly 1). ─
+# (P above already has no siblings — the denies above ARE the no-sibling case. Assert
+#  explicitly that worktree count is 1 here, so the intent is documented.)
+wt_n=$(git -C "$P" worktree list | wc -l | tr -d ' ')
+if [ "$wt_n" -eq 1 ]; then PASSED=$((PASSED+1)); else FAILED=$((FAILED+1)); printf '  FAIL: expected 1 worktree in fresh primary, got %s\n' "$wt_n" >&2; fi
+
+# ── Primary checkout: ALLOW safe forms ───────────────────────────────────────────
+assert "primary: checkout main allows (home)"       "$ALLOW" "$P" "git checkout main"
+assert "primary: switch main allows (home)"         "$ALLOW" "$P" "git switch main"
+assert "primary: checkout -- file allows (restore)" "$ALLOW" "$P" "git checkout -- seed"
+assert "primary: checkout . allows (restore)"       "$ALLOW" "$P" "git checkout ."
+assert "primary: checkout HEAD -- file allows"      "$ALLOW" "$P" "git checkout HEAD -- seed"
+assert "primary: bare checkout allows"              "$ALLOW" "$P" "git checkout"
+assert "primary: git status allows (fast-path)"     "$ALLOW" "$P" "git status"
+assert "primary: git commit allows (fast-path)"     "$ALLOW" "$P" "git commit -m x"
+assert "primary: git log allows (fast-path)"        "$ALLOW" "$P" "git log --oneline"
+
+# ── Worktree pass-through: git-dir != git-common-dir → never blocked ──────────────
+WT="$ROOT/primary-wt"
+git -C "$P" worktree add -q -b wtbranch "$WT" >/dev/null 2>&1
+assert "worktree cwd: checkout -b allows"           "$ALLOW" "$WT" "git checkout -b anything"
+assert "worktree cwd: switch -c allows"             "$ALLOW" "$WT" "git switch -c anything"
+# From the PRIMARY checkout, `git -C <worktree>` targets the worktree → allow.
+assert "primary + git -C worktree: checkout -b allows" "$ALLOW" "$P" "git -C $WT checkout -b anything"
+
+# ── master-default repo: home = master; create still denied ───────────────────────
+M="$(new_repo master-primary master)"
+assert "master repo: checkout master allows (home)" "$ALLOW" "$M" "git checkout master"
+assert "master repo: checkout -b denies"            "$DENY"  "$M" "git checkout -b x"
+assert "master repo: checkout main denies (main is not this repo's default... but seeded)" "$ALLOW" "$M" "git checkout main"
+# ^ main+master are BOTH always in the seed set, so `checkout main` is allowed even in
+#   a master-default repo. That's intentional (both are canonical default names).
+
+# ── Escape hatch ─────────────────────────────────────────────────────────────────
+assert "escape hatch: checkout -b allows"           "$ALLOW" "$P" "git checkout -b feature" "ALLOW_MAIN_BRANCHING=1"
+
+# ── Folded hard-reset guard (worktree-count gated) ───────────────────────────────
+# P now has 1 sibling worktree (WT added above) → count > 1 → hard reset denied.
+assert "primary +wt: reset --hard denies"           "$DENY"  "$P" "git reset --hard HEAD"
+assert "primary +wt: reset --keep denies"           "$DENY"  "$P" "git reset --keep HEAD"
+assert "primary +wt: reset --soft allows (not hard)" "$ALLOW" "$P" "git reset --soft HEAD"
+# A repo with a single worktree → hard reset is the operator's business → allow.
+S="$(new_repo solo)"
+assert "solo (1 wt): reset --hard allows"           "$ALLOW" "$S" "git reset --hard HEAD"
+
+# ── Fail-open cases ──────────────────────────────────────────────────────────────
+assert "fail-open: empty command allows"            "$ALLOW" "$P" ""
+assert "fail-open: non-checkout command allows"     "$ALLOW" "$P" "ls -la"
+# Non-git cwd → fail open. Use a plain temp dir with a checkout-shaped command.
+NG="$ROOT/notgit"; mkdir -p "$NG"
+assert "fail-open: non-git cwd allows"              "$ALLOW" "$NG" "git checkout -b x"
+
+# ── Summary ──────────────────────────────────────────────────────────────────────
+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/.claude/settings.json

@@ -141,6 +141,15 @@
             "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous-commands.sh\""
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-primary-checkout.sh\""
+          }
+        ]
       }
     ]
   }

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

@@ -390,7 +390,26 @@ User selects per stack.
 
    **Confirm with the user first** in brownfield (this edits a user-owned file). In greenfield with no existing `.gitignore`, write it directly. Re-run is idempotent — the carve-out lines `grep` to themselves.
 
-8. **State-sync commit**: `git add .gitignore .claude/settings.json .claude/skills/ .claude/agents/ .claude/hooks/ .forge/` then `git commit -m "chore(forge): initialize forge state + track product files"` (scoped; never `git add .`) — so the new project's state and Forge product files are both in git from the start.
+8. **Wire the primary-checkout weld (`core.hooksPath`).** Welds the primary checkout to the default branch so all branch work happens in worktrees — every tier (issue #21, ADR-031). The tracked `.forge/git-hooks/pre-commit` backstop only fires once `core.hooksPath` points at it. This is per-clone git config, so init owns it. **Detect + warn, never clobber:**
+
+   ```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 set to '$cur' (Husky/lefthook?). NOT overwriting."
+     echo "        The primary-checkout pre-commit backstop (.forge/git-hooks/pre-commit) is"
+     echo "        therefore inactive. To keep the weld, chain it into your existing hooks dir"
+     echo "        (call .forge/git-hooks/pre-commit from your pre-commit), or accept the"
+     echo "        PreToolUse-only coverage (Claude sessions are still guarded)."
+   fi
+   ```
+
+   **WHY repo-relative** (`.forge/git-hooks`, not an absolute path): an absolute `core.hooksPath` silently skips in linked worktrees (the documented Husky/lefthook worktree hazard — see `orchestrating/bootstrap-checks.md`); a repo-relative path resolves under each worktree checkout. **WHY never clobber:** silently disabling a consumer's existing hook framework is unacceptable.
+
+9. **State-sync commit**: `git add .gitignore .claude/settings.json .claude/skills/ .claude/agents/ .claude/hooks/ .forge/` then `git commit -m "chore(forge): initialize forge state + track product files"` (scoped; never `git add .`) — so the new project's state and Forge product files are both in git from the start. (The tracked `.forge/git-hooks/` is included by the `.forge/` path; `core.hooksPath` itself is local git config, not a tracked file, so it needs no staging.)
 
 *"Initialized. Ready?"*
 

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,10 +197,10 @@ 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 the **`forge-state-rollup.sh` SessionStart hook** (the mechanical port of Rollup 1.0 — issue #22; skill prose only *reads* it) from the milestone files; never committed, never hand-edited; the hook renders it in any checkout (gitignored local write), but worktree agents still never write the *committed* derived-source state; 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, 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)
@@ -207,6 +209,7 @@ State lives in `.forge/`. One line per artifact; protocol detail lives in the na
 - `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. Rendered mechanically by the **`forge-state-rollup.sh` SessionStart hook** at boot (issue #22 — an executable, not agent prose), and re-run via that same executable at `chief-of-staff` Show/Sync and after any mid-session milestone CRUD; the hook runs the milestone Rollup 1.0 **first** (the join reads the fresh `index.yml`), and confines the committed-source step-0 sweep to the main checkout. **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.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

package/experimental/m10/source/hooks/forge-branch-guard.sh

@@ -1,61 +0,0 @@
-#!/usr/bin/env bash
-# Forge PreToolUse(Bash) guardrail — protect the shared main checkout's HEAD when
-# parallel git worktrees are active.
-#
-# Blocks the "moved the shared HEAD under other sessions" catastrophe (canvaz, burned
-# twice 2026-06-05): switching branches or hard-resetting in the MAIN checkout while
-# sibling worktrees are branched off it. Orchestration-agnostic — depends only on git
-# worktree state, so it holds whether coordination is M10, Agent Teams, or manual
-# worktrees.
-#
-# Scope is deliberately narrow to avoid false positives:
-#   - fires ONLY when >1 worktree exists (single-worktree/solo work is never touched)
-#   - fires ONLY in the main checkout (linked worktrees own their own HEAD)
-#   - skips any command containing `cd` (can't reliably tell which tree it targets)
-#   - allows safe forms: file restore (`git checkout -- <path>`), branch create (`-b`)
-#
-# exit 0 = allow; exit 2 = deny. Override by running the command yourself outside Claude.
-
-set -uo pipefail
-
-PAYLOAD=$(cat)
-CMD=$(printf '%s' "$PAYLOAD" | jq -r '.tool_input.command // empty' 2>/dev/null) || exit 0
-[ -z "$CMD" ] && exit 0
-
-# Only git commands are interesting; and bail on `cd` (target tree is ambiguous).
-case "$CMD" in
-  *git*) ;;
-  *) exit 0 ;;
-esac
-case "$CMD" in
-  *"cd "*) exit 0 ;;
-esac
-
-git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
-
-# Single worktree → no shared-HEAD hazard.
-wt_count=$(git worktree list 2>/dev/null | wc -l | tr -d ' ')
-[ "${wt_count:-1}" -le 1 ] && exit 0
-
-# Main checkout iff --git-dir == --git-common-dir (linked worktrees differ).
-[ "$(git rev-parse --git-dir 2>/dev/null)" = "$(git rev-parse --git-common-dir 2>/dev/null)" ] || exit 0
-
-deny() { echo "[forge-branch-guard] $*" >&2; exit 2; }
-
-# Branch switch (checkout/switch to a ref), excluding file-restore (`--`) and create (`-b`).
-switches_branch=0
-if printf '%s' "$CMD" | grep -qE '\bgit[[:space:]]+(checkout|switch)\b'; then
-  if ! printf '%s' "$CMD" | grep -qE '([[:space:]]--([[:space:]]|$))|(\bgit[[:space:]]+(checkout|switch)[[:space:]]+-[bB]\b)'; then
-    switches_branch=1
-  fi
-fi
-
-# Hard/keep/merge reset rewrites HEAD + working tree.
-hard_reset=0
-printf '%s' "$CMD" | grep -qE '\bgit[[:space:]]+reset[[:space:]]+(--hard|--keep|--merge)\b' && hard_reset=1
-
-if [ "$switches_branch" = "1" ] || [ "$hard_reset" = "1" ]; then
-  deny "Refusing to move the shared main HEAD — $wt_count worktrees are branched off it (the 'burned twice' failure). Switch/reset inside a worktree, or stop the other sessions first. Override: run the command yourself outside Claude."
-fi
-
-exit 0