forge-orkes 0.77.0 → 0.80.0

package/template/.forge/checks/forge-jarvis-relay.sh

@@ -66,23 +66,71 @@ payload_claims_landed() {  # payload_claims_landed <payload>
   printf '%s' "${1:-}" | grep -qiE 'merged|landed|validated|promoted|on main|is live|shipped|deployed'
 }
 
+# ── milestone name lookup (issue #34 — an operator with 40+ milestones in flight can't tell
+#    which slice a bare buzz is about). The awk extraction is kept textually aligned with
+#    milestone_name in forge-jarvis-awareness.sh — same guard, same nested `milestone: / name:`
+#    parse, same degrade-to-empty on any miss. <forge-dir> here is the slice's `.forge` directory
+#    (NOT the worktree root — see the two-dirname derivation in build_relay_text below); the state
+#    file lives at <forge-dir>/state/milestone-<id>.yml. ────────────────────────────────────────
+milestone_name() {  # milestone_name <milestone-id> <forge-dir>
+  _mid="${1:-}"; _fd="${2:-}"
+  [ -n "$_mid" ] && [ -n "$_fd" ] || { printf ''; return 0; }
+  _id="${_mid#m-}"
+  _f="$_fd/state/milestone-$_id.yml"
+  [ -f "$_f" ] || { printf ''; return 0; }
+  awk '
+    /^milestone:/ { inp=1; next }
+    inp && /^[A-Za-z]/ { inp=0 }
+    inp && /^[[:space:]]+name:/ {
+      sub(/^[[:space:]]*[^:]+:[[:space:]]*/, "")
+      sub(/[[:space:]]*#.*/, "")
+      gsub(/^["'"'"']|["'"'"']$/, "")
+      print; exit
+    }
+  ' "$_f"
+}
+
+# ── "m-<id> — <name>", truncated ~60 chars; degrades to the bare id (never a blank "m- — "
+#    prefix) when the name can't be resolved or the id itself is empty. ─────────────────────────
+named_milestone() {  # named_milestone <milestone-id> <forge-dir>
+  _mid="${1:-}"; _fd="${2:-}"
+  [ -n "$_mid" ] || { printf ''; return 0; }
+  _nm="$(milestone_name "$_mid" "$_fd")"
+  if [ -n "$_nm" ]; then
+    printf '%s' "$_mid — $_nm" | cut -c1-60
+  else
+    printf '%s' "$_mid"
+  fi
+}
+
 # ── build the relay text for ONE parsed ping (the pure host-truth text-builder) ───────────────
-# Reads: $2=type $3=payload ; $MILESTONE (optional, for fold). Prints one line to stdout.
-build_relay_text() {  # build_relay_text <type> <payload>
-  _type="${1:-note}"; _payload="${2:-}"
+# Reads: $2=type $3=payload $4=log-path (optional) ; $MILESTONE (optional, for fold + naming).
+# Prints one line to stdout, prefixed "m-<id> — <name>: " when a name can be resolved (issue #34)
+# — degrades to a bare "m-<id>: " prefix, or no prefix at all when $MILESTONE is also empty.
+build_relay_text() {  # build_relay_text <type> <payload> [<log-path>]
+  _type="${1:-note}"; _payload="${2:-}"; _LOG="${3:-}"
+  if [ -n "$_LOG" ]; then
+    # mode_scan's log path is always <worktree>/.forge/runner-work/notify.log — two dirnames
+    # land on <worktree>/.forge (the forge-dir milestone_name expects), not the worktree root.
+    _fd="$(dirname "$(dirname "$_LOG")")"
+    _named="$(named_milestone "${MILESTONE:-}" "$_fd")"
+  else
+    _named="${MILESTONE:-}"
+  fi
+  if [ -n "$_named" ]; then _prefix="$_named: "; else _prefix=""; fi
   case "$_type" in
     ambiguity)
       # A QUESTION — relay verbatim, named. Legal: it is not a state claim (acceptance #2).
-      printf '❓ Needs you (ambiguity): %s' "$_payload" ;;
+      printf '%s❓ Needs you (ambiguity): %s' "$_prefix" "$_payload" ;;
     fork)
       # payload is a PATH to a sketch the operator LOOKS AT (§8) — name it.
-      printf '🎨 Design fork — review the sketch: %s' "$_payload" ;;
+      printf '%s🎨 Design fork — review the sketch: %s' "$_prefix" "$_payload" ;;
     irreversible)
       # a gate on an irreversible act — your call; relay verbatim, named.
