npm - forge-orkes - Versions diffs - 0.56.0 → 0.58.3 - Mend

forge-orkes 0.56.0 → 0.58.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/template/.forge/checks/tests/forge-hold-check.test.sh ADDED Viewed

@@ -0,0 +1,404 @@
+#!/usr/bin/env sh
+# Fixture-repo test suite for .forge/checks/forge-hold-check.sh (m-31, plan 53-01).
+#
+# Contract under test (plan-01 "Locked interface" — do not re-derive):
+#   forge-hold-check.sh <base>...<head> [--approvals <file>]
+#   stdout: hold=clear                                      (no facts)
+#           hold=blocked  + fact=<class>:<path> lines       (facts, no operator act)
+#           hold=waived waived_by=<login>
+#                         + "fact=<class>:<path> waived"    (facts + operator approval)
+#           class ∈ irreversible|structural|protected
+#   exit:   0 = clear or waived; 1 = blocked; 2 = bad invocation (missing arg,
+#           non-three-dot range, unresolvable refs, missing --approvals file).
+#   Range MUST be three-dot BASE...HEAD; the fact base is merge-base(BASE, HEAD).
+#   Config .forge/hold-config.yml is read from the BASE side only
+#   (git show <merge-base>:...) — a PR cannot rewrite the rules it is judged by.
+#   Built-ins are hard-coded and config is ADDITIVE only (raise-only):
+#     irreversible: */migrations/*, */migrate/*, db/schema*, *.sql  (+config irreversible_paths)
+#     structural:   NEW dependency key in package.json, composer.json, pyproject.toml,
+#                   requirements*.txt, Gemfile, go.mod, Cargo.toml — version-value
+#                   changes to an existing key NEVER fire; lockfiles (package-lock.json,
+#                   yarn.lock, pnpm-lock.yaml, composer.lock, Gemfile.lock, go.sum,
+#                   Cargo.lock, uv.lock, poetry.lock) ignored entirely (pain 6)
+#     protected:    .github/workflows/*, .gitlab-ci.yml, .forge/project.yml,
+#                   .forge/hold-config.yml, .forge/checks/** (scripts + fixture
+#                   suites)  (+config deploy_paths, gating_tests)
+#   Waiver: any --approvals login ∈ base-side config operators: → waived. Absent
+#   config / empty operators → NO waiver possible (raise-only safe default).
+#
+# Builds throwaway git repos in mktemp dirs with NO remote configured anywhere —
+# offline by construction (NFR-032); any network dependency in the script breaks here.
+#
+# Usage:
+#   ./.forge/checks/tests/forge-hold-check.test.sh              # all cases
+#   ./.forge/checks/tests/forge-hold-check.test.sh pain6        # one tag
+# Filter tags: irreversible structural pain6 waiver self-protect docs-only invocation multi
+#
+# RED-phase friendly (TDD): a missing/non-executable helper does NOT abort the
+# suite — every selected case FAILS with "(helper missing ...)" as the got-value
+# and the suite exits non-zero. Exits 0 iff every selected case passes. Self-cleans.
+set -u
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/../forge-hold-check.sh"
+[ -x "$HELPER" ] || printf 'NOTE: %s missing or not executable — RED phase, every selected case below should FAIL\n' "$HELPER" >&2
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+# Isolate from the developer's global/system git config.
+GIT_CONFIG_GLOBAL=/dev/null
+GIT_CONFIG_SYSTEM=/dev/null
+export GIT_CONFIG_GLOBAL GIT_CONFIG_SYSTEM
+PASSED=0
+FAILED=0
+SELECTED=0
+FILTER="${1:-}"
+pass() { PASSED=$((PASSED + 1)); printf 'PASS: %s\n' "$1"; }
+fail() { FAILED=$((FAILED + 1)); printf 'FAIL: %s\n' "$1" >&2; }
+check() { # desc, actual, expected (exact match)
+  if [ "$2" = "$3" ]; then pass "$1"; else fail "$1 (got '$2', want '$3')"; fi
+}
+check_contains() { # desc, actual, needle
+  case "$2" in
+    *"$3"*) pass "$1" ;;
+    *) fail "$1 (got '$2', must contain '$3')" ;;
+  esac
+}
+check_absent() { # desc, actual, forbidden-substring
+  case "$2" in
+    *"$3"*) fail "$1 (got '$2', must NOT contain '$3')" ;;
+    *) pass "$1" ;;
+  esac
+}
+running() { # tag... — 0 if this case block is selected by $FILTER (empty = all)
+  if [ -z "$FILTER" ]; then SELECTED=$((SELECTED + 1)); return 0; fi
+  for _t in "$@"; do
+    if [ "$_t" = "$FILTER" ]; then SELECTED=$((SELECTED + 1)); return 0; fi
+  done
+  return 1
+}
+# Run the helper from a repo cwd; sets OUT (stdout) and RC. RED-friendly.
+run_hold() { # cwd, helper-args...
+  rh_cwd="$1"; shift
+  if [ -x "$HELPER" ]; then
+    if OUT="$(cd "$rh_cwd" && "$HELPER" "$@" 2>/dev/null)"; then RC=0; else RC=$?; fi
+  else
+    OUT="(helper missing or not executable: $HELPER)"
+    RC=127
+  fi
+}
+# NO `git remote add` anywhere: fixtures are remote-less by construction (NFR-032).
+new_repo() { # name → prints repo path (main branch, one root commit)
+  d="$ROOT/repo.$1"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" symbolic-ref HEAD refs/heads/main
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name tester
+  git -C "$d" commit --allow-empty -qm init
+  printf '%s\n' "$d"
+}
+put() { # repo, path, content — write + stage + commit on current branch
+  p_dir=$(dirname "$1/$2")
+  mkdir -p "$p_dir"
+  printf '%s\n' "$3" > "$1/$2"
+  git -C "$1" add "$2"
+  git -C "$1" commit -qm "edit $2"
+}
+pr() { # repo — create + switch to branch 'pr' off main
+  git -C "$1" checkout -qb pr main
+}
+approvals() { # name, login... → prints file path with one login per line
+  a_f="$ROOT/approvals.$1"
+  : > "$a_f"
+  for _l in "$@"; do [ "$_l" = "$1" ] && continue; printf '%s\n' "$_l" >> "$a_f"; done
+  printf '%s\n' "$a_f"
+}
+CONFIG_OPS='version: 1
+operators:
+  - zayne
+irreversible_paths: []
+deploy_paths: []
+gating_tests: []'
+# ---------------------------------------------------------------------------
+# irreversible — acceptance 1: migration fires naming the fact; neg control clean
+# ---------------------------------------------------------------------------
+if running irreversible; then
+  R=$(new_repo irr)
+  put "$R" src/app.js 'console.log(1)'
+  pr "$R"
+  put "$R" app/migrations/001_add_users.py 'create table users'
+  put "$R" src/app.js 'console.log(2)'
+  run_hold "$R" 'main...pr'
+  check "irreversible: migration file blocks (exit 1)" "$RC" "1"
+  check_contains "irreversible: verdict line" "$OUT" "hold=blocked"
+  check_contains "irreversible: fact names class+path" "$OUT" "fact=irreversible:app/migrations/001_add_users.py"
+  R=$(new_repo irr-neg)
+  put "$R" src/app.js 'console.log(1)'
+  pr "$R"
+  put "$R" src/app.js 'console.log(2)'
+  run_hold "$R" 'main...pr'
+  check "irreversible neg: same diff minus migration is clean (exit 0)" "$RC" "0"
+  check "irreversible neg: silent verdict only" "$OUT" "hold=clear"
+  R=$(new_repo irr-schema)
+  pr "$R"
+  put "$R" db/schema.rb 'ActiveRecord::Schema.define'
+  run_hold "$R" 'main...pr'
+  check "irreversible: db/schema* fires" "$RC" "1"
+  check_contains "irreversible: schema fact" "$OUT" "fact=irreversible:db/schema.rb"
+  R=$(new_repo irr-sql)
+  pr "$R"
+  put "$R" scripts/backfill.sql 'UPDATE users SET x=1;'
+  run_hold "$R" 'main...pr'
+  check "irreversible: *.sql data-mutation script fires" "$RC" "1"
+  check_contains "irreversible: sql fact" "$OUT" "fact=irreversible:scripts/backfill.sql"
+  # Config ADDS a glob (additive union with built-ins)
+  R=$(new_repo irr-conf)
+  put "$R" .forge/hold-config.yml 'version: 1
+operators: []
+irreversible_paths:
+  - "dangerzone/*"
+deploy_paths: []
+gating_tests: []'
+  pr "$R"
+  put "$R" dangerzone/wipe.txt 'boom'
+  run_hold "$R" 'main...pr'
+  check "irreversible: config-added glob fires" "$RC" "1"
+  check_contains "irreversible: config-glob fact" "$OUT" "fact=irreversible:dangerzone/wipe.txt"
+fi
+# ---------------------------------------------------------------------------
+# pain6 / structural — acceptance 2: bump+lockfile NEVER fire; NEW dep entry fires
+# ---------------------------------------------------------------------------
+if running pain6 structural; then
+  R=$(new_repo bump)
+  put "$R" package.json '{
+  "name": "app",
+  "dependencies": {
+    "left-pad": "1.0.0",
+    "express": "4.17.0"
+  }
+}'
+  put "$R" package-lock.json '{"lockfileVersion": 2, "v": 1}'
+  pr "$R"
+  put "$R" package.json '{
+  "name": "app",
+  "dependencies": {
+    "left-pad": "1.3.0",
+    "express": "4.18.2"
+  }
+}'
+  put "$R" package-lock.json '{"lockfileVersion": 2, "v": 2}'
+  run_hold "$R" 'main...pr'
+  check "pain6: version bump + lockfile churn is clean (exit 0)" "$RC" "0"
+  check "pain6: verdict" "$OUT" "hold=clear"
+  R=$(new_repo newdep)
+  put "$R" package.json '{
+  "name": "app",
+  "dependencies": {
+    "express": "4.17.0"
+  }
+}'
+  pr "$R"
+  put "$R" package.json '{
+  "name": "app",
+  "dependencies": {
+    "express": "4.17.0",
+    "evil-pkg": "0.0.1"
+  }
+}'
+  run_hold "$R" 'main...pr'
+  check "pain6 neg: NEW dependency entry fires structural (exit 1)" "$RC" "1"
+  check_contains "pain6 neg: structural fact names manifest" "$OUT" "fact=structural:package.json"
+  R=$(new_repo lockonly)
+  put "$R" package-lock.json '{"v": 1}'
+  pr "$R"
+  put "$R" package-lock.json '{"v": 2}'
+  put "$R" yarn.lock 'lock churn'
+  run_hold "$R" 'main...pr'
+  check "pain6: lockfile-only churn is clean (exit 0)" "$RC" "0"
+  # Second manifest format: requirements.txt
+  R=$(new_repo reqs)
+  put "$R" requirements.txt 'flask==2.0.0
+requests==2.28.0'
+  pr "$R"
+  put "$R" requirements.txt 'flask==2.3.0
+requests==2.28.0'
+  run_hold "$R" 'main...pr'
+  check "pain6: requirements.txt version bump clean" "$RC" "0"
+  R=$(new_repo reqs-new)
+  put "$R" requirements.txt 'flask==2.0.0'
+  pr "$R"
+  put "$R" requirements.txt 'flask==2.0.0
+sketchy-lib==0.1.0'
+  run_hold "$R" 'main...pr'
+  check "pain6 neg: requirements.txt NEW entry fires" "$RC" "1"
+  check_contains "pain6 neg: requirements fact" "$OUT" "fact=structural:requirements.txt"
+  # go.mod: bump clean / new require fires
+  R=$(new_repo gomod)
+  put "$R" go.mod 'module example.com/app
+require (
+	github.com/pkg/errors v0.8.0
+)'
+  pr "$R"
+  put "$R" go.mod 'module example.com/app
+require (
+	github.com/pkg/errors v0.9.1
+)'
+  put "$R" go.sum 'churn'
+  run_hold "$R" 'main...pr'
+  check "pain6: go.mod version bump + go.sum churn clean" "$RC" "0"
+fi
+# ---------------------------------------------------------------------------
+# waiver — acceptance 3: operator approval waives + lists; non-operator does not
+# ---------------------------------------------------------------------------
+if running waiver; then
+  R=$(new_repo waive)
+  put "$R" .forge/hold-config.yml "$CONFIG_OPS"
+  pr "$R"
+  put "$R" app/migrations/002_drop_col.py 'drop column'
+  AF=$(approvals w1 zayne)
+  run_hold "$R" 'main...pr' --approvals "$AF"
+  check "waiver: operator approval waives (exit 0)" "$RC" "0"
+  check_contains "waiver: verdict names login" "$OUT" "hold=waived waived_by=zayne"
+  check_contains "waiver: lists what it waived" "$OUT" "fact=irreversible:app/migrations/002_drop_col.py waived"
+  AF=$(approvals w2 bot-agent)
+  run_hold "$R" 'main...pr' --approvals "$AF"
+  check "waiver neg: non-operator approval stays blocked (exit 1)" "$RC" "1"
+  check_contains "waiver neg: still names the fact" "$OUT" "fact=irreversible:app/migrations/002_drop_col.py"
+  check_absent "waiver neg: no waived verdict" "$OUT" "hold=waived"
+  run_hold "$R" 'main...pr'
+  check "waiver neg: no approvals input stays blocked (exit 1)" "$RC" "1"
+  # Operators are read from BASE: a PR that adds its approver to operators
+  # cannot self-waive — and the config edit itself raises protected.
+  R=$(new_repo selfadd)
+  put "$R" .forge/hold-config.yml "$CONFIG_OPS"
+  pr "$R"
+  put "$R" app/migrations/003_evil.py 'drop table'
+  put "$R" .forge/hold-config.yml 'version: 1
+operators:
+  - zayne
+  - mallory
+irreversible_paths: []
+deploy_paths: []
+gating_tests: []'
+  AF=$(approvals w3 mallory)
+  run_hold "$R" 'main...pr' --approvals "$AF"
+  check "waiver F4: head-side operator self-add cannot waive (exit 1)" "$RC" "1"
+  check_contains "waiver F4: config edit raises protected fact" "$OUT" "fact=protected:.forge/hold-config.yml"
+  # No config at base → empty operators → approval cannot waive (raise-only default)
+  R=$(new_repo noconf)
+  pr "$R"
+  put "$R" app/migrations/004_x.py 'alter'
+  AF=$(approvals w4 zayne)
+  run_hold "$R" 'main...pr' --approvals "$AF"
+  check "waiver: absent config means NO waiver possible (exit 1)" "$RC" "1"
+fi
+# ---------------------------------------------------------------------------
+# self-protect — acceptance 4: config + scripts + project.yml + CI defs hard-coded
+# ---------------------------------------------------------------------------
+if running self-protect protected; then
+  for f in .forge/hold-config.yml .forge/checks/forge-hold-check.sh .forge/checks/forge-check-lint.sh .forge/checks/tests/forge-hold-check.test.sh .forge/project.yml .github/workflows/ci.yml .gitlab-ci.yml; do
+    R=$(new_repo "sp-$(printf '%s' "$f" | tr '/.' '--')")
+    pr "$R"
+    put "$R" "$f" 'edited'
+    run_hold "$R" 'main...pr'
+    check "self-protect: $f edit blocks (exit 1)" "$RC" "1"
+    check_contains "self-protect: $f named as protected fact" "$OUT" "fact=protected:$f"
+  done
+  # Config ADDS deploy path (additive; base side)
+  R=$(new_repo sp-deploy)
+  put "$R" .forge/hold-config.yml 'version: 1
+operators: []
+irreversible_paths: []
+deploy_paths:
+  - "deploy/*"
+gating_tests: []'
+  pr "$R"
+  put "$R" deploy/prod.tf 'resource {}'
+  run_hold "$R" 'main...pr'
+  check "self-protect: config-added deploy path fires" "$RC" "1"
+  check_contains "self-protect: deploy fact" "$OUT" "fact=protected:deploy/prod.tf"
+fi
+# ---------------------------------------------------------------------------
+# docs-only — acceptance 6: a status on every PR; clean exits 0 silent
+# ---------------------------------------------------------------------------
+if running docs-only; then
+  R=$(new_repo docs)
+  put "$R" README.md 'hello'
+  pr "$R"
+  put "$R" README.md 'hello world'
+  put "$R" docs/guide.md 'guide'
+  run_hold "$R" 'main...pr'
+  check "docs-only: exit 0" "$RC" "0"
+  check "docs-only: exactly hold=clear, nothing else" "$OUT" "hold=clear"
+fi
+# ---------------------------------------------------------------------------
+# multi — a risky PR names EVERY fact, one line each
+# ---------------------------------------------------------------------------
+if running multi; then
+  R=$(new_repo multi)
+  put "$R" package.json '{"dependencies": {"a": "1.0.0"}}'
+  pr "$R"
+  put "$R" package.json '{"dependencies": {"a": "1.0.0", "b": "2.0.0"}}'
+  put "$R" db/migrations/005.sql 'ALTER TABLE'
+  put "$R" .github/workflows/deploy.yml 'on: push'
+  run_hold "$R" 'main...pr'
+  check "multi: blocked (exit 1)" "$RC" "1"
+  check_contains "multi: irreversible named" "$OUT" "fact=irreversible:db/migrations/005.sql"
+  check_contains "multi: structural named" "$OUT" "fact=structural:package.json"
+  check_contains "multi: protected named" "$OUT" "fact=protected:.github/workflows/deploy.yml"
+fi
+# ---------------------------------------------------------------------------
+# invocation — exit 2 on bad usage, never a false verdict
+# ---------------------------------------------------------------------------
+if running invocation; then
+  R=$(new_repo inv)
+  run_hold "$R"
+  check "invocation: missing range exits 2" "$RC" "2"
+  run_hold "$R" 'main..pr'
+  check "invocation: two-dot range rejected (exit 2)" "$RC" "2"
+  run_hold "$R" 'nosuch...branches'
+  check "invocation: unresolvable refs exit 2" "$RC" "2"
+  pr "$R"
+  put "$R" src/x.js 'x'
+  run_hold "$R" 'main...pr' --approvals "$ROOT/definitely-missing-file"
+  check "invocation: missing --approvals file exits 2 (derivation failed = loud)" "$RC" "2"
+fi
+# ---------------------------------------------------------------------------
+printf '\n%d selected case block(s): %d passed, %d failed\n' "$SELECTED" "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ] && [ "$SELECTED" -gt 0 ]

