forge-orkes 0.79.0 → 0.80.1

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

@@ -0,0 +1,175 @@
+# 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
+
+### 0. Dry-run first and check the processed count
+
+```bash
+.claude/hooks/forge-context-migrate.sh --dry-run
+```
+
+Confirm the `forge-context-migrate: N milestone id(s) processed` line names a
+plausible number of ids for your `context.md`'s actual Locked Decisions
+headings. The tool exits non-zero and prints an `ERROR` line instead of a
+silent `0 milestone id(s) processed` when it finds Locked Decisions headings
+it can't resolve to any milestone id (issue #42) — but a dry-run check is
+still worth doing before the destructive untrack step below, since a partial
+match (some headings resolve, some don't) still exits 0. Milestone ids must
+be `m-<number>` (`M53`, `m-53`) or a labelled `m-<label>` form (`M-EVT01`,
+`m-SEQPRIM01`); anything else won't shard.
+
+### 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, numeric ids normalized to `m-{N}` and
+labelled ids lowercased and preserved, e.g. `m-evt01`),
+`.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.

package/template/.forge/migrations/0.80.0-size-gate-wiring.md

@@ -0,0 +1,145 @@
+# Migration Guide: Size gate wired to boot (Forge 0.80.0)
+
+Applies to projects upgrading to 0.80.0 or later. The size-gate check
+(`.claude/hooks/forge-size-gate.sh`, issue #37) — which warns when a
+context-engineering artifact (FORGE.md, context.md, a plan, a skill file, …)
+crosses its declared size gate — is now invoked mechanically by the same
+`SessionStart` hook that runs `forge-state-rollup.sh`. A boot session can no
+longer skip the check and let an artifact silently grow past its gate until
+someone notices by hand.
+
+`/upgrading` ships the new hook file (`.claude/hooks/forge-size-gate.sh`) like
+any other framework file. It does **not** wire the `SessionStart` invocation,
+because `.claude/settings.json` is a **user-owned file** — upgrades never
+overwrite it (FORGE.md → State Ownership, "Stable shared" class notes
+settings.json is propagated only via explicit installer steps, never blanket
+overwrite). Without this migration's one manual step, the hook ships but is
+never invoked: the executable exists, nothing mechanically triggers it.
+
+Projects that ran `initializing` fresh on 0.80.0+ (or already carry the
+`forge-size-gate` reference in their `SessionStart` block from an earlier
+partial adoption) need nothing further.
+
+## Prerequisites
+
+1. On the new version's framework files (`npx forge-orkes upgrade`, or the
+   `upgrading` skill) — so `.claude/hooks/forge-size-gate.sh` is present and
+   executable.
+2. Already migrated to 0.77.0's `forge-state-rollup.sh` SessionStart wiring
+   (`.forge/migrations/0.77.0-state-rollup-executable.md`) — this guide
+   assumes that hook block already exists in `.claude/settings.json` and
+   extends it, rather than creating a `SessionStart` block from scratch. If
+   that migration hasn't run yet, do it first.
+3. Working tree clean or changes committed — this migration edits
+   `.claude/settings.json`, a tracked file.
+
+## Detection
+
+Keyed on **the executable existing while the SessionStart wiring is
+absent** — the shipped-but-unwired gap. Uses `jq` to inspect
+`.claude/settings.json`'s `hooks.SessionStart` array for an entry referencing
+`forge-size-gate`; degrades to a plain-text grep if `jq` is not installed.
+Silent in a non-Forge / non-git tree, silent once the hook is wired:
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+[ -x .claude/hooks/forge-size-gate.sh ] || exit 0
+
+settings=".claude/settings.json"
+[ -f "$settings" ] || {
+  echo "MIGRATE — forge-size-gate.sh is present but $settings does not exist; add it with the SessionStart hook below"
+  exit 0
+}
+
+if command -v jq >/dev/null 2>&1; then
+  wired="$(jq -r '
+    (.hooks.SessionStart // []) as $entries
+    | [$entries[].hooks[]?.command // "" | select(contains("forge-size-gate"))]
+    | length > 0
+  ' "$settings" 2>/dev/null)"
+  if [ "$wired" != "true" ]; then
+    echo "MIGRATE — $settings has no SessionStart hook referencing forge-size-gate.sh; the executable shipped but nothing mechanically triggers it"
+  fi
+else
+  if ! grep -q "forge-size-gate" "$settings" 2>/dev/null; then
+    echo "MIGRATE — $settings has no reference to forge-size-gate.sh (jq unavailable, ran plain-text check); add the SessionStart hook below"
+  fi
+fi
+```
+
+## Migration steps
+
+### 1. Add the size-gate command to the SessionStart hook block
+
+Open `.claude/settings.json` and find the `hooks.SessionStart` array entry
+(added by the 0.77.0 migration). Append a second command object to that
+entry's `hooks` array, alongside the existing `forge-state-rollup.sh` command
+— **not** a second `SessionStart` array entry:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/forge-state-rollup.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/forge-state-rollup.sh\" || true"
+          },
+          {
+            "type": "command",
+            "command": "[ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/forge-size-gate.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/forge-size-gate.sh\" || true"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Both commands run on the same `startup|resume|clear` matcher, in order —
+`forge-state-rollup.sh` first (so caches are fresh), then
+`forge-size-gate.sh` (which only reads files, order doesn't matter
+functionally, but mirroring this repo's own `.claude/settings.json` keeps the
+two guides consistent).
+
+If `hooks.SessionStart` already has other entries (e.g. from a project-local
+customization) beyond the one 0.77.0 added, append the `forge-size-gate.sh`
+command object to whichever entry's `hooks` array already contains
+`forge-state-rollup.sh`, rather than creating a new array entry. If no
+`SessionStart` block exists yet at all (0.77.0's migration was skipped), run
+that migration first — this guide only adds a second command, it does not
+construct the block from scratch.
+
+The `[ -x ... ] && ... || true` guard means the hook is a no-op — never a
+boot failure — on any checkout where the script is absent or not executable
+(SessionStart hooks are non-blocking; `forge-size-gate.sh` itself also always
+exits 0 — it's an advisory, not a gate that can fail a boot).
+
+### 2. Commit the settings change
+
+```bash
+git add .claude/settings.json
+git commit -m "chore(forge): wire forge-size-gate SessionStart hook (0.80.0)"
+```
+
+## Validation
+
+- Start a new session, or run `/clear` — the boot summary line should include
+  a `[forge-size-gate] N artifact(s) over their declared gate: …` line if any
+  tracked artifact is currently over gate, or no `[forge-size-gate]` line at
+  all if everything is within gate (the hook is silent when there's nothing
+  to report — it does not print an "all clear" line). Either outcome means
+  the hook ran; the absence of a `[forge-size-gate]` clause is not the same
+  as the hook slot producing no output at all (compare to before this
+  migration, where the SessionStart summary had no size-gate clause because
+  nothing invoked the script).
+- `jq '.hooks.SessionStart' .claude/settings.json` prints the array with both
+  the `forge-state-rollup` and `forge-size-gate` commands present in the same
+  entry's `hooks` list.
+- Re-running the Detection block above now prints nothing (exits silently) —
+  the gap is closed.
+- Manually run `.claude/hooks/forge-size-gate.sh` from the repo root — it
+  should produce the same output the boot's SessionStart line showed,
+  confirming the wired invocation matches a direct run.

package/template/.forge/templates/constitution.md

@@ -130,4 +130,4 @@ Minimize framework token footprint. Compress prose, route models by task complex
 
 ## Amending the Constitution
 
-Articles can be amended only by explicit user decision during a discuss phase. Amendments are recorded in `.forge/context.md` with rationale. No agent may unilaterally override a constitutional article.
+Articles can be amended only by explicit user decision during a discuss phase. Amendments are recorded in the active milestone's `.forge/context/{id}.md` with rationale (`.forge/context.md` is a derived index, regenerated every boot — never a write target). No agent may unilaterally override a constitutional article.

package/template/.forge/templates/context-milestone.md

@@ -0,0 +1,30 @@
+# Per-Milestone Locked Context — `.forge/context/{id}.md`
+
+One file per milestone (`m-{N}.md`), holding exactly that milestone's slice
+of what the old monolithic `.forge/context.md` used to carry inline. Same
+append-only convention as before — strike through instead of rewriting when a
+decision changes; add an Amendment Log entry in `.forge/context-log.md`.
+
+The rendered `.forge/context.md` (derived index, `forge-state-rollup.sh`)
+prefers a `<!-- summary: ... -->` marker on the line right after the heading
+over the first bullet, when a hand-written one-liner is worth pinning.
+
+---
+
+### m-{N} — {Topic} (locked {date})
+
+<!-- summary: one-line hand-written summary for the derived index (optional) -->
+
+Context: {why this milestone exists / what triggered it}.
+
+- **[Topic]**: [Decision]. Reason: [Why this was chosen].
+
+## Deferred
+
+<!-- Deferred Ideas entries whose text starts with this milestone's id prefix
+     (e.g. "m-{N}: ...") land here during migration or ongoing work. -->
+
+## Discretion
+
+<!-- Discretion Areas entries whose text starts with this milestone's id
+     prefix land here during migration or ongoing work. -->

package/template/.forge/templates/slice-runner/config.yml

@@ -15,7 +15,13 @@ per_slice_budget_usd: 25
 
 # Max agent turns per headless phase (passed to `claude -p --max-turns`). Bounds a
 # single phase; cross-platform (unlike a `timeout` wall-clock, which macOS lacks).
-max_turns_per_phase: 60
+# Raised 60 -> 120 (m-54): three consecutive error_max_turns halts on large
+# content-editing phases (context.md shard/migration, FORGE.md trim), each attempt
+# landing real incremental progress before hitting the wall — the phases themselves
+# weren't stuck, 60 was just too tight for multi-file, iteratively-tested work.
+# Budget (per_slice_budget_usd) already gates cost independently, so this has
+# headroom: each halted attempt spent $2-6 of the $25 slice cap, nowhere near it.
+max_turns_per_phase: 120
 
 # RESERVED — not yet enforced. Intended as an optional per-phase wall-clock cap in
 # seconds (0 = off); the runner does not read this key yet (macOS has no stock