forge-orkes 0.33.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.33.0",
+  "version": "0.36.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,13 +56,13 @@ packages, plans, verification reports, commits, and archived artifacts.
 
 | Intent | Examples | Action |
 |--------|----------|--------|
-| Show | "show streams", "active streams", "what is running?" | Run Registry Drift Check, then summarize registry without loading all deep history |
+| Show | "show streams", "active streams", "what is running?" | Run Registry Drift Check + Merge Cadence 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" | Run Registry Drift Check, then refresh registry summaries from active stream briefs |
+| Sync | "sync streams" | Run Registry Drift Check + Merge Cadence 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 |
@@ -256,6 +256,50 @@ Use "merge safe" to identify streams that can land:
 If any condition fails, mark the stream blocked or keep it ready with a named
 reason it cannot merge yet.
 
+## Merge Cadence Check
+
+**Merge often and early** (FORGE.md Project Streams). Ready work integrated late
+drifts from main, staleness accrues on shared surfaces, and the eventual merge is
+larger and riskier. This check makes the cadence visible so integration happens
+when work is ready — not at milestone end. Run it at the **start of the Show and
+Sync intents**, after the Registry Drift Check.
+
+**Advisory — it surfaces and recommends. It never merges, never rebases, and
+never blocks.** Merging and rebasing stay human decisions (conflicts need
+judgment); the Chief's job is to make "this is ready, integrate it now" impossible
+to miss.
+
+Streams that use **integration checkpoints** (FORGE.md → Stream Integration
+Checkpoints) already fast-forward verified phases onto main automatically, so this
+check focuses on what they don't cover: streams/phases **without** a checkpoint,
+diverged streams whose publish was rejected (non-ff — they need a manual
+merge/rebase), and **cross-stream merge order**. A checkpoint stream that is
+cleanly auto-publishing needs no nudge here.
+
+1. **Ready-to-merge surfacing.** From `active.yml`, collect streams with
+   `status: ready` (and any `merge_queue` entries). For each, run the Merge Safe
+   Flow conditions. Unblocked + no conflicts → list under **Ready to merge** with
+   a one-line *"ready — integrate now"* and, if known, how long it has been ready
+   (from the stream's `last_sync` / brief date). Add/refresh its `merge_queue`
+   entry (`status: waiting`). Blocked → list the named reason instead.
+2. **Idle-ready nudge.** A stream that has sat `ready` across **multiple Show/Sync
+   passes** or whose branch is mergeable but untouched is the cadence smell.
+   Recommend integrating it before more divergence accrues. No magic threshold —
+   report the age and let the operator decide; the point is visibility, not a hard
+   cutoff.
+3. **Sibling-rebase nudge.** When main has advanced on a **shared** or
+   **depended-on** surface since a live worktree branched, surface
+   *"main moved on {surface} — rebase worktree {stream} ({path}) before it drifts"*
+   for each affected live stream. Cheap detection: compare each live stream's
+   branch point against main for the shared surfaces it declares
+   (`git -C {worktree} rev-list --count HEAD..main -- {shared_surface}` > 0).
+   This is the cadence-driven form of the boot-time `forge.worktree_rebase_check`.
+4. **Order.** When more than one stream is ready, recommend a merge order
+   (fewest shared-surface conflicts first; depended-on streams before dependents).
+
+If nothing is ready and no worktree is behind on a shared surface, say so in one
+line (`merge cadence: nothing ready, no rebases needed`) and continue.
+
 ## Close Flow
 
 1. Confirm final status: merged, intentionally abandoned, superseded, or split.
@@ -273,9 +317,15 @@ Streams:
 - billing-webhooks — active — owns api/billing, shared db/schema — next: verify webhook retries
 - settings-ui — paused — owns app/settings — next: resume form validation
 
+Ready to merge:
+- reporting-export — ready 2 passes ago — no conflicts — integrate now (merge often and early)
+
+Rebase needed:
+- billing-webhooks — main moved on db/schema since it branched — rebase ../app-worktrees/billing-webhooks
+
 Conflicts:
 - billing-webhooks and reporting-export both touch db/schema. Contract owner needed before either merges.
 
 Next:
-- Continue billing-webhooks, or start a new stream with read-only ownership until boundaries are declared.
+- Merge reporting-export, then rebase billing-webhooks onto the new main.
 ```

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

@@ -28,14 +28,25 @@ 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`).
 - Any differ → surface: *"`{file}` has changed on main since this worktree branched. Pull just this file (`git restore --source main -- {file}`), rebase, or skip?"* — operator decides.
 - Setting absent or `false` → no-op.
 