-      printf '⚠️ Irreversible action — your call: %s' "$_payload" ;;
+      printf '%s⚠️ Irreversible action — your call: %s' "$_prefix" "$_payload" ;;
     budget)
       # the runner's OWN spend tally — no host source to recompute against; relay verbatim, named.
-      printf '💸 Budget cap reached: %s' "$_payload" ;;
+      printf '%s💸 Budget cap reached: %s' "$_prefix" "$_payload" ;;
     done|halt)
       # STATE-CLAIM territory. Recompute host truth FIRST; build the claim from it, not the payload.
       _rs="$(host_release_state "${MILESTONE:-}")"
@@ -90,25 +138,25 @@ build_relay_text() {  # build_relay_text <type> <payload>
       if payload_claims_landed "$_payload"; then
         if [ "$_rs" = unmerged ]; then
           # The standing lesson: payload says merged, host says not. Relay the host, loudly.
-          printf '⚠️ DISCREPANCY — payload claims landed/merged, but host shows release_state=unmerged. %s (host truth wins). Payload said: %s' "$_base" "$_payload"
+          printf '%s⚠️ DISCREPANCY — payload claims landed/merged, but host shows release_state=unmerged. %s (host truth wins). Payload said: %s' "$_prefix" "$_base" "$_payload"
         elif [ "$_rs" = unknown ]; then
-          printf '⚠️ %s — payload claims landed/merged but the host could NOT be verified (release_state=unknown). Payload said: %s' "$_base" "$_payload"
+          printf '%s⚠️ %s — payload claims landed/merged but the host could NOT be verified (release_state=unknown). Payload said: %s' "$_prefix" "$_base" "$_payload"
         else
           # payload claims landed AND host agrees (merged/validated) — no discrepancy.
-          printf '%s — host confirms: release_state=%s. %s' "$_base" "$_rs" "$_payload"
+          printf '%s%s — host confirms: release_state=%s. %s' "$_prefix" "$_base" "$_rs" "$_payload"
         fi
       else
-        printf '%s — host: release_state=%s. %s' "$_base" "$_rs" "$_payload"
+        printf '%s%s — host: release_state=%s. %s' "$_prefix" "$_base" "$_rs" "$_payload"
       fi ;;
     *)
       # unknown type — relay raw, named (never silently drop).
-      printf '(%s): %s' "$_type" "$_payload" ;;
+      printf '%s(%s): %s' "$_prefix" "$_type" "$_payload" ;;
   esac
 }
 
 # Parse a TSV log line (ts<TAB>type<TAB>payload) then build text. Prints one line.
-relay_one_line() {  # relay_one_line <tsv-line>
-  _line="$1"
+relay_one_line() {  # relay_one_line <tsv-line> [<log-path>]
+  _line="$1"; _LOG="${2:-}"
   _type="$(printf '%s' "$_line" | cut -f2)"
   _payload="$(printf '%s' "$_line" | cut -f3-)"
   # A malformed line with no tabs → cut returns the whole line for f2/f3; treat as a raw note.
@@ -116,7 +164,7 @@ relay_one_line() {  # relay_one_line <tsv-line>
     *"	"*) : ;;                       # has a tab — well-formed
     *) _type='note'; _payload="$_line" ;;
   esac
-  build_relay_text "$_type" "$_payload"
+  build_relay_text "$_type" "$_payload" "$_LOG"
 }
 
 # ── modes — one function per mode, each owning its own arg loop ───────────────────────────────