package/template/.forge/gitignore CHANGED Viewed

@@ -4,7 +4,12 @@
 # project state survives machine loss and can be pulled from any clone:
 #   FORGE.md project.yml constitution.md design-system.md context.md roadmap.yml
 #   requirements/ phases/ research/ decisions/ contracts/ audits/
-#   refactor-backlog.yml state/ templates/ migrations/
+#   refactor-backlog.yml state/ templates/ migrations/ checks/
+#
+# checks/ (the merge-floor CI check scripts + fixture suites) is deliberately
+# HERE and not in .claude/hooks/: many projects gitignore .claude/hooks/ as
+# per-developer files, and an ignored script can neither run in CI nor be
+# guarded by the hold check's protected-path self-protection.
 #
 # The entries below are the ONLY ephemeral exceptions — session- or
 # machine-local artifacts that must never be committed.

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

@@ -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.2-merge-floor-checks-relocation.md ADDED Viewed

@@ -0,0 +1,61 @@
+# Migration Guide: Merge-floor checks relocate to `.forge/checks/` (Forge 0.58.2)
+Applies to projects that received the merge-floor check scripts —
+`forge-hold-check.sh`, `forge-check-lint.sh` + their fixture suites — under
+`.claude/hooks/` (shipped there in 0.57.0–0.58.1), and/or wired CI at that path.
+0.58.2 moves them to **`.forge/checks/`** (scripts at the top, suites under
+`tests/`). Why: many projects gitignore `.claude/hooks/` as per-developer files
+(host-verified on ptnrkit). A gitignored script never reaches the repo CI
+clones — the *required check can't run* — and, invisible to the PR diff, the
+hold check's self-protection can't guard it either. `.forge/**` is committed in
+installed projects, so `.forge/checks/` is CI-runnable and sits inside the hold
+check's hard-coded protected set (`.forge/checks/**`, replacing the two old
+`.claude/hooks/` entries).
+The upgrade (npm bin or `/upgrading` Step 4a) **adds** `.forge/checks/` but —
+additive by design — never deletes the old copies. This guide is the cleanup.
+## Detection
+Fires when an old-path copy or an old-path CI reference is still present:
+```bash
+migrate=0
+for f in .claude/hooks/forge-hold-check.sh .claude/hooks/forge-check-lint.sh \
+         .claude/hooks/tests/forge-hold-check.test.sh .claude/hooks/tests/forge-check-lint.test.sh; do
+  [ -f "$f" ] && { echo "MIGRATE — stale relocation leftover: $f"; migrate=1; }
+done
+if grep -rl '\.claude/hooks/forge-\(hold-check\|check-lint\)\.sh' \
+     .github/workflows .gitlab-ci.yml 2>/dev/null; then
+  echo "MIGRATE — CI still invokes the old path"; migrate=1
+fi
+[ "$migrate" -eq 0 ] && echo "OK — already migrated (or never had the checks)"
+```
+## Steps
+1. **Upgrade first** (`npx forge-orkes upgrade`, or `/upgrading`) so
+   `.forge/checks/` exists with the 0.58.2 scripts.
+2. **Commit `.forge/checks/`** — it is *meant to be tracked*, unlike
+   `.claude/hooks/`: `git add .forge/checks && git commit -m "chore(forge): track merge-floor checks at .forge/checks/"`.
+3. **Delete the old copies** listed by the detection block (plus
+   `git rm --cached` them first if your project tracks `.claude/hooks/`).
+4. **Re-point CI** — in `.github/workflows/merge-floor.yml` / `.gitlab-ci.yml`,
+   change `./.claude/hooks/forge-{hold-check,check-lint}.sh` →
+   `./.forge/checks/forge-{hold-check,check-lint}.sh` (full snippets:
+   `docs/merge-floor-checks.md` §5–6). Expect the PR carrying this CI edit to
+   raise a **protected-path hold on itself** — that is the self-protection
+   working; the operator's PR approval waives it.
+5. If your `.forge/hold-config.yml` `gating_tests:`/`deploy_paths:` lists name
+   the old paths (unusual), update them too.
+Projects that gitignored `.claude/hooks/` never had the scripts in CI at all —
+for them steps 3–5 reduce to wiring CI at `.forge/checks/` for the first time.
+## Verify
+```bash
+./.forge/checks/tests/forge-hold-check.test.sh && ./.forge/checks/tests/forge-check-lint.test.sh
+git ls-files --error-unmatch .forge/checks/forge-hold-check.sh   # tracked = ✓
+```

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

