forge-orkes 0.42.0 → 0.46.0

package/template/.forge/migrations/0.43.0-safety-policy.md

@@ -0,0 +1,60 @@
+# Migration Guide: Safety & Policy Hardening (Forge 0.43.0)
+
+Forge 0.43.0 adds two layers ported from a comparison against the Sendmarc internal framework:
+
+- **[ADR-017](https://github.com/Attuned-Media/forge/blob/main/docs/decisions/ADR-017-deterministic-safety-guardrails.md)** — deterministic safety-guardrail hooks (`block-dangerous-commands`, `scan-secrets`, `protect-files`, `warn-large-files`), `format-on-save`, `permissions.deny` for secrets, and a hook test harness.
+- **[ADR-018](https://github.com/Attuned-Media/forge/blob/main/docs/decisions/ADR-018-lightweight-policy-layer.md)** — the `.claude/rules/` layer (always-on `agent-discipline` rule), confidence-gated specialist reviewer agents, and an opt-in `experimental/conventions/` pack.
+
+**Mostly automatic, backward-compatible.** Running `npx forge-orkes@latest upgrade` does the heavy lifting: it additively installs the guardrail hooks and the always-on rule, syncs the specialist agents, and merges the hook wiring + `deny` globs into your `settings.json` — **without** removing any hooks/rules you added (m10's `forge-claim-check` and pack-installed stack rules are preserved). Nothing breaks if you do nothing; the guardrails simply aren't active until the settings carry them.
+
+## Detection
+
+Prints `MIGRATE` when the project is missing the safety hooks. Silent + exit 0 once present.
+
+```bash
+[ -d .forge ] || exit 0                                        # not a Forge project
+[ -f .claude/hooks/block-dangerous-commands.sh ] && exit 0     # already migrated → silent
+echo "MIGRATE — run 'npx forge-orkes@latest upgrade' to install the safety guardrails (ADR-017) + rules layer (ADR-018)"
+exit 0
+```
+
+## Migration steps
+
+### 1. Upgrade
+
+```bash
+npx forge-orkes@latest upgrade
+```
+
+This installs/refreshes `.claude/hooks/` (guardrails + `tests/`), adds `.claude/rules/agent-discipline.md`, syncs the `security/performance/doc-reviewer` agents, `chmod +x`'s the hook scripts, and additively merges the hook groups + secret-`deny` globs into `.claude/settings.json` (idempotent — safe to re-run).
+
+### 2. Ensure `jq` is installed
+
+The guard hooks parse tool JSON with `jq` and **fail closed** (block with an install message) without it. It is already a Forge prerequisite:
+
+```bash
+jq --version || brew install jq        # macOS
+jq --version || sudo apt install jq    # Debian/Ubuntu
+```
+
+### 3. Verify
+
+```bash
+.claude/hooks/tests/run.sh             # hook test suite — expect all green
+ls -l .claude/hooks/*.sh               # expect -rwxr-xr-x (executable)
+```
+
+If the scripts aren't executable (a copy can strip the bit): `chmod +x .claude/hooks/*.sh`.
+
+## Notes & opt-outs
+
+- **Protected-branch pushes are blocked by default** (`main`, `master`, + `git init.defaultBranch`). If a repo legitimately commits to `main`, set `CLAUDE_PROTECTED_BRANCHES=""` (empty) in your shell or `settings.json` `env` to disable *that check only* — force-push/filesystem/db/publish guards stay on. Add extra branches with `CLAUDE_PROTECTED_BRANCHES="main,develop,staging"`.
+- **Editing hooks/settings** is blocked/prompted by `protect-files`. In a project you re-sync hooks via `/upgrading`, not by hand. To author them deliberately, set `FORGE_ALLOW_HOOK_EDITS=1`.
+- **Describing a dangerous command in a commit message** (e.g. the literal text `git push --force`) can trip `block-dangerous-commands`, since it greps the whole Bash command string. Reword, or approve the override.
+- **Opt-in stack conventions:** if your project is Laravel/PHP, Python, or Vue, install the convention skills + path-scoped rules deliberately — they are not in the base template (Forge core is stack-agnostic):
+  ```bash
+  bash experimental/conventions/install.sh            # all stacks
+  bash experimental/conventions/install.sh laravel    # one stack
+  ```
+  (Delivered via the dev repo / `upgrading` experimental route, like m10 — not the npm tarball.)
+- **Specialist reviewers** are optional depth — the `reviewing` skill can spawn them for high-risk diffs, or invoke `security-reviewer` / `performance-reviewer` / `doc-reviewer` directly. The 3-mode `reviewer` is unchanged.

package/template/.forge/migrations/0.44.0-desire-paths.md

@@ -0,0 +1,57 @@
+# Migration Guide: Desire-Path Hardening (Forge 0.44.0)
+
+Forge 0.44.0 batches six desire-path framework fixes (forge#11–#16) surfaced from real multi-worktree usage. **It is backward-compatible** — five of the six are skill/prose behaviour changes that take effect the moment the framework files are synced, with nothing to migrate per project. The only mechanical change is the active-skill PreToolUse hook (forge#12), and `npx forge-orkes upgrade` applies it for you.
+
+## What changed (no action needed)
+
+- **#11** — the ID Reservation Protocol is now a **blocking gate** in `planning`/`architecting`, plus a new `forge` boot preflight (absent-`reservations.yml` nudge + un-reserved-ID backfill scan). Advisory; surfaces, never blocks.
+- **#13** — checkpoint publish (`verifying`) gains a **strand guard**: it pushes `origin HEAD:main` only when local `main` is an ancestor of the worktree HEAD, so a checkpoint can't leave your canonical main diverged. `forge` boot now also fast-forwards the **primary** main checkout from origin after a checkpoint.
+- **#14** — `executing` Step 0 now inits git submodules for worktrees from **any** origin (not just `orchestrating`-created ones) before the first build.
+- **#15** — `chief-of-staff` gains **Exclusive Resource Leases** (device/port/singleton) and `verifying`'s device gate acquires/releases them.
+- **#16** — `planning` adds a block-anchored **overlay/popover must_have checklist**.
+
+These ride in on the skill files synced by the upgrade. No per-project state changes.
+
+## The one mechanical change (auto-applied): active-skill hook (#12)
+
+The inline PreToolUse(Write\|Edit) "No active skill" guard in `.claude/settings.json` is replaced by `.claude/hooks/forge-active-skill-guard.sh`, which also allows edits when a milestone is durably `current.status: executing` (so a cleared marker no longer blocks a legitimate executing session). On upgrade, `create-forge.js` **strips the legacy inline guard** from your `settings.json` and the additive hooks sync installs + `chmod +x`'s the new script. Idempotent — re-running upgrade is a no-op.
+
+## Detection
+
+Prints `MIGRATE` only if a project still carries the **legacy inline** active-skill guard in `settings.json` (i.e. the new installer hasn't run yet). Silent + exit 0 once migrated.
+
+```bash
+[ -d .forge ] || exit 0                                       # not a Forge project
+[ -f .claude/settings.json ] || exit 0                        # no settings → nothing to migrate
+if grep -q 'if \[ ! -f' .claude/settings.json && grep -q 'No active skill' .claude/settings.json; then
+  echo "MIGRATE — settings.json still has the inline active-skill guard; re-run 'npx forge-orkes upgrade' to install forge-active-skill-guard.sh (forge#12)"
+fi
+exit 0
+```
+
+## Manual migration (only if Detection prints MIGRATE)
+
+Normally unnecessary — the installer does this. If you hand-merge settings, replace the inline `PreToolUse` "Write|Edit" guard command:
+
+```
+if [ ! -f "$(git rev-parse --show-toplevel 2>/dev/null)/.forge/.active-skill" ]; then echo "[Forge] No active skill. ..." >&2; exit 2; fi
+```
+
+with the script call, and ensure the script is present + executable:
+
+```bash
+# In .claude/settings.json, the PreToolUse Write|Edit hook command becomes:
+#   bash "$CLAUDE_PROJECT_DIR/.claude/hooks/forge-active-skill-guard.sh"
+chmod +x .claude/hooks/forge-active-skill-guard.sh
+git add .claude/settings.json .claude/hooks/forge-active-skill-guard.sh
+git commit -m "chore(forge): migrate active-skill guard to script (0.44.0, forge#12)"
+```
+
+## Validation
+
+```bash
+[ -x .claude/hooks/forge-active-skill-guard.sh ] && echo "OK: guard script present + executable" || echo "FAIL: guard script missing/not executable"
+grep -q 'forge-active-skill-guard.sh' .claude/settings.json && echo "OK: settings wired to script" || echo "FAIL: settings not wired"
+grep -q 'if \[ ! -f' .claude/settings.json && echo "WARN: legacy inline guard still present" || echo "OK: legacy inline guard removed"
+echo "validation complete"
+```

package/template/.forge/migrations/0.46.0-id-reservation-ledger.md

@@ -0,0 +1,44 @@
+# Migration Guide: ID Reservation Ledger in the Git Common Dir (Forge 0.46.0)
+
+Forge 0.46.0 moves the ID-reservation **coordination point** from the branch-tracked `.forge/reservations.yml` to a **machine-local ledger in the git common dir** — `.git/forge/id-reservations` — written by a new `forge-reserve` POSIX-sh helper. This fixes the cross-worktree collisions ADR-016 could not (a reservation on an unmerged branch is invisible to sibling worktrees, which share `.git`, not branches). See [ADR-021](../../docs/decisions/ADR-021-id-reservation-ledger-git-common-dir.md) (supersedes ADR-016) and [issue #19](https://github.com/Attuned-Media/forge/issues/19).
+
+**It is backward-compatible and zero-touch.** The helper is installed + `chmod +x`'d by the upgrade's additive hooks sync. The ledger self-creates on the **first** `forge-reserve` run, seeded implicitly by the allocation `max()` (which reads in-tree IDs + `main:.forge/reservations.yml`). Your existing `reservations.yml` is untouched and still respected as a `max()` input. A project that never runs concurrent worktrees sees no behavior change and needs no action.
+
+## What changed (no action needed)
+
+- **`forge-reserve` helper** allocates the next `ADR/DEF/FR/NFR` number under a portable `mkdir` lock and prints it on stdout; `planning` (fr/nfr/def) and `architecting` (adr) now call it instead of hand-scanning.
+- **Allocation is `max(ledger ∪ in-tree ∪ main:reservations.yml) + 1`** per kind — the ledger gives same-machine worktrees authority (including *uncommitted* siblings), while `main:reservations.yml` remains the durable cross-machine floor.
+- **`reservations.yml` is reclassified** from the coordination mechanism to a **durable audit trail + cross-machine floor**, still committed with your work by the helper.
+
+These take effect the moment the framework files are synced. No per-project state changes.
+
+## Detection
+
+Prints `MIGRATE` only if a project predates the helper (has `.forge/` but no `forge-reserve.sh`). Silent + exit 0 once the helper is present.
+
+```bash
+[ -d .forge ] || exit 0                                  # not a Forge project
+[ -f .claude/hooks/forge-reserve.sh ] && exit 0          # helper present → already migrated, silent
+echo "MIGRATE — ID reservation now uses .git/forge/id-reservations via forge-reserve; run 'npx forge-orkes upgrade' to install the helper (ADR-021, issue #19)"
+exit 0
+```
+
+## Migration steps (normally none)
+
+The upgrade installs the helper; the ledger self-creates on first reserve. Two optional cleanups:
+
+- **Backfill un-reserved IDs (recommended for concurrent-worktree projects).** `forge` boot's ID-reservation preflight lists landed `ADR-`/`FR-`/`NFR-`/`DEF-` IDs that have no `reservations.yml` entry. Appending them keeps `main:reservations.yml` a complete floor.
+- **ADR location caveat.** `forge-reserve`'s in-tree ADR scan reads `docs/decisions/ADR-NNN*` (per ADR-021). Projects that keep ADRs under **`.forge/decisions/`** should ensure those ADRs are represented in `reservations.yml` (via the backfill above) so the `main:reservations.yml` floor covers them — the ledger + floor still prevent collisions, but the in-tree ADR *input* won't see a `.forge/decisions/` file directly.
+
+## Cross-machine caveat (accepted)
+
+The ledger is machine-local (like the integration flag). Two *concurrent* worktrees on *different* laptops, both reserving before either merges, still fall back to merge-time renumber — bounded by the `main:reservations.yml` floor, so no worse than ADR-016. Tracked as DEF-046 (land-time detector deferred).
+
+## Validation
+
+```bash
+[ -x .claude/hooks/forge-reserve.sh ] && echo "OK: forge-reserve present + executable" || echo "FAIL: helper missing/not executable"
+id=$(.claude/hooks/forge-reserve.sh fr --milestone m-smoke --summary "migration smoke") && echo "OK: allocated $id" || echo "FAIL: forge-reserve did not run"
+# revert the smoke reservation: drop the last reservations.yml block + the ledger line for $id
+echo "validation complete"
+```