forge-orkes 0.77.0 → 0.80.0

package/template/.forge/FORGE.md

@@ -1,17 +1,15 @@
 # Forge
 
-Lean meta-prompting framework. Context engineering + constitutional governance on agent-native primitives. This file is the always-loaded **routing/index layer**: tables, invariants, and pointers. Procedures live in the skills that execute them; rationale lives in ADRs — both load only on demand.
+Lean meta-prompting framework. Context engineering + constitutional governance on agent-native primitives. This file is the always-loaded **routing/index layer**: tables, invariants, pointers. Procedures live in the skills that execute them; rationale lives in ADRs — both load on demand only.
 
 ## Critical: No Native Plan Mode
 
-**NEVER use `EnterPlanMode` when Forge active.** Forge writes plans to `.forge/phases/` — native plan mode conflicts.
-
-All phases: **invoke via `Skill` tool**, never native behavior. `planning` → `Skill(planning)`, not `EnterPlanMode`.
+**NEVER use `EnterPlanMode` when Forge active.** Forge writes plans to `.forge/phases/` — native plan mode conflicts. All phases: invoke via `Skill` tool, e.g. `planning` → `Skill(planning)`, not `EnterPlanMode`.
 
 ## Core Principles
 
 1. **Lean default, powerful when needed.** Quick → skip ceremony. Complex → full governance.
-2. **Adapter-native.** Use each platform's built-ins through adapters. Avoid custom runtime unless the substrate truly needs it.
+2. **Adapter-native.** Use each platform's built-ins through adapters; avoid custom runtime unless the substrate 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?"
@@ -21,7 +19,7 @@ All phases: **invoke via `Skill` tool**, never native behavior. `planning` → `
 
 ## 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 — durable behavior, not one platform's tool names. **Platform adapters** translate the protocol into a runtime (Claude Code skills/hooks, Codex/AGENTS behavior, manual multi-session handoffs). Adapter mechanics stay in adapter files and skills; they do not become core requirements.
+**Core protocol** lives in `.forge/`: project/constitution state, milestones, requirements, roadmap, context, streams, work packages, plans, verification, audits, state ownership rules — durable behavior, not one platform's tool names. **Platform adapters** translate the protocol into a runtime (Claude Code skills/hooks, Codex/AGENTS behavior, manual handoffs) and stay out of core requirements.
 
 ## Project Streams
 
@@ -33,18 +31,16 @@ Three runtime coordination layers: Project, Stream, Work Package.
 | **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` |
 
-Ordinary Quick/Standard/Full tiers run inside a stream. Project Chief / Chief of Staff coordinates multiple active streams or pivots without dropping context. Workers never coordinate laterally; they report to the stream or project chief. M10 worktrees are an optional isolation backend, not the primary UX.
+Ordinary Quick/Standard/Full tiers run inside a stream; Project Chief / Chief of Staff coordinates multiple active streams or pivots without dropping context. Workers report to the stream or project chief, never laterally. M10 worktrees are an optional isolation backend, not the primary UX.
 
