forge-orkes 0.36.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.36.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 + Merge Cadence 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 + Merge Cadence 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
@@ -262,7 +259,7 @@ reason it cannot merge yet.
 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.
+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
@@ -304,7 +301,8 @@ line (`merge cadence: nothing ready, no rebases needed`) and continue.
 
 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.
 

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

@@ -45,7 +45,9 @@ git worktree list --porcelain 2>/dev/null \
 
 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.
+**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)
 

package/template/.forge/FORGE.md

@@ -202,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)
@@ -215,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).
 
@@ -237,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.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

@@ -112,6 +112,11 @@ releases:
     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