forge-orkes 0.79.0 → 0.80.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.79.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"

package/template/.claude/hooks/forge-size-gate.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env sh
+# forge-size-gate — mechanical enforcement of FORGE.md's Size Gates table
+# (issue #37). Size gates were prose-only: nothing measured an artifact
+# against its declared KB gate, so FORGE.md itself drifted over its own
+# 35 KB gate and context.md drifted ~4x over its 12 KB gate before anyone
+# noticed. This hook is the mechanical check — it runs at every boot and
+# advises, once, when something is over.
+#
+#   forge-size-gate.sh [--project <path>]
+#   (SessionStart hook)  reads {cwd, hook_event_name, source} from stdin JSON.
+#
+#     --project <path>   operate on the repo containing <path>. Default: the
+#                        SessionStart payload's `cwd`, else the CWD. NEVER
+#                        $CLAUDE_PROJECT_DIR — see forge-state-rollup.sh for
+#                        why (that resolves to the main checkout even inside
+#                        a worktree).
+#
+# What it checks — every artifact FORGE.md's Size Gates table declares a KB
+# gate for (read the table directly at $root/.forge/FORGE.md, not
+# hallucinated): FORGE.md, project.yml, requirements/m*.yml (each file, not
+# summed), constitution.md, context.md, refactor-backlog.yml,
+# streams/active.yml, streams/*.yml (per file, excluding active.yml itself —
+# a different gate), streams/*/brief.md (per file), reservations.yml,
+# prototypes/*.md (per file — archive/ is a subdirectory so a flat glob never
+# reaches it). plan-{NN}.md instances are deliberately NOT checked here —
+# there are too many to enumerate at boot and no single "current" one;
+# planning's own Step 8 already lints plan size at creation time.
+#
+# Plus a tiered skill-file class this hook introduces: every
+# .claude/skills/*/SKILL.md is checked against a KB gate that depends on
+# whether the skill is an entry point. Entry-point skill names are listed one
+# per line in .claude/hooks/skill-gate-tiers.txt (40 KB tier); every other
+# skill defaults to the stricter 20 KB tier. A missing tier-list file
+# degrades to "no skills are entry-point" — every skill checked at 20 KB —
+# never a crash.
+#
+# KB is decimal (1 KB = 1000 B), matching the numbers FORGE.md's own Size
+# Gates table was measured against (research/milestone-54.md: FORGE.md is
+# "35,834 B against the declared 35 KB gate" — over only under the decimal
+# reading).
+#
+# A declared-gate artifact that does not exist in this repo (e.g. no
+# prototypes/ dir yet) is skipped silently — not an error, not a violation.
+#
+# Contract (SessionStart, mirrors forge-state-rollup.sh — ADR-032):
+#   - Exit 0 ALWAYS. SessionStart is non-blocking; this hook must never abort
+#     a session.
+#   - Read-only. No writes, no cache, nothing to render.
+#   - stdout is injected into the model's context. When every checked
+#     artifact is within gate, this hook prints NOTHING — a silent pass costs
+#     zero context. When one or more are over, it prints exactly ONE terse
+#     summary line naming every offender, never a multi-line dump (a
+#     multi-line dump would itself be the token-cost problem this hook
+#     exists to prevent).
+#
+# Portable: POSIX sh + git + wc. No network calls (NFR-030).
+
+set -u
+
+# --- argument / stdin parsing ------------------------------------------------
+
+project=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --project) shift; project="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+    --project=*) project="${1#*=}"; shift ;;
+    -*) shift ;;                 # unknown flag — ignore, never fail a boot hook
+    *) shift ;;
+  esac
+done
+
+# SessionStart delivers {cwd, source, hook_event_name, ...} on stdin. When no
+# --project was given, prefer the payload's cwd (the actual worktree the
+# session started in) over the process CWD. Read stdin only if it is not a
+# tty and jq is present; never block waiting for input that will not arrive.
+stdin_cwd=""
+if [ -z "$project" ] && [ ! -t 0 ] && command -v jq >/dev/null 2>&1; then
+  payload="$(cat 2>/dev/null || true)"
+  if [ -n "$payload" ]; then
+    stdin_cwd="$(printf '%s' "$payload" | jq -r '.cwd // empty' 2>/dev/null || true)"
+  fi
+fi
+[ -z "$project" ] && project="${stdin_cwd:-$PWD}"
+
+# --- repo resolution ---------------------------------------------------------
+# Silent no-op when not in a git repo or the repo has no .forge/ — the common
+# case for a non-Forge session, and this hook must be invisible there.
+
+root="$(git -C "$project" rev-parse --show-toplevel 2>/dev/null)" || exit 0
+[ -d "$root/.forge" ] || exit 0
+
+TIER_FILE="$root/.claude/hooks/skill-gate-tiers.txt"
+
+# --- violation bookkeeping ----------------------------------------------------
+
+VIOLATIONS=""
+VIOLATION_COUNT=0
+
+record_violation() { # path actual_bytes gate_kb
+  VIOLATIONS="${VIOLATIONS}${VIOLATIONS:+, }$1 (${2}B/${3}KB)"
+  VIOLATION_COUNT=$((VIOLATION_COUNT + 1))
+}
+
+# check_gate <abs_path> <gate_kb> — decimal KB (1 KB = 1000 B). Missing file
+# is skipped silently, not a violation.
+check_gate() {
+  f="$1"; kb="$2"
+  [ -f "$f" ] || return 0
+  bytes="$(wc -c < "$f" 2>/dev/null | tr -d ' ')"
+  [ -z "$bytes" ] && return 0
+  limit=$((kb * 1000))
+  if [ "$bytes" -gt "$limit" ]; then
+    rel="${f#"$root"/}"
+    record_violation "$rel" "$bytes" "$kb"
+  fi
+}
+
+# --- declared single-file artifacts (FORGE.md Size Gates table) -------------
+
+check_gate "$root/.forge/FORGE.md" 35
+check_gate "$root/.forge/project.yml" 5
+check_gate "$root/.forge/constitution.md" 10
+check_gate "$root/.forge/context.md" 12
+check_gate "$root/.forge/refactor-backlog.yml" 150
+check_gate "$root/.forge/streams/active.yml" 20
+check_gate "$root/.forge/reservations.yml" 50
+
+# --- declared per-file glob artifacts (each file checked individually) ------
+
+for f in "$root"/.forge/requirements/m*.yml; do
+  [ -f "$f" ] || continue
+  check_gate "$f" 50
+done
+
+for f in "$root"/.forge/streams/*.yml; do
+  [ -f "$f" ] || continue
+  case "$(basename "$f")" in active.yml) continue ;; esac
+  check_gate "$f" 15
+done
+
+for f in "$root"/.forge/streams/*/brief.md; do
+  [ -f "$f" ] || continue
+  check_gate "$f" 8
+done
+
+for f in "$root"/.forge/prototypes/*.md; do
+  [ -f "$f" ] || continue
+  check_gate "$f" 8
+done
+
+# --- tiered skill-file class --------------------------------------------------
+# Entry-point skills (listed by name in skill-gate-tiers.txt) get 40 KB;
+# every other skill defaults to the stricter 20 KB tier. Missing tier-list
+# file → every skill defaults to 20 KB, never a crash.
+
+for f in "$root"/.claude/skills/*/SKILL.md; do
+  [ -f "$f" ] || continue
+  skill_name="$(basename "$(dirname "$f")")"
+  skill_kb=20
+  if [ -f "$TIER_FILE" ] && grep -qx "$skill_name" "$TIER_FILE" 2>/dev/null; then
+    skill_kb=40
+  fi
+  check_gate "$f" "$skill_kb"
+done
+
+# --- summary (stdout → injected into boot context) ---------------------------
+# Silent when clean. One terse line when not.
+
+if [ "$VIOLATION_COUNT" -gt 0 ]; then
+  printf '[forge-size-gate] %s artifact(s) over their declared gate: %s — see FORGE.md § Size Gates\n' \
+    "$VIOLATION_COUNT" "$VIOLATIONS"
+fi
+
+exit 0