@@ -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.

package/template/.forge/templates/hold-config.yml ADDED Viewed

@@ -0,0 +1,34 @@
+# Forge hold-config — per-repo path lists for the merge-floor hold check
+# (.forge/checks/forge-hold-check.sh; see docs/merge-floor-checks.md).
+#
+# ADDITIVE ONLY: every list below UNIONS with the check's hard-coded built-ins —
+# nothing here can remove a hold class (raise-only by construction, D-9/A4d).
+#
+# SELF-PROTECTED: this file's path and the whole .forge/checks/** subtree (both
+# check scripts + their fixture suites) are hard-coded into the check's
+# protected set. A PR that edits any of them raises a protected-path hold on
+# itself — editing the watchdog's rules wakes the watchdog (fold-pass F4/F5
+# lesson). The check reads this file from the BASE side of the diff, so a PR
+# cannot rewrite the rules it is judged by.
+version: 1
+# Logins whose PR review approval waives a hold (the recorded operator act, B2).
+# Empty ⇒ no waiver is possible — holds block until this is configured.
+operators: []
+  # - your-login
+# Extra irreversible-class paths (migrations, schema, data-mutation scripts)
+# beyond the built-ins (*/migrations/*, */migrate/*, db/schema*, *.sql).
+irreversible_paths: []
+  # - "db/seeds/*"
+# Deploy config paths (protected class) beyond the built-in CI-definition set
+# (.github/workflows/*, .gitlab-ci.yml).
+deploy_paths: []
+  # - "deploy/*"
+  # - "Dockerfile"
+# Gating test files (protected class; also narrows the check-quality lint's
+# deleted-assertion scope when set — default there is EVERY test file in the diff).
+gating_tests: []
+  # - "tests/e2e/*"