forge-orkes 0.64.5 → 0.68.1

package/bin/create-forge.js

@@ -52,31 +52,22 @@ const FORGE_END = '<!-- forge:end -->';
 
 // --- File classification for upgrades ---
 
-// Framework-owned: Forge controls these entirely
+// Framework-owned: Forge controls these entirely. Auto-clean removes files that
+// dropped out of the template — but ownership is decided per top-level UNIT
+// (a skill DIR under .claude/skills/, an agent FILE under .claude/agents/), and
+// only the template defines which units Forge shipped. A unit the base template
+// never shipped — user-authored, vendored-parity, or an opt-in experimental
+// skill installed separately (e.g. m10's orchestrating, the convention packs) —
+// is NOT framework content and is preserved, never swept, even though it lives
+// under a framework-owned dir. Deleting it would destroy work Forge never owned,
+// and .claude/ is frequently gitignored, so the loss is unrecoverable. Files
+// removed from WITHIN a still-shipped unit (e.g. a renamed helper inside a
+// template skill dir) stay cleanable — their unit is still present in the
+// template. See upgradeDir(). Experimental skills are additionally diffed
+// against their shipped sources by detectExperimentalStaleness() (report-only;
+// re-sync consent lives in the /upgrading skill layer).
 const FRAMEWORK_OWNED_DIRS = ['.claude/agents', '.claude/skills'];
 
