forge-orkes 0.62.0 → 0.63.0

package/template/.claude/skills/upgrading/SKILL.md

@@ -1,231 +1,160 @@
 ---
 name: upgrading
-description: "Sync Forge framework files from a local dev repo or NPM. Use when developing Forge itself or applying updates to an installed project."
+description: "Upgrade Forge framework files from the npm registry (origin-first default), or sync from a local dev repo in explicit dev mode. Use when applying updates to an installed project or developing Forge itself."
 ---
 
-# Upgrading: Local Dev Sync
+# Upgrading: Origin-First Registry Upgrade
 
-Sync framework files from a local Forge source repo into the current project for testing without publishing to NPM.
+The default upgrade path is the npm registry. This skill wraps the published bin (`forge-orkes`) as the **one sync engine** and layers the agent-only steps on top: the bin computes and applies the file sync; the skill renders the report and drives the consent-gated conversations. One computation, two renderings — never re-detect what the bin already reported. Local-clone sync survives only as explicit **Dev Mode** (`/upgrading dev`).
 
-For published upgrades, use `npx forge-orkes upgrade`.
+## Mode Gate (first)
 
-## Step 1: Resolve Source Path
+| Invocation | Mode |
+|---|---|
+| `/upgrading dev` | **Dev Mode** (below) — local-clone sync for developing Forge itself |
+| `/upgrading X.Y.Z` | Default path with the engine pinned: `npx forge-orkes@{version} upgrade --yes --json` |
+| `/upgrading` | Default path at `@latest` |
 
-Check if `.forge/dev-source` exists in the project root.
+## Default Path (registry)
 
-- **Exists:** Read the path (first line, trimmed). Confirm it contains `packages/create-forge/template/`.
-- **Missing:** Ask the user for the local Forge repo path, validate it has `packages/create-forge/template/`, save to `.forge/dev-source`.
+### 1. Preflight
 
-Template directory: `{source}/packages/create-forge/template/`.
+- Read the installed version: `.claude/settings.json` → `forge.version` (absent → treat as `unknown`).
+- `.forge/dev-source` present → emit exactly ONE notice line — *"dev mode available — `/upgrading dev`"* — and continue on the registry path. Presence of `.forge/dev-source` NEVER selects dev mode.
 