+**Integration flag check (consumer — worktree only).** When `in_main_checkout: false`, check whether a checkpoint publish has landed work on main that this worktree should pull (FORGE.md → Stream Integration Checkpoints). Event-driven, not polled — read the flag first; act only if it is set:
+
+- Read `.git/forge/integration-pending` (in the git common dir — set by a producer's checkpoint publish, shared across this machine's worktrees). Absent, or its main sha already seen by this worktree → **skip** (no fetch, no scan). This is the cheap gate: no flag → no work.
+- Flag set with an unseen sha → confirm against the ref: `behind=$(git rev-list --count HEAD..main 2>/dev/null)` (one targeted `git fetch origin main` first if a remote and the local ref is stale). `behind` is 0 → mark seen, skip.
+- `behind > 0` and the worktree has **no divergent local commits** (`git rev-list --count main..HEAD` is 0) → **fast-forward automatically**: `git merge --ff-only main`. A fast-forward is conflict-free by definition, so do it without asking; report *"pulled {N} commit(s) from main (checkpoint integration)."* Mark the sha seen.
+- `behind > 0` **and** the worktree has diverged → **surface, do not auto-rebase**: *"main advanced on {surfaces} since this worktree branched — rebase onto main? (`git rebase main`)"* — rebase can conflict; the operator decides.
+
+Cross-machine note: the flag file is machine-local, so a worktree on another laptop relies on the opt-in `forge.worktree_rebase_check` / a periodic fetch instead — eventual, not instant.
+
+**Ready-to-merge nudge (main checkout / streams without checkpoints).** If `.forge/streams/active.yml` exists, scan for streams with `status: ready` or a non-empty `merge_queue` **that are not auto-publishing via checkpoints**. Any present → one line: *"{N} stream(s) ready to merge — run `/chief-of-staff` (merge safe) to integrate."* Pointer only — the cadence logic lives in the Chief's Merge Cadence Check; `forge` never merges. Nothing pending → silent.
+
 ### 1.0 State Rollup (index.yml is derived)
 
 `index.yml` is a **derived registry** — regenerate it from the milestone files before reading, and after any milestone CRUD (promote/defer/resume/delete). **Never hand-edit `index.yml`.**
@@ -74,7 +85,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 +100,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/planning/SKILL.md

