forge-orkes 0.31.0 → 0.33.0

package/template/.forge/FORGE.md

@@ -1,6 +1,6 @@
 # Forge
 
-Lean meta-prompting framework for Claude Code. Context engineering + constitutional governance on native primitives.
+Lean meta-prompting framework. Context engineering + constitutional governance on agent-native primitives.
 
 ## Critical: No Native Plan Mode
 
@@ -11,7 +11,7 @@ All phases: **invoke via `Skill` tool**, never native behavior. `planning` → `
 ## Core Principles
 
 1. **Lean default, powerful when needed.** Quick → skip ceremony. Complex → full governance.
-2. **Native-first.** Claude Code built-ins only. No custom JS. Deprecate Forge when native catches up.
+2. **Adapter-native.** Use each platform's built-ins through adapters. Avoid custom runtime unless the substrate truly needs it.
 3. **Context is sacred.** Size-gate artifacts, lazy-load skills, fresh agents for isolated work.
 4. **Decisions are contracts.** Lock before building. Honor or flag — never silently override.
 5. **Verify goals, not tasks.** "Does it work?" > "Did we finish checklist?"
@@ -19,6 +19,39 @@ All phases: **invoke via `Skill` tool**, never native behavior. `planning` → `
 7. **Pave desire paths.** Repeated deviations/corrections = signal → evolve framework.
 8. **Disconfirm before commit.** Before locking a diagnosis, a solution, or a foundational choice, run the cheap pass that could break it. A conclusion reached without an attempt to refute it is a hypothesis, not a finding. Enforced at the three commit points: `debugging` (Confirmation Gate), `discussing`/`architecting` (option-space framing), `architecting` (Platform & Goal Validation).
 
+## Core Protocol And Adapters
+
+**Core protocol** lives in `.forge/`: project/constitution state, milestones, requirements, roadmap, context, streams, work packages, plans, verification, audits, and state ownership rules. The core protocol describes durable behavior, not one platform's tool names.
+
+**Platform adapters** translate the protocol into a runtime. Each platform adapter maps core behavior to its tools: Claude Code skills/hooks, Codex/AGENTS behavior, manual multi-session handoffs, or future agent surfaces. Adapter mechanics stay in adapter files and skills; they should not become core requirements.
+
+## Project Streams
+
+Forge has three runtime coordination layers: Project, Stream, and Work Package.
+
+| Layer | Purpose | Default Context |
+|---|---|---|
+| **Project** | Repo-wide traffic map: active streams, ownership, risks, merge order | `.forge/streams/active.yml` |
+| **Stream** | One active line of work: goal, branch/worktree, state, blockers, next action | `.forge/streams/{stream}.yml` + `brief.md` |
+| **Work Package** | Delegated bounded task inside a stream | `.forge/streams/{stream}/packages/{id}.yml` |
+
+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."
@@ -60,7 +93,7 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | Systematic debugging | `debugging` | When stuck |
 | Upgrade Forge files | `upgrading` | On-demand |
 | Cross-session memory | `beads-integration` | When Beads installed |
-| Multi-agent orchestration (experimental) | `orchestrating` | Full (opt-in) |
+| Multi-agent backend (experimental) | `orchestrating` | Optional, usually selected by Chief/Streams |
 
 > Experimental skills require opt-in install — see `packages/create-forge/experimental/m10/README.md`.
 
@@ -73,7 +106,25 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | `requirements/m{N}.yml` | 50 KB/file | Prevents scope creep |
 | `plan.md` | 30 KB | Keeps executor context <50% |
 | `constitution.md` | 10 KB | Gates must be scannable |
+| `context.md` | 12 KB | Active decisions only; history archives to `context-archive.md` |
 | `refactor-backlog.yml` | 150 KB | Working backlog stays scannable; terminal items archive to `refactor-backlog-archive.yml` (advisory — flags, never blocks) |
