npm - forge-orkes - Versions diffs - 0.55.0 → 0.58.2 - Mend

forge-orkes 0.55.0 → 0.58.2

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 (20) hide show

package/bin/create-forge.js +6 -0
package/package.json +1 -1
package/template/.claude/hooks/forge-release-fold.sh +458 -0
package/template/.claude/hooks/tests/forge-release-fold.test.sh +773 -0
package/template/.claude/settings.json +1 -1
package/template/.claude/skills/forge/SKILL.md +4 -2
package/template/.claude/skills/reviewing/SKILL.md +1 -1
package/template/.claude/skills/upgrading/SKILL.md +18 -0
package/template/.claude/skills/verifying/SKILL.md +9 -2
package/template/.forge/FORGE.md +8 -3
package/template/.forge/checks/forge-check-lint.sh +383 -0
package/template/.forge/checks/forge-hold-check.sh +259 -0
package/template/.forge/checks/tests/forge-check-lint.test.sh +597 -0
package/template/.forge/checks/tests/forge-hold-check.test.sh +404 -0
package/template/.forge/gitignore +6 -1
package/template/.forge/migrations/0.56.0-merged-validated-fold.md +74 -0
package/template/.forge/migrations/0.58.2-merge-floor-checks-relocation.md +61 -0
package/template/.forge/templates/hold-config.yml +34 -0
package/template/.forge/templates/project.yml +51 -21
package/template/.forge/templates/state/index.yml +51 -24

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.56.0-merged-validated-fold.md ADDED Viewed

@@ -0,0 +1,74 @@
+# Migration Guide: Merged→validated fold (Forge 0.56.0)
+0.56.0 adds a **derived `release_state`** dimension — each unit of work is now
+computed (at every `forge` boot, from git truth) as `unmerged`, `merged`, or
+`validated` and rendered into the git-ignored `index.yml` cache. Nothing is
+stored: the fold-of-record `.claude/hooks/forge-release-fold.sh` recomputes it
+on read, so a value can never go stale. See
+[ADR-024](../decisions/ADR-024-merged-validated-fold.md).
+**This change is inert by default.** With no `forge.validation_event` configured
+— which is every existing repo, including forge itself — every gate (milestone
+close, worktree teardown, boot) behaves byte-for-byte as before. The only
+difference is an additional derived column in the git-ignored cache. You do not
+have to do anything.
+## What arrives via upgrading
+The `upgrading` skill (or `npx forge-orkes upgrade`) syncs the framework files:
+- `.claude/hooks/forge-release-fold.sh` (+ its test suite) — the fold.
+- Skill edits to `forge` (boot rollup renders `release_state`), `verifying`,
+  `reviewing` (the human-gate now dispatches on the binding), and
+  `orchestrating` (worktree teardown splits on merged-ness).
+- `.forge/templates/project.yml` — a commented `forge.validation_event` block
+  documenting the opt-in.
+**Not touched:** your `project.yml`. The binding is opt-in — the upgrade never
+writes it. `human_verified` / M0 sign-off / the legacy-complete grandfather all
+keep working exactly as today.
+## Opting in (deploy-surface repos only)
+A repo that gates release on a real deployment can bind validation to a
+host-recorded promotion. In `project.yml`:
+```yaml
+forge:
+  validation_event: promotion_approval
+  promotion:
+    tag_pattern: "promotion/{sha}"      # FROZEN — your promotion job must emit it byte-exactly
+    allowed_signers: ".forge/promotion_signers"   # committed, PUBLIC keys only
+```
+Under `promotion_approval`, `complete` becomes the machine/code-verified state
+(no in-session sign-off required) and the human gate relocates to the deploy
+boundary: a unit renders `validated` only once a **CI-signed** `promotion/{sha}`
+tag covers its landed SHA. The fold verifies the tag **offline** (`git tag -v`
+against the allowed-signers file) — no network.
+### Prerequisite (Track B — not shipped by this change)
+`promotion_approval` is only meaningful once your deploy pipeline emits the
+signed tag. That job must:
+1. Run in a protected/Environment-approved context holding a **CI-held SSH key**
+   no agent context can read.
+2. SSH-sign a tag named `promotion/<full-deploy-sha>` on the approved deploy
+   commit.
+3. Commit the signing key's **public** half to the `allowed_signers` path.
+Until that job exists, leave `validation_event` unset (the default) — the fold
+stays inert.
+## Detection
+Data-driven by filename: `upgrading` globs `.forge/migrations/{v}-*.md` and
+surfaces any guide where `installed < v <= source`. No action needed beyond the
+framework-file sync — this guide fires automatically on upgrade to 0.56.0.
+## Nothing-to-do default
+If you do not run a deploy-gated release flow, ignore all of the above. The
+default binding is your current behavior; 0.56.0 changes nothing you can see
+except a new derived column in a cache you never commit.

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/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/*"