@@ -188,7 +188,7 @@ Plan naming reflects the slice: `plan-01-user-signs-up.md`, not `plan-01-models.
 1. `.forge/templates/plan.md` -> `.forge/phases/milestone-{id}/{phase}-{name}/plan-{NN}.md`
    - `{id}`=milestone, `{phase}`=phase# (preserved verbatim, NOT renumbered), `{name}`=kebab, `{NN}`=seq
    - Ex: `.forge/phases/milestone-3/2-providers/plan-01.md`
-2. Frontmatter: phase, plan#, wave, deps, `slice_exception:` (optional, see Core Principle)
+2. Frontmatter: phase, plan#, wave, deps, `slice_exception:` (optional, see Core Principle), `integration_checkpoint:` (optional, see below)
 3. must_haves:
    - **Truths:** User-observable outcomes (3-7). MUST be phrased as something the user can see, click, or receive -- not "model X exists" or "table Y created".
    - **Artifacts:** Must exist, substantive not stubs. Slice plans typically span 2-4 layers (e.g., component + handler + repo).
@@ -205,6 +205,15 @@ Plan naming reflects the slice: `plan-01-user-signs-up.md`, not `plan-01-models.
 </task>
 ```
 
+#### Integration Checkpoints (merge often and early)
+
+Mark the phases where a verified slice should **land on main**, so a stream integrates continuously instead of batching at milestone end (FORGE.md → Stream Integration Checkpoints). Set `integration_checkpoint: true` in the plan frontmatter for those phases.
+
+- **Default heuristic to propose:** the milestone's **last phase**, plus **any phase another stream or phase depends on** (a depended-on slice should be on main before its dependents build against it).
+- **Advisory — propose, don't impose.** Surface the suggested checkpoints and let the operator confirm/adjust: *"Mark phases {N, …} as integration checkpoints? Verified work there fast-forwards onto main automatically."*
+- **The mark is the opt-in.** A plan with no `integration_checkpoint` never auto-publishes — leave it unset for phases that should not land mid-flight (spikes, exploratory work, anything not independently shippable).
+- Only the **producer** (a worktree session) acts on the mark; `verifying` does the fast-forward-only publish on PASS. In a single-checkout project the mark is a no-op.
+
 #### Plan Anchors (drift-resistant references)
 
 Tasks reference concrete code — symbols, paths, line numbers, contract shapes, versions. These are **anchors**: snapshotted at planning time, relied on at execution time, *after* the codebase has moved. Make them re-derivable instead of fragile:

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

@@ -292,6 +292,28 @@ After PASSED verdict:
 2. **Persist** — Confirm verification report documented, desire-path files written to `.forge/state/desire-paths/`
 3. **Update state** — Set `current.status` to `reviewing` in `.forge/state/milestone-{id}.yml`
 4. **State-sync commit** (State Commit Protocol): `git add .forge/` then `git commit -m "chore(forge): sync state after verifying — m{N} {phase-name}"` (scoped; never `git add .`).
-5. **Recommend clear:** *"State synced. `/clear` then `/forge` for reviewing."*
+5. **Integration Checkpoint Publish** (see below) — if this phase is a checkpoint and the session is a worktree, fast-forward-only publish to main.
+6. **Recommend clear:** *"State synced. `/clear` then `/forge` for reviewing."*
 
 If GAPS found, route back to planning in gap-closure mode. Context clear applies after re-verified PASSED verdict.
+
+### Integration Checkpoint Publish (merge often and early)
+
+Realizes producer-side continuous integration (FORGE.md → Stream Integration Checkpoints). Runs at Phase Handoff step 5, **only when all hold**:
+
+- the phase's plan frontmatter has `integration_checkpoint: true`;
+- the verdict is PASSED **and** `current.human_verified` is set (where required) — never publish unverified work;
+- the session is a **worktree** (`git rev-parse --git-dir` ≠ `--git-common-dir`). In a single checkout, skip — there is no main to fast-forward into.
+
+Then publish **fast-forward only**:
+
+```bash
+# Push this worktree's verified commits to main. FF-only is the safety:
+# git refuses a non-ff push, so a diverged main is surfaced, never forced.
+git push origin HEAD:main            # remote present
+# no remote → fast-forward the local main ref where possible, else report ready-to-ff
+```
+
+- **Success** → set the integration flag for sibling worktrees: write `.git/forge/integration-pending` (in the git common dir) with the new main sha, this stream/milestone, and the shared surfaces this phase changed. Report: *"Checkpoint published — phase {N} fast-forwarded onto main; siblings will pick it up on next boot."*
+- **Rejected (non-ff — main diverged)** → **do not force.** Surface: *"main has advanced since this worktree branched — publish needs a manual merge/rebase first."* Leave the work on the branch; the Chief's Merge Cadence Check / a human resolves it.
+- Never auto-resolve a conflict, never force-push.

package/template/.forge/FORGE.md

@@ -37,6 +37,17 @@ 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.
 
+**Merge often and early.** Integrate ready work **as soon as it is ready**, not at milestone end. Long-lived stream branches drift from main, shared surfaces go stale, and the merge gets larger and riskier the longer it waits — the opposite of the merge discipline streams exist to provide. The default posture is continuous integration, realized two ways: **producer-side** by publishing at verified checkpoints (below), and **project-side** by the Chief's Merge Cadence Check (cross-stream order + streams without checkpoints). Forge never force-pushes, never auto-resolves a conflict, and never auto-rebases.
+
+### Stream Integration Checkpoints
+
+Integration is **event-driven, not polled**: a stream publishes its work to main at plan-marked phase boundaries, and a lightweight flag tells sibling worktrees there is something to pull. No flag set → boot does no integration work.
+
+- **Checkpoints (plan-marked).** `planning` marks selected phases as integration checkpoints (`integration_checkpoint: true` in the plan frontmatter) — the points where a verified slice should land on main. Default heuristic: the last phase, plus any phase another stream/phase depends on. Advisory — planning proposes, the operator confirms. **The mark is the opt-in:** a plan with no marked checkpoint never auto-publishes, so existing/unmarked work is unaffected.
+- **Producer — publish on verified checkpoint (fast-forward only).** When `verifying` returns PASS for a checkpoint phase *and the session is a worktree*, it integrates that phase to main with a **fast-forward-only** push: `git push origin HEAD:main`. Git rejects a non-ff push — that *is* the safety: a diverged main is surfaced for a human merge, never force-pushed. On success it sets the **integration flag**. (No remote → fast-forward local `main` where possible, else record ready-to-ff for the primary checkout.)
+- **Flag (cheap, set by the producer).** A marker in the shared git common dir — `.git/forge/integration-pending` — records the new main sha, the publishing stream, and the shared surfaces that changed. It is shared across all of a repo's worktrees on a machine, so any boot reads it for free; absent or already-seen → skip. The `main` ref is the source of truth the marker points at. Cross-machine (the marker is machine-local) falls back to the opt-in `forge.worktree_rebase_check` / a periodic fetch — eventual, not instant.
+- **Consumer — auto fast-forward, else prompt.** `forge` boot in a worktree checks the flag. Flag set (main advanced past this worktree's merge-base) and the worktree has **no divergent local commits** → **fast-forward it automatically** (`git merge --ff-only main`) and report — a fast-forward is conflict-free by definition, so it is safe without asking. Worktree has **diverged** → **surface a rebase prompt** (never auto-rebase; rebase can conflict and needs human judgment). Flag not set → no fetch, no scan, continue boot.
+
 ### 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)).
@@ -232,14 +243,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.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/migrations/0.35.0-merge-often-and-early.md

@@ -0,0 +1,56 @@
+# Migration Guide: Merge often and early (Forge 0.35.0)
+
+Applies to every project that uses Chief/Streams, but it is **framework-behavior
+only — nothing on disk to migrate**. The change lives in framework-owned files
+that `upgrading` overwrites for you (`FORGE.md`, `chief-of-staff`, `forge`
+skills) (issue [#8](https://github.com/Attuned-Media/forge/issues/8)).
+
+## What changed
+
+Stream integration was pull-based and deferred — a delivered + verified stream
+sat on its branch until someone manually merged at milestone end, drifting from
+main and staling shared surfaces. 0.35.0 makes **continuous integration** the
+default posture:
+
+- **Stated principle** in `FORGE.md` Project Streams: *merge often and early —
+  integrate ready work as soon as it is ready.* Surfacing only; Forge never
+  auto-merges or auto-rebases.
+- **`chief-of-staff` Merge Cadence Check** (advisory, run at Show + Sync):
+  ready-to-merge surfacing from `active.yml` `status: ready` + `merge_queue`, an
+  idle-ready nudge, a sibling-rebase nudge when main advanced on a shared surface,
+  and a merge-order recommendation.
+- **`forge` boot** gains a light ready-to-merge nudge (one line pointing at
+  `/chief-of-staff`) when `active.yml` shows ready streams.
+
+The `merge_queue:` block already exists in the `active.yml` template — no schema
+change. The Chief just keeps it current and surfaces it.
+
+## Prerequisites
+
+1. On the new version's framework files (`npx forge-orkes upgrade`, or the
+   `upgrading` skill).
+
+## Detection
+
+No on-disk migration — the behavior ships in framework-owned files the upgrade
+already overwrote, and `active.yml` already carries `merge_queue`. Intentional
+no-op:
+
+```bash
+# Skill-behavior change only — merge cadence lives in chief-of-staff/forge/FORGE.md,
+# all framework-owned and synced by the upgrade. active.yml merge_queue is unchanged.
+exit 0
+```
+
+## Migration steps
+
+None. After the upgrade, the next `/chief-of-staff` Show/Sync runs the Merge
+Cadence Check, and `/forge` boot nudges when ready streams exist.
+
+## Validation
+
+- `grep -c 'Merge Cadence Check' .claude/skills/chief-of-staff/SKILL.md` returns ≥ 1.
+- `grep -c 'Merge often and early' .forge/FORGE.md` returns ≥ 1.
+- With a stream at `status: ready` in `.forge/streams/active.yml`, run
+  `/chief-of-staff show` — it lists the stream under **Ready to merge** with an
+  "integrate now" recommendation, and never merges on its own.

package/template/.forge/migrations/0.36.0-stream-integration-checkpoints.md

@@ -0,0 +1,66 @@
+# Migration Guide: Stream Integration Checkpoints (Forge 0.36.0)
+
+Applies to projects that run Chief/Streams in worktrees, but it is
+**framework-behavior only — nothing on disk to migrate**. The change lives in
+framework-owned files that `upgrading` overwrites (`FORGE.md`, `planning`,
+`verifying`, `forge`, `chief-of-staff`), and it is **fully opt-in**: a phase only
+auto-publishes once its plan is marked `integration_checkpoint: true`, so
+existing plans are unaffected until you choose to mark one.
+
+This is the event-driven follow-up to 0.35.0's "merge often and early" (issue
+[#8](https://github.com/Attuned-Media/forge/issues/8)).
+
+## What changed
+
+Continuous integration becomes producer-driven and event-based instead of polled:
+
+- **`planning`** marks integration-checkpoint phases (`integration_checkpoint:
+  true` in plan frontmatter; default heuristic = last phase + depended-on
+  phases; advisory).
+- **`verifying`** (producer): on a PASSED + human-verified checkpoint phase in a
+  worktree, fast-forward-only publishes to main (`git push origin HEAD:main` —
+  git rejects a non-ff, which is the safety; a diverged main is surfaced, never
+  forced) and sets an integration flag at `.git/forge/integration-pending` (git
+  common dir, shared across a machine's worktrees).
+- **`forge` boot** (consumer): in a worktree, reads the flag cheaply — set + no
+  divergence → auto `git merge --ff-only main` (conflict-free); diverged →
+  surface a rebase prompt; not set → skip. Supersedes the 0.35.0 boot polling
+  pointer.
+
+No state-shape change: the plan field is new and optional, and the flag lives in
+`.git/` (machine-local runtime), not tracked state.
+
+## Prerequisites
+
+1. On the new version's framework files (`npx forge-orkes upgrade`, or the
+   `upgrading` skill).
+
+## Detection
+
+No on-disk migration — behavior ships in framework-owned files the upgrade
+overwrote; the plan field and the `.git/` flag are created lazily on first use.
+Intentional no-op:
+
+```bash
+# Skill-behavior change only — checkpoint publish/consume lives in
+# planning/verifying/forge/FORGE.md (framework-owned, synced by the upgrade).
+# The optional plan field + .git/forge flag are created on first use; nothing to migrate.
+exit 0
+```
+
+## Migration steps
+
+None. To start using it: when `planning` next runs, accept the proposed
+integration checkpoints (or add `integration_checkpoint: true` to a plan's
+frontmatter). Verified work in those phases will fast-forward onto main from its
+worktree, and sibling worktrees pick it up on next `/forge` boot.
+
+## Validation
+
+- `grep -c 'Stream Integration Checkpoints' .forge/FORGE.md` returns ≥ 1.
+- `grep -c 'integration_checkpoint' .claude/skills/planning/SKILL.md` returns ≥ 1.
+- `grep -c 'Integration Checkpoint Publish' .claude/skills/verifying/SKILL.md`
+  returns ≥ 1.
+- With a checkpoint phase verified in a worktree, main fast-forwards to include
+  it and `.git/forge/integration-pending` is written; a sibling worktree's next
+  `/forge` boot fast-forwards (clean) or prompts to rebase (diverged).

package/template/.forge/releases.yml

@@ -97,6 +97,21 @@ releases:
     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."
+  - milestone: 16
+    version: "0.35.0"
+    bump: minor
+    reserved_at: "2026-06-21"
+    summary: "Merge often and early (issue #8). Stream integration was pull-based and deferred — ready work sat on its branch until milestone end, drifting from main and staling shared surfaces. Adds the stated principle to FORGE.md Project Streams (continuous integration posture; surfacing only, never auto-merge/auto-rebase). chief-of-staff gains an advisory Merge Cadence Check (Show + Sync): ready-to-merge surfacing from active.yml status:ready + merge_queue, idle-ready nudge, sibling-rebase nudge when main advanced on a shared surface, and merge-order recommendation. forge boot gains a light ready-to-merge nudge pointing to chief-of-staff. All advisory — never blocks, never merges, never rebases."
+  - milestone: 16
+    version: "0.36.0"
+    bump: minor
+    reserved_at: "2026-06-21"
+    summary: "Stream Integration Checkpoints — event-driven continuous integration, the producer/flag/consumer follow-up to #8's polling-based cadence check. (1) planning marks integration_checkpoint phases in plan frontmatter (advisory; default = last phase + depended-on phases; the mark is the opt-in so unmarked/existing work is unaffected). (2) Producer: verifying, on a PASSED + human-verified checkpoint phase in a worktree, fast-forward-only publishes to main (git push origin HEAD:main — git rejects non-ff, which is the safety; diverged main is surfaced, never forced) and sets an integration flag in .git/forge/integration-pending (git common dir, shared across a machine's worktrees). (3) Consumer: forge boot in a worktree reads the flag cheaply — set + no divergence → auto git merge --ff-only main (conflict-free); diverged → surface a rebase prompt; not set → skip (no fetch, no scan). Supersedes the 0.35.0 forge-boot polling pointer with event-driven detection. Cross-machine falls back to opt-in worktree_rebase_check. Never force-pushes, auto-resolves a conflict, or auto-rebases."
 
 # 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