forge-orkes 0.79.0 → 0.80.1

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

package/template/.claude/hooks/tests/forge-context-migrate.test.sh

@@ -0,0 +1,248 @@
+#!/usr/bin/env sh
+# Self-contained fixture test for .claude/hooks/forge-context-migrate.sh
+# (phase 95 plan-01 task 1, issue #37 / ADR-033).
+#
+# Builds a small throwaway monolithic context.md fixture covering every
+# classification case the migrator has to get right: an `M{N}` heading, a
+# `m-{N}` heading, an id-less "drafting" heading, prefixed + unprefixed
+# Deferred/Discretion entries, Needs Resolution, and an Amendment Log. Proves:
+# one context/{id}.md per locked milestone heading, id-less content routed to
+# context-log.md (never a milestone), unprefixed Deferred/Discretion entries
+# routed to context/_shared.md (never guessed onto a milestone), and that
+# re-running against an already-migrated tree is a no-op (skips every id,
+# touches no existing file).
+#
+# Run:  ./.claude/hooks/tests/forge-context-migrate.test.sh
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+MIGRATE="$SCRIPT_DIR/../forge-context-migrate.sh"
+
+[ -x "$MIGRATE" ] || { printf 'FATAL: migrator not executable: %s\n' "$MIGRATE" >&2; exit 1; }
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+pass() { PASSED=$((PASSED + 1)); printf 'PASS: %s\n' "$1"; }
+fail() { FAILED=$((FAILED + 1)); printf 'FAIL: %s\n' "$1" >&2; }
+check_file() { [ -f "$1" ] && pass "$2" || fail "$2 (missing: $1)"; }
+check_absent_file() { [ -f "$1" ] && fail "$2 (should not exist: $1)" || pass "$2"; }
+check_has() { case "$2" in *"$3"*) pass "$1" ;; *) fail "$1 (missing substring '$3')" ;; esac; }
+check_absent() { case "$2" in *"$3"*) fail "$1 (must NOT contain '$3')" ;; *) pass "$1" ;; esac; }
+
+FIXDIR="$ROOT/src"
+mkdir -p "$FIXDIR"
+SOURCE="$FIXDIR/context.md"
+DEST="$ROOT/.forge"
+mkdir -p "$DEST"
+
+cat > "$SOURCE" <<'FIXTURE'
+# Locked Context
+
+Preamble prose that belongs to nobody — dropped, never carried anywhere.
+
+---
+
+## Locked Decisions
+
+### M7 — Widget Registry (locked 2026-01-01)
+
+Context: why m7 exists.
+
+- **Decision A**: Do the thing. Reason: because.
+
+### m-9 — Gadget Pipeline (locked 2026-01-02)
+
+- **Decision B**: Do the other thing. Reason: also because.
+
+### M? — Future Program (drafting)
+
+- **Draft idea**: not locked yet, no milestone id assigned.
+
+## Deferred Ideas
+
+- M7: narrower follow-up — Deferred because: out of scope. Revisit: later.
+- Cross-cutting idea with no milestone prefix — Deferred because: nobody owns
+  this yet. Revisit: when it does.
+
+## Discretion Areas
+
+- m-9: exact wording of the follow-up doc.
+- Generic discretion with no prefix at all.
+
+## Needs Resolution
+
+(none)
+
+---
+
+## Amendment Log
+
+| Date | Change | Rationale | Approved By |
+|------|--------|-----------|-------------|
+| 2026-01-01 | Added M7 | Fixture seed | Tester |
+FIXTURE
+
+# --- first run: real migration --------------------------------------------
+
+OUT1="$("$MIGRATE" --source "$SOURCE" --dest "$DEST" 2>&1)"
+RC1=$?
+check() { [ "$RC1" -eq 0 ] && pass "$1" || fail "$1 (exit $RC1)"; }
+check "migrator exits 0 on first run"
+
+check_file "$DEST/context/m-7.md" "context/m-7.md created (M7 heading normalized)"
+check_file "$DEST/context/m-9.md" "context/m-9.md created (m-9 heading)"
+check_absent_file "$DEST/context/m-future.md" "no file invented for the M? drafting block"
+check_file "$DEST/context-log.md" "context-log.md created"
+check_file "$DEST/context/_shared.md" "context/_shared.md created"
+
+m7="$(cat "$DEST/context/m-7.md" 2>/dev/null)"
+check_has "m-7.md carries its Locked Decision body" "$m7" "Do the thing"
+check_has "m-7.md carries its own Deferred entry (prefix match)" "$m7" "narrower follow-up"
+check_absent "m-7.md does NOT carry m-9's Discretion entry" "$m7" "exact wording of the follow-up doc"
+
+m9="$(cat "$DEST/context/m-9.md" 2>/dev/null)"
+check_has "m-9.md carries its Locked Decision body" "$m9" "Do the other thing"
+check_has "m-9.md carries its own Discretion entry (prefix match)" "$m9" "exact wording of the follow-up doc"
+
+log="$(cat "$DEST/context-log.md" 2>/dev/null)"
+check_has "context-log.md carries the id-less drafting block" "$log" "Future Program"
+check_has "context-log.md carries the Amendment Log verbatim" "$log" "Added M7"
+check_has "context-log.md carries Needs Resolution" "$log" "(none)"
+check_absent "context-log.md does NOT carry M7's locked content" "$log" "Do the thing"
+
+shared="$(cat "$DEST/context/_shared.md" 2>/dev/null)"
+check_has "_shared.md carries the unprefixed Deferred entry" "$shared" "Cross-cutting idea with no milestone prefix"
+check_has "_shared.md carries the unprefixed Discretion entry" "$shared" "Generic discretion with no prefix"
+check_absent "_shared.md does NOT carry M7's prefixed Deferred entry" "$shared" "narrower follow-up"
+
+# --- idempotency: second run must be a pure no-op --------------------------
+
+sum_before_7="$(cat "$DEST/context/m-7.md" | wc -c)"
+sum_before_log="$(cat "$DEST/context-log.md" | wc -c)"
+sum_before_shared="$(cat "$DEST/context/_shared.md" | wc -c)"
+
+OUT2="$("$MIGRATE" --source "$SOURCE" --dest "$DEST" 2>&1)"
+RC2=$?
+[ "$RC2" -eq 0 ] && pass "migrator exits 0 on re-run" || fail "migrator exits 0 on re-run (exit $RC2)"
+
+check_has "re-run reports a SKIP for m-7" "$OUT2" "SKIP"
+check_has "re-run names m-7 in a skip line" "$OUT2" "m-7"
+
+sum_after_7="$(cat "$DEST/context/m-7.md" | wc -c)"
+sum_after_log="$(cat "$DEST/context-log.md" | wc -c)"
+sum_after_shared="$(cat "$DEST/context/_shared.md" | wc -c)"
+
+[ "$sum_before_7" -eq "$sum_after_7" ] && pass "re-run left context/m-7.md byte-identical" || fail "re-run mutated context/m-7.md"
+[ "$sum_before_log" -eq "$sum_after_log" ] && pass "re-run left context-log.md byte-identical" || fail "re-run mutated context-log.md"
+[ "$sum_before_shared" -eq "$sum_after_shared" ] && pass "re-run left context/_shared.md byte-identical" || fail "re-run mutated context/_shared.md"
+
+file_count_after="$(ls "$DEST"/context/*.md 2>/dev/null | wc -l | tr -d ' ')"
+[ "$file_count_after" -eq 3 ] && pass "re-run created no duplicate files (still m-7, m-9, _shared)" || fail "re-run changed file count (got $file_count_after, want 3)"
+
+# --- dry-run touches nothing -------------------------------------------------
+
+DRYDEST="$ROOT/.forge-dry"
+mkdir -p "$DRYDEST/context"
+OUT3="$("$MIGRATE" --source "$SOURCE" --dest "$DRYDEST" --dry-run 2>&1)"
+RC3=$?
+[ "$RC3" -eq 0 ] && pass "dry-run exits 0" || fail "dry-run exits 0 (exit $RC3)"
+check_has "dry-run reports what it would do" "$OUT3" "DRY-RUN"
+check_absent_file "$DRYDEST/context/m-7.md" "dry-run creates no real file"
+check_absent_file "$DRYDEST/context-log.md" "dry-run creates no real context-log.md"
+
+# --- source file is never modified ------------------------------------------
+
+src_after="$(cat "$SOURCE" | wc -c)"
+[ -n "$src_after" ] && pass "source context.md still readable after migration" || fail "source context.md unreadable after migration"
+grep -q "### M7 — Widget Registry" "$SOURCE" && pass "source context.md left untouched" || fail "source context.md was modified"
+
+# --- labelled milestone ids (issue #42) -------------------------------------
+# Non-numeric ids (M-EVT01, m-SEQPRIM01) must shard into distinct files —
+# digit-stripping them onto a shared "m-01" was the exact silent-collision
+# bug reported upstream. Purely-numeric ids must keep their existing
+# normalization (m-53 stays m-53, unaffected by the labelled-id path).
+
+LBLROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT" "$LBLROOT"' EXIT INT TERM
+LBLSRC="$LBLROOT/context.md"
+LBLDEST="$LBLROOT/.forge"
+mkdir -p "$LBLDEST"
+
+cat > "$LBLSRC" <<'FIXTURE'
+## Locked Decisions
+
+### M-EVT01 — Event pipeline
+
+- **Decision**: Emit events. Reason: because.
+
+### m-SEQPRIM01 — Sequencer primitives
+
+- **Decision**: Order things. Reason: also because.
+
+### m-53 — Numeric id alongside labelled ones
+
+- **Decision**: Still works numerically.
+
+## Deferred Ideas
+
+- m-EVT01: a follow-up scoped to the labelled id.
+
+## Needs Resolution
+
+(none)
+
+## Amendment Log
+
+(none)
+FIXTURE
+
+LBLOUT="$("$MIGRATE" --source "$LBLSRC" --dest "$LBLDEST" 2>&1)"
+LBLRC=$?
+[ "$LBLRC" -eq 0 ] && pass "labelled-id migration exits 0" || fail "labelled-id migration exits 0 (exit $LBLRC)"
+
+check_file "$LBLDEST/context/m-evt01.md" "context/m-evt01.md created (labelled id, lowercased)"
+check_file "$LBLDEST/context/m-seqprim01.md" "context/m-seqprim01.md created (distinct from m-evt01, not digit-collapsed)"
+check_file "$LBLDEST/context/m-53.md" "context/m-53.md still created (numeric id unaffected by labelled-id path)"
+
+lbl_count="$(ls "$LBLDEST"/context/*.md 2>/dev/null | wc -l | tr -d ' ')"
+[ "$lbl_count" -eq 3 ] && pass "labelled + numeric ids produce 3 distinct files, none collapsed" || fail "labelled-id run produced $lbl_count file(s), want 3"
+
+evt="$(cat "$LBLDEST/context/m-evt01.md" 2>/dev/null)"
+check_has "m-evt01.md carries its own Deferred entry (labelled-prefix match)" "$evt" "a follow-up scoped to the labelled id"
+
+# --- unresolvable id scheme guard (issue #42) --------------------------------
+# A context.md whose Locked Decisions headings don't match m-<number> or a
+# labelled m-<label> form at all (e.g. a different project's own convention)
+# must fail loudly instead of silently producing zero shards.
+
+BADROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT" "$LBLROOT" "$BADROOT"' EXIT INT TERM
+BADSRC="$BADROOT/context.md"
+BADDEST="$BADROOT/.forge"
+mkdir -p "$BADDEST"
+
+cat > "$BADSRC" <<'FIXTURE'
+## Locked Decisions
+
+### FEATURE-ABC — unrelated id scheme
+
+- **Decision**: Something.
+
+### FEATURE-XYZ — another unrelated id
+
+- **Decision**: Something else.
+FIXTURE
+
+BADOUT="$("$MIGRATE" --source "$BADSRC" --dest "$BADDEST" --dry-run 2>&1)"
+BADRC=$?
+[ "$BADRC" -ne 0 ] && pass "unresolvable id scheme exits non-zero instead of silently producing 0 shards" || fail "unresolvable id scheme should exit non-zero (exit $BADRC)"
+check_has "unresolvable id scheme prints an ERROR line" "$BADOUT" "ERROR"
+
+# --- summary -----------------------------------------------------------------
+
+printf '\n%s passed, %s failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ] || exit 1
+exit 0

