forge-orkes 0.64.5 → 0.67.0

package/package.json

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

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

@@ -23,13 +23,17 @@
 #
 # Pinned field set (contract between record + recommend; keep names stable):
 #   ts repo milestone skill task_type complexity model first_try_pass check_exit
+#   cost_usd tokens   (step-5 m-42 — durable per-phase spend; the ts field already
+#                      dates every row, so cost_usd+tokens give spend-over-time stats
+#                      from this ONE durable log, no new store. Both null when unset —
+#                      lazy migration, existing rows/readers unaffected.)
 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]
+         [--check-exit N] [--cost USD] [--tokens N]
        forge-model-outcome.sh recommend
 EOF
 }
@@ -42,7 +46,7 @@ log_path() {
 do_record() {
   # --- parse flags (ALL optional — missing -> empty string / null) ---------
   repo=""; milestone=""; skill=""; task_type=""; complexity=""; model=""
-  first_try_pass=""; check_exit=""
+  first_try_pass=""; check_exit=""; cost=""; tokens=""
   while [ $# -gt 0 ]; do
     case "$1" in
       --repo) shift; repo="${1:-}"; [ $# -gt 0 ] && shift || true ;;
@@ -61,6 +65,10 @@ do_record() {
       --first-try-pass=*) first_try_pass="${1#*=}"; shift ;;
       --check-exit) shift; check_exit="${1:-}"; [ $# -gt 0 ] && shift || true ;;
       --check-exit=*) check_exit="${1#*=}"; shift ;;
+      --cost) shift; cost="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --cost=*) cost="${1#*=}"; shift ;;
+      --tokens) shift; tokens="${1:-}"; [ $# -gt 0 ] && shift || true ;;
+      --tokens=*) tokens="${1#*=}"; shift ;;
       -*) printf 'forge-model-outcome: unknown option: %s (ignored)\n' "$1" >&2; shift ;;
       *) shift ;;
     esac
@@ -87,9 +95,16 @@ do_record() {
     *) 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}' \
+  # cost_usd (float) + tokens (int) — numeric JSON, null when unset/malformed. A
+  # numeric literal (not a quoted string) keeps `jq` sums/averages trivial.
+  cost_j="null"
+  case "$cost" in ''|*[!0-9.]*) cost_j="null" ;; *) cost_j="$cost" ;; esac
+  tokens_j="null"
+  case "$tokens" in ''|*[!0-9]*) tokens_j="null" ;; *) tokens_j="$tokens" ;; 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,"cost_usd":%s,"tokens":%s}' \
     "$(esc "$ts")" "$(esc "$repo")" "$(esc "$milestone")" "$(esc "$skill")" \
-    "$(esc "$task_type")" "$(esc "$complexity")" "$(esc "$model")" "$fp" "$ce")
+    "$(esc "$task_type")" "$(esc "$complexity")" "$(esc "$model")" "$fp" "$ce" "$cost_j" "$tokens_j")
 
   # 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
