forge-orkes 0.31.0 → 0.32.0

package/package.json

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

@@ -0,0 +1,238 @@
+---
+name: chief-of-staff
+description: "Coordinate multiple active Forge streams. Use for explicit stream intents, mid-flow pivots, delegated work, cross-stream conflict checks, and merge ordering."
+---
+
+# Chief Of Staff
+
+Project-level traffic control for concurrent Forge work. The Chief owns the
+project stream registry, stream lifecycle, conflict checks, context switching,
+delegation, merge order, and closeout.
+
+Use this skill when the user explicitly asks about streams, Chief of Staff, or
+parallel application work. Do not route ordinary single-feature work here by
+default. Inside each stream, continue to use Forge's Quick, Standard, and Full
+tiers for actual execution.
+
+## Operating Model
+
+Forge has three coordination layers:
+
+| Layer | Owner | Purpose | Default context |
+|-------|-------|---------|-----------------|
+| Project | Project Chief | Active streams, conflicts, pivots, merge order | `.forge/streams/active.yml` |
+| Stream | Stream Chief or lead session | One coherent line of application work | `.forge/streams/{stream}.yml` + `brief.md` |
+| Work Package | Worker session | Delegated bounded task | `.forge/streams/{stream}/packages/{id}.yml` |
+
+Workers never coordinate laterally. A worker reports to its stream chief or the
+Project Chief. Scope expansion, shared-surface edits, and cross-stream conflict
+questions return to the Chief before work continues.
+
+## Stream States
+
+- `draft` - described but not ready for active work
+- `active` - currently being driven in this session
+- `paused` - safe to resume later; context snapshot is current
+- `delegated` - worker session or external session is carrying the stream
+- `blocked` - cannot proceed until a dependency, decision, or conflict clears
+- `ready` - implementation is ready for merge or verification
+- `merged` - stream work has landed in the integration branch
+- `closed` - final outcome recorded; no active coordination remains
+
+## 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,
+   conflict context, or resume context.
+5. 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,
+packages, plans, verification reports, commits, and archived artifacts.
+
+## Supported Intents
+
+| Intent | Examples | Action |
+|--------|----------|--------|
+| Show | "show streams", "active streams", "what is running?" | Summarize registry without loading all deep history |
+| Start | "start stream X", "new stream for billing" | Snapshot current stream, create stream files, register stream |
+| Pause | "pause stream X" | Update brief, mark paused, keep next action explicit |
+| Resume | "resume stream X" | Load stream context, set active, surface blockers and ownership |
+| Delegate | "delegate stream X", "farm this out" | Create or update a work package and handoff prompt |
+| Adopt M10 | "adopt existing M10 worktrees", "migrate active orchestrating sessions" | Wrap live M10 worktrees as streams without teardown |
+| Sync | "sync streams" | Refresh registry summaries from active stream briefs |
+| 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 |
+
+## Start Stream Flow
+
+1. Read the registry.
+2. If another stream is active, snapshot its current state:
+   - update `.forge/streams/{stream}/brief.md`
+   - set `next_action`
+   - mark it `paused`, `delegated`, or leave `active` only if work continues
+3. Create a stable stream id from the goal, such as `billing-webhooks`.
+4. Create:
+   - `.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`.
+6. Declare ownership:
+   - `owned_surfaces` for files or areas the stream may edit
+   - `shared_surfaces` for contracts, APIs, schemas, or docs touched with care
+   - `read_only_surfaces` for context only
+   - `forbidden_surfaces` for explicit exclusions
+7. If ownership is uncertain, start read-only and ask for a narrower boundary.
+8. Run conflict detection before making edits.
+
+## Adopt Existing M10 Worktrees Flow
+
+Use this when a repo already has `orchestrating` / M10 worktrees running and the
+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`.
+2. Discover live M10 worktrees from both sources:
+   - `git worktree list --porcelain` branches matching `refs/heads/forge/m-*`
+   - `.forge/state/milestone-*.yml` with
+     `lifecycle.worktree_mode: active` or `degraded`
+3. For each discovered worktree, read its milestone state when available:
+   - milestone id and name
+   - `current.status`, `current.phase`, `current.phase_name`
+   - `lifecycle.worktree_path`
+   - `lifecycle.worktree_branch`
+   - `lifecycle.worktree_anchor`
+   - `lifecycle.session_id`
+   - `lifecycle.claim_session_id`
+   - blockers or refused/degraded reason
+4. Create a stable stream id. Prefer a slug from milestone id + name, for
+   example `m16-chief-streams`. If only the branch is known, derive from the
+   branch suffix.
+5. For each adopted stream, create if missing:
+   - `.forge/streams/{id}.yml`
+   - `.forge/streams/{id}/brief.md`
+   - `.forge/streams/{id}/packages/`
+6. Populate the stream file:
+   - `stream.id`, `goal`, `status`, `tier`
+   - `runtime.branch` from `lifecycle.worktree_branch`
+   - `runtime.worktree` from `lifecycle.worktree_path`
+   - `runtime.worker_sessions` with the M10 session / claim ids
+   - `ownership.owned_surfaces`, `shared_surfaces`, and `read_only_surfaces`
+     as empty lists if unknown
+   - `blockers` from milestone blockers or degraded/refused notes
+   - `context.milestone` pointing at `.forge/state/milestone-{id}.yml`
+7. Populate the stream brief with:
+   - current milestone/phase/status
+   - worktree path and branch
+   - 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`.
+9. Run conflict detection. Missing ownership is a conflict until clarified, but
+   it does not block adoption.
+10. Ask before changing `.forge/project.yml`:
+    - If the user confirms Chief should be the front door, set
+      `orchestration.auto: false`.
+    - If not confirmed, leave legacy M10 auto-routing unchanged.
+
+Adoption is idempotent. If a stream already references the same worktree branch
+or path, update its summary and brief instead of creating a duplicate stream.
+
+## Pause And Resume Flow
+
+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`.
+3. Clear `current_stream` only if no stream remains active in this session.
+
+Resume:
+1. Load registry, stream file, and brief.
+2. Surface status, blockers, owned surfaces, shared surfaces, and next action.
+3. Set the stream to `active`.
+4. Run conflict detection before continuing.
+
+## Delegate Flow
+
+1. Confirm the stream has a clear goal and ownership boundary.
+2. Copy `.forge/templates/streams/work-package.yml` to
+   `.forge/streams/{stream}/packages/{id}.yml`.
+3. Include goal, owned/read-only/forbidden surfaces, deliverables, verification
+   commands, stop conditions, and reporting target.
+4. Mark the stream `delegated` if the worker owns the next action.
+5. Tell the worker to report back to the Chief, not to other workers.
+6. If the worker finds conflicts, missing contracts, blocked verification, or
+   scope expansion, they stop and report back before editing outside package
+   scope.
+
+If the work-package template is not present yet, create the smallest package
+shape that preserves goal, surfaces, deliverables, stop conditions, and next
+reporting step. Phase 25 upgrades this to the full schema.
+
+Delegation prompt must name the package path and the reporting target:
+
+```text
+Work from `.forge/streams/{stream}/packages/{id}.yml`.
+Edit only `scope.owns`.
+Read `scope.may_read` for context.
+Do not touch `scope.must_not_touch`.
+Report conflicts, missing contracts, blocked verification, or scope expansion
+back to the Chief. Do not coordinate directly with other workers.
+```
+
+## Detect Conflicts
+
+Compare all `active`, `delegated`, and `ready` streams:
+
+- overlapping `owned_surfaces` means serialize, split, or block one stream
+- `owned_surfaces` overlapping another stream's `shared_surfaces` requires a
+  reservation, contract, or explicit merge order
+- overlapping `shared_surfaces` requires a named contract owner
+- overlapping `read_only_surfaces` is safe
+- missing ownership is a conflict until clarified
+
+Record conflicts in both the registry and the affected stream files. Do not let
+workers resolve cross-stream conflicts directly.
+
+## Merge Safe Flow
+
+Use "merge safe" to identify streams that can land:
+
+1. Candidate stream status must be `ready`.
+2. No blockers may be open.
+3. Owned surfaces must not overlap another active or ready stream.
+4. Shared surfaces must have a contract owner and documented validation.
+5. Verification commands or manual validation must be listed.
+6. Merge order must be explicit when more than one stream is ready.
+
+If any condition fails, mark the stream blocked or keep it ready with a named
+reason it cannot merge yet.
+
+## 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`.
+4. Clear `current_stream` if this was the active stream.
+5. Keep closed stream history available until a later archive/compaction pass.
+
+## Output Shape
+
+Keep Chief responses short and operational:
+
+```text
+Streams:
+- billing-webhooks — active — owns api/billing, shared db/schema — next: verify webhook retries
+- settings-ui — paused — owns app/settings — next: resume form validation
+
+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.
+```

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