@@ -211,7 +259,7 @@ mode_scan() {
     _n=$((_n + 1))
     _marker="$MARKER_DIR/$_n.relayed"
     [ -f "$_marker" ] && continue                      # at-most-once: already relayed, never re-buzz
-    _text="$(relay_one_line "$_l")"
+    _text="$(relay_one_line "$_l" "$LOG")"
     # Write the marker BEFORE emitting — a crash after emit must not double-buzz; a crash
     # before emit leaves it unmarked and it re-surfaces as while-you-were-away (no silent loss).
     # A FAILED marker write must not emit either: emitting unmarked would re-buzz on every

package/template/.forge/checks/tests/forge-jarvis-awareness.test.sh

@@ -167,5 +167,63 @@ else
   bad 'guard: bare-number branch fix-issue-2 (no m- token) is not discovered' "$OUT"
 fi
 
+# --- 13-16. NAMED MILESTONES (issue #34): "m-<id> — <name>" at both print sites, degrading to
+#     the bare id when the name can't be resolved — no crash either way. ------------------------
+WTN="$ROOT/worktrees-named"; mkdir -p "$WTN/m-50/.forge/state" "$WTN/m-51"
+cat > "$WTN/m-50/.forge/state/milestone-50.yml" <<'EOF'
+milestone:
+  id: m-50
+  name: "Named milestone fixture"
+  origin: null
+
+current:
+  status: executing
+EOF
+# m-51 has NO .forge/state/milestone-51.yml — the no-file degrade case.
+
+OUT="$(FORGE_JARVIS_FOLD="$FOLDSTUB" FORGE_JARVIS_BOARD="$BOARDSTUB" \
+       sh "$AWARE" --dry-run --worktree-root "$WTN" 2>&1)"
+
+# 13. slice-list row WITH a resolvable milestone.name shows "m-<id> — <name>"
+if printf '%s' "$OUT" | grep -q 'm-50 — Named milestone fixture'; then
+  ok 'slice-list: milestone with a resolvable name renders "m-<id> — <name>"'
+else
+  bad 'slice-list: milestone with a resolvable name renders "m-<id> — <name>"' "$OUT"
+fi
+
+# 14. slice-list row with NO milestone state file still renders — degrades to the bare id
+if printf '%s' "$OUT" | grep -qE '(^|[[:space:]])m-51([[:space:]]|$)'; then
+  ok 'slice-list: no state file degrades to the bare id, no crash'
+else
+  bad 'slice-list: no state file degrades to the bare id, no crash' "$OUT"
+fi
+
+# stub board: one row WITH a "name" field, one row WITHOUT — pins the board-side degrade
+BOARDSTUB_NAMED="$ROOT/board-named.sh"
+cat > "$BOARDSTUB_NAMED" <<'EOF'
+#!/bin/sh
+[ "$1" = "--emit" ] || exit 2
+printf '{"forge_id": "m-60", "status": "executing", "release_state": "unmerged", "name": "Board-named unit"}\n'
+printf '{"forge_id": "m-61", "status": "executing", "release_state": "unmerged"}\n'
+EOF
+chmod +x "$BOARDSTUB_NAMED"
+
+OUT="$(FORGE_JARVIS_FOLD="$FOLDSTUB" FORGE_JARVIS_BOARD="$BOARDSTUB_NAMED" \
+       sh "$AWARE" --worktree-root "$EMPTY" 2>&1)"
+
+# 15. board-projection row WITH a "name" field shows "m-<id> — <name>"
+if printf '%s' "$OUT" | grep -q 'm-60 — Board-named unit  status=executing'; then
+  ok 'board projection: a row with a name field renders "m-<id> — <name>"'
+else
+  bad 'board projection: a row with a name field renders "m-<id> — <name>"' "$OUT"
+fi
+
+# 16. board-projection row missing the "name" field degrades to the bare id (no crash)
+if printf '%s' "$OUT" | grep -q 'm-61  status=executing' && ! printf '%s' "$OUT" | grep -q 'm-61 — '; then
+  ok 'board projection: no name field degrades to the bare id, no crash'
+else
+  bad 'board projection: no name field degrades to the bare id, no crash' "$OUT"
+fi
+
 printf '\nforge-jarvis-awareness.test.sh: %s passed, %s failed\n' "$PASSED" "$FAILED"
 [ "$FAILED" -eq 0 ]

package/template/.forge/checks/tests/forge-jarvis-relay.test.sh

@@ -160,6 +160,56 @@ else
   bad "guard: bare-number branch fix-issue-2 (no m- token) emits no log path" "$out"
 fi
 
+# --- 16-19. NAMED MILESTONES (issue #34): build_relay_text prefixes "m-<id> — <name>" onto
+#     every buzz type, resolving the name from $LOG's worktree root; degrades to the bare
+#     "m-<id>" prefix when the state file can't be resolved — never a crash either way. ----------
+WTN="$ROOT/slice-wt-named"; mkdir -p "$WTN/.forge/state" "$WTN/.forge/runner-work"
+cat > "$WTN/.forge/state/milestone-77.yml" <<'EOF'
+milestone:
+  id: m-77
+  name: "Named relay fixture"
+  origin: null
+
+current:
+  status: executing
+EOF
+LOGN="$WTN/.forge/runner-work/notify.log"
+printf '2026-07-21T10:00:00Z\tambiguity\tJWT or sessions?\n' >> "$LOGN"
+printf '2026-07-21T10:01:00Z\tdone\tPR opened\n'             >> "$LOGN"
+printf '2026-07-21T10:02:00Z\thalt\tstuck\n'                 >> "$LOGN"
+
+scan_named() { FORGE_JARVIS_FOLD="$FOLD_UNMERGED" sh "$RELAY" --scan "$LOGN" --milestone m-77 2>/dev/null; }
+out="$(scan_named)"
+
+# 16. ambiguity buzz is prefixed "m-<id> — <name>"
+case "$out" in
+  *"m-77 — Named relay fixture: "*"Needs you (ambiguity)"*) ok "ambiguity buzz prefixed with the resolved milestone name" ;;
+  *) bad "ambiguity buzz prefixed with the resolved milestone name" "$out" ;;
+esac
+
+# 17. done buzz is prefixed "m-<id> — <name>"
+case "$out" in
+  *"m-77 — Named relay fixture: "*"Slice done"*) ok "done buzz prefixed with the resolved milestone name" ;;
+  *) bad "done buzz prefixed with the resolved milestone name" "$out" ;;
+esac
+
+# 18. halt buzz is prefixed "m-<id> — <name>"
+case "$out" in
+  *"m-77 — Named relay fixture: "*"Slice HALTED"*) ok "halt buzz prefixed with the resolved milestone name" ;;
+  *) bad "halt buzz prefixed with the resolved milestone name" "$out" ;;
+esac
+
+# 19. a worktree whose milestone state can't be resolved still fires — degrades to the bare
+#     "m-<id>" prefix, no crash.
+WTB="$ROOT/slice-wt-bare"; mkdir -p "$WTB/.forge/runner-work"   # no .forge/state at all
+LOGB="$WTB/.forge/runner-work/notify.log"
+printf '2026-07-21T10:00:00Z\tbudget\tcap hit\n' >> "$LOGB"
+out2="$(FORGE_JARVIS_FOLD="$FOLD_UNMERGED" sh "$RELAY" --scan "$LOGB" --milestone m-88 2>/dev/null)"
+case "$out2" in
+  *"m-88: "*"Budget cap reached"*) ok "unresolvable milestone state degrades to the bare id prefix, no crash" ;;
+  *) bad "unresolvable milestone state degrades to the bare id prefix, no crash" "$out2" ;;
+esac
+
 # --- summary -----------------------------------------------------------------
 printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
 [ "$FAILED" = 0 ]

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/migrations/0.80.0-context-md-sharding.md