package/template/.claude/hooks/tests/forge-release-fold.test.sh

@@ -24,7 +24,7 @@
 #   ./.claude/hooks/tests/forge-release-fold.test.sh ordering    # ordering controls
 # Filter tags (one arg, selects matching case blocks):
 #   unmerged merged grandfather human-verified signoff-tag stored-field
-#   exit-2 stable-sha ordering promotion forgery labeled
+#   exit-2 stable-sha ordering promotion forgery labeled squash
 # `promotion` + `forgery` (plan 51-01): validation_event=promotion_approval —
 # a CI-signed tag on a deploy sha CONTAINING the unit's landed sha validates;
 # tag deletion reverts; unsigned/wrong-key lookalikes and non-containing tags
@@ -791,9 +791,60 @@ lifecycle:
   check_absent "unsafe labeled id: no verdict on stdout" "$OUT" "release_state="
 fi
 
+# --- case: squash-merged unit resolves merged (issue #39, m-53/PR#38 shape) -----
+# GitHub squash-and-merge creates a brand-new commit on main with no ancestor
+# relationship to the source branch — the direct ancestor check alone
+# permanently misreports this as unmerged. Reproduces the real bug shape:
+# a live branch tip (resolved via streams/m-N.yml runtime.branch, exactly
+# resolution rule 1's `else` route — no lifecycle.worktree_branch in the state
+# file, matching the real m-53 fixture), plus an unrelated commit on main
+# between the branch's fork point and the squash (mirrors main advancing
+# independently in between — and would defeat a naive whole-tree-hash
+# comparison, which this repo's own investigation found fails under exactly
+# this kind of drift).
+if running squash; then
+  printf '\n--- case: squash-merged unit resolves merged (git merge --squash, not --no-ff) ---\n'
+  d="$(new_repo squash)"
+  write_milestone "$d" 120 'milestone:
+  id: 120
+  name: "fixture: squash-merged unit"
+
+current:
+  tier: standard
+  status: executing
+  last_updated: "2026-07-29"
+  human_verified: null
+
+lifecycle:
+  worktree_mode: active'
+  write_stream "$d" m-120 forge/m-120
+  git -C "$d" checkout -qb forge/m-120
+  # Real file content — an --allow-empty commit here would give the branch a
+  # zero-diff tip, making the squash-probe trivially match ANY zero-diff main
+  # commit regardless of the mechanism under test. Genuine content is what
+  # makes this a meaningful positive fixture.
+  printf 'feature work\n' > "$d/FEATURE.txt"
+  git -C "$d" add FEATURE.txt
+  git -C "$d" commit -qm "work on forge/m-120 (will be squash-merged)"
+  git -C "$d" checkout -q main
+  # Unrelated main-side drift between fork and squash, with its OWN real file
+  # content — mirrors main advancing independently in between, exactly like
+  # m-53/PR#38 (main gained m-54's declaration in between). Would defeat a
+  # naive whole-tree-hash comparison, which this repo's own investigation
+  # found fails under exactly this kind of drift.
+  printf 'unrelated\n' > "$d/OTHER.txt"
+  git -C "$d" add OTHER.txt
+  git -C "$d" commit -qm "unrelated main-side work"
+  git -C "$d" merge -q --squash forge/m-120 >/dev/null 2>&1
+  git -C "$d" commit -q -m "squash merge forge/m-120 (#120)"
+  run_fold "$d" m-120
+  check "squash-merged: exit 0" "$RC" "0"
+  check "squash-merged: resolves merged (no false negative on ancestor-check failure)" "$OUT" "release_state=merged reason=no-signoff"
+fi
+
 # --- summary -------------------------------------------------------------------
 if [ -n "$FILTER" ] && [ "$SELECTED" -eq 0 ]; then
