forge-orkes 0.34.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.34.0",
+  "version": "0.37.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

@@ -41,12 +41,13 @@ questions return to the Chief before work continues.
 
 ## Context Loading
 
-1. Read `.forge/streams/active.yml` first.
-2. If missing, create it from `.forge/templates/streams/active.yml`.
-3. Load only the selected stream's `.forge/streams/{stream}.yml`.
-4. Load the selected stream's `brief.md` when the user needs status, handoff,
+`active.yml` is **derived** (ADR-015) — regenerate it, don't read a possibly-stale copy and never hand-edit it.
+
+1. **Run the Stream Rollup** (below) to regenerate `.forge/streams/active.yml` from the per-stream files + active milestones, then read it. No `streams/` dir and no active milestones → nothing to roll up.
+2. The per-stream files `.forge/streams/{stream}.yml` are the **source of truth** — load the selected stream's file for detail.
+3. Load the selected stream's `brief.md` when the user needs status, handoff,
    conflict context, or resume context.
-5. Load work packages only when delegating, checking worker status, or closing
+4. Load work packages only when delegating, checking worker status, or closing
    a stream.
 
 Keep summaries in the registry short. Deep history belongs in stream briefs,
@@ -56,54 +57,50 @@ 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 Stream Rollup + Merge Cadence Check, then summarize the derived 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" | Update per-stream files from briefs, run Stream Rollup + Merge Cadence Check to regenerate the derived registry |
 | 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.
+## Stream Rollup (active.yml is derived)
+
+`active.yml` is a **derived projection**, not a hand-maintained registry — it is
+regenerated by joining the per-stream files with active milestones (ADR-015,
+FORGE.md → Stream Rollup). This **replaces** the old advisory Registry Drift Check:
+drift between the milestone view and the stream view can no longer occur, because
+every field has one source and coverage is computed into the artifact. Run the
+rollup at the **start of Show and Sync**, and after any Start/Resume/Pause/Close
+edit to a stream file.
+
+Procedure (deterministic + idempotent — never hand-edit `active.yml`):
+
+1. Glob `.forge/streams/{stream}.yml`. Each → a row: `coordination` = the file's
+   `status`; plus goal, runtime (branch/worktree), ownership summary,
+   `merge_readiness` (from `merge.readiness`), `blocked_by`, `next_action`.
+2. For a stream with `stream.milestone: m-{id}`, read `phase` + activity from
+   `.forge/state/milestone-{id}.yml` (`current.status`, `last_updated`) — do not
+   store workflow phase in the stream file. Linked milestone `deferred`/`complete`/
+   absent → `phase` reflects that (and surface it: a deferred milestone's stream
+   should likely pause; offer it).
+3. Glob active milestones (`index.yml` `status: active`). Any with **no** stream
+   file → emit a derived `stream: implicit` row (phase from the milestone, no
+   coordination) so coverage is guaranteed — an active milestone is never silently
+   missing. Offer to materialize a stream file if it needs coordination (never
+   auto-create).
+4. Derive `merge_queue:` — one entry per stream with `merge.readiness: ready`.
+5. Write `active.yml` (`version`, `updated_at`, derived `streams:` sorted by id,
+   derived `merge_queue:`). No hand-edited keys.
+
+Note: invoked directly, `/chief-of-staff` does not run `forge`'s milestone Rollup,
+so `index.yml` may be slightly stale; read it as-is for step 3 and suggest a
+`/forge` pass if it looks off. The Chief writes `active.yml` (derived class); it
+never writes `index.yml` or any milestone file.
 
 ## Start Stream Flow
 
@@ -117,7 +114,7 @@ proceed with the requested Show/Sync.
    - `.forge/streams/{id}.yml` from `.forge/templates/streams/stream.yml`
    - `.forge/streams/{id}/brief.md` from `.forge/templates/streams/brief.md`
    - `.forge/streams/{id}/packages/`