@@ -45,10 +45,12 @@ Never accumulate decisions in working memory. Never batch writes to convergence.
 `context.md` is **shared mutable** state per FORGE.md State Ownership — writes follow two structural rules:
 - **Scope to your milestone's block.** Different milestone blocks → git merges cleanly across worktrees.
 - **Append-only within a block.** When superseding an older decision, *strike through* (`~~old decision~~`) and append the new line below — never rewrite in place. Same-line concurrent edits become impossible by construction; reading the history of a decision becomes possible by inspection.
+- **Keep active context active.** Write current/open decisions to `.forge/context.md`. Do not rehydrate old milestone blocks from `.forge/context-archive.md` unless the user is amending that historical decision.
 
 **On first decision of the session:**
 - Check if `.forge/context.md` exists. If not → create it from `.forge/templates/context.md`
 - Add a milestone heading inside `## Locked Decisions`: `### M{id} — {name} (drafting)` (use "M?" if no milestone yet)
+- If the needed historical decision is archived, cite the archive in the new active decision instead of copying the whole block back.
 - **Cross-tree liveness check (informational).** If editing an existing block for milestone `{id}`, run `git worktree list --porcelain | awk '/^branch / && $2 ~ /refs\/heads\/forge\/m-'"$id"'(-|$)/ {print}'`. Any hit means m{id} is **live in another worktree** — surface one line: *"m{id} is live in worktree at `{path}`. Edits land cleanly on main but won't be visible to that worktree until it rebases or pulls."* Proceed with the write — main is often the canonical author of `context.md`, this is a heads-up, not a block.
 
 **On each confirmed decision:**

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