-**Merge often and early.** Integrate ready work **as soon as it is ready**, not at milestone end — long-lived stream branches drift and the merge grows riskier the longer it waits. Realized producer-side (checkpoint publishing, below) and project-side (the Chief's Merge Cadence Check). Forge never force-pushes, never auto-resolves a conflict, and never auto-rebases.
+**Merge often and early** — integrate ready work as soon as it is ready, not at milestone end (long-lived branches drift, merges grow riskier). Realized producer-side (checkpoint publishing, below) + project-side (the Chief's Merge Cadence Check). Forge never force-pushes, auto-resolves a conflict, or auto-rebases.
 
 ### Stream Integration Checkpoints
 
-Event-driven continuous integration. **Mechanism + rationale: [ADR-027](../docs/decisions/ADR-027-integration-checkpoints-declaration-split.md).** Producer implementation: `verifying` (Integration Checkpoint Publish). Consumer: `forge` boot (Step 1 preflight). In brief:
+Event-driven continuous integration ([ADR-027](../docs/decisions/ADR-027-integration-checkpoints-declaration-split.md)). Producer: `verifying` (Integration Checkpoint Publish). Consumer: `forge` boot (Step 1 preflight).
 
-- **Checkpoints are plan-marked** (`integration_checkpoint: true` in plan frontmatter; planning proposes — last phase + depended-on phases — the operator confirms). **The mark is the opt-in**: unmarked plans never auto-publish.
-- **Producer:** on a checkpoint phase's verified PASS in a worktree session, fast-forward-only publish (`git push origin HEAD:main`), **strand-guarded** — publish only when local `main` is an ancestor of the worktree HEAD; stranded → do not push, surface "integrate through local main first" (forge#13). On success, set the **integration flag** — `.git/forge/integration-pending` in the machine-local git common dir.
-- **Intake (declaration split, B3'):** a new milestone/stream's **first** worktree commit is a declaration — milestone id (+ reservation), one-line intent, stream registration with `ownership` claims — ff-pushed to main immediately; content stays worktree-only until the milestone's own checkpoint. One-breath rule: main knows THAT work exists; the worktree knows WHAT it is.
-- **Consumer:** boot reads the flag (absent or already-seen → skip; no fetch, no scan). Clean fast-forwards run automatically in worktrees **and** the primary main checkout; any divergence surfaces a prompt — never an auto-rebase. Cross-machine, the flag doesn't exist — the opt-in `forge.worktree_rebase_check` / periodic fetch covers it, eventually.
+- **Producer:** plan-marked checkpoints (`integration_checkpoint: true`, operator-confirmed) fast-forward-push on a worktree's verified PASS, strand-guarded (push only if local `main` is an ancestor of HEAD; stranded → "integrate through local main first", forge#13), then set the machine-local integration flag. A stream's first worktree commit is a lighter declaration-only push (id + intent) so main knows work exists before content lands.
+- **Consumer:** boot reads the flag (absent/seen ⇒ skip, no fetch); clean fast-forwards run automatically, any divergence prompts — never auto-rebase. Cross-machine: opt-in `forge.worktree_rebase_check`.
 
 ### Worktree Convention (base)
 
@@ -59,6 +55,8 @@ Where worktrees live and what they're named — single source of truth, base con
 
 **Recorded path is authoritative once set** — `lifecycle.worktree_path` (milestone) / `runtime.worktree` (stream) is read verbatim, never re-derived; changing `worktree_root` affects only new worktrees; move a live worktree only with `git worktree move` + update the record. No recorded path → resolve from the convention. `forge` boot and `chief-of-staff` adoption **validate advisorily**: recorded path outside the resolved root → warn (never block, never move); an explicit `worktree_root` is honored.
 
+**Primary checkout is welded to the default branch — all tiers** ([ADR-031](../docs/decisions/ADR-031-weld-primary-checkout-to-default-branch.md)). Its HEAD is shared across concurrent sessions; a `checkout -b` there silently redirects others' commits. Enforced (`git-dir == git-common-dir` scoped, never touches worktrees): `.claude/hooks/protect-primary-checkout.sh` (PreToolUse — denies branch create/switch/detach + hard-reset) + `.forge/git-hooks/pre-commit` (off-default-commit backstop; wired per-clone by `initializing`/`upgrading` via repo-relative `core.hooksPath`, detect+warn+never-clobber). Branch work: `.forge/bin/new-worktree.sh <slug>`. Escape: `ALLOW_MAIN_BRANCHING=1`.
+
 **`orchestration.worktree_hydrate`** (optional, `project.yml`; forge#18) lists superproject-relative paths to required-but-gitignored artifacts (e.g. `.mcp.json`) a fresh worktree's tracked-only checkout lacks. Copy is guarded `source-exists && dest-absent` — never overwrites, never `git add`s, so the secret stays untracked in both trees. Applied by `orchestrating` at creation and re-asserted idempotently in `executing`'s Workspace Prerequisites, covering worktrees of any origin. Omit ⇒ no propagation. The per-worktree runtime counterpart of the install-time carve-out propagation below (State Ownership § Stable shared).
 
 ## Workflow Tiers
@@ -66,9 +64,9 @@ Where worktrees live and what they're named — single source of truth, base con
 Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 
 ### Prototyping (minutes–hours, disposable)
-**Triggers:** "mock up"/"sketch"/"prototype"/"draw up"/"iterate on the UI"/"explore how X could look" — disposable in-app visual exploration behind an alpha/feature flag, no requirements locked yet
+**Triggers:** disposable in-app visual exploration ("mock up", "sketch", "prototype", "explore how X could look") behind an alpha/feature flag, no requirements locked yet
 **Flow:** `prototyping` — establish flag → iterate ⟲ (render → react → adjust) → resolve (graduate→milestone | park | discard)
-**No verify/review gate by design** — the deliverable is a thing to look at and react to, not shippable code. Real UI work with known requirements is Standard + `designing` (which *does* gate on quality). See [ADR-022](../docs/decisions/ADR-022-prototyping-tier.md).
+**No verify/review gate by design** — a thing to look at and react to, not shippable code. Real UI work with known requirements is Standard + `designing` (which *does* gate on quality). See [ADR-022](../docs/decisions/ADR-022-prototyping-tier.md).
 
 ### Quick (minutes)
 **Triggers:** bug fix, typo, config, dep bump, <50 lines
@@ -89,29 +87,27 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 
 ## Skill Routing
 
-| Need to... | Skill | Tier |
-|------------|-------|------|
-| Start any task | `forge` | All |
-| Set up new project | `initializing` | First run |
-| Investigate codebase/tech/requirements | `researching` | Standard, Full |
-| Talk through approach/trade-offs | `discussing` | Standard, Full (on-demand) |
-| Architectural decisions | `architecting` | Full |
-| Break work into tasks with gates | `planning` | Standard, Full |
-| Build with deviation rules + atomic commits | `executing` | All |
-| Prove work delivers on goals (+ M9 e2e validation gate; captures the Human Verification Gate sign-off) | `verifying` | Standard, Full |
-| Audit health + catalog refactoring (+ M9 e2e audits; hard-blocks completion on the Human Verification Gate) | `reviewing` | Standard, Full |
-| Small scoped fix | `quick-tasking` | Quick |
-| Rapid disposable UI mockup behind an alpha flag (no verify/review gate) | `prototyping` | Prototyping |
-| UI with design system | `designing` | When UI |
-| Security review | `securing` | When auth/data/API |
-| E2E/integration tests + suite audit (+ M9 author-mode gate) | `testing` | When UI/flows or flaky suite |
-| Systematic debugging | `debugging` | When stuck |
-| Upgrade Forge files from the npm registry (default; local dev sync only via explicit `/upgrading dev`) | `upgrading` | On-demand |
-| Cross-session memory | `beads-integration` | When Beads installed |
-| Project/read Forge work in Notion | `notion-integration` | When Notion configured |
-| 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`.
+| Need to... | Skill |
+|------------|-------|
+| Start any task | `forge` |
+| First-run project setup | `initializing` |
+| Investigate before building | `researching` |
+| Talk through trade-offs | `discussing` |
+| Architectural decisions | `architecting` |
+| Break work into gated tasks | `planning` |
+| Build with deviation rules + atomic commits | `executing` |
+| Prove goals delivered (+ M9 e2e gate; see Human Verification Gate) | `verifying` |
+| Health/security/refactor gate + close-the-loop | `reviewing` |
+| Small scoped fix | `quick-tasking` |
+| Disposable UI mockup behind an alpha flag | `prototyping` |
+| UI with design system | `designing` |
+| Security review | `securing` |
+| E2E/integration tests + suite audit (+ M9 author-mode gate) | `testing` |
+| Systematic debugging | `debugging` |
+| Upgrade Forge files (registry default; `/upgrading dev` for local sync) | `upgrading` |
+| Cross-session memory | `beads-integration` |
+| Project/read Forge work in Notion | `notion-integration` |
+| Multi-agent backend (experimental — see `packages/create-forge/experimental/m10/README.md`) | `orchestrating` |
 
 ## Context Engineering
 
@@ -123,7 +119,7 @@ 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` |
+| `context.md` | 12 KB | Derived index, rendered fresh every boot — one row per milestone, pointing at `context/{id}.md` (full decisions live there, single-owner-mutable) |
 | `refactor-backlog.yml` | 150 KB | Terminal items archive to `refactor-backlog-archive.yml` (advisory) |
 | `streams/active.yml` | 20 KB | Traffic map must stay cheap to load |
 | `streams/{stream}.yml` | 15 KB | Stream state stays resumable without becoming history |
@@ -134,89 +130,84 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 
 ### Accumulating Artifacts
 
-Every new accumulating artifact declares: owner, size gate, archive/compaction rule, `derived` vs source-of-truth status, and migration behavior. Defaults: `roadmap.yml`, `requirements/*.yml`, `releases.yml`, `reservations.yml` are source-of-truth — load scoped slices, not whole history. `phases/`, `audits/`, `research/`, `archive/`, `context-archive.md`, `reservations-archive.yml` are historical — load only by milestone/stream/package/version (R104: `reservations-archive.yml` holds every row `forge-reserve compact` has dropped from `reservations.yml`, verbatim; the working file alone still carries every kind's floor). `prototypes/{slug}.md` is single-owner mutable while `exploring|parked`; terminal statuses archive to `prototypes/archive/`. Runtime/generated files (`.mcp-server/*.db*`, logs, spike DBs, `.git/forge/*`) are excluded from framework context unless debugging them. The board (ADR-025): `.forge/notion/map.yml` is derived, git-ignored, rebuildable; board config is the `board:` block in `project.yml` (absent ⇒ inert). Template copies sync mechanically — not separate concepts.
+Every new accumulating artifact declares owner, size gate, archive/compaction rule, `derived` vs source-of-truth status, migration behavior. `roadmap.yml`, `requirements/*.yml`, `releases.yml`, `reservations.yml` are source-of-truth — load scoped slices, not whole history. `phases/`, `audits/`, `research/`, `archive/`, `context-archive.md`, `reservations-archive.yml` are historical — load only by milestone/stream/package/version (R104: `reservations-archive.yml` holds every row `compact` dropped; the working file keeps each kind's floor). `prototypes/{slug}.md` is single-owner while `exploring|parked`; terminal → `prototypes/archive/`. Runtime/generated files (`.mcp-server/*.db*`, logs, spike DBs, `.git/forge/*`) are excluded unless debugging. Board (ADR-025): `.forge/notion/map.yml` is derived; config is `board:` in `project.yml` (absent ⇒ inert). Template copies sync mechanically.
 
 ### Fresh Agent Pattern
-Task touches 20+ files or complex subsystem → spawn fresh executor with isolated context. Prevents context rot.
+20+ files or a complex subsystem → spawn a fresh executor with isolated context. Prevents context rot.
 
 ### Context Handoff
-Each phase writes outputs to `.forge/` before completing. At phase boundaries, recommend `/clear`; the next phase loads from disk. Advisory — skip for short phases under 40% context.
+Each phase writes outputs to `.forge/` before completing; at boundaries recommend `/clear`, next phase loads from disk. Advisory — skip under 40% context.
 
 ### Lazy Loading
-Skills load only when invoked. Active context is `.forge/context.md`; consult `.forge/context-archive.md` only when older decisions matter.
+Skills load only when invoked. `.forge/context.md` is a derived index (id/name/status/path per milestone) — consult it for orientation, then read the specific `context/{id}.md` when a milestone's actual decisions are needed. `context-archive.md` predates this model and is superseded (its content lives in `context/{id}.md` now); consult it only for pre-0.80.0 history not yet folded in.
 
 ### Rules Layer (`.claude/rules/`)
-Three policy weights, lightest-first (ADR-018): **`constitution.md`** (always-loaded hard gates, 10 KB) → **`.claude/rules/`** (lightweight ambient guidance — always-on, or path-scoped via `paths:` glob at zero cost until a matching file is touched) → **skills** (heavy, opt-in). Core ships one always-on rule, `agent-discipline.md`; stack-specific rules are opt-in (`experimental/conventions/`). Format + authoring: `.claude/rules/README.md` (itself always loaded).
+Three policy weights, lightest-first (ADR-018): `constitution.md` (always-loaded hard gates, 10 KB) → `.claude/rules/` (ambient guidance — always-on, or path-scoped via `paths:` glob at zero cost until a matching file is touched) → skills (heavy, opt-in). Core ships one always-on rule, `agent-discipline.md`; stack-specific rules are opt-in (`experimental/conventions/`). Format + authoring: `.claude/rules/README.md`.
 
 ## Model Routing
 
-Configured in `project.yml` under `models:` — `default`, `parent_session` (advisory), `by_complexity.{trivial|standard|complex}` (per-task, M24), `skills.{name}` (per-skill).
+Configured in `project.yml` under `models:` — `default`, `parent_session` (advisory), `by_complexity.{trivial|standard|complex}` (per-task), `skills.{name}` (per-skill).
 
-**Precedence:** `by_complexity.{task.complexity}` → `skills.X` → `default` → parent model. **Complexity overrides skill** (LOCKED, context.md § M24): a task's `by_complexity` resolution wins over `models.skills.{skill}` — the per-task signal is the granular one; a task with no complexity resolves via the unchanged chain, zero behavior change untagged.
+**Precedence:** `by_complexity.{task.complexity}` → `skills.X` → `default` → parent model. **Complexity overrides skill** (LOCKED, `context.md` § M24) — a task with no complexity resolves via the unchanged chain, zero behavior change untagged.
 
-**All advisory** — forge displays the expected model at each transition and suggests `/model` on mismatch; the review gate logs the model used. Forge cannot auto-switch models.
+**All advisory** — forge displays the expected model at each transition, suggests `/model` on mismatch; the review gate logs the model used. Forge cannot auto-switch models.
 
-**Subagent inheritance.** A skill spawning subagents MUST pass the resolved `model` param explicitly — subagents do NOT inherit skill-level routing (without the param they run on the parent model, defeating the routing intent). Resolve **per task** where the task declares `complexity`, else the skill chain; surface *"Spawning {role} with model: {model} (from {source})"*. An inline task inherits the session model and cannot be re-routed.
+**Subagent inheritance.** A skill spawning subagents MUST pass the resolved `model` param explicitly — subagents do NOT inherit skill-level routing. Resolve per task where it declares `complexity`, else the skill chain; surface *"Spawning {role} with model: {model} (from {source})"*. An inline task inherits the session model.
 
-**Spawn gate — predicate A (LOCKED, context.md § M24; refined m-33).** Executing's mandatory spawn on a complexity-tagged task fires **only when the resolved model differs from the live session model**. Resolved == live — always the case with no `models:` block — makes the spawn a pure no-op, so the tag becomes a context signal only (spawn iff a context trigger independently fires). WHY: an unconditional spawn burned ~315k subagent tokens on m-30 for zero routing benefit.
+**Spawn gate — predicate A (LOCKED, `context.md` § M24; refined m-33).** Executing's mandatory spawn on a complexity-tagged task fires only when the resolved model differs from the live session model — resolved == live (always true with no `models:` block) makes the spawn a no-op, so the tag becomes a context signal only.
 
 ## Agents
 
 | Agent | Role | Tools | When |
 |-------|------|-------|------|
-| `researcher` | Investigation | Read-only (Read, Glob, Grep, WebFetch) | Research |
-| `planner` | Planning + constitutional gates | Read + Write (plan files) | Planning |
+| `researcher` | Investigation | Read-only | Research |
+| `planner` | Planning + constitutional gates | Read + Write (plans) | Planning |
 | `executor` | Building + deviation rules | All dev tools | Execution |
 | `verifier` | Goal-backward verification | Read + Bash (tests) | Verification |
-| `reviewer` | Security + architecture + refactoring (breadth pass, gates the health report) | Read, Bash, Grep, Glob | Reviewing |
-| `tester` | E2E/integration authoring + suite analysis | Dual-mode: author (Write/Edit/Bash/git) · analyst (read-only) | Testing skill |
-| `security-reviewer` | Confidence-gated security depth (≥8, exploit-scenario required) | Read, Grep, Glob, Bash | Optional deep-dive |
-| `performance-reviewer` | Real bottlenecks only (Impact = frequency × cost; ≥8 + ≥Medium) | Read, Grep, Glob, Bash | Optional deep-dive |
-| `doc-reviewer` | Docs-vs-source accuracy (≥8; Blocker/Major/Minor) | Read, Grep, Glob, Bash | Optional deep-dive |
+| `reviewer` | Security/architecture/refactoring (breadth, gates the health report) | Read, Bash, Grep, Glob | Reviewing |
+| `tester` | E2E/integration authoring + suite analysis | Author (Write/Edit/Bash/git) or read-only | Testing skill |
+| `security-reviewer` | Security depth (≥8, exploit-scenario required) | Read, Grep, Glob, Bash | Deep-dive |
+| `performance-reviewer` | Real bottlenecks only (frequency × cost; ≥8 + ≥Medium) | Read, Grep, Glob, Bash | Deep-dive |
+| `doc-reviewer` | Docs-vs-source accuracy (≥8; Blocker/Major/Minor) | Read, Grep, Glob, Bash | Deep-dive |
 
-The three specialist reviewers complement the generalist `reviewer` — single-axis, defensible depth, read-only, pulled in deliberately (from `reviewing` or direct). The 3-mode `reviewer` remains the breadth pass that gates the milestone health report.
+The three specialists complement `reviewer` — single-axis, read-only, pulled in deliberately. `reviewer`'s 3-mode pass remains the breadth gate on the milestone health report.
 
 ## Project Init (First Run)
 
-No `.forge/project.yml` → auto-detect project type:
-
-**Brownfield** (has package.json/src/.git): detect frameworks → absorb → verify docs vs code → scan stack → detect design system → analyze patterns → infer constitution → user confirms.
-
-**Greenfield**: project basics → design system → constitution → state init.
-
-Quick tier skips init.
+No `.forge/project.yml` → auto-detect project type. **Brownfield** (has package.json/src/.git): frameworks → absorb → verify docs vs code → scan stack → design system → patterns → infer constitution → user confirms. **Greenfield**: project basics → design system → constitution → state init. Quick tier skips init.
 
 ## State Management
 
 State lives in `.forge/`. One line per artifact; protocol detail lives in the named ADRs and skills:
 
-- `project.yml` — vision, stack, design system, verification, constraints (<5 KB). Optional `jarvis.dev_lane_cmd` (m-48) is the stack-agnostic seam Jarvis runs to spin up a slice's local dev server for operator UAT before a PR opens; absent ⇒ manual lane start. See `docs/jarvis.md`.
+- `project.yml` — vision, stack, design system, verification, constraints (<5 KB). Optional `jarvis.dev_lane_cmd` (m-48) seams Jarvis's dev-server spin-up for UAT; absent ⇒ manual start (`docs/jarvis.md`).
 - `constitution.md` — active architectural gates
 - `design-system.md` — component mapping table
-- `requirements/m{N}.yml` — per-milestone structured requirements with `[NEEDS CLARIFICATION]` markers. **FR/DEF/NFR ids are globally unique across all milestone files** — reserve via the ID Reservation Protocol before writing. M9 e2e gate fields (`e2e`, `observable_outcome`, `validated`, hash) lazy-migrate; absent ⇒ `false`.
+- `requirements/m{N}.yml` — per-milestone structured requirements, `[NEEDS CLARIFICATION]` markers. **FR/DEF/NFR ids globally unique** — reserve first. M9 e2e gate fields lazy-migrate; absent ⇒ `false`.
 - `roadmap.yml` — phases, milestones, dependencies
-- `state/index.yml` — DERIVED milestone registry, **git-ignored render-on-read cache** (0.53.0): regenerated at every boot by the **`forge-state-rollup.sh` SessionStart hook** (the mechanical port of Rollup 1.0 — issue #22; skill prose only *reads* it) from the milestone files; never committed, never hand-edited; the hook renders it in any checkout (gitignored local write), but worktree agents still never write the *committed* derived-source state; absent on a fresh clone (the project sentinel is `project.yml`). Rows carry the derived `release_state`.
-- **Derived `release_state`** ([ADR-024](../docs/decisions/ADR-024-merged-validated-fold.md)) — `{unmerged, merged, validated}` computed at rollup by `.claude/hooks/forge-release-fold.sh` (git-only, offline; the fold binary is the only source — agent prose never re-derives it), never stored. Validation binding via `forge.validation_event`: `in_session_signoff` (default; absent ⇒ this) or `promotion_approval` (CI-signed `promotion/{sha}` tag). Inert until a repo opts in; full spec in ADR-024 + the fold header.
+- `state/index.yml` — DERIVED milestone registry, git-ignored render-on-read cache (0.53.0), regenerated at boot by `forge-state-rollup.sh` (issue #22; read-only for skills); never committed; absent on a fresh clone (sentinel `project.yml`). Rows carry derived `release_state`.
+- **Derived `release_state`** ([ADR-024](../docs/decisions/ADR-024-merged-validated-fold.md)) — `{unmerged, merged, validated}`, computed at rollup (`forge-release-fold.sh`, git-only, offline), never stored. Binding via `forge.validation_event`: `in_session_signoff` (default) or `promotion_approval` (CI-signed tag); inert until opted in.
 - `state/milestone-{id}.yml` — per-milestone cursor (**single source of truth**): position, decisions, blockers. One owner at a time.
-- `state/desire-paths/` — append-only framework-usage observations, one file per observation, `scope: project|framework` (absent ⇒ project); occurrence counts derived by globbing. **`forge` boot is the single review owner** — surfaces groups at 3+, persists declines (no re-nag), routes `framework`-scope signals upstream ([ADR-012](../docs/decisions/ADR-012-upstream-desire-path-feedback-channel.md)); `verifying` captures but never surfaces.
-- `context.md` — active locked decisions + deferred ideas (≤12 KB); history archives to `context-archive.md`
-- `streams/active.yml` — DERIVED Project Chief traffic map, git-ignored render-on-read cache, rendered by the same `forge-state-rollup.sh` hook — see Stream Rollup below ([ADR-015](../docs/decisions/ADR-015-derived-stream-registry.md))
-- `streams/{stream}.yml` (+ `brief.md`, `packages/{id}.yml`) — per-stream **source of truth**: coordination lifecycle, ownership, shared surfaces, blockers, merge readiness, optional `stream.milestone` link (milestone-backed streams omit workflow phase — the rollup reads it from the milestone)
+- `state/desire-paths/` — append-only usage observations, `scope: project|framework` (absent ⇒ project); counts derived by globbing. `forge` boot is the single review owner — surfaces groups at 3+, persists declines, routes `framework`-scope upstream ([ADR-012](../docs/decisions/ADR-012-upstream-desire-path-feedback-channel.md)); `verifying` captures, never surfaces. Issue-sourced entries carry `resolves_issue: N`.
+- `context/{id}.md` (+ derived `context.md` index) — locked decisions + deferred ideas per milestone; history archives to `context-archive.md`
+- `streams/active.yml` — DERIVED traffic map, git-ignored render-on-read cache, same hook — see Stream Rollup ([ADR-015](../docs/decisions/ADR-015-derived-stream-registry.md))
+- `streams/{stream}.yml` (+ `brief.md`, `packages/{id}.yml`) — per-stream **source of truth**: lifecycle, ownership, surfaces, blockers, merge readiness, optional `stream.milestone` link (rollup reads phase from the milestone)
 - `research/milestone-{id}.md` — dated immutable findings snapshot
 - `phases/milestone-{id}/{phase}-{name}/plan-{NN}.md` — task plans with must_haves frontmatter (`{id}`=milestone, `{phase}`=phase# verbatim, `{name}`=kebab, `{NN}`=seq)
-- `refactor-backlog.yml` — refactoring catalog worked via quick-tasking; status vocab `pending | in_progress | done | dismissed | deferred`; terminal items auto-archive to `refactor-backlog-archive.yml` on the next reviewing/quick-tasking write
+- `refactor-backlog.yml` — quick-tasking catalog; vocab `pending|in_progress|done|dismissed|deferred`; terminal items auto-archive
 - `releases.yml` — append-only version-reservation registry (Version Reservation Protocol)
-- `reservations.yml` — append-only id-reservation audit trail + cross-machine floor (ID Reservation Protocol); `forge-reserve compact` (R104) moves dropped rows verbatim to `reservations-archive.yml`, retaining each kind's max + a 14-day tail
+- `reservations.yml` — append-only id-reservation audit trail + cross-machine floor; `forge-reserve compact` (R104) moves dropped rows to `reservations-archive.yml`, keeping each kind's max + a 14-day tail
+- `state/issue-loop/declined/{N}.yml` — close-the-loop decline markers (no re-nag) from `reviewing`; inert once the issue closes
 - `archive/milestone-{id}/` — archived milestone artifacts (archive-delete)
-- `prototypes/{slug}.md` — resumable disposable-mockup state (`exploring | parked | graduated | discarded`); terminal → `prototypes/archive/`. Single-owner, one driver. See `Skill(prototyping)`.
+- `prototypes/{slug}.md` — disposable-mockup state (`exploring|parked|graduated|discarded`); terminal → `prototypes/archive/`. Single-owner. See `Skill(prototyping)`.
 
-**Milestones** group phases into concurrent streams — own state file, no conflicts across sessions; can be deferred (frozen in place) or archive-deleted. Registry status vocab: `not_started | active | deferred | complete`. **`current.status` is authoritative** — complete only at `current.status == complete`; 100% tasks ≠ done (verifying + reviewing + the recorded human sign-off still gate).
+**Milestones** group phases into concurrent streams — own state file, no cross-session conflicts; deferred (frozen) or archive-deleted. Status vocab: `not_started | active | deferred | complete`. **`current.status` is authoritative** — 100% tasks ≠ done (verifying + reviewing + the recorded human sign-off still gate).
 
 **Format:** YAML for machine state, Markdown for human content.
 
 ### Stream Rollup
 
-`active.yml` is a pure projection — regenerated, never hand-edited — by a deterministic, idempotent **join**: per-stream files contribute coordination state; active milestones contribute `phase` (any active milestone with no stream file gets a derived `implicit` row — coverage is computed, not maintained); `merge_queue` derives from `merge.readiness: ready`. A **step-0 completed-stream auto-close sweep** runs first: a milestone-backed stream whose milestone is `complete`, not yet `closed`, with no live worktree is auto-closed — a done-and-merged milestone can never leave a zombie "ready to merge" row. Rendered mechanically by the **`forge-state-rollup.sh` SessionStart hook** at boot (issue #22 — an executable, not agent prose), and re-run via that same executable at `chief-of-staff` Show/Sync and after any mid-session milestone CRUD; the hook runs the milestone Rollup 1.0 **first** (the join reads the fresh `index.yml`), and confines the committed-source step-0 sweep to the main checkout. **Numbered procedure: the ADR-015 addendum.** Because each field has exactly one source and coverage is computed, two-registry drift cannot occur — supersedes the old advisory Registry Drift Check.
+`active.yml` is a deterministic **join**: per-stream files contribute coordination state; active milestones contribute `phase` (stream-file-less active milestone → derived `implicit` row); `merge_queue` derives from `merge.readiness: ready`. A **step-0 auto-close sweep** closes milestone-backed streams whose milestone is `complete`, not `closed`, with no live worktree. Rendered by the same hook at boot and at `chief-of-staff` Show/Sync/CRUD; Rollup 1.0 runs first, sweep confined to main. Numbered procedure: the ADR-015 addendum — each field has one source, so drift cannot occur.
 
 ### State Commit Protocol
 
@@ -227,7 +218,7 @@ git add .forge/        # scoped — respects .gitignore; never `git add .`
 git commit -m "chore(forge): sync state after {phase} — m{N} {phase-name}"
 ```
 
-**In a worktree session, pin with the recorded path** — `git -C {worktree_path} add/commit` (`lifecycle.worktree_path` is authoritative over cwd; the process cwd can silently reset to the launch checkout across turns, and a wrong-cwd git op can even exit 0). Guard: compare `git rev-parse --show-toplevel` to the recorded path before the first write — full discipline in `executing` (Worktree cwd discipline) and `verifying` (Worktree cwd guard). State-sync commits are separate from per-task code commits (which stay atomic during executing).
+**In a worktree session, pin with the recorded path** — `git -C {worktree_path} add/commit` (cwd can silently reset to the launch checkout across turns; a wrong-cwd op can even exit 0). Guard: compare `git rev-parse --show-toplevel` to the recorded path before the first write — full discipline in `executing`/`verifying`. State-sync commits are separate from per-task code commits.
 
 ### State Ownership (multi-worktree safety)
 
@@ -235,12 +226,12 @@ git commit -m "chore(forge): sync state after {phase} — m{N} {phase-name}"
 
 | 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 checkout currently driving that milestone. Other worktrees never touch it (not even read-then-write; pull from main instead). |
+| **Single-owner mutable** | `state/milestone-{id}.yml`, `phases/milestone-{id}/`, `research/milestone-{id}.md`, `context/{id}.md` | Exactly one writer at a time — the checkout currently driving that milestone. Other worktrees never touch it (not even read-then-write; pull from main instead). |
 | **Single-owner mutable (per stream)** | `streams/{stream}.yml`, `streams/{stream}/brief.md`, `streams/{stream}/packages/*.yml` | The stream's current driver writes them; distinct streams own distinct files — no cross-stream contention. |
-| **Derived (git-ignored render-on-read cache)** | `state/index.yml`, `streams/active.yml`, the rendered `release_state` column | Never hand-edited, **never committed** — regenerated by rollup from sources at every boot. Any session may render its own copy; absence on a fresh clone is normal (render-then-read; the sentinel is `project.yml`). |
+| **Derived (git-ignored render-on-read cache)** | `state/index.yml`, `streams/active.yml`, `context.md`, the rendered `release_state` column | Never hand-edited, **never committed** — regenerated by rollup from sources at every boot. Any session may render its own copy; absence on a fresh clone is normal (render-then-read; the sentinel is `project.yml`). `context.md` specifically joins `context/{id}.md` files with `state/index.yml` (ADR-033). |
 | **Append-only shared** | `releases.yml`, `reservations.yml`, `state/desire-paths/*`, `deferred-issues/*` | Many writers OK; structure prevents collision (append-only entries / distinct filenames). |
 | **Machine-local runtime** | `.git/forge/id-reservations`, `.git/forge/integration-pending` | Git common dir — shared across a machine's worktrees, never git-tracked, excluded from framework context. |
-| **Shared mutable** | `context.md`, `refactor-backlog.yml`, `requirements/m{N}.yml` | Write only your milestone/stream block; within a block, append-only — strike through instead of rewriting. |
+| **Shared mutable** | `refactor-backlog.yml`, `requirements/m{N}.yml` | Write only 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`, `.claude/skills/`, `.claude/agents/` | Rarely changes except via `/upgrading` (registry default — the npm bin is the sync engine; local dev sync only via explicit `/upgrading dev`). Canonical on main; worktrees lag until they rebase. An upgrade touches only its own checkout — `upgrading` Step 8 offers live-worktree rebases (never auto); opt-in `forge.worktree_rebase_check` is the boot-time net. Gitignored carve-outs (`.mcp.json`, experimental hooks) propagate via the experimental installer, not git. |
 
 Ownership rules (quick reference):
@@ -252,11 +243,11 @@ Ownership rules (quick reference):
 
 ### Version Reservation Protocol
 
-The project version + CHANGELOG slot are shared resources — `.forge/releases.yml` (append-only) removes the number from per-milestone scope. **Reserve early, at planning**: derive `max() + bump`, **claim it in the ledger first** — `forge-reserve version --value <X.Y.Z>` (record-only; a conflict names the sibling milestone holding the number, its claim possibly worktree-only — re-read and re-bump; ADR-029) — then append ONE `{milestone, version, bump, reserved_at, summary}` entry and **commit + push the reservation BEFORE editing the version file** so a parallel session sees the number taken. Never edit prior entries. **Delivery never invents a number** — write only the reserved version; no reservation → reserve at delivery (pull, `max() + bump`, append, push, then write). **Race:** the second push rebases onto the first (append-only → clean), re-reads `max()`, takes the next number. **Bump criteria (0.x):** patch = bug fix/doc/sync/refinement; minor = new skill/agent/routing-row/auto-trigger/state-artifact/capability; major = post-1.0 breaking. Default to minor when in doubt — a capability shipped as a patch drifts the version away from truth.
+The version + CHANGELOG slot are shared — `.forge/releases.yml` (append-only). **Reserve at planning**: derive `max() + bump`, claim in the ledger first (`forge-reserve version --value <X.Y.Z>` — conflict names the sibling milestone holding it), append ONE `{milestone, version, bump, reserved_at, summary}` entry, **commit + push before editing the version file**. Never edit prior entries; never invent a number at delivery — no reservation found → reserve then, same steps. Push race → rebase onto the file, re-read `max()`. Bump criteria + race narrative: `planning`'s Reserve-version step + ADR-029.
 
 ### ID Reservation Protocol
 
-Sequential ids — `ADR-NNN`, `DEF-NNN`, `FR-`/`NFR-NNN`, milestone `M-NN`, refactor `R0NN`, roadmap phase/wave numbers — are shared cross-worktree resources; scan-and-increment sees only committed state, so concurrent worktrees claim the same number and collide silently until merge. **Reserve with the helper before creating the artifact**: `forge-reserve <kind> --milestone <id> [--summary <text>]` (`.claude/hooks/forge-reserve.sh`, kinds `adr|def|fr|nfr|milestone|refactor|phase|wave|version`; id formats per [ADR-023](../docs/decisions/ADR-023-extend-id-reservation-to-milestone-refactor-ids.md) + ADR-029 — phase/wave registry tokens are `P-0NN`/`W-0NN` while roadmap.yml keeps bare ints; `version` is record-only via `--value` (the ledger makes in-flight claims sibling-visible; `releases.yml` stays the durable registry)) prints the id and dual-writes the **machine-local ledger** (`.git/forge/id-reservations`, git common dir — the same-machine coordination point, written under a `mkdir` lock) plus the tracked `.forge/reservations.yml` (durable audit trail + cross-machine floor; the caller commits it with the work). **Next number = `max(ledger ∪ in-tree ∪ main:reservations.yml) + 1`** per kind — the in-tree scan includes archives, so a compacted id is never reallocated. Reserve points: `architecting` (adr), `planning` (fr/nfr/def, phase/wave, version), `forge` Rollup / `discussing` / `prototyping` (milestone), `reviewing` (refactor). Deferred issues are counter-free per-issue files (`.forge/deferred-issues/{date}-{milestone}-{slug}.md`) — no DI-NNN, nothing to collide on. Accepted gap: concurrent reserves on *different machines* fall back to merge-time renumber, bounded by the floor. On any residual collision (legacy/un-reserved ids), **keep the older milestone's id and renumber the newer**. Lazy migration — the ledger self-creates on first reserve. Full rationale: [ADR-021](../docs/decisions/ADR-021-id-reservation-ledger-git-common-dir.md) (supersedes ADR-016) + ADR-023 + ADR-029. Versions stay in `releases.yml` (separate semver/CHANGELOG semantics); the ledger only carries their claims.
+Sequential ids (`ADR-NNN`, `DEF-NNN`, `FR-`/`NFR-NNN`, milestone `M-NN`, refactor `R0NN`, roadmap phase/wave) are shared cross-worktree resources — scan-and-increment collides silently until merge. **Reserve before create**: `forge-reserve <kind> --milestone <id> [--summary <text>]` (`.claude/hooks/forge-reserve.sh`, kinds `adr|def|fr|nfr|milestone|refactor|phase|wave|version`). Next id = **`max(ledger ∪ in-tree ∪ main:reservations.yml) + 1`** per kind; residual collision → older milestone keeps the id, newer renumbers. Reserve points: `architecting` (adr), `planning` (fr/nfr/def, phase/wave, version), `forge` Rollup/`discussing`/`prototyping` (milestone), `reviewing` (refactor). Deferred issues are counter-free — nothing to collide on. Full mechanics (ledger + lock, id-format table, cross-machine floor, lazy migration): the helper's header comment + [ADR-021](../docs/decisions/ADR-021-id-reservation-ledger-git-common-dir.md) (supersedes ADR-016) + ADR-023 + ADR-029.
 
 ## Deviation Rules
 
@@ -281,16 +272,16 @@ verification:
     - cmd: "npm run lint"
     - cmd: "npm test"
     - cmd: "npx tsc --noEmit"
-      advisory: true           # pre-existing failures — warn only
-  auto_fix: true               # fix and retry on failure
-  max_retries: 2               # max attempts per command
+      advisory: true      # pre-existing failures — warn only
+  auto_fix: true            # fix and retry on failure
+  max_retries: 2            # max attempts per command
 ```
 
-Auto-detected from `package.json` at init. Advisory mode warns, never blocks. Auto-fix loop: read output → fix → amend → re-run (≤ `max_retries`; retries count toward the 3-strike task limit). Empty commands = no gate (opt-out). `verification.e2e_soft_cap` (default 10) — advisory per-milestone cap on `e2e:true` stories, surfaced by `reviewing`, never blocks.
+Auto-detected from `package.json` at init. Advisory mode warns, never blocks. Auto-fix loop: read output → fix → amend → re-run (≤ `max_retries`; retries count toward the 3-strike limit). Empty commands = opt-out. `verification.e2e_soft_cap` (default 10) — advisory per-milestone cap on `e2e:true` stories, surfaced by `reviewing`, never blocks.
 
 ### Truth checks (executable must_haves)
 
-Plans MAY declare a per-truth `check:` shell command in `must_haves.truths` (exit 0 = pass; authored goal-backward at planning, before code exists; linted by planning Step 8). `executing` runs declared checks once at plan completion (early fix-loop signal, never a verdict); `verifying` re-executes them and applies the **executed-evidence rule**: VERIFIED only with a recorded command + exit code + output excerpt — no executed evidence → UNCERTAIN or human-route, never VERIFIED. Legacy bare-string truths stay valid.
+Plans MAY declare a per-truth `check:` shell command in `must_haves.truths` (exit 0 = pass; authored goal-backward at planning, before code exists). `executing` runs declared checks once at plan completion (early fix-loop signal, never a verdict); `verifying` re-executes, applying the **executed-evidence rule**: VERIFIED only with a recorded command + exit code + output excerpt — no evidence → UNCERTAIN or human-route. Legacy bare-string truths stay valid.
 
 ### Human Verification Gate (close precondition)
 
@@ -305,8 +296,8 @@ Plans MAY declare a per-truth `check:` shell command in `must_haves.truths` (exi
 
 ## Beads Integration (Optional)
 
-With Beads installed: `bd prime` (session context), `bd ready` (unblocked tasks), `bd complete` (update deps), `bd compact` (summarize old). Without Beads, `.forge/state/` + Session Memory suffice.
+With Beads: `bd prime` (session context), `bd ready` (unblocked tasks), `bd complete` (update deps), `bd compact` (summarize old). Without it, `.forge/state/` + Session Memory suffice.
 
 ## Atomic Commits
 
-One commit per task. Format: `{type}({scope}): {description}` — types `feat fix test refactor chore docs`. Never `git add .` or `git add -A` — stage individually. Phase handoffs additionally emit one scoped `chore(forge): sync state …` commit (State Commit Protocol) so `.forge/` state never drifts out of git.
+One commit per task. Format: `{type}({scope}): {description}` — types `feat fix test refactor chore docs`. Never `git add .`/`-A` — stage individually. Phase handoffs additionally emit one scoped `chore(forge): sync state …` commit (State Commit Protocol) so `.forge/` state never drifts out of git.

package/template/.forge/bin/new-worktree.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# One-command worktree for any commit-producing task (issue #21, ADR-031).
+#
+#   bash .forge/bin/new-worktree.sh <slug> [base-ref]
+#
+# Creates {worktree_root}/{slug} on branch forge/{slug} off origin/main (or [base-ref]).
+# The primary checkout's HEAD never moves — that is the whole point of the weld: branch
+# work lives in worktrees, each with its own independent HEAD, so concurrent sessions
+# never clobber each other's commits.
+#
+# worktree_root follows the FORGE.md Worktree Convention: `orchestration.worktree_root`
+# from .forge/project.yml, default `../<repo-basename>-worktrees/`. Relative paths resolve
+# against the repo root; absolute / ~ honored verbatim.
+
+set -euo pipefail
+
+SLUG=${1:?usage: new-worktree.sh <slug> [base-ref]}
+BASE=${2:-origin/main}
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+REPO_BASE=$(basename "$REPO_ROOT")
+
+# Resolve worktree_root from project.yml (light grep — no yaml dependency). The value
+# lives under an `orchestration:` block as `worktree_root: <path>`.
+WT_ROOT_CFG=$(grep -E '^[[:space:]]*worktree_root:' "$REPO_ROOT/.forge/project.yml" 2>/dev/null \
+  | head -1 | sed -E 's/^[[:space:]]*worktree_root:[[:space:]]*//; s/^["'\'']//; s/["'\'']$//; s/[[:space:]]*(#.*)?$//' || true)
+
+if [ -z "$WT_ROOT_CFG" ]; then
+  WORKTREE_ROOT="$(dirname "$REPO_ROOT")/${REPO_BASE}-worktrees"
+else
+  case "$WT_ROOT_CFG" in
+    /*)   WORKTREE_ROOT="$WT_ROOT_CFG" ;;                         # absolute — verbatim
+    "~"*) WORKTREE_ROOT="${WT_ROOT_CFG/#\~/$HOME}" ;;             # ~ — expand
+    *)    WORKTREE_ROOT="$REPO_ROOT/$WT_ROOT_CFG" ;;              # relative — against repo root
+  esac
+fi
+
+# Slashes in the slug become dashes in the directory name; the branch keeps the slash.
+DIR_NAME=$(printf '%s' "$SLUG" | tr '/' '-')
+WT_PATH="$WORKTREE_ROOT/$DIR_NAME"
+BRANCH="forge/$SLUG"
+
+if [ -e "$WT_PATH" ]; then
+  echo "✋ $WT_PATH already exists. Pick another slug or remove it first (git worktree remove)." >&2
+  exit 1
+fi
+
+mkdir -p "$WORKTREE_ROOT"
+# Best-effort refresh of origin/main so the worktree starts from current main; offline-safe.
+git fetch origin main --quiet 2>/dev/null || true
+git worktree add -b "$BRANCH" "$WT_PATH" "$BASE"
+
+echo ""
+echo "✅ Worktree ready"
+echo "   path:   $WT_PATH"
+echo "   branch: $BRANCH (from $BASE)"
+echo ""
+echo "   cd \"$WT_PATH\""
+echo ""
+echo "Reminders: run your install step after entering (worktrees don't share deps);"
+echo "the primary checkout stayed on its default branch — that is intentional."

package/template/.forge/bin/tests/new-worktree.test.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Scratch-repo tests for .forge/bin/new-worktree.sh (issue #21, ADR-031).
+#
+# Builds a throwaway repo with a committed HEAD, runs the helper (base ref = HEAD so no
+# network is needed), and asserts the worktree dir + branch it creates. Self-cleans. Run:
+#   ./.forge/bin/tests/new-worktree.test.sh
+# Prints `ALL PASS` and exits 0 iff every case passes; non-zero on any failure.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/../new-worktree.sh"
+[ -x "$HELPER" ] || { printf 'FATAL: helper not executable: %s\n' "$HELPER" >&2; exit 1; }
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+pass() { PASSED=$((PASSED + 1)); }
+fail() { FAILED=$((FAILED + 1)); printf '  FAIL: %s\n' "$1" >&2; }
+
+# A repo named so its default worktree_root is predictable: <base>-worktrees next to it.
+new_repo() {
+  local d="$ROOT/$1"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" symbolic-ref HEAD refs/heads/main
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name tester
+  mkdir -p "$d/.forge"
+  : > "$d/seed"
+  git -C "$d" add -A && git -C "$d" commit -qm init
+  printf '%s\n' "$d"
+}
+
+# ── Case 1: default worktree_root, simple slug ───────────────────────────────────
+R="$(new_repo proj)"
+( cd "$R" && "$HELPER" myslug HEAD ) >/dev/null 2>&1 || true
+WT="$ROOT/proj-worktrees/myslug"
+if [ -d "$WT" ]; then pass; else fail "case1: worktree dir not created at $WT"; fi
+br=$(git -C "$WT" branch --show-current 2>/dev/null || true)
+if [ "$br" = "forge/myslug" ]; then pass; else fail "case1: branch is '$br', want forge/myslug"; fi
+
+# ── Case 2: re-running the same slug errors (dir exists) ─────────────────────────
+if ( cd "$R" && "$HELPER" myslug HEAD ) >/dev/null 2>&1; then
+  fail "case2: duplicate slug should have errored (exit non-zero)"
+else
+  pass
+fi
+
+# ── Case 3: slug with a slash → dashed dir, slashed branch ───────────────────────
+R2="$(new_repo proj2)"
+( cd "$R2" && "$HELPER" feat/thing HEAD ) >/dev/null 2>&1 || true
+WT2="$ROOT/proj2-worktrees/feat-thing"
+if [ -d "$WT2" ]; then pass; else fail "case3: dashed dir not created at $WT2"; fi
+br2=$(git -C "$WT2" branch --show-current 2>/dev/null || true)
+if [ "$br2" = "forge/feat/thing" ]; then pass; else fail "case3: branch is '$br2', want forge/feat/thing"; fi
+
+# ── Case 4: configured relative worktree_root honored ────────────────────────────
+R3="$(new_repo proj3)"
+printf 'orchestration:\n  worktree_root: .wt\n' > "$R3/.forge/project.yml"
+git -C "$R3" add -A && git -C "$R3" commit -qm cfg
+( cd "$R3" && "$HELPER" wtslug HEAD ) >/dev/null 2>&1 || true
+WT3="$R3/.wt/wtslug"
+if [ -d "$WT3" ]; then pass; else fail "case4: configured worktree_root .wt not honored (want $WT3)"; fi
+
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+if [ "$FAILED" -eq 0 ]; then printf 'ALL PASS\n'; exit 0; fi
+exit 1

package/template/.forge/checks/forge-jarvis-awareness.sh

@@ -69,6 +69,43 @@ fold_state() {  # fold_state <milestone-id>
   [ -n "$_rs" ] && printf '%s' "$_rs" || printf 'unknown'
 }
 
+# ── milestone name lookup (issue #34 — bare ids are useless with 40+ milestones in flight).
+#    Reads milestone.name (nested under the top-level `milestone:` key) from the worktree's own
+#    state file — a naive `grep -m1 '^name:'` returns empty since the key is indented under
+#    `milestone:`, not top-level. Same nested-key awk pattern as yget() in
+#    forge-board-render.sh (parent/child scan), specialized to milestone/name. Degrades to empty
+#    on any miss (absent file, absent key) — callers degrade to the bare id, never crash. ────────
+milestone_name() {  # milestone_name <milestone-id> <worktree-path>
+  _mid="${1:-}"; _wt="${2:-}"
+  [ -n "$_mid" ] && [ -n "$_wt" ] || { printf ''; return 0; }
+  _id="${_mid#m-}"
+  _f="$_wt/.forge/state/milestone-$_id.yml"
+  [ -f "$_f" ] || { printf ''; return 0; }
+  awk '
+    /^milestone:/ { inp=1; next }
+    inp && /^[A-Za-z]/ { inp=0 }
+    inp && /^[[:space:]]+name:/ {
+      sub(/^[[:space:]]*[^:]+:[[:space:]]*/, "")
+      sub(/[[:space:]]*#.*/, "")
+      gsub(/^["'"'"']|["'"'"']$/, "")
+      print; exit
+    }
+  ' "$_f"
+}
+
+# ── "m-<id> — <name>", truncated ~60 chars so one slice-list row stays one line; degrades to
+#    the bare id (never a blank "m- — " prefix) when the name can't be resolved. ────────────────
+named_milestone() {  # named_milestone <milestone-id> <worktree-path>
+  _mid="${1:-}"; _wt="${2:-}"
+  [ -n "$_mid" ] || { printf ''; return 0; }
+  _nm="$(milestone_name "$_mid" "$_wt")"
+  if [ -n "$_nm" ]; then
+    printf '%s' "$_mid — $_nm" | cut -c1-60
+  else
+    printf '%s' "$_mid"
+  fi
+}
+
 # ── milestone id derivation for a matched branch (issue #25, bare-branch loosening). A
 #    forge/m-* branch keeps its original textual derivation unchanged (strip forge/, strip the
 #    8-hex session suffix). A bare branch (m-<id>-slug | m<digits>-slug) derives the id from the
@@ -143,7 +180,8 @@ _slices="$(list_slices)"
 if [ -n "$_slices" ]; then
   printf '%s\n' "$_slices" | while IFS="$TAB" read -r _m _br _pt; do
     if [ "$DRY_RUN" -eq 1 ]; then _rs='(dry-run)'; else _rs="$(fold_state "$_m")"; fi
-    printf '   %-10s  %-26s  release_state=%-9s  %s\n' "$_m" "$_br" "$_rs" "$_pt"
+    _disp="$(named_milestone "$_m" "$_pt")"
+    printf '   %-40s  %-26s  release_state=%-9s  %s\n' "$_disp" "$_br" "$_rs" "$_pt"
   done
 else
   printf '   (none on this machine)\n'
@@ -165,7 +203,13 @@ elif [ -f "$BOARD" ]; then
         _id="$(printf '%s' "$_ln" | sed -n 's/.*"forge_id":[[:space:]]*"\([^"]*\)".*/\1/p')"
         _st="$(printf '%s' "$_ln" | sed -n 's/.*"status":[[:space:]]*"\([^"]*\)".*/\1/p')"
         _rs="$(printf '%s' "$_ln" | sed -n 's/.*"release_state":[[:space:]]*"\([^"]*\)".*/\1/p')"
-        printf '   %s  status=%s  release_state=%s\n' "${_id:-?}" "${_st:-?}" "${_rs:-?}"
+        _nm="$(printf '%s' "$_ln" | sed -n 's/.*"name":[[:space:]]*"\([^"]*\)".*/\1/p')"
+        if [ -n "$_nm" ]; then
+          _disp="$(printf '%s' "${_id:-?} — $_nm" | cut -c1-60)"
+        else
+          _disp="${_id:-?}"
+        fi
+        printf '   %s  status=%s  release_state=%s\n' "$_disp" "${_st:-?}" "${_rs:-?}"
       done
     else
       printf '   (all board units complete — nothing in flight)\n'