forge-orkes 0.46.0 → 0.50.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.46.0",
+  "version": "0.50.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/agents/verifier.md

@@ -24,9 +24,9 @@ Plan+must_haves (`.forge/phases/milestone-{id}/{phase}-{name}/plan.md`), executi
 **Status**: PASS | FAIL | PARTIAL
 
 ## Observable Truths
-| Truth | Status | Evidence |
-|-------|--------|----------|
-| {from must_haves} | PASS/FAIL | {observed} |
+| Truth | Evidence (command → exit code; output excerpt) | Status |
+|-------|-----------------------------------------------|--------|
+| {from must_haves} | {executed command} → {exit}; {excerpt} | PASS/FAIL/UNCERTAIN/HUMAN |
 
 ## Artifacts
 | Artifact | Exists | Substantive | Wired | Evidence |
@@ -64,7 +64,10 @@ Read: .forge/deferred-issues.md → known pre-existing failures (if exists; trea
 ```
 
 ### 2. Truths
-Per truth: determine method, execute, record PASS+evidence or FAIL+actual.
+Per truth, three branches (executed-evidence rule — canonical statement: verifying SKILL Level 1):
+1. Declared `check:` in must_haves → EXECUTE it. Exit 0 = PASS, non-zero = FAIL. Record command + exit code + output excerpt.
+2. No declared check → run your OWN command and record the same evidence triple — executed evidence qualifies regardless of plan vintage.
+3. No executed evidence → UNCERTAIN, or HUMAN for `manual:`-routed truths (never execute the route text as shell). **Never PASS on judgment alone** — the exit code, not your assessment, is the verdict.
 
 ### 3. Artifacts
 Per artifact:
@@ -138,6 +141,7 @@ gaps:
 
 ## Anti-Patterns
 - **Fix-while-verifying**: Report, don't fix
+- **Evidence-free PASS**: No executed command recorded → verdict must be UNCERTAIN, never PASS
 - **Surface-level**: Exists != substantive
 - **Skip wired**: Code exists but unused
 - **Trust count**: Passing != correct coverage

package/template/.claude/hooks/forge-model-outcome.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env sh
+# forge-model-outcome — advisory per-task model-routing outcome log + promotion
+# ladder (M24 phases 37-38).
+#
+#   forge-model-outcome.sh record [--repo R] [--milestone M] [--skill S]
+#     [--task-type T] [--complexity C] [--model MO] [--first-try-pass true|false]
+#     [--check-exit N]
+#
+# Appends ONE printf-built JSON line to ${FORGE_HOME:-$HOME}/.forge/model-outcomes.jsonl
+# (honors $HOME so tests can redirect it). Lazily creates the dir + file.
+#
+# ADVISORY, always: any failure (unwritable home, etc.) is swallowed and this
+# helper still exits 0 — logging must never block or fail a task. The write
+# path is dependency-free (printf only, no jq/python — NFR-026).
+#
+#   forge-model-outcome.sh recommend
+#
+# Reads the log and prints an untested -> probation -> proven promotion ladder
+# per (model, task_type), plus concrete routing recommendations for proven
+# buckets. The READ path may use jq (unlike record's write path). Degrades to
+# an "insufficient data" message + exit 0 when jq is absent or the log is
+# absent/empty — never errors (NFR-026).
+#
+# Pinned field set (contract between record + recommend; keep names stable):
+#   ts repo milestone skill task_type complexity model first_try_pass check_exit
+set -u
+
+usage() {
+  cat <<'EOF' >&2
+usage: forge-model-outcome.sh record [--repo R] [--milestone M] [--skill S]
+         [--task-type T] [--complexity C] [--model MO] [--first-try-pass true|false]
+         [--check-exit N]
+       forge-model-outcome.sh recommend
+EOF
+}
+
+log_path() {
+  home="${FORGE_HOME:-$HOME}"
+  printf '%s/.forge/model-outcomes.jsonl' "$home"
+}
+
+do_record() {
+  # --- parse flags (ALL optional — missing -> empty string / null) ---------
+  repo=""; milestone=""; skill=""; task_type=""; complexity=""; model=""
+  first_try_pass=""; check_exit=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --repo) shift; repo="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --repo=*) repo="${1#*=}"; shift ;;
+      --milestone) shift; milestone="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --milestone=*) milestone="${1#*=}"; shift ;;
+      --skill) shift; skill="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --skill=*) skill="${1#*=}"; shift ;;
+      --task-type) shift; task_type="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --task-type=*) task_type="${1#*=}"; shift ;;
+      --complexity) shift; complexity="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --complexity=*) complexity="${1#*=}"; shift ;;
+      --model) shift; model="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --model=*) model="${1#*=}"; shift ;;
+      --first-try-pass) shift; first_try_pass="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --first-try-pass=*) first_try_pass="${1#*=}"; shift ;;
+      --check-exit) shift; check_exit="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --check-exit=*) check_exit="${1#*=}"; shift ;;
+      -*) printf 'forge-model-outcome: unknown option: %s (ignored)\n' "$1" >&2; shift ;;
+      *) shift ;;
+    esac
+  done
+
+  dir="$(dirname "$(log_path)")"
+  log="$(log_path)"
+
+  # Escape backslash then double-quote for a JSON string value — these are
+  # controlled enums/basenames, so this minimal escape is enough (no jq).
+  esc() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)"
+
+  fp="false"
+  case "$first_try_pass" in
+    true|1|yes) fp="true" ;;
+    *) fp="false" ;;
+  esac
+
+  ce="null"
+  case "$check_exit" in
+    ''|*[!0-9-]*) ce="null" ;;
+    *) ce="$check_exit" ;;
+  esac
+
+  line=$(printf '{"ts":"%s","repo":"%s","milestone":"%s","skill":"%s","task_type":"%s","complexity":"%s","model":"%s","first_try_pass":%s,"check_exit":%s}' \
+    "$(esc "$ts")" "$(esc "$repo")" "$(esc "$milestone")" "$(esc "$skill")" \
+    "$(esc "$task_type")" "$(esc "$complexity")" "$(esc "$model")" "$fp" "$ce")
+
+  # The whole create+append is best-effort: swallow any failure (unwritable
+  # home, read-only fs, a ".forge" that's a regular file, ...) and exit 0
+  # regardless — a task must never be blocked or failed by this log.
+  ( mkdir -p "$dir" && printf '%s\n' "$line" >> "$log" ) 2>/dev/null
+  exit 0
+}
+
+do_recommend() {
+  # Promotion-ladder thresholds (Ringer parity) — documented constants.
+  VOLUME_MIN=5          # count < VOLUME_MIN -> untested
+  PROVEN_CUTOFF=0.90    # count >= VOLUME_MIN and pass_rate >= PROVEN_CUTOFF -> proven; else probation
+
+  log="$(log_path)"
+
+  if ! command -v jq >/dev/null 2>&1; then
+    printf 'recommendations unavailable: jq not found (insufficient data)\n'
+    exit 0
+  fi
+  if [ ! -s "$log" ]; then
+    printf 'recommendations unavailable: no outcome data yet (insufficient data)\n'
+    exit 0
+  fi
+
+  buckets="$(jq -sc --argjson min "$VOLUME_MIN" --argjson cutoff "$PROVEN_CUTOFF" '
+    group_by([.model, .task_type])
+    | map(
+        {
+          model: .[0].model,
+          task_type: .[0].task_type,
+          count: length,
+          pass_rate: (([ .[] | select(.first_try_pass == true) ] | length) / length)
+        }
+        | . + {
+            status: (
+              if .count < $min then "untested"
+              elif .pass_rate >= $cutoff then "proven"
+              else "probation"
+              end
+            )
+          }
+      )
+    | .[]
+  ' "$log" 2>/dev/null)"
+
+  if [ -z "$buckets" ]; then
+    printf 'recommendations unavailable: no outcome data yet (insufficient data)\n'
+    exit 0
+  fi
+
+  cutoff_pct="$(awk -v c="$PROVEN_CUTOFF" 'BEGIN{printf "%.0f", c*100}')"
+  printf 'Model-outcome promotion ladder (volume >= %s runs, proven cutoff >= %s%% first-try):\n\n' "$VOLUME_MIN" "$cutoff_pct"
+
+  printf '%s\n' "$buckets" | while IFS= read -r b; do
+    model="$(printf '%s' "$b" | jq -r '.model')"
+    task_type="$(printf '%s' "$b" | jq -r '.task_type')"
+    count="$(printf '%s' "$b" | jq -r '.count')"
+    status="$(printf '%s' "$b" | jq -r '.status')"
+    pct="$(printf '%s' "$b" | jq -r '.pass_rate' | awk '{printf "%.0f", $1*100}')"
+    printf '  model=%-10s task_type=%-14s status=%-10s count=%-4s first-try=%s%%\n' "$model" "$task_type" "$status" "$count" "$pct"
+  done
+
+  printf '\nRouting recommendations:\n'
+  printf '%s\n' "$buckets" | while IFS= read -r b; do
+    status="$(printf '%s' "$b" | jq -r '.status')"
+    [ "$status" = "proven" ] || continue
+    model="$(printf '%s' "$b" | jq -r '.model')"
+    task_type="$(printf '%s' "$b" | jq -r '.task_type')"
+    count="$(printf '%s' "$b" | jq -r '.count')"
+    pct="$(printf '%s' "$b" | jq -r '.pass_rate' | awk '{printf "%.0f", $1*100}')"
+    printf '  %s is proven on %s tasks (%s runs, %s%% first-try) -> route %s tasks to %s\n' "$model" "$task_type" "$count" "$pct" "$task_type" "$model"
+  done
+
+  exit 0
+}
+
+cmd="${1:-}"
+[ $# -gt 0 ] && shift || true
+
+case "$cmd" in
+  record) do_record "$@" ;;
+  recommend) do_recommend ;;
+  ""|-h|--help) usage; exit 0 ;;
+  *) printf 'forge-model-outcome: unknown subcommand: %s\n' "$cmd" >&2; usage; exit 2 ;;
+esac

package/template/.claude/hooks/tests/forge-model-outcome.test.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env sh
+# Self-contained unit test for .claude/hooks/forge-model-outcome.sh (M24 phase 37).
+#
+# Needs no network and no fixtures beyond a temp dir. Each case runs the helper
+# with an isolated $HOME and asserts its exit code + the jsonl file's contents.
+# jq is used HERE to parse the helper's output for assertions — the helper's
+# own write path never uses jq (printf only; see forge-model-outcome.sh, NFR-026).
+# Run:
+#   ./.claude/hooks/tests/forge-model-outcome.test.sh
+# Exits 0 iff every case passes; non-zero on any failure. Self-cleans on exit.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HELPER="$SCRIPT_DIR/../forge-model-outcome.sh"
+
+[ -x "$HELPER" ] || { printf 'FATAL: helper not executable: %s\n' "$HELPER" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { printf 'FATAL: jq required for test assertions\n' >&2; exit 1; }
+
+ROOT="$(mktemp -d)"
+trap 'rm -rf "$ROOT"' EXIT INT TERM
+
+PASSED=0
+FAILED=0
+pass() { PASSED=$((PASSED + 1)); printf 'PASS: %s\n' "$1"; }
+fail() { FAILED=$((FAILED + 1)); printf 'FAIL: %s\n' "$1" >&2; }
+
+# --- Case 1: record appends one valid jsonl line with the pinned fields -----
+d="$ROOT/case1"; mkdir -p "$d"
+HOME="$d" "$HELPER" record --repo forge --milestone m24 --skill executing \
+  --task-type docs --complexity trivial --model haiku --first-try-pass true --check-exit 0 >/dev/null
+if [ -f "$d/.forge/model-outcomes.jsonl" ]; then
+  pass "case1 log file created"
+else
+  fail "case1 log file not created"
+fi
+line="$(tail -1 "$d/.forge/model-outcomes.jsonl" 2>/dev/null)"
+if printf '%s' "$line" | jq -e \
+  '.task_type=="docs" and .complexity=="trivial" and .model=="haiku" and .first_try_pass==true and .check_exit==0 and .repo=="forge" and .milestone=="m24" and .skill=="executing"' \
+  >/dev/null 2>&1; then
+  pass "case1 line carries pinned fields"
+else
+  fail "case1 line missing/incorrect fields: $line"
+fi
+
+# --- Case 2: unwritable home degrades to exit 0, never blocks ---------------
+d="$ROOT/case2"; mkdir -p "$d"
+: > "$d/.forge"   # regular file where a dir is expected -> mkdir -p fails
+HOME="$d" "$HELPER" record --repo forge --milestone m24 --skill executing --model haiku >/dev/null 2>&1
+rc=$?
+check_rc() { [ "$1" -eq "$2" ] && pass "$3" || fail "$3 (got exit $1, want $2)"; }
+check_rc "$rc" 0 "case2 unwritable home still exits 0"
+
+# --- Case 3: two record calls append, they do not overwrite -----------------
+d="$ROOT/case3"; mkdir -p "$d"
+HOME="$d" "$HELPER" record --repo forge --milestone m24 --skill executing --model haiku --task-type docs >/dev/null
+HOME="$d" "$HELPER" record --repo forge --milestone m24 --skill executing --model opus --task-type code-feature >/dev/null
+lines="$(wc -l < "$d/.forge/model-outcomes.jsonl" | tr -d ' ')"
+if [ "$lines" = "2" ]; then
+  pass "case3 two calls -> two lines (append, not overwrite)"
+else
+  fail "case3 expected 2 lines, got $lines"
+fi
+
+# --- Case 4: recommend — proven bucket (volume met, high pass rate) --------
+d="$ROOT/case4"; mkdir -p "$d"
+i=1
+while [ "$i" -le 6 ]; do
+  HOME="$d" "$HELPER" record --repo x --milestone m24 --skill executing \
+    --task-type docs --complexity trivial --model haiku --first-try-pass true --check-exit 0 >/dev/null
+  i=$((i + 1))
+done
+out="$(HOME="$d" "$HELPER" recommend)"
+if printf '%s' "$out" | grep -qi 'proven' && printf '%s' "$out" | grep -qi 'docs' && printf '%s' "$out" | grep -qi 'haiku'; then
+  pass "case4 recommend marks (haiku,docs) proven + recommends routing"
+else
+  fail "case4 recommend missing proven/docs/haiku: $out"
+fi
+
+# --- Case 5: recommend — probation bucket (volume met, sub-cutoff pass rate) -
+d="$ROOT/case5"; mkdir -p "$d"
+i=1
+while [ "$i" -le 5 ]; do
+  fp="true"; [ "$i" -le 2 ] && fp="false"   # 3/5 = 60% < 90% cutoff
+  HOME="$d" "$HELPER" record --repo x --milestone m24 --skill executing \
+    --task-type code-fix --complexity standard --model sonnet --first-try-pass "$fp" --check-exit 0 >/dev/null
+  i=$((i + 1))
+done
+out="$(HOME="$d" "$HELPER" recommend)"
+if printf '%s' "$out" | grep -qi 'probation'; then
+  pass "case5 recommend marks sub-cutoff bucket probation"
+else
+  fail "case5 recommend did not mark bucket probation: $out"
+fi
+
+# --- Case 6: recommend degrades on an empty/absent log — exit 0 ------------
+d="$ROOT/case6"; mkdir -p "$d"
+out="$(HOME="$d" "$HELPER" recommend)"
+rc=$?
+check_rc "$rc" 0 "case6 recommend on absent log exits 0"
+if printf '%s' "$out" | grep -qiE 'insufficient|unavailable|no data|not enough'; then
+  pass "case6 recommend on absent log prints insufficient-data message"
+else
+  fail "case6 recommend missing insufficient-data message: $out"
+fi
+
+# --- Report -----------------------------------------------------------------
+printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
+[ "$FAILED" -eq 0 ]

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

@@ -200,7 +200,11 @@ Resume:
 1. Run the Stream Rollup, then load the stream file and brief.
 2. Surface status, blockers, owned surfaces, shared surfaces, and next action.
 3. Set the **stream file's** `status` to `active`, then regenerate `active.yml`.
-4. Run conflict detection before continuing.
+4. **Relocate into the stream worktree (Native Worktree Entry).** When the resumed stream's file records a `runtime.worktree`, apply the canonical Native Worktree Entry contract (identical to the forge ownership-gate option 1):
+   - **If the `EnterWorktree` tool is available**, call `EnterWorktree({path: {runtime.worktree}})` to relocate this session into the stream worktree **in place**, then log `Relocated into worktree {runtime.worktree} ({runtime.branch})` (independent of any prompt, so the cwd move is visible) and continue the resume from inside the worktree.
+   - **If `EnterWorktree` is unavailable** (older Claude Code CLI, or a non-Claude-Code adapter), fall back to printing the `cd {path}` instruction (here `cd {runtime.worktree}`) — today's implicit behavior made explicit.
+   - Streams with no `runtime.worktree` resume unchanged — no relocation attempted. Exit is always `ExitWorktree({action: "keep"})`; the Chief never lets the native tool remove a worktree (teardown/merge stays the Chief's existing flow).
+5. Run conflict detection before continuing.
 
 ## Delegate Flow
 

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

@@ -243,6 +243,33 @@ ID = `DI-{N}` where N = next integer after existing max (or 001 if new file).
 ### Quick Tier
 Run all non-advisory verification commands once after commit. 1 retry max.
 
+### Declared Checks (plan completion)
+
+After the plan's FINAL task commit, extract the `check:` commands from the plan's `must_haves.truths` and run each once. Truths with a `manual:` route have no check to run — skip them (never execute the route text as shell). No declared checks → silent no-op (legacy plans unchanged).
+
+- **Failure** → enters the auto-fix loop above with the check's failure output as fix context; retries count toward the existing 3-strike/deferred-issues rules.
+- **This run is an EARLY SIGNAL only** — it never records a verification verdict. `verifying` re-executes every check fresh and applies the executed-evidence rule.
+- WHY here: the check's failure output is cheapest to act on before context handoff — same reasoning as a retry-with-failure-context loop; waiting for verifying costs a full phase round-trip.
+
+### Model-Outcome Log (mandatory, per task — M24)
+
+Once a task's verification bookkeeping settles (3-Strike result known, declared-check exit code known), call `.claude/hooks/forge-model-outcome.sh record` **once for that task** — this is a MANDATORY step in the bookkeeping, not an optional "consider logging" note (an optional note is exactly the zero-writer failure the M11 desire-path signal caught). Source every field from state the gate already computed — no new instrumentation:
+
+```
+.claude/hooks/forge-model-outcome.sh record \
+  --repo "$(basename "$(git rev-parse --show-toplevel)")" \
+  --milestone "m{id}" --skill executing \
+  --task-type "{task.task_type}" --complexity "{task.complexity}" \
+  --model "{model the task's executor ran on}" \
+  --first-try-pass {true|false — passed attempt 1 vs needed a retry} \
+  --check-exit {declared check's exit code, or omit if none}
+```
+
+- `model` is the **per-task resolved model** (phase 36 — `by_complexity` → `skills.executing` → `default` → parent), not a skill-wide constant.
+- `task_type` / `complexity` come from the task's own fields (planning Step 6.2); omit either if the task left them unmarked.
+- **One append per task, every task** — this is what closes the loop phase 38's `recommend` reads from.
+- **Advisory** — the helper is itself dependency-free and always exits 0 (unwritable `~/.forge`, etc. are swallowed); a logging failure NEVER blocks or fails the task.
+
 ## Context Engineering
 
 | Trigger | Action |
@@ -253,8 +280,11 @@ Run all non-advisory verification commands once after commit. 1 retry max.
 | Context 40-60% | Consider fresh agent |
 | Context under 40% | Continue normally |
 | Switching unrelated subsystems | Spawn fresh agent |
+| Task carries ANY `complexity` tag (COST, M24) | Spawn a fresh executor on its resolved model — even under 40% context. Only an UNTAGGED glue task runs inline on the parent model. |
+
+**Spawn via Agent tool** with: relevant plan details, specific files, locked decisions from context.md, clear success criteria. **Resolve the model PER TASK**, not once per skill run: `models.by_complexity.{task.complexity}` → `models.skills.executing` → `models.default` → parent (complexity overrides skill — FORGE.md → Model Routing). Display per spawn: *"Spawning executor with model: {model} (from {source})"*
 
-**Spawn via Agent tool** with: relevant plan details, specific files, locked decisions from context.md, clear success criteria. **Pass `model` param** from `project.yml` model routing (`models.skills.executing` → `models.default` → parent). Display: *"Spawning executor with model: {model} (from {source})"*
+**Why the tag gates the spawn (enforced subagent spawning).** An inline task inherits the parent session's model and cannot be re-routed — routing only has teeth if every tagged task actually spawns. Spawning carries fixed briefing overhead, which is why the rule keys on the *tag* (a deliberate plan-time signal the work is worth routing) rather than "spawn everything": the cheapest untagged glue work stays inline. A full parent-as-orchestrator model (spawn everything, parent never implements) is a deferred follow-up, to be justified by M24 outcome-log evidence — not implemented here.
 
 ## Execution Summary
 

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

@@ -122,6 +122,8 @@ 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.**
+
 Read `.forge/context.md`. **Needs Resolution** unchecked → warn: *"{N} unresolved discrepancies."* Quick proceeds; Standard/Full blocked at planning.
 
 ### 1.1a Live-Worktree Ownership Gate (enforced)
@@ -150,7 +152,10 @@ The gate (below) and this finalize path are mutually exclusive on `current.statu
 
 Present the four resolutions and wait for an explicit choice:
 
-1. **Enter the worktree** *(recommended)* — print the exact command (`cd {worktree_path}` then `/forge`); re-running there anchors to this milestone and writes land in the owner. This session does nothing further to the milestone.
+1. **Enter the worktree** *(recommended)* — relocate this session into the worktree **in place** (the operator no longer has to `cd` + re-run). This is the canonical **Native Worktree Entry** contract, reused verbatim at the `chief-of-staff` resume and `orchestrating` hand-back touch points:
+   - **If the `EnterWorktree` tool is available**, call `EnterWorktree({path: {worktree_path}})` — always `{path}` into the recorded `lifecycle.worktree_path`, never `{name}` (Forge owns worktree creation; `{name}` would spawn a new one on the wrong branch convention). Then log one line — `Relocated into worktree {worktree_path} ({branch})` — **independent of any confirmation prompt**, so the cwd move is always visible in the transcript. Continue routing to the requested skill from inside the worktree: writes now land in the owner, and the ownership gate is satisfied because this session **is** the owner.
+   - **If `EnterWorktree` is unavailable** (older Claude Code CLI, or a non-Claude-Code adapter), fall back to today's behavior: print the exact command (`cd {worktree_path}` then `/forge`); re-running there anchors to this milestone and writes land in the owner. This session does nothing further to the milestone.
+   - Exit is always `ExitWorktree({action: "keep"})` — Forge never lets the native tool **remove** a worktree; teardown stays option 3 / `git worktree remove`.
 2. **Sync, then continue in the worktree** — bring main's commits in (`git -C {worktree_path} rebase main`, or merge), then work from the worktree. Use when main has changes the worktree needs first.
 3. **Retire the worktree** — only if it is dead/superseded. Close the stream, `git worktree remove {worktree_path}`, and clear `lifecycle.worktree_*` on the milestone — which ends its ownership so main may write. **Confirm before removing; never auto-remove a worktree.**
 4. **Recorded override** — deliberately write from main anyway. Write `lifecycle.ownership_override: {at: {ISO}, from: main, reason: "{operator's reason}"}` into `milestone-{id}.yml`, echo it in the boot line, and carry it into the next `reviewing` report. This is the **only** way past the block and it is **never silent**. (An override is scoped to this milestone; clear it once the worktree is retired or synced.)
@@ -198,6 +203,15 @@ Downstream skills (researching, discussing, planning, executing, verifying, revi
 
 **Surface at 3+.** For each remaining group with 3+ files (declined groups already skipped), **load `desire-paths-review.md` in this skill dir and follow it** — it carries the concrete fix-suggestion map (per `type`), the Apply/decline mechanics (archive to `resolved/` on apply; write a `declined/` file on decline — no re-nag), and the upstream transport for `scope: framework` signals (portable block + optional `gh issue` against `forge.upstream_repo`). Groups under 3 (the common boot) → nothing to surface; skip the load. (Occurrence count is derived from file count — no counter to reset.)
 
+### 1.2a Prototype hygiene (parked-rot guard)
+
+The Prototyping tier writes an always-present state file (`.forge/prototypes/{slug}.md`), so a `parked` prototype can accumulate silently — the rot risk of a durable artifact. Cheap boot check, advisory, never blocks:
+
+- No `.forge/prototypes/` dir → skip (nothing to surface). This is the common boot.
+- Glob `.forge/prototypes/*.md` (NOT `archive/` — graduated/discarded are already terminal and archived). For each, read `status`.
+- Any `status: parked` with `parked` (or `created`) older than **30 days** → one line each: *"Prototype `{slug}` ({title}) parked {N}d — resume (`/forge prototype {slug}`), graduate, or discard? Parked mockups rot."* Surface only; the operator decides. `exploring` prototypes are live work in progress — do not nag them.
+- Nothing stale → silent.
+
 ### 1.3 Interface Check
 
 Check `interface` in `project.yml`:
@@ -220,6 +234,7 @@ Before tier detection, check if user request matches stream or lifecycle pattern
 - "resume milestone {id}" / "undefer {id}" / "reactivate milestone {id}" → **Resume**
 - "delete milestone {id}" / "archive milestone {id}" / "remove milestone {id}" → **Delete** (see below)
 - "deferred" / "show deferred" / "deferred items" / "what's deferred" / "deferred work" → **Show Deferred**
+- "prototype {slug}" / "resume prototype {slug}" / "mockup {slug}" / "show prototypes" / "list prototypes" → **Prototype Ops**
 
 No match → fall through to Step 2B (tier detection).
 
@@ -244,6 +259,12 @@ Examples:
 1. Invoke `Skill(deferred)` directly.
 2. Do not enter tier detection. Do not prompt for milestone. The deferred skill is read-only and self-contained.
 
+### Prototype Ops
+
+Prototypes are the disposable in-app mockup tier (`.forge/prototypes/{slug}.md`; see `Skill(prototyping)`).
+- **"prototype {slug}" / "resume prototype {slug}" / "mockup {slug}"** → invoke `Skill(prototyping)` with the slug. It reads the existing state file and continues the iteration loop (or starts a new prototype if the slug is unknown). Do not enter tier detection.
+- **"show prototypes" / "list prototypes"** → read-only: glob `.forge/prototypes/*.md`, list each `{slug} — {title} — {status}` (skip `.forge/prototypes/archive/`). No state writes, no tier detection.
+
 ### Defer Operation
 
 1. Validate: milestone in `index.yml`, status not `deferred`
@@ -299,6 +320,12 @@ No `project.yml` → `Skill(initializing)`. Brownfield/greenfield, absorption, s
 
 ## Step 2B: Detect Tier
 
+### Prototyping
+ANY: "mock up"/"mockup"/"sketch"/"prototype"/"draw up"/"iterate on the UI"/"explore how X could look"/"design iteration", **disposable** in-app visual exploration behind an alpha/feature flag, no requirements locked yet
+→ `prototyping`
+
+Distinguishing signal: the deliverable is *a thing to look at and react to*, not shippable code. If the operator wants to **see how something might look before deciding to build it**, it's Prototyping — even if it touches many files. Real UI work with known requirements is Standard + `designing` (which gates on quality/verification); Prototyping deliberately skips that gate. When genuinely ambiguous, ask: *"Is this a throwaway mockup to react to, or the real build?"*
+
 ### Quick
 ANY: single file, typo/formatting, config/env, dep bump, <50 lines, "quick"/"small"/"minor"
 → `quick-tasking`
@@ -380,6 +407,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 | testing | sonnet | Code gen (author) + audit judgment (analyst) — matches executing/reviewing. M9: author-mode refuses e2e without `e2e:true` + `validated:true`. |
 | deferred | haiku | Read + format only |
 | chief-of-staff | sonnet | Cross-stream coordination and conflict judgment |
+| prototyping | sonnet | UI code gen for disposable mockups |
 
 | `current.status` | Route To |
 |-------------------|----------|
@@ -396,6 +424,7 @@ Where `{source}` = `skills.{name}` | `models.default` | `parent session`. Suppre
 | `quick-tasking` | `Skill(quick-tasking)` |
 | (keyword: `deferred` / "show deferred") | `Skill(deferred)` — read-only aggregator |
 | (keyword: `show streams` / `start stream` / `merge safe` / `Chief of Staff`) | `Skill(chief-of-staff)` — project stream coordination |
+| (keyword: `prototype {slug}` / `mock up` / `sketch` — disposable UI exploration) | `Skill(prototyping)` — no verify/review gate |
 
 ### Status Advancement Check
 
@@ -454,9 +483,10 @@ After clear, skills load from disk via "Read Context"/"Pre-Execution Checklist".
 ## State Transitions
 
 ```
-Standard:  not_started → [init?] → researching → discussing → planning → executing → verifying → reviewing → complete
-Full:      not_started → [init?] → researching → discussing → architecting → planning → executing → verifying → reviewing → complete
-Advisory:  [init?] → discussing → [tier gate] → planning → executing → verifying → reviewing → complete
+Standard:    not_started → [init?] → researching → discussing → planning → executing → verifying → reviewing → complete
+Full:        not_started → [init?] → researching → discussing → architecting → planning → executing → verifying → reviewing → complete
+Advisory:    [init?] → discussing → [tier gate] → planning → executing → verifying → reviewing → complete
+Prototyping: [flag] → iterate ⟲ (render → react → adjust) → resolve: graduate→milestone | park | discard    (no verify/review gate)
 
 Branches (any tier, on-demand): debugging (stuck) · designing (UI) · securing (auth/data/API) · testing (e2e/integration/flake)
 Phase boundaries: `[clear]` recommended between phases to reset context.

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

@@ -193,6 +193,8 @@ Plan naming reflects the slice: `plan-01-user-signs-up.md`, not `plan-01-models.
 2. Frontmatter: phase, plan#, wave, deps, `slice_exception:` (optional, see Core Principle), `integration_checkpoint:` (optional, see below)
 3. must_haves:
    - **Truths:** User-observable outcomes (3-7). MUST be phrased as something the user can see, click, or receive -- not "model X exists" or "table Y created".
+     - Each truth SHOULD carry a `check:` command authored NOW, goal-backward, before any code exists -- a check written before the code cannot be retro-fitted to what got built (semantics in `.forge/templates/plan.md`).
+     - A truth that cannot be a command (visual, real-device, external service) carries a `manual:` route instead (human gate / M9 e2e) -- never a fake check.
    - **Artifacts:** Must exist, substantive not stubs. Slice plans typically span 2-4 layers (e.g., component + handler + repo).
    - **Key Links:** Connections between artifacts -- these prove the slice is wired, not stubbed.
 4. XML tasks (2-3/plan, 15-60 min):
@@ -207,6 +209,18 @@ Plan naming reflects the slice: `plan-01-user-signs-up.md`, not `plan-01-models.
 </task>
 ```
 
+#### Complexity + Task Type Assignment (cost-aware routing, M24)
+
+At the same goal-backward moment `check:` commands are authored — plan time, before any code exists — assign each task an **optional** `complexity` (`trivial`|`standard`|`complex`) and `task_type` (`code-feature`|`code-fix`|`docs`|`research`|`config`|`test`). Executing resolves these into the spawn model via `models.by_complexity` (FORGE.md → Model Routing); an unmarked task falls back to skill-level routing (FR-131) — zero behavior change if you skip it.
+
+Light heuristic, do not over-prescribe:
+- **complexity** — config/doc/mechanical single-file edit -> `trivial`; ordinary feature/fix -> `standard`; new cross-layer behavior, tricky logic, or high blast radius -> `complex`.
+- **task_type** — pick the dominant kind of work the task does.
+
+Both fields are **advisory, not a gate**: a genuinely ambiguous task MAY be left unmarked rather than guessed. Do not add a Step 8 lint dimension for this — unlike `check:` truths, routing hints are optional annotations, not verification obligations.
+
+**Consulting the promotion ladder (advisory).** While assigning, the planner MAY run `.claude/hooks/forge-model-outcome.sh recommend` and fold any `proven`-bucket line into the assignment as advisory input — e.g. "ladder: haiku proven on docs → a docs task here is a safe `trivial`". This is advisory only: planning NEVER blocks on it, and on the common early case (`recommend` reports insufficient data) assignment proceeds normally on the heuristic above. Do not turn this into a required lookup step.
+
 #### Overlay / Popover must_haves (when a plan adds a floating surface)
 
 When a plan introduces an **overlay, popover, sheet, anchored panel, or any floating surface** (especially one anchored to a moving element like a canvas block), specifying its *content* (rows, keys, payload) is **not enough** — the *behavior* questions below only surface when a human touches the running UI, each costing a full build → deploy → UAT round. Add a `must_haves.truths` entry for every item that applies, phrased as a user-observable behavior:
@@ -384,7 +398,7 @@ Decision captured once, pre-code. Does not block planning.
 
 ## Step 8: Verify Plans
 
-9 dimensions:
+10 dimensions:
 1. **Requirement Coverage** -- every req has task(s)
 2. **Task Completeness** -- files + action + verify + done
 3. **Deps** -- valid DAG, no cycles
@@ -394,6 +408,7 @@ Decision captured once, pre-code. Does not block planning.
 7. **Context** -- honors locked, excludes deferred
 8. **Spec Validity** -- valid syntax, correct paths
 9. **Slice Integrity (HARD GATE)** -- every plan delivers a vertical slice OR declares `slice_exception:`
+10. **Check Quality** -- truth checks are real, diagnostic, and routed
 
 ### Slice Integrity Check
 
@@ -408,6 +423,17 @@ Roadmap-level check: FAIL if phase 1 has no user-observable goal.
 
 On fail: restructure plan(s) into slices, or declare `slice_exception:` with one of `infra_bootstrap | shared_library | data_migration` and a one-line rationale. Re-verify.
 
+### Check Quality Check
+
+A check that cannot fail manufactures fake evidence -- worse than no check, because verifying will execute it and record a hollow PASS. Lint every truth `check:` before handoff (heuristics ported from Ringer's manifest lint, applied as prose -- no script):
+
+- **(a) Cannot-fail check** -- `true`, `:`, `exit 0`, or an echo-only pipeline → **always a failure, no justify path.** Rewrite it so it can catch the truth being false.
+- **(b) Silent-fail check** -- every conjunct is an existence test / `grep -q` / `diff -q` and no `||` branch prints diagnostics → fix or justify in one line. The failure output is what feeds executing's auto-fix loop and the verification report; a silent exit 1 starves both.
+- **(c) Existence-only check on a behavioral truth** -- `test -f` (or equivalent) where the truth claims behavior → fix (run/validate the content) or justify.
+- **(d) Unrouted truth** -- a truth with neither a `check:` nor a named manual route (human gate / M9 e2e) → flag; assign a route. Checks stay optional per truth -- the route does not.
+
+On fail: same mechanics as the other dimensions -- fix, re-verify, max 3 cycles. Rule (a) findings must be fixed, never justified.
+
 Issues -> fix, re-verify. Max 3 cycles.
 
 ## Step 9: Present

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

@@ -0,0 +1,88 @@
+---
+name: prototyping
+description: "Rapid, disposable, in-app design mockups. Iterate UI behind an alpha/feature flag to conceptualize how something might look BEFORE committing to a real build. Trigger: 'mock up', 'sketch a UI', 'quick design iteration', 'prototype this screen', 'explore how X could look', 'draw up options'. Prototyping tier — no verify/review gate."
+model: sonnet
+---
+
+# Prototyping
+
+Fast visual exploration inside the real app. You are drawing iterations of how something *might* look, gated behind an alpha/feature flag, so the operator can react to a concrete rendering before any real build is scoped. This is **not** production work.
+
+**What makes this its own tier.** Standard/Full ceremony (research → discuss → plan → verify → review, goal-backward verification, a milestone cursor) is the wrong shape — a mockup has no requirements yet (discovering them is the *point*) and no observable truth to verify beyond "does it look like something worth discussing?". Quick tier's <50-line / 1-2-file caps and its commit-and-done finish don't fit a multi-file, multi-iteration loop whose output is deliberately disposable. Prototyping fills that gap.
+
+**Three rules that define the tier:**
+1. **Disposable by default.** Everything you write lives behind a flag and is expected to be thrown away. Do not refactor for production, do not add tests, do not handle every edge case. Make it *look* right, fast.
+2. **No verify/review gate.** There is no `verifying`, no `reviewing`, no health gate. The gate is the operator's eyes.
+3. **Iterate, don't finish.** The loop is: render → operator reacts → adjust → render. It ends when the operator graduates, parks, or discards — never at "100% of tasks done".
+
+## Step 1: Establish the prototype
+
+Give the exploration a short kebab `{slug}` (e.g. `dashboard-redesign`, `onboarding-v2`).
+
+**Check for an existing session.** Glob `.forge/prototypes/{slug}.md`. Exists → this is a **resume**: read it, summarize the iterations so far and the current open question, and continue the loop at Step 4. Absent → new prototype, continue.
+
+**Load the design system loosely.** Read `.forge/project.yml → design_system` and `.forge/design-system.md` if present — use real components and tokens so the mockup reads as native to the app. But this is exploration: **it is fine to hand-roll a component the design system doesn't have yet** (that gap may be the very thing you're exploring). The `designing` skill's *strict* "never build custom for what the system provides" rule is relaxed here — prefer the system, don't be blocked by it.
+
+## Step 2: Establish the visibility flag (alpha-toggle pattern)
+
+**A prototype must never be reachable in production.** The default mechanism is to render it behind an alpha/feature flag in the real app, so it is visible in-context to whoever is exploring but off for everyone else.
+
+Resolve the flag in this order:
+1. `.forge/project.yml → prototype_flag` — a project convention naming how alpha features gate (e.g. `alpha`, a feature-flag key, an env check, a `?alpha=1` query param, a settings toggle). Use it.
+2. No convention recorded → **look** at how the codebase already gates alpha/experimental UI (grep for existing flags, `alpha`, `feature`, `experimental`, env-gated routes). Found a pattern → follow it and offer to record it: *"Gate this behind `{pattern}`? I'll note `prototype_flag: {pattern}` in project.yml so future prototypes reuse it."*
+3. No pattern anywhere → **ask once**: *"How should alpha/mockup UI be gated so it's visible to us but never in prod? (feature flag / env check / query param / settings toggle)"* — then record the answer as `prototype_flag`.
+
+Never ship prototype code on an always-on path. If you can't find or agree a gate, STOP and ask — do not guess.
+
+## Step 3: Write the state file
+
+Copy `.forge/templates/prototypes/prototype.md` → `.forge/prototypes/{slug}.md` and populate the frontmatter (`slug`, `title`, `created`, `status: exploring`, `flag`, `goal`). This is a **lightweight, resumable** record — the loop's memory across `/clear`, not a plan. Keep it under the 8 KB size gate; it holds the current question and a terse iteration log, not a design doc.
+
+## Step 4: Iterate (the loop)
+
+This is where the time goes. Each pass:
+
+1. **Render an iteration.** Build the mockup UI behind the flag, using the design system where it fits. Aim for *fast and legible*, not complete or robust. Static/stub data is fine and expected.
+2. **Make it visible.** Confirm it renders behind the flag and tell the operator exactly how to see it (route, toggle, `?alpha=1`, whichever the flag is).
+3. **Log the iteration.** Append one terse line to the state file's `## Iterations` (date, what this pass tried, what to react to). This is what makes a resume cheap.
+4. **Operator reacts.** They eyeball it and say what to change, what to try instead, or what they've decided. Adjust and loop.
+
+**Deviation posture (looser than executing).** Auto-fix anything blocking the render (Rules 1-3) without ceremony — the point is speed. But a **Rule 4 stop still holds**: a new DB table, a real service layer, a schema migration, a dependency install, or anything that outlives the flag is no longer a mockup — STOP and tell the operator this has outgrown prototyping (likely a graduate). Mockups fake their data; they don't build backends.
+
+**Commits are optional and disposable.** Commit iterations only if the operator wants checkpoints to compare or revert. Use `chore(proto): {slug} — {iteration note}`. Never present prototype commits as durable work; they ride the flag and leave with it.
+
+## Step 5: Resolve (one of three terminal outcomes)
+
+The loop ends when the operator picks an outcome. Each has a clean terminal path so prototypes never rot.
+
+### Graduate → promote to a real milestone
+The mockup proved the idea; now build it for real. This mirrors the refactor-backlog promotion procedure.
+
+1. Synthesize milestone id `m-proto-{slug}` (or a numeric id — scan `.forge/state/milestone-*.yml` for max + 1).
+2. Copy `.forge/templates/state/milestone.yml` → `.forge/state/milestone-{id}.yml`. Populate: `milestone.id`, `milestone.name: "Graduated from prototype: {title}"`, `milestone.origin: prototype/{slug}`, `current.tier: standard` (or `full` if the operator says so), `current.status: researching`, `current.last_updated: {ISO}`.
+3. Append to `.forge/roadmap.yml`: one milestone entry + a first phase (`dependencies: []`). Note the prototype as the design reference so `researching`/`designing` can look at the alpha code.
+4. Run the **State Rollup (forge 1.0)** so `index.yml` picks up the new milestone (do **not** hand-edit `index.yml`).
+5. In the state file: set `status: graduated`, add `graduated_to: m-{id}`, `resolved: {ISO}`. **Archive** it: move `.forge/prototypes/{slug}.md` → `.forge/prototypes/archive/{slug}.md`.
+6. **Leave the alpha flag in place** — the graduated milestone builds the real thing and removes/keeps the flag as its own work decides. Say so.
+7. Confirm: *"Graduated prototype {slug} → milestone m-{id}. State + roadmap created, prototype archived. The alpha mockup stays as the design reference. Routing to researching."* Then fall through to normal Standard/Full routing via `forge`.
+
+### Discard → the idea's out, clean up
+1. **Remove the alpha-flagged code** you added for this prototype (the render, the flag branch if nothing else uses it, stub data). Grep first; only remove what this prototype introduced — never touch code the flag gated before you arrived.
+2. Commit the removal: `chore(proto): discard {slug} mockup`.
+3. In the state file: set `status: discarded`, add `resolved: {ISO}`, a one-line `discard_reason`. **Archive** it: move → `.forge/prototypes/archive/{slug}.md` (keeps the audit trail — what we tried and why we dropped it).
+4. Confirm what was removed and that the file is archived.
+
+### Park → sit on it for later
+Keep the mockup live behind the flag; you're not ready to decide.
+1. In the state file: set `status: parked`, add `parked: {ISO}` and a one-line note on *what would unpark it* (a decision, a dependency, a conversation).
+2. Leave the file in `.forge/prototypes/` (not archived — it's still live). Leave the alpha code in place behind the flag.
+3. Confirm: *"Parked prototype {slug} behind `{flag}`. Resume anytime with `/forge prototype {slug}`."*
+
+**Parked prototypes are the rot risk your always-a-state-file choice creates.** `forge` boot surfaces parked prototypes older than a threshold so they don't accumulate silently (see forge Step 1.5 → Prototype hygiene). A park is a deferral, not a hiding place.
+
+## What this skill does NOT do
+
+- **No goal-backward verification.** There's nothing to prove works. If you find yourself wanting `verifying`, the work has graduated — promote it.
+- **No production quality bar.** No test coverage, no a11y gate, no security/architecture review. (Basic keyboard/focus sanity is fine if cheap, but it is not gated.)
+- **No unit tests, no real data layer, no migrations.** Mockups stub their data. Any of these = a Rule 4 stop → graduate.
+- **No `git add .`** — stage individually, as everywhere in Forge.

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

@@ -126,17 +126,22 @@ Milestones with zero `e2e:true` stories never see this gate. Verifying logs noth
 
 ### Level 1: Observable Truths
 
-Read the plan's `must_haves.truths`. For each truth:
+Read the plan's `must_haves.truths`. Truths may be legacy bare strings or `{truth, check}` / `{truth, manual}` objects (see `.forge/templates/plan.md`). For each truth, one of three branches — **this is the canonical statement of the executed-evidence rule** (verifier.md and FORGE.md cite it):
 
-1. Design a test that proves/disproves it
-2. Run the test
-3. Record: **VERIFIED** | **FAILED** | **UNCERTAIN**
+1. **Declared `check:`** (and no `manual:` route) → EXECUTE it. Exit 0 → **VERIFIED**; non-zero → **FAILED**. Record the command, exit code, and an output excerpt either way.
+2. **No declared check** (legacy plan, or a truth planning left judgment-shaped) → run your OWN command that proves/disproves it and record the same evidence triple — executed evidence qualifies regardless of schema vintage.
+3. **No executed evidence** → the verdict is **UNCERTAIN** or **HUMAN VERIFICATION NEEDED**. **Never VERIFIED.**
+
+WHY the hard line: a verdict without executed evidence is the hallucination surface this rule closes — an agent designing and grading its own test can report VERIFIED without running anything. The exit code, not judgment, is the verdict.
+
+Manual-route truths (`manual:` field, or inherently uncommandable — visual, real-device, external service) are branch 3 by design: never execute their route text as shell, never invent a proxy command — list them under HUMAN VERIFICATION NEEDED; they flow to the existing Human Verification Gate / M9 e2e gate unchanged.
 
 ```markdown
-| Truth | Test | Result |
-|-------|------|--------|
-| User can edit their bio | Click edit, type, save, check persistence | VERIFIED |
-| Profile photo uploads correctly | Upload image, check display | FAILED — 413 on large files |
+| Truth | Evidence (command → exit) | Result |
+|-------|---------------------------|--------|
+| User can edit their bio | `npx playwright test bio-edit.spec` → 0 | VERIFIED |
+| Profile photo uploads correctly | `npm test -- upload.spec` → 1; "413 Payload Too Large at 6MB" | FAILED — 413 on large files |
+| Layout matches design on mobile | (manual: human gate — not executed) | HUMAN VERIFICATION NEEDED |
 ```
 
 ### Level 2: Artifacts (Exists → Substantive → Wired)

package/template/.forge/FORGE.md

@@ -69,6 +69,11 @@ Worktrees are a **base concern** — Chief/Streams creates and references them w
 
 Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 
+### Prototyping (minutes–hours, disposable)
+**Triggers:** "mock up"/"sketch"/"prototype"/"draw up"/"iterate on the UI"/"explore how X could look" — disposable in-app visual exploration behind an alpha/feature flag, no requirements locked yet
+**Flow:** `prototyping` — establish flag → iterate ⟲ (render → react → adjust) → resolve (graduate→milestone | park | discard)
+**No verify/review gate by design.** The deliverable is a thing to look at and react to, not shippable code. Fills the gap where Standard/Full ceremony (goal-backward verification, a milestone cursor) is the wrong shape and Quick's <50-line/1-2-file caps + commit-and-done don't fit an iteration loop. Real UI work with known requirements is Standard + `designing` (which *does* gate on quality). See [ADR-022](../docs/decisions/ADR-022-prototyping-tier.md).
+
 ### Quick (minutes)
 **Triggers:** bug fix, typo, config, dep bump, <50 lines
 **Flow:** `quick-tasking` → commit → done
@@ -100,6 +105,7 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | Prove work delivers on goals (+ M9 e2e validation gate when `e2e:true` stories present; captures the Human Verification Gate sign-off) | `verifying` | Standard, Full |
 | Audit health + catalog refactoring (+ M9 e2e soft-cap, orphan-test, flake-rate audits; hard-blocks completion on the Human Verification Gate) | `reviewing` | Standard, Full |
 | Small scoped fix | `quick-tasking` | Quick |
+| Rapid disposable UI mockup behind an alpha flag (no verify/review gate) | `prototyping` | Prototyping |
 | UI with design system | `designing` | When UI |
 | Security review | `securing` | When auth/data/API |
 | E2E/integration tests + suite audit (+ M9 author-mode gate refuses e2e without `e2e:true` + `validated:true`) | `testing` | When UI/flows or flaky suite |
@@ -127,6 +133,7 @@ Auto-detects complexity. Override: "Use Quick/Standard/Full tier."
 | `streams/{stream}/brief.md` | 8 KB | Stream context packet must fit into active session context |
 | `streams/{stream}/packages/{id}.yml` | 10 KB | Delegated work contract stays bounded |
 | `reservations.yml` | 50 KB | Append-only ID-reservation registry; one short line per ADR/DEF/FR/NFR reserved |
+| `prototypes/{slug}.md` | 8 KB | Disposable-mockup state — current question + terse iteration log, not a design doc; terminal items archive to `prototypes/archive/` |
 
 ### Accumulating Artifacts
 
@@ -137,6 +144,10 @@ Every new accumulating artifact needs: owner, size gate, archive/compaction rule
   source-of-truth; load scoped slices, not whole history.
 - `phases/`, `audits/`, `research/`, `archive/`, and `context-archive.md` are
   historical; load only by milestone/stream/package/version.
+- `prototypes/{slug}.md` is single-owner mutable while `status: exploring | parked`
+  (the driving session writes it); terminal statuses (`graduated`, `discarded`)
+  archive to `prototypes/archive/`. `forge` boot surfaces stale `parked` prototypes
+  (>30d). Not derived, not shared — a prototype has exactly one driver.
 - 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.
@@ -169,6 +180,10 @@ Configure in `project.yml`:
 models:
   default: sonnet          # fallback
   parent_session: sonnet   # advisory — warns on mismatch
+  by_complexity:           # per-task complexity → model (M24). Overrides skills — see Precedence.
+    trivial: haiku
+    standard: sonnet
+    complex: opus
   skills:                  # per-skill overrides
     architecting: opus
     planning: opus
@@ -176,10 +191,11 @@ models:
     quick-tasking: haiku
 ```
 
-**Precedence:** `skills.X` → `default` → parent model.
+**Precedence:** `by_complexity.{task.complexity}` → `skills.X` → `default` → parent model.
+**Complexity overrides skill** (LOCKED, context.md § M24): when a task declares a `<complexity>`, its `by_complexity` resolution wins over `models.skills.{skill}`. WHY — the per-task signal is the granular one and the whole point of M24; letting the coarser skill-level setting win would make per-task routing inert on any project that already sets `models.skills.executing`. A task with **no** complexity resolves via the unchanged `skills → default → parent` chain — zero behavior change for untagged tasks.
 **All advisory** — forge displays expected model at each transition, suggests `/model` on mismatch. Review gate logs model used. Cannot auto-switch.
 
-**Subagent inheritance.** When a skill spawns subagents via the Agent tool (parallel research, fresh-context reviewers, executor fan-out, tester author/analyst, etc.), the skill MUST pass the resolved `model` param explicitly. Subagents do NOT inherit skill-level routing automatically — without the param they run on the parent session's model, defeating the routing intent. Resolve using the same precedence chain (`models.skills.{skill}` → `models.default` → parent) and surface it: *"Spawning {role} with model: {model} (from {source})"*.
+**Subagent inheritance.** When a skill spawns subagents via the Agent tool (parallel research, fresh-context reviewers, executor fan-out, tester author/analyst, etc.), the skill MUST pass the resolved `model` param explicitly. Subagents do NOT inherit skill-level routing automatically — without the param they run on the parent session's model, defeating the routing intent. Resolution is **per-task** where the task being spawned declares a `complexity` (`by_complexity` wins per the Precedence above), falling back to the skill-level chain (`models.skills.{skill}` → `models.default` → parent) otherwise — surface it: *"Spawning {role} with model: {model} (from {source})"*. **Inline-task limitation:** a task that runs inline (no spawn) inherits the parent session's model and cannot be re-routed — per-task routing is inherently a subagent-spawn feature, not something that reaches into an already-running skill session.
 
 ## Agents
 
@@ -231,6 +247,7 @@ State lives in `.forge/`:
 - `releases.yml` — Append-only version-reservation registry (cross-session coordination point; see Version Reservation Protocol)
 - `reservations.yml` — Append-only ID-reservation audit trail + cross-machine floor for ADR/DEF/FR/NFR numbers, written by `forge-reserve` (ADR-021). The same-machine cross-worktree coordination point is the machine-local ledger `.git/forge/id-reservations`; see ID Reservation Protocol.
 - `archive/milestone-{id}/` — Archived milestone artifacts (archive-delete)
+- `prototypes/{slug}.md` — Lightweight resumable state for a disposable in-app design mockup (Prototyping tier). Status vocab: `exploring | parked | graduated | discarded`. Terminal (`graduated`/`discarded`) → archive to `prototypes/archive/{slug}.md`. Single-owner mutable; not derived, not shared. See `Skill(prototyping)`.
 
 **Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions. Can be deferred (frozen in place) or archive-deleted.
 `index.yml status` gates routing: `not_started | active | deferred | complete`.
@@ -349,6 +366,10 @@ verification:
 - Empty commands = no gate (opt-out)
 - `verification.e2e_soft_cap` (default 10) — advisory cap on `e2e:true` stories per milestone surfaced by the `reviewing` skill. Soft — never blocks.
 
+### Truth checks (executable must_haves)
+
+Plans MAY declare a per-truth `check:` shell command in `must_haves.truths` (exit 0 = pass; authored goal-backward at planning, before code exists; linted by planning Step 8 dimension 10). `executing` runs declared checks once at plan completion (early fix-loop signal, never a verdict); `verifying` re-executes them and applies the **executed-evidence rule**: VERIFIED only with a recorded command + exit code + output excerpt — no executed evidence → UNCERTAIN or human-route, never VERIFIED. Legacy bare-string truths stay valid; details live in the planning/executing/verifying skills + plan template.
+
 ### Human Verification Gate (close precondition)
 
 **No milestone reaches `complete` and no orchestration worktree is torn down until a human has explicitly signed off** — recorded as `current.human_verified` in `milestone-{id}.yml`. Code-level verification (tests, lint, type-check, the 3-level goal-backward pass) is necessary but **never sufficient** to close a milestone. A human must confirm the work in whatever form fits the milestone — device session, visual check, e2e walk, smoke test ("of some sorts").

package/template/.forge/migrations/0.50.1-template-releases-scrub.md

@@ -0,0 +1,91 @@
+# Migration Guide: Template-Seeded Release Registry Scrub (Forge 0.50.1)
+
+Applies to projects whose fresh install ran with forge-orkes 0.32.0–0.50.0. Those
+package versions shipped `template/.forge/releases.yml` containing the forge dev
+repo's own release history (13–19 entries, versions 0.20.0–0.37.0) instead of an
+empty scaffold, so `npx forge-orkes` seeded every new project's Version
+Reservation Registry with foreign entries. The registry's `max()` rule then
+resolves against forge's history — a fresh 0.1.0 project reserving its first
+version gets 0.38.0. From 0.50.1 the template ships an empty scaffold
+(`releases: []`) and the release script refuses to ship a template with live
+registry entries; this guide cleans installs that were already seeded.
+
+`reservations.yml` (the ID-reservation sibling) was audited for the same
+pattern: its template copy has been an empty scaffold since it was introduced —
+no migration needed there.
+
+## Prerequisites
+
+1. On the new version's framework files (run `npx forge-orkes upgrade` first).
+2. Working tree clean or changes committed — the migration rewrites
+   `.forge/releases.yml`.
+
+## Detection
+
+Prints `MIGRATE` when `.forge/releases.yml` carries the template-seeded foreign
+entries; silent + exit 0 otherwise.
+
+```bash
+# Fingerprint two forge-dev entries every seeded variant (0.32.0–0.50.0)
+# contains; either match → the registry was template-seeded at install.
+# The forge dev repo itself legitimately holds these entries — skip it.
+F=.forge/releases.yml
+[ -f "$F" ] || exit 0
+[ -d packages/create-forge/template ] && exit 0
+if grep -qF 'CLAUDE.md @import extraction (framework prose' "$F" \
+   || grep -qF 'Nested phase layout (phases/milestone-{id}/{phase}-{name}/)' "$F"; then
+  echo "MIGRATE — .forge/releases.yml was seeded with the forge dev repo's release history at install; scrub the foreign entries"
+fi
+```
+
+## Migration steps
+
+The migration is NEVER auto-applied. In Claude Code it runs via the
+`quick-tasking` skill, which the `upgrading` Step-7 prompt hands this guide to
+on "yes". Step 3 is potentially lossy — confirm with the user before renumbering
+anything.
+
+### 1. Separate foreign entries from the project's own
+
+An entry belongs to THIS project iff its `milestone:` matches a milestone that
+exists here — in `.forge/state/milestone-*.yml`, `.forge/roadmap.yml`, or
+`.forge/archive/milestone-*/`. Everything else is foreign: the seeded block is
+contiguous, sits at the top of the `releases:` list, spans versions
+0.20.0–0.37.0, and its summaries describe forge framework features (streams,
+worktree gates, CLAUDE.md @import extraction, …) rather than anything this
+project built. Entries the project itself appended (if any) follow the seeded
+block.
+
+### 2. Rebuild the registry
+
+Keep the header comment block. Delete the foreign entries. Keep the project's
+own entries in their original order. If no own entries remain, end the file
+with `releases: []`.
+
+### 3. Check the project's own entries for version skew (confirm with user)
+
+Any entry the project reserved while the foreign block was present took
+`max()` off forge's history — e.g. a project actually at 0.3.0 reserving
+"0.38.0". For each such entry, ask the operator:
+
+- **Not yet published or tagged anywhere** → renumber the entry (and the
+  project's `package.json` or equivalent version file) to continue the
+  project's true version line.
+- **Already published/tagged** → keep the inflated number for continuity and
+  note the skew in a comment beside the entry.
+
+Never renumber without explicit confirmation.
+
+### 4. Commit
+
+One scoped commit, e.g.
+`fix(forge): scrub template-seeded entries from releases.yml (0.50.1 migration)`.
+
+## Validation
+
+- `grep -F 'CLAUDE.md @import extraction' .forge/releases.yml` → no matches.
+- Every remaining `milestone:` in `.forge/releases.yml` names a milestone that
+  exists in this project's state, roadmap, or archive.
+- The highest `version:` left in the registry (if any) is consistent with the
+  project's actual version in `package.json` (or equivalent).
+- Re-running the Detection block prints nothing and exits 0.

package/template/.forge/releases.yml

@@ -20,110 +20,17 @@
 # editing package.json. If two sessions reserve near-simultaneously, the second
 # push rebases onto the first (append-only → no conflict) and must re-read max()
 # and take the next number.
+#
+# LAZY MIGRATION: this file starts empty. The first milestone that bumps this
+# project's version appends the first entry; while empty, max() falls back to
+# the version already recorded in the project itself (package.json or
+# equivalent). Entries belong to THIS project's milestones only.
+#
+#   releases:
+#     - milestone: 3
+#       version: "0.4.0"
+#       bump: minor
+#       reserved_at: "2026-07-01"
+#       summary: "User-facing summary of what this release ships"
 
-releases:
-  - milestone: 12
-    version: "0.21.0"
-    bump: minor
-    reserved_at: "2026-06-12"
-    summary: "CLAUDE.md @import extraction (framework prose → .forge/FORGE.md)"
-  - milestone: 13
-    version: "0.20.0"
-    bump: minor
-    reserved_at: "2026-06-12"
-    summary: "Nested phase layout (phases/milestone-{id}/{phase}-{name}/)"
-  - milestone: 14
-    version: "0.22.0"
-    bump: minor
-    reserved_at: "2026-06-13"
-    summary: "Refactor-backlog compaction migration + lifecycle (archive terminal items, size gate, status-vocab enforcement)"
-  - milestone: 10
-    version: "0.23.0"
-    bump: minor
-    reserved_at: "2026-06-14"
-    summary: "M10 auto-routing — forge routes Standard/Full through orchestrating when installed (install = consent); orchestration.auto opt-out"
-  - milestone: 15
-    version: "0.24.0"
-    bump: minor
-    reserved_at: "2026-06-14"
-    summary: "Disconfirm-before-commit rigor: debugging Confirmation Gate (blind-spot check), architecting Platform & Goal Validation + option-space framing, discussing widen-before-narrowing, CLAUDE.md principle 8"
-  - milestone: 16
-    version: "0.25.0"
-    bump: minor
-    reserved_at: "2026-06-14"
-    summary: "Worktree branch anchor in forge milestone selection — git branch deterministically selects the milestone (exact lifecycle.worktree_branch match, or milestone-id token in branch name) before the timestamp default; deferred/complete matches surface instead of auto-resuming"
-  - milestone: 16
-    version: "0.26.0"
-    bump: minor
-    reserved_at: "2026-06-14"
-    summary: "Milestone-anchored worktree naming in orchestrating — worktree dir + branch become forge/m-{id}-{session_id} (was forge/{uuid}), adds lifecycle.worktree_anchor. Makes the 0.25.0 branch-anchor id-token fallback work for orch worktrees so a moved/stale-state worktree still resolves to its milestone off the branch name alone; uuid suffix keeps collision-resistance, forge/ prefix keeps GC sweep"
-  - milestone: 17
-    version: "0.27.0"
-    bump: minor
-    reserved_at: "2026-06-15"
-    summary: "Human Verification Gate — hard block on milestone close + orchestration teardown until an explicit human sign-off is recorded as current.human_verified in milestone state. Code-level PASS is necessary but never sufficient to close. Captured by verifying (post-verdict prompt), enforced at reviewing-complete + orchestrating Step 5.0; recorded-override (method: override) is the only bypass and is surfaced. New current.human_verified state field — lazy migration: absent = prompt on next close, already-complete milestones never re-gated."
-  - milestone: 18
-    version: "0.28.0"
-    bump: minor
-    reserved_at: "2026-06-15"
-    summary: "Configurable repo-scoped worktree root — orchestration.worktree_root defaults to ../<repo-name>-worktrees/ (was shared ../forge-worktrees/). Fixes cross-repo worktree mixing when multiple repos share a parent dir, fixes cwd-sensitive resolution (relative roots now resolve against repo root, not shell cwd), and folds a gitignore-guard for repos with fully-ignored .claude/ trees (initializing writes correct carve-out for greenfield; upgrading detects + warns for brownfield)"
-  - milestone: 19
-    version: "0.29.0"
-    bump: minor
-    reserved_at: "2026-06-15"
-    summary: "Shared-state taxonomy for multi-worktree Forge — FORGE.md State Ownership expanded to enumerate all 5 file-sharing classes (single-owner mutable, derived, append-only shared, shared mutable, stable shared) with the rule each follows. Promotes 'do not touch another worktree's state files' to explicit rule. Adds structural rule for context.md + refactor-backlog.yml (write only to your milestone block, within-block append-only). New `forge` boot worktree-liveness view (lists live Forge worktrees + their owning milestones in main). Cross-tree write warnings in discussing (context.md) + reviewing (refactor-backlog.yml). Opt-in worktree-side rebase check at boot (gated by forge.worktree_rebase_check). Triggered by the canvaz 2026-06-15 case: main-session edits to m9's context block were invisible to the m9 worktree."
-  - milestone: 20
-    version: "0.30.0"
-    bump: minor
-    reserved_at: "2026-06-16"
-    summary: "Upstream desire-path feedback channel (ADR-012) — closes the capture→act loop in Principle 7. (1) Plan-anchor re-derivation guard already landed (commit 5ddf3a1): executing re-derives plan literals against HEAD before the first task; planning makes anchors drift-resistant. (2) `scope: project|framework` field added to the desire-path schema, set at capture by verifying/executing/planning (lazy migration: absent⇒project). (3) Single review owner = forge boot — retires verifying's duplicate 'Surface Recommendations', co-locates the type→evolution suggestion table, adds a decline-ledger (declined/) so declines stop re-nagging, adds a Quick-tier review trigger in quick-tasking. (4) Tiered upstream transport for scope:framework signals: always write a portable block to state/desire-paths/upstream/; offer `gh issue create` against forge.upstream_repo (default github.com/zayneupton/forge) when gh present; upgrading harvests upstream/ into {source}/docs/desire-paths-inbox/. Optional forge.upstream_repo added to project.yml. Triggered by the canvaz plan-anchor-drift signal that could only reach the framework via manual chat copy-paste."
-  - milestone: 15
-    version: "0.31.0"
-    bump: minor
-    reserved_at: "2026-06-17"
-    summary: "Data-driven migration detection — replaces hardcoded per-version detection blocks (SKILL Step 7 + bin detectLegacyLayouts) with a single loop over synced .forge/migrations/{v}-*.md guides, ranged (installed, source]. New uniform Detection-block contract: echo `MIGRATE` on stdout when the migration applies, silent/exit-0 for no-op. All 7 guides normalized to it (0.28.0 consolidated to one `## Detection`; 0.29.0 stays an explicit in-range no-op). Removes the staleness class entirely — a new guide is auto-covered the moment it ships in the template, zero per-version code, and the install-run blind spot is fixed (detection keys off freshly-synced guides + pre-bump installed version). Triggered by ptnrkit 0.19.2→0.30.0 upgrade where bin was 4 versions behind and 2 real on-disk migrations (0.20.0, 0.22.0) reported 'needs manual review: 0'."
-  - milestone: 16
-    version: "0.32.0"
-    bump: minor
-    reserved_at: "2026-06-18"
-    summary: "Project Chief / Streams orchestration — adds Project/Stream/Work Package runtime layers, Chief of Staff routing, stream/work-package templates, active context compaction, framework-wide size audit, and an idempotent migration guide. M10 is repositioned as an optional backend for worktree isolation, merge queue support, and experimental file claims."
-  - milestone: 16
-    version: "0.32.1"
-    bump: patch
-    reserved_at: "2026-06-20"
-    summary: "Chief front-door follow-up — detects projects that adopted worktree-backed streams but left legacy orchestration.auto enabled or unset, then prompts to set orchestration.auto: false so Chief/Streams is the default entry point while M10 remains explicit."
-  - milestone: 16
-    version: "0.33.0"
-    bump: minor
-    reserved_at: "2026-06-21"
-    summary: "Worktree convention promoted to base + experimental-skill drift fix + Chief registry drift check (issues #4/#5/#6). (1) FORGE.md gains a base 'Worktree Convention' (path/anchor/branch + orchestration.worktree_root resolution + lifecycle.worktree_path authority) so Chief/Streams has a fallback when a worktree was created outside orchestrating, and the convention stays upgrade-synced regardless of the experimental skill. (2) upgrading no longer blanket-skips installed experimental skills — it diffs them against experimental/*/source and offers a preview/confirm re-sync (warn at minimum), closing the silent-freeze where base migrations (e.g. 0.28.0 worktree-root) became no-ops against a frozen orchestrating skill. (3) migration-guide template gains an authoring guard: guides whose behavior lives in an experimental skill must detect the skill's content, not just the version stamp. (4) chief-of-staff gains an advisory Registry Drift Check (Show + Sync) reconciling state/index.yml active milestones against streams/active.yml."
-  - milestone: 16
-    version: "0.34.0"
-    bump: minor
-    reserved_at: "2026-06-21"
-    summary: "Live-Worktree Ownership Gate (issue #7). forge boot's worktree surfacing was advisory, so a session on main could write single-owner-mutable milestone state (milestone-{id}.yml, phases/, research/) while a live worktree owned the milestone — forking the cursor (main 'reviewing' vs worktree 'planning'). forge SKILL gains an enforced gate (1.1a): when invoked from main and the selected milestone has a live worktree, milestone-owned writes are blocked and routing stops until the operator enters the worktree, syncs it, retires it, or records an explicit lifecycle.ownership_override (the only, never-silent bypass). Shared project docs stay writable from main with a not-visible-until-sync warning. FORGE.md State Ownership promoted from advice to enforcement. Also folds in dev/template skill drift cleanup: forge/discussing/planning dev .claude/skills copies were behind the template (chief-streams + context-archive content) — brought to parity."
-  - milestone: 16
-    version: "0.35.0"
-    bump: minor
-    reserved_at: "2026-06-21"
-    summary: "Merge often and early (issue #8). Stream integration was pull-based and deferred — ready work sat on its branch until milestone end, drifting from main and staling shared surfaces. Adds the stated principle to FORGE.md Project Streams (continuous integration posture; surfacing only, never auto-merge/auto-rebase). chief-of-staff gains an advisory Merge Cadence Check (Show + Sync): ready-to-merge surfacing from active.yml status:ready + merge_queue, idle-ready nudge, sibling-rebase nudge when main advanced on a shared surface, and merge-order recommendation. forge boot gains a light ready-to-merge nudge pointing to chief-of-staff. All advisory — never blocks, never merges, never rebases."
-  - milestone: 16
-    version: "0.36.0"
-    bump: minor
-    reserved_at: "2026-06-21"
-    summary: "Stream Integration Checkpoints — event-driven continuous integration, the producer/flag/consumer follow-up to #8's polling-based cadence check. (1) planning marks integration_checkpoint phases in plan frontmatter (advisory; default = last phase + depended-on phases; the mark is the opt-in so unmarked/existing work is unaffected). (2) Producer: verifying, on a PASSED + human-verified checkpoint phase in a worktree, fast-forward-only publishes to main (git push origin HEAD:main — git rejects non-ff, which is the safety; diverged main is surfaced, never forced) and sets an integration flag in .git/forge/integration-pending (git common dir, shared across a machine's worktrees). (3) Consumer: forge boot in a worktree reads the flag cheaply — set + no divergence → auto git merge --ff-only main (conflict-free); diverged → surface a rebase prompt; not set → skip (no fetch, no scan). Supersedes the 0.35.0 forge-boot polling pointer with event-driven detection. Cross-machine falls back to opt-in worktree_rebase_check. Never force-pushes, auto-resolves a conflict, or auto-rebases."
-  - milestone: 16
-    version: "0.37.0"
-    bump: minor
-    reserved_at: "2026-06-22"
-    summary: "Derived stream registry / Stream Rollup (ADR-015) — the durable structural fix for issue #4's registry drift, superseding the 0.33.0 advisory Registry Drift Check. streams/active.yml becomes a DERIVED projection (like state/index.yml), never hand-edited, regenerated by a deterministic join-rollup over two single-sourced inputs: per-stream files streams/{stream}.yml (coordination lifecycle + ownership/runtime/merge/blockers) and active milestone files (workflow phase). Resolves the not-1:1 milestone↔stream relationship by keeping workflow phase and coordination status as orthogonal dimensions side by side in each derived row (phase from milestone, coordination from stream file) rather than collapsing one into the other; coverage is computed (active milestone with no stream file → derived 'implicit' row) so #4's exact symptom is structurally impossible. Adds stream.milestone link field (lazy; absent ⇒ standalone). forge boot + chief-of-staff Show/Sync run the Stream Rollup; chief Start/Pause/Resume/Close/Adopt write per-stream files then regenerate. Registry Drift Check removed. active.yml put in the derived state-ownership class (ADR-011); worktrees never write it. Migration: materialize per-stream files from a hand-maintained active.yml, then regenerate."
-
-# Note on the 15 / 0.24.0 ordering: reserved as max(0.23.0)+minor. origin/main was
-# already at 0.23.0 when this shipped (M10/M12/M13/M14 all merged), so 0.24.0 is a
-# clean increment — no publish-order coordination needed. (Earlier draft of this
-# release was built on a stale 0.19.2 base before a fetch corrected it.)
-
-# Note on the 12/13 ordering: both reserved 2026-06-12. M13 holds the lower number
-# (0.20.0) and M12 the higher (0.21.0) by explicit user decision — they ship in the
-# same package release, M12 topping the version. max() here is 0.21.0, so the next
-# milestone reserves 0.22.0 (minor) regardless of which milestone id is higher.
+releases: []

package/template/.forge/templates/plan.md

@@ -29,8 +29,29 @@ must_haves:
   truths:                            # USER-observable when plan is done. Must contain a user verb
                                      # (see, click, submit, receive, view, download, error, redirect).
                                      # Internal-only truths like "Schema applied" do NOT satisfy.
+                                     # Entry form: bare string (legacy — remains valid, no migration)
+                                     # OR object with an OPTIONAL executable check:
     - ""                             # e.g., "User submits signup form and lands on dashboard"
-    - ""                             # e.g., "Invalid email shows inline 'must be a valid email' error"
+    - truth: ""                      # e.g., "Invalid email shows inline 'must be a valid email' error"
+      check: ""                      # OPTIONAL shell command proving the truth. Semantics:
+                                     #  - exit 0 = pass; anything else = fail. The exit code, not
+                                     #    agent judgment, is the verdict (executed-evidence rule).
+                                     #  - must PRINT WHY it fails — its output feeds executing's
+                                     #    auto-fix loop and the verification report (`diff` beats
+                                     #    `diff -q`; an assert-with-message beats a bare `test`).
+                                     #  - verify content/behavior, not existence (`test -f` proves
+                                     #    existence only).
+                                     #  - safe to run repeatedly — read-only, or idempotent against
+                                     #    durable state (checks run in executing AND verifying,
+                                     #    plus auto-fix retries).
+                                     #  - authored at planning time, goal-backward, BEFORE code
+                                     #    exists — a pre-code check can't be retro-fitted to what
+                                     #    got built.
+    - truth: ""                      # A truth that can't be a command (visual, real-device,
+      manual: ""                     # external service) carries a `manual:` route INSTEAD of a
+                                     # check — e.g. "human gate" or "M9 e2e" — never a fake check.
+                                     # executing skips manual truths (no check to run); verifying
+                                     # routes them to HUMAN VERIFICATION NEEDED.
   artifacts:                         # Files that must exist and be substantive (not stubs).
                                      # Slice plans typically span 2-4 layers — paths should cross
                                      # boundaries (component + handler + repo), not cluster in one dir.
@@ -50,6 +71,19 @@ must_haves:
 
 <task type="auto">
   <name>Action-oriented task name</name>
+  <complexity>standard</complexity>       <!-- OPTIONAL (M24). complexity is trivial | standard | complex.
+                                                Routing signal → resolves a model via project.yml
+                                                models.by_complexity (see FORGE.md Model Routing).
+                                                trivial = config/docs/mechanical; standard = ordinary
+                                                feature/fix; complex = cross-layer behavior, tricky logic,
+                                                high blast radius. OMIT the field → the task falls back to
+                                                skill-level model routing, exactly as pre-M24 plans did.
+                                                No migration: a task with neither field parses unchanged. -->
+  <task_type>code-feature</task_type>      <!-- OPTIONAL (M24). code-feature | code-fix | docs | research |
+                                                config | test. The promotion-ladder BUCKET key — phases
+                                                37-38 learn "model X is proven on task_type Y". Free choice
+                                                from this controlled vocabulary; pick the dominant kind.
+                                                OMIT → task is not bucketed; no effect on legacy plans. -->
   <files>
     - src/path/to/file.tsx (create)
     - src/path/to/other.ts (modify)

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

@@ -90,6 +90,10 @@ models:
     securing: sonnet                   # Security analysis needs depth
     debugging: sonnet                  # Investigation needs solid reasoning
     discussing: sonnet                 # Conversation needs natural fluency
+  # by_complexity:                     # Per-task complexity -> model (M24). Overrides skills.X — see FORGE.md Model Routing Precedence.
+  #   trivial: haiku
+  #   standard: sonnet
+  #   complex: opus
 
 orchestration:                       # M10 multi-agent orchestration (experimental). Only consulted when M10 is installed.
   # auto: true                         # false = never auto-route Standard/Full through orchestrating (install = consent; set false to opt out).

package/template/.forge/templates/prototypes/prototype.md

@@ -0,0 +1,31 @@
+---
+slug: "{kebab-slug}"
+title: "{short human title}"
+created: "{ISO date}"
+status: exploring          # exploring | parked | graduated | discarded
+flag: "{how it's gated — e.g. alpha, ?alpha=1, feature:foo, settings.alphaMockups}"
+goal: "{one line — what are we trying to see before building it for real?}"
+# --- set on resolve ---
+# graduated_to: m-{id}     # when status: graduated
+# resolved: "{ISO date}"   # when graduated or discarded
+# discard_reason: "..."    # when status: discarded
+# parked: "{ISO date}"     # when status: parked
+# unpark_when: "..."       # when status: parked — what would bring this back
+---
+
+# Prototype: {title}
+
+Disposable in-app mockup, gated behind `{flag}`. Not production work — see `.claude/skills/prototyping/SKILL.md`.
+
+## Open question
+
+{The thing this iteration round is trying to answer / react to right now. Rewrite as it evolves.}
+
+## Iterations
+
+<!-- One terse line per pass. This is the loop's memory across /clear — keep it scannable, not a design doc. -->
+- {ISO date} — {what this iteration tried, and what to look at}
+
+## Notes
+
+{Optional: decisions leaning one way, dead ends, things to remember if this graduates.}