@@ -163,7 +163,12 @@ No `project.yml` + Standard/Full → **Step 2A**. State exists → **Step 2B**.
 
 ## Step 1.5: Lifecycle Operations
 
-Before tier detection, check if user request matches lifecycle patterns:
+Before tier detection, check if user request matches stream or lifecycle patterns:
+- "show streams" / "active streams" / "what streams are active" / "stream status" → **Show Streams**
+- "start stream {name}" / "new stream {name}" / "create stream {name}" / "pivot to {work}" → **Start Stream**
+- "pause stream {id}" / "resume stream {id}" / "delegate stream {id}" / "sync streams" → **Manage Streams**
+- "detect conflicts" / "check stream conflicts" / "merge safe" / "close stream {id}" → **Manage Streams**
+- "Chief of Staff" / "Project Chief" / "use streams" / "parallel workstreams" → **Chief**
 - "defer milestone {id}" / "defer {id}" / "pause milestone {id}" → **Defer**
 - "resume milestone {id}" / "undefer {id}" / "reactivate milestone {id}" → **Resume**
 - "delete milestone {id}" / "archive milestone {id}" / "remove milestone {id}" → **Delete** (see below)
@@ -171,6 +176,22 @@ Before tier detection, check if user request matches lifecycle patterns:
 
 No match → fall through to Step 2B (tier detection).
 
