forge-orkes 0.30.0 → 0.32.0

package/bin/create-forge.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const { execSync } = require('child_process');
 
 const templateDir = path.join(__dirname, '..', 'template');
 const targetDir = process.cwd();
@@ -349,144 +350,117 @@ async function install() {
 }
 
 /**
- * Detect pre-0.10.0 requirements layouts (single top-level file, suffixed top-level,
- * or per-phase files). Returns array of legacy paths found, relative to project root.
+ * Extract the first fenced ```bash block under a guide's `## Detection` heading.
+ * Returns the script string, or null if the guide has no such block (e.g. a
+ * non-conformant guide). State-machine parse — no markdown dependency.
  */
-function detectLegacyRequirementsLayout() {
-  const forgeDir = path.join(targetDir, '.forge');
-  if (!fs.existsSync(forgeDir)) return [];
-
-  const legacy = [];
-
-  for (const entry of fs.readdirSync(forgeDir, { withFileTypes: true })) {
-    if (!entry.isFile()) continue;
-    if (entry.name === 'requirements.yml') {
-      legacy.push(path.join('.forge', entry.name));
-    } else if (/^requirements-m\d+\.yml$/.test(entry.name)) {
-      legacy.push(path.join('.forge', entry.name));
+function extractDetectionBlock(guideContent) {
+  const lines = guideContent.split('\n');
+  let inDetection = false;
+  let inCode = false;
+  const code = [];
+  for (const line of lines) {
+    if (!inDetection) {
+      if (/^##\s+Detection\b/.test(line)) inDetection = true;
+      continue;
     }
-  }
-
-  const phasesDir = path.join(forgeDir, 'phases');
-  if (fs.existsSync(phasesDir)) {
-    for (const phase of fs.readdirSync(phasesDir, { withFileTypes: true })) {
-      if (!phase.isDirectory()) continue;
-      const reqPath = path.join(phasesDir, phase.name, 'requirements.yml');
-      if (fs.existsSync(reqPath)) {
-        legacy.push(path.join('.forge', 'phases', phase.name, 'requirements.yml'));
-      }
+    // Stop scanning if we hit the next top-level (## ...) heading before a block.
+    if (!inCode && /^##\s/.test(line) && !/^##\s+Detection\b/.test(line)) break;
+    if (!inCode) {
+      if (/^```bash\s*$/.test(line)) inCode = true;
+      continue;
     }
+    if (/^```/.test(line)) break; // closing fence
+    code.push(line);
   }
-
-  return legacy;
+  return code.length ? code.join('\n') : null;
 }
 
 /**
- * Detect a pre-0.17.0 project.yml that has no `layers:` field. Cross-layer
- * contract detection (planning Step 6.1) reads `layers:`; without it the planner
- * falls back to a coarse top-level-directory heuristic. Returns true if the field
- * is absent and no contract index has been seeded. False if project.yml is missing
- * (not yet initialized) or already migrated.
+ * Data-driven post-upgrade migration check. Loops over the migration guides
+ * synced into the project this run (.forge/migrations/{v}-*.md), runs each
+ * guide's `## Detection` block, and on a `MIGRATE` stdout hit prints a warning
+ * with the exact guide pointer. There are NO per-version code branches: a new
+ * guide that ships with a conformant Detection block is auto-covered.
+ *
+ * Range: installed < v <= source. `installedVersion` is the project's
+ * settings.json forge.version captured BEFORE the version stamp; `source` is
+ * pkgVersion (this package's package.json) — never the template settings.json
+ * literal, which is a placeholder the installer stamps at write time. Non-
+ * interactive: the bin only warns and points at the guide; it never applies.
  */
-function detectMissingLayersConfig() {
-  const projectYml = path.join(targetDir, '.forge', 'project.yml');
-  if (!fs.existsSync(projectYml)) return false;
-
-  let content;
-  try {
-    content = fs.readFileSync(projectYml, 'utf-8');
-  } catch {
-    return false;
-  }
-
-  // Already declared a layers: key (any value, including []) → migrated.
-  if (/^layers:/m.test(content)) return false;
-  // A seeded contract index implies layers were declared at init → migrated.
-  if (fs.existsSync(path.join(targetDir, '.forge', 'contracts', 'index.yml'))) return false;
+function runPostUpgradeMigrationChecks(installedVersion) {
+  const migrationsDir = path.join(targetDir, '.forge', 'migrations');
+  if (!fs.existsSync(migrationsDir)) return;
 
-  return true;
-}
+  const installed =
+    installedVersion && installedVersion !== 'unknown' ? installedVersion : '0.0.0';
+  const source = pkgVersion;
 
-/**
- * Detect a pre-0.19.0 state/index.yml: 0.19.0 makes index.yml a thin derived
- * registry (regenerated by rollup) and moves desire_paths to append-only files.
- * A legacy index.yml still carries desire_paths:/metrics:/embedded narrative, or
- * is large. Returns true if index.yml exists and looks legacy; false if missing
- * (not yet initialized) or already a slim registry.
- */
-function detectLegacyStateIndex() {
-  const indexYml = path.join(targetDir, '.forge', 'state', 'index.yml');
-  if (!fs.existsSync(indexYml)) return false;
-
-  let content;
+  // Select in-range guides: installed < v <= source. Parse {v} from the filename.
+  let guides;
   try {
-    content = fs.readFileSync(indexYml, 'utf-8');
+    guides = fs
+      .readdirSync(migrationsDir)
+      .map((name) => {
+        const m = name.match(/^(\d+\.\d+\.\d+)-.*\.md$/);
+        return m ? { name, version: m[1] } : null;
+      })
+      .filter(Boolean)
+      .filter(
+        (g) =>
+          compareVersions(installed, g.version) < 0 &&
+          compareVersions(g.version, source) <= 0
+      )
+      .sort((a, b) => compareVersions(a.version, b.version));
   } catch {
-    return false;
+    return;
   }
 
-  // Legacy markers: shared accumulators or per-milestone narrative drifted in.
-  if (/^\s*(desire_paths|metrics|current_status):/m.test(content)) return true;
-  // A slim registry is small; KBs of index.yml means narrative crept in.
-  if (Buffer.byteLength(content, 'utf-8') > 4096) return true;
+  for (const guide of guides) {
+    const guidePath = path.join(migrationsDir, guide.name);
+    let script;
+    try {
+      script = extractDetectionBlock(fs.readFileSync(guidePath, 'utf-8'));
+    } catch {
+      continue;
+    }
+    if (!script) continue; // no runnable Detection block → treat as no-op
+
+    let stdout = '';
+    try {
+      stdout = execSync(script, {
+        cwd: targetDir,
+        shell: '/bin/bash',
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+    } catch {
+      // A non-zero exit or detection error is a no-op, not a failure — keep going.
+      continue;
+    }
+
+    if (!/MIGRATE/.test(stdout)) continue; // no-op
 
-  return false;
-}
+    const reasonLine = stdout
+      .split('\n')
+      .find((l) => l.includes('MIGRATE'));
+    const reason = reasonLine
+      ? reasonLine.replace(/^.*MIGRATE\s*[—-]?\s*/, '').trim()
+      : '';
 
-/**
- * After upgrade, surface any detected legacy file layouts the new framework
- * version no longer writes, or new config fields older projects lack.
- * Non-interactive — prints a warning with a pointer to the migration guide.
- * Add new detection blocks here as future versions change layout.
- */
-function runPostUpgradeMigrationChecks() {
-  const legacyReqs = detectLegacyRequirementsLayout();
-  if (legacyReqs.length > 0) {
-    console.log('  ⚠  Pre-0.10.0 requirements layout detected');
-    console.log('  ─────────────────────────────────────────');
-    console.log('  Found:');
-    for (const p of legacyReqs) {
-      console.log(`    ${p}`);
-    }
-    console.log();
-    console.log('  Forge 0.10.0+ uses per-milestone files at .forge/requirements/m{N}.yml.');
-    console.log('  Migration guide: .forge/migrations/0.10.0-per-milestone-requirements.md');
+    console.log(`  ⚠  ${guide.version} migration available${reason ? ` — ${reason}` : ''}`);
+    console.log('  ─────────────────────────────────────────────────────────────');
+    console.log(`  Guide: .forge/migrations/${guide.name}`);
+    console.log(
+      `         (canonical: https://github.com/Attuned-Media/forge/blob/main/docs/migrations/${guide.name})`
+    );
     console.log();
-    console.log('  Run the migration before your next planning cycle. In Claude Code:');
+    console.log('  Migrations are never applied automatically. In Claude Code:');
     console.log('    /forge then hand the guide to quick-tasking, or invoke Skill(quick-tasking)');
     console.log('    with the guide path as the task definition.');
     console.log();
   }
-
-  if (detectMissingLayersConfig()) {
-    console.log('  ⚠  Cross-layer contracts: project.yml has no `layers:` field (Forge 0.17.0)');
-    console.log('  ──────────────────────────────────────────────────────────────────────');
-    console.log('  Forge 0.17.0 added cross-layer contract detection (planning Step 6.1),');
-    console.log('  which reads `layers:` from .forge/project.yml. Your project.yml predates');
-    console.log('  this field, so planning falls back to a coarse top-level-directory heuristic.');
-    console.log();
-    console.log('  Migration guide: .forge/migrations/0.17.0-cross-layer-contracts.md');
-    console.log();
-    console.log('  Quick fix: add a `layers:` list to .forge/project.yml — or `layers: []`');
-    console.log('  for a single-layer project to silence this notice. In Claude Code:');
-    console.log('    /forge then hand the guide to quick-tasking.');
-    console.log();
-  }
-
-  if (detectLegacyStateIndex()) {
-    console.log('  ⚠  Worktree-safe state: legacy state/index.yml detected (Forge 0.19.0)');
-    console.log('  ────────────────────────────────────────────────────────────────────');
-    console.log('  Forge 0.19.0 makes index.yml a derived registry (regenerated by rollup),');
-    console.log('  moves desire_paths to append-only files, and commits .forge/ state at every');
-    console.log('  phase handoff. Your index.yml predates this — it still carries desire_paths/');
-    console.log('  metrics or embedded narrative, which conflicts across git worktrees.');
-    console.log();
-    console.log('  Migration guide: .forge/migrations/0.19.0-worktree-safe-state.md');
-    console.log();
-    console.log('  This migration edits user-owned state, so it is guided — never automatic.');
-    console.log('  In Claude Code: /forge then hand the guide to quick-tasking.');
-    console.log();
-  }
 }
 
 async function upgrade() {
@@ -656,7 +630,9 @@ async function upgrade() {
 
   console.log(`  Upgraded to v${pkgVersion}\n`);
 
-  runPostUpgradeMigrationChecks();
+  // Pass the version captured BEFORE upgradeSettings() stamped the new one, so the
+  // migration range is (installed, source] against the freshly-synced guides.
+  runPostUpgradeMigrationChecks(installedVersion);
 }
 
 // --- Entry point ---

package/package.json

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