package/template/.claude/hooks/forge-state-rollup.sh

@@ -7,6 +7,11 @@
 # (which a "the index is stale, work around it" project-memory habit can
 # out-compete — the exact ptnrkit failure #22 was filed against).
 #
+# A third join (ADR-033, issue #37) renders .forge/context.md itself as a
+# derived index over .forge/context/*.md — the per-milestone decision files
+# forge-context-migrate.sh produces. Same contract as the other two: derived,
+# git-ignored, rendered fresh every boot, never hand-edited.
+#
 #   forge-state-rollup.sh [--project <path>] [--quiet]
 #   (SessionStart hook)  reads {cwd, hook_event_name, source} from stdin JSON.
 #
@@ -17,9 +22,11 @@
 #                        render this worktree's caches into the wrong tree.
 #     --quiet            suppress the stdout summary line (still writes caches).
 #
-# What it writes (both are git-ignored render-on-read caches since 0.53.0):
+# What it writes (all three are git-ignored render-on-read caches since
+# 0.53.0 / this addendum for context.md):
 #     .forge/state/index.yml       — derived milestone registry
 #     .forge/streams/active.yml    — derived stream registry (if streams/ exists)
+#     .forge/context.md            — derived context index (if context/ exists)
 # It NEVER commits them and NEVER runs git add/commit. Rendering a gitignored
 # cache is a local write that never lands on main, so any checkout (main OR
 # worktree) may render its own copy (FORGE.md → State Ownership, Derived class).