-  printf 'ERROR: filter "%s" matched no cases (tags: unmerged merged grandfather human-verified signoff-tag stored-field exit-2 stable-sha ordering promotion forgery labeled)\n' "$FILTER" >&2
+  printf 'ERROR: filter "%s" matched no cases (tags: unmerged merged grandfather human-verified signoff-tag stored-field exit-2 stable-sha ordering promotion forgery labeled squash)\n' "$FILTER" >&2
   exit 2
 fi
 

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env sh
+# Self-contained unit test for .claude/hooks/forge-size-gate.sh (issue #37).
+#
+# Proves the mechanical size gate: exactly one advisory line naming every
+# over-gate artifact (with size + gate), total silence when everything is
+# within gate, silent skip (no crash, no error) when a declared-gate artifact
+# is simply absent, and correct tiering of skill files (40KB for names listed
+# in skill-gate-tiers.txt, 20KB default for everything else).
+#
+# Builds throwaway git repos in mktemp dirs, NO remote configured. Isolated
+# from the developer's git config. Run:
+#   ./.claude/hooks/tests/forge-size-gate.test.sh
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GATE="$SCRIPT_DIR/../forge-size-gate.sh"
+
+[ -x "$GATE" ] || { printf 'FATAL: hook not executable: %s\n' "$GATE" >&2; exit 1; }
+command -v git >/dev/null 2>&1 || { printf 'FATAL: git not found\n' >&2; exit 1; }
+
+GIT_CONFIG_GLOBAL=/dev/null
+GIT_CONFIG_SYSTEM=/dev/null
+export GIT_CONFIG_GLOBAL GIT_CONFIG_SYSTEM
+unset FORGE_ALLOW_HOOK_EDITS 2>/dev/null || true
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+pass() { PASSED=$((PASSED + 1)); printf 'PASS: %s\n' "$1"; }
+fail() { FAILED=$((FAILED + 1)); printf 'FAIL: %s\n' "$1" >&2; }
+check() { if [ "$2" = "$3" ]; then pass "$1"; else fail "$1 (got '$2', want '$3')"; fi; }
+check_has() { case "$2" in *"$3"*) pass "$1" ;; *) fail "$1 (got '$2', want substring '$3')" ;; esac; }
+check_absent() { case "$2" in *"$3"*) fail "$1 (got '$2', must NOT contain '$3')" ;; *) pass "$1" ;; esac; }
+
+# pad_to <path> <bytes> — write <path> with exactly <bytes> bytes of filler.
+pad_to() {
+  path="$1"; n="$2"
+  mkdir -p "$(dirname "$path")"
+  awk -v n="$n" 'BEGIN { for (i = 0; i < n; i++) printf "a"; printf "\n" }' | head -c "$n" > "$path"
+}
+
+REPO="$ROOT/repo"
+mkdir -p "$REPO"
+git -C "$REPO" init -q
+git -C "$REPO" symbolic-ref HEAD refs/heads/main
+git -C "$REPO" config user.email t@example.com
+git -C "$REPO" config user.name tester
+
+mkdir -p "$REPO/.forge"
+mkdir -p "$REPO/.claude/hooks"
+printf 'forge\nchief-of-staff\n' > "$REPO/.claude/hooks/skill-gate-tiers.txt"
+
+git -C "$REPO" add -A
+git -C "$REPO" commit -qm "chore(forge): seed empty repo" --allow-empty >/dev/null 2>&1
+
+# ===========================================================================
+# Case A — an artifact over its gate is named in the ONE advisory line, with
+# correct size + gate numbers.
+# ===========================================================================
+pad_to "$REPO/.forge/FORGE.md" 35800   # over the 35KB (35000B) gate
+out_a="$("$GATE" --project "$REPO" 2>&1)"
+check_has "over-gate artifact named" "$out_a" ".forge/FORGE.md"
+check_has "over-gate artifact shows actual bytes" "$out_a" "35800B"
+check_has "over-gate artifact shows its gate" "$out_a" "35KB"
+check_has "advisory line points at FORGE.md Size Gates" "$out_a" "FORGE.md § Size Gates"
+# exactly one line of output
+lc_a="$(printf '%s\n' "$out_a" | grep -c .)"
+check "advisory is exactly one line" "$lc_a" "1"
+rm -f "$REPO/.forge/FORGE.md"
+
+# ===========================================================================
+# Case B — every checked artifact within gate → zero output.
+# ===========================================================================
+pad_to "$REPO/.forge/FORGE.md" 100
+pad_to "$REPO/.forge/project.yml" 100
+out_b="$("$GATE" --project "$REPO" 2>&1)"
+check "all within gate → no output" "$out_b" ""
+rc_b=$?
+"$GATE" --project "$REPO" >/dev/null 2>&1
+check "all within gate → exit 0" "$?" "0"
+
+# ===========================================================================
+# Case C — a declared-gate artifact simply absent → no crash, no error, and
+# it is never named (context.md was never created in this fixture repo).
+# ===========================================================================
+out_c="$("$GATE" --project "$REPO" 2>&1)"; rc_c=$?
+check "missing artifact → exit 0" "$rc_c" "0"
+check_absent "missing artifact never named" "$out_c" "context.md"
+
+# ===========================================================================
+# Case D — tiered skill gate: same-sized file, different tier outcome.
+#   - "forge" is in skill-gate-tiers.txt → 40KB tier → 35KB file is fine.
+#   - "some-other-skill" is NOT listed → 20KB default tier → 35KB file is over.
+# ===========================================================================
+pad_to "$REPO/.claude/skills/forge/SKILL.md" 35000
+pad_to "$REPO/.claude/skills/some-other-skill/SKILL.md" 35000
+out_d="$("$GATE" --project "$REPO" 2>&1)"
+check_absent "entry-point skill under its 40KB tier → no violation" "$out_d" "skills/forge/SKILL.md"
+check_has "non-entry-point skill over the 20KB default tier → violation" "$out_d" "skills/some-other-skill/SKILL.md"
+check_has "non-entry-point violation shows the 20KB gate" "$out_d" "20KB"
+rm -rf "$REPO/.claude/skills"
+
+# ===========================================================================
+# Case E — missing tier-list file degrades to "every skill at 20KB", never
+# a crash.
+# ===========================================================================
+rm -f "$REPO/.claude/hooks/skill-gate-tiers.txt"
+pad_to "$REPO/.claude/skills/forge/SKILL.md" 25000   # over 20KB, would be fine under the 40KB tier
+out_e="$("$GATE" --project "$REPO" 2>&1)"; rc_e=$?
+check "missing tier-list → exit 0 (no crash)" "$rc_e" "0"
+check_has "missing tier-list → default 20KB tier applied even to 'forge'" "$out_e" "skills/forge/SKILL.md"
+rm -rf "$REPO/.claude/skills"
+printf 'forge\nchief-of-staff\n' > "$REPO/.claude/hooks/skill-gate-tiers.txt"
+
+# ===========================================================================
+# Case F — non-Forge repo / non-repo dir: silent no-op, exit 0.
+# ===========================================================================
+mkdir -p "$ROOT/plain"
+"$GATE" --project "$ROOT/plain" >"$ROOT/out_f" 2>&1; rc_f=$?
+check "non-git dir → exit 0" "$rc_f" "0"
+check "non-git dir → no output" "$(cat "$ROOT/out_f")" ""
+
+mkdir -p "$ROOT/emptygit"
+git -C "$ROOT/emptygit" init -q
+"$GATE" --project "$ROOT/emptygit" >"$ROOT/out_f2" 2>&1; rc_f2=$?
+check "git repo without .forge → exit 0, silent" "$rc_f2" "0"
+check "git repo without .forge → no output" "$(cat "$ROOT/out_f2")" ""
+
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]

package/template/.claude/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.68.0",
+    "version": "0.80.1",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {
@@ -63,6 +63,10 @@
           {
             "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"
           }
         ]
       }