forge-orkes 0.32.0 → 0.33.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.33.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/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."

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/releases.yml

@@ -87,6 +87,16 @@ 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."
 
 # 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).