@@ -121,7 +136,8 @@ do_recommend() {
           model: .[0].model,
           task_type: .[0].task_type,
           count: length,
-          pass_rate: (([ .[] | select(.first_try_pass == true) ] | length) / length)
+          pass_rate: (([ .[] | select(.first_try_pass == true) ] | length) / length),
+          total_cost: ([ .[] | (.cost_usd // 0) ] | add)
         }
         | . + {
             status: (
@@ -149,7 +165,8 @@ do_recommend() {
     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"
+    cost="$(printf '%s' "$b" | jq -r '.total_cost' | LC_NUMERIC=C awk '{printf "%.4f", $1+0}')"
+    printf '  model=%-10s task_type=%-14s status=%-10s count=%-4s first-try=%s%% spend=$%s\n' "$model" "$task_type" "$status" "$count" "$pct" "$cost"
   done
 
   printf '\nRouting recommendations:\n'

package/template/.claude/hooks/forge-slice-runner.sh

@@ -172,6 +172,35 @@ usage_num() {  # usage_num <result.json> <input_tokens|output_tokens> — the AG
   _um="$(sed 's/.*"usage":{//' "$1" 2>/dev/null | grep -o "\"$2\":[0-9]*" | head -1 | sed 's/.*://')"
   [ -n "$_um" ] && printf '%s' "$_um" || printf '0'
 }
+actual_model_from_result() {  # actual_model_from_result <result.json> — the PRIMARY model actually used
+  # The launcher's result envelope carries `modelUsage`, an object keyed by FULL model
+  # id (`claude-sonnet-5`, `claude-haiku-4-5-...`) with a per-model usage breakdown. A
+  # single phase legitimately touches MORE than one model (main work + background
+  # micro-calls), so "the actual model" is the PRIMARY: the entry with the max
+  # outputTokens. Step-5 attribution records reality from HERE, never from intent.
+  # Dependency-free awk (NFR-026); result.json is a single line.
+  # Anchor to the LAST `"modelUsage":{` (the launcher's real one, appended AFTER the
+  # model-controlled `result` string) — same spoof defense result_num uses with tail -1:
+  # a phase that embeds `"modelUsage":{…}` in its answer text can't win, because its copy
+  # precedes the launcher's and we take the last.
+  [ -f "$1" ] || { printf -- '-'; return 0; }
+  _am="$(awk '
+    { ex = $0; seg = ""
+      while (match(ex, /"modelUsage":\{/)) { ex = substr(ex, RSTART+RLENGTH); seg = ex }
+      if (seg == "") next
+      best=""; bestn=-1
+      while (match(seg, /"[^"]+":\{[^}]*"outputTokens":[0-9]+/)) {
+        entry = substr(seg, RSTART, RLENGTH)
+        idm = entry; sub(/":\{.*/, "", idm); sub(/^"/, "", idm)     # model id = leading quoted token
+        otm = entry; sub(/.*"outputTokens":/, "", otm); ot = otm + 0
+        if (ot > bestn) { bestn = ot; best = idm }
+        seg = substr(seg, RSTART+RLENGTH)
+      }
+      if (best != "") print best
+      exit
+    }' "$1" 2>/dev/null)"
+  [ -n "$_am" ] && printf '%s' "$_am" || printf -- '-'
+}
 
 # --- model-by-phase-type map (STEP-5 SEAM — read, NOT routed) ----------------
 # The runner reads config.model_by_phase_type to RECORD each phase's intended model
@@ -201,12 +230,17 @@ phase_type_of() {  # phase_type_of <phase> — optional `phase_type:` in the pha
     | sed -E 's/^phase_type:[[:space:]]*//; s/[[:space:]]*(#.*)?$//')"
   printf '%s' "$_pt"
 }
-model_for_phase() {  # model_for_phase <phase> <report-file> — intended model, recorded not routed
+model_for_phase() {  # model_for_phase <phase> — the intended model, from the MAP ONLY
+  # The routing decision (and the recorded intended_model) come SOLELY from
+  # config.model_by_phase_type keyed by the phase's phase_type. It deliberately does
+  # NOT fall back to the phase's self-reported usage.model: a phase's own output must
+  # never influence its dispatch (that would break the absent-map byte-identical
+  # invariant on a parked-phase resume, where a prior report persists). No phase_type
+  # or no map entry → "-" (unrouted). The <report-file> arg is retained for call-site
+  # compatibility but no longer read.
   _mp_type="$(phase_type_of "$1")"
   _mp=""
   [ -n "$_mp_type" ] && _mp="$(cfg_map_get model_by_phase_type "$_mp_type" "")"
-  # Fall back to what the phase itself recorded, then a placeholder.
-  [ -z "$_mp" ] && _mp="$(report_nested "$2" model)"
   [ -z "$_mp" ] && _mp="-"
   printf '%s' "$_mp"
 }
@@ -469,6 +503,16 @@ for phase in $PHASES; do
   #     token furnace). A launch that writes no report at all is a CRASH, not a
   #     check failure — it halts immediately so crash-resume re-runs it next boot.
   _pstart="$(date +%s 2>/dev/null || echo 0)"   # phase wall-clock start (runner-measured)
+  # STEP 5 — per-phase model routing. Resolve the intended model ONCE (map value via
+  # model_for_phase, or "-"/"" when unmapped). `_route_model` is what THIS attempt
+  # launches with; on a routed STARTUP failure it is blanked for a single unrouted
+  # retry (the fallback), recorded `routed → fallback` in the receipt. All routing
+  # lives here + at the launch below — nowhere else (FR-198/NFR-044).
+  _intended_model="$(model_for_phase "$phase" "$report")"
+  _route_model="$_intended_model"
+  [ "$_route_model" = "-" ] && _route_model=""
+  _fallback=no
+  _routed_fallback_done=0
   attempt=1
   max_attempt=2
   verdict=""
@@ -477,6 +521,11 @@ for phase in $PHASES; do
       "$phase" "$idx" "$total" "$LAUNCHER" "$attempt" >&2
     (
       cd "$WORKTREE"
+      # STEP 5 routing: prepend `--model <value>` iff this phase is routed. Built via
+      # `set --` so an unrouted launch passes NO --model flag — the dispatch args are
+      # then byte-for-byte today's (the absent-map neg control). Empty `"$@"` expands
+      # to nothing; a set value is properly word-safe.
+      if [ -n "$_route_model" ]; then set -- --model "$_route_model"; else set --; fi
       # A headless, zero-touch phase has no TTY to approve tool use, so the per-tool
       # permission gate is bypassed — otherwise the very first Write (the work, or
       # the mandatory phase-report.yml) blocks forever waiting for an approval that
@@ -489,7 +538,7 @@ for phase in $PHASES; do
       FORGE_SLICE_PHASE="$phase" \
       FORGE_SLICE_PHASE_INDEX="$idx" \
       FORGE_SLICE_ATTEMPT="$attempt" \
-      "$LAUNCHER" -p \
+      "$LAUNCHER" -p "$@" \
         --output-format json \
         --max-turns "$MAX_TURNS" \
         --max-budget-usd "$MAX_BUDGET" \
@@ -498,12 +547,28 @@ for phase in $PHASES; do
         < "$prompt" \
         > "$wdir/result.json" 2> "$wdir/launch.err"
     ) || {
-      printf '[runner] phase %s: launcher exited non-zero (attempt %s)\n' "$phase" "$attempt" >&2
+      printf '[runner] phase %s: launcher exited non-zero (attempt %s%s)\n' \
+        "$phase" "$attempt" "${_route_model:+, --model $_route_model}" >&2
     }
 
     # Record this attempt's session id — the fresh-context proof the retry asserts.
     extract_session "$wdir/result.json" > "$wdir/attempt-$attempt.session"
 
+    # STEP 5 fallback — a ROUTED launch that wrote NO report is a startup failure
+    # (e.g. an unusable model). Retry ONCE unrouted (blank _route_model), recorded
+    # `routed → fallback` in the receipt. This is a DISTINCT axis from the
+    # checks-failed retry: it does not consume `attempt`, and a bad model degrades
+    # to the default rather than halting the slice (routing must be harmless). An
+    # unrouted launch that writes no report is a genuine crash → the halt below.
+    if [ ! -f "$report" ] && [ -n "$_route_model" ] && [ "$_routed_fallback_done" -eq 0 ]; then
+      printf '[runner] phase %s: routed launch (--model %s) wrote no report — falling back to default (unrouted), one retry\n' \
+        "$phase" "$_route_model" >&2
+      _routed_fallback_done=1
+      _fallback=yes
+      _route_model=""
+      continue
+    fi
+
     # (4) REQUIRE the on-disk phase-report.yml. Absent = crash → halt now (do NOT
     #     spend the retry on a crash; the resume path re-runs it from files).
     if [ ! -f "$report" ]; then
@@ -556,20 +621,59 @@ for phase in $PHASES; do
   #      spend seam), one row per phase. Sourced for FIDELITY (live walk found the
   #      phase-report's self-reported usage was all zeros — a phase can't know its
   #      own token count):
-  #        tokens       = result.json input_tokens + output_tokens (launcher truth)
-  #        wall_clock_s = runner-measured elapsed for the phase (incl. any retry)
-  #        retry_count  = runner-observed (attempt-1), not the phase's self-report
-  #        model        = intended model for the phase-type, READ from config but
-  #                       NOT routed (model_for_phase → the step-5 seam)
+  #        tokens         = result.json input_tokens + output_tokens (launcher truth)
+  #        wall_clock_s   = runner-measured elapsed for the phase (incl. any retry)
+  #        retry_count    = runner-observed (attempt-1), not the phase's self-report
+  #        model          = intended model (kept for back-compat with the 5-col reader)
+  #        intended_model = what routing ASKED for (map value, "-" when unmapped)
+  #        actual_model   = the PRIMARY model actually used (result.json modelUsage,
+  #                         max outputTokens) — reality, not intent
+  #        fallback       = yes when a routed launch fell back unrouted (routed → fallback)
+  #        cost_usd       = per-phase spend (result.json total_cost_usd) — the spend
+  #                         the by-phase-type-and-model attribution surface sums
   _tok_in="$(usage_num "$wdir/result.json" input_tokens)"
   _tok_out="$(usage_num "$wdir/result.json" output_tokens)"
   _u_tokens="$(awk -v a="$_tok_in" -v b="$_tok_out" 'BEGIN{printf "%d", (a+0)+(b+0)}')"
   _now="$(date +%s 2>/dev/null || echo 0)"
   if [ "$_now" -ge "$_pstart" ] 2>/dev/null; then _u_wall=$(( _now - _pstart )); else _u_wall=0; fi
   _u_retry=$(( attempt - 1 ))
-  _u_model="$(model_for_phase "$phase" "$report")"
-  [ -f "$USAGE_FILE" ] || printf 'phase_name\ttokens\twall_clock_s\tmodel\tretry_count\n' > "$USAGE_FILE"
-  printf '%s\t%s\t%s\t%s\t%s\n' "$phase" "$_u_tokens" "$_u_wall" "$_u_model" "$_u_retry" >> "$USAGE_FILE"
+  _u_intended="${_intended_model:--}"
+  _u_actual="$(actual_model_from_result "$wdir/result.json")"
+  _u_model="$_u_intended"                                 # 5-col `model` = intended (back-compat)
+  _u_cost="$_cost"                                        # per-phase spend (result.json total_cost_usd)
+  [ -f "$USAGE_FILE" ] || printf 'phase_name\ttokens\twall_clock_s\tmodel\tretry_count\tintended_model\tactual_model\tfallback\tcost_usd\n' > "$USAGE_FILE"
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+    "$phase" "$_u_tokens" "$_u_wall" "$_u_model" "$_u_retry" "$_u_intended" "$_u_actual" "$_fallback" "$_u_cost" >> "$USAGE_FILE"
+
+  # (4b) FEED THE M24 OUTCOME LADDER (step-5 B4). Append ONE outcome line per ROUTED
+  #      phase so the ladder accumulates real per-(model, task_type) volume at last.
+  #      The ladder answers "should I route task_type T to model X?", so it is keyed on
+  #      the model the operator MAPPED — the intended model — in ONE consistent
+  #      vocabulary for BOTH outcomes (a routing that held and one that fell back share
+  #      a key, so success/failure of the same mapped model aggregate instead of
+  #      fragmenting). Recorded only when there is a routing decision to judge:
+  #        • unrouted (no phase_type / no map entry) → SKIP: the default model's baseline
+  #          is not a routing choice.
+  #        • park → SKIP: an operator interrupt is not a model-quality outcome.
+  #        • routed → fallback → first_try_pass=false (the mapped model failed to run).
+  #        • routed & ran      → first_try_pass = attempt 1 AND terminal-good AND no checks failed.
+  #      ADVISORY: the helper always exits 0; guard so a missing helper never touches the
+  #      slice. The routing map is consumed READ-ONLY throughout the runner; only the
+  #      operator ever edits it by hand (D-F) — no code path here modifies that config.
+  _mo_type="$(phase_type_of "$phase")"
+  if [ -n "$_mo_type" ] && [ -n "$_intended_model" ] && [ "$_intended_model" != "-" ] \
+     && [ "$verdict" != park ] && [ -x "$SELF_DIR/forge-model-outcome.sh" ]; then
+    _mo_ftp=false
+    if [ "$_fallback" = no ] && [ "$attempt" -eq 1 ] \
+       && { [ "$verdict" = proceed ] || [ "$verdict" = done ]; } && [ "$cfailed" -eq 0 ]; then
+      _mo_ftp=true
+    fi
+    "$SELF_DIR/forge-model-outcome.sh" record \
+      --repo "$(basename "$REPO_ROOT" 2>/dev/null || echo slice)" \
+      --skill executing --task-type "$_mo_type" \
+      --model "$_intended_model" --first-try-pass "$_mo_ftp" \
+      --check-exit "$cfailed" --cost "$_u_cost" --tokens "$_u_tokens" >/dev/null 2>&1 || true
+  fi
 
   # (5) BRANCH on verdict. proceed advances; done ends with the done ping.
   #     park is STUBBED here (plan-48 wires the real §8 interrupt ping) — explicit,

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

@@ -103,6 +103,30 @@ else
   fail "case6 recommend missing insufficient-data message: $out"
 fi
 
+# --- Case 7: cost_usd + tokens are stored numeric, null when omitted (m-42) --
+d="$ROOT/case7"; mkdir -p "$d"
+HOME="$d" "$HELPER" record --repo x --skill executing --task-type verifying \
+  --model haiku --first-try-pass true --check-exit 0 --cost 0.0333 --tokens 686 >/dev/null
+HOME="$d" "$HELPER" record --repo x --skill executing --task-type docs \
+  --model sonnet --first-try-pass true >/dev/null   # no cost/tokens → null
+log="$d/.forge/model-outcomes.jsonl"
+if grep -q '"cost_usd":0.0333' "$log" && grep -q '"tokens":686' "$log"; then
+  pass "case7 record stores numeric cost_usd + tokens"
+else
+  fail "case7 cost/tokens not stored numeric: $(cat "$log")"
+fi
+if grep -q '"cost_usd":null' "$log" && grep -q '"tokens":null' "$log"; then
+  pass "case7 omitted cost/tokens store as null (lazy migration)"
+else
+  fail "case7 omitted cost/tokens not null: $(cat "$log")"
+fi
+out="$(HOME="$d" "$HELPER" recommend)"
+if printf '%s' "$out" | grep -qE 'spend=\$0\.0333'; then
+  pass "case7 recommend surfaces per-bucket spend"
+else
+  fail "case7 recommend missing spend column: $out"
+fi
+
 # --- Report -----------------------------------------------------------------
 printf '\n%d passed, %d failed\n' "$PASSED" "$FAILED"
 [ "$FAILED" -eq 0 ]

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

@@ -193,6 +193,7 @@ Plan naming reflects the slice: `plan-01-user-signs-up.md`, not `plan-01-models.
    - `{id}`=milestone, `{phase}`=phase# (preserved verbatim, NOT renumbered), `{name}`=kebab, `{NN}`=seq
    - Ex: `.forge/phases/milestone-3/2-providers/plan-01.md`
 2. Frontmatter: phase, plan#, wave, deps, `slice_exception:` (optional, see Core Principle), `integration_checkpoint:` (optional, see below)
+   - **`phase_type:` (per-phase model routing, m-42).** Stamp the workflow phase this plan SERVES — one of the `model_by_phase_type` keys (`researching | discussing | architecting | planning | executing | verifying | reviewing`). Build plans are almost always `executing`; a plan that authors a verify/review phase's work is `verifying`/`reviewing`. This is what lets the headless slice runner route each phase to the model mapped for its type (the map ships commented → routing is off until the operator activates it, so stamping this is always safe and never changes behavior on its own). Empty ⇒ that phase runs unrouted (inherits the default model). Emit it on every plan; when unsure, `executing`.
 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`).

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

@@ -35,6 +35,7 @@ SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SELF_DIR/../.." && pwd)"
 
 LOGS=""
+USAGES=""
 MARKER_DIR_OVERRIDE=""
 LIVE_WINDOW=120
 SINCE=""
@@ -43,6 +44,8 @@ DRY_RUN=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --log)           LOGS="${LOGS}${LOGS:+
+}${2:-}"; shift 2 ;;
+    --usage)         USAGES="${USAGES}${USAGES:+
 }${2:-}"; shift 2 ;;
     --marker-dir)    MARKER_DIR_OVERRIDE="${2:-}"; shift 2 ;;
     --live-window)   LIVE_WINDOW="${2:-120}"; shift 2 ;;
