forge-orkes 0.32.0 → 0.34.0

package/bin/create-forge.js

@@ -37,6 +37,16 @@ const FRAMEWORK_OWNED_DIRS = ['.claude/agents', '.claude/skills'];
 // Experimental / opt-in skills installed separately (e.g. from experimental/m10).
 // They are NOT in the shipped base template, so the framework-owned auto-clean
 // would otherwise delete them on upgrade. Preserve them instead.
+//
+// The npm tarball ships only bin/ + template/ — NOT experimental/ — so this route
+// cannot diff or re-sync an experimental skill against its source. Preserving
+// blindly is what silently froze them pre-0.33.0 (issue #5): a base migration that
+// changed experimental-skill behavior became a no-op. The structural fix lives
+// elsewhere — (a) the clone-based `upgrading` skill (Step 3b) offers a real
+// re-sync against experimental/*/source, and (b) load-bearing conventions are
+// promoted to base (FORGE.md) so they no longer depend on the frozen skill. Here
+// we can only PRESERVE + flag, so the report below tells the user staleness was
+// not checked and how to refresh.
 const EXPERIMENTAL_SKILL_PATHS = ['.claude/skills/orchestrating'];
 
 function isExperimentalSkillPath(displayPath) {
@@ -623,8 +633,17 @@ async function upgrade() {
   if (results.preserved.length > 0) {
     console.log(`  Preserved (${results.preserved.length}):`);
     for (const f of results.preserved) {
-      console.log(`    ${f} (kept — opt-in experimental skill)`);
+      console.log(`    ${f} (kept — opt-in experimental skill; staleness not checked by npm)`);
     }
+    console.log(
+      `    ↳ The npm upgrade does not ship experimental sources, so it cannot`
+    );
+    console.log(
+      `      re-sync these. To refresh against a Forge clone, run the \`upgrading\``
+    );
+    console.log(
+      `      skill (offers a re-sync), or re-run \`experimental/<pkg>/install.sh\`.`
+    );
     console.log();
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/skills/chief-of-staff/SKILL.md

@@ -56,17 +56,55 @@ packages, plans, verification reports, commits, and archived artifacts.
 
 | Intent | Examples | Action |
 |--------|----------|--------|
-| Show | "show streams", "active streams", "what is running?" | Summarize registry without loading all deep history |
+| Show | "show streams", "active streams", "what is running?" | Run Registry Drift Check, then summarize registry without loading all deep history |
 | Start | "start stream X", "new stream for billing" | Snapshot current stream, create stream files, register stream |
 | Pause | "pause stream X" | Update brief, mark paused, keep next action explicit |
 | Resume | "resume stream X" | Load stream context, set active, surface blockers and ownership |
 | Delegate | "delegate stream X", "farm this out" | Create or update a work package and handoff prompt |
 | Adopt M10 | "adopt existing M10 worktrees", "migrate active orchestrating sessions" | Wrap live M10 worktrees as streams without teardown |
-| Sync | "sync streams" | Refresh registry summaries from active stream briefs |
+| Sync | "sync streams" | Run Registry Drift Check, then refresh registry summaries from active stream briefs |
 | Detect Conflicts | "detect conflicts", "check stream conflicts" | Compare ownership and dependencies |
 | Merge Safe | "merge safe?", "what can land?" | Identify ready streams with no blocking conflicts |
 | Close | "close stream X" | Record final status, archive/mark closed, clear active pointer if needed |
 
+## Registry Drift Check
+
+Forge keeps two registries that both describe "what work is active," with no
+automatic reconciliation: `.forge/state/index.yml` (milestones, owned by the
+`forge` skill) and `.forge/streams/active.yml` (streams, owned by the Chief).
+`/forge` and `/chief-of-staff` can therefore present different pictures of the
+project. Run this check at the **start of the Show and Sync intents** so the
+divergence is surfaced instead of silently left to the operator.
+
+This is **advisory — it never blocks, never auto-creates a milestone, and never
+auto-writes a stream.** It reports, and offers.
+
+1. Read active milestones from `.forge/state/index.yml` (those with
+   `status: active`). If the file is absent, skip the check silently — a
+   streams-only project has nothing to reconcile.
+   - Note: invoking `/chief-of-staff` directly bypasses `forge`'s boot preflight,
+     so `index.yml` may be stale (it is regenerated by `forge`'s Rollup, not by
+     the Chief). Read it as-is; do not run Rollup from the Chief. If it looks
+     stale, say so and suggest a `/forge` pass.
+2. Read the stream registry from `.forge/streams/active.yml`.
+3. Map each active milestone to a stream by id, trying these forms in order:
+   `m-{id}`, `milestone-{id}`, bare `{id}`, and any stream whose
+   `context.milestone` points at `.forge/state/milestone-{id}.yml`.
+4. Report each mismatch:
+   - **Active milestone with no stream** → offer to add it as a `paused` stream
+     (do not create it automatically). Quick-fix milestones legitimately may not
+     warrant a stream — let the operator decide.
+   - **Stream pointing at a `deferred`, `complete`, or absent milestone** → the
+     stream's status should follow its milestone; offer to update it (pause a
+     stream whose milestone deferred, close one whose milestone completed).
+   - **Stream with no milestone counterpart** → informational only. Quick-fix
+     streams are valid; never auto-create a milestone for them.
+5. If everything maps cleanly, say so in one line (`registries aligned`) and
+   continue to the intent.
+
+Keep the output compact — a few lines under a `Registry drift:` header, then
+proceed with the requested Show/Sync.
+
 ## Start Stream Flow
 
 1. Read the registry.
@@ -119,7 +157,12 @@ existing M10 state.
 6. Populate the stream file:
    - `stream.id`, `goal`, `status`, `tier`
    - `runtime.branch` from `lifecycle.worktree_branch`
-   - `runtime.worktree` from `lifecycle.worktree_path`
+   - `runtime.worktree` from `lifecycle.worktree_path`. **If no path was
+     recorded** (a manual `git worktree add`, or pre-convention state), resolve
+     it from the base **Worktree Convention** in `FORGE.md` —
+     `{orchestration.worktree_root or ../<repo>-worktrees}/{anchor}` — rather
+     than assuming the experimental `orchestrating` skill's internal default.
+     Confirm the resolved path with `git worktree list` before recording it.
    - `runtime.worker_sessions` with the M10 session / claim ids
    - `ownership.owned_surfaces`, `shared_surfaces`, and `read_only_surfaces`
      as empty lists if unknown

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

@@ -28,8 +28,8 @@ git worktree list --porcelain 2>/dev/null \
 ```
 
 **If `in_main_checkout: true`** AND any Forge worktrees are reported:
-- Surface them at the top of the boot output, one line each: *"m{id} is live in worktree `{path}` on branch `{branch}`. Edits to its milestone state belong there; shared-doc edits here (`context.md`, `refactor-backlog.yml`) won't be visible to it until it rebases or pulls."*
-- This is informational — `forge` continues to Rollup + selection. The operator now knows. (See FORGE.md State Ownership for the full taxonomy.)
+- Surface them at the top of the boot output, one line each: *"m{id} is live in worktree `{path}` on branch `{branch}`. Its milestone state is **owned there** — selecting it from main triggers the Live-Worktree Ownership Gate (1.1a). Shared-doc edits here (`context.md`, `refactor-backlog.yml`) won't be visible to it until it rebases or pulls."*
+- Surfacing continues to Rollup + selection — but it is **no longer purely informational**. Enforcement is deferred to **1.1a**, which fires only for the *selected* milestone (booting from main to work an unrelated milestone stays free). Record which worktrees were reported here so 1.1a can match the selection against them. (See FORGE.md State Ownership for the full taxonomy.)
 
 **If `in_main_checkout: false`** (this session is itself a worktree) AND `forge.worktree_rebase_check: true` in `.forge/project.yml` (default `false` — opt-in):
 - Diff `.forge/` between this worktree's `HEAD` and `origin/main` (or `main` if no remote), restricted to the **shared-mutable** + **stable-shared** files per the FORGE.md taxonomy (`context.md`, `refactor-backlog.yml`, `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `requirements/m{N}.yml`).
@@ -74,7 +74,7 @@ Check state files:
 4. **Multiple (no arg, no anchor):** Show active + not_started milestones with status + `last_updated`. Default most recent. After main list, show **Deferred:** section (id, name, frozen status `was: {current.status}`, defer date, reason). *"{N} active. Most recent: [{name}] ({current.status}, {date}). This one, or switch?"*
 5. **One:** Auto-select. *"Resuming: [{name}] -- {current.status}, {percent}%"*
 6. **None active:** If deferred exist, mention them: *"No active milestones. {N} deferred — 'resume milestone {id}' to reactivate."* Else → init or create.
-7. Load `milestone-{id}.yml`
+7. Load `milestone-{id}.yml`, then run the **Live-Worktree Ownership Gate (1.1a)** — it can block routing before any milestone-owned write.
 8. **Route on `current.status`, NOT `{percent}`.** Complete only at `complete`. 100% phases ≠ done -- verifying + reviewing must run.
 9. Report + **immediately route** (Step 3). Show: `current.status`, phase labels (Executed/Verified/Pending/In progress -- **never "Complete" for unverified**), `{percent}`. **No menus.** Position → action → invoke.
 
@@ -89,6 +89,35 @@ Beads enabled (`forge.beads_integration: true`) → `bd prime`. Optional.
 
 Read `.forge/context.md`. **Needs Resolution** unchecked → warn: *"{N} unresolved discrepancies."* Quick proceeds; Standard/Full blocked at planning.
 
+### 1.1a Live-Worktree Ownership Gate (enforced)
+
+Single-owner-mutable state must be written by exactly one checkout. When this session is on **main** and the **selected** milestone has a **live worktree**, writing its state from here forks the cursor — main records one `current.status`, the worktree another, and a later resume anchored to the worktree silently contradicts main's claim. FORGE.md State Ownership forbids this; this gate is where the entrypoint **enforces** it, before routing to any skill that writes milestone-owned files. (See FORGE.md → State Ownership.)
+
+**Trigger.** `in_main_checkout: true` (from the Step 1 preflight) **AND** the selected milestone has a live worktree — any of:
+- the preflight's `git worktree list` reported a `forge/m-{id}-*` / `forge/{id}` branch for this milestone; or
+- `milestone-{id}.yml` `lifecycle.worktree_mode` is `active` or `degraded` and a `lifecycle.worktree_path` is recorded; or
+- `.forge/streams/active.yml` shows a stream for this milestone with a `runtime.worktree`.
+
+Resolve the worktree path from the recorded `lifecycle.worktree_path` / `runtime.worktree`, or — if absent — from the base **Worktree Convention** (FORGE.md).
+
+**When it does NOT trigger** (no-op — continue to routing): no live worktree for the selected milestone; or this session **is** the owning worktree (`in_main_checkout: false` and the branch anchors to this milestone); or the milestone has a recorded, still-current `lifecycle.ownership_override` (see option 4).
+
+**When it triggers — STOP. Do not route** to `planning`, `executing`, `verifying`, `reviewing`, `quick-tasking` against this milestone, and do not write any of:
+- `.forge/state/milestone-{id}.yml`
+- `.forge/phases/milestone-{id}/`
+- `.forge/research/milestone-{id}.md`
+
+Present the four resolutions and wait for an explicit choice:
+
+1. **Enter the worktree** *(recommended)* — print the exact command (`cd {worktree_path}` then `/forge`); re-running there anchors to this milestone and writes land in the owner. This session does nothing further to the milestone.
+2. **Sync, then continue in the worktree** — bring main's commits in (`git -C {worktree_path} rebase main`, or merge), then work from the worktree. Use when main has changes the worktree needs first.
+3. **Retire the worktree** — only if it is dead/superseded. Close the stream, `git worktree remove {worktree_path}`, and clear `lifecycle.worktree_*` on the milestone — which ends its ownership so main may write. **Confirm before removing; never auto-remove a worktree.**
+4. **Recorded override** — deliberately write from main anyway. Write `lifecycle.ownership_override: {at: {ISO}, from: main, reason: "{operator's reason}"}` into `milestone-{id}.yml`, echo it in the boot line, and carry it into the next `reviewing` report. This is the **only** way past the block and it is **never silent**. (An override is scoped to this milestone; clear it once the worktree is retired or synced.)
+
+**Shared project docs** (`context.md`, `refactor-backlog.yml`, `project.yml`, `constitution.md`, `roadmap.yml`, `requirements/m{N}.yml`) stay writable from main even when the gate is up — but warn they won't be visible to the live worktree until it pulls/rebases (same note as the preflight).
+
+An agent must never present "override" as a peer default. Lead with option 1; reach for 4 only on the operator's explicit instruction with a reason.
+
 ### 1.2 Backlog + Desire Paths
 
 Check `.forge/refactor-backlog.yml`:

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

@@ -43,7 +43,7 @@ Read the source version (`{source}/packages/create-forge/package.json` `version`
 
 **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`.
 
-**Preserve experimental skills.** Opt-in skills installed separately (e.g. `.claude/skills/orchestrating/` from `experimental/m10/`) are not in the base template. Never flag them as "removed from template" or delete them — leave them untouched.
+**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
 
@@ -53,7 +53,31 @@ For each framework-owned file in the source template:
 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 → report **removed from template** (don't delete -- let user decide)
+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.
+
+**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."*
 
 ## Step 4: Sync Template-Only Files
 
@@ -97,6 +121,10 @@ Added: {N} files
   - .claude/skills/new-skill/SKILL.md
   - ...
 
+Experimental skills: {N}
+  - orchestrating (from experimental/m10) — updated  [or: unchanged / STALE, declined]
+  - ...
+
 Removed from template: {N} files
   - .claude/agents/old-agent.md (still in your project)
   - ...

package/template/.forge/FORGE.md

@@ -37,6 +37,21 @@ Forge has three runtime coordination layers: Project, Stream, and Work Package.
 
 Use ordinary Quick/Standard/Full tiers inside a stream. Use Project Chief / Chief of Staff when coordinating multiple active streams or pivoting without dropping context. Workers never coordinate laterally; they report to the stream or project chief. M10 worktrees remain an optional backend for isolation/merge discipline, not the primary UX.
 
+### Worktree Convention (base)
+
+Worktrees are a **base concern** — Chief/Streams creates and references them with plain `git worktree`, independent of the experimental `orchestrating` skill. This convention is the single source of truth for *where worktrees live and what they're named*, so it lives here in base (not buried in an experimental skill) and stays upgrade-synced for every install (see [ADR-010](../docs/decisions/ADR-010-repo-scoped-worktree-root.md)).
+
+| Element | Convention |
+|---|---|
+| **Root** | `orchestration.worktree_root` from `project.yml`; if unset, default `../<repo-basename>-worktrees/`. Relative paths resolve against the **repo root** (not shell cwd); absolute and leading-`~` paths are honored verbatim. Per-repo sibling dirs keep each repo's worktrees from pooling into one shared dir. |
+| **Anchor** | `{milestone-id}-{session}` (e.g. `m-9-a1b2c3d4`). For a manual stream worktree with no session, the milestone/stream id alone is acceptable (`m-PLUG01`). |
+| **Path** | `{worktree_root}/{anchor}` — the resolved **absolute** path. |
+| **Branch** | `forge/{anchor}`. |
+
+**Recorded path is authoritative once set.** When a worktree is created through `orchestrating`, the resolved absolute path is recorded in `lifecycle.worktree_path` (in `state/milestone-{id}.yml`) or in a stream's `runtime.worktree`, and every later operation reads it verbatim — never re-derives. Changing `orchestration.worktree_root` later only affects **new** worktrees; live ones keep working off their recorded path. Move a live worktree only with `git worktree move` (a bare `mv` strips the gitdir pointer), then update the recorded path.
+
+**Fallback when no path was recorded.** A worktree created outside `orchestrating` (a manual `git worktree add`, an adopted stream) may have no recorded path. Resolve it from this convention — `{worktree_root}/{anchor}` — rather than assuming the experimental skill's internal default. Chief/Streams uses this fallback; `orchestrating` (when installed) implements the same scheme for the worktrees it creates.
+
 ## Workflow Tiers
 
 Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
@@ -217,14 +232,18 @@ with the work it describes. Every artifact has a sharing class:
 | **Stable shared** | `project.yml`, `constitution.md`, `design-system.md`, `roadmap.yml`, `FORGE.md` | Rarely changes after init. Canonical on main. Worktrees lag and pull on rebase. No special protocol — git handles it because the conflict surface is tiny. |
 
 Cross-tree edits land on the current branch and are invisible to other worktrees
-until they pull/rebase. `forge` surfaces live worktrees at boot; `discussing`
-and `reviewing` warn before touching shared-mutable blocks; optional
-`forge.worktree_rebase_check` detects stale shared files inside worktrees. See
+until they pull/rebase. `forge` surfaces live worktrees at boot **and enforces
+the Live-Worktree Ownership Gate** (forge SKILL 1.1a): when invoked from main for
+a milestone that has a live worktree, milestone-owned writes are **blocked**
+until the operator enters the worktree, syncs it, retires it, or records an
+explicit `lifecycle.ownership_override`. `discussing` and `reviewing` warn before
+touching shared-mutable blocks; optional `forge.worktree_rebase_check` detects
+stale shared files inside worktrees. See
 [ADR-011](../docs/decisions/ADR-011-shared-state-taxonomy.md) for rationale.
 
 ### State Ownership rules (quick reference)
 
-- `state/milestone-{id}.yml` is the **single source of truth**; exactly one agent owns it at a time. **Other worktrees never write it** — promoted from advice to explicit rule, because catching yourself before the first wrong edit is the part the framework can help with.
+- `state/milestone-{id}.yml` is the **single source of truth**; exactly one agent owns it at a time. **Other worktrees never write it** — and from a main checkout this is **enforced**, not just advised: the Live-Worktree Ownership Gate (forge SKILL 1.1a) blocks milestone-owned writes from main while a live worktree owns the milestone, with a recorded `lifecycle.ownership_override` as the only (never-silent) bypass.
 - Worktree / parallel agents write **only** their own milestone file and **append** desire-path files. They **never** write `index.yml`.
 - `index.yml` is **regenerated by rollup** (read every `milestone-*.yml` → rewrite the registry) by the main/orchestrator session — on `forge` resume and at `orchestrating` teardown. The rollup is deterministic + idempotent, so it **is** the reconcile step — never a hand-merge.
 - For shared-mutable files: write only your milestone's block; within a block, append-only (strike through, don't rewrite).

package/template/.forge/migrations/0.32.1-chief-front-door.md

@@ -0,0 +1,64 @@
+# Migration Guide: Chief Front Door (Forge 0.32.1)
+
+Forge 0.32.0 introduced Project Chief / Streams and could adopt active M10
+worktrees as streams, but the migration guide only asked whether to set
+`orchestration.auto: false`. If that decision was skipped, a project could have
+adopted streams while legacy M10 auto-routing still acted as the default front
+door.
+
+This migration detects that ambiguous state and asks the operator to choose.
+
+## Detection
+
+Prints `MIGRATE` when a project has adopted worktree-backed streams but has not
+explicitly opted out of legacy M10 auto-routing. Silent + exit 0 means no
+migration needed.
+
+```bash
+[ -f .forge/streams/active.yml ] || exit 0
+
+if grep -qE '^[[:space:]]+worktree:[[:space:]]*"?[^"[:space:]]+' .forge/streams/active.yml .forge/streams/*.yml 2>/dev/null; then
+  if ! awk '
+    /^orchestration:[[:space:]]*$/ { in_block=1; next }
+    /^[^[:space:]#][^:]*:/ { in_block=0 }
+    in_block && /^[[:space:]]+auto:[[:space:]]*false[[:space:]]*(#.*)?$/ { found=1 }
+    END { exit found ? 0 : 1 }
+  ' .forge/project.yml 2>/dev/null; then
+    echo "MIGRATE - adopted Chief streams still have legacy orchestration.auto enabled or unset"
+  fi
+fi
+```
+
+## Migration Steps
+
+1. Show the operator the current active streams:
+   - `.forge/streams/active.yml`
+   - any stream whose `runtime.worktree` or registry `worktree` points at a live
+     Forge worktree
+2. Explain the choice:
+   - `orchestration.auto: false` makes Chief/Streams the front door.
+   - M10 remains available when the Chief explicitly chooses worktree isolation
+     or the user explicitly asks for multi-agent/worktree mode.
+   - Leaving auto-routing enabled preserves legacy behavior where Standard/Full
+     `/forge` work can route straight to `orchestrating`.
+3. Ask: `Make Chief/Streams the front door now? (yes/no)`
+4. If yes, update `.forge/project.yml` in place:
+
+```yaml
+orchestration:
+  auto: false
+```
+
+If an `orchestration:` block already exists, add or update only its `auto` key.
+Do not modify other project settings.
+
+If no, record the operator's decision in the upgrade report. Do not edit
+`.forge/project.yml`.
+
+## Validation
+
+- `.forge/project.yml` contains `orchestration.auto: false` when the operator
+  chose Chief/Streams as the front door.
+- `.forge/streams/active.yml` and per-stream runtime files were not overwritten.
+- Explicit M10 use still works through Chief-selected or user-requested
+  orchestration.

package/template/.forge/migrations/0.33.0-worktree-convention-base.md

@@ -0,0 +1,94 @@
+# Migration Guide: Worktree convention promoted to base (Forge 0.33.0)
+
+Applies to projects that installed the experimental M10 `orchestrating` skill
+(`.claude/skills/orchestrating/`). Projects without M10 have nothing to migrate.
+
+0.33.0 closes a silent-freeze class (issues
+[#5](https://github.com/Attuned-Media/forge/issues/5) /
+[#6](https://github.com/Attuned-Media/forge/issues/6)). Three things changed:
+
+1. **The worktree path/naming/anchor convention is now base** — documented in
+   `FORGE.md` ("Worktree Convention"), so Chief/Streams has a fallback when a
+   worktree was created outside `orchestrating`, and the convention stays
+   upgrade-synced for every install regardless of the experimental skill (see
+   [ADR-010](../decisions/ADR-010-repo-scoped-worktree-root.md)).
+2. **`upgrading` no longer blanket-skips experimental skills** — Step 3b now
+   diffs an installed experimental skill against its `experimental/*/source/`
+   origin and offers a preview/confirm re-sync.
+3. **`chief-of-staff` gained an advisory Registry Drift Check** reconciling
+   `state/index.yml` against `streams/active.yml` (issue
+   [#4](https://github.com/Attuned-Media/forge/issues/4)). No on-disk migration —
+   it just runs on the next Show/Sync.
+
+The only thing that needs migrating on disk is an `orchestrating` skill that was
+**frozen before 0.28.0** and is therefore still pinned to the old shared
+`../forge-worktrees/` root. Against a frozen skill the 0.28.0 migration was a
+no-op, so new worktrees kept landing in the shared dir instead of the per-repo
+`../<repo>-worktrees/`. This guide detects that and offers the re-sync that
+0.28.0's "do nothing" note assumed had already happened.
+
+## Prerequisites
+
+1. On the new version's framework files (run `npx forge-orkes upgrade`, or the
+   `upgrading` skill against a local dev checkout, first).
+2. Working tree clean or changes committed — the fix re-syncs one skill dir.
+
+## Detection
+
+Prints `MIGRATE` only when the experimental `orchestrating` skill is installed
+**and** still pinned to the pre-0.28.0 shared worktree root (has `forge-worktrees`,
+lacks `<repo>-worktrees`). Silent + exit 0 otherwise — not installed, or already
+current. This is a **content** check, not a version-stamp check, because the
+skill is experimental and `upgrading` never force-overwrites it (the very gap
+this release closes).
+
+```bash
+S=.claude/skills/orchestrating/SKILL.md
+[ -f "$S" ] || exit 0
+if grep -q 'forge-worktrees' "$S" && ! grep -q '<repo>-worktrees' "$S"; then
+  echo "MIGRATE — experimental orchestrating skill is pinned to the pre-0.28.0 shared worktree root; re-sync it from experimental/m10"
+fi
+```
+
+## Migration steps
+
+### 1. Re-sync the experimental skill
+
+Run the `upgrading` skill. Its new **Step 3b** detects the stale `orchestrating`
+skill and offers a re-sync from `experimental/m10/source/skills/orchestrating/`.
+Answer **yes** to update the skill's markdown to the current convention
+(per-repo `../<repo>-worktrees/` default).
+
+Equivalent by hand (from the project root, with a Forge source checkout at
+`{source}`):
+
+```bash
+cp {source}/packages/create-forge/experimental/m10/source/skills/orchestrating/SKILL.md \
+   .claude/skills/orchestrating/SKILL.md
+cp {source}/packages/create-forge/experimental/m10/source/skills/orchestrating/bootstrap-checks.md \
+   .claude/skills/orchestrating/bootstrap-checks.md 2>/dev/null || true
+```
+
+### 2. (If the release changed them) re-run the M10 installer for hooks/MCP
+
+`upgrading` re-syncs only the skill markdown. If this release also changed M10
+hooks or the MCP server, re-run `experimental/m10/install.sh`. For 0.33.0 it did
+not — skill-only.
+
+### 3. Leave live worktrees alone
+
+Existing worktrees keep working off their recorded `lifecycle.worktree_path`.
+Only **new** worktrees pick up the per-repo default. Do not relocate a live
+worktree except via `git worktree move`.
+
+<!-- The migration is NEVER auto-applied. In Claude Code it runs via the
+`quick-tasking` skill, which the `upgrading` Step-7 prompt hands this guide to on
+"yes". -->
+
+## Validation
+
+- `grep -c '<repo>-worktrees' .claude/skills/orchestrating/SKILL.md` returns ≥ 1
+  and `grep -c 'forge-worktrees' .claude/skills/orchestrating/SKILL.md` returns 0.
+- `FORGE.md` contains a "Worktree Convention (base)" subsection.
+- Start a new M10 milestone (or `git worktree add` manually) — the worktree
+  appears under `../<your-repo>-worktrees/`, not the shared `../forge-worktrees/`.

package/template/.forge/migrations/0.34.0-live-worktree-ownership-gate.md

@@ -0,0 +1,66 @@
+# Migration Guide: Live-Worktree Ownership Gate (Forge 0.34.0)
+
+Applies to every project, but it is **framework-behavior only — nothing on disk
+to migrate**. The change lives entirely in framework-owned files that
+`upgrading` overwrites for you (`forge/SKILL.md`, `FORGE.md`). This guide exists
+so the change is recorded and discoverable; its Detection is an intentional no-op
+(issue [#7](https://github.com/Attuned-Media/forge/issues/7)).
+
+## What changed
+
+`forge` boot already surfaced live Forge worktrees, but the warning was
+**informational** — a session on `main` could still write single-owner-mutable
+milestone state while a worktree owned that milestone, forking the cursor (main
+says `reviewing`, the worktree says `planning`, a later resume contradicts the
+earlier claim).
+
+0.34.0 promotes that warning to an **enforced gate** (forge SKILL **1.1a**):
+
+- **Trigger** — invoked from `main` AND the selected milestone has a live
+  worktree (recorded `lifecycle.worktree_path` / `lifecycle.worktree_mode`,
+  a `forge/m-{id}-*` branch in `git worktree list`, or a stream `runtime.worktree`).
+- **Effect** — milestone-owned writes are blocked
+  (`state/milestone-{id}.yml`, `phases/milestone-{id}/`, `research/milestone-{id}.md`)
+  and routing stops until the operator picks one resolution: **enter** the
+  worktree, **sync** it, **retire** it, or record an explicit
+  `lifecycle.ownership_override: {at, from: main, reason}` — the only,
+  never-silent bypass.
+- Shared project docs (`context.md`, `refactor-backlog.yml`, `project.yml`, …)
+  stay writable from `main`, with the existing "not visible to the worktree
+  until it pulls/rebases" warning.
+
+`FORGE.md` State Ownership is updated from advice to enforcement to match.
+
+## Prerequisites
+
+1. On the new version's framework files (`npx forge-orkes upgrade`, or the
+   `upgrading` skill).
+
+## Detection
+
+No on-disk migration — the new behavior ships in framework-owned files that the
+upgrade already overwrote. The `lifecycle.ownership_override` field is written
+lazily, only when an operator records an override; absent means "no override,"
+which is the correct default. Intentional no-op:
+
+```bash
+# Skill-behavior change only — enforcement lives in forge/SKILL.md + FORGE.md,
+# both framework-owned and synced by the upgrade. Nothing on disk to migrate.
+exit 0
+```
+
+## Migration steps
+
+None. After the upgrade, the next `/forge` invoked from `main` against a
+milestone with a live worktree will enforce the gate automatically.
+
+## Validation
+
+- `grep -c '1.1a Live-Worktree Ownership Gate' .claude/skills/forge/SKILL.md`
+  returns 1.
+- From a `main` checkout with a live `forge/m-*` worktree, run `/forge` and
+  select that milestone — Forge blocks milestone-owned writes and offers the
+  enter / sync / retire / recorded-override choices instead of routing straight
+  into planning/executing/verifying/reviewing.
+- From the owning worktree (or for a milestone with no live worktree), `/forge`
+  routes normally — the gate is a no-op.

package/template/.forge/releases.yml

@@ -87,6 +87,21 @@ releases:
     bump: minor
     reserved_at: "2026-06-18"
     summary: "Project Chief / Streams orchestration — adds Project/Stream/Work Package runtime layers, Chief of Staff routing, stream/work-package templates, active context compaction, framework-wide size audit, and an idempotent migration guide. M10 is repositioned as an optional backend for worktree isolation, merge queue support, and experimental file claims."
+  - milestone: 16
+    version: "0.32.1"
+    bump: patch
+    reserved_at: "2026-06-20"
+    summary: "Chief front-door follow-up — detects projects that adopted worktree-backed streams but left legacy orchestration.auto enabled or unset, then prompts to set orchestration.auto: false so Chief/Streams is the default entry point while M10 remains explicit."
+  - milestone: 16
+    version: "0.33.0"
+    bump: minor
+    reserved_at: "2026-06-21"
+    summary: "Worktree convention promoted to base + experimental-skill drift fix + Chief registry drift check (issues #4/#5/#6). (1) FORGE.md gains a base 'Worktree Convention' (path/anchor/branch + orchestration.worktree_root resolution + lifecycle.worktree_path authority) so Chief/Streams has a fallback when a worktree was created outside orchestrating, and the convention stays upgrade-synced regardless of the experimental skill. (2) upgrading no longer blanket-skips installed experimental skills — it diffs them against experimental/*/source and offers a preview/confirm re-sync (warn at minimum), closing the silent-freeze where base migrations (e.g. 0.28.0 worktree-root) became no-ops against a frozen orchestrating skill. (3) migration-guide template gains an authoring guard: guides whose behavior lives in an experimental skill must detect the skill's content, not just the version stamp. (4) chief-of-staff gains an advisory Registry Drift Check (Show + Sync) reconciling state/index.yml active milestones against streams/active.yml."
+  - milestone: 16
+    version: "0.34.0"
+    bump: minor
+    reserved_at: "2026-06-21"
+    summary: "Live-Worktree Ownership Gate (issue #7). forge boot's worktree surfacing was advisory, so a session on main could write single-owner-mutable milestone state (milestone-{id}.yml, phases/, research/) while a live worktree owned the milestone — forking the cursor (main 'reviewing' vs worktree 'planning'). forge SKILL gains an enforced gate (1.1a): when invoked from main and the selected milestone has a live worktree, milestone-owned writes are blocked and routing stops until the operator enters the worktree, syncs it, retires it, or records an explicit lifecycle.ownership_override (the only, never-silent bypass). Shared project docs stay writable from main with a not-visible-until-sync warning. FORGE.md State Ownership promoted from advice to enforcement. Also folds in dev/template skill drift cleanup: forge/discussing/planning dev .claude/skills copies were behind the template (chief-streams + context-archive content) — brought to parity."
 
 # Note on the 15 / 0.24.0 ordering: reserved as max(0.23.0)+minor. origin/main was
 # already at 0.23.0 when this shipped (M10/M12/M13/M14 all merged), so 0.24.0 is a

package/template/.forge/templates/migration-guide.md

@@ -45,6 +45,37 @@ its version runs it once, and after the version is stamped it falls out of range
 ledger, no per-version code, no staleness. (It also closes the install-run blind spot:
 detection keys off the freshly-synced guides on disk, not the skill's own pre-sync code.)
 
+### Experimental-skill guard (read if your change lives in an experimental skill)
+
+If the behavior your guide migrates is implemented **only inside an experimental,
+opt-in skill** (e.g. `.claude/skills/orchestrating/` from `experimental/m10/`),
+a version-stamp check is **not enough**. `upgrading` never overwrites an
+experimental skill in its base sync (it offers a re-sync in Step 3b, which the
+user may decline), so the skill can stay pinned at install-time content while the
+version stamp advances — and a stamp-only Detection block would report "nothing
+to migrate" while the behavior is silently absent. This is exactly how the 0.28.0
+repo-scoped worktree root became a no-op (issue #5).
+
+So when your change touches experimental-skill behavior, the Detection block MUST
+inspect the **skill's content on disk**, not the version, and emit `MIGRATE` when
+the skill is stale:
+
+```bash
+# The behavior lives in an experimental skill — check its CONTENT, not the version.
+S=.claude/skills/orchestrating/SKILL.md
+[ -f "$S" ] || exit 0                       # skill not installed → nothing to do
+if grep -q 'forge-worktrees' "$S" \
+   && ! grep -q '<repo>-worktrees' "$S"; then
+  echo "MIGRATE — experimental orchestrating skill is pinned to the pre-0.28.0 worktree root; re-sync it"
+fi
+```
+
+Better still, **also promote the load-bearing convention into base** (`FORGE.md`
+or a base skill) so it is upgrade-synced regardless of the experimental skill's
+state — then the base workflow no longer depends on experimental internals at all
+(issue #6). The content-check Detection above is the floor; base promotion is the
+durable fix.
+
 ### Detection block skeleton (applies)
 
 ```bash
@@ -106,6 +137,7 @@ must be confirmed with the user.>
 - [ ] Exactly one `## Detection` heading; exactly one ` ```bash ` block under it.
 - [ ] Block emits `MIGRATE` on stdout iff the migration applies; silent + exit 0 otherwise.
 - [ ] Block is safe on a clean/empty project (no errors, exit 0).
+- [ ] If the change lives in an experimental skill, Detection checks the skill's **content** (not just the version stamp) — see the Experimental-skill guard above.
 - [ ] Any new accumulating artifact declares owner, size gate, archive/compaction rule, derived vs source-of-truth status, and future migration behavior.
 - [ ] Mirrored byte-identical to `docs/migrations/{same-name}.md`.
 - [ ] No edit to `upgrading/SKILL.md` or `create-forge.js` was needed (the loop covers it).