+| `streams/active.yml` | 20 KB | Project Chief traffic map must stay cheap to load |
+| `streams/{stream}.yml` | 15 KB | Stream state stays resumable without becoming history |
+| `streams/{stream}/brief.md` | 8 KB | Stream context packet must fit into active session context |
+| `streams/{stream}/packages/{id}.yml` | 10 KB | Delegated work contract stays bounded |
+
+### Accumulating Artifacts
+
+Every new accumulating artifact needs: owner, size gate, archive/compaction rule,
+`derived` vs source-of-truth status, and migration behavior. Defaults:
+
+- `roadmap.yml`, `requirements/*.yml`, `releases.yml` are source-of-truth; load
+  scoped slices, not whole history.
+- `phases/`, `audits/`, `research/`, `archive/`, and `context-archive.md` are
+  historical; load only by milestone/stream/package/version.
+- Runtime/generated files (`.mcp-server/*.db*`, logs, spike DBs) are excluded
+  from framework context and packages unless debugging them.
+- Template copies sync mechanically; do not treat them as separate concepts.
 
 ### Fresh Agent Pattern
 Task touches 20+ files or complex subsystem → spawn fresh executor with isolated context. Prevents context rot.
@@ -82,7 +133,9 @@ Task touches 20+ files or complex subsystem → spawn fresh executor with isolat
 Each phase writes outputs to `.forge/` before completing. At phase boundaries, recommend `/clear`. Next phase loads from disk. Advisory — skip for short phases under 40% context.
 
 ### Lazy Loading
-Skills load only when invoked. CLAUDE.md stays in context; skill details on demand. Base context ~300 lines.
+Skills load only when invoked. Active context is `.forge/context.md`; consult
+`.forge/context-archive.md` only when older decisions matter. Skill details stay
+on demand. Base context ~300 lines.
 
 ## Model Routing
 
@@ -136,7 +189,12 @@ State lives in `.forge/`:
 - `state/index.yml` — DERIVED registry rolled up from milestone files (id, name, status, last_updated). Never hand-edited; never written by worktree agents.
 - `state/milestone-{id}.yml` — Per-milestone cursor (single source of truth): position, progress, decisions, blockers. One owner at a time.
 - `state/desire-paths/` — Append-only framework-usage observations, one file per observation. Occurrence counts derived by globbing (no mutable counter). Each carries `scope: project | framework` (set at capture; absent ⇒ project). **`forge` boot is the single review owner**: at 3+ occurrences it surfaces a concrete fix from the co-located suggestion table, persists declines to `declined/` (no re-nag), and for `scope: framework` signals routes them upstream — a portable block to `upstream/` plus a `gh issue` offer against `forge.upstream_repo`. This closes Principle 7's capture→act loop; `verifying` captures but no longer surfaces. See [ADR-012](../docs/decisions/ADR-012-upstream-desire-path-feedback-channel.md).
