forge-orkes 0.46.0 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.46.0",
+  "version": "0.49.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/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/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)
@@ -198,6 +200,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 +231,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 +256,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 +317,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 +404,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 +421,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 +480,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/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.}