forge-orkes 0.58.2 → 0.59.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.58.2",
+  "version": "0.59.1",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.58.2",
+    "version": "0.58.3",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {

package/template/.claude/skills/chief-of-staff/SKILL.md

@@ -106,6 +106,22 @@ so `index.yml` may be slightly stale; read it as-is when deriving implicit-row
 coverage and suggest a `/forge` pass if it looks off. The Chief writes `active.yml`
 (derived class); it never writes `index.yml` or any milestone file.
 
+### Board render + inbox (attended)
+
+After the Stream Rollup on **Show** and **Sync**, if `board.enabled: true` in
+`project.yml` **and** a Notion MCP server is present, run the board **render** —
+the `notion-integration` skill's `render()` (`forge-board-render.sh --emit`, then
+upsert agent-owned props by `Forge ID` over the session MCP), the same attended
+transport `forge` boot uses — then `pull_inbox()`: if the board holds Forge-ID-less
+rows, surface ONE advisory line — *"inbox has N items, top: {X} — take one in?"* —
+ordered by the operator's `Priority`/`Queue Position`. This rides the **existing**
+intake moment (no new ceremony — the Gate-6 named risk); taking an item in is the
+normal act (`EnterWorktree` + milestone declaration), and nothing materializes
+silently (M21). **Advisory, non-blocking** (FR-175): unconfigured, MCP absent, or a
+call errors → log one line and continue; a render or inbox read never blocks Show,
+Sync, or any merge. Board disabled or no MCP → silent. The unattended render is
+`forge-board-render.sh --deliver` under post-merge CI (R11), never here.
+
 ## Start Stream Flow
 
 1. Read the registry.

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

