forge-orkes 0.61.0 → 0.63.0

package/template/.forge/migrations/0.63.0-origin-first-upgrading.md

@@ -0,0 +1,49 @@
+# Migration Guide: Origin-First Upgrading (Forge 0.63.0)
+
+Applies to projects whose installed `upgrading` skill predates 0.63.0. The default `/upgrading` path changed from "sync from a local Forge clone at `.forge/dev-source`" to "wrap the npm registry bin": `/upgrading` now runs `npx forge-orkes@latest upgrade --yes --json` as the one sync engine and layers the agent-only steps (migration prompts, experimental re-sync, Codex offer, worktree propagation) on the bin's JSON report. Local-clone sync survives only as explicit **Dev Mode** (`/upgrading dev`) — presence of `.forge/dev-source` never selects it (ADR-026).
+
+## Prerequisites
+
+1. Network access to the npm registry (the new default path runs `npx forge-orkes`).
+2. Nothing else — the migration IS the upgrade run; no files need hand-editing.
+
+## Detection
+
+Prints `MIGRATE` when the installed upgrading skill is old-shape (it lacks the registry engine invocation the 0.63.0 skill always carries); silent + exit 0 otherwise.
+
+```bash
+# Old-shape upgrading skill: exists but lacks the registry engine invocation.
+S=.claude/skills/upgrading/SKILL.md
+[ -f "$S" ] || exit 0                        # skill not installed → nothing to do
+if ! grep -q 'forge-orkes@latest upgrade --yes --json' "$S" 2>/dev/null; then
+  echo "MIGRATE — installed upgrading skill predates the origin-first default (registry engine); re-running the upgrade replaces it"
+fi
+```
+
+## Migration steps
+
+### 1. Re-run the upgrade
+
+The sync itself replaces the skill — that is the whole migration. Either route works:
+
+- `npx forge-orkes@latest upgrade` (any machine, no clone needed), or
+- `/upgrading` in a Claude Code session **on 0.63.0+ framework files** (the run that installs this guide already synced the new skill; this Detection then stops firing).
+
+### 2. Understand what changed in daily use
+
+- **`/upgrading`** now upgrades from the npm registry. If `.forge/dev-source` exists you will see exactly one notice line — *"dev mode available — `/upgrading dev`"* — and the registry upgrade proceeds anyway.
+- **`/upgrading X.Y.Z`** pins the engine to that release (`npx forge-orkes@X.Y.Z upgrade --yes --json`).
+- **`/upgrading dev`** is the only way to sync from a local clone (framework development). Its flow — source resolution, downgrade guard, upstream desire-path harvest — is unchanged, just explicit.
+- Experimental skills now re-sync from the release tarball itself (`experimental/` ships in the package since 0.63.0), so registry-only machines get staleness detection + consent-gated re-sync too (closes issue #5).
+
+### 3. Optional: drop `.forge/dev-source` on non-dev machines
+
+On machines that never develop Forge itself, the file now only produces the notice line. Removing it is safe and silences the notice. Keep it on your framework-dev machine(s) for `/upgrading dev`.
+
+## Validation
+
+```bash
+grep -q 'forge-orkes@latest upgrade --yes --json' .claude/skills/upgrading/SKILL.md \
+  && echo "upgrading skill is origin-first (0.63.0+)" \
+  || echo "still old-shape — re-run the upgrade"
+```