forge-orkes 0.58.2 → 0.58.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.58.2",
+  "version": "0.58.3",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.58.2",
+    "version": "0.58.3",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {

package/template/.forge/migrations/0.53.0-render-on-read-registries.md

@@ -0,0 +1,103 @@
+# Migration Guide: Render-on-read state registries (Forge 0.53.0)
+
+Applies to projects whose derived registries — `.forge/state/index.yml` and/or
+`.forge/streams/active.yml` — are still **git-tracked**. Both files were already
+`DERIVED / DO NOT HAND-EDIT` projections; 0.53.0 makes them **git-ignored
+render-on-read caches**: regenerated at every `forge` boot from their sources and
+**never committed**. Because the value is computed on read and never stored in
+git, the two-registry drift class — a committed projection going stale against
+its source (e.g. a committed `active.yml` phase reading `researching` while the
+milestone had moved to `discussing`) — can no longer occur.
+
+Sources are unchanged: `index.yml` ← `.forge/state/milestone-*.yml` (Rollup 1.0);
+`active.yml` ← `.forge/streams/*.yml` + active milestones (Stream Rollup). Only
+the *storage* changes — tracked file → local cache.
+
+Projects that never committed these files (fresh 0.53.0+ installs) need nothing.
+
+## Prerequisites
+
+1. On the new version's framework files (`npx forge-orkes upgrade`, or the
+   `upgrading` skill) — so the updated `.gitignore` entries and the render-then-read
+   `deferred`/`planning` skills are present.
+2. Working tree clean or changes committed — the migration stops tracking two
+   files and edits `.gitignore`.
+
+## Detection
+
+Keyed on **git-tracking state**, not a content grep: the `DERIVED / DO NOT
+HAND-EDIT` header is identical before and after, so only `git ls-files` can tell
+a committed-pre-0.53.0 registry from a git-ignored-post-0.53.0 one. Fires while
+either registry is still tracked; silent once both are untracked (already
+migrated), and silent in a non-Forge / non-git tree:
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+migrate=0
+for f in .forge/state/index.yml .forge/streams/active.yml; do
+  if git ls-files --error-unmatch "$f" >/dev/null 2>&1; then
+    echo "MIGRATE — $f is still git-tracked (pre-0.53.0); render-on-read makes it a git-ignored cache regenerated at boot"
+    migrate=1
+  fi
+done
+[ "$migrate" -eq 0 ] && exit 0
+```
+
+## Migration steps
+
+### 1. Stop tracking the two registries (keep them on disk)
+
+```bash
+git rm --cached .forge/state/index.yml .forge/streams/active.yml 2>/dev/null
+```
+
+`--cached` removes them from the index only — the working-copy files stay as a
+local cache and are re-rendered on the next boot. (If either was never tracked,
+the command is a harmless no-op for that path.)
+
+### 2. Git-ignore both derived registries
+
+Add to the project's root `.gitignore` (paths relative to the repo root):
+
+```
+.forge/state/index.yml
+.forge/streams/active.yml
+```
+
+Consumer projects created from `create-forge` instead gain these under
+`.forge/.gitignore` (paths relative to `.forge/`):
+
+```
+state/index.yml
+streams/active.yml
+```
+
+Without this, the next `git add .forge/` would re-commit the caches and reopen
+the drift class.
+
+### 3. Confirm the readers render-then-read
+
+`forge` boot and `chief-of-staff` already render before reading. In 0.53.0 the
+two direct readers are converted too: `deferred` and `planning` no longer treat a
+missing `index.yml` as "not a Forge project" — the project sentinel moved to the
+committed `.forge/project.yml`, and they derive milestone state from
+`.forge/state/milestone-*.yml` (rendering the cache first) when `index.yml` is
+absent. These ship with the framework upgrade; no per-project edit is needed.
+
+### 4. Regenerate the caches
+
+Run `/forge` (boot) — it runs Rollup 1.0 and the Stream Rollup and rewrites both
+files from their sources. From here they are regenerated on read, never committed.
+
+## Validation
+
+- `git ls-files --error-unmatch .forge/state/index.yml` exits **non-zero**
+  (untracked); same for `.forge/streams/active.yml`.
+- `git check-ignore .forge/state/index.yml` and `git check-ignore
+  .forge/streams/active.yml` each exit **0** (ignored).
+- Both files still exist on disk after a `/forge` boot (rendered cache).
+- A fresh clone with no prior boot: `deferred` and `planning` do **not** print
+  "No forge state found" (they key the sentinel on `project.yml`).
+- Editing a milestone's phase and booting yields an `active.yml` whose row phase
+  matches the milestone — the projection can no longer be stale, because it is
+  never stored.

package/template/.forge/migrations/0.58.3-render-on-read-registries-catchup.md

@@ -0,0 +1,42 @@
+# Migration Guide: Render-on-read registries catch-up (Forge 0.58.3)
+
+Applies to projects that upgraded **across 0.53.0 while the 0.53.0 migration
+guide was missing from the shipped template** (missing 0.53.0–0.58.2; restored
+in 0.58.3). For those projects, `/upgrading` Step 7's version-range detection
+(`installed < v <= source`) fired for the crossed range but had no
+`0.53.0-*.md` guide on disk to surface — so the render-on-read registry
+migration (untrack `.forge/state/index.yml` + `.forge/streams/active.yml`) was
+silently skipped, and range detection never looks backward at an
+already-crossed version. Host-verified on ptnrkit: stamped 0.58.2 with both
+derived registries still git-tracked and actively committed.
+
+This guide exists solely to re-surface that skipped migration. It re-runs the
+same detection; the actual steps live in the (now-delivered)
+`0.53.0-render-on-read-registries.md` alongside this file.
+
+## Detection
+
+Identical to the 0.53.0 guide — keyed on git-tracking state. Silent once both
+registries are untracked (migrated, or a fresh ≥0.53.0 install):
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+migrate=0
+for f in .forge/state/index.yml .forge/streams/active.yml; do
+  if git ls-files --error-unmatch "$f" >/dev/null 2>&1; then
+    echo "MIGRATE — $f is still git-tracked; the 0.53.0 render-on-read migration was skipped"
+    migrate=1
+  fi
+done
+[ "$migrate" -eq 0 ] && echo "OK — already migrated (or never tracked the registries)"
+```
+
+## Steps
+
+Detection fired → follow `0.53.0-render-on-read-registries.md` (same
+directory) end to end: `git rm --cached` the two registries, gitignore them
+(root `.gitignore`, or `state/index.yml` + `streams/active.yml` in
+`.forge/.gitignore` for create-forge installs), then boot `/forge` to
+regenerate the caches. Its Validation section applies unchanged.
+
+Detection silent → nothing to do; this guide is a no-op.