forge-orkes 0.79.0 → 0.80.1

package/bin/create-forge.js

@@ -885,6 +885,12 @@ async function upgrade() {
   //    initializing/upgrading skills' job, NOT the installer's — see makeGitHooksExecutable.
   upgradeAdditiveDir('.forge/git-hooks', results);
   makeGitHooksExecutable(path.join(targetDir, '.forge'));
+  // 2-bin. Sync the tracked worktree helper (0.78.0, ADR-031) — omitted from the
+  //    additive-sync category set until issue #41, so upgraded projects never
+  //    received .forge/bin/new-worktree.sh even though the weld's deny message
+  //    and migration guide both point at it. Additive, same reasoning as the
+  //    other .forge/ categories above.
+  upgradeAdditiveDir('.forge/bin', results);
 
   // 2a. Confirm stale framework-file removals before deleting (R066a). Defaults
   //     to yes (cleanup is the normal case); auto-confirms when non-interactive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.79.0",
+  "version": "0.80.1",
   "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,317 @@
+#!/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}`; or a
+#     labelled id like `M-EVT01`, `m-SEQPRIM01` — normalized to lowercase with
+#     the label preserved, e.g. `m-evt01`, `m-seqprim01`, never digit-stripped)
+#     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, suffix) {
+  w = line
+  sub(/^### /, "", w)
+  sub(/^- /, "", w)
+  sub(/^~~/, "", w)
+  n = split(w, arr, /[ \t]/)
+  if (n < 1) return ""
+  tok = arr[1]
+  gsub(/[:,.]+$/, "", tok)
+  # Purely-numeric ids (M53, m-53, m53) keep the original digit-only
+  # normalization. Labelled ids (M-EVT01, m-SEQPRIM01) must NOT be digit-
+  # stripped — that would collapse distinct labelled ids onto the same
+  # numeric suffix (m-EVT01 and m-SEQPRIM01 would both become m-01) — so
+  # their alphanumeric suffix is preserved verbatim (lowercased) instead.
+  if (tok !~ /^[Mm]-?[A-Za-z0-9]+$/) return ""
+  suffix = tok
+  sub(/^[Mm]-?/, "", suffix)
+  if (suffix == "") return ""
+  if (suffix ~ /^[0-9]+$/) {
+    digits = suffix
+    gsub(/[^0-9]/, "", digits)
+    return "m-" digits
+  }
+  return "m-" tolower(suffix)
+}
+
+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
+    }
+  }
+
+  if (n_ids == 0 && n_noid > 0) {
+    print "forge-context-migrate: ERROR — 0 milestone id(s) resolved but " n_noid \
+      " Locked Decision heading(s) found with no resolvable id; this usually means the" \
+      " heading's id scheme doesn't match m-<number> or a labelled m-<label> form" \
+      " (check context.md's heading format before proceeding)" > "/dev/stderr"
+    print "forge-context-migrate: " n_ids " milestone id(s) processed"
+    exit 1
+  }
+
+  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-release-fold.sh

@@ -28,7 +28,13 @@
 #   (3) unknown in both → exit 2 — the fold cannot ask the question, so it
 #       never emits a false verdict.
 #
-# merged = `git merge-base --is-ancestor <sha> <main-ref>`.
+# merged = `git merge-base --is-ancestor <sha> <main-ref>`, OR — when that
+# fails — a squash-merge equivalence check (see is_merged() below). GitHub's
+# squash-and-merge creates a brand-new commit on <main-ref> with no ancestor
+# relationship to the source branch, so the direct check alone is a permanent
+# false negative for any squash-merged unit whose branch/stream ref is still
+# live (issue #39, m-55; reproduced live via m-53/PR#38). The fallback stays
+# git-only, no network — NFR-030 unaffected.
 #
 # Validation is dispatched on forge.validation_event from the project's
 # .forge/project.yml (default: in_session_signoff; promotion_approval is the
@@ -171,6 +177,33 @@ hv_is_set() {
   '
 }
 
+# is_merged <sha> — merged rung of the fold. Direct ancestor check first
+# (unchanged cost/behavior for fast-forward / true-merge-commit units). On
+# failure, falls back to a squash-merge equivalence check: build an
+# unreferenced synthetic commit representing <sha>'s cumulative diff since it
+# diverged from $main_ref, then ask `git cherry` (patch-id based — the same
+# primitive git itself uses to detect already-applied/rebased/squashed
+# commits) whether an equivalent patch already landed on $main_ref. Squash-
+# and-merge creates a brand-new commit with no ancestor relationship to the
+# source branch, so the direct check alone is a permanent false negative for
+# every squash-merged unit whose branch/stream ref is still live (m-53/PR#38,
+# issue #39). Git-only, no network (NFR-030 preserved) — the synthetic commit
+# is never attached to a ref, so it's naturally garbage-collectable.
+is_merged() {
+  target="$1"
+  if git -C "$root" merge-base --is-ancestor "$target" "$main_ref" 2>/dev/null; then
+    return 0
+  fi
+  mb="$(git -C "$root" merge-base "$main_ref" "$target" 2>/dev/null)" || return 1
+  [ -n "$mb" ] || return 1
+  tgt_tree="$(git -C "$root" rev-parse -q --verify "$target^{tree}" 2>/dev/null)" || return 1
+  synth="$(git -C "$root" commit-tree "$tgt_tree" -p "$mb" -m squash-probe 2>/dev/null)" || return 1
+  case "$(git -C "$root" cherry "$main_ref" "$synth" 2>/dev/null)" in
+    -*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 # --- argument parsing ------------------------------------------------------
 
 unit=""
@@ -281,7 +314,7 @@ fi
 # validated REQUIRES merged — checked first, always. An unmerged unit is
 # unmerged no matter what any approval artifact says.
 
-if ! git -C "$root" merge-base --is-ancestor "$sha" "$main_ref" 2>/dev/null; then
+if ! is_merged "$sha"; then
   printf 'release_state=unmerged reason=not-on-main\n'
   exit 0
 fi

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