-// Experimental / opt-in skills installed separately (e.g. from experimental/m10).
-// They are NOT in the shipped base template, so the framework-owned auto-clean
-// would otherwise delete them on upgrade. Preserve them instead.
-//
-// The npm tarball ships experimental/ alongside bin/ + template/, so this route
-// CAN diff an installed experimental skill against its same-tarball source:
-// detectExperimentalStaleness() reports unchanged|stale with the differing files.
-// (Blind preservation is what silently froze these pre-0.33.0 — issue #5: a base
-// migration that changed experimental-skill behavior became a no-op.) Detection
-// only — consent for a re-sync lives in the /upgrading skill layer, and
-// load-bearing conventions are still promoted to base (FORGE.md) rather than
-// left to a frozen skill. This preserve-list gates auto-clean only; staleness
-// discovery is by directory scan of the shipped experimental/ tree.
-const EXPERIMENTAL_SKILL_PATHS = ['.claude/skills/orchestrating'];
-
-function isExperimentalSkillPath(displayPath) {
-  const norm = displayPath.split(path.sep).join('/');
-  return EXPERIMENTAL_SKILL_PATHS.some(
-    (p) => norm === p || norm.startsWith(p + '/')
-  );
-}
-
 // Compare dotted numeric versions (e.g. "0.19.1"). Returns 1 if a>b, -1 if a<b, 0 if equal.
 function compareVersions(a, b) {
   const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
@@ -259,9 +250,15 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
     const srcPath = path.join(srcDir, rel);
     if (!fs.existsSync(srcPath)) {
       const displayPath = path.join(relDir, rel);
-      // Never auto-clean opt-in experimental skills — they live outside the base template.
-      if (autoClean && isExperimentalSkillPath(displayPath)) {
-        result.preserved.push(displayPath);
+      // Ownership is per top-level unit: the first path segment of `rel` is the
+      // skill dir (or, for flat agents, the file itself). If the template no
+      // longer ships that unit at all, the file is user-authored, vendored, or an
+      // opt-in experimental skill — not Forge's to delete. Preserve it. Only
+      // files whose unit the template STILL ships (a stale file inside a shipped
+      // skill dir) remain removal candidates.
+      const topUnit = rel.split(path.sep)[0];
+      if (autoClean && !fs.existsSync(path.join(srcDir, topUnit))) {
+        result.preserved.push(`${displayPath} (kept — not shipped by the base template)`);
         continue;
       }
       const destPath = path.join(destDir, rel);
@@ -374,6 +371,30 @@ function mergeManagedDeny(destSettings, srcSettings) {
   }
 }
 
+/**
+ * Union the template's managed allow rules into the project's permissions.allow.
+ * Additive — a user's own allow/deny entries are untouched (mirrors
+ * mergeManagedDeny). Forge automates a worktree-heavy workflow (streams, the
+ * slice runner, orchestration/human-verified teardown), but the harness auto-mode
+ * classifier soft-denies `git worktree remove` for a worktree the session didn't
+ * create in-session, and a Remote-Control / detached session cannot enter
+ * bypassPermissions after launch. A NARROW allow rule survives auto mode and runs
+ * before the classifier, so the automating session can clean up its own worktrees.
+ * These are read/teardown of Forge-managed worktrees only — `remove` is git-guarded
+ * (refuses on a dirty/untracked tree without --force) and, in the Forge flow, only
+ * ever runs on a merged, human-verified worktree. It never touches commits or
+ * branches — worktree removal drops a checkout, not history.
+ */
+function mergeManagedAllow(destSettings, srcSettings) {
+  const srcAllow = (srcSettings.permissions && srcSettings.permissions.allow) || [];
+  if (!srcAllow.length) return;
+  destSettings.permissions = destSettings.permissions || {};
+  const destAllow = destSettings.permissions.allow || (destSettings.permissions.allow = []);
+  for (const rule of srcAllow) {
+    if (!destAllow.includes(rule)) destAllow.push(rule);
+  }
+}
+
 /**
  * Strip the legacy *inline* active-skill guard from PreToolUse (forge#12). It was
  * an inline `if [ ! -f .../.forge/.active-skill ]; then ... exit 2; fi` one-liner;
@@ -437,6 +458,7 @@ function upgradeSettings() {
   // Additively install framework-managed safety guardrails (ADR-017)
   mergeManagedHooks(destSettings, srcSettings);
   mergeManagedDeny(destSettings, srcSettings);
+  mergeManagedAllow(destSettings, srcSettings);
 
   const after = JSON.stringify(destSettings);
   if (before === after) return 'unchanged';
@@ -949,7 +971,7 @@ async function upgrade() {
     if (results.preserved.length > 0) {
       say(`  Preserved (${results.preserved.length}):`);
       for (const f of results.preserved) {
-        say(`    ${f} (kept — opt-in experimental skill)`);
+        say(`    ${f}`);
       }
       for (const e of experimental) {
         say(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.64.5",
+  "version": "0.68.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/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/settings.json

@@ -1,6 +1,6 @@
 {
   "forge": {
-    "version": "0.58.3",
+    "version": "0.68.0",
     "default_tier": "standard",
     "beads_integration": false,
     "context_gates": {
@@ -48,6 +48,11 @@
       "Edit(**/.secrets/**)",
       "Edit(**/*.pem)",
       "Edit(**/*.key)"
+    ],
+    "allow": [
+      "Bash(git worktree remove *)",
+      "Bash(git worktree prune)",
+      "Bash(git worktree prune *)"
     ]
   },
   "hooks": {

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/.claude/skills/upgrading/SKILL.md

@@ -139,7 +139,7 @@ Source version (`{source}/packages/create-forge/package.json`) **<** installed (
 
 Dev mode syncs from a checkout, so it keeps file-classification semantics — **the npm bin's sync behavior is the spec**; do not re-derive it here. Categories:
 
-- **Framework-owned** (`.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.forge/FORGE.md`) → overwrite when different; a local skill dir absent from the template defers to the experimental pass below (only no-source dirs report *removed from template* — never deleted).
+- **Framework-owned** (`.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.forge/FORGE.md`) → overwrite when different. Ownership is per top-level **unit** — a skill DIR under `.claude/skills/`, a flat agent FILE under `.claude/agents/`: a unit the template doesn't ship (user-authored, vendored-parity, or an opt-in experimental skill) is **preserved, never deleted**; only stale files *inside* a still-shipped skill dir are cleaned. Experimental skills additionally get the staleness pass below.
 - **Template-only** (`.forge/templates/**`, `.forge/migrations/**`, `.forge/adapters/**`, `.forge/gitignore` → `.forge/.gitignore`) → overwrite; `.forge/FORGE.md` lands BEFORE the CLAUDE.md pass.
 - **Additive** (`.claude/hooks/**` incl. `tests/`, `.claude/rules/**`, `.forge/checks/**`) → add + overwrite template-shipped files, never delete local extras, `chmod +x` synced `*.sh`.
 - **Import-managed** `CLAUDE.md` → the bin's `ensureClaudeMdImport()` cases verbatim; user content outside a forge section is never modified.

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

@@ -91,17 +91,25 @@ materialize_work_order() {
   # Prefer the worktree's OWN milestone — .forge/phases/ carries the repo's whole milestone
   # history (32 dirs on the forge repo), so "the only milestone dir" is a fixture-world
   # assumption. The Worktree Convention names the branch forge/{anchor} with anchor =
-  # {milestone-id}[-{session}]; derive the id and pick that milestone's dir.
+  # {milestone-id}[-{session}]; derive the id and pick that milestone's dir. The id's own
+  # m- may be a strippable prefix (m-40 → milestone-40) or PART of a labeled id kept
+  # verbatim (m-EVT01 → milestone-m-EVT01) — canvaz first run 2026-07-22: stripping it
+  # unconditionally missed milestone-m-EVT01 and fell through to a 38-dir refusal. Try the
+  # anchor verbatim before the m--stripped form, then both again minus one trailing
+  # -{session} token; first existing dir wins (exact/longer forms first).
   _mdir=""
   _branch="$(git -C "$WORKTREE" branch --show-current 2>/dev/null)"
   case "$_branch" in
-    forge/m-*)
-      _anchor="${_branch#forge/m-}"                                   # 40 | 40-a1b2c3d4 | R61-002
-      [ -d "$WORKTREE/.forge/phases/milestone-$_anchor" ] && _mdir="$WORKTREE/.forge/phases/milestone-$_anchor"
-      if [ -z "$_mdir" ]; then
-        _short="${_anchor%-*}"                                        # strip one trailing -token (session suffix)
-        [ "$_short" != "$_anchor" ] && [ -d "$WORKTREE/.forge/phases/milestone-$_short" ] && _mdir="$WORKTREE/.forge/phases/milestone-$_short"
-      fi ;;
+    forge/*)
+      _anchor="${_branch#forge/}"                    # m-40 | m-40-a1b2c3d4 | m-EVT01-e6063597
+      _short="${_anchor%-*}"                         # minus one trailing -token (session suffix)
+      for _cand in "$_anchor" "${_anchor#m-}" "$_short" "${_short#m-}"; do
+        [ -n "$_cand" ] || continue
+        if [ -d "$WORKTREE/.forge/phases/milestone-$_cand" ]; then
+          _mdir="$WORKTREE/.forge/phases/milestone-$_cand"
+          break
+        fi
+      done ;;
   esac
   # Fallback (non-git fixture dirs / unconventional branches): a SINGLE milestone dir is
   # unambiguous; several without a branch-derived pick is a refusal, never a guess.

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-dispatch.test.sh

@@ -157,6 +157,41 @@ else
   bad "dry-run side effects" "dry-run wrote work-order files"
 fi
 
+# --- 13-14. BRANCH-DERIVED MILESTONE PICK (canvaz first run 2026-07-22): with several
+#     milestone dirs, the forge/{anchor} branch names the one to build. The id's m- may be
+#     strippable (m-40 → milestone-40) or part of a labeled id (m-EVT01 → milestone-m-EVT01);
+#     unconditional stripping refused a clean labeled-id dispatch. These fixtures are real
+#     git repos — cases 9-12 (mktemp dirs) never reach the branch path.
+mkbranch() { git -C "$1" init -q -b "$2" 2>/dev/null || { git -C "$1" init -q && git -C "$1" checkout -q -b "$2"; }; }
+
+# 13. labeled id: forge/m-EVT01-<session> resolves milestone-m-EVT01 (m- is part of the id)
+LSLICE="$ROOT/labeled-wt"
+mkdir -p "$LSLICE/.forge/phases/milestone-m-EVT01/1-evt" "$LSLICE/.forge/phases/milestone-5/1-decoy"
+printf 'evt plan\n' > "$LSLICE/.forge/phases/milestone-m-EVT01/1-evt/plan-01.md"
+printf 'decoy\n'    > "$LSLICE/.forge/phases/milestone-5/1-decoy/plan-01.md"
+mkbranch "$LSLICE" forge/m-EVT01-e6063597
+err13="$(sh "$DISPATCH" --slice "$LSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && grep -q '^  - 1-evt$' "$LSLICE/slice.yml" 2>/dev/null \
+   && grep -q 'evt plan' "$LSLICE/phases/1-evt/plan.md" 2>/dev/null && [ ! -d "$LSLICE/phases/1-decoy" ]; then
+  ok "labeled milestone id: branch picks milestone-m-EVT01 among several dirs (m- kept)"
+else
+  bad "labeled-id branch pick" "rc=$rc err=$err13"
+fi
+
+# 14. numeric id + session suffix: forge/m-40-<session> still resolves milestone-40 (m- stripped)
+QSLICE="$ROOT/numeric-wt"
+mkdir -p "$QSLICE/.forge/phases/milestone-40/1-num" "$QSLICE/.forge/phases/milestone-39/1-decoy"
+printf 'num plan\n' > "$QSLICE/.forge/phases/milestone-40/1-num/plan-01.md"
+printf 'decoy\n'    > "$QSLICE/.forge/phases/milestone-39/1-decoy/plan-01.md"
+mkbranch "$QSLICE" forge/m-40-a1b2c3d4
+err14="$(sh "$DISPATCH" --slice "$QSLICE" --materialize-only 2>&1)"; rc=$?
+if [ "$rc" = 0 ] && grep -q '^  - 1-num$' "$QSLICE/slice.yml" 2>/dev/null \
+   && grep -q 'num plan' "$QSLICE/phases/1-num/plan.md" 2>/dev/null && [ ! -d "$QSLICE/phases/1-decoy" ]; then
+  ok "numeric milestone id: branch picks milestone-40 among several dirs (m- stripped)"
+else
+  bad "numeric-id branch pick" "rc=$rc err=$err14"
+fi
+
 # --- summary -----------------------------------------------------------------
 printf '\n%s: %d passed, %d failed\n' "$(basename "$0")" "$PASSED" "$FAILED"
 [ "$FAILED" = 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