forge-orkes 0.77.0 → 0.80.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.80.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/forge-context-migrate.sh

@@ -0,0 +1,297 @@
+#!/usr/bin/env sh
+# forge-context-migrate — one-time tool: split a monolithic `.forge/context.md`
+# into `.forge/context/{id}.md` (one file per milestone) + `.forge/context-log.md`
+# (Amendment Log + Needs Resolution + any content with no resolvable milestone
+# id) + `.forge/context/_shared.md` (Deferred/Discretion entries that are
+# genuinely cross-cutting, i.e. carry no milestone-id prefix). Part of the
+# context.md size-gate fix (issue #37, ADR-033) — context.md becomes a
+# derived index (forge-state-rollup.sh renders it); this tool produces the
+# per-milestone source files that index reads.
+#
+#   forge-context-migrate.sh [--source <path>] [--dest <path>] [--dry-run]
+#
+#     --source <path>   the monolithic context.md to read. Default:
+#                        <repo-root>/.forge/context.md (resolved via git from
+#                        the CWD).
+#     --dest <path>      the directory context/ + context-log.md are written
+#                        under (i.e. the ".forge"-equivalent dir — outputs
+#                        land at <dest>/context/{id}.md, <dest>/context-log.md,
+#                        <dest>/context/_shared.md). Default: <repo-root>/.forge.
+#     --dry-run          parse and report what WOULD be written; touches no
+#                        files on disk.
+#
+# NEVER touches --source. This tool is a pure "read old, write new" step —
+# deleting/replacing the monolithic file is a separate, explicit step so the
+# tool stays testable without mutating the thing it reads.
+#
+# Classification rules (see phase 95 plan-01 task 1):
+#   - `## Locked Decisions` sub-headings (`### ...`) whose first word resolves
+#     to a milestone id (`M{N}`, `m-{N}`, `m{N}` — normalized to `m-{N}`) each
+#     become `context/{id}.md`. A heading with no resolvable id (e.g. a
+#     drafting block, or a pointer-stub heading like "Historical Decisions")
+#     is NOT sharded — it lands in context-log.md verbatim.
+#   - `## Deferred Ideas` / `## Discretion Areas` top-level bullets whose text
+#     starts with a resolvable milestone-id prefix append to that milestone's
+#     context/{id}.md (created if absent) under a `## Deferred` / `##
+#     Discretion` heading. An entry with no prefix is genuinely cross-cutting
+#     and goes to context/_shared.md instead — never guessed onto a milestone.
+#   - `## Needs Resolution` and `## Amendment Log` are never milestone-scoped
+#     — copied verbatim into context-log.md.
+#   - Anything else (top-of-file preamble, unrecognized `## ` sections) is
+#     dropped or logged to context-log.md's "Other Sections" — never silently
+#     lost, but never invented a milestone home either.
+#
+# Idempotency: re-running against an already-migrated tree is a no-op per id
+# — if `<dest>/context/{id}.md` already exists on disk, that id is SKIPPED
+# entirely (Locked + Deferred + Discretion content for that id alike), one
+# skip line printed per id, and the existing file is never touched. Likewise
+# context-log.md and context/_shared.md are left alone if they already exist.
+#
+# Portable: POSIX sh + awk. No network calls.
+
+set -u
+
+SCRIPT_NAME="forge-context-migrate"
+
+source=""
+dest=""
+dry_run=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --source) shift; source="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+    --source=*) source="${1#*=}"; shift ;;
+    --dest) shift; dest="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+    --dest=*) dest="${1#*=}"; shift ;;
+    --dry-run) dry_run=1; shift ;;
+    -h|--help)
+      printf 'Usage: %s [--source <path>] [--dest <path>] [--dry-run]\n' "$SCRIPT_NAME"
+      exit 0
+      ;;
+    *) printf '%s: unknown argument: %s\n' "$SCRIPT_NAME" "$1" >&2; exit 2 ;;
+  esac
+done
+
+if [ -z "$source" ] || [ -z "$dest" ]; then
+  root="$(git rev-parse --show-toplevel 2>/dev/null)"
+  if [ -z "$root" ]; then
+    printf '%s: not in a git repo — pass --source and --dest explicitly\n' "$SCRIPT_NAME" >&2
+    exit 1
+  fi
+  [ -z "$source" ] && source="$root/.forge/context.md"
+  [ -z "$dest" ] && dest="$root/.forge"
+fi
+
+if [ ! -f "$source" ]; then
+  printf '%s: source file not found: %s\n' "$SCRIPT_NAME" "$source" >&2
+  exit 1
+fi
+
+# --- idempotency inputs: which ids/artifacts already exist at dest ----------
+
+existing_ids=" "
+if [ -d "$dest/context" ]; then
+  for f in "$dest"/context/*.md; do
+    [ -f "$f" ] || continue
+    base="$(basename "$f" .md)"
+    [ "$base" = "_shared" ] && continue
+    existing_ids="$existing_ids$base "
+  done
+fi
+
+skip_log=0
+[ -f "$dest/context-log.md" ] && skip_log=1
+
+skip_shared=0
+[ -f "$dest/context/_shared.md" ] && skip_shared=1
+
+# --- write target dirs (real run only — dry-run touches nothing) -----------
+
+if [ "$dry_run" -eq 0 ]; then
+  mkdir -p "$dest/context"
+fi
+
+# --- awk parser/writer -------------------------------------------------------
+# Buffers everything in memory (context.md is well under a few hundred KB)
+# then writes/report at END. Program is written to a scratch file so the
+# shell wrapper stays a plain single-quoted awk invocation.
+
+awk_prog="$(mktemp 2>/dev/null || mktemp -t forge-context-migrate)"
+trap 'rm -f "$awk_prog"' EXIT INT TERM
+
+cat > "$awk_prog" <<'AWKEOF'
+function extract_id(line,    w, arr, n, tok, digits) {
+  w = line
+  sub(/^### /, "", w)
+  sub(/^- /, "", w)
+  sub(/^~~/, "", w)
+  n = split(w, arr, /[ \t]/)
+  if (n < 1) return ""
+  tok = arr[1]
+  gsub(/[:,.]+$/, "", tok)
+  if (tok ~ /^[Mm]-?[0-9]+$/) {
+    digits = tok
+    gsub(/[^0-9]/, "", digits)
+    return "m-" digits
+  }
+  return ""
+}
+
+function add_id(id) {
+  if (!(id in seen_id)) {
+    seen_id[id] = 1
+    n_ids++
+    id_order[n_ids] = id
+  }
+}
+
+BEGIN {
+  section = ""
+  cur_state = ""
+  cur_id = ""
+  cur_noid_key = ""
+  n_ids = 0
+  n_noid = 0
+}
+
+/^## / {
+  cur_state = ""
+  cur_id = ""
+  if ($0 ~ /^## Locked Decisions/) { section = "LOCKED"; cur_state = "LOCKED_PRE"; next }
+  if ($0 ~ /^## Deferred Ideas/) { section = "DEFERRED"; next }
+  if ($0 ~ /^## Discretion Areas/) { section = "DISCRETION"; next }
+  if ($0 ~ /^## Needs Resolution/) { section = "NEEDS_RESOLUTION"; next }
+  if ($0 ~ /^## Amendment Log/) { section = "AMENDMENT"; next }
+  section = "OTHER"
+  other_buf = other_buf $0 "\n"
+  next
+}
+
+section == "" { next }
+
+section == "LOCKED" {
+  if ($0 ~ /^### /) {
+    id = extract_id($0)
+    if (id == "") {
+      n_noid++
+      cur_noid_key = "NOID" n_noid
+      noid_order[n_noid] = cur_noid_key
+      noid_body[cur_noid_key] = $0 "\n"
+      cur_state = "LOCKED_NOID"
+      cur_id = ""
+    } else {
+      add_id(id)
+      locked_body[id] = $0 "\n"
+      cur_state = "LOCKED_BLOCK"
+      cur_id = id
+    }
+    next
+  }
+  if (cur_state == "LOCKED_PRE") { pre_locked_buf = pre_locked_buf $0 "\n"; next }
+  if (cur_state == "LOCKED_BLOCK") { locked_body[cur_id] = locked_body[cur_id] $0 "\n"; next }
+  if (cur_state == "LOCKED_NOID") { noid_body[cur_noid_key] = noid_body[cur_noid_key] $0 "\n"; next }
+  next
+}
+
+section == "DEFERRED" || section == "DISCRETION" {
+  if ($0 ~ /^- /) {
+    id = extract_id($0)
+    if (id == "") {
+      if (section == "DEFERRED") { cur_state = "SHARED_DEF"; shared_deferred = shared_deferred $0 "\n" }
+      else { cur_state = "SHARED_DISC"; shared_discretion = shared_discretion $0 "\n" }
+      cur_id = ""
+    } else {
+      add_id(id)
+      if (section == "DEFERRED") { deferred_body[id] = deferred_body[id] $0 "\n"; cur_state = "DEF_ID" }
+      else { discretion_body[id] = discretion_body[id] $0 "\n"; cur_state = "DISC_ID" }
+      cur_id = id
+    }
+    next
+  }
+  if (cur_state == "DEF_ID") { deferred_body[cur_id] = deferred_body[cur_id] $0 "\n"; next }
+  if (cur_state == "DISC_ID") { discretion_body[cur_id] = discretion_body[cur_id] $0 "\n"; next }
+  if (cur_state == "SHARED_DEF") { shared_deferred = shared_deferred $0 "\n"; next }
+  if (cur_state == "SHARED_DISC") { shared_discretion = shared_discretion $0 "\n"; next }
+  next
+}
+
+section == "NEEDS_RESOLUTION" { needs_resolution_buf = needs_resolution_buf $0 "\n"; next }
+section == "AMENDMENT" { amendment_buf = amendment_buf $0 "\n"; next }
+section == "OTHER" { other_buf = other_buf $0 "\n"; next }
+
+END {
+  for (i = 1; i <= n_ids; i++) {
+    id = id_order[i]
+    if (index(existing, " " id " ") > 0) {
+      print "SKIP: " id " — context/" id ".md already exists, not overwritten" > "/dev/stderr"
+      continue
+    }
+    content = ""
+    if (id in locked_body) content = content locked_body[id]
+    if (id in deferred_body) content = content "\n## Deferred\n\n" deferred_body[id]
+    if (id in discretion_body) content = content "\n## Discretion\n\n" discretion_body[id]
+    fname = dest "/context/" id ".md"
+    if (dryrun == "1") {
+      print "DRY-RUN: would create " fname
+    } else {
+      printf "%s", content > fname
+      close(fname)
+      print "CREATED: " fname
+    }
+  }
+
+  if (skip_log == "1") {
+    print "SKIP: context-log.md already exists, not overwritten" > "/dev/stderr"
+  } else {
+    log_out = "# Context Log\n\n"
+    log_out = log_out "Migrated from the monolithic `.forge/context.md` (ADR-033). Per-milestone\n"
+    log_out = log_out "decisions now live in `.forge/context/{id}.md`; the rendered `.forge/context.md`\n"
+    log_out = log_out "is a derived index (forge-state-rollup.sh) — this file carries the content\n"
+    log_out = log_out "that never was milestone-scoped.\n\n---\n\n"
+    if (pre_locked_buf != "" || n_noid > 0) {
+      log_out = log_out "## Locked Decisions (No Milestone ID)\n\n"
+      if (pre_locked_buf != "") log_out = log_out pre_locked_buf "\n"
+      for (i = 1; i <= n_noid; i++) log_out = log_out noid_body[noid_order[i]] "\n"
+    }
+    if (other_buf != "") log_out = log_out "## Other Sections\n\n" other_buf "\n"
+    log_out = log_out "## Needs Resolution\n\n"
+    log_out = log_out (needs_resolution_buf != "" ? needs_resolution_buf : "(none)\n")
+    log_out = log_out "\n---\n\n## Amendment Log\n\n" amendment_buf
+    fname = dest "/context-log.md"
+    if (dryrun == "1") {
+      print "DRY-RUN: would create " fname
+    } else {
+      printf "%s", log_out > fname
+      close(fname)
+      print "CREATED: " fname
+    }
+  }
+
+  if (shared_deferred == "" && shared_discretion == "") {
+    # nothing genuinely cross-cutting — do not create an empty file
+  } else if (skip_shared == "1") {
+    print "SKIP: context/_shared.md already exists, not overwritten" > "/dev/stderr"
+  } else {
+    shared_out = "# Shared / Cross-Cutting Context\n\n"
+    shared_out = shared_out "Deferred Ideas and Discretion Areas entries from `.forge/context.md` with no\n"
+    shared_out = shared_out "resolvable milestone-id prefix — genuinely cross-cutting, not owned by one\n"
+    shared_out = shared_out "milestone.\n\n---\n\n"
+    if (shared_deferred != "") shared_out = shared_out "## Deferred Ideas\n\n" shared_deferred "\n"
+    if (shared_discretion != "") shared_out = shared_out "## Discretion Areas\n\n" shared_discretion "\n"
+    fname = dest "/context/_shared.md"
+    if (dryrun == "1") {
+      print "DRY-RUN: would create " fname
+    } else {
+      printf "%s", shared_out > fname
+      close(fname)
+      print "CREATED: " fname
+    }
+  }
+
+  print "forge-context-migrate: " n_ids " milestone id(s) processed"
+}
+AWKEOF
+
+awk -v dest="$dest" -v dryrun="$dry_run" -v existing="$existing_ids" \
+    -v skip_log="$skip_log" -v skip_shared="$skip_shared" \
+    -f "$awk_prog" "$source"