-### Harvest upstream desire paths (advisory)
-
-`upgrading` is the one skill that bridges this project and a local Forge clone (`{source}`), so it harvests framework-scope desire paths the project has queued (ADR-012). After resolving `{source}`:
-
-1. Glob this project's `.forge/state/desire-paths/upstream/*.md`. None → skip silently.
-2. Any present → list them and offer to copy each into `{source}/docs/desire-paths-inbox/` (create the dir if missing) — a **tracked** location in the Forge repo where it won't be lost on machine swap.
-3. On copy → move the project-side block to `.forge/state/desire-paths/upstream/harvested/` so it isn't re-offered. Report counts like other steps.
-
-Advisory — never blocks the sync. This is the **convenience tier**: the primary close is the GH issue offered by `forge` review at capture time. Harvest just catches anything written when `gh`/the repo URL wasn't available.
-
-### Downgrade guard
-
-Read the source version (`{source}/packages/create-forge/package.json` `version`) and the installed version (`.claude/settings.json` `forge.version`). **If source < installed, STOP** — do not sync. Report: *"Refusing to downgrade: installed v{installed} is newer than source v{source}. Point dev-source at a newer checkout, or confirm an intentional downgrade."* Only proceed on explicit user override. (Rolling backward overwrites newer framework files and deletes files newer versions added — and with `.claude/` often gitignored, it is unrecoverable.)
-
-## Step 2: File Classification
-
-| Category | Paths | Behavior |
-|----------|-------|----------|
-| **Framework-owned** | `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.forge/FORGE.md` | Overwrite |
-| **Import-managed** | `CLAUDE.md` | Never overwrite content; migrate legacy forge sections + guarantee the `@.forge/FORGE.md` import line (Step 5) |
-| **Merge-owned** | `.claude/settings.json` | Smart-merge `forge.*` keys only (Step 5) |
-| **Template-only** | `.forge/templates/**`, `.forge/migrations/**`, `.forge/gitignore` → `.forge/.gitignore` | Overwrite |
-| **Additive-sync** | `.claude/hooks/**` (incl. `tests/`), `.claude/rules/**`, `.forge/checks/**` (incl. `tests/`) | Add + overwrite template-shipped files; never delete local extras (Step 4a) |
-
-**Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements/`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
-
-**Experimental skills — re-sync, don't blanket-skip.** Opt-in skills installed separately (e.g. `.claude/skills/orchestrating/` from `experimental/m10/`) are not in the base template, so they never appear in the Step 3 base sync. Earlier guidance was to leave them *untouched* — but that silently froze them at install-time content, so a base-template migration that changes behavior living only in an experimental skill became a no-op (the version stamp advanced and the migration doc shipped, yet the behavior never landed — e.g. the 0.28.0 repo-scoped worktree root). Step 3b now gives experimental skills their own **detect-and-offer-re-sync** pass against their `experimental/*/source/` origin. Never auto-overwrite and never flag them "removed from template" — but never leave staleness invisible either.
-
-## Step 3: Sync Framework-Owned Files
-
-For each framework-owned file in the source template:
-
-1. Read source and local content
-2. Different → overwrite local, report **updated**
-3. Same → report **unchanged**
-4. Source has new file → copy, report **added**
-5. Local has file not in source → it may be an **experimental** skill — defer the verdict to Step 3b, which distinguishes "experimental, has a known source" from "genuinely removed from template." Only skills with no experimental source are reported **removed from template** (don't delete -- let user decide).
-
-## Step 3b: Re-sync Experimental Skills (detect + offer, never blanket-skip)
-
-Experimental skills are installed from `{source}/packages/create-forge/experimental/<pkg>/source/skills/<name>/`, not the base template — so Step 3 never sees them. Without this pass they freeze at install-time content forever (issue #5). This pass makes staleness **visible and one-click-fixable** while staying non-destructive.
-
-For each skill dir present in the project's `.claude/skills/` but **absent from the base template**:
-
-1. Search the source for a matching experimental origin: `{source}/packages/create-forge/experimental/*/source/skills/<name>/`.
-2. **No match** → genuinely local / removed-from-template. Report **removed from template** (don't delete) as before. Done.
-3. **Match found** → it is an experimental skill with a known upstream. Diff each markdown file in the installed dir against the source dir (`SKILL.md` and any siblings, e.g. `bootstrap-checks.md`):
-   - **All identical** → report `{name}: experimental, unchanged`.
-   - **Differs** → report `{name}: experimental, STALE (pinned at install; source has changes)` and **offer** a re-sync with the same preview/confirm UX as base skills:
-
-     ```
-     {name} is an experimental skill (from experimental/{pkg}/) pinned at install time.
-     The release ships newer content. Files that differ: {list}.
-     Re-sync from experimental/{pkg}/source? (yes / show diff / no)
-     ```
-
-     - **yes** → overwrite the installed skill's markdown files from source; report **updated (experimental)**.
-     - **show diff** → display the diff(s), then re-ask.
-     - **no** → leave untouched; note in the report that it stays pinned.
+### 2. Run the engine
 
-**Default is non-destructive** — never overwrite an experimental skill without an explicit `yes`. **Scope:** this pass re-syncs the skill's **markdown** (the behavior-bearing prose). It does **not** touch the experimental package's hooks, MCP server, or `settings.json`/`.mcp.json` wiring — those are owned by the package's own installer. When a re-sync lands, add one line: *"Hooks / MCP server for {pkg} are not re-synced here — re-run `experimental/{pkg}/install.sh` if the release changed them."*
+One Bash invocation:
 
-## Step 4: Sync Template-Only Files
-
-Same process as Step 3 for `.forge/templates/**`, `.forge/migrations/**`, and `.forge/adapters/**`. (Matches the npm bin's template-only dirs — keeps migration guides installed so the Step 7 pointers resolve via the in-Claude sync route, not just `npx forge-orkes upgrade`. `.forge/adapters/**` ships the platform-adapter generation protocols, e.g. `codex-generation.md`, so the Step 4b Codex step can hand it to `quick-tasking`.)
-
-**Also sync the forge gitignore:** the source ships it as `.forge/gitignore` (npm strips files literally named `.gitignore` from a published tarball). Copy/refresh the source's `.forge/gitignore` into the project as `.forge/.gitignore` (overwrite — it is framework-owned). Report added/updated/unchanged like any template-only file.
-
-**Sync the framework prose file `.forge/FORGE.md`** (framework-owned single file — it holds the `# Forge` prose, formerly embedded in CLAUDE.md). Copy/refresh `{source}/packages/create-forge/template/.forge/FORGE.md` → `.forge/FORGE.md` (overwrite when different; report added/updated/unchanged). **Run this BEFORE the Step 5 CLAUDE.md pass** so a migrated import line never points at a missing file.
-
-## Step 4a: Sync Hooks + Rules + Checks (additive — mirrors the npm bin)
+```bash
+npx forge-orkes@latest upgrade --yes --json
+# pinned: npx forge-orkes@{version} upgrade --yes --json
+```
 
-The template ships the safety-guardrail hook scripts (ADR-017), the always-on rules layer (ADR-018), and — since 0.58.2 — the merge-floor CI check scripts: `.claude/hooks/**` — **including the `tests/` subtree** — `.claude/rules/**`, and `.forge/checks/**` (incl. `tests/`). The npm bin has additively synced hooks + rules since those ADRs landed (`upgradeAdditiveDir`); this skill previously synced neither, so a project upgraded only via `/upgrading` never received `.claude/hooks/` at all — while its settings.json wires guards like `protect-files.sh` and skills invoke `forge-release-fold.sh`, none of which existed on disk.
+- stdout is exactly ONE JSON document; stderr is human prose — ignore it.
+- `--yes` auto-confirms stale-framework-file removal ONLY; it never bypasses the downgrade guard.
+- **Non-zero exit** → the bin refused or failed and still emitted `{error, reason}` on stdout. Surface the reason and **STOP**. The downgrade-guard refusal names `--force`; that stays a human decision — never re-run with `--force` yourself.
 
-For every file under `{source}/packages/create-forge/template/.claude/hooks/`, `.../.claude/rules/`, and `.../.forge/checks/` (recursive):
+### 3. Parse the JSON
 
-1. Absent locally → copy, report **added**.
-2. Present but differs → overwrite, report **updated**.
-3. Identical → report **unchanged**.
-4. **Additive only** — never delete a local file the template lacks. Project-local and experimental hooks (e.g. M10 `forge-claim-check*.sh`) and pack-installed path-scoped rules are preserved; no "removed from template" verdicts in this pass.
-5. `chmod +x` every synced `*.sh` (a copy can strip the execute bit; guard hooks and CI checks must be runnable).
+Top-level keys (all always present; `schemaVersion: 1`): `installedVersion` (pre-stamp; `"unknown"` if unstamped), `packageVersion`, `packageRoot` (the bin's own package dir — an npx cache path, valid at emit time only), `results` (`{updated, added, unchanged, removed, preserved}`, repo-relative paths), `claudeMd` (`created|migrated|appended|unchanged`), `settings` (`updated|unchanged|missing`), `experimental` (`[{name, pkg, status: unchanged|stale, files}]` — detection only; the bin never rewrites), `migrations` (`[{version, guide, reason}]` — applying guides only, pre-filtered), `codexAdapterPresent`, `worktrees` (`[{path, branch}]` — live `forge/m-*`).
 
-The two subtrees differ in tracked-ness, and the sync respects it: `.forge/checks/**` is **committed** project content (CI must clone it; the hold check's protected set guards `.forge/checks/**`), while `.claude/hooks/**` is a **machine-local carve-out** in many projects (gitignored as per-developer files — host-verified on ptnrkit). Sync both to disk identically; stage only what the project's own `.gitignore` admits — never `git add -f` a hook file past a project's ignore rules. The old `.claude/hooks/` copies of `forge-hold-check.sh` / `forge-check-lint.sh` (+ their two `tests/*.test.sh` suites) are relocation leftovers on upgraded projects — the migration guide `0.58.2-merge-floor-checks-relocation.md` covers removing them and re-pointing CI.
+`schemaVersion` ≠ 1 → warn (*"engine emitted schema {n}; this skill reads 1"*) and render best-effort — never silently misread.
 
-The settings.json *wiring* for these hooks is not written here — Step 5's smart-merge owns it.
+### 4. Render the report
 
-## Step 4b: Codex Adapter (presence-gated — detect + offer, never auto)
+From the JSON only — no re-scanning:
 
-Forge ships a **Codex/AGENTS adapter** (`.agents/skills/` + `.codex/` wiring) for projects run on Codex. It is a *derived translation* of the canonical `.claude/` skills (ADR-014) and drifts whenever core moves — but `upgrading` syncs only `.claude/`, so the Codex adapter would silently rot. This step makes that staleness visible and one-keystroke-fixable, **without** ever generating it here (only an agent-as-Codex can author it natively).
+```
+Forge Upgrade Complete (registry)
+─────────────────────────────────
+Source: npm registry — forge-orkes@{packageVersion}
+Version: {installedVersion} → {packageVersion}
+
+Updated / Added: listed from results
+Experimental skills: {N} (name, pkg, status)
+Codex adapter: present / not present   (layer c updates this line)
+Removed from template: {N} (removal confirmed via --yes)
+CLAUDE.md: {claudeMd}   (migrated/appended render as Migrated:/Restored:)
+Settings: {settings}
+Unchanged: {N} · Preserved: {N} (user-owned, never touched)
+```
 
-1. **Presence gate.** Glob the project root for `.agents/` and `.codex/`. **Neither exists → skip silently** — no prose, no prompt (Claude-only / greenfield projects are unaffected).
-2. **Either exists → report + offer.** The Codex adapter is present and may be stale relative to the `.claude/` source just synced in Steps 3–4. Offer regeneration:
-   ```
-   Codex adapter detected (.agents/ / .codex/). It may be stale vs the .claude/
-   source just synced. Regenerate it now? (yes / no)
-   ```
-   - **yes** → invoke `quick-tasking`, handing it `.forge/adapters/codex-generation.md` as the task definition (the **same delegation pattern as Step 7 migrations**). The protocol instructs an agent-as-Codex to author `.agents/` + `.codex/` from source using native primitives; a human reviews the diff before commit. `upgrading` itself **never** writes `.agents/` and never performs the translation.
-   - **no** → record `Codex adapter: stale, declined` for the Step 6 report.
-3. **Report line.** Add a `Codex adapter:` line to the Step 6 report — one of `regenerated` / `stale, declined` / `not present`.
+## Agent Layers (after the report — consent-gated, keyed to the JSON)
 
-Presence-gated, never auto-runs, regeneration is agent-run via `quick-tasking`. The protocol doc itself reaches the project via the Step 4 `.forge/adapters/**` sync.
+The engine changed; the conversation did not. Each layer consumes one JSON field and preserves the legacy consent UX exactly. Trust the JSON — never re-run detection the bin already did (no second worktree scan, no second migration Detection pass).
 
-## Step 5: Handle Import-Managed + Merge-Owned Files
+### a. Migrations — `migrations[]`
 
-**`CLAUDE.md` (import-managed — one-pass auto-migration, no prompt):** mirror the npm bin's `ensureClaudeMdImport()` case-for-case. The framework prose lives in `.forge/FORGE.md` (synced in Step 4) — never write prose into CLAUDE.md, and never modify user content outside a legacy forge section.
+For each entry in the migrations array `[{version, guide, reason}]` from the JSON, the uniform prompt:
 
-1. **No `CLAUDE.md`** → write the stub: one explanatory comment + the `@.forge/FORGE.md` import line. Report **created**.
-2. **Legacy `<!-- forge:start -->` / `<!-- forge:end -->` markers present** → replace the marker section *in place* with the `@.forge/FORGE.md` import line (position preserved), collapsing blank-line runs only at the two seams — never globally. Report **migrated**.
-3. **No markers, but a legacy `# Forge` header** (old installs appended prose to EOF) → strip from the header to end-of-file, append the import line. Report **migrated**.
-4. **Import line already present** (tolerating trailing whitespace / CRLF) → leave untouched. Report **unchanged**.
-5. **User-authored CLAUDE.md, no forge content, no import line** → append the comment + import line at EOF. Report **restored** (the import-line guarantee — Forge always loads its context).
+```
+{version} migration available — {reason}
+Guide: {guide}
+Migrate now? (yes/no/show guide)
+```
 
-No manual-merge prompt for forge sections; migration is silent except the report line. User content outside the forge section is never modified, and the import line is never duplicated.
+- **yes** → invoke `quick-tasking`, handing it the guide path as the task definition. Migrations are never applied inline by upgrading; lossy steps are confirmed inside quick-tasking.
+- **show guide** → display the guide, re-ask.
+- **no** → note in the report (split-brain until migrated — recommend before the next planning/review cycle).
 
-**`.claude/settings.json`:**
-1. Read source and local versions
-2. Compare `forge.*` keys only
-3. If different → update `forge.*` keys in local, preserve user's `hooks` and custom keys
-4. Set `forge.version` to match the source package version
-5. **Additively merge the template's framework hook wiring** (ADR-017, mirrors the bin's `upgradeSettingsHooks`): for each hook group in the template's `hooks`, add it to the local `hooks` unless a deep-equal group already exists. Never remove or rewrite a user's own hook entries. Without this, the scripts synced in Step 4a exist on disk but never fire on projects whose settings.json predates the wiring.
+### b. Experimental re-sync — `experimental[]`
 
-## Step 6: Report
+For each entry with `status: stale` (detection is bin-side; the bin never rewrites experimental skills):
 
 ```
-Forge Local Sync Complete
-─────────────────────────
-Source: {path}
-Version: {old} → {new}
+{name} is an experimental skill (from experimental/{pkg}/) pinned at install time.
+The release ships newer content. Files that differ: {files}.
+Re-sync from the release package? (yes / show diff / no)
+```
 
-Updated: {N} files
-  - .claude/skills/executing/SKILL.md
-  - ...
+- Source path: `{packageRoot}/experimental/{pkg}/source/skills/{name}/` from the JSON. `packageRoot` is an npx cache path valid at emit time — use it immediately in this session; absent/invalid → fall back to offering `experimental/{pkg}/install.sh` guidance.
+- **yes** → overwrite the installed skill's **markdown** files only (hooks, MCP server, settings/`.mcp.json` wiring stay owned by the package installer). Report *updated (experimental)* and add: *"Hooks / MCP server for {pkg} are not re-synced here — re-run `experimental/{pkg}/install.sh` if the release changed them."*
+- **show diff** → display, re-ask. **no** → stays pinned; note it.
 
-Added: {N} files
-  - .claude/skills/new-skill/SKILL.md
-  - ...
+### c. Codex adapter — `codexAdapterPresent`
 
-Experimental skills: {N}
-  - orchestrating (from experimental/m10) — updated  [or: unchanged / STALE, declined]
-  - ...
+`false` → skip silently. `true` → the adapter may be stale vs the `.claude/` source the bin just upgraded — offer regeneration (never auto; upgrading never writes `.agents/`):
 
-Codex adapter: regenerated   [or: stale, declined / not present]
+```
+Codex adapter detected (.agents/ / .codex/). It may be stale vs the .claude/ source just upgraded.
+Regenerate it now? (yes / no)
+```
 
-Removed from template: {N} files
-  - .claude/agents/old-agent.md (still in your project)
-  - ...
+- **yes** → invoke `quick-tasking`, handing it `.forge/adapters/codex-generation.md` as the task definition (an agent-as-Codex authors the adapter natively; a human reviews the diff before commit).
+- **no** → report line `Codex adapter: stale, declined`.
 
-Migrated: {N} files
-  - CLAUDE.md (forge section extracted to .forge/FORGE.md — @import)
+### d. Worktree propagation — `worktrees[]`
 
-Restored: {N} files
-  - CLAUDE.md (@.forge/FORGE.md import line re-appended)
+Non-empty → the upgrade landed in this checkout only; each live worktree keeps its branch-point framework files until it rebases. **Commit the upgrade first** — a worktree can only rebase onto committed history; if the sync is uncommitted, prompt (*"Commit this upgrade before propagating? e.g. `chore(forge): upgrade to v{packageVersion}`"*) and wait. Then offer — never auto (a rebase can conflict and needs human judgment):
 
-Unchanged: {N} files
 ```
+{N} live worktree(s) lag this upgrade (v{installedVersion} → v{packageVersion}):
+  - {path} ({branch})
+Pick up v{packageVersion} in each:  git -C {path} rebase main
+Rebase now? (each / list-only / skip)
+```
+
+- **each** → run `git -C {path} rebase main` per worktree; on conflict, stop that one, report it, move on — never force, never auto-resolve.
+- **list-only / skip** → print the commands; the operator runs them at a safe stopping point.
+- Gitignored carve-outs (`.mcp.json`, experimental hooks) are not carried by a rebase — whenever layer (b) re-synced anything, add: each worktree must re-run `experimental/{pkg}/install.sh`.
 
-The `Migrated:` line appears only when a legacy marker/`# Forge` section was extracted this run; `Restored:` only when a missing import line was re-appended. A steady-state upgrade lists `CLAUDE.md` under Unchanged.
+## Dev Mode (`/upgrading dev` — explicit only)
 
-## Step 7: Post-Upgrade Migration Checks (data-driven)
+Local-clone sync for developing Forge itself: test framework changes in a project without publishing to npm. Presence of `.forge/dev-source` NEVER selects this mode — only the explicit `dev` argument does.
 
-After sync completes, detect legacy file layouts the new framework version no longer writes but may still read in compatibility mode. This is **data-driven** — it loops over the migration guides synced in Step 4 and runs each guide's `## Detection` block. There are **no per-version blocks here**: a new guide that ships in the template (with a conformant Detection block — see `.forge/templates/migration-guide.md`) is auto-covered on the next upgrade with no edit to this skill.
+### Source resolution
 
-For each guide that signals it applies, surface a migration prompt — **never auto-migrate**.
+`.forge/dev-source` exists → read the path (first line, trimmed) and confirm it contains `packages/create-forge/template/`. Missing → ask for the local Forge repo path, validate it, save to `.forge/dev-source`.
 
-### The loop
+### Harvest upstream desire paths (advisory)
 
-1. **`installed`** = the project's `.claude/settings.json` `forge.version`, **captured at the START of this upgrade run, BEFORE Step 5 stamps the new version**. If absent/unknown, treat `installed` as `0.0.0` (all guides in range). Do **not** read the *source template's* `settings.json` literal — it carries a placeholder the installer stamps at write time, not the real version.
-2. **`source`** = `{source}/packages/create-forge/package.json` `version`. This is the authoritative new version. (Again: never the template `settings.json` literal.)
-3. Glob the just-synced guides: `.forge/migrations/{v}-*.md`. Parse `{v}` (the leading `MAJOR.MINOR.PATCH`) from each filename. Select guides where **`installed < v <= source`** (semver compare on dotted numerics).
-4. For each selected guide, ascending by version: run its `## Detection` fenced bash block from the project root (via the Bash tool, under `bash`). 
-   - stdout contains **`MIGRATE`** → the migration applies; surface the prompt (below). The text after `MIGRATE —` is the reason; show it.
-   - prints nothing / no `MIGRATE` → **no-op**; report `{v}: no action` and move on.
-   - the block errors → report `{v}: detection error (skipped)`; do **not** abort the loop.
+Dev mode is the one route that bridges this project and a local Forge clone, so it harvests framework-scope desire paths (ADR-012): glob `.forge/state/desire-paths/upstream/*.md`; none → skip silently. Any present → offer to copy each into `{source}/docs/desire-paths-inbox/` (create if missing); on copy, move the project-side block to `.forge/state/desire-paths/upstream/harvested/` so it isn't re-offered. Convenience tier only — the GH issue offered at capture time remains the primary channel. Never blocks the sync.
 
-### The prompt (uniform across guides)
+### Downgrade guard
 
-For each applying guide:
+Source version (`{source}/packages/create-forge/package.json`) **<** installed (`.claude/settings.json` `forge.version`) → **STOP**: *"Refusing to downgrade: installed v{installed} is newer than source v{source}. Point dev-source at a newer checkout, or confirm an intentional downgrade."* Proceed only on explicit user override — rolling backward overwrites newer framework files and deletes files newer versions added, and with `.claude/` often gitignored that is unrecoverable.
 
-```
-{v} migration available — {reason from the MIGRATE line, or the guide title}
-Guide: .forge/migrations/{v}-{slug}.md
-       (canonical: https://github.com/Attuned-Media/forge/blob/main/docs/migrations/{v}-{slug}.md)
+### Local sync
 
-Migrate now? (yes/no/show guide)
-```
+Dev mode syncs from a checkout, so it keeps file-classification semantics — **the npm bin's sync behavior is the spec**; do not re-derive it here. Categories:
 
-- **yes** → invoke the `quick-tasking` skill, handing it the guide path as the task definition. `upgrading` never edits user state / project files / `.gitignore` directly — every migration runs via `quick-tasking`, and any lossy step (e.g. narrative extraction, staging files) is confirmed with the user first.
-- **show guide** → read and display the guide file, then re-ask.
-- **no** → note in the upgrade report. The new skills compose new-shape paths on write while legacy files persist on disk (split-brain) until migrated; recommend running it before the next planning/review cycle.
+- **Framework-owned** (`.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.forge/FORGE.md`) → overwrite when different; a local skill dir absent from the template defers to the experimental pass below (only no-source dirs report *removed from template* — never deleted).
+- **Template-only** (`.forge/templates/**`, `.forge/migrations/**`, `.forge/adapters/**`, `.forge/gitignore` → `.forge/.gitignore`) → overwrite; `.forge/FORGE.md` lands BEFORE the CLAUDE.md pass.
+- **Additive** (`.claude/hooks/**` incl. `tests/`, `.claude/rules/**`, `.forge/checks/**`) → add + overwrite template-shipped files, never delete local extras, `chmod +x` synced `*.sh`.
+- **Import-managed** `CLAUDE.md` → the bin's `ensureClaudeMdImport()` cases verbatim; user content outside a forge section is never modified.
+- **Merge-owned** `.claude/settings.json` → `forge.*` keys + additive hook-group wiring only; stamp `forge.version` last.
+- **Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements/`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
 
-### Why there is no bookkeeping
+Render the same report shape as the default path, with `Source: {path}` instead of the registry line.
 
-Recording "crossed" guides is implicit in the range. Once Step 5 stamps `forge.version` to `source`, a later run's range `(new installed, source]` excludes every guide already crossed — so nothing re-detects, with **no ledger or marker file**. The range also closes the install-run blind spot: detection keys off the guides **freshly synced this run** (Step 4) plus the **pre-stamp installed version**, so the run that installs new detection behavior uses the new guides, not this skill's own pre-sync prose.
+### Post-sync layers
 
-## Step 8: Propagate to Live Worktrees (offer, never auto)
+Re-use layers (a)–(d) with dev-derived inputs — this is the one mode that computes them itself, since there is no engine JSON:
 
-The sync lands framework files (`.claude/skills/`, `.claude/agents/`, `.forge/FORGE.md`, templates) in **this checkout only**. A live Forge worktree keeps running its branch-point copies until it pulls main in — and nothing else surfaces this: the integration flag (`.git/forge/integration-pending`) fires only on a verified **work** checkpoint, never on an upgrade, and `forge.worktree_rebase_check` is opt-in. So close the loop here, where the upgrade actually happened.
+- **(a) Migrations** — the data-driven Detection loop: select freshly-synced guides `.forge/migrations/{v}-*.md` where `installed < v <= source` (semver on the PRE-stamp installed version), run each guide's `## Detection` bash block from the project root; `MIGRATE` on stdout → the layer-(a) prompt with the text after `MIGRATE —` as the reason; no output → `{v}: no action`; block errors → `{v}: detection error (skipped)`, never abort the loop. Range bookkeeping is implicit: once `forge.version` is stamped, crossed guides fall out of the next run's range — no ledger.
+- **(b) Experimental staleness** — diff installed non-template skill dirs against `{source}/packages/create-forge/experimental/*/source/skills/{name}/`; stale → the layer-(b) offer with `{source}` as the source path.
+- **(c) Codex** — presence glob (`.agents/` / `.codex/`) → the layer-(c) offer.
+- **(d) Worktrees** — `git worktree list --porcelain` filtered to `refs/heads/forge/m-*`, main checkout only (`git rev-parse --git-dir` == `--git-common-dir`; from a worktree, skip and say so) → the layer-(d) offer.
 
-1. **Main checkout only.** `git rev-parse --git-dir` == `--git-common-dir` → main; differ → this session **is** a worktree, so skip (run `/upgrading` from main to propagate). No remote/not a git repo → skip.
-2. **Commit the sync first** — a worktree can only rebase onto committed history, so uncommitted synced files won't propagate. If the sync is unstaged, prompt: *"Commit this upgrade on main before propagating? (e.g. `chore(forge): upgrade to v{new}`)"* and wait.
-3. **Enumerate live worktrees:** `git worktree list --porcelain`, branches matching `refs/heads/forge/m-*` (same scan as the `forge` boot preflight). None → done, silent.
-4. **Offer — never auto** (a rebase can conflict and needs human judgment):
-   ```
-   {N} live worktree(s) lag this upgrade (v{old} → v{new}):
-     - {path} ({branch})
-   Pick up v{new} in each:  git -C {path} rebase main
-   Rebase now? (each / list-only / skip)
-   ```
-   - **each** → run `git -C {path} rebase main` per worktree; on conflict, **stop that one**, report it, and move on — never force, never auto-resolve.
-   - **list-only / skip** → print the commands; the operator runs them when each worktree is at a safe stopping point.
-5. **Gitignored carve-outs don't rebase.** `.mcp.json`, experimental hooks (e.g. M10 `forge-claim-check*.sh`), and anything else gitignored is **not** carried by a rebase. If the upgrade changed them (e.g. an experimental skill was re-synced in Step 3b), each worktree must re-run the experimental installer (`experimental/{pkg}/install.sh`) — a rebase alone leaves them stale. Surface this line whenever Step 3b reported an experimental re-sync.
+Same consent gates, same report lines as the registry path.

package/template/.forge/FORGE.md

@@ -104,7 +104,7 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | Security review | `securing` | When auth/data/API |
 | E2E/integration tests + suite audit (+ M9 author-mode gate) | `testing` | When UI/flows or flaky suite |
 | Systematic debugging | `debugging` | When stuck |
-| Upgrade Forge files | `upgrading` | On-demand |
+| Upgrade Forge files from the npm registry (default; local dev sync only via explicit `/upgrading dev`) | `upgrading` | On-demand |
 | Cross-session memory | `beads-integration` | When Beads installed |
 | Project/read Forge work in Notion | `notion-integration` | When Notion configured |
 | Multi-agent backend (experimental) | `orchestrating` | Optional, usually selected by Chief/Streams |
@@ -239,7 +239,7 @@ git commit -m "chore(forge): sync state after {phase} — m{N} {phase-name}"
 | **Append-only shared** | `releases.yml`, `reservations.yml`, `state/desire-paths/*`, `deferred-issues/*` | Many writers OK; structure prevents collision (append-only entries / distinct filenames). |
 | **Machine-local runtime** | `.git/forge/id-reservations`, `.git/forge/integration-pending` | Git common dir — shared across a machine's worktrees, never git-tracked, excluded from framework context. |
 | **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` | Write only your milestone/stream block; within a block, append-only — strike through instead of rewriting. |
-| **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md`, `.claude/skills/`, `.claude/agents/` | Rarely changes except via `/upgrading`. Canonical on main; worktrees lag until they rebase. An upgrade touches only its own checkout — `upgrading` Step 8 offers live-worktree rebases (never auto); opt-in `forge.worktree_rebase_check` is the boot-time net. Gitignored carve-outs (`.mcp.json`, experimental hooks) propagate via the experimental installer, not git. |
+| **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md`, `.claude/skills/`, `.claude/agents/` | Rarely changes except via `/upgrading` (registry default — the npm bin is the sync engine; local dev sync only via explicit `/upgrading dev`). Canonical on main; worktrees lag until they rebase. An upgrade touches only its own checkout — `upgrading` Step 8 offers live-worktree rebases (never auto); opt-in `forge.worktree_rebase_check` is the boot-time net. Gitignored carve-outs (`.mcp.json`, experimental hooks) propagate via the experimental installer, not git. |
 
 Ownership rules (quick reference):
 

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"
+```