+### Chief / Stream Operations
+
+1. Invoke `Skill(chief-of-staff)` directly.
+2. Do not enter tier detection. The Chief is project-level traffic control, not
+   a replacement for Forge's Quick, Standard, or Full tiers.
+3. Use Chief only for explicit stream intents, concurrent application work,
+   mid-flow pivots, delegated work, conflict detection, merge ordering, or
+   closing streams.
+4. Ordinary single-stream feature work still follows normal tier detection.
+   Once inside a stream, the stream uses Quick/Standard/Full for execution.
+
+Examples:
+- "show streams" → `Skill(chief-of-staff)` summarizes `.forge/streams/active.yml`
+- "start stream settings cleanup" → `Skill(chief-of-staff)` snapshots current stream, creates a new stream, and checks conflicts
+- "merge safe?" → `Skill(chief-of-staff)` lists ready streams that can land without blocking conflicts
+
 ### Show Deferred
 
 1. Invoke `Skill(deferred)` directly.
@@ -262,13 +283,17 @@ Tier + state → invoke via `Skill` tool. All phases use `Skill()`.
 
 **CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
-**Experimental — M10 orchestration (auto-routes when installed).** Installing M10 *is* the consent: `forge` then auto-routes Standard/Full work through `orchestrating` **before** `executing` — no separate invocation to remember. Route through `Skill(orchestrating)` first when **all** hold:
+**Experimental — M10 orchestration backend.** Chief/Streams is the preferred
+user-facing orchestration model. M10 remains an optional backend for streams
+that need worktree isolation, merge-queue discipline, or experimental file
+claims. Route through `Skill(orchestrating)` first when **all** hold:
+- **Selected:** Project Chief chooses M10 for a stream, user explicitly asks for multi-agent/worktree mode, or legacy `orchestration.auto` is enabled.
 - **Installed:** `.claude/skills/orchestrating/` present + `forge-orchestrator` in `.mcp.json` + `.claude/hooks/forge-claim-check.sh` present.