-5. Add a compact entry to `.forge/streams/active.yml`.
+5. Set the new stream file's `stream.milestone` link if it backs a milestone (else leave null for a standalone stream), then **regenerate `active.yml` via the Stream Rollup** — do not hand-write a registry entry.
 6. Declare ownership:
    - `owned_surfaces` for files or areas the stream may edit
    - `shared_surfaces` for contracts, APIs, schemas, or docs touched with care
@@ -133,7 +130,7 @@ user asks to move to Chief/Streams. Do not teardown, merge, rebase, or remove
 worktrees as part of adoption. Adoption only creates stream metadata around
 existing M10 state.
 
-1. Read or create `.forge/streams/active.yml`.
+1. Ensure the `.forge/streams/` dir exists (`active.yml` is derived — it will be regenerated by the rollup in step 8, not hand-created).
 2. Discover live M10 worktrees from both sources:
    - `git worktree list --porcelain` branches matching `refs/heads/forge/m-*`
    - `.forge/state/milestone-*.yml` with
@@ -174,7 +171,7 @@ existing M10 state.
    - known blockers
    - unknown ownership surfaces marked as needing declaration
    - next action from milestone state or "declare ownership and sync"
-8. Add or update the compact entry in `.forge/streams/active.yml`.
+8. **Regenerate `active.yml` via the Stream Rollup** (do not hand-write the entry); set the adopted stream's `stream.milestone` link so its phase derives from milestone state.
 9. Run conflict detection. Missing ownership is a conflict until clarified, but
    it does not block adoption.
 10. Ask before changing `.forge/project.yml`:
@@ -190,14 +187,14 @@ or path, update its summary and brief instead of creating a duplicate stream.
 Pause:
 1. Update the stream brief with current state, decisions, blockers, and next
    action.
-2. Set registry status to `paused`, unless work was handed to another session
-   and should be `delegated`.
+2. Set the **stream file's** `status` to `paused` (or `delegated` if handed off),
+   then regenerate `active.yml` via the Stream Rollup.
 3. Clear `current_stream` only if no stream remains active in this session.
 
 Resume:
-1. Load registry, stream file, and brief.
+1. Run the Stream Rollup, then load the stream file and brief.
 2. Surface status, blockers, owned surfaces, shared surfaces, and next action.
-3. Set the stream to `active`.
+3. Set the **stream file's** `status` to `active`, then regenerate `active.yml`.
 4. Run conflict detection before continuing.
 
 ## Delegate Flow
@@ -256,11 +253,56 @@ 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 Stream Rollup (which gives it a fresh derived registry).
+
+**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.
 2. Record final outcome in the stream brief.
-3. Update registry status to `closed`.
+3. Set the **stream file's** `status` to `closed`, then regenerate `active.yml`
+   via the Stream Rollup.
 4. Clear `current_stream` if this was the active stream.
 5. Keep closed stream history available until a later archive/compaction pass.
 
@@ -273,9 +315,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

@@ -36,6 +36,19 @@ git worktree list --porcelain 2>/dev/null \
 - 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.
+
+**Stream Rollup (active.yml is derived).** If `.forge/streams/` has any stream files, regenerate `.forge/streams/active.yml` from them + active milestones per FORGE.md → Stream Rollup, the same way step 1.0 regenerates `index.yml`. `active.yml` is derived — never read it as authoritative without rolling up first, and never hand-edit it. Runs in the main checkout (worktrees never write `active.yml`). No `streams/` dir → skip.
+
+**Ready-to-merge nudge (main checkout / streams without checkpoints).** From the just-regenerated `active.yml`, scan for streams with `coordination: 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`.**

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)).
@@ -191,8 +202,8 @@ State lives in `.forge/`:
 - `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` — 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/active.yml` — **DERIVED** Project Chief traffic map. Regenerated by the Stream Rollup from the per-stream files + active milestone files (see Stream Rollup below). **Never hand-edited**, like `index.yml`. Each row carries the two orthogonal dimensions side by side: `phase` (from the milestone, for milestone-backed streams) and `coordination` (from the stream file). See [ADR-015](../docs/decisions/ADR-015-derived-stream-registry.md).
+- `streams/{stream}.yml` — Per-stream **source of truth**: coordination lifecycle, ownership, shared surfaces, blockers, merge readiness, and an optional `stream.milestone: m-{id}` link. Standalone (quick-fix) streams own their `status` here; milestone-backed streams omit workflow phase (the rollup reads it from the milestone).
 - `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)