@@ -124,7 +124,7 @@ Uses only signals that stay current (`current.phase`, `current.status`, the road
 
 Beads enabled (`forge.beads_integration: true`) → `bd prime`. Optional.
 
-Notion adapter (opt-in): `notion.enabled: true` in `project.yml` **and** a Notion MCP server present → log *"Notion adapter active"* and (Phase 2) run `pull_inbox()` (`notion-integration` skill); config without MCP → log *"Notion adapter inactive (MCP absent)"*; neither → silent. When active, `project()` also fires at each phase **handoff** (the State Commit Protocol checkpoint) to push agent-owned state to the board. **Advisory — never blocks boot, handoff, or commit.**
+Notion board adapter (opt-in): `board.enabled: true` in `project.yml` **and** a Notion MCP server present → log *"board render (attended)"* and, **after the State + Stream rollups**, run the board **render** — the `notion-integration` skill's `render()` (`forge-board-render.sh --emit`, then upsert agent-owned props by `Forge ID` over the session MCP) — then `pull_inbox()` (the backlog inbox): if the board holds Forge-ID-less rows, surface ONE advisory line — *"inbox has N items, top: {X} — take one in?"* — ordered by the operator's `Priority`/`Queue Position`. This rides the **existing** intake moment (no new ceremony — the Gate-6 named risk); taking an item in is the normal act (`EnterWorktree` + milestone declaration, Step 3), and nothing materializes silently (M21). Config without MCP → log *"board adapter inactive (MCP absent)"*; neither → silent. When active, `render()` also fires at each phase **handoff** (the State Commit Protocol checkpoint) to push agent-owned state to the board. **Advisory — never blocks boot, handoff, or commit** (FR-175): an emit/render failure logs one line and boot continues. (The unattended render is `forge-board-render.sh --deliver` under post-merge CI — R11, not a boot concern.)
 
 Read `.forge/context.md`. **Needs Resolution** unchecked → warn: *"{N} unresolved discrepancies."* Quick proceeds; Standard/Full blocked at planning.
 

package/template/.claude/skills/notion-integration/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: notion-integration
+description: "Use when rendering Forge state to the Notion board or reading its backlog inbox: 'render the board', 'project Forge state to Notion', 'read the backlog inbox', 'sync notion'. Opt-in adapter — requires a Notion MCP server (attended) or a scoped token (headless) AND a board: block in project.yml. Inert when either is absent."
+---
+
+# The board (Notion adapter)
+
+The Notion adapter that renders **the board** — a rendered **status** window + a backlog **inbox** — and never anything else. Git (`.forge/`) stays the source of truth; the board is a **projection + inbox**, **never an approval surface** (D-D/M21). No runtime, no polling, no daemon (Fork 3): the render rides existing Forge lifecycle hooks (ADR-025).
+
+Two things the board is NOT: it does not gate any merge/deploy/promotion/fold (board data flows OUT only, except the inbox's explicit-intake read), and it does not compute or store any status of its own — it **delivers the state the rollups already compute** (compute-don't-store).
+
+## Prerequisites
+
+The adapter activates only when both hold (else fully inert — zero behavior change at boot, handoff, or commit):
+
+1. **Config** — a `board:` block in `.forge/project.yml` with `enabled: true` and a `database_id` (see `docs/board.md` for the schema).
+2. **Delivery** — for **attended** renders, a Notion MCP server present in the session; for **headless** renders (post-merge CI / cron), a scoped integration token in the env var named by `board.ci_token_env` (phase 57 — `forge-board-render.sh --deliver`).
+
+## Degradation contract — non-blocking by construction
+
+The adapter is **advisory everywhere**. Unconfigured, MCP/token absent, offline, or a call errors → **log one line and continue**. It **never** blocks a phase handoff, a `forge` boot, a commit, a fold, a merge, or a slice. A failed render leaves the board stale; the next successful render reconciles. (This is what makes acceptance test #5 hold by construction.)
+
+## One compute, two transports (ADR-025)
+
+The single source of truth for *what the board shows* is the projection builder, **`forge-board-render.sh`**:
+
+- **`--emit`** computes and prints the normalized projection JSON (units + deferred view) from the existing folds — deterministic, offline, side-effect-free. This is the seam both transports deliver.
+- **Attended transport** (this skill's `render()`): run `forge-board-render.sh --emit`, then upsert each unit to Notion via the **session MCP**.
+- **Headless transport** (`forge-board-render.sh --deliver`, phase 57): the same `--emit` projection, delivered via a scoped-token `curl` for post-merge CI / cron (R11).
+
+Because both deliver the identical `--emit` object, there is no second source of truth for the projection.
+
+## Data model
+
+Single Notion database (topology: one workspace, per-repo views). Rows are Forge units keyed by `Forge ID`, nested by a self-`Parent` relation. Full model: `.forge/phases/milestone-32/03-board-architecture/data-model.md` (extends ADR-019 with the `Repo` stamp + `Release State`; ADR-020 identity binding). Finer-grained rows (requirements/phases/tasks/plans) remain deferred — m-21 DEF-044/045, do not build.
+
+### Field ownership — the collision-proof invariant (ADR-019, kept verbatim)
+
+Every property has exactly one owner. **`render()` writes ONLY agent-owned properties**, addressed by `Forge ID`, and issues **no write, ever** to a human-owned property. Non-overlapping ownership ⇒ **overwrite-on-render is safe by construction** (a hand-edited agent-owned cell is corrected at the next render; a human-owned cell is never touched).
+
+- **Agent-owned** (overwritten every render): `Forge ID`, `Name`, `Layer`, `Status`, `Tier`, `Progress`, `Blockers`, `Parent`, `Rollup Summary`, `Release State`, `Repo`, `Last Rendered`.
+- **Human-owned** (read as inbox proposals in `pull_inbox`, **never** written): `Priority`, `Queue Position`, `Triage Notes`, `Comments`.
+
+**No gate-read property exists.** Nothing on the board is read by any merge/deploy/promotion/fold path (acceptance test #6).
+
+### Identity binding (ADR-020)
+
+`Forge ID` is the **binding of record** — a text property set **once at create**, never re-projected. `.forge/notion/map.yml` (`forge-id → page-id`) is a **derived, gitignored** cache. Page resolution for a unit `U`:
+
+1. **map cache** → page id.
+2. **miss** → query Notion for `Forge ID == U.forge_id`; found → write the pair back (self-heal).
+3. **not found** → create the page, stamp `Forge ID`, record the pair.
+
+Deleting `map.yml` never duplicates rows — step 2 re-binds. `map.yml` is derived (ADR-011 class): only the main/orchestrator session writes it; worktrees never hand-edit it.
+
+## Operations
+
+### `render()` — attended: push agent-owned state out (the status window)
+
+**Trigger:** `forge` boot, `chief-of-staff` Show/Sync (the attended render sites, phase 57) — plus on demand via `sync()`. Producer-side, like a checkpoint publish.
+
+**Precondition:** `board.enabled: true` + a Notion MCP present. Else no-op (log *"board adapter inactive (MCP absent)"*).
+
+**Procedure:**
+
+1. Run `forge-board-render.sh --emit` → the projection JSON. (If it errors, log and stop — non-blocking.)
+2. For each `unit` in `projection.units`:
+   a. **Resolve** its page by the resolution order above (map → query → create), keyed by `unit.forge_id`.
+   b. **Upsert ONLY agent-owned properties** by `Forge ID`: `Name`, `Layer`, `Status` (per the Layer's vocabulary, ADR-015), `Tier`, `Progress`, `Blockers`, `Parent`, `Rollup Summary`, **`Release State`** (= `unit.release_state`), **`Repo`** (= `projection.repo`), `Last Rendered` = now.
+   c. **Never** write `Priority`, `Queue Position`, `Triage Notes`, or `Comments`.
+   d. On create, record `forge-id → page-id` in `.forge/notion/map.yml`.
+3. **Deferred view:** render `projection.deferred[]` as a Notion view/callout (the three surfaces the `deferred` skill aggregates). This is rendered, not stored — no fourth storage surface.
+
+**Overwrite-on-render** is automatic: every render re-upserts the agent-owned props, so a hand-edited status cell is corrected next time (acceptance test #1). **Idempotent:** re-running with unchanged state is a no-op write — identity binding guarantees update-not-duplicate.
+
+**Failure / offline:** skip, leave the map as-is; the next successful render reconciles. **Never blocks.**
+
+### `pull_inbox()` — attended: read the backlog inbox (proposals only, never materialize)
+
+**Trigger:** `forge` boot, `chief-of-staff` Show/Sync — the same attended moments as `render()` — plus on demand via `sync()`. This is the **one** direction board data flows IN, and even then only as a *proposal* (D-D/M21): reading the inbox is read-and-surface, never an approval or a write.
+
+**Precondition:** `board.enabled: true` + a Notion MCP present. Else no-op (one logged line, non-blocking — FR-175).
+
+**Procedure:**
+
+1. Query the board for two things, both **read-only**:
+   a. **Reprioritizations** — human-owned `Priority` / `Queue Position` on existing (Forge-ID-bound) rows. Use them to ORDER the proposal only; **never** write them back (human-owned, per the ownership table).
+   b. **New drops** — rows with **no `Forge ID`**. These are inbox items the operator authored.
+2. **Surface, don't act.** If (b) is non-empty, emit a SINGLE proposal line — `inbox has {N} items, top: {highest-priority title}` — ordered by the (a) reprioritization, then STOP. Reading the inbox **never writes repo state**: no milestone, worktree, file, reservation, or `map.yml` entry comes into being as a side effect of the read.
+3. **Intake is the existing act.** An item enters repo state **only** when the operator explicitly takes it in through the **normal intake act** — the existing worktree + milestone-declaration flow (`EnterWorktree` + the stream/milestone declaration, `forge` Step 3 / `chief-of-staff`). The inbox adds **no second intake mechanism** (Gate-6 named-risk guard).
+4. On intake, the item's row gets a `Forge ID` (ADR-020) and thereafter renders as agent-owned **status** — it is no longer an inbox draft.
+
+**Nothing in the inbox materializes silently (M21).** The board is a projection + inbox, never an approval surface: an inbox drop is a proposal the operator takes in at an existing intake moment, or ignores — the framework never turns a board row into repo state on its own.
+
+**Failure / offline:** board disabled, MCP absent, or a read error → skip with one logged line. **Never blocks** boot, Show/Sync, or any work.
+
+### `sync()` — manual escape hatch
+
+Explicit `sync` command → run `pull_inbox()` then `render()` once, on demand — same preconditions and non-blocking posture as both. For when the operator wants a fresh board push + inbox read outside the automatic boot / Show/Sync moments.
+
+## Credential safety
+
+The Notion secret lives **only** in the Notion MCP server's config (attended) or the env var named by `board.ci_token_env` (headless). This skill — and every operation it defines — must **never** read, store, echo, or project that secret into `.forge/` (which is committed to git). The agent reaches Notion exclusively through MCP tool calls (attended) that already carry the credential; the headless script reads the token from the environment, never from a file.

package/template/.forge/FORGE.md

@@ -152,6 +152,12 @@ Every new accumulating artifact needs: owner, size gate, archive/compaction rule
 - Runtime/generated files (`.mcp-server/*.db*`, logs, spike DBs, and the
   `.git/forge/*` machine-local files — the id-reservation ledger + integration
   flag) are excluded from framework context and packages unless debugging them.
+- The board (ADR-025): `.forge/notion/map.yml` is **derived** (owner: main/orchestrator
+  session; `forge-id → page-id` cache), **gitignored**, and rebuildable by query-self-heal
+  (ADR-020) — never committed, never hand-edited, no size gate. The board **config** is the
+  `board:` block in `project.yml` — **stable-shared**, governed by project.yml's 5 KB gate,
+  changes via `/upgrading`; migration is lazy (absent block / `enabled:false` ⇒ inert, zero
+  behavior change). The board itself accumulates nothing in-repo — it is a projection + inbox.
 - Template copies sync mechanically; do not treat them as separate concepts.
 
 ### Fresh Agent Pattern

package/template/.forge/checks/forge-board-render.sh

@@ -0,0 +1,373 @@
+#!/usr/bin/env sh
+# forge-board-render.sh — the board projection builder (m-32, Brief-R2 step 3; ADR-025).
+#
+# The board is a DELIVERY of the state the rollups already compute — not a new
+# compute. This script emits ONE normalized projection (the single source of truth
+# for what the board shows), computed only from existing sources:
+#   - units: .forge/state/milestone-*.yml (id/name/status/tier) — same derivation the rollup uses
+#   - release_state: .claude/hooks/forge-release-fold.sh, copied VERBATIM (ADR-024 — never re-derived)
+#   - deferred view: the same three surfaces the `deferred` skill aggregates
+#     (deferred milestones · deferred refactor-backlog items · deferred phases in active milestones)
+#
+# MODES:
+#   --emit      compute + print the projection JSON on stdout (pure, offline, no side effects, no Notion).
+#               ALWAYS runs regardless of board config — it is just "what the board would show".
+#   --deliver   [phase 57] compute the same projection, then upsert to Notion via curl + a scoped
+#               token from env; gated on board.enabled + token; non-blocking.
+#
+# INVARIANTS:
+#   - Only AGENT-OWNED fields are emitted (never Priority/Queue/Triage — those are read IN by the inbox).
+#   - --emit is DETERMINISTIC: same repo state → byte-identical (no wall-clock; rendered_at lives in --deliver).
+#   - release_state comes only from the fold binary.
+#   - No new runtime dependency: POSIX sh + git only (curl for --deliver). No language interpreters, no toolchains.
+#   - Non-blocking by construction: a config/read/fold problem logs one line and continues (fold → "unknown").
+#
+# A future refactor could DRY the deferred aggregation with the `deferred` skill (agent-driven, model:haiku);
+# out of scope for m-32 — both read the same three authoritative sources, so there is NO stored aggregate
+# (compute-don't-store). Do NOT introduce a canonical-list file.
+
+set -u
+
+MODE="${1:-}"
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+FORGE="$ROOT/.forge"
+PROJECT="$FORGE/project.yml"
+# Tolerant fold lookup (0.59.1): probe the TRACKED location first (.forge/checks/), then fall back
+# to the client-hook location (.claude/hooks/). The lookup IS the migration path — a consumer that
+# tracks a copy of the fold under .forge/checks/ gets real release_state in CI; if only the gitignored
+# .claude/hooks/ copy exists (absent in CI clones), unit_release_state degrades to "unknown". See docs/board.md.
+FOLD="$ROOT/.forge/checks/forge-release-fold.sh"
+[ -f "$FOLD" ] || FOLD="$ROOT/.claude/hooks/forge-release-fold.sh"
+
+# ---------------------------------------------------------------------------
+# JSON string escaping (POSIX; escapes \, ", and control chars via tab/newline).
+# ---------------------------------------------------------------------------
+json_escape() {
+  # reads $1, prints a JSON-safe string body (no surrounding quotes)
+  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' | tr '\n' ' '
+}
+
+# ---------------------------------------------------------------------------
+# Config: read a scalar under the top-level `board:` block of project.yml.
+# ---------------------------------------------------------------------------
+board_cfg() { # $1 = key under board:
+  [ -f "$PROJECT" ] || return 0
+  awk -v k="$1" '
+    /^board:/ { inb=1; next }
+    inb && /^[A-Za-z]/ { inb=0 }
+    inb && $0 ~ "^[[:space:]]+"k":" {
+      sub(/^[[:space:]]*[^:]+:[[:space:]]*/, "")
+      sub(/[[:space:]]*#.*/, "")
+      gsub(/^["'"'"']|["'"'"']$/, "")
+      print; exit
+    }
+  ' "$PROJECT"
+}
+
+board_enabled() { # 0 = enabled, 1 = disabled
+  [ "${FORGE_BOARD_FORCE_DISABLED:-}" = "1" ] && return 1
+  [ "$(board_cfg enabled)" = "true" ] && return 0
+  return 1
+}
+
+# ---------------------------------------------------------------------------
+# YAML helpers (working-tree reads; scalar-only, comment/quote stripped).
+# ---------------------------------------------------------------------------
+yget() { # $1=file $2=parent $3=key  → scalar value of parent.key
+  [ -f "$1" ] || return 0
+  awk -v p="$2" -v k="$3" '
+    $0 ~ "^"p":" { inp=1; next }
+    inp && /^[A-Za-z]/ { inp=0 }
+    inp && $0 ~ "^[[:space:]]+"k":" {
+      sub(/^[[:space:]]*[^:]+:[[:space:]]*/, "")
+      sub(/[[:space:]]*#.*/, "")
+      gsub(/^["'"'"']|["'"'"']$/, "")
+      print; exit
+    }
+  ' "$1"
+}
+
+# release_state via the fold, verbatim (ADR-024). fold missing/err → "unknown".
+# The fold prints `release_state=<state> [reason=<code>]`; take ONLY the state token.
+unit_release_state() { # $1 = unit id (e.g. m-32)
+  rs=""
+  if [ -x "$FOLD" ] || [ -f "$FOLD" ]; then
+    rs=$(sh "$FOLD" "$1" 2>/dev/null | sed -n 's/^release_state=\([A-Za-z_-]*\).*/\1/p' | head -1)
+  fi
+  [ -n "$rs" ] || { rs="unknown"; printf 'board-render: release fold unavailable for %s — release_state: unknown\n' "$1" >&2; }
+  printf '%s' "$rs"
+}
+
+# Derived progress "done/total" from roadmap phase list vs current.phase.
+unit_progress() { # $1 = numeric id, $2 = current.phase, $3 = status
+  roadmap="$FORGE/roadmap.yml"
+  [ -f "$roadmap" ] || { printf ''; return 0; }
+  phases=$(awk -v id="$1" '
+    /^  milestones:/ { inm=1 }
+    inm && $0 ~ "^    - id: "id"[[:space:]]*$" { grab=1; next }
+    inm && grab && /phases:/ { sub(/^[^\[]*\[/,""); sub(/\].*/,""); gsub(/[[:space:]]/,""); print; exit }
+    inm && grab && /^    - id:/ { exit }
+  ' "$roadmap")
+  [ -n "$phases" ] || { printf ''; return 0; }
+  total=$(printf '%s' "$phases" | awk -F, '{print NF}')
+  if [ "$3" = "complete" ]; then done=$total; else
+    # done = count of phase ids strictly before current.phase in the list
+    done=$(printf '%s' "$phases" | tr ',' '\n' | awk -v cur="$2" '$0==cur{exit} {c++} END{print c+0}')
+  fi
+  printf '%s/%s' "$done" "$total"
+}
+
+# ---------------------------------------------------------------------------
+# Deferred aggregation — the three surfaces the `deferred` skill reads.
+# Emits JSON objects into the deferred[] array (no stored file — compute-don't-store).
+# ---------------------------------------------------------------------------
+emit_deferred() {
+  first=1
+  # Surface 1: deferred MILESTONES — lifecycle.deferred_at set, not superseded by a later
+  # resumed_at. Same key the `deferred` skill + boot rollup use (a milestone with
+  # current.status: deferred but deferred_at: null derives as ACTIVE — matched, not "fixed").
+  for f in "$FORGE"/state/milestone-*.yml; do
+    [ -f "$f" ] || continue
+    da=$(yget "$f" lifecycle deferred_at)
+    [ -n "$da" ] && [ "$da" != "null" ] || continue
+    ra=$(yget "$f" lifecycle resumed_at)
+    [ -n "$ra" ] && [ "$ra" != "null" ] && continue   # resumed → not deferred
+    base=$(basename "$f" .yml); id="${base#milestone-}"
+    nm=$(yget "$f" milestone name); rs=$(yget "$f" lifecycle deferred_reason)
+    [ "$first" = 1 ] && first=0 || printf ',\n'
+    printf '    {"surface": "milestone", "id": "m-%s", "name": "%s", "deferred_at": "%s", "reason": "%s"}' \
+      "$id" "$(json_escape "$nm")" "$(json_escape "$da")" "$(json_escape "$rs")"
+  done
+  # Surface 2: deferred REFACTOR-backlog items (status: deferred). Block-scan: accumulate
+  # each `- id:` item's fields, emit when its status is deferred.
+  bl="$FORGE/refactor-backlog.yml"
+  if [ -f "$bl" ]; then
+    awk '
+      function flush() { if (id != "" && st == "deferred") print id "\t" desc "\t" da "\t" rn }
+      /^  - id:/ { flush(); id=$3; gsub(/["'"'"']/,"",id); desc=""; da=""; rn=""; st="" }
+      /^    (description|title):/ { d=$0; sub(/^[^:]*:[[:space:]]*/,"",d); gsub(/["'"'"']/,"",d); if(desc=="")desc=substr(d,1,80) }
+      /^    status:/ { st=$2 }
+      /^    deferred_at:/ { da=$2; gsub(/["'"'"']/,"",da) }
+      /^    deferred_reason:/ { rn=$0; sub(/^[^:]*:[[:space:]]*/,"",rn); gsub(/["'"'"']/,"",rn) }
+      END { flush() }
+    ' "$bl" 2>/dev/null | while IFS='	' read -r rid rdesc rda rrn; do
+      [ -n "$rid" ] || continue
+      [ "$first" = 1 ] && first=0 || printf ',\n'
+      printf '    {"surface": "refactor", "id": "%s", "name": "%s", "deferred_at": "%s", "reason": "%s"}' \
+        "$(json_escape "$rid")" "$(json_escape "$rdesc")" "$(json_escape "$rda")" "$(json_escape "$rrn")"
+    done
+  fi
+  # Surface 3: deferred PHASES/TASKS inside ACTIVE milestones. Derived-active =
+  # lifecycle.deferred_at unset AND current.status not complete/not_started. The scan
+  # SKIPS the `current:` block so a milestone's own current.status line never false-hits.
+  for f in "$FORGE"/state/milestone-*.yml; do
+    [ -f "$f" ] || continue
+    st=$(yget "$f" current status)
+    case "$st" in complete|not_started) continue ;; esac
+    da_m=$(yget "$f" lifecycle deferred_at)
+    [ -n "$da_m" ] && [ "$da_m" != "null" ] && continue    # milestone-deferred → surface 1
+    hit=$(awk '
+      /^current:/ { inc=1; next }
+      inc && /^[A-Za-z]/ { inc=0 }
+      !inc && /^[[:space:]]+(status:[[:space:]]*deferred|deferred:[[:space:]]*true)/ { print "1"; exit }
+    ' "$f")
+    [ "$hit" = "1" ] || continue
+    base=$(basename "$f" .yml); id="${base#milestone-}"
+    [ "$first" = 1 ] && first=0 || printf ',\n'
+    printf '    {"surface": "active-milestone", "id": "m-%s", "name": "%s", "deferred_at": "", "reason": "phase/task deferred inside active milestone"}' \
+      "$id" "$(json_escape "$(yget "$f" milestone name)")"
+  done
+}
+
+# ---------------------------------------------------------------------------
+# The shared projection builder — one source of truth for what the board shows.
+# --emit prints it; --deliver (phase 57) delivers this same object.
+# ---------------------------------------------------------------------------
+emit_projection() {
+  # Repo name default: the git common dir's parent basename, so a worktree
+  # ("…/forge-worktrees/m-32") still reports "forge", not the worktree dir name.
+  repo="$(basename "$(dirname "$(git rev-parse --git-common-dir 2>/dev/null)")" 2>/dev/null)"
+  [ -n "$repo" ] && [ "$repo" != "." ] || repo="$(basename "$ROOT")"
+  db="$(board_cfg database_id)"
+  reponame="$(board_cfg repo)"; [ -n "$reponame" ] || reponame="$repo"
+  benabled=false; board_enabled && benabled=true
+
+  printf '{\n'
+  printf '  "repo": "%s",\n' "$(json_escape "$reponame")"
+  printf '  "database_id": "%s",\n' "$(json_escape "$db")"
+  printf '  "board_enabled": %s,\n' "$benabled"
+  printf '  "units": [\n'
+  ufirst=1
+  for f in "$FORGE"/state/milestone-*.yml; do
+    [ -f "$f" ] || continue
+    base=$(basename "$f" .yml); id="${base#milestone-}"; unit="m-$id"
+    nm=$(yget "$f" milestone name)
+    status=$(yget "$f" current status)
+    tier=$(yget "$f" current tier)
+    cphase=$(yget "$f" current phase)
+    rstate=$(unit_release_state "$unit")
+    prog=$(unit_progress "$id" "$cphase" "$status")
+    [ "$ufirst" = 1 ] && ufirst=0 || printf ',\n'
+    printf '    {"forge_id": "%s", "layer": "Milestone", "name": "%s", "status": "%s", "release_state": "%s", "tier": "%s", "progress": "%s", "blockers": [], "parent": null}' \
+      "$unit" "$(json_escape "$nm")" "$(json_escape "$status")" "$(json_escape "$rstate")" "$(json_escape "$tier")" "$(json_escape "$prog")"
+  done
+  printf '\n  ],\n'
+  printf '  "deferred": [\n'
+  emit_deferred
+  printf '\n  ]\n'
+  printf '}\n'
+}
+
+# ===========================================================================
+# --deliver — headless transport (phase 57, ADR-025 decision 3).
+#
+# Computes the SAME emit_projection object, then upserts each unit to Notion via
+# curl + REST, using a scoped token read from the env var NAMED by
+# board.ci_token_env (default FORGE_NOTION_TOKEN). The token VALUE is never read
+# from a file and never written into .forge/ (NFR-035). POSIX sh + curl + jq only,
+# no language interpreter (NFR-034). NON-BLOCKING by construction: board disabled,
+# token/db/tool absent, network error, or any non-2xx logs ONE line and exits 0 —
+# a CI step must never fail because the board was unreachable (FR-175).
+# ===========================================================================
+NOTION_API="https://api.notion.com/v1"
+NOTION_VERSION="2022-06-28"
+
+log_deliver() { printf 'board-render: %s\n' "$1" >&2; }
+
+# The token, read by DYNAMIC env-var name via awk ENVIRON — never eval, never a file.
+deliver_token() {
+  var="$(board_cfg ci_token_env)"; [ -n "$var" ] || var="FORGE_NOTION_TOKEN"
+  awk -v n="$var" 'BEGIN { v = ENVIRON[n]; if (v != "") print v }'
+}
+
+# curl wrapper. Prints "<response-body>\n<http_code>" (code is the LAST line).
+# All failures are the caller's to absorb (non-blocking).
+notion_curl() { # $1 method  $2 url  $3 token  $4 body(optional)
+  if [ -n "${4:-}" ]; then
+    curl -sS -X "$1" "$2" \
+      -H "Authorization: Bearer $3" \
+      -H "Notion-Version: $NOTION_VERSION" \
+      -H "Content-Type: application/json" \
+      -w '\n%{http_code}' -d "$4" 2>/dev/null
+  else
+    curl -sS -X "$1" "$2" \
+      -H "Authorization: Bearer $3" \
+      -H "Notion-Version: $NOTION_VERSION" \
+      -w '\n%{http_code}' 2>/dev/null
+  fi
+}
+
+# Derived, gitignored cache: forge-id -> notion-page-id (ADR-020). "<forge-id>: <page-id>".
+MAP="$FORGE/notion/map.yml"
+map_lookup() { # $1 forge_id -> page_id (empty on miss)
+  [ -f "$MAP" ] || return 0
+  awk -v id="$1" '$1 == id":" { print $2; exit }' "$MAP"
+}
+map_record() { # $1 forge_id  $2 page_id  — best-effort self-heal (ADR-020).
+  [ -n "$2" ] || return 0
+  # Derived-class rule (ADR-011): only the main/orchestrator checkout writes the map;
+  # a linked worktree skips the write (the query path re-binds next render).
+  [ "$(git rev-parse --git-dir 2>/dev/null)" = "$(git rev-parse --git-common-dir 2>/dev/null)" ] || return 0
+  mkdir -p "$(dirname "$MAP")" 2>/dev/null || return 0
+  if [ -f "$MAP" ]; then grep -v "^$1:" "$MAP" > "$MAP.tmp" 2>/dev/null && mv "$MAP.tmp" "$MAP" 2>/dev/null; fi
+  printf '%s: %s\n' "$1" "$2" >> "$MAP" 2>/dev/null || true
+}
+
+# Query the board for a page whose `Forge ID` == $3. Prints its page id (empty on miss/err).
+query_page() { # $1 db  $2 token  $3 forge_id
+  qbody="$(jq -n --arg fid "$3" '{filter:{property:"Forge ID",rich_text:{equals:$fid}},page_size:1}')"
+  qresp="$(notion_curl POST "$NOTION_API/databases/$1/query" "$2" "$qbody")"
+  [ "$(printf '%s' "$qresp" | tail -1)" = "200" ] || return 0
+  printf '%s' "$qresp" | sed '$d' | jq -r '.results[0].id // empty' 2>/dev/null
+}
+
+# Agent-owned Notion properties for one unit (stdin: the unit JSON). $1 repo, $2 rendered_at,
+# $3 = 1 to stamp `Forge ID` (create only — set once, never re-projected per ADR-020).
+# Never emits a human-owned property (Priority/Queue/Triage) — overwrite-on-render is safe.
+unit_properties() { # stdin unit  $1 repo  $2 ts  $3 set_forge_id
+  jq -c --arg repo "$1" --arg ts "$2" --argjson setfid "$3" '
+    def sel(v): (if (v // "") == "" then {select: null} else {select: {name: v}} end);
+    {
+      "Name":          {title: [{text: {content: (.name // "")}}]},
+      "Layer":         sel(.layer),
+      "Status":        sel(.status),
+      "Tier":          sel(.tier),
+      "Release State": sel(.release_state),
+      "Progress":      {rich_text: [{text: {content: (.progress // "")}}]},
+      "Blockers":      {rich_text: [{text: {content: ((.blockers // []) | join(", "))}}]},
+      "Rollup Summary":{rich_text: [{text: {content: (.rollup_summary // "")}}]},
+      "Last Rendered": {date: {start: $ts}}
+    }
+    + (if ($repo | length) > 0 then {"Repo": {select: {name: $repo}}} else {} end)
+    + (if $setfid == 1 then {"Forge ID": {rich_text: [{text: {content: .forge_id}}]}} else {} end)
+  '
+}
+
+deliver_headless() {
+  board_enabled || { log_deliver "board disabled (board.enabled != true) — deliver skipped"; return 0; }
+  var="$(board_cfg ci_token_env)"; [ -n "$var" ] || var="FORGE_NOTION_TOKEN"
+  tok="$(deliver_token)"
+  [ -n "$tok" ] || { log_deliver "token env \$$var unset — deliver skipped (non-blocking)"; return 0; }
+  db="$(board_cfg database_id)"
+  [ -n "$db" ] || { log_deliver "board.database_id unset — deliver skipped (non-blocking)"; return 0; }
+  command -v jq   >/dev/null 2>&1 || { log_deliver "jq unavailable — deliver skipped (non-blocking)"; return 0; }
+  command -v curl >/dev/null 2>&1 || { log_deliver "curl unavailable — deliver skipped (non-blocking)"; return 0; }
+
+  proj="$(emit_projection)" || { log_deliver "emit failed — deliver skipped (non-blocking)"; return 0; }
+  repo="$(printf '%s' "$proj" | jq -r '.repo // ""')"
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"   # rendered_at lives ONLY in deliver (emit stays deterministic).
+
+  ok=0; fail=0
+  count="$(printf '%s' "$proj" | jq '.units | length')"
+  i=0
+  while [ "$i" -lt "$count" ]; do
+    unit="$(printf '%s' "$proj" | jq -c ".units[$i]")"
+    i=$((i + 1))
+    fid="$(printf '%s' "$unit" | jq -r '.forge_id')"
+    [ -n "$fid" ] && [ "$fid" != "null" ] || continue
+
+    page="$(map_lookup "$fid")"
+    if [ -z "$page" ]; then
+      page="$(query_page "$db" "$tok" "$fid")"
+      [ -n "$page" ] && map_record "$fid" "$page"
+    fi
+
+    if [ -n "$page" ]; then
+      props="$(printf '%s' "$unit" | unit_properties "$repo" "$ts" 0)"
+      body="$(jq -n --argjson p "$props" '{properties: $p}')"
+      resp="$(notion_curl PATCH "$NOTION_API/pages/$page" "$tok" "$body")"
+    else
+      props="$(printf '%s' "$unit" | unit_properties "$repo" "$ts" 1)"
+      body="$(jq -n --arg db "$db" --argjson p "$props" '{parent: {database_id: $db}, properties: $p}')"
+      resp="$(notion_curl POST "$NOTION_API/pages" "$tok" "$body")"
+    fi
+
+    code="$(printf '%s' "$resp" | tail -1)"
+    case "$code" in
+      2*)
+        ok=$((ok + 1))
+        [ -z "$(map_lookup "$fid")" ] && map_record "$fid" "$(printf '%s' "$resp" | sed '$d' | jq -r '.id // empty' 2>/dev/null)"
+        ;;
+      *)
+        fail=$((fail + 1))
+        log_deliver "unit $fid → HTTP ${code:-none} (non-blocking, continuing)"
+        ;;
+    esac
+  done
+  log_deliver "deliver complete: $ok upserted, $fail failed (non-blocking) — repo=$repo"
+  return 0
+}
+
+case "$MODE" in
+  --emit)
+    emit_projection
+    ;;
+  --deliver)
+    deliver_headless
+    exit 0
+    ;;
+  *)
+    printf 'usage: forge-board-render.sh --emit | --deliver\n' >&2
+    exit 2
+    ;;
+esac

package/template/.forge/gitignore

@@ -41,3 +41,7 @@ dev-source
 # entries a fresh install would re-commit them.
 state/index.yml
 streams/active.yml
+
+# Notion board id-binding cache (ADR-020 derived class) — forge-id → page-id, rebuilt
+# by query-self-heal; never committed (a committed copy would leak private Notion page IDs).
+notion/map.yml

package/template/.forge/migrations/0.53.0-render-on-read-registries.md

@@ -0,0 +1,103 @@
+# Migration Guide: Render-on-read state registries (Forge 0.53.0)
+
+Applies to projects whose derived registries — `.forge/state/index.yml` and/or
+`.forge/streams/active.yml` — are still **git-tracked**. Both files were already
+`DERIVED / DO NOT HAND-EDIT` projections; 0.53.0 makes them **git-ignored
+render-on-read caches**: regenerated at every `forge` boot from their sources and
+**never committed**. Because the value is computed on read and never stored in
+git, the two-registry drift class — a committed projection going stale against
+its source (e.g. a committed `active.yml` phase reading `researching` while the
+milestone had moved to `discussing`) — can no longer occur.
+
+Sources are unchanged: `index.yml` ← `.forge/state/milestone-*.yml` (Rollup 1.0);
+`active.yml` ← `.forge/streams/*.yml` + active milestones (Stream Rollup). Only
+the *storage* changes — tracked file → local cache.
+
+Projects that never committed these files (fresh 0.53.0+ installs) need nothing.
+
+## Prerequisites
+
+1. On the new version's framework files (`npx forge-orkes upgrade`, or the
+   `upgrading` skill) — so the updated `.gitignore` entries and the render-then-read
+   `deferred`/`planning` skills are present.
+2. Working tree clean or changes committed — the migration stops tracking two
+   files and edits `.gitignore`.
+
+## Detection
+
+Keyed on **git-tracking state**, not a content grep: the `DERIVED / DO NOT
+HAND-EDIT` header is identical before and after, so only `git ls-files` can tell
+a committed-pre-0.53.0 registry from a git-ignored-post-0.53.0 one. Fires while
+either registry is still tracked; silent once both are untracked (already
+migrated), and silent in a non-Forge / non-git tree:
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+migrate=0
+for f in .forge/state/index.yml .forge/streams/active.yml; do
+  if git ls-files --error-unmatch "$f" >/dev/null 2>&1; then
+    echo "MIGRATE — $f is still git-tracked (pre-0.53.0); render-on-read makes it a git-ignored cache regenerated at boot"
+    migrate=1
+  fi
+done
+[ "$migrate" -eq 0 ] && exit 0
+```
+
+## Migration steps
+
+### 1. Stop tracking the two registries (keep them on disk)
+
+```bash
+git rm --cached .forge/state/index.yml .forge/streams/active.yml 2>/dev/null
+```
+
+`--cached` removes them from the index only — the working-copy files stay as a
+local cache and are re-rendered on the next boot. (If either was never tracked,
+the command is a harmless no-op for that path.)
+
+### 2. Git-ignore both derived registries
+
+Add to the project's root `.gitignore` (paths relative to the repo root):
+
+```
+.forge/state/index.yml
+.forge/streams/active.yml
+```
+
+Consumer projects created from `create-forge` instead gain these under
+`.forge/.gitignore` (paths relative to `.forge/`):
+
+```
+state/index.yml
+streams/active.yml
+```
+
+Without this, the next `git add .forge/` would re-commit the caches and reopen
+the drift class.
+
+### 3. Confirm the readers render-then-read
+
+`forge` boot and `chief-of-staff` already render before reading. In 0.53.0 the
+two direct readers are converted too: `deferred` and `planning` no longer treat a
+missing `index.yml` as "not a Forge project" — the project sentinel moved to the
+committed `.forge/project.yml`, and they derive milestone state from
+`.forge/state/milestone-*.yml` (rendering the cache first) when `index.yml` is
+absent. These ship with the framework upgrade; no per-project edit is needed.
+
+### 4. Regenerate the caches
+
+Run `/forge` (boot) — it runs Rollup 1.0 and the Stream Rollup and rewrites both
+files from their sources. From here they are regenerated on read, never committed.
+
+## Validation
+
+- `git ls-files --error-unmatch .forge/state/index.yml` exits **non-zero**
+  (untracked); same for `.forge/streams/active.yml`.
+- `git check-ignore .forge/state/index.yml` and `git check-ignore
+  .forge/streams/active.yml` each exit **0** (ignored).
+- Both files still exist on disk after a `/forge` boot (rendered cache).
+- A fresh clone with no prior boot: `deferred` and `planning` do **not** print
+  "No forge state found" (they key the sentinel on `project.yml`).
+- Editing a milestone's phase and booting yields an `active.yml` whose row phase
+  matches the milestone — the projection can no longer be stale, because it is
+  never stored.

package/template/.forge/migrations/0.58.3-render-on-read-registries-catchup.md

@@ -0,0 +1,42 @@
+# Migration Guide: Render-on-read registries catch-up (Forge 0.58.3)
+
+Applies to projects that upgraded **across 0.53.0 while the 0.53.0 migration
+guide was missing from the shipped template** (missing 0.53.0–0.58.2; restored
+in 0.58.3). For those projects, `/upgrading` Step 7's version-range detection
+(`installed < v <= source`) fired for the crossed range but had no
+`0.53.0-*.md` guide on disk to surface — so the render-on-read registry
+migration (untrack `.forge/state/index.yml` + `.forge/streams/active.yml`) was
+silently skipped, and range detection never looks backward at an
+already-crossed version. Host-verified on ptnrkit: stamped 0.58.2 with both
+derived registries still git-tracked and actively committed.
+
+This guide exists solely to re-surface that skipped migration. It re-runs the
+same detection; the actual steps live in the (now-delivered)
+`0.53.0-render-on-read-registries.md` alongside this file.
+
+## Detection
+
+Identical to the 0.53.0 guide — keyed on git-tracking state. Silent once both
+registries are untracked (migrated, or a fresh ≥0.53.0 install):
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+migrate=0
+for f in .forge/state/index.yml .forge/streams/active.yml; do
+  if git ls-files --error-unmatch "$f" >/dev/null 2>&1; then
+    echo "MIGRATE — $f is still git-tracked; the 0.53.0 render-on-read migration was skipped"
+    migrate=1
+  fi
+done
+[ "$migrate" -eq 0 ] && echo "OK — already migrated (or never tracked the registries)"
+```
+
+## Steps
+
+Detection fired → follow `0.53.0-render-on-read-registries.md` (same
+directory) end to end: `git rm --cached` the two registries, gitignore them
+(root `.gitignore`, or `state/index.yml` + `streams/active.yml` in
+`.forge/.gitignore` for create-forge installs), then boot `/forge` to
+regenerate the caches. Its Validation section applies unchanged.
+
+Detection silent → nothing to do; this guide is a no-op.

package/template/.forge/templates/project.yml

@@ -121,27 +121,22 @@ models:
     debugging: sonnet                  # Investigation needs solid reasoning
     discussing: sonnet                 # Conversation needs natural fluency
 
-# notion:                            # OPT-IN work-management adapter — INERT by default. Projects Forge
-#                                    # milestones/streams/packages onto a Notion board and reads human triage/
-#                                    # priority proposals back. Activates only with BOTH this block (enabled: true)
-#                                    # AND a Notion MCP server in .mcp.json; absent either → fully inert, zero
-#                                    # behavior change. Git (.forge/) stays source of truth — Notion is a
-#                                    # projection + inbox, never symmetric sync (ADR-019). Mirrors the opt-in
-#                                    # shape of forge.beads_integration.
-#   enabled: false                   # Master switch. false/absent → adapter never runs.
-#   database_id: ""                  # Id of the single "Forge Work Items" Notion database (all layers as rows).
-#   properties:                      # OPTIONAL rename map: Forge property → your Notion column name. Omit → defaults.
-#     Forge ID: "Forge ID"           #   Binding key — agent-owned, set once, never overwritten.
-#     Status: "Status"               #   Agent-owned, overwritten each projection.
-#     Priority: "Priority"           #   Human-owned — read as proposal, never overwritten.
-#   intake_filter:                   # OPTIONAL (FR-116): gate which Forge-ID-less pages pull_inbox() treats as
-#                                    # triage requests, so one board can mix agent items + arbitrary human pages.
-#                                    # Absent → every Forge-ID-less page is a candidate (FR-114 base). One of:
-#     property: "Type"               #   {property, equals} — page's <property> equals <value>
-#     equals: "Request"
-#     # property: "Type"             #   {property, in} — page's <property> is one of <values>
-#     # in: ["Request", "Bug"]
-#     # view: "Triage"               #   {view} — pages in the named saved Notion view
+# board:                             # OPT-IN Notion board (ADR-025) — INERT by default. A rendered STATUS window
+#                                    # + a backlog INBOX projecting Forge state onto Notion; NEVER an approval
+#                                    # surface (D-D — no board field feeds any merge/deploy/promotion/fold path).
+#                                    # Activates only with BOTH this block (enabled: true) AND a Notion MCP server
+#                                    # (attended render) or a scoped token (headless CI render); absent either →
+#                                    # fully inert, zero behavior change at boot/handoff/commit. Git (.forge/)
+#                                    # stays source of truth. See docs/board.md for setup + the CI wiring snippet.
+#   enabled: false                   # Master switch. false/absent → the board never runs.
+#   provider: notion                 # the only adapter today
+#   database_id: ""                  # Notion database the renderer upserts into (a per-row Repo prop scopes shared workspaces)
+#   repo: ""                         # value stamped on each row's Repo property; empty → derived from the repo basename
+#   ci_token_env: FORGE_NOTION_TOKEN # env-var NAME the headless --deliver reads the token from (never the value; NFR-035)
+#   lanes:                           # DESCRIPTIVE-ONLY (renderer does not read these; --emit always emits all
+#     status: true                   #   three). The framework ships these three lanes ONLY — a bespoke outbound
+#     backlog: true                  #   lane is PROJECT-LOCAL config composing these; the framework carries none.
+#     deferred: true                 #   status / backlog (explicit-intake, M21) / deferred view.
 
 risks:                              # What could go wrong?
   - risk: ""