@@ -0,0 +1,158 @@
+# Migration Guide: context.md sharded into per-milestone files (Forge 0.80.0)
+
+Applies to projects upgrading to 0.80.0 or later. `.forge/context.md` — a
+single monolithic, git-tracked file that accumulated one section per
+milestone's locked decisions — is now a **derived, git-ignored index**
+(ADR-033, issue #37), same class as `.forge/state/index.yml` and
+`.forge/streams/active.yml`. The actual decision content lives in
+`.forge/context/{id}.md`, one file per milestone, produced by a new one-time
+tool: `.claude/hooks/forge-context-migrate.sh`.
+
+`/upgrading` ships both new pieces — the migration tool
+(`.claude/hooks/forge-context-migrate.sh`) and the extended
+`.claude/hooks/forge-state-rollup.sh` that renders `context.md` as an index —
+like any other framework file. It does **not** run the migration or touch
+`.forge/context.md`, because both are **user-owned content**: `context.md`'s
+existing prose is a specific repo's real decision history, not something an
+upgrade can safely rewrite or delete on its own.
+
+**What actually happens if this migration is skipped.** Read
+`forge-state-rollup.sh`'s render logic directly: the third join
+(`render_context_index`) only runs when `.forge/context/` exists as a
+directory (`if [ -d "$root/.forge/context" ]; then render_context_index; fi`).
+On an unmigrated repo — no `.forge/context/` directory yet — that guard is
+false, so the rollup **never touches `.forge/context.md` at all**: it is not
+overwritten, not cleared, not rendered as an empty index. The old monolithic
+file sits there completely untouched, and the boot summary line simply omits
+the `+ context.md (…)` clause it would otherwise show. There is no
+data-loss risk from the render side; the actual gap is that the file quietly
+stops being what the rest of the framework expects it to be once the repo
+does start sharding (skills read/write `.forge/context/{id}.md` post-0.80.0,
+not the monolithic file) — an unmigrated repo's decision history becomes
+stale and invisible to that new convention until this migration runs.
+
+Projects that ran `initializing` fresh on 0.80.0+ start with no
+`.forge/context.md` at all (nothing to migrate). Projects that already ran
+this migration (their own dogfood, or a prior partial adoption) have a
+populated `.forge/context/` directory and need nothing further.
+
+## Prerequisites
+
+1. On the new version's framework files (`npx forge-orkes upgrade`, or the
+   `upgrading` skill) — so `.claude/hooks/forge-context-migrate.sh` and the
+   extended `.claude/hooks/forge-state-rollup.sh` are present and executable.
+2. Working tree clean or changes committed — this migration creates new
+   tracked files (`context/{id}.md`, `context-log.md`), untracks
+   `.forge/context.md`, and edits a gitignore file.
+3. Read `.forge/context.md` once before running anything, so you know what
+   the pre-migration content actually looks like in this repo (heading
+   shapes vary historically — `### m-52 — …`, `### M49 — …`, and undated
+   drafting blocks with no id all exist in the wild; the migration tool
+   handles all three, but it's worth knowing what to expect in the output).
+
+## Detection
+
+Keyed on **`.forge/context.md` being git-tracked, non-trivially sized, and
+`.forge/context/` not existing yet** — the pre-migration gap. A byte-count
+floor (500 bytes) guards against false-positiving on a repo that already
+shrank `context.md` down to a near-empty derived index through some other
+path. Silent in a non-Forge / non-git tree, silent on a fresh install (no
+`context.md` at all), silent once `.forge/context/` exists (already
+migrated), silent once `context.md` is untracked (already gitignored, i.e.
+already migrated):
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+[ -f .forge/context.md ] || exit 0
+[ -d .forge/context ] && exit 0
+
+git ls-files --error-unmatch .forge/context.md >/dev/null 2>&1 || exit 0
+
+size="$(wc -c < .forge/context.md 2>/dev/null | tr -d ' ')"
+[ -n "$size" ] && [ "$size" -gt 500 ] || exit 0
+
+echo "MIGRATE — .forge/context.md is a tracked, ${size}-byte monolithic file with no .forge/context/ directory; run forge-context-migrate.sh to shard it before the derived-index render starts being relied on"
+```
+
+## Migration steps
+
+### 1. Run the migration tool for real (not dry-run)
+
+From the repo root, with no flags — the tool resolves `--source` and `--dest`
+from the current repo via `git rev-parse --show-toplevel` when they're
+omitted, defaulting to `<repo-root>/.forge/context.md` and `<repo-root>/.forge`:
+
+```bash
+.claude/hooks/forge-context-migrate.sh
+```
+
+This reads `.forge/context.md` and writes `.forge/context/{id}.md` (one file
+per resolvable milestone heading, ids normalized to `m-{N}`),
+`.forge/context-log.md` (Amendment Log, Needs Resolution, and any undated
+drafting block that has no milestone id to shard by), and
+`.forge/context/_shared.md` if any Deferred Ideas / Discretion Areas entry
+has no milestone-id prefix. It does **not** touch or delete the source
+`context.md` — that's step 2, done separately on purpose so the tool itself
+stays a pure read-old/write-new operation.
+
+The tool is idempotent per milestone id: if `.forge/context/{id}.md` already
+exists, that id is skipped (never overwritten, never duplicated) and one
+skip line is printed. Re-running this command after the fact is always safe.
+What is **not** repeatable is the untrack step below — do that once.
+
+### 2. Untrack context.md and gitignore it
+
+```bash
+git rm --cached .forge/context.md
+```
+
+Add `.forge/context.md` to whichever gitignore file already lists
+`.forge/state/index.yml` and `.forge/streams/active.yml` — grep for
+`index.yml` to find the right file (in this repo it's the root
+`.gitignore`, under the "Render-on-read derived registries" comment block;
+your project's may differ if it customized gitignore layout):
+
+```bash
+grep -rn "index.yml" .gitignore .forge/.gitignore 2>/dev/null
+```
+
+Add the line next to the other two derived-registry entries, matching their
+existing comment block rather than starting a new one.
+
+### 3. Commit the migration output
+
+```bash
+git add .forge/context/ .forge/context-log.md .gitignore
+git commit -m "chore(forge): shard context.md into per-milestone files (0.80.0)"
+```
+
+Do **not** `git add .forge/context.md` — it is now untracked and gitignored;
+the working copy on disk will be overwritten by the next boot's render into
+a derived index, which is expected.
+
+**This is a one-time, per-repo operation.** The `git rm --cached` + gitignore
+step only needs doing once — running `forge-context-migrate.sh` again later
+(e.g. if a new milestone's context needs re-splitting for some reason) is
+safe and idempotent per the tool's own design, but do not repeat the untrack
+step; `.forge/context.md` is already gitignored after step 2 and a second
+`git rm --cached` on an already-untracked path is a no-op error, not harmful
+but not necessary.
+
+## Validation
+
+- `.forge/context/` contains one file per milestone heading that existed in
+  the old monolithic `context.md` (spot-check the count against what you
+  read in Prerequisites step 3).
+- `git status --short .forge/context.md` shows nothing (untracked +
+  gitignored paths don't appear in default `git status` output) — confirming
+  the untrack + gitignore took effect. `git check-ignore .forge/context.md`
+  exits 0.
+- Start a new session, or run `/clear` — the boot summary line now includes
+  a `+ context.md (N context rows)` clause, and `.forge/context.md` on disk
+  is the rendered index (one row per milestone: id, name, status,
+  release_state, path), not the old monolithic prose.
+- Re-running the Detection block above now prints nothing (exits silently)
+  — the gap is closed.
+- Spot-check any pre-existing citation into `context.md` (e.g. "LOCKED,
+  context.md § M24") still resolves: the rendered index has a row for that
+  milestone id, and `.forge/context/{id}.md` contains the cited content.