-- `context.md` — Locked decisions + deferred ideas (discuss phase)
+- `context.md` — Active locked decisions + deferred ideas (target <=12KB)
+- `context-archive.md` — Historical locked decisions; load only when relevant
+- `streams/active.yml` — Compact Project Chief traffic map: active stream summaries only.
+- `streams/{stream}.yml` — Per-stream state: lifecycle, ownership, shared surfaces, blockers, merge readiness.
+- `streams/{stream}/brief.md` — Human-readable stream context packet loaded when resuming that stream.
+- `streams/{stream}/packages/{id}.yml` — Work package contract for delegated workers or manual sessions.
 - `research/milestone-{id}.md` — Research findings snapshot (dated, immutable)
 - `phases/milestone-{id}/{phase}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter (`{id}`=milestone, `{phase}`=phase# preserved verbatim, `{name}`=kebab, `{NN}`=seq)
 - `refactor-backlog.yml` — Refactoring catalog (actionable items only), worked via quick-tasking. Canonical status vocab: `pending | in_progress | done | dismissed | deferred`. Terminal items auto-archive on the next reviewing/quick-tasking write (compaction-on-write).
@@ -162,31 +220,22 @@ State-sync commits are separate from per-task code commits (which stay atomic du
 
 ### State Ownership (multi-worktree safety)
 
-`.forge/` is **code-like**: it branches with the repo, syncs via git, atomic-commits with the work it describes. Worktrees get their own `.forge/` checkout by construction — that's not configuration, that's git. The framework's job is to specify how each *kind* of `.forge/` file behaves under that model.
-
-**Every `.forge/` artifact falls into one of five sharing classes.** The class determines the write rule across worktrees:
+`.forge/` is code-like: it branches with the repo, syncs via git, and commits
+with the work it describes. Every artifact has a sharing class:
 
 | Class | Files | Write rule |
 |---|---|---|
 | **Single-owner mutable** | `state/milestone-{id}.yml`, `phases/milestone-{id}/`, `research/milestone-{id}.md` | Exactly one writer at a time — the worktree (or main session) currently driving that milestone. **Other worktrees never touch it**, not even to read-then-write — they pull from main if they need it. |
 | **Derived** | `state/index.yml` | Never hand-edited. Regenerated by Rollup 1.0 from `milestone-*.yml`. Only the main/orchestrator session runs rollup. |
 | **Append-only shared** | `releases.yml` (version reservations), `state/desire-paths/*` (one file per observation) | Many writers OK; structure prevents collision. `releases.yml` uses the Version Reservation Protocol (append + commit + push before depending on the slot); desire-paths use distinct filenames so two writers never touch the same file. |
-| **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` (ID space `FR-`/`DEF-`/`NFR-` is globally shared even though each milestone owns its file) | Two rules: **(a) Write only to YOUR milestone's block.** Different milestone blocks → git merges cleanly. **(b) Within a block, append-only.** Locked decisions get *struck through* (`~~old~~`) rather than rewritten in place; new sub-bullets appended below existing ones. Same-line concurrent edits become impossible by construction. |
+| **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` (ID space `FR-`/`DEF-`/`NFR-` is globally shared even though each milestone owns its file) | Write only to 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` | 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 write awareness.** When a session edits a shared-mutable file's block whose milestone is **live in a different worktree** (e.g. main writes to `context.md`'s `## M9` block while m9 is running in a worktree), the edit lands cleanly on main but is **invisible to the worktree until it pulls/rebases**. This is identical to how `src/foo.ts` works under branches — there's nothing pathological about it; it's branch divergence. The framework surfaces the situation so the operator can decide:
-
-- **`forge` Step 1** in main checks `git worktree list` and surfaces live Forge worktrees at boot — *"m9 is live in worktree X at e94b6bb. Edits to m9 state belong there; shared docs edited here need a sync."*
-- **`discussing`** (before writing to `context.md`'s milestone block) and **`reviewing`** (before writing to `refactor-backlog.yml`) emit a one-line warning when the target block's milestone is live elsewhere. The warning informs, never blocks — main is often the canonical author of these files.
-- **Worktree-side rebase check** (opt-in via `forge.worktree_rebase_check: true` in `project.yml`) — when `forge` boots inside a worktree, it diffs `.forge/` between the worktree's HEAD and `main`; if shared-mutable files have changed on main, it offers `git restore --source main -- <files>` or a rebase.
-
-**Why not global `.forge/`?** A common instinct is "make `.forge/` shared so context propagates automatically." It breaks four load-bearing invariants:
-1. **Decisions are contracts** — they're versioned with the code they govern; severing them from branches breaks the contract.
-2. **State survives machine loss** — the multi-laptop pull-from-any-clone story depends on `.forge/` being in git.
-3. **History time-travel** — `git checkout` an old commit and you see the plan/decisions as they were; global state makes that impossible.
-4. **Git is the concurrency detector** — without it, two sessions writing the same field becomes silent last-write-wins.
-
-Per-worktree `.forge/` with a sharing taxonomy is the model. See [ADR-011](../docs/decisions/ADR-011-shared-state-taxonomy.md) for the longer version.
+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
+[ADR-011](../docs/decisions/ADR-011-shared-state-taxonomy.md) for rationale.
 
 ### State Ownership rules (quick reference)
 
@@ -194,7 +243,7 @@ Per-worktree `.forge/` with a sharing taxonomy is the model. See [ADR-011](../do
 - 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).
-- Same-milestone parallel work is out of scope, guarded by the M10 claim layer.
+- Same-milestone parallel work needs Chief/Streams contracts; M10 file claims are optional defense-in-depth.
 
 ### Version Reservation Protocol
 

package/template/.forge/migrations/0.32.0-chief-streams.md

@@ -0,0 +1,159 @@
+# Migration Guide: Chief/Streams (Forge 0.32.0)
+
+Adds Project Chief / Streams support to existing Forge projects. This migration
+installs framework-owned stream templates and adapter routing, and offers active
+context compaction. It must never overwrite user-owned runtime stream state in
+`.forge/streams/`.
+
+## Prerequisites
+
+1. Upgrade framework files first so this guide and the new templates are present.
+2. Commit or stash unrelated work.
+3. If `.forge/streams/` already exists, treat it as user state and preserve it.
+
+## Detection
+
+Prints `MIGRATE` when stream templates, Chief routing, active-context
+compaction support, or active M10 adoption appears missing. Silent + exit 0
+means no migration needed.
+
+```bash
+need=0
+
+for f in \
+  .forge/templates/streams/active.yml \
+  .forge/templates/streams/stream.yml \
+  .forge/templates/streams/brief.md \
+  .forge/templates/streams/work-package.yml
+do
+  [ -f "$f" ] || need=1
+done
+
+if [ -f .claude/skills/forge/SKILL.md ] && ! grep -q 'chief-of-staff' .claude/skills/forge/SKILL.md; then
+  need=1
+fi
+
+if [ -f .claude/skills/chief-of-staff/SKILL.md ]; then
+  :
+else
+  need=1
+fi
+
+if [ -f .forge/context.md ] && [ ! -f .forge/context-archive.md ]; then
+  bytes=$(wc -c < .forge/context.md | tr -d ' ')
+  [ "$bytes" -gt 12288 ] && need=1
+fi
+
+if [ ! -f .forge/streams/active.yml ] && grep -R "worktree_mode: \\(active\\|degraded\\)" .forge/state/milestone-*.yml >/dev/null 2>&1; then
+  need=1
+fi
+
+if [ "$need" -eq 1 ]; then
+  echo "MIGRATE - Chief/Streams templates, routing, context compaction, or M10 adoption missing"
+fi
+```
+
+## Migration Steps
+
+### 1. Add Stream Templates
+
+Copy the framework-owned templates from the upgraded Forge source into:
+
+- `.forge/templates/streams/active.yml`
+- `.forge/templates/streams/stream.yml`
+- `.forge/templates/streams/brief.md`
+- `.forge/templates/streams/work-package.yml`
+
+Create parent directories if needed. Do not copy anything into `.forge/streams/`
+unless the user explicitly asks to instantiate a real stream.
+
+### 2. Add Chief Skill And Routing
+
+Copy the Chief skill into the platform adapter used by the project:
+
+- Claude adapter: `.claude/skills/chief-of-staff/SKILL.md`
+- Codex/AGENTS adapter, if present in that project: `.agents/skills/chief-of-staff/SKILL.md`
+
+Update the Forge entry skill for the active adapter so stream intents route to
+Chief before tier detection. Required intent examples:
+
+- `show streams`
+- `start stream`
+- `pause stream`
+- `resume stream`
+- `delegate stream`
+- `sync streams`
+- `detect conflicts`
+- `merge safe`
+- `close stream`
+- `Chief of Staff`
+
+### 3. Preserve Runtime State
+
+If `.forge/streams/` already exists, inspect it but never overwrite it. Runtime
+stream files are user/project state, not framework templates. If a runtime file
+is missing a field, add it only after showing the diff to the user.
+
+### 4. Adopt Existing M10 Worktrees When Present
+
+If `.forge/state/milestone-*.yml` contains `lifecycle.worktree_mode: active` or
+`degraded`, adopt those M10 sessions as streams. Do not teardown, merge, rebase,
+remove, or rename existing worktrees as part of migration.
+
+For each active M10 worktree:
+
+1. Read the milestone state and `git worktree list --porcelain`.
+2. Create or update `.forge/streams/active.yml`.
+3. Create or update:
+   - `.forge/streams/{stream-id}.yml`
+   - `.forge/streams/{stream-id}/brief.md`
+   - `.forge/streams/{stream-id}/packages/`
+4. Map existing M10 fields into stream state:
+   - `lifecycle.worktree_path` -> `runtime.worktree`
+   - `lifecycle.worktree_branch` -> `runtime.branch`
+   - `lifecycle.session_id` / `claim_session_id` -> `runtime.worker_sessions`
+   - milestone id/name/status/phase -> stream goal, context, and brief
+5. Leave ownership surfaces empty if unknown and mark them as needing
+   declaration. Missing ownership should surface as a conflict to resolve after
+   adoption; it should not block adoption.
+6. Ask before setting `orchestration.auto: false` in `.forge/project.yml`.
+   Turning it off makes Chief/Streams the front door while keeping M10 available
+   as an optional backend.
+
+Adoption is idempotent: if a stream already references the same worktree path or
+branch, update that stream's summary/brief instead of creating a duplicate.
+
+### 5. Compact Active Context When Needed
+
+If `.forge/context.md` is over 12 KB and `.forge/context-archive.md` is missing:
+
+1. Copy the original `.forge/context.md` to `.forge/context-archive.md`.
+2. Keep current/open decisions, Deferred Ideas, Needs Resolution, and Amendment
+   Log in `.forge/context.md`.
+3. Move completed historical milestone decision blocks into the archive.
+4. Add a pointer in active context to `.forge/context-archive.md`.
+
+This step must preserve decision text losslessly.
+
+### 6. Confirm M10 Positioning
+
+If the project has M10 installed, keep worktree and merge safety instructions.
+Update wording so Chief/Streams is the user-facing orchestration model and M10
+is an optional backend for worktree isolation, merge queue support, and optional
+file claims.
+
+## Validation
+
+- Stream templates exist under `.forge/templates/streams/`.
+- Chief skill exists in the active platform adapter.
+- Forge routing mentions `chief-of-staff`, `show streams`, `start stream`, and
+  `merge safe`.
+- `.forge/streams/` runtime state is unchanged unless the user approved a
+  specific migration of a runtime stream file.
+- Existing active/degraded M10 worktrees, if any, are represented in
+  `.forge/streams/active.yml` and per-stream files without teardown.
+- If context compaction ran, `.forge/context-archive.md` contains historical
+  decisions and `.forge/context.md` is under 12 KB.
+- Running detection a second time is idempotent and prints no `MIGRATE` once the
+  project has templates, routing, Chief skill, compacted context, and adopted
+  active M10 worktrees.

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

@@ -1,29 +1,109 @@
 # Forge Release Registry — version reservations across concurrent milestones
 #
 # PURPOSE: remove the version number + CHANGELOG slot from per-milestone scope so
-# two milestones running in parallel sessions never collide on your project's
+# two milestones running in parallel sessions never collide on `package.json`
 # version or pick the same number. This is the coordination point both sessions
 # read and append to.
 #
 # COMMITTED + APPEND-ONLY. Each milestone appends exactly ONE entry when it
 # reserves its version (at planning, or at delivery if planning predates this
 # file). Appending — never editing prior entries — is what keeps two sessions
-# from conflicting: distinct lines, no contention. Commit and push the
-# reservation so a parallel session pulls and sees numbers already taken.
+# from conflicting: distinct lines, no contention. The registry is committed and
+# pushed so a parallel session pulls and sees reservations already taken.
 #
 # RULE: the next free version = highest `version:` in this file, bumped by the
-# change's semver level (capability = minor; fix/doc = patch). Delivery NEVER
-# writes a project version that is not reserved here first.
+# change's semver level (capability = minor 0.x.0; fix/doc = patch 0.x.y; see the
+# version-bump criteria in FORGE.md / project memory). Delivery NEVER writes a
+# `package.json` version that is not reserved here first.
 #
 # RACE NOTE: reserve EARLY (at planning), commit + push the reservation BEFORE
-# editing the version. If two sessions reserve near-simultaneously, the second
-# push rebases onto the first (append-only → no conflict) and re-reads max() to
-# take the next number.
+# editing package.json. If two sessions reserve near-simultaneously, the second
+# push rebases onto the first (append-only → no conflict) and must re-read max()
+# and take the next number.
 
-releases: []
-# Example entry shape (delete this comment once you add a real one):
-#   - milestone: 1
-#     version: "0.2.0"
-#     bump: minor
-#     reserved_at: "YYYY-MM-DD"
-#     summary: "one-line description of the milestone"
+releases:
+  - milestone: 12
+    version: "0.21.0"
+    bump: minor
+    reserved_at: "2026-06-12"
+    summary: "CLAUDE.md @import extraction (framework prose → .forge/FORGE.md)"
+  - milestone: 13
+    version: "0.20.0"
+    bump: minor
+    reserved_at: "2026-06-12"
+    summary: "Nested phase layout (phases/milestone-{id}/{phase}-{name}/)"
+  - milestone: 14
+    version: "0.22.0"
+    bump: minor
+    reserved_at: "2026-06-13"
+    summary: "Refactor-backlog compaction migration + lifecycle (archive terminal items, size gate, status-vocab enforcement)"
+  - milestone: 10
+    version: "0.23.0"
+    bump: minor
+    reserved_at: "2026-06-14"
+    summary: "M10 auto-routing — forge routes Standard/Full through orchestrating when installed (install = consent); orchestration.auto opt-out"
+  - milestone: 15
+    version: "0.24.0"
+    bump: minor
+    reserved_at: "2026-06-14"
+    summary: "Disconfirm-before-commit rigor: debugging Confirmation Gate (blind-spot check), architecting Platform & Goal Validation + option-space framing, discussing widen-before-narrowing, CLAUDE.md principle 8"
+  - milestone: 16
+    version: "0.25.0"
+    bump: minor
+    reserved_at: "2026-06-14"
+    summary: "Worktree branch anchor in forge milestone selection — git branch deterministically selects the milestone (exact lifecycle.worktree_branch match, or milestone-id token in branch name) before the timestamp default; deferred/complete matches surface instead of auto-resuming"
+  - milestone: 16
+    version: "0.26.0"
+    bump: minor
+    reserved_at: "2026-06-14"
+    summary: "Milestone-anchored worktree naming in orchestrating — worktree dir + branch become forge/m-{id}-{session_id} (was forge/{uuid}), adds lifecycle.worktree_anchor. Makes the 0.25.0 branch-anchor id-token fallback work for orch worktrees so a moved/stale-state worktree still resolves to its milestone off the branch name alone; uuid suffix keeps collision-resistance, forge/ prefix keeps GC sweep"
+  - milestone: 17
+    version: "0.27.0"
+    bump: minor
+    reserved_at: "2026-06-15"
+    summary: "Human Verification Gate — hard block on milestone close + orchestration teardown until an explicit human sign-off is recorded as current.human_verified in milestone state. Code-level PASS is necessary but never sufficient to close. Captured by verifying (post-verdict prompt), enforced at reviewing-complete + orchestrating Step 5.0; recorded-override (method: override) is the only bypass and is surfaced. New current.human_verified state field — lazy migration: absent = prompt on next close, already-complete milestones never re-gated."
+  - milestone: 18
+    version: "0.28.0"
+    bump: minor
+    reserved_at: "2026-06-15"
+    summary: "Configurable repo-scoped worktree root — orchestration.worktree_root defaults to ../<repo-name>-worktrees/ (was shared ../forge-worktrees/). Fixes cross-repo worktree mixing when multiple repos share a parent dir, fixes cwd-sensitive resolution (relative roots now resolve against repo root, not shell cwd), and folds a gitignore-guard for repos with fully-ignored .claude/ trees (initializing writes correct carve-out for greenfield; upgrading detects + warns for brownfield)"
+  - milestone: 19
+    version: "0.29.0"
+    bump: minor
+    reserved_at: "2026-06-15"
+    summary: "Shared-state taxonomy for multi-worktree Forge — FORGE.md State Ownership expanded to enumerate all 5 file-sharing classes (single-owner mutable, derived, append-only shared, shared mutable, stable shared) with the rule each follows. Promotes 'do not touch another worktree's state files' to explicit rule. Adds structural rule for context.md + refactor-backlog.yml (write only to your milestone block, within-block append-only). New `forge` boot worktree-liveness view (lists live Forge worktrees + their owning milestones in main). Cross-tree write warnings in discussing (context.md) + reviewing (refactor-backlog.yml). Opt-in worktree-side rebase check at boot (gated by forge.worktree_rebase_check). Triggered by the canvaz 2026-06-15 case: main-session edits to m9's context block were invisible to the m9 worktree."
+  - milestone: 20
+    version: "0.30.0"
+    bump: minor
+    reserved_at: "2026-06-16"
+    summary: "Upstream desire-path feedback channel (ADR-012) — closes the capture→act loop in Principle 7. (1) Plan-anchor re-derivation guard already landed (commit 5ddf3a1): executing re-derives plan literals against HEAD before the first task; planning makes anchors drift-resistant. (2) `scope: project|framework` field added to the desire-path schema, set at capture by verifying/executing/planning (lazy migration: absent⇒project). (3) Single review owner = forge boot — retires verifying's duplicate 'Surface Recommendations', co-locates the type→evolution suggestion table, adds a decline-ledger (declined/) so declines stop re-nagging, adds a Quick-tier review trigger in quick-tasking. (4) Tiered upstream transport for scope:framework signals: always write a portable block to state/desire-paths/upstream/; offer `gh issue create` against forge.upstream_repo (default github.com/zayneupton/forge) when gh present; upgrading harvests upstream/ into {source}/docs/desire-paths-inbox/. Optional forge.upstream_repo added to project.yml. Triggered by the canvaz plan-anchor-drift signal that could only reach the framework via manual chat copy-paste."
+  - milestone: 15
+    version: "0.31.0"
+    bump: minor
+    reserved_at: "2026-06-17"
+    summary: "Data-driven migration detection — replaces hardcoded per-version detection blocks (SKILL Step 7 + bin detectLegacyLayouts) with a single loop over synced .forge/migrations/{v}-*.md guides, ranged (installed, source]. New uniform Detection-block contract: echo `MIGRATE` on stdout when the migration applies, silent/exit-0 for no-op. All 7 guides normalized to it (0.28.0 consolidated to one `## Detection`; 0.29.0 stays an explicit in-range no-op). Removes the staleness class entirely — a new guide is auto-covered the moment it ships in the template, zero per-version code, and the install-run blind spot is fixed (detection keys off freshly-synced guides + pre-bump installed version). Triggered by ptnrkit 0.19.2→0.30.0 upgrade where bin was 4 versions behind and 2 real on-disk migrations (0.20.0, 0.22.0) reported 'needs manual review: 0'."
+  - milestone: 16
+    version: "0.32.0"
+    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
+# clean increment — no publish-order coordination needed. (Earlier draft of this
+# release was built on a stale 0.19.2 base before a fetch corrected it.)
+
+# Note on the 12/13 ordering: both reserved 2026-06-12. M13 holds the lower number
+# (0.20.0) and M12 the higher (0.21.0) by explicit user decision — they ship in the
+# same package release, M12 topping the version. max() here is 0.21.0, so the next
+# milestone reserves 0.22.0 (minor) regardless of which milestone id is higher.

package/template/.forge/templates/context.md

@@ -2,6 +2,10 @@
 
 Created during the discuss phase. This document is a contract between the user and all downstream agents.
 
+Active context target: <= 12 KB. When completed historical milestone decision
+blocks accumulate, copy them to `.forge/context-archive.md` and keep only
+current/open decisions here.
+
 **Rules:**
 - **Locked Decisions** → MUST be implemented exactly as stated. No alternatives. No "better" solutions.
 - **Deferred Ideas** → MUST NOT appear in plans, tasks, or code. Not even as TODOs.