forge-orkes 0.75.0 → 0.79.0

package/bin/create-forge.js

@@ -124,6 +124,24 @@ function makeHookScriptsExecutable(hooksDir) {
   try { walk(hooksDir); } catch { /* best-effort */ }
 }
 
+/**
+ * Make the tracked git hooks under .forge/git-hooks/ executable (issue #21 / ADR-031).
+ * These are git hooks (pre-commit, …) with NO .sh extension, so makeHookScriptsExecutable
+ * (which only chmods *.sh) misses them — chmod them explicitly. Best-effort; never throws.
+ * NOTE: this function deliberately does NO `git config core.hooksPath` — per-clone wiring
+ * (with the Husky/lefthook conflict warning) is owned by the initializing/upgrading skills,
+ * not the installer, which stays git-config-free and runs unattended in CI.
+ */
+function makeGitHooksExecutable(forgeDir) {
+  const gitHooksDir = path.join(forgeDir, 'git-hooks');
+  if (!fs.existsSync(gitHooksDir)) return;
+  for (const entry of fs.readdirSync(gitHooksDir, { withFileTypes: true })) {
+    if (entry.isFile() && !entry.name.startsWith('.')) {
+      try { fs.chmodSync(path.join(gitHooksDir, entry.name), 0o755); } catch { /* best-effort */ }
+    }
+  }
+}
+
 /**
  * Additively sync a framework-managed `.claude/` dir into an existing project on
  * upgrade (ADR-017/018). Copies/updates the template's files, but NEVER deletes
@@ -498,6 +516,7 @@ async function install() {
   const srcForge = path.join(templateDir, '.forge');
   const destForge = path.join(targetDir, '.forge');
   const forgeCount = copyDirRecursive(srcForge, destForge);
+  makeGitHooksExecutable(destForge); // extensionless git hooks (.forge/git-hooks/pre-commit)
   console.log(`  Installed .forge/templates/ (${forgeCount} files)`);
 
   // npm strips files literally named `.gitignore` from the published tarball, so
@@ -858,6 +877,14 @@ async function upgrade() {
   //    protected set (.forge/checks/**) can guard them. Additive for the same
   //    reason as above: never delete a project-local extra check.
   upgradeAdditiveDir('.forge/checks', results);
+  // 2-git-hooks. Sync the tracked git hooks (issue #21 / ADR-031: the primary-checkout
+  //    weld pre-commit backstop). Tracked at .forge/git-hooks/ for the same reason as
+  //    .forge/checks/ — .claude/hooks/ is commonly gitignored, and a git hook must be
+  //    tracked to run for humans/CI. Additive; then chmod the extensionless hooks
+  //    (upgradeAdditiveDir only +x's *.sh). Per-clone core.hooksPath wiring is the
+  //    initializing/upgrading skills' job, NOT the installer's — see makeGitHooksExecutable.
+  upgradeAdditiveDir('.forge/git-hooks', results);
+  makeGitHooksExecutable(path.join(targetDir, '.forge'));
 
   // 2a. Confirm stale framework-file removals before deleting (R066a). Defaults
   //     to yes (cleanup is the normal case); auto-confirms when non-interactive

package/experimental/m10/README.md

@@ -55,7 +55,7 @@ Idempotent — re-running emits warnings instead of errors.
 If you'd rather see exactly what changes:
 
 1. Copy `source/mcp-server/` → `<target>/.forge/.mcp-server/`
-2. Copy `source/hooks/forge-claim-check.sh`, `source/hooks/forge-claim-check-doctor.sh`, `source/hooks/forge-session-id.sh`, and `source/hooks/forge-branch-guard.sh` → `<target>/.claude/hooks/` (`chmod +x`)
+2. Copy `source/hooks/forge-claim-check.sh`, `source/hooks/forge-claim-check-doctor.sh`, `source/hooks/forge-session-id.sh`, and `source/hooks/protect-primary-checkout.sh` → `<target>/.claude/hooks/` (`chmod +x`)
 3. Copy `source/skills/orchestrating/` → `<target>/.claude/skills/orchestrating/`
 4. Merge `forge-orchestrator` entry into `<target>/.mcp.json`:
    ```json
@@ -71,12 +71,12 @@ If you'd rather see exactly what changes:
      { "hooks": [{ "type": "command", "command": ".claude/hooks/forge-session-id.sh" }] }
    ]
    ```
-   Also add the branch-discipline guardrail under `PreToolUse`:
+   Also add the primary-checkout guardrail under `PreToolUse`:
    ```json
    { "matcher": "Bash",
-     "hooks": [{ "type": "command", "command": ".claude/hooks/forge-branch-guard.sh" }] }
+     "hooks": [{ "type": "command", "command": ".claude/hooks/protect-primary-checkout.sh" }] }
    ```
-   The SessionStart hook captures the Claude session id (claim identity); without it the enforcement gate fail-opens (ADR-007). The branch-guard protects the shared main HEAD when worktrees are active (ADR-008) — orchestration-agnostic, independent of the claim layer.
+   The SessionStart hook captures the Claude session id (claim identity); without it the enforcement gate fail-opens (ADR-007). The primary-checkout guard welds the primary checkout to the default branch — all branch work happens in worktrees (issue #21, ADR-031) — orchestration-agnostic, independent of the claim layer. It supersedes the old forge-branch-guard.sh (ADR-008) and folds in its hard-reset protection.
 6. `cd <target>/.forge/.mcp-server && npm install`
 
 ## Verify

package/experimental/m10/install.sh

@@ -72,7 +72,7 @@ echo
 # Step 3: copy hooks
 echo "==> Hooks → .claude/hooks/"
 do_or_say "mkdir -p '$TARGET/.claude/hooks'"
-for h in forge-claim-check.sh forge-claim-check-doctor.sh forge-session-id.sh forge-branch-guard.sh; do
+for h in forge-claim-check.sh forge-claim-check-doctor.sh forge-session-id.sh protect-primary-checkout.sh; do
   if [[ -f "$TARGET/.claude/hooks/$h" ]]; then
     say "skip: $h already exists"
   else
@@ -161,21 +161,22 @@ else
 fi
 echo
 
-# Step 6c: register branch-discipline guardrail (PreToolUse on Bash). Orchestration-
-# agnostic — protects the shared main HEAD whenever >1 worktree exists.
-echo "==> .claude/settings.json branch-guard hook"
-BG_CMD='.claude/hooks/forge-branch-guard.sh'
+# Step 6c: register the primary-checkout branch weld (PreToolUse on Bash). Welds the
+# primary checkout to the default branch — all branch work happens in worktrees (issue
+# #21). Orchestration-agnostic; supersedes the old forge-branch-guard.sh.
+echo "==> .claude/settings.json primary-checkout guard hook"
+BG_CMD='.claude/hooks/protect-primary-checkout.sh'
 if [[ ! -f "$SETTINGS" ]]; then
-  say "[dry-run] settings.json not yet created — branch-guard would be added alongside the others"
+  say "[dry-run] settings.json not yet created — primary-checkout guard would be added alongside the others"
 elif jq -e --arg cmd "$BG_CMD" '.hooks.PreToolUse[]?.hooks[]? | select(.command == $cmd)' "$SETTINGS" >/dev/null 2>&1; then
-  say "skip: forge-branch-guard.sh hook already registered"
+  say "skip: protect-primary-checkout.sh hook already registered"
 else
   if [[ $DRY_RUN -eq 0 ]]; then
     tmp=$(mktemp)
-    jq '.hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":".claude/hooks/forge-branch-guard.sh"}]}]' "$SETTINGS" > "$tmp"
+    jq '.hooks.PreToolUse += [{"matcher":"Bash","hooks":[{"type":"command","command":".claude/hooks/protect-primary-checkout.sh"}]}]' "$SETTINGS" > "$tmp"
     mv "$tmp" "$SETTINGS"
   fi
-  say "appended branch-guard PreToolUse(Bash) hook entry"
+  say "appended primary-checkout guard PreToolUse(Bash) hook entry"
 fi
 echo
 

package/experimental/m10/source/hooks/protect-primary-checkout.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Weld the primary checkout to the default branch — deny branch create/switch there.
+#
+# PreToolUse(Bash) hook. Exit 2 (+ JSON permissionDecision:deny) = block. Exit 0 = allow.
+#
+# WHY: the primary checkout's HEAD is shared mutable state across every concurrent
+# Claude session running in that directory. One session running `git checkout -b`
+# silently redirects every OTHER session's subsequent commits onto its branch — an
+# invisible clobber that surfaces later as wrong-branch commits, contaminated PRs,
+# stranded milestone state, or dropped history (issue #21: 3 confirmed incidents —
+# m85's 12-commit drop, m62's stranded phase commits, a Quick-tier checkout -b that
+# contaminated a concurrent PR). Branch work belongs in worktrees, which each own
+# their own HEAD.
+#
+# Scope: fires ONLY in the primary checkout (git-dir == git-common-dir). Linked
+# worktrees are unaffected (their git-dir differs). Unlike the dormant
+# forge-branch-guard.sh this supersedes, the branch weld is UNCONDITIONAL — it fires
+# even when no sibling worktree exists yet, because the second session's worktree is
+# typically created AFTER the offending `checkout -b`. This hook also folds in the
+# one distinct protection the old guard provided: denying a hard-reset in the primary
+# checkout while sibling worktrees are branched off it (the history-rewrite class).
+#
+# Default branch is resolved dynamically (main/master + init.defaultBranch), never
+# hardcoded — Forge ships to repos on any default branch.
+#
+# Fails OPEN (exit 0 / allow) on any malfunction (no jq, empty command, non-git cwd,
+# git probe error) — a guard must never wedge the agent on its own failure.
+#
+# Escape hatch (deliberate, human use): ALLOW_MAIN_BRANCHING=1
+
+set -uo pipefail
+
+emit_deny() {
+  local reason="${1//\"/\\\"}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$reason"
+  exit 2
+}
+
+[ "${ALLOW_MAIN_BRANCHING:-0}" = "1" ] && exit 0
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+[ -z "$COMMAND" ] && exit 0
+
+# Normalize the cheapest whitespace-substitution evasion (`git checkout$IFS-b`) to a
+# real space before matching. A string matcher on an un-expanded shell command can
+# never be complete against expansion — the pre-commit backstop is the sound layer —
+# but closing the trivial $IFS trick keeps the PreToolUse layer honest.
+COMMAND=$(printf '%s' "$COMMAND" | sed -E 's/\$\{?IFS\}?/ /g')
+
+# Git allows global options BEFORE the subcommand: `git -c k=v checkout`,
+# `git --no-pager switch`, `git -C <path> -p checkout`, etc. The guard must tolerate
+# ANY run of them, not just a single `-C <path>` — otherwise `git -c x=y checkout -b`
+# sails past (issue #21 regression). GITPRE matches `git` + zero-or-more global options
+# (a `-x`/`--long`/`--long=val`/`-C <path>`/`-c <kv>` token, each optionally taking the
+# next word as its value) up to the subcommand.
+GITPRE='git[[:space:]]+((-[A-Za-z]|--[A-Za-z-]+)(=[^[:space:]]+)?[[:space:]]+([^-][^[:space:]]*[[:space:]]+)?)*'
+
+# Fast path: only inspect commands that touch checkout/switch/reset at all. Anything
+# else exits immediately WITHOUT any git probe (keeps the hook cheap on every Bash call).
+printf '%s' "$COMMAND" | grep -qE "${GITPRE}(checkout|switch|reset)([[:space:]]|\$)" || exit 0
+
+# Resolve which repo dir the command targets: honor `git -C <path>`, else the hook cwd.
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+[ -z "$CWD" ] && CWD=$(pwd)
+# Honor a GLOBAL `git -C <path>` (before the subcommand) only. Isolate the pre-subcommand
+# segment first so `switch -C`/`checkout -C` (create-force, AFTER the subcommand) is never
+# mistaken for a target-dir option.
+PRE=$(printf '%s' "$COMMAND" | sed -E 's/[[:space:]](checkout|switch|reset)[[:space:]].*$//')
+GC_PATH=$(printf '%s' "$PRE" | grep -oE '(^|[[:space:]])-C[[:space:]]+[^[:space:]]+' | head -1 | awk '{print $2}' || true)
+# A flag-shaped -C value (e.g. `-C --foo`) is not a real target dir → ignore it.
+case "$GC_PATH" in -*) GC_PATH="" ;; esac
+TARGET_DIR="${GC_PATH:-$CWD}"
+
+GIT_DIR=$(git -C "$TARGET_DIR" rev-parse --git-dir 2>/dev/null) || exit 0
+COMMON_DIR=$(git -C "$TARGET_DIR" rev-parse --git-common-dir 2>/dev/null) || exit 0
+GIT_DIR_ABS=$(cd "$TARGET_DIR" 2>/dev/null && cd "$GIT_DIR" 2>/dev/null && pwd) || exit 0
+COMMON_DIR_ABS=$(cd "$TARGET_DIR" 2>/dev/null && cd "$COMMON_DIR" 2>/dev/null && pwd) || exit 0
+
+# In a linked worktree git-dir != git-common-dir → branch ops are fine there.
+[ "$GIT_DIR_ABS" != "$COMMON_DIR_ABS" ] && exit 0
+
+# ── Default-branch set (dynamic — mirrors block-dangerous-commands.sh) ───────────
+# Seed main+master, add the configured init.defaultBranch. A switch/checkout TO any
+# of these names is "returning home" and always allowed.
+DEFAULT_BRANCHES="main master"
+GIT_DEFAULT=$(git -C "$TARGET_DIR" config --get init.defaultBranch 2>/dev/null || true)
+[ -n "$GIT_DEFAULT" ] && DEFAULT_BRANCHES="$DEFAULT_BRANCHES $GIT_DEFAULT"
+is_default_branch() {
+  for b in $DEFAULT_BRANCHES; do [ "$1" = "$b" ] && return 0; done
+  return 1
+}
+
+DENY_MSG="Blocked: the primary checkout's HEAD stays on the default branch — branch create/switch here silently redirects every other concurrent session's commits onto your branch (recurring clobber, issue #21). Do branch work in a worktree: bash .forge/bin/new-worktree.sh <slug> (or git worktree add). To operate on an existing worktree from here, use git -C <worktree-path>. Human escape hatch: ALLOW_MAIN_BRANCHING=1."
+
+# ── 1) Branch creation / orphan / detach / track: always deny in primary checkout ──
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}checkout[[:space:]]+((-[a-zA-Z]*[bB][a-zA-Z]*|--orphan|--detach|--track)([[:space:]=]|\$))"; then
+  emit_deny "$DENY_MSG"
+fi
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}switch[[:space:]]+((-[cC]|--create|--force-create|--orphan|--detach|--track)([[:space:]=]|\$))"; then
+  emit_deny "$DENY_MSG"
+fi
+
+# ── 2) hard/keep/merge reset in the primary checkout while worktrees are branched ──
+# Folded from the superseded forge-branch-guard.sh: a reset that rewrites HEAD +
+# working tree here can drop verified work committed under sibling worktrees. Gated
+# on >1 worktree (unlike the branch weld, which is unconditional).
+if printf '%s' "$COMMAND" | grep -qE "${GITPRE}reset[[:space:]]+(--hard|--keep|--merge)([[:space:]]|\$)"; then
+  wt_count=$(git -C "$TARGET_DIR" worktree list 2>/dev/null | wc -l | tr -d ' ')
+  if [ "${wt_count:-1}" -gt 1 ]; then
+    emit_deny "Refusing to move the shared primary HEAD via reset — $wt_count worktrees are branched off it (the 'burned twice' history-rewrite failure, issue #21). Reset inside a worktree, or stop the other sessions first. Human escape hatch: ALLOW_MAIN_BRANCHING=1."
+  fi
+  exit 0   # single-worktree hard-reset is the operator's own business — allow.
+fi
+
+# ── 3) checkout/switch to a ref other than the default branch ───────────────────
+# Only checkout/switch move HEAD to a ref. A reset that reached this far (--soft /
+# --mixed, or a hard/keep/merge reset in a single-worktree repo) is not a branch move
+# off the default → allow it and stop.
+printf '%s' "$COMMAND" | grep -qE "${GITPRE}(checkout|switch)([[:space:]]|\$)" || exit 0
+
+# `git checkout <ref> -- <paths>` and `git checkout -- <paths>` never move HEAD →
+# allow anything containing a ` -- ` pathspec separator.
+printf '%s' "$COMMAND" | grep -qE '[[:space:]]--([[:space:]]|$)' && exit 0
+
+# Extract the first non-flag argument after checkout/switch. Strip everything up to and
+# including the subcommand keyword — whatever git global options preceded it (`-c`,
+# `--no-pager`, `-C <path>`, …) are consumed by the greedy prefix. The trailing separator
+# is optional so a BARE `git checkout` (no target) yields empty ARGS → allowed below.
+ARGS=$(printf '%s' "$COMMAND" | sed -E 's/.*[[:space:]](checkout|switch)([[:space:]]+|$)/ /' | head -1)
+FIRST_REF=""
+for word in $ARGS; do
+  case "$word" in
+    -*) continue ;;                     # flags (creation flags already denied above)
+    \;|\&\&|\|\||\||\&) break ;;        # end of this git command
+    *) FIRST_REF="$word"; break ;;
+  esac
+done
+
+# Bare `git checkout`/`git switch` (no target) is a no-op/error → allow.
+[ -z "$FIRST_REF" ] && exit 0
+
+# Returning home (default branch) or file-restore forms → allow. Any other ref → deny.
+case "$FIRST_REF" in
+  HEAD|.) exit 0 ;;                      # file restore forms
+  *) is_default_branch "$FIRST_REF" && exit 0 || emit_deny "$DENY_MSG" ;;
+esac

package/package.json

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

@@ -113,3 +113,124 @@ primary coordination point.
 - "internal error at line N" on every edit → corrupt DB or missing tool. Run doctor. Common: `jq` not on PATH.
 - No collisions detected → confirm `CLAUDE_SESSION_ID` set and `claims.db` exists; otherwise hook fail-opens.
 - macOS `timeout: command not found` → `brew install coreutils` for `gtimeout`, or skip (DB busy_timeout still applies).
+
+## `forge-state-rollup.sh` — SessionStart state rollup
+
+Makes the boot rollup mechanical (issue #22). Ports **State Rollup 1.0** and the
+**Stream Rollup** (ADR-015 addendum) from advisory skill prose into an
+executable that a SessionStart hook runs on every boot, so a session can no
+longer skip the render and work from a stale cache or hand-reconstruct the
+registries — the failure mode filed against #22.
+
+### Behavior
+
+Renders two git-ignored render-on-read caches (0.53.0) and never commits
+either:
+
+| Renders | From | Notes |
+|---|---|---|
+| `.forge/state/index.yml` | `.forge/state/milestone-*.yml` | Derived registry status (`deferred`/`complete`/`not_started`/`active`); `last_updated` falls back to legacy `progress.last_update`; per-row `release_state` is fetched by shelling to `forge-release-fold.sh` — the fold is the **only** source, never re-derived here |
+| `.forge/streams/active.yml` | `.forge/streams/*.yml` + active milestones | Stream Rollup join: per-stream coordination rows, milestone-derived `phase`, `implicit` coverage rows for active milestones with no stream file, derived `merge_queue` (only rendered if `.forge/streams/` exists) |
+
+A **step-0 completed-stream auto-close sweep** runs before the stream join and
+edits committed stream files (`streams/{stream}.yml`) — a milestone-backed
+stream whose milestone is `complete`, not already `closed`, with no live
+worktree gets auto-closed. This step is **main-checkout only**
+(`git rev-parse --git-dir` == `--git-common-dir`); a linked worktree skips the
+sweep but still renders both caches locally.
+
+Deterministic and idempotent — two runs against the same sources produce
+byte-identical output.
+
+**Fold dependency and degrade.** `release_state` comes exclusively from
+`.claude/hooks/forge-release-fold.sh`. If the fold script is missing or exits
+non-zero for a unit, that row gets `release_state: unknown` plus one advisory
+stderr line (`forge-state-rollup: release fold unavailable for m-N —
+release_state: unknown`) — a broken fold degrades a single row, it never
+breaks boot.
+
+**Non-blocking contract.** Exit `0` **always** — SessionStart hooks are
+non-blocking, so every failure path (not a git repo, no `.forge/`, no
+`.forge/state/`) degrades to a silent no-op rather than surfacing an error.
+stdout carries one terse summary line (unless `--quiet`) that is injected into
+the model's context — e.g. `[forge-state-rollup] rendered index.yml (3
+milestones) + active.yml (2 stream rows). Registries are fresh — READ them,
+do not regenerate by hand.` stderr carries advisories (auto-close, fold
+degrade) and is visible in the transcript but not injected into context.
+
+### Why `cwd`, not `$CLAUDE_PROJECT_DIR`
+
+`$CLAUDE_PROJECT_DIR` resolves to the repo **root** (main checkout) even when
+the session started inside a linked worktree. Rendering against it from a
+worktree session would write the caches into the wrong tree. The hook instead
+resolves the target repo from the SessionStart payload's `cwd` (read from
+stdin JSON), falling back to `$PWD` if `--project` isn't passed and stdin/`jq`
+aren't available. Each worktree therefore renders **its own** gitignored
+caches; a worktree's boot never touches main's.
+
+### Prerequisites
+
+- POSIX `sh` + `git` + `awk`/`sed` (mirrors `forge-release-fold.sh`) — no other
+  runtime dependency.
+- `jq` — used only to parse the SessionStart stdin JSON (`cwd`). Absent `jq`
+  degrades to a no-stdin path (falls back to `--project` or `$PWD`); it does
+  not disable the hook.
+- No network calls.
+
+### CLI usage
+
+```bash
+.claude/hooks/forge-state-rollup.sh [--project <path>] [--quiet]
+```
+
+- `--project <path>` — operate on the repo containing `<path>` instead of the
+  SessionStart payload's `cwd`. Useful for manually re-rendering a specific
+  worktree or repo outside a session.
+- `--quiet` — suppress the stdout summary line; caches are still written.
+
+Run it manually any time the caches look stale — it is safe to re-run and
+always produces the same output for the same sources.
+
+### Registration
+
+Wired as a `SessionStart` hook in `.claude/settings.json` (and the
+`create-forge` template copy), matcher `startup|resume|clear`:
+
+```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"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The `[ -x ... ] && ... || true` guard means a repo without the hook file (or
+with it non-executable) boots exactly as before — the hook is additive, not a
+new hard dependency.
+
+### Disabling
+
+Remove the `SessionStart` block above from `.claude/settings.json`, or make
+the script non-executable: `chmod -x .claude/hooks/forge-state-rollup.sh`.
+Without it, boot falls back to the advisory skill-prose rollup (`forge` /
+`chief-of-staff` render-then-read) — correct but no longer mechanically
+enforced.
+
+### Tests
+
+`.claude/hooks/tests/forge-state-rollup.test.sh` — a standalone git-fixture
+suite (36 cases) run directly (not through `tests/run.sh`), building throwaway
+repos in `mktemp` dirs. Covers the #22 acceptance shape (a stale cache is
+regenerated regardless), fold-degrade → `release_state: unknown`, the
+main-only auto-close sweep, the linked-worktree guard (sweep skipped, caches
+still rendered), and the SessionStart stdin path. See `tests/README.md`.