@@ -204,6 +215,15 @@ State lives in `.forge/`:
 
 **Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions. Can be deferred (frozen in place) or archive-deleted.
 `index.yml status` gates routing: `not_started | active | deferred | complete`.
+
+**Stream Rollup (`active.yml` is derived).** Mirrors the milestone Rollup: `active.yml` is a pure projection, regenerated — never hand-edited — by a deterministic, idempotent **join** of two single-sourced inputs (ADR-015). Run by the main/orchestrator session and at `chief-of-staff` Show/Sync; worktrees never write it. Procedure:
+1. Glob `streams/{stream}.yml`. Each → a row carrying its coordination state (`coordination` = the file's `status`), goal, runtime, ownership summary, `merge.readiness`, blockers, next action — all from the stream file.
+2. For a stream with `stream.milestone: m-{id}`, read `phase`/activity from `milestone-{id}.yml` (`current.status`, `last_updated`) — **not** stored in the stream file. A linked milestone that is `deferred`/`complete`/absent → the row's `phase` reflects that.
+3. Glob active milestones (from `index.yml`). Any active milestone with **no** stream file → emit a derived `stream: implicit` row (phase from the milestone, no coordination state) so coverage is guaranteed in the artifact — an active milestone can never be silently missing.
+4. Derive `merge_queue:` — one entry per stream with `merge.readiness: ready`.
+5. Write `active.yml` (`version`, `updated_at`, derived `streams:` sorted by id, derived `merge_queue:`). No hand-edited keys.
+
+Because each field has exactly one source and coverage is computed, the two-registry drift class (issue #4) cannot occur — this **supersedes** the advisory Registry Drift Check shipped in 0.33.0.
 **Format**: YAML for machine state, Markdown for human content.
 **`current.status` is authoritative.** Complete only at `current.status == complete`. 100% tasks ≠ done — still needs verifying + reviewing + a recorded human sign-off (`current.human_verified` — see Verification Gates → Human Verification Gate).
 
@@ -226,7 +246,7 @@ 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. |
+| **Derived** | `state/index.yml`, `streams/active.yml` | Never hand-edited. Regenerated by rollup from their sources (`index.yml` ← `milestone-*.yml` via Rollup 1.0; `active.yml` ← per-stream files + active milestones via the Stream Rollup). Only the main/orchestrator session (and `chief-of-staff` for `active.yml`) 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) | 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. |

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/migrations/0.37.0-derived-stream-registry.md

@@ -0,0 +1,78 @@
+# Migration Guide: Derived stream registry / Stream Rollup (Forge 0.37.0)
+
+Applies to projects using Chief/Streams that have a **hand-maintained
+`.forge/streams/active.yml` with stream entries**. `active.yml` becomes a
+**derived projection** (ADR-015) — regenerated by the Stream Rollup from the
+per-stream files + active milestones, never hand-edited. This is the durable fix
+for issue [#4](https://github.com/Attuned-Media/forge/issues/4) and supersedes
+the 0.33.0 Registry Drift Check.
+
+The only thing that needs migrating is **data that lives only in `active.yml`**:
+if a stream was tracked as a registry row but has no `.forge/streams/{stream}.yml`
+source file, the rollup (which reads per-stream files) would drop it. The
+migration materializes those files first, then lets the rollup regenerate
+`active.yml`.
+
+Projects with no streams, or whose `active.yml` is the empty stub, need nothing —
+the next `forge` boot / `chief-of-staff` Show simply regenerates it in the derived
+shape. (That is why Detection only fires when there are real stream rows.)
+
+## Prerequisites
+
+1. On the new version's framework files (`npx forge-orkes upgrade`, or the
+   `upgrading` skill).
+2. Working tree clean or changes committed — the migration writes per-stream
+   files and rewrites `active.yml`.
+
+## Detection
+
+Fires only when `active.yml` is the **old hand-maintained shape** (no derived
+marker) **and** carries real stream rows. Silent otherwise — already derived, no
+streams, or no file:
+
+```bash
+F=.forge/streams/active.yml
+[ -f "$F" ] || exit 0
+grep -q 'DO NOT HAND-EDIT' "$F" && exit 0       # already derived (new template marker)
+if grep -qE '^[[:space:]]*-?[[:space:]]*id:[[:space:]]*\S' "$F"; then
+  echo "MIGRATE — active.yml is hand-maintained with stream entries (pre-ADR-015); materialize per-stream files, then it becomes derived"
+fi
+```
+
+## Migration steps
+
+### 1. Ensure every registry stream has a source file
+
+For each stream row in the current `active.yml`, confirm a
+`.forge/streams/{id}.yml` exists. For any that don't, create one from
+`.forge/templates/streams/stream.yml` and copy the row's data into it:
+
+- `stream.status` ← the row's status (coordination lifecycle);
+- `stream.milestone` ← `m-{id}` if the stream backs a milestone, else leave
+  `null` (standalone / quick-fix stream);
+- `runtime.branch` / `runtime.worktree`, `ownership.*`, `merge.readiness`,
+  `blockers`, `next_action` ← from the row.
+
+Do **not** copy a workflow phase into the stream file — that derives from the
+linked milestone.
+
+### 2. Regenerate `active.yml` (derived)
+
+Run `chief-of-staff` Show (or `/forge` boot) — it runs the Stream Rollup and
+rewrites `active.yml` in the derived shape (header marker, `phase` + `coordination`
+per row, derived `merge_queue`, plus `implicit` rows for active milestones with no
+stream file). From here `active.yml` is regenerated, never hand-edited.
+
+<!-- Lossy step (materializing files from registry rows) — confirm with the user
+before writing if any row's data is ambiguous. Runs via quick-tasking. -->
+
+## Validation
+
+- `head -5 .forge/streams/active.yml` shows the `DERIVED — DO NOT HAND-EDIT`
+  marker.
+- Every stream that was in the old registry has a `.forge/streams/{id}.yml`
+  source file.
+- Re-running `chief-of-staff` Show produces byte-identical `active.yml` (the
+  rollup is idempotent).
+- No active milestone is missing from the map (active milestones with no stream
+  file appear as `stream: implicit` rows).

package/template/.forge/releases.yml

@@ -102,6 +102,21 @@ releases:
     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."
+  - milestone: 16
+    version: "0.37.0"
+    bump: minor
+    reserved_at: "2026-06-22"
+    summary: "Derived stream registry / Stream Rollup (ADR-015) — the durable structural fix for issue #4's registry drift, superseding the 0.33.0 advisory Registry Drift Check. streams/active.yml becomes a DERIVED projection (like state/index.yml), never hand-edited, regenerated by a deterministic join-rollup over two single-sourced inputs: per-stream files streams/{stream}.yml (coordination lifecycle + ownership/runtime/merge/blockers) and active milestone files (workflow phase). Resolves the not-1:1 milestone↔stream relationship by keeping workflow phase and coordination status as orthogonal dimensions side by side in each derived row (phase from milestone, coordination from stream file) rather than collapsing one into the other; coverage is computed (active milestone with no stream file → derived 'implicit' row) so #4's exact symptom is structurally impossible. Adds stream.milestone link field (lazy; absent ⇒ standalone). forge boot + chief-of-staff Show/Sync run the Stream Rollup; chief Start/Pause/Resume/Close/Adopt write per-stream files then regenerate. Registry Drift Check removed. active.yml put in the derived state-ownership class (ADR-011); worktrees never write it. Migration: materialize per-stream files from a hand-maintained active.yml, then regenerate."
 
 # 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/streams/active.yml

@@ -1,32 +1,45 @@
 # Forge Streams — Active Project Map
-# Size gate: keep this file <= 20 KB. It is the Project Chief's default context.
-# Store summaries only. Deep stream history belongs in streams/{stream}/.
+#
+# DERIVED — DO NOT HAND-EDIT. This file is a projection regenerated by the
+# Stream Rollup (FORGE.md → Stream Rollup) from two sources:
+#   - per-stream files  .forge/streams/{stream}.yml   (coordination + stream-only state)
+#   - active milestones .forge/state/milestone-*.yml   (workflow phase)
+# Edit those sources, then let `forge` boot or `chief-of-staff` Show/Sync
+# regenerate this file. Hand edits are overwritten on the next rollup.
+#
+# Size gate: keep this file <= 20 KB. Summaries only; deep history lives in
+# streams/{stream}/. See ADR-015.
 
 version: 1
-updated_at: null
+updated_at: null                 # set by the rollup
 
 project_chief:
   current_stream: null
   merge_policy: "chief-owned"
   notes: ""
 
+# Each row is DERIVED. `phase` comes from the linked milestone (milestone-backed
+# rows); `coordination` comes from the stream file. `stream: implicit` marks an
+# active milestone that has no stream file yet (coverage — materialize a stream
+# file if it needs coordination).
 streams:
   # - id: "billing-retries"
-  #   status: active              # draft | active | paused | delegated | blocked | ready | merged | closed
+  #   stream: explicit            # explicit (has a stream file) | implicit (milestone-only)
+  #   milestone: "m-12"           # link, if milestone-backed; absent ⇒ standalone
+  #   phase: executing            # DERIVED from milestone current.status (backed rows only)
+  #   coordination: active        # DERIVED from stream file status: draft|active|paused|delegated|blocked|ready|merged|closed
   #   goal: "Fix checkout retry handling"
   #   branch: "forge/stream-billing-retries"
   #   worktree: "../app-worktrees/billing-retries"
-  #   owner: ""                   # session/thread/user label
-  #   owned_surfaces:
-  #     - "src/billing/**"
-  #   shared_surfaces:
-  #     - "src/lib/events.ts"
+  #   owned_surfaces: ["src/billing/**"]
+  #   shared_surfaces: ["src/lib/events.ts"]
+  #   merge_readiness: not_ready  # not_ready | ready | blocked | merged
   #   risk: medium                # low | medium | high | unknown
   #   blocked_by: []
   #   next_action: "Review event contract before editing shared surface"
-  #   last_sync: null
   []
 
+# DERIVED — one entry per stream whose stream file has merge.readiness: ready.
 merge_queue:
   # - stream: "billing-retries"
   #   status: waiting             # waiting | merging | blocked | merged

package/template/.forge/templates/streams/stream.yml

@@ -7,7 +7,10 @@ version: 1
 stream:
   id: ""
   goal: ""
-  status: draft                    # draft | active | paused | delegated | blocked | ready | merged | closed
+  status: draft                    # COORDINATION lifecycle: draft | active | paused | delegated | blocked | ready | merged | closed
+  milestone: null                  # link to a milestone (e.g. "m-12"); null ⇒ standalone (quick-fix) stream.
+                                   # Set → Stream Rollup derives workflow `phase` from the milestone; do NOT
+                                   # duplicate workflow status here. This `status` stays the coordination dimension.
   tier: null                       # quick | standard | full | null until known
   created_at: null
   updated_at: null