-- **Not opted out:** `orchestration.auto` in `project.yml` ≠ `false` (absent = on; install = consent per ADR-001).
+- **Not opted out:** `orchestration.auto` in `project.yml` ≠ `false` for legacy auto-routing; explicit Project Chief selection can still use M10 when installed.
 - **Tier is Standard or Full.** Quick never auto-orchestrates (a worktree per typo is the wrong trade).
 - **Not already in a session:** active milestone has no `lifecycle.worktree_mode: active|degraded` (don't re-bootstrap inside a live session).
 
-`orchestrating` bootstrap stays the safety net — incompatible repo → it refuses, writes `worktree_mode: refused`, and `forge` continues single-agent. Absent install → standard routing. Manual `Skill(orchestrating)` still works for explicit control; set `orchestration.auto: false` in `project.yml` to opt back out.
+`orchestrating` bootstrap stays the safety net — incompatible repo → it refuses, writes `worktree_mode: refused`, and `forge` continues single-agent. Absent install → standard routing. Manual `Skill(orchestrating)` still works for explicit backend control; set `orchestration.auto: false` in `project.yml` to opt out of legacy auto-routing.
 
 ### Auto-Routing (Always Deterministic)
 
@@ -307,6 +332,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 | discussing | sonnet | Conversation |
 | testing | sonnet | Code gen (author) + audit judgment (analyst) — matches executing/reviewing. M9: author-mode refuses e2e without `e2e:true` + `validated:true`. |
 | deferred | haiku | Read + format only |
+| chief-of-staff | sonnet | Cross-stream coordination and conflict judgment |
 
 | `current.status` | Route To |
 |-------------------|----------|
@@ -322,6 +348,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 | `deferred` | Milestone frozen. *"Resume milestone {id}" to reactivate.* |
 | `quick-tasking` | `Skill(quick-tasking)` |
 | (keyword: `deferred` / "show deferred") | `Skill(deferred)` — read-only aggregator |
+| (keyword: `show streams` / `start stream` / `merge safe` / `Chief of Staff`) | `Skill(chief-of-staff)` — project stream coordination |
 
 ### Status Advancement Check
 

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

@@ -32,6 +32,11 @@ If you find yourself writing a plan that only touches `src/models/`, `src/db/`,
 Read `.forge/context.md` **Needs Resolution**. If unchecked `- [ ]` items:
 *"{N} items need input: [list]. For each: lock, defer, fix, or drop?"*
 
+Load `.forge/context.md` as the active decision set. Consult
+`.forge/context-archive.md` only when the current milestone, stream, or
+requirement cites an older milestone decision (for example M9 e2e policy or M14
+backlog lifecycle). Do not load archived decision blocks wholesale.
+
 | Choice | Action |
 |--------|--------|
 | Lock | Record in Locked Decisions |
@@ -61,6 +66,10 @@ If missing, create `.forge/context.md` from template:
 
 Must complete BEFORE plans. Plans reference context.md.
 
+If a plan depends on an archived decision, cite the archive section in the plan
+or active context summary; do not copy the historical block back into
+`.forge/context.md`.
+
 ## Step 4: Structure Requirements
 
 Resolve current milestone ID from `.forge/state/index.yml` (active milestone) or invocation context. Target file: `.forge/requirements/m{N}.yml`.

package/template/.forge/FORGE.md

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

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

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

package/template/.forge/releases.yml

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

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

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

package/template/.forge/templates/migration-guide.md

@@ -106,5 +106,6 @@ must be confirmed with the user.>
 - [ ] Exactly one `## Detection` heading; exactly one ` ```bash ` block under it.
 - [ ] Block emits `MIGRATE` on stdout iff the migration applies; silent + exit 0 otherwise.
 - [ ] Block is safe on a clean/empty project (no errors, exit 0).
+- [ ] Any new accumulating artifact declares owner, size gate, archive/compaction rule, derived vs source-of-truth status, and future migration behavior.
 - [ ] Mirrored byte-identical to `docs/migrations/{same-name}.md`.
 - [ ] No edit to `upgrading/SKILL.md` or `create-forge.js` was needed (the loop covers it).

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

@@ -0,0 +1,34 @@
+# 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}/.
+
+version: 1
+updated_at: null
+
+project_chief:
+  current_stream: null
+  merge_policy: "chief-owned"
+  notes: ""
+
+streams:
+  # - id: "billing-retries"
+  #   status: active              # 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"
+  #   risk: medium                # low | medium | high | unknown
+  #   blocked_by: []
+  #   next_action: "Review event contract before editing shared surface"
+  #   last_sync: null
+  []
+
+merge_queue:
+  # - stream: "billing-retries"
+  #   status: waiting             # waiting | merging | blocked | merged
+  #   reason: "shared event contract pending"
+  []

package/template/.forge/templates/streams/brief.md

@@ -0,0 +1,47 @@
+# Stream Brief: {stream}
+
+Size gate: keep this brief <= 8 KB. It is the first file loaded when resuming a stream.
+
+## Goal
+
+{One sentence describing the line of work.}
+
+## Current State
+
+Status: draft | active | paused | delegated | blocked | ready | merged | closed
+
+{What is true right now? Include whether code has changed, whether workers are active, and whether merge is safe.}
+
+## Ownership
+
+Owned surfaces:
+- {paths/modules this stream may edit}
+
+Shared surfaces:
+- {paths/modules requiring contract or Project Chief approval}
+
+Read-only surfaces:
+- {paths/modules this stream may inspect but not edit}
+
+Forbidden surfaces:
+- {paths/modules this stream must not touch}
+
+## Decisions
+
+- {Locked decisions that apply to this stream}
+
+## Findings
+
+- {Recent findings needed to resume without chat history}
+
+## Work Packages
+
+- {WP-id}: {status} — {short goal}
+
+## Blockers
+
+- {blocker or "none"}
+
+## Next Action
+
+{The next concrete action for the stream chief or worker.}

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

@@ -0,0 +1,56 @@
+# Forge Stream State
+# Copy to .forge/streams/{stream}.yml.
+# Size gate: keep per-stream state <= 15 KB. Put narrative in brief.md or findings.md.
+
+version: 1
+
+stream:
+  id: ""
+  goal: ""
+  status: draft                    # draft | active | paused | delegated | blocked | ready | merged | closed
+  tier: null                       # quick | standard | full | null until known
+  created_at: null
+  updated_at: null
+  owner: ""
+
+runtime:
+  branch: ""
+  worktree: ""
+  chief_session: ""
+  worker_sessions: []
+
+ownership:
+  owned_surfaces: []
+  shared_surfaces: []
+  read_only_surfaces: []
+  forbidden_surfaces: []
+  reservations:
+    # - surface: "src/lib/events.ts"
+    #   reason: "Event contract update"
+    #   status: proposed          # proposed | approved | blocked | released
+    []
+
+dependencies:
+  blocked_by_streams: []
+  blocks_streams: []
+  contracts: []
+
+context:
+  brief: ".forge/streams/{stream}/brief.md"
+  findings: ".forge/streams/{stream}/findings.md"
+  packages_dir: ".forge/streams/{stream}/packages"
+
+blockers:
+  # - type: decision | conflict | external | human-action
+  #   summary: ""
+  #   since: null
+  #   resolution: ""
+  []
+
+merge:
+  readiness: not_ready              # not_ready | ready | blocked | merged
+  risk: unknown                     # low | medium | high | unknown
+  required_checks: []
+  notes: ""
+
+next_action: ""

package/template/.forge/templates/streams/work-package.yml

@@ -0,0 +1,70 @@
+# Forge Work Package Template
+# Bounded delegated work for a single stream.
+# Copy to: .forge/streams/{stream}/packages/{id}.yml
+
+package:
+  id: "{package-id}"
+  stream: "{stream-id}"
+  title: ""
+  status: draft                  # draft | assigned | active | blocked | ready | returned | closed
+  created_at: "{ISO-8601}"
+  updated_at: "{ISO-8601}"
+  owner: ""                      # worker session, person, or agent label
+  reports_to: "chief-of-staff"   # Project Chief or stream chief
+
+goal:
+  summary: ""
+  observable_outcome: ""
+  non_goals: []
+
+scope:
+  owns:
+    # Files, dirs, modules, routes, or contracts this worker may edit.
+    - ""
+  may_read:
+    # Context surfaces the worker may inspect but should not edit.
+    - ""
+  shared_surfaces:
+    # APIs, schemas, data contracts, docs, or config shared with other streams.
+    - surface: ""
+      contract_owner: ""
+      rule: "report changes before editing"
+  must_not_touch:
+    # Explicit exclusions. Any need to edit these returns to the Chief.
+    - ""
+
+dependencies:
+  blocked_by: []
+  provides_to: []
+  contracts_required: []
+
+verify:
+  commands:
+    # - cmd: "npm test -- ..."
+    #   advisory: false
+  manual_checks: []
+  evidence_required: []
+
+stop_conditions:
+  - "Need to edit must_not_touch or undeclared shared surface"
+  - "Find conflicting ownership with another stream"
+  - "Contract is missing, ambiguous, or contradicted by implementation"
+  - "Task scope expands beyond the package goal"
+  - "Verification cannot be run or fails for reasons outside package scope"
+
+deliverables:
+  - "Changed files or commits"
+  - "Verification evidence"
+  - "Decision notes or conflicts found"
+  - "Recommended next action"
+
+handoff:
+  instructions: ""
+  report_back:
+    to: "chief-of-staff"
+    include:
+      - "what changed"
+      - "what was verified"
+      - "conflicts or scope expansion"
+      - "open risks"
+      - "next action"