forge-orkes 0.74.0 → 0.77.0

package/template/.forge/migrations/0.77.0-state-rollup-executable.md

@@ -0,0 +1,120 @@
+# Migration Guide: State rollup made mechanical (Forge 0.77.0)
+
+Applies to projects upgrading to 0.77.0 or later. State Rollup 1.0 and the
+Stream Rollup (ADR-015 addendum) — previously advisory skill prose that an
+agent had to remember to run at boot — are now an executable,
+`.claude/hooks/forge-state-rollup.sh`, invoked mechanically by a `SessionStart`
+hook. A boot session can no longer skip the render and fall back to reading a
+stale `.forge/state/index.yml` / `.forge/streams/active.yml` cache, or
+hand-reconstruct the registries from memory — the exact failure mode filed as
+issue #22.
+
+`/upgrading` ships the new hook file (`.claude/hooks/forge-state-rollup.sh`)
+like any other framework file. It does **not** wire the `SessionStart`
+registration, because `.claude/settings.json` is a **user-owned file** —
+upgrades never overwrite it (FORGE.md → State Ownership, "Stable shared"
+class notes settings.json is gitignored-carve-out territory, 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.77.0+ (or already carry the
+`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-state-rollup.sh` and
+   `.claude/hooks/forge-release-fold.sh` are present and executable.
+2. Working tree clean or changes committed — this migration edits
+   `.claude/settings.json`, a tracked file.
+
+## Detection
+
+Keyed on **the executable existing (or the version already at/above 0.77.0)
+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-state-rollup`; 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-state-rollup.sh ] || exit 0
+
+settings=".claude/settings.json"
+[ -f "$settings" ] || {
+  echo "MIGRATE — forge-state-rollup.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-state-rollup"))]
+    | length > 0
+  ' "$settings" 2>/dev/null)"
+  if [ "$wired" != "true" ]; then
+    echo "MIGRATE — $settings has no SessionStart hook referencing forge-state-rollup.sh; the executable shipped but nothing mechanically triggers it"
+  fi
+else
+  if ! grep -q "forge-state-rollup" "$settings" 2>/dev/null; then
+    echo "MIGRATE — $settings has no reference to forge-state-rollup.sh (jq unavailable, ran plain-text check); add the SessionStart hook below"
+  fi
+fi
+```
+
+## Migration steps
+
+### 1. Add the SessionStart hook block
+
+Open `.claude/settings.json` and add (or merge into) a `hooks.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"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If `hooks.SessionStart` already has other entries (e.g. from a project-local
+customization), append this object to the existing array rather than
+replacing it. If `hooks` exists but has no `SessionStart` key yet, add the key
+alongside the existing `PreToolUse`/`PostToolUse` blocks.
+
+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-state-rollup.sh` itself also
+always exits 0).
+
+### 2. Commit the settings change
+
+```bash
+git add .claude/settings.json
+git commit -m "chore(forge): wire forge-state-rollup SessionStart hook (0.77.0)"
+```
+
+## Validation
+
+- Start a new session, or run `/clear` — the boot summary line should include
+  `[forge-state-rollup] rendered index.yml (…) …` (plus an `active.yml` clause
+  if `.forge/streams/` exists), confirming the hook actually ran.
+- `jq '.hooks.SessionStart' .claude/settings.json` prints a non-null array
+  containing the `forge-state-rollup` command, not `null`.
+- Re-running the Detection block above now prints nothing (exits silently) —
+  the gap is closed.
+- `.forge/state/index.yml` and `.forge/streams/active.yml` (if applicable)
+  exist on disk and are fresh — their mtimes update on every boot, since the
+  hook re-renders unconditionally.

package/template/.forge/templates/project.yml

@@ -99,6 +99,20 @@ verification:
 #                                    # only — the private key lives host-side, in the deploy Environment).
 #                                    # Empty ⇒ git config gpg.ssh.allowedSignersFile.
 
+# orchestration:                     # OPTIONAL — worktree behavior (M10 / streams). Absent → defaults.
+#   worktree_root: ""                # Where Forge worktrees live. Default ../<repo-basename>-worktrees.
+#                                    #   Relative → resolves against repo root; absolute / ~ honored verbatim.
+#   worktree_hydrate: []             # OPTIONAL list of superproject-relative paths — required-but-gitignored
+#                                    #   artifacts copied into a fresh worktree so it can build and reach its
+#                                    #   tools (a clean worktree checks out TRACKED files only). Guarded
+#                                    #   source-exists && dest-absent: never overwrites, never git-adds, so a
+#                                    #   secret-bearing file stays gitignored/untracked in both trees and never
+#                                    #   enters git history (.mcp.json the canonical case). Applied by
+#                                    #   orchestrating at creation AND asserted in executing's Workspace
+#                                    #   Prerequisites → worktrees of ANY origin covered. Omit → no propagation.
+#                                    #   e.g. [".mcp.json", ".env.local"]. Dependency install stays with the
+#                                    #   executing/verifying preflight, not this key.
+
 success_criteria:                   # How do we know we're done?
   - ""                              # e.g., "User can create and edit posts"
   - ""                              # e.g., "All tests pass with >80% coverage"