@@ -398,15 +405,136 @@ render_active() {
   STREAM_ROW_COUNT="$sn"
 }
 
+# --- Context Index (ADR-033 addendum) ----------------------------------------
+# Third join: .forge/context/*.md (one file per milestone, produced by
+# forge-context-migrate.sh) ⋈ the index.yml rows this same pass already
+# rendered above — no second fold invocation, reuse what render_index wrote.
+
+# context_index_lookup <norm_id> — prints "name\tstatus\trelease_state" for
+# the index.yml row matching <norm_id> (already normalized, no leading "m-").
+# Empty output when no row matches — degrade gracefully, never error.
+context_index_lookup() {
+  awk -v want="$1" '
+    /^  - id:/ { id=$3; gsub(/["\x27]/,"",id); sub(/^m-/,"",id); inrow=(id==want); name=""; status=""; rel="" }
+    inrow && /^    name:/ { name=$0; sub(/^    name: /,"",name); gsub(/^["\x27]|["\x27]$/,"",name) }
+    inrow && /^    status:/ { status=$2 }
+    inrow && /^    release_state:/ { rel=$2; print name "\t" status "\t" rel; exit }
+  ' "$root/.forge/state/index.yml" 2>/dev/null
+}
+
+# context_summary <file> — a <!-- summary: ... --> marker wins over the
+# first "- " bullet; empty when the file has neither (row still renders,
+# just with an empty summary — never a crash).
+context_summary() {
+  f="$1"
+  s="$(awk '/<!-- summary:/ { line=$0; sub(/^.*<!-- summary: */,"",line); sub(/ *-->.*$/,"",line); print line; exit }' "$f" 2>/dev/null)"
+  if [ -z "$s" ]; then
+    s="$(awk '/^- / { line=$0; sub(/^- /,"",line); print line; exit }' "$f" 2>/dev/null)"
+  fi
+  printf '%s\n' "$s"
+}
+
+CONTEXT_ROW_COUNT=0
+
+render_context_index() {
+  context_path="$root/.forge/context.md"
+  ctx_rows=""     # "id\tname\tstatus\trelease_state\tsummary\tpath"
+  cn=0
+
+  for cfile in "$root"/.forge/context/*.md; do
+    [ -f "$cfile" ] || continue
+    case "$(basename "$cfile")" in _shared.md) continue ;; esac
+    c_id="$(basename "$cfile" .md)"
+    [ -z "$c_id" ] && continue
+    rel_path=".forge/context/$(basename "$cfile")"
+
+    fields="$(context_index_lookup "$(norm_id "$c_id")")"
+    if [ -n "$fields" ]; then
+      c_name="$(printf '%s' "$fields" | awk -F'\t' '{print $1}')"
+      c_status="$(printf '%s' "$fields" | awk -F'\t' '{print $2}')"
+      c_rel="$(printf '%s' "$fields" | awk -F'\t' '{print $3}')"
+    else
+      c_name=""
+      c_status="unknown"
+      c_rel="unknown"
+    fi
+    [ -z "$c_status" ] && c_status="unknown"
+    [ -z "$c_rel" ] && c_rel="unknown"
+    c_summary="$(context_summary "$cfile")"
+
+    # A tab-delimited empty field is unsafe: `read` with IFS set to a plain
+    # tab still treats it as IFS-whitespace, so consecutive/empty fields get
+    # collapsed and every column after them shifts left. name/summary are the
+    # only fields that can legitimately be empty — substitute a sentinel and
+    # translate it back to "" after the read loop below.
+    [ -z "$c_name" ] && c_name="@@EMPTY@@"
+    [ -z "$c_summary" ] && c_summary="@@EMPTY@@"
+
+    ctx_rows="$ctx_rows$c_id	$c_name	$c_status	$c_rel	$c_summary	$rel_path
+"
+    cn=$((cn + 1))
+  done
+
+  sorted="$(printf '%s' "$ctx_rows" | LC_ALL=C sort -t'	' -k1,1)"
+
+  {
+    printf '# Locked Context — Index (DERIVED — do not hand-edit)\n'
+    printf '# Regenerated at boot by .claude/hooks/forge-state-rollup.sh: one row per\n'
+    printf '# .forge/context/{id}.md, joined with state/index.yml (status/release_state\n'
+    printf '# already resolved by this same pass). Git-ignored render-on-read cache —\n'
+    printf '# never committed. Full decision text lives in .forge/context/{id}.md, not\n'
+    printf '# here. See .forge/context-log.md (Amendment Log + Needs Resolution + any\n'
+    printf '# content with no resolvable milestone id) and .forge/context/_shared.md\n'
+    printf '# (cross-cutting Deferred Ideas / Discretion Areas, if present).\n'
+    printf '#\n'
+    printf '# Rules (apply to every context/{id}.md this index points at):\n'
+    printf '# - Locked Decisions -> MUST be implemented exactly as stated.\n'
+    printf '# - Deferred Ideas -> MUST NOT appear in plans, tasks, or code.\n'
+    printf '# - Discretion Areas -> Agent uses judgment; research, pick, document why.\n'
+    printf '#\n'
+    printf '# A milestone that is complete AND validated renders as a thin row\n'
+    printf '# (id, name, path only) — content never moves, only the render shortens.\n'
+    printf 'context:\n'
+    if [ "$cn" -eq 0 ]; then
+      printf '  []\n'
+    else
+      printf '%s\n' "$sorted" | while IFS='	' read -r r_id r_name r_status r_rel r_summary r_path; do
+        [ -z "$r_id" ] && continue
+        [ "$r_name" = "@@EMPTY@@" ] && r_name=""
+        [ "$r_summary" = "@@EMPTY@@" ] && r_summary=""
+        printf '  - id: %s\n' "$r_id"
+        printf '    name: %s\n' "$(yaml_quote "$r_name")"
+        if [ "$r_status" = "complete" ] && [ "$r_rel" = "validated" ]; then
+          printf '    path: %s\n' "$r_path"
+        else
+          printf '    status: %s\n' "$r_status"
+          printf '    release_state: %s\n' "$r_rel"
+          [ -n "$r_summary" ] && printf '    summary: %s\n' "$(yaml_quote "$r_summary")"
+          printf '    path: %s\n' "$r_path"
+        fi
+      done
+    fi
+    printf 'see_also:\n'
+    printf '  - .forge/context-log.md\n'
+    printf '  - .forge/context/_shared.md\n'
+  } > "$context_path.tmp.$$" && mv -f "$context_path.tmp.$$" "$context_path"
+
+  CONTEXT_ROW_COUNT="$cn"
+}
+
 # --- run ---------------------------------------------------------------------
 
-render_index                 # index.yml first — stream rollup reads it
+render_index                 # index.yml first — stream rollup + context index read it
 
 if [ -d "$root/.forge/streams" ]; then
   stream_autoclose_sweep     # step 0 (main checkout only)
   render_active              # then the join
 fi
 
+if [ -d "$root/.forge/context" ]; then
+  render_context_index       # third join
+fi
+
 # --- summary (stdout → injected into boot context) ---------------------------
 
 if [ "$quiet" -eq 0 ]; then
@@ -418,6 +546,11 @@ if [ "$quiet" -eq 0 ]; then
     [ "${STREAM_ROW_COUNT:-0}" = "1" ] || summary="${summary}s"
     summary="$summary)"
   fi
+  if [ -d "$root/.forge/context" ]; then
+    summary="$summary + context.md (${CONTEXT_ROW_COUNT:-0} context row"
+    [ "${CONTEXT_ROW_COUNT:-0}" = "1" ] || summary="${summary}s"
+    summary="$summary)"
+  fi
   [ -n "$SWEEP_CLOSED" ] && summary="$summary; auto-closed:${SWEEP_CLOSED}"
   [ "${fold_unavailable:-0}" -gt 0 ] && summary="$summary; ${fold_unavailable} release_state unknown (fold unavailable)"
   if [ "$in_main_checkout" -eq 1 ]; then

package/template/.claude/hooks/skill-gate-tiers.txt

@@ -0,0 +1,6 @@
+# Entry-point skills — checked against the 40KB size gate by
+# forge-size-gate.sh instead of the 20KB default every other skill gets.
+# One skill name per line (matches the skill's directory name under
+# .claude/skills/). Lines starting with # are comments.
+forge
+chief-of-staff