forge-orkes 0.77.0 → 0.80.0

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

package/template/.forge/templates/state/desire-path.yml

@@ -7,6 +7,9 @@ type: ""                              # recurring_friction | agent_struggle | us
 date: ""                              # ISO 8601 date the observation was made, e.g. "2026-07-23"
 milestone: ""                         # milestone id, or a short label for non-milestone work (e.g. "quick-task (...)")
 scope: project                        # project | framework — absent ⇒ project (this repo only; framework ⇒ upstream-eligible per ADR-012)
+# resolves_issue: 26                 # OPTIONAL — GitHub issue number this observation's fix resolves. The
+#                                    # close-the-loop check (reviewing) keys off it to surface the issue as
+#                                    # likely-closable once the fix ships. Omit when the observation resolves no issue.
 suggestion_target: ""                 # the file/skill this observation would change if acted on
 note: >
   What was observed — concrete enough that a future review can judge recurrence

package/experimental/m10/source/hooks/forge-branch-guard.sh

@@ -1,61 +0,0 @@
-#!/usr/bin/env bash
-# Forge PreToolUse(Bash) guardrail — protect the shared main checkout's HEAD when
-# parallel git worktrees are active.
-#
-# Blocks the "moved the shared HEAD under other sessions" catastrophe (canvaz, burned
-# twice 2026-06-05): switching branches or hard-resetting in the MAIN checkout while
-# sibling worktrees are branched off it. Orchestration-agnostic — depends only on git
-# worktree state, so it holds whether coordination is M10, Agent Teams, or manual
-# worktrees.
-#
-# Scope is deliberately narrow to avoid false positives:
-#   - fires ONLY when >1 worktree exists (single-worktree/solo work is never touched)
-#   - fires ONLY in the main checkout (linked worktrees own their own HEAD)
-#   - skips any command containing `cd` (can't reliably tell which tree it targets)
-#   - allows safe forms: file restore (`git checkout -- <path>`), branch create (`-b`)
-#
-# exit 0 = allow; exit 2 = deny. Override by running the command yourself outside Claude.
-
-set -uo pipefail
-
-PAYLOAD=$(cat)
-CMD=$(printf '%s' "$PAYLOAD" | jq -r '.tool_input.command // empty' 2>/dev/null) || exit 0
-[ -z "$CMD" ] && exit 0
-
-# Only git commands are interesting; and bail on `cd` (target tree is ambiguous).
-case "$CMD" in
-  *git*) ;;
-  *) exit 0 ;;
-esac
-case "$CMD" in
-  *"cd "*) exit 0 ;;
-esac
-
-git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
-
-# Single worktree → no shared-HEAD hazard.
-wt_count=$(git worktree list 2>/dev/null | wc -l | tr -d ' ')
-[ "${wt_count:-1}" -le 1 ] && exit 0
-
-# Main checkout iff --git-dir == --git-common-dir (linked worktrees differ).
-[ "$(git rev-parse --git-dir 2>/dev/null)" = "$(git rev-parse --git-common-dir 2>/dev/null)" ] || exit 0
-
-deny() { echo "[forge-branch-guard] $*" >&2; exit 2; }
-
-# Branch switch (checkout/switch to a ref), excluding file-restore (`--`) and create (`-b`).
-switches_branch=0
-if printf '%s' "$CMD" | grep -qE '\bgit[[:space:]]+(checkout|switch)\b'; then
-  if ! printf '%s' "$CMD" | grep -qE '([[:space:]]--([[:space:]]|$))|(\bgit[[:space:]]+(checkout|switch)[[:space:]]+-[bB]\b)'; then
-    switches_branch=1
-  fi
-fi
-
-# Hard/keep/merge reset rewrites HEAD + working tree.
-hard_reset=0
-printf '%s' "$CMD" | grep -qE '\bgit[[:space:]]+reset[[:space:]]+(--hard|--keep|--merge)\b' && hard_reset=1
-
-if [ "$switches_branch" = "1" ] || [ "$hard_reset" = "1" ]; then
-  deny "Refusing to move the shared main HEAD — $wt_count worktrees are branched off it (the 'burned twice' failure). Switch/reset inside a worktree, or stop the other sessions first. Override: run the command yourself outside Claude."
-fi
-
-exit 0