@@ -82,9 +85,36 @@ GLOBBED_EOF
   fi
 fi
 
+# ── resolve the usage.tsv set (spend receipts): explicit --usage wins; else disk-glob ────────────
+# Same slice worktrees as the logs, sibling file runner-work/usage.tsv. No new store —
+# these ARE the per-phase receipts the runner already writes (step-5 spend attribution).
+if [ -z "$USAGES" ]; then
+  if [ -n "$WT_ROOT" ]; then
+    for _wt in "$WT_ROOT"/*/; do
+      [ -d "$_wt" ] || continue
+      _u="${_wt}.forge/runner-work/usage.tsv"
+      [ -f "$_u" ] && USAGES="${USAGES}${USAGES:+
+}$_u"
+    done
+  else
+    _uglobbed="$(git -C "$REPO_ROOT" worktree list --porcelain 2>/dev/null | awk '
+      /^worktree / { p = substr($0, 10) }
+      /^branch /   { if ($2 ~ /refs\/heads\/forge\/m-/) print p "/.forge/runner-work/usage.tsv" }')"
+    while IFS= read -r _u; do
+      [ -n "$_u" ] || continue
+      [ -f "$_u" ] && USAGES="${USAGES}${USAGES:+
+}$_u"
+    done <<UGLOBBED_EOF
+$_uglobbed
+UGLOBBED_EOF
+  fi
+fi
+
 if [ "$DRY_RUN" -eq 1 ]; then
   printf 'forge-jarvis-instruments (--dry-run): resolved logs:\n'
   if [ -n "$LOGS" ]; then printf '%s\n' "$LOGS" | sed 's/^/   /'; else printf '   (none)\n'; fi
+  printf 'forge-jarvis-instruments (--dry-run): resolved usage receipts:\n'
+  if [ -n "$USAGES" ]; then printf '%s\n' "$USAGES" | sed 's/^/   /'; else printf '   (none)\n'; fi
   exit 0
 fi
 
@@ -146,4 +176,41 @@ awk -F'\t' -v total="$_total" -v win="$LIVE_WINDOW" '
     printf "  (proxy — derived from relay latency, not an uptime store)\n"
   }' "$TMP"
 
+# ── 5. Spend by phase and model (step-5 attribution) ─────────────────────────────────────────────
+# Answers "what did this cost, by phase and model?" WITHOUT opening a file — computed
+# live from the runner's usage.tsv receipts (9-col step-5 schema: …actual_model fallback
+# cost_usd). NO new store. Legacy 5-col receipts have no model/cost columns → skipped with
+# a note. Groups by (phase, actual_model), sums cost, flags routed→fallback rows.
+printf '\n5. Spend by phase and model (from usage.tsv receipts):\n'
+printf '%s\n' "$USAGES" | while IFS= read -r U; do
+  [ -n "$U" ] && [ -f "$U" ] || continue
+  _hdr="$(head -1 "$U")"
+  case "$_hdr" in
+    *actual_model*cost_usd*)
+      # LC_NUMERIC=C so awk parses AND prints the `.`-decimal cost regardless of locale
+      # (a comma locale otherwise reads "0.63" as 0 and prints "0,63" — same fix the runner uses).
+      LC_NUMERIC=C awk -F'\t' -v src="$U" '
+        NR==1 { next }
+        NF>=9 && $1!="" {
+          key = $1 SUBSEP $7                 # phase SUBSEP actual_model
+          cost[key] += ($9 + 0)
+          if ($8 == "yes") fb[key] += 1
+          seen[key] = 1
+        }
+        END {
+          for (k in seen) {
+            split(k, a, SUBSEP)
+            printf "     %-16s %-26s $%.4f%s\n", a[1], a[2], cost[k], (fb[k] ? "  (routed->fallback x" fb[k] ")" : "")
+          }
+        }' "$U"
+      ;;
+    *)
+      printf '     (legacy 5-col receipt %s — no model/cost columns; re-run to populate)\n' "$U" ;;
+  esac
+done
+# Note when no receipts were found at all (a clean "nothing ran yet", not an error).
+if [ -z "$USAGES" ]; then
+  printf '     (no usage.tsv receipts found — no slices instrumented yet)\n'
+fi
+
 exit 0

package/template/.forge/checks/tests/forge-jarvis-instruments.test.sh

@@ -60,5 +60,28 @@ printf '%s\n' "$OUT" | grep -qE '2/3 relayed live'        && ok "presence proxy:
 # 5. the presence line labels itself a proxy (never a measured SLA)
 printf '%s\n' "$OUT" | grep -qiE 'proxy'                  && ok "presence figure is labelled a proxy, not an SLA"      || bad "proxy label"      "$OUT"
 
+# ── spend-by-phase-and-model section (step-5 attribution, from usage.tsv receipts) ──
+# A hand-built 9-col usage.tsv: two models, one routed→fallback row. The section must
+# answer "what did this cost, by phase and model" from the receipts — no new store.
+USG="$ROOT/usage.tsv"
+{
+  printf 'phase_name\ttokens\twall_clock_s\tmodel\tretry_count\tintended_model\tactual_model\tfallback\tcost_usd\n'
+  printf 'phase-1\t1000\t2\tsonnet\t0\tsonnet\tclaude-sonnet-5\tno\t0.6300\n'
+  printf 'phase-2\t500\t1\thaiku\t0\thaiku\tclaude-haiku-4-5-20251001\tno\t0.0040\n'
+  printf 'phase-3\t800\t3\topus\t0\topus\tclaude-sonnet-5\tyes\t0.4000\n'
+} > "$USG"
+
+SOUT="$(sh "$INSTR" --log "$LOG" --marker-dir "$MK" --usage "$USG" 2>/dev/null)"
+
+printf '%s\n' "$SOUT" | grep -qE '5\. Spend by phase and model'          && ok "spend section renders"                                  || bad "spend section"        "$SOUT"
+printf '%s\n' "$SOUT" | grep -qE 'phase-1.*claude-sonnet-5.*\$0\.6300'   && ok "spend: phase-1 on claude-sonnet-5 = \$0.6300"            || bad "spend phase-1"        "$SOUT"
+printf '%s\n' "$SOUT" | grep -qE 'phase-2.*claude-haiku-4-5.*\$0\.0040'  && ok "spend: phase-2 on claude-haiku = \$0.0040"               || bad "spend phase-2"        "$SOUT"
+printf '%s\n' "$SOUT" | grep -qE 'phase-3.*routed->fallback'             && ok "spend: phase-3 flagged routed->fallback"                || bad "spend fallback flag"  "$SOUT"
+
+# neg control — the numbers are COMPUTED at render; no new stored aggregate file exists.
+grep -rqiE 'spend[-_]?store|aggregate\.tsv|spend\.db|cost[-_]cache' "$SCRIPT_DIR/../forge-jarvis-instruments.sh" \
+  && bad "no-new-store neg control" "found a spend-store reference" \
+  || ok "no new spend store — computed from usage.tsv at render"
+
 printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
 [ "$FAILED" = 0 ]

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

@@ -13,6 +13,11 @@ phase: 1
 phase_name: ""
 plan: 1
 type: execute                        # execute | tdd
+phase_type: ""                       # the workflow phase this plan SERVES — one of the model_by_phase_type keys:
+                                     #   researching | discussing | architecting | planning | executing | verifying | reviewing
+                                     # Drives per-phase model routing (m-42): the slice runner reads this to pick the phase's
+                                     # model from config.model_by_phase_type. Build plans are usually `executing`; a verify/review
+                                     # phase plan is `verifying`/`reviewing`. Empty = unrouted (inherits the default model).
 wave: 1                              # Execution wave (1 = no dependencies)
 depends_on: []                       # Plan IDs that must complete first
 autonomous: true                     # false if contains checkpoints

package/template/.forge/templates/slice-runner/config.yml

@@ -45,18 +45,27 @@ divergence_budget_lines: 4000
 # without touching the loop.
 notify_channel: pushnotification
 
-# --- model-by-phase-type map (STEP-5 SEAM — read, not routed) ---------------
+# --- model-by-phase-type map (per-phase model routing — step 5) --------------
 
-# Read per phase-type and recorded into phase-report.yml usage.model, but NOT used
-# to route the launch yet — this is the seam step 5 (per-phase model routing)
-# fills. Leaving it here now keeps the report's `model` field populated and gives
-# step 5 a config surface to switch on. The runner MUST NOT branch launch behavior
-# on this map in this milestone.
+# Maps a phase's `phase_type:` (declared in its plan — the workflow phase it serves:
+# researching|discussing|architecting|planning|executing|verifying|reviewing) to the
+# model its headless `claude -p` launch runs on. `--model` accepts these aliases
+# (or a full id like `claude-sonnet-5`).
+#
+# SHIPS COMMENTED = OFF BY DEFAULT. An absent/empty map reproduces today's behavior
+# BYTE-FOR-BYTE: every phase inherits the default model, no `--model` flag is added.
+# UNCOMMENT an entry to activate routing for that phase-type — that first uncomment
+# is your moment to confirm it does what you expect (nothing chooses for you; the map
+# is yours and only you edit it — no code ever writes it). A routed launch that fails
+# at startup falls back once to the default and records `routed → fallback` in the
+# usage receipt, so a bad value degrades loudly, never silently.
+#
+# Suggested starting point (uncomment the lines you want):
 model_by_phase_type:
-  researching: sonnet
-  discussing: sonnet
-  architecting: opus
-  planning: opus
-  executing: sonnet
-  verifying: haiku
-  reviewing: sonnet
+  # researching: sonnet
+  # discussing: sonnet
+  # architecting: opus
+  # planning: opus
+  # executing: sonnet
+  # verifying: haiku
+  # reviewing: sonnet