forge-orkes 0.80.4 → 0.82.0

package/bin/create-forge.js

@@ -295,19 +295,25 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
 }
 
 /**
- * Guarantee CLAUDE.md carries the single `@.forge/FORGE.md` import line, migrating
- * any legacy embedded forge section out in one pass. The framework prose itself lives
- * in .forge/FORGE.md (synced separately) — this function never writes prose into
- * CLAUDE.md and never touches user content outside the legacy forge section.
+ * Guarantee CLAUDE.md carries the single `@.forge/FORGE.md` import line WITHIN ITS
+ * FIRST 3 LINES, migrating any legacy embedded forge section out in one pass. Claude
+ * Code truncates memory files at 40k chars from the TAIL — an import line buried below
+ * that cliff silently unloads the entire framework, so the import must never live in
+ * the tail. The framework prose itself lives in .forge/FORGE.md (synced separately) —
+ * this function never writes prose into CLAUDE.md and never touches user content
+ * outside the legacy forge section / the one line it relocates.
  *
  *   no CLAUDE.md                         → write the stub (comment + import) → 'created'
  *   marker section present               → replace section in place with the import line → 'migrated'
  *   legacy `# Forge` header (no markers) → strip header-to-EOF, append import line → 'migrated'
- *   import line already present          → 'unchanged'
- *   none of the above                    → append comment + import line at EOF → 'appended'
+ *   import line within the first 3 lines → untouched, no rewrite (no mtime churn) → 'unchanged'
+ *   import line present but lower        → remove that line, insert as line 1 + blank line,
+ *                                           every other byte preserved in order → 'moved'
+ *   no import line anywhere              → prepend import line + blank line, original
+ *                                           content follows intact → 'appended'
  *
- * Newline cleanup is confined to the seam of the replaced region only — a global
- * collapse would mutate user content, which upgrades must never do.
+ * Newline cleanup is confined to the seam of the replaced/relocated region only — a
+ * global collapse would mutate user content, which upgrades must never do.
  */
 function ensureClaudeMdImport() {
   const destPath = path.join(targetDir, 'CLAUDE.md');
@@ -344,21 +350,90 @@ function ensureClaudeMdImport() {
     return 'migrated';
   }
 
-  // Import line already present (tolerating trailing whitespace/CRLF) — nothing to do.
-  if (FORGE_IMPORT_RE.test(existing)) return 'unchanged';
+  // Import line present somewhere (tolerating trailing whitespace/CRLF) — find its
+  // exact line so position and byte-preservation are decided on real line boundaries,
+  // not the regex's own (looser) match span.
+  if (FORGE_IMPORT_RE.test(existing)) {
+    const lines = existing.split('\n');
+    const idx = lines.findIndex((l) => l.trimEnd() === FORGE_IMPORT_LINE);
+
+    // Already within the first 3 lines — leave the file byte-for-byte untouched.
+    if (idx === -1 || idx <= 2) return 'unchanged';
+
+    // Remove the import's own line.
+    lines.splice(idx, 1);
+    // If that removal left two adjacent blank lines where there weren't three
+    // before, collapse them back to one — the only non-import byte we ever drop.
+    if (idx > 0 && idx < lines.length && lines[idx - 1].trim() === '' && lines[idx].trim() === '') {
+      lines.splice(idx, 1);
+    }
+    const merged = FORGE_IMPORT_LINE + '\n\n' + lines.join('\n');
+    fs.writeFileSync(destPath, merged);
+    return 'moved';
+  }
 
-  // User-authored CLAUDE.md with no forge content and no import line — append it.
-  const merged =
-    existing.trimEnd() + '\n\n' + CLAUDE_STUB;
+  // User-authored CLAUDE.md with no forge content and no import line anywhere —
+  // prepend the import (plus a separating blank line) so it is never buried below
+  // the truncation cliff. Original content follows intact, byte-for-byte.
+  const merged = FORGE_IMPORT_LINE + '\n\n' + existing;
   fs.writeFileSync(destPath, merged);
   return 'appended';
 }
 
+// --- Hook identity helpers (per-hook dedupe key: event + matcher + script basename) ---
+
+// Normalize a hook group's matcher for key comparisons — trim, and treat an
+// absent/empty matcher as the same value so an unset matcher never desyncs
+// from "".
+function normalizeMatcher(matcher) {
+  return typeof matcher === 'string' ? matcher.trim() : '';
+}
+
+// Basename of the first path-looking token in a command string (quotes
+// stripped) — "bash /path/to/x.sh" and "$CLAUDE_PROJECT_DIR/.claude/hooks/x.sh"
+// both resolve to "x.sh", so the same framework script hosted at a different
+// path, or invoked via an interpreter prefix, is recognized as the same hook.
+// No path-looking token (e.g. a bare `echo` one-liner) → the whole trimmed
+// command is its own identity.
+function hookScriptBasename(command) {
+  const tokens = command.match(/"[^"]*"|'[^']*'|\S+/g) || [];
+  for (const raw of tokens) {
+    let tok = raw;
+    if ((tok.startsWith('"') && tok.endsWith('"')) || (tok.startsWith("'") && tok.endsWith("'"))) {
+      tok = tok.slice(1, -1);
+    }
+    if (tok.includes('/')) return path.basename(tok);
+  }
+  return command.trim();
+}
+
+// Identity of a single hook entry within a group. Prompt-backed hooks key off
+// the prompt text; anything else (neither command nor prompt) falls back to a
+// full-entry identity so it never collides with something it isn't.
+function hookEntryIdentity(hookEntry) {
+  if (typeof hookEntry.command === 'string') return 'cmd:' + hookScriptBasename(hookEntry.command);
+  if (typeof hookEntry.prompt === 'string') return 'prompt:' + hookEntry.prompt.trim();
+  return 'raw:' + JSON.stringify(hookEntry);
+}
+
+// Full dedupe key for one (event, matcher, hook-entry) registration. JSON-encoded
+// as a tuple so no delimiter choice can be ambiguated by the values themselves.
+function hookKey(event, matcher, hookEntry) {
+  return JSON.stringify([event, normalizeMatcher(matcher), hookEntryIdentity(hookEntry)]);
+}
+
 /**
  * Additively install the template's framework-managed hooks into an existing
- * settings.json (ADR-017). Never removes a user's hooks; dedups by deep-equality
- * so re-running upgrade is idempotent. New groups (the safety guardrails) get
- * appended; groups the project already has (identical) are skipped.
+ * settings.json (ADR-017). Never removes a user's hooks. Dedupes PER HOOK
+ * ENTRY, keyed by (event, matcher, script basename) — not whole-group
+ * equality — because consumer repos legitimately reshape groups (combine two
+ * matcher="Bash" groups into one, host the same script at a project-local
+ * path, etc.) without that being a meaningfully different hook. A hook whose
+ * key already exists anywhere under that event is skipped; a genuinely new
+ * hook is appended into an existing dest group sharing its matcher, or into a
+ * newly created group when no such group exists yet. See cleanupDuplicateHooks()
+ * (called from upgradeSettings()) for the paired destination-side cleanup pass
+ * that collapses duplicates already baked into a project's settings.json.
  */
 function mergeManagedHooks(destSettings, srcSettings) {
   if (!srcSettings.hooks) return;
@@ -366,12 +441,62 @@ function mergeManagedHooks(destSettings, srcSettings) {
   for (const event of Object.keys(srcSettings.hooks)) {
     const srcGroups = srcSettings.hooks[event] || [];
     const destGroups = destSettings.hooks[event] || (destSettings.hooks[event] = []);
-    for (const group of srcGroups) {
-      const groupJson = JSON.stringify(group);
-      if (!destGroups.some((d) => JSON.stringify(d) === groupJson)) {
-        destGroups.push(group);
+
+    const existingKeys = new Set();
+    const groupsByMatcher = new Map();
+    for (const group of destGroups) {
+      const nm = normalizeMatcher(group.matcher);
+      if (!groupsByMatcher.has(nm)) groupsByMatcher.set(nm, group);
+      for (const hookEntry of group.hooks || []) {
+        existingKeys.add(hookKey(event, group.matcher, hookEntry));
       }
     }
+
+    for (const srcGroup of srcGroups) {
+      for (const hookEntry of srcGroup.hooks || []) {
+        const key = hookKey(event, srcGroup.matcher, hookEntry);
+        if (existingKeys.has(key)) continue; // already installed, whatever group it sits in
+
+        const nm = normalizeMatcher(srcGroup.matcher);
+        let destGroup = groupsByMatcher.get(nm);
+        if (!destGroup) {
+          destGroup = { matcher: srcGroup.matcher, hooks: [] };
+          destGroups.push(destGroup);
+          groupsByMatcher.set(nm, destGroup);
+        }
+        destGroup.hooks.push(hookEntry);
+        existingKeys.add(key);
+      }
+    }
+  }
+}
+
+/**
+ * Collapse duplicate hook registrations already baked into a project's
+ * settings.json — the same (event, matcher, script basename) appearing in
+ * more than one group, or more than once in the same group — keeping the
+ * first occurrence and dropping any group the collapse empties. Runs on
+ * every upgrade, independent of what mergeManagedHooks() just added, so
+ * repos that accumulated near-duplicate groups under the old whole-group
+ * equality merge converge without operator action. Idempotent by
+ * construction: a settings.json with no duplicates is left byte-identical.
+ */
+function cleanupDuplicateHooks(destSettings) {
+  if (!destSettings.hooks) return;
+  for (const event of Object.keys(destSettings.hooks)) {
+    const groups = destSettings.hooks[event];
+    if (!Array.isArray(groups)) continue;
+    const seen = new Set();
+    for (const group of groups) {
+      if (!Array.isArray(group.hooks)) continue;
+      group.hooks = group.hooks.filter((hookEntry) => {
+        const key = hookKey(event, group.matcher, hookEntry);
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      });
+    }
+    destSettings.hooks[event] = groups.filter((g) => Array.isArray(g.hooks) && g.hooks.length > 0);
   }
 }
 
@@ -475,6 +600,9 @@ function upgradeSettings() {
   migrateActiveSkillHook(destSettings);
   // Additively install framework-managed safety guardrails (ADR-017)
   mergeManagedHooks(destSettings, srcSettings);
+  // Converge any duplicate hook registrations already baked into the
+  // destination (pre-existing, or left by an older whole-group merge).
+  cleanupDuplicateHooks(destSettings);
   mergeManagedDeny(destSettings, srcSettings);
   mergeManagedAllow(destSettings, srcSettings);
 
@@ -535,6 +663,9 @@ async function install() {
     case 'appended':
       console.log('  Added @.forge/FORGE.md import line to existing CLAUDE.md');
       break;
+    case 'moved':
+      console.log('  Moved @.forge/FORGE.md import line to the top of CLAUDE.md');
+      break;
     case 'unchanged':
       console.log('  CLAUDE.md import line already present');
       break;
@@ -959,6 +1090,9 @@ async function upgrade() {
   } else if (claudeStatus === 'appended') {
     results.updated.push('CLAUDE.md');
     say('  CLAUDE.md: @.forge/FORGE.md import line restored');
+  } else if (claudeStatus === 'moved') {
+    results.updated.push('CLAUDE.md');
+    say('  CLAUDE.md: @.forge/FORGE.md import line moved to the top (was below the truncation-safe zone)');
   } else if (claudeStatus === 'unchanged') {
     results.unchanged.push('CLAUDE.md');
   } else if (claudeStatus === 'created') {

package/package.json

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

package/template/.claude/hooks/forge-size-gate.sh

@@ -42,6 +42,16 @@
 # A declared-gate artifact that does not exist in this repo (e.g. no
 # prototypes/ dir yet) is skipped silently — not an error, not a violation.
 #
+# Special-cased alongside the tiered skill-file class: the CONSUMER's
+# repo-root CLAUDE.md, advisory at 30 KB (m-56). This is NOT a FORGE.md Size
+# Gates table row — that table lists forge-owned artifacts, and CLAUDE.md
+# belongs entirely to the consumer (the import-to-top fix keeps the
+# @.forge/FORGE.md import out of Claude Code's 40k-char tail-truncation
+# zone; this check is the companion advisory for when the consumer's own
+# prose grows past a size where relocating it into path-scoped
+# .claude/rules/ files, ADR-018, is worth considering). Absent CLAUDE.md or
+# under 30 KB → silent, same contract as every other check.
+#
 # Contract (SessionStart, mirrors forge-state-rollup.sh — ADR-032):
 #   - Exit 0 ALWAYS. SessionStart is non-blocking; this hook must never abort
 #     a session.
@@ -164,6 +174,22 @@ for f in "$root"/.claude/skills/*/SKILL.md; do
   check_gate "$f" "$skill_kb"
 done
 
+# --- consumer CLAUDE.md advisory (special-cased — NOT a Size Gates table row) -
+# CLAUDE.md is consumer-owned, not forge-owned, so it never joins the declared
+# table above (m-56). Threshold is 30 KB BINARY (30720 B — Claude Code's own
+# memory-file semantics use binary units), unlike the decimal-KB gates above.
+# Missing file or under threshold → silent, same contract as every other check.
+
+CLAUDE_MD_GATE_BYTES=30720
+
+if [ -f "$root/CLAUDE.md" ]; then
+  claude_bytes="$(wc -c < "$root/CLAUDE.md" 2>/dev/null | tr -d ' ')"
+  if [ -n "$claude_bytes" ] && [ "$claude_bytes" -gt "$CLAUDE_MD_GATE_BYTES" ]; then
+    VIOLATIONS="${VIOLATIONS}${VIOLATIONS:+, }CLAUDE.md (${claude_bytes}B, over the 30KB advisory threshold — relocate prose into path-scoped .claude/rules/, ADR-018)"
+    VIOLATION_COUNT=$((VIOLATION_COUNT + 1))
+  fi
+fi
+
 # --- summary (stdout → injected into boot context) ---------------------------
 # Silent when clean. One terse line when not.
 

package/template/.claude/hooks/tests/forge-size-gate.test.sh

@@ -114,6 +114,34 @@ check_has "missing tier-list → default 20KB tier applied even to 'forge'" "$ou
 rm -rf "$REPO/.claude/skills"
 printf 'forge\nchief-of-staff\n' > "$REPO/.claude/hooks/skill-gate-tiers.txt"
 
+# ===========================================================================
+# Case F1 — consumer CLAUDE.md over the 30KB (30720B) advisory threshold: one
+# advisory line naming CLAUDE.md, its byte size, the 30KB threshold, and the
+# .claude/rules/ relocation pointer. Special-cased, NOT a Size Gates table row.
+# ===========================================================================
+pad_to "$REPO/CLAUDE.md" 31000
+out_f1="$("$GATE" --project "$REPO" 2>&1)"
+check_has "over-30KB CLAUDE.md named" "$out_f1" "CLAUDE.md"
+check_has "over-30KB CLAUDE.md shows actual bytes" "$out_f1" "31000B"
+check_has "over-30KB CLAUDE.md names the 30KB threshold" "$out_f1" "30KB"
+check_has "over-30KB CLAUDE.md points at .claude/rules/ relocation" "$out_f1" ".claude/rules"
+rm -f "$REPO/CLAUDE.md"
+
+# ===========================================================================
+# Case F2 — consumer CLAUDE.md under the 30KB threshold → never named.
+# ===========================================================================
+pad_to "$REPO/CLAUDE.md" 5000
+out_f2b="$("$GATE" --project "$REPO" 2>&1)"
+check_absent "under-30KB CLAUDE.md never named" "$out_f2b" "CLAUDE.md"
+rm -f "$REPO/CLAUDE.md"
+
+# ===========================================================================
+# Case F3 — no CLAUDE.md at all → no error, clean run, exit 0.
+# ===========================================================================
+out_f3="$("$GATE" --project "$REPO" 2>&1)"; rc_f3=$?
+check "absent CLAUDE.md → exit 0" "$rc_f3" "0"
+check_absent "absent CLAUDE.md never named" "$out_f3" "CLAUDE.md"
+
 # ===========================================================================
 # Case F — non-Forge repo / non-repo dir: silent no-op, exit 0.
 # ===========================================================================

package/template/.claude/settings.json

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

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

@@ -5,7 +5,7 @@ description: "Use when rendering Forge state to the Notion board or reading its
 
 # 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).
+The Notion adapter that renders **the board** — a rendered **status** window + a backlog **inbox**. 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).
 
@@ -14,7 +14,7 @@ Two things the board is NOT: it does not gate any merge/deploy/promotion/fold (b
 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`).
+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` (`forge-board-render.sh --deliver`).
 
 ## Degradation contract — non-blocking by construction
 
@@ -26,20 +26,24 @@ The single source of truth for *what the board shows* is the projection builder,
 
 - **`--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).
+- **Headless transport** (`forge-board-render.sh --deliver`): 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.
+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 phase/plan rows (m-21 DEF-044/045, resolved m-57) live in a second, opt-in DB — see below.
+
+### Second grain — phase + plan rows (opt-in, `board.plan_database_id`)
+
+`--emit` also always computes `projection.phase_rows[]` (one row per phase/plan, self-related via `Parent phase`). `--deliver` pushes them only when `board.plan_database_id` is set — absent ⇒ inert, same opt-in contract as `board:` itself. Schema (`Grain`/`Intent`/`Progress` Select, self-relation, rich text), the three saved views (Roadmap / In flight / Outline — hand-created; Notion's API can't create views), and the Intent(human)/Progress(machine) split: `docs/board.md`.
 
 ### 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`.
-  - `Blockers`, `Parent`, and `Rollup Summary` are **reserved, not yet populated**: at the current milestone-only scope the renderer emits them empty (`blockers: []`, `parent: null`, no `rollup_summary`) — they gain real values only when finer-grained rows land (DEF-044/045). Ownership is declared now so the schema doesn't shift later (R084).
+  - `Blockers`, `Parent`, and `Rollup Summary` are **reserved, not yet populated**: at the current milestone-only scope the renderer emits them empty (`blockers: []`, `parent: null`, no `rollup_summary`) — phase/plan granularity now lives in the second DB above, not as sub-rows here. Ownership is declared now so the schema doesn't shift later (R084).
 - **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).
@@ -58,7 +62,7 @@ Deleting `map.yml` never duplicates rows — step 2 re-binds. `map.yml` is deriv
 
 ### `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.
+**Trigger:** `forge` boot, `chief-of-staff` Show/Sync — 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)"*).
 

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

@@ -102,11 +102,20 @@ unit_release_state() { # $1 = unit id (e.g. m-32)
 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[] ids may be bare (- id: 55) or quoted/labeled (- id: "m-53") —
+  # accept either spelling against both the raw and m--stripped unit id forms
+  # (issue #49), same tolerant style as unit_id()/phase_table()'s mpart lookup.
+  bare="$1"; case "$1" in m-*) bare="${1#m-}" ;; esac
+  labeled="m-$bare"
+  phases=$(awk -v bare="$bare" -v labeled="$labeled" '
     /^  milestones:/ { inm=1 }
-    inm && $0 ~ "^    - id: "id"[[:space:]]*$" { grab=1; next }
+    inm && /^    - id: / {
+      if (grab) exit
+      val=$0; sub(/^    - id: */,"",val); gsub(/[[:space:]]+$/,"",val); gsub(/^"|"$/,"",val); gsub(/^'"'"'|'"'"'$/,"",val)
+      if (val == bare || val == labeled) 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}')
@@ -179,6 +188,123 @@ emit_deferred() {
   done
 }
 
+# ---------------------------------------------------------------------------
+# Phase+plan grain rows (m-57 phase 103; derivation LOCKED in context/m-57.md).
+# One row per roadmap phases[] entry (grain Phase) + one row per plan-*.md on
+# disk under that phase's dir (grain Plan, parent = the phase row's forge_id).
+# Progress is the same family as forge's {percent}: no phase dir => unplanned;
+# dir exists but cursor not reached => planned; cursor AT the phase with
+# status executing/verifying/reviewing => in_progress; behind the cursor or
+# milestone complete => done. Intent is the roadmap `status:` field VERBATIM
+# (human-owned; projected, never re-derived) — inherited onto plan rows too.
+# ---------------------------------------------------------------------------
+
+# roadmap milestone: value ("1", "m-33") -> the shared dir/state-file key ("1", "33")
+mpart() {
+  case "$1" in m-*) printf '%s' "${1#m-}" ;; *) printf '%s' "$1" ;; esac
+}
+
+# TSV id\tname\tmilestone_raw\tstatus, in file order — the phases[] block only
+# (the earlier `milestones:` block is never entered; inph stays 0 until it).
+phase_table() {
+  roadmap="$FORGE/roadmap.yml"
+  [ -f "$roadmap" ] || return 0
+  awk '
+    /^  phases:/ { inph = 1; next }
+    inph && /^  [A-Za-z]/ { inph = 0 }
+    inph && /^    - id:/ {
+      if (id != "") print id "\t" name "\t" ms "\t" st
+      v = $0; sub(/^[^:]*:[[:space:]]*/, "", v); id = v; name = ""; ms = ""; st = ""
+      next
+    }
+    inph && /^      name:/      { v=$0; sub(/^[^:]*:[[:space:]]*/,"",v); sub(/[[:space:]]*#.*/,"",v); gsub(/^"|"$/,"",v); name=v; next }
+    inph && /^      milestone:/ { v=$0; sub(/^[^:]*:[[:space:]]*/,"",v); sub(/[[:space:]]*#.*/,"",v); gsub(/^"|"$/,"",v); ms=v; next }
+    inph && /^      status:/    { v=$0; sub(/^[^:]*:[[:space:]]*/,"",v); sub(/[[:space:]]*#.*/,"",v); gsub(/^"|"$/,"",v); st=v; next }
+    END { if (id != "") print id "\t" name "\t" ms "\t" st }
+  ' "$roadmap"
+}
+
+# $1 mpart  $2 phase_id -> the matching .forge/phases/milestone-{mpart}/{id}-* dir, or empty
+phase_dir_for() {
+  base="$FORGE/phases/milestone-$1"
+  [ -d "$base" ] || return 0
+  for d in "$base/$2"-*; do
+    [ -d "$d" ] && { printf '%s' "$d"; return 0; }
+  done
+}
+
+# $1 dir(may be empty)  $2 phase_id  $3 milestone current.status  $4 cursor phase  $5 cursor status
+phase_progress() {
+  [ -n "$1" ] || { printf 'unplanned'; return 0; }
+  [ "$3" = "complete" ] && { printf 'done'; return 0; }
+  [ -n "$4" ] || { printf 'planned'; return 0; }
+  if [ "$2" -lt "$4" ] 2>/dev/null; then printf 'done'; return 0; fi
+  if [ "$2" -eq "$4" ] 2>/dev/null; then
+    case "$5" in
+      executing|verifying|reviewing) printf 'in_progress' ;;
+      *) printf 'planned' ;;
+    esac
+    return 0
+  fi
+  printf 'planned'
+}
+
+# $1 phase progress  $2 plan number  $3 cursor plan (may be empty; only meaningful when $1=in_progress)
+plan_progress() {
+  case "$1" in
+    done) printf 'done' ;;
+    in_progress)
+      if [ -z "$3" ]; then printf 'planned'; return 0; fi
+      if [ "$2" -lt "$3" ] 2>/dev/null; then printf 'done'
+      elif [ "$2" -eq "$3" ] 2>/dev/null; then printf 'in_progress'
+      else printf 'planned'; fi
+      ;;
+    *) printf 'planned' ;;
+  esac
+}
+
+emit_phase_rows() {
+  first=1
+  warned=""
+  phase_table | while IFS='	' read -r pid pname pms pstatus; do
+    [ -n "$pid" ] || continue
+    part="$(mpart "$pms")"
+    munit="$(unit_id "$part")"
+    sf="$FORGE/state/milestone-$part.yml"
+    if [ -f "$sf" ]; then
+      mstatus=$(yget "$sf" current status)
+      cphase=$(yget "$sf" current phase)
+      cplan=$(yget "$sf" current plan)
+    else
+      mstatus=""; cphase=""; cplan=""
+      case " $warned " in
+        *" $munit "*) : ;;
+        *) warned="$warned $munit"
+           printf 'board-render: no state/milestone-%s.yml for %s — phase rows degrade to unplanned\n' "$part" "$munit" >&2 ;;
+      esac
+    fi
+    dir="$(phase_dir_for "$part" "$pid")"
+    [ -f "$sf" ] || dir=""    # never-declared milestone (no cursor) => unplanned, never a crash
+    prog="$(phase_progress "$dir" "$pid" "$mstatus" "$cphase" "$mstatus")"
+    pkey="$munit/$pid"
+    [ "$first" = 1 ] && first=0 || printf ',\n'
+    printf '    {"forge_id": "%s", "grain": "Phase", "milestone": "%s", "phase_id": %s, "plan": null, "name": "%s", "intent": "%s", "progress": "%s", "parent": null}' \
+      "$(json_escape "$pkey")" "$(json_escape "$munit")" "$pid" "$(json_escape "$pname")" "$(json_escape "$pstatus")" "$(json_escape "$prog")"
+
+    [ -n "$dir" ] || continue
+    for pf in "$dir"/plan-*.md; do
+      [ -f "$pf" ] || continue
+      pbase=$(basename "$pf" .md)
+      nn=${pbase#plan-}                                    # zero-padded, e.g. "01" — used in the key/name verbatim
+      nnum="$(printf '%s' "$nn" | sed 's/^0*//')"; [ -n "$nnum" ] || nnum=0   # arithmetic-safe (no octal-literal risk)
+      pprog="$(plan_progress "$prog" "$nnum" "$cplan")"
+      printf ',\n'
+      printf '    {"forge_id": "%s", "grain": "Plan", "milestone": "%s", "phase_id": %s, "plan": %s, "name": "%s", "intent": "%s", "progress": "%s", "parent": "%s"}' \
+        "$(json_escape "$pkey/plan-$nn")" "$(json_escape "$munit")" "$pid" "$nnum" "$(json_escape "$pbase")" "$(json_escape "$pstatus")" "$(json_escape "$pprog")" "$(json_escape "$pkey")"
+    done
+  done
+}
+
 # ---------------------------------------------------------------------------
 # The shared projection builder — one source of truth for what the board shows.
 # --emit prints it; --deliver (phase 57) delivers this same object.
@@ -215,6 +341,9 @@ emit_projection() {
       "$unit" "$(json_escape "$nm")" "$(json_escape "$status")" "$(json_escape "$rstate")" "$(json_escape "$tier")" "$(json_escape "$prog")"
   done
   printf '\n  ],\n'
+  printf '  "phase_rows": [\n'
+  emit_phase_rows
+  printf '\n  ],\n'
   printf '  "deferred": [\n'
   emit_deferred
   printf '\n  ]\n'
@@ -312,6 +441,98 @@ unit_properties() { # stdin unit  $1 repo  $2 ts  $3 set_forge_id
   '
 }
 
+# Second, opt-in DB for phase/plan grain rows (m-57 phase 103): board.plan_database_id.
+# Own gitignored identity map (a distinct Notion database => distinct page ids) — mirrors
+# MAP/map_lookup/map_record exactly rather than parameterizing them, so the existing
+# unit delivery path above is untouched (R084-style: duplicate a few lines, don't risk it).
+PLAN_MAP="$FORGE/notion/plan-map.yml"
+planmap_lookup() { # $1 forge_id -> page_id (empty on miss)
+  [ -f "$PLAN_MAP" ] || return 0
+  awk -v id="$1" '$1 == id":" { print $2; exit }' "$PLAN_MAP"
+}
+planmap_record() { # $1 forge_id  $2 page_id
+  [ -n "$2" ] || return 0
+  [ "$(git rev-parse --git-dir 2>/dev/null)" = "$(git rev-parse --git-common-dir 2>/dev/null)" ] || return 0
+  mkdir -p "$(dirname "$PLAN_MAP")" 2>/dev/null || return 0
+  if [ -f "$PLAN_MAP" ]; then grep -v "^$1:" "$PLAN_MAP" > "$PLAN_MAP.tmp" 2>/dev/null && mv "$PLAN_MAP.tmp" "$PLAN_MAP" 2>/dev/null; fi
+  printf '%s: %s\n' "$1" "$2" >> "$PLAN_MAP" 2>/dev/null || true
+}
+
+# Agent-owned Notion properties for one phase/plan row (stdin: the row JSON). $1 repo, $2 ts,
+# $3 parent page-id (empty => omit the relation — a resolution miss logs and skips it, never
+# fails the row), $4 = 1 to stamp `Forge ID` (create only, same identity convention as units).
+plan_row_properties() { # stdin row  $1 repo  $2 ts  $3 parent_page  $4 set_forge_id
+  jq -c --arg repo "$1" --arg ts "$2" --arg parent "$3" --argjson setfid "$4" '
+    def sel(v): (if (v // "") == "" then {select: null} else {select: {name: v}} end);
+    {
+      "Name":          {title: [{text: {content: (.name // "")}}]},
+      "Grain":         sel(.grain),
+      "Intent":        sel(.intent),
+      "Progress":      sel(.progress),
+      "Milestone":     {rich_text: [{text: {content: (.milestone // "")}}]},
+      "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)
+    + (if ($parent | length) > 0 then {"Parent phase": {relation: [{id: $parent}]}} else {} end)
+  '
+}
+
+# Upserts every projection.phase_rows[] entry into the plan-grain DB, keyed by forge_id
+# (same map -> query -> create resolution order as units). Processes rows in projection
+# order — a phase row upserts (and records its page id) before its own plan rows are
+# reached, so "Parent phase" resolves within THIS run without a second pass. A parent
+# miss (never happens in-order, but degrades safely) logs and omits the relation only —
+# never fails the row. Every failure is non-blocking: log + continue (deliver_headless's posture).
+deliver_plan_grain() { # $1 proj json  $2 plan_db  $3 token  $4 repo  $5 ts
+  pproj="$1"; pdb="$2"; ptok="$3"; prepo="$4"; pts="$5"
+  pok=0; pfail=0
+  pcount="$(printf '%s' "$pproj" | jq '.phase_rows | length')"
+  pi=0
+  while [ "$pi" -lt "$pcount" ]; do
+    row="$(printf '%s' "$pproj" | jq -c ".phase_rows[$pi]")"
+    pi=$((pi + 1))
+    rfid="$(printf '%s' "$row" | jq -r '.forge_id')"
+    [ -n "$rfid" ] && [ "$rfid" != "null" ] || continue
+
+    rparent_fid="$(printf '%s' "$row" | jq -r '.parent // empty')"
+    rparent_page=""
+    if [ -n "$rparent_fid" ]; then
+      rparent_page="$(planmap_lookup "$rparent_fid")"
+      [ -n "$rparent_page" ] || log_deliver "plan grain: parent $rparent_fid not yet resolved for $rfid — relation omitted"
+    fi
+
+    rpage="$(planmap_lookup "$rfid")"
+    if [ -z "$rpage" ]; then
+      rpage="$(query_page "$pdb" "$ptok" "$rfid")"
+      [ -n "$rpage" ] && planmap_record "$rfid" "$rpage"
+    fi
+
+    if [ -n "$rpage" ]; then
+      rprops="$(printf '%s' "$row" | plan_row_properties "$prepo" "$pts" "$rparent_page" 0)"
+      rbody="$(jq -n --argjson p "$rprops" '{properties: $p}')"
+      rresp="$(notion_curl PATCH "$NOTION_API/pages/$rpage" "$ptok" "$rbody")"
+    else
+      rprops="$(printf '%s' "$row" | plan_row_properties "$prepo" "$pts" "$rparent_page" 1)"
+      rbody="$(jq -n --arg db "$pdb" --argjson p "$rprops" '{parent: {database_id: $db}, properties: $p}')"
+      rresp="$(notion_curl POST "$NOTION_API/pages" "$ptok" "$rbody")"
+    fi
+
+    rcode="$(printf '%s' "$rresp" | tail -1)"
+    case "$rcode" in
+      2*)
+        pok=$((pok + 1))
+        [ -z "$(planmap_lookup "$rfid")" ] && planmap_record "$rfid" "$(printf '%s' "$rresp" | sed '$d' | jq -r '.id // empty' 2>/dev/null)"
+        ;;
+      *)
+        pfail=$((pfail + 1))
+        log_deliver "plan-grain row $rfid → HTTP ${rcode:-none} (non-blocking, continuing)"
+        ;;
+    esac
+  done
+  log_deliver "plan grain deliver complete: $pok upserted, $pfail failed (non-blocking) — db=$pdb"
+}
+
 deliver_headless() {
   board_enabled || { log_deliver "board disabled (board.enabled != true) — deliver skipped"; return 0; }
   var="$(token_env_name)"
@@ -364,6 +585,13 @@ deliver_headless() {
     esac
   done
   log_deliver "deliver complete: $ok upserted, $fail failed (non-blocking) — repo=$repo"
+
+  pdb="$(board_cfg plan_database_id)"
+  if [ -z "$pdb" ]; then
+    log_deliver "plan grain: no plan_database_id — skipped"
+  else
+    deliver_plan_grain "$proj" "$pdb" "$tok" "$repo" "$ts"
+  fi
   return 0
 }
 

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

@@ -0,0 +1,291 @@
+#!/usr/bin/env sh
+# Fixture-repo test suite for the phase+plan grain projection (m-57, plan 103-01).
+#
+# Contract under test (context/m-57.md LOCKED derivation + must_haves.truths):
+#   --emit adds a phase_rows[] array alongside units[]: one Phase-grain row per
+#   roadmap phases[] entry (including never-planned ones, progress: unplanned)
+#   plus one Plan-grain row per plan-*.md on disk under that phase's dir, with
+#   `parent` pointing at the phase row's forge_id. Progress derives from the
+#   milestone cursor (state/milestone-{id}.yml): no dir => unplanned; dir but
+#   cursor not reached => planned; cursor AT the phase (executing/verifying/
+#   reviewing) => in_progress; behind the cursor or milestone complete => done.
+#   Intent is the roadmap `status:` value verbatim (never re-derived). --emit
+#   stays deterministic (no wall-clock). --deliver upserts phase_rows to
+#   board.plan_database_id only when set; unset => one skip line, unit
+#   delivery byte-for-byte unchanged (inert by construction, ADR-025 pattern).
+#
+# Builds a throwaway git repo in a mktemp dir, no remote, offline by construction.
+# The plan-db-inert case shadows `curl` with a PATH stub (same technique as
+# board-render-deliver.test.sh) so --deliver runs its real logic with zero
+# network traffic.
+#
+# Usage: ./.forge/checks/tests/forge-board-render.test.sh [--case <name>]
+#   cases: unplanned-visible, cursor-derivation, plan-parent-link,
+#          emit-deterministic, plan-db-inert, intent-verbatim,
+#          quoted-id-progress, bare-id-progress
+# RED-phase friendly: a missing/non-executable script fails every case, exits non-zero.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RENDER="$SCRIPT_DIR/../forge-board-render.sh"
+
+CASE=""
+if [ "${1:-}" = "--case" ]; then CASE="${2:-}"; fi
+
+command -v jq >/dev/null 2>&1 || { printf 'FATAL: jq required\n' >&2; exit 1; }
+[ -f "$RENDER" ] || printf 'NOTE: %s missing — RED phase, every case should FAIL\n' "$RENDER" >&2
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null
+export GIT_CONFIG_GLOBAL GIT_CONFIG_SYSTEM
+
+PASSED=0; FAILED=0
+ok()  { PASSED=$((PASSED+1)); printf '  ok   %s\n' "$1"; }
+bad() { FAILED=$((FAILED+1)); printf '  FAIL %s\n     %s\n' "$1" "$2"; }
+want_case() { [ -z "$CASE" ] || [ "$CASE" = "$1" ]; }
+
+# --- build the fixture repo -------------------------------------------------
+# One milestone (m-60), four phases spanning all four progress states + one
+# arbitrary Intent value ("next") to prove verbatim passthrough:
+#   200 earlier  — dir on disk, behind cursor (201)          => done
+#   201 first    — dir on disk, AT cursor, status executing  => in_progress
+#   202 gap      — NO dir on disk                            => unplanned
+#   203 later    — dir on disk, ahead of cursor               => planned
+REPO="$ROOT/proj"
+mkdir -p "$REPO/.forge/state" "$REPO/.forge/checks" \
+  "$REPO/.forge/phases/milestone-60/200-earlier" \
+  "$REPO/.forge/phases/milestone-60/201-first" \
+  "$REPO/.forge/phases/milestone-60/203-later"
+cd "$REPO" || exit 1
+git init -q -b main; git config user.email t@t; git config user.name t
+
+: > .forge/phases/milestone-60/200-earlier/plan-01.md
+: > .forge/phases/milestone-60/201-first/plan-01.md
+: > .forge/phases/milestone-60/201-first/plan-02.md
+: > .forge/phases/milestone-60/203-later/plan-01.md
+
+cat > .forge/state/milestone-60.yml <<'EOF'
+milestone:
+  id: m-60
+  name: "Fixture milestone"
+current:
+  tier: standard
+  phase: 201
+  status: executing
+  plan: 1
+lifecycle:
+  deferred_at: null
+  resumed_at: null
+EOF
+
+# Regression-guard pair for issue #49: milestone-53 pairs with a roadmap
+# milestones[] entry spelled quoted/labeled ("m-53"); milestone-55 pairs with
+# one spelled bare (55) — mirrors the two spellings live in this repo's own
+# roadmap.yml. Both mid-phase (status: executing, cursor at the SECOND
+# declared phase) so a real, non-trivial N/M (1/2) is the only way either
+# case passes — not just "non-empty".
+cat > .forge/state/milestone-53.yml <<'EOF'
+milestone:
+  id: m-53
+  name: "Quoted-id fixture milestone"
+current:
+  tier: standard
+  phase: 94
+  status: executing
+  plan: 1
+lifecycle:
+  deferred_at: null
+  resumed_at: null
+EOF
+
+cat > .forge/state/milestone-55.yml <<'EOF'
+milestone:
+  id: m-55
+  name: "Bare-id fixture milestone"
+current:
+  tier: standard
+  phase: 99
+  status: executing
+  plan: 1
+lifecycle:
+  deferred_at: null
+  resumed_at: null
+EOF
+
+cat > .forge/roadmap.yml <<'EOF'
+roadmap:
+  milestones:
+    - id: 60
+      name: "Fixture milestone"
+      phases: [200, 201, 202, 203]
+    - id: "m-53"
+      name: "Quoted-id fixture milestone"
+      phases: [93, 94]
+    - id: 55
+      name: "Bare-id fixture milestone"
+      phases: [98, 99]
+  phases:
+    - id: 200
+      name: "earlier"
+      milestone: "60"
+      status: complete
+    - id: 201
+      name: "first"
+      milestone: "60"
+      status: active
+    - id: 202
+      name: "gap"
+      milestone: "60"
+      status: next
+    - id: 203
+      name: "later"
+      milestone: "60"
+      status: planned
+  waves: []
+EOF
+
+cat > .forge/project.yml <<'EOF'
+project: { name: fixture }
+board:
+  enabled: true
+  provider: notion
+  database_id: db-fixture-unit-000
+  repo: fixturerepo
+  ci_token_env: FORGE_NOTION_TOKEN
+EOF
+git add -A; git commit -qm init
+
+run_emit() { cd "$REPO" && sh "$RENDER" --emit 2>/dev/null; }
+OUT="$(run_emit)"
+
+# ============================================================================
+# Case: unplanned-visible — a never-planned phase (202, no dir) still gets a
+# row, and it reads progress: unplanned.
+# ============================================================================
+if want_case unplanned-visible; then
+  prog=$(printf '%s' "$OUT" | jq -r '.phase_rows[] | select(.forge_id=="m-60/202") | .progress')
+  if [ "$prog" = "unplanned" ]; then ok "never-planned phase 202 visible with progress: unplanned"
+  else bad "unplanned-visible" "got progress=[$prog]"; fi
+fi
+
+# ============================================================================
+# Case: cursor-derivation — done/in_progress/planned across three phases,
+# the same story forge's {percent} tells.
+# ============================================================================
+if want_case cursor-derivation; then
+  p200=$(printf '%s' "$OUT" | jq -r '.phase_rows[] | select(.forge_id=="m-60/200") | .progress')
+  p201=$(printf '%s' "$OUT" | jq -r '.phase_rows[] | select(.forge_id=="m-60/201") | .progress')
+  p203=$(printf '%s' "$OUT" | jq -r '.phase_rows[] | select(.forge_id=="m-60/203") | .progress')
+  if [ "$p200" = "done" ] && [ "$p201" = "in_progress" ] && [ "$p203" = "planned" ]; then
+    ok "cursor derivation: 200=done, 201=in_progress, 203=planned"
+  else
+    bad "cursor-derivation" "got 200=[$p200] 201=[$p201] 203=[$p203]"
+  fi
+fi
+
+# ============================================================================
+# Case: plan-parent-link — plan rows carry their parent phase's key.
+# ============================================================================
+if want_case plan-parent-link; then
+  parent=$(printf '%s' "$OUT" | jq -r '.phase_rows[] | select(.forge_id=="m-60/201/plan-01") | .parent')
+  if [ "$parent" = "m-60/201" ]; then ok "plan row m-60/201/plan-01 parents to m-60/201"
+  else bad "plan-parent-link" "got parent=[$parent]"; fi
+fi
+
+# ============================================================================
+# Case: emit-deterministic — two consecutive --emit runs, no repo change,
+# byte-identical output.
+# ============================================================================
+if want_case emit-deterministic; then
+  a="$(run_emit)"; b="$(run_emit)"
+  if [ "$a" = "$b" ] && [ -n "$a" ]; then ok "two --emit runs are byte-identical"
+  else bad "emit-deterministic" "runs differ or empty"; fi
+fi
+
+# ============================================================================
+# Case: intent-verbatim — Intent is the roadmap status: value verbatim, never
+# re-derived (phase 202's "next" — outside the {planned,complete} pair used
+# elsewhere in this fixture — proves passthrough, not a coincidental match).
+# ============================================================================
+if want_case intent-verbatim; then
+  intent=$(printf '%s' "$OUT" | jq -r '.phase_rows[] | select(.forge_id=="m-60/202") | .intent')
+  if [ "$intent" = "next" ]; then ok "intent projected verbatim (next, unchanged)"
+  else bad "intent-verbatim" "got intent=[$intent]"; fi
+fi
+
+# ============================================================================
+# Case: quoted-id-progress (issue #49) — the roadmap milestones[] entry for
+# m-53 is spelled quoted/labeled (- id: "m-53"). Before the fix, unit_progress()
+# only matched unquoted ids and silently rendered progress: "" despite m-53
+# declaring phases. Assert a real N/M instead.
+# ============================================================================
+if want_case quoted-id-progress; then
+  prog=$(printf '%s' "$OUT" | jq -r '.units[] | select(.forge_id=="m-53") | .progress')
+  if [ "$prog" = "1/2" ]; then ok "quoted-id m-53 progress resolves to 1/2 (not empty)"
+  else bad "quoted-id-progress" "got progress=[$prog]"; fi
+fi
+
+# ============================================================================
+# Case: bare-id-progress — regression guard for the 120 legacy bare-numeric
+# roadmap.yml milestones[] entries (- id: 55): the tolerant match must not
+# break what already worked.
+# ============================================================================
+if want_case bare-id-progress; then
+  prog=$(printf '%s' "$OUT" | jq -r '.units[] | select(.forge_id=="m-55") | .progress')
+  if [ "$prog" = "1/2" ]; then ok "bare-id m-55 progress unchanged at 1/2"
+  else bad "bare-id-progress" "got progress=[$prog]"; fi
+fi
+
+# ============================================================================
+# Case: plan-db-inert — board.plan_database_id unset: --deliver leaves unit
+# delivery untouched and logs one plan-grain skip line, no network (curl is a
+# PATH stub — canned responses only, exercised end-to-end offline).
+# ============================================================================
+if want_case plan-db-inert; then
+  STUBBIN="$ROOT/bin"
+  CAPTURE="$ROOT/curl-capture.txt"
+  export CAPTURE
+  mkdir -p "$STUBBIN"
+  cat > "$STUBBIN/curl" <<'STUB'
+#!/usr/bin/env sh
+{ printf '=== call ===\n'; for a in "$@"; do printf '%s\n' "$a"; done; } >> "$CAPTURE"
+url=""
+for a in "$@"; do case "$a" in https://*) url="$a" ;; esac; done
+case "$url" in
+  */query) printf '{"object":"list","results":[]}\n200' ;;
+  *)       printf '{"object":"page","id":"stub-page-x"}\n200' ;;
+esac
+STUB
+  chmod +x "$STUBBIN/curl"
+  : > "$CAPTURE"
+
+  cd "$REPO" && PATH="$STUBBIN:$PATH" env FORGE_NOTION_TOKEN=ci-env-fake-value-do-not-use \
+    sh "$RENDER" --deliver >/dev/null 2>"$ROOT/err.txt"
+  rc=$?
+
+  [ "$rc" -eq 0 ] && ok "deliver exits 0 with plan_database_id unset" || bad "plan-db-inert exit 0" "rc=$rc"
+
+  if grep -q 'plan grain: no plan_database_id' "$ROOT/err.txt"; then
+    ok "logs the plan-grain skip line"
+  else
+    bad "plan-grain skip log" "got: $(cat "$ROOT/err.txt")"
+  fi
+
+  # unit delivery untouched: every --emit unit forge_id still reaches curl
+  missing=""
+  for fid in $(cd "$REPO" && sh "$RENDER" --emit 2>/dev/null | jq -r '.units[].forge_id'); do
+    grep -q "$fid" "$CAPTURE" || missing="$missing $fid"
+  done
+  [ -z "$missing" ] && ok "unit delivery unchanged (all unit forge_ids still reached curl)" \
+    || bad "unit delivery unchanged" "forge_ids never delivered:$missing"
+
+  # zero interaction with the plan grain: no phase/plan forge_id, no Grain property
+  if grep -q 'm-60/2' "$CAPTURE"; then bad "no plan-grain forge_ids sent" "found one in curl traffic"
+  else ok "no plan-grain forge_ids reached curl"; fi
+  if grep -q '"Grain"' "$CAPTURE"; then bad "no Grain property sent" "found one in curl traffic"
+  else ok "no Grain property reached curl (plan grain never touched)"; fi
+fi
+
+printf '\n%s passed, %s failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]

package/template/.forge/migrations/0.82.0-roadmap-self-description.md

@@ -0,0 +1,180 @@
+# Migration Guide: roadmap self-description — milestone keys + Intent normalization (Forge 0.82.0)
+
+Applies to projects upgrading to 0.82.0 or later whose `.forge/roadmap.yml` predates
+the board's phase+plan grain work (m-57, research/milestone-57.md). Two mechanical
+edits land on `.forge/roadmap.yml`: every `phases[]` entry gains an explicit
+`milestone:` field naming its owning milestone, and every phase's `status:` field is
+normalized to the closed Intent vocabulary `planned | next | active | deferred |
+complete`. Neither edit is optional — phase 103 (phase-plan-projection)'s board
+renderer reads both fields directly, so an unmigrated `roadmap.yml` renders the
+Roadmap/In-flight views with blank or unpredictable Grain/Intent columns.
+
+This is forge's own dogfooded worked example: this repo's `.forge/roadmap.yml` (96
+phase entries) was migrated by this same procedure in the phase that shipped this
+guide. The mechanics below generalize from that pass, plus the repeating-phase-id
+case forge's own repo does not have but a fan-out repo like canvaz does.
+
+## Prerequisites
+
+1. On 0.82.0 or later (`npx forge-orkes upgrade`, or the `upgrading` skill) —
+   `.forge/checks/forge-roadmap-check.sh` must exist so step 4 below can validate
+   the result.
+2. Working tree clean or changes committed — this migration is a mechanical text
+   edit across every `phases[]` entry in `.forge/roadmap.yml`, plus (if stale) one
+   `board.database_id` line in `.forge/project.yml`.
+3. Read `.forge/roadmap.yml`'s `milestones:` list once before editing — it is the
+   ONLY authoritative source for which milestone owns which phase id. Do not guess
+   ownership from comments, directory names, or proximity in the file.
+
+## Detection
+
+Keyed on any `phases[]` entry lacking a `milestone:` field. Tolerant of a missing
+file, a non-git tree, or an already-migrated repo (silent, exit 0 in all three
+cases). Scoped to the `phases:` block only — the `milestones:` list's own `- id:`
+entries are a different, unrelated shape and are never counted:
+
+```bash
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+[ -f .forge/roadmap.yml ] || exit 0
+
+missing="$(awk '
+  BEGIN { in_phases=0; open=0; has_ms=1; count=0 }
+  /^  phases:$/ { in_phases=1; next }
+  /^  coverage_verified:/ { in_phases=0 }
+  in_phases && /^    - id:/ {
+    if (open && !has_ms) count++
+    open=1; has_ms=0
+    next
+  }
+  in_phases && open && /^      milestone:/ { has_ms=1 }
+  END { if (open && !has_ms) count++; print count }
+' .forge/roadmap.yml)"
+
+[ -n "$missing" ] && [ "$missing" -gt 0 ] 2>/dev/null || exit 0
+
+echo "MIGRATE — $missing phases[] entries in .forge/roadmap.yml have no milestone: field; see .forge/migrations/0.82.0-roadmap-self-description.md"
+```
+
+## Migration steps
+
+### 1. Derive each phase's owning milestone from `milestones:` — never guess
+
+`.forge/roadmap.yml`'s `phases:` list is flat: phase ids are unique only within a
+single milestone's line-of-work, not globally. **In a repo where planning
+allocated ids per-milestone starting from 1 each time (the canvaz shape), phase
+`id: 1` repeats once per milestone — e.g. canvaz's `id: 1` appears 29 times, `id:
+2` appears 24 times** — disambiguated today only by a human-readable comment or
+proximity to a `# --- m-N ---` divider, which is exactly the ambiguity this field
+removes. (Forge's own repo does not have this problem — `.forge/checks/forge-reserve.sh`
+allocates phase ids from a single ledger, so every id here is already globally
+unique — but the `milestone:` field ships on every repo's roadmap regardless,
+because self-description should not depend on which id-allocation convention a
+given repo happens to use.)
+
+The `milestones:` list's `phases: [...]` array is the ONLY authoritative map. For
+each milestone entry:
+
+```yaml
+    - id: 7
+      name: "Some Milestone"
+      phases: [23, 24, 25]
+```
+
+every id in that array gets `milestone: "7"` (as a quoted string, matching the
+convention already used for named milestone ids like `"m-33"`). Concretely, for
+each `phases[]` entry:
+
+1. Find the milestone whose `phases: [...]` array (one-line flow, wrapped flow, or
+   block style — `forge-roadmap-check.sh` already parses all three shapes) contains
+   this phase's id.
+2. Insert `milestone: "<that milestone's id>"` as a new line directly after the
+   phase's `name:` line, before `milestone_dir:` (or `goal:` if the entry has no
+   `milestone_dir:`). Quote the value even when the milestone id is a bare number —
+   `milestone: "7"`, not `milestone: 7` — so numeric and named ids (`"m-33"`) render
+   identically wherever this field is read.
+3. **Every phase id must resolve to exactly one milestone.** If a phase id appears
+   in zero or more than one milestone's `phases:` array, stop and flag it to the
+   repo's operator instead of guessing — that is a pre-existing roadmap defect this
+   migration should surface, not silently paper over. (`forge-roadmap-check.sh`'s
+   `orphan-phase` and `dangling-phase-ref` findings catch exactly this class; run it
+   before this migration if you suspect drift.)
+4. Do not renumber, reorder, reindent, or touch any other field on any phase or
+   milestone entry. This is a shared-mutable file (other milestones' in-flight work
+   may be reading it concurrently) — the only permitted diff per entry is the one
+   inserted `milestone:` line plus the `status:` value substitution in step 2 below.
+
+### 2. Normalize every `status:` value to the closed Intent vocabulary
+
+The Intent vocabulary is a closed set: `planned | next | active | deferred |
+complete`. A drift survey (research/milestone-57.md, canvaz's 107-entry roadmap)
+found seven distinct values in the wild. Apply this map verbatim to every
+`phases[]` entry's `status:` field — nothing else:
+
+| Observed value | Normalized to | Note |
+|---|---|---|
+| `planned` | `planned` | unchanged — already in the closed set |
+| `pending` | `planned` | most common drift; "not yet started" reads as `planned` |
+| `complete` | `complete` | unchanged — already in the closed set |
+| `deferred` | `deferred` | unchanged — already in the closed set |
+| `verified` | `complete` | a finished phase, whatever verb described it |
+| `planning` | `active` | in-progress work, whichever gerund named the stage |
+| `executing` | `active` | in-progress work, whichever gerund named the stage |
+
+If your repo's `roadmap.yml` carries a `status:` value not in this table (this
+repo's own migration hit exactly one: a stray `done`, on a single phase, not
+anticipated by the survey above) — treat any other terminal-sounding value
+(`done`, `shipped`, `finished`, …) the same way `verified` is treated: it collapses
+to `complete`. Do not invent a sixth Intent value; the set is closed by design (the
+board's Intent column is a Notion Select over exactly these five). A trailing `#
+prose` comment after a status value moves to a comment line directly above the
+`status:` field rather than being dropped — the normalized line itself must be bare
+(`status: <value>`, nothing after it but optional whitespace).
+
+### 3. Check `board.database_id` in `project.yml` points at the live workspace
+
+If this repo has a `board:` block in `.forge/project.yml` (ADR-025 — absent means
+this step is inert, skip it), confirm `database_id` names the Notion database in
+the workspace you actually intend to render into, not one that was abandoned or
+replaced. This class of drift is easy to miss because **attended renders (an
+interactive Claude Code session with the Notion MCP server) mask a stale id** — the
+session's cached `.forge/notion/map.yml` page-ids keep resolving even after the
+configured database itself has drifted, since the MCP calls key off page ids, not
+the database id, once a row's `notion_page_id` is already cached. The gap only
+surfaces in `forge-board-render.sh --deliver` (headless, CI, no MCP session, no
+cached map) — which would write into the wrong (possibly dead) workspace with no
+attended session present to notice.
+
+```bash
+grep -n -A5 "^board:" .forge/project.yml
+```
+
+Confirm `database_id` against the database you can actually open in the Notion
+workspace you're rendering into today, not one recorded from an earlier workspace
+migration. If it's stale, update it by hand — this is a one-line config edit, not
+something this migration automates (the correct id can only come from the
+operator, who knows which workspace is live).
+
+### 4. Re-run the roadmap integrity check
+
+```bash
+.forge/checks/forge-roadmap-check.sh
+```
+
+Compare its `finding=` line count against what it printed before you started this
+migration. This migration must not introduce any NEW finding — pre-existing
+findings unrelated to this change (e.g. a dangling wave reference from an earlier
+drift) are not this migration's job to fix and may remain.
+
+## Validation
+
+- `grep -c '^      milestone: ' .forge/roadmap.yml` matches the number of
+  `phases[]` entries (`grep -c '^    - id:' .forge/roadmap.yml` restricted to the
+  `phases:` block — every phase, no more, no fewer).
+- No `status:` value under a `phases[]` entry falls outside `planned | next |
+  active | deferred | complete`.
+- `.forge/checks/forge-roadmap-check.sh` exits with the same finding count (or
+  fewer) as before the migration — never more.
+- If `board:` is configured, `database_id` names a database you can open today in
+  the live Notion workspace.
+- Re-running the Detection block above now prints nothing (exits silently) — the
+  gap is closed.