@giamme/forge 0.0.0-stage → 0.9.0

package/scripts/forge-memory.sh

@@ -0,0 +1,575 @@
+#!/usr/bin/env bash
+# forge-memory.sh — project memory that outlives a single forge run.
+#
+# Every forge dispatch is a clean slate, so without this the tenth run in a repo
+# rediscovers what the first one learned. Two files, deliberately split:
+#
+#   .forge/memory.md    curated, hard-capped, injected into every prompt
+#   .forge/ledger.tsv   append-only, one row per dispatch, NEVER injected
+#
+# That split is what makes "remembers everything" and "small" compatible. The
+# ledger is unbounded but costs no context; only memory.md is paid for, on every
+# dispatch of every future run, which is why it has a hard cap.
+#
+# Writing is automatic, so the judgment has to be free and the bookkeeping has to
+# be deterministic: the model that just did the work emits its learning in-band
+# (a FORGE_LEARNING line in its final message, alongside FORGE_VERDICT), and this
+# script does dedup, recurrence counting, staleness and capping in bash. No model
+# ever decides what to prune.
+#
+# Usage:
+#   forge-memory.sh inject <repo> <planner|dwarf|qa>
+#   forge-memory.sh note   <planner|dwarf|qa>
+#   forge-memory.sh record <repo> --last <file> --role <r> [--run-id X] [--task T]
+#                                 [--model M] [--verdict V] [--duration S]
+#   forge-memory.sh show   <repo>
+#   forge-memory.sh prune  <repo>
+#   forge-memory.sh spend  <repo> [--run <run-id>]
+#
+# Exit codes: 0 ok | 2 usage error
+set -uo pipefail
+
+# Where to log the Jev calls this script makes. Empty means nowhere, which is what it
+# meant everywhere until a real run showed 51 logged calls and an unknown number of
+# unlogged memory ones sitting beside them.
+JEV_RUN_DIR=""
+
+die()  { printf 'forge: %s\n' "$1" >&2; exit "${2:-2}"; }
+
+MAX_LINES="${FORGE_MEMORY_MAX_LINES:-40}"
+MAX_BYTES="${FORGE_MEMORY_MAX_BYTES:-4096}"
+TAB="$(printf '\t')"
+
+# Derived here rather than inherited: forge-parallel.sh sets SKILL_DIR but does not
+# export it, and this script is also run directly. Getting it wrong would leave the Jev
+# curation below silently disabled instead of visibly broken.
+SKILL_DIR="${SKILL_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+
+# Writing files into someone's repo automatically needs an escape hatch that does
+# not require editing the skill.
+memory_off() { [ "${FORGE_MEMORY:-on}" = "off" ]; }
+
+# --- run dataset ----------------------------------------------------------------
+# What curation decided, for the run dataset (scripts/forge_dataset): the final ledger
+# rows say what was kept, but not that Jev refiled a category, merged a paraphrase or
+# muted a fact, nor which facts a rebuild dropped and why. Fail-open and silent.
+MEMORY_DROPS=""   # when set, rebuild appends "<reason>\t<category>\t<text>" rows here
+memory_dataset_on() {
+  case "${FORGE_DATASET:-on}" in off|OFF|Off|0|no|false) return 1 ;; esac
+  return 0
+}
+memory_dataset_event() { # memory_dataset_event <name> <repo> <run-dir> [--set k=v | --file label=path]...
+  local name="$1" repo="$2" dir="$3"; shift 3
+  memory_dataset_on || return 0
+  python3 "$SKILL_DIR/scripts/forge-dataset.py" event "$name" --repo "$repo" ${dir:+--dir "$dir"} "$@" \
+    >/dev/null 2>&1 || true
+}
+
+dir_for()    { echo "$1/.forge"; }
+memory_for() { echo "$1/.forge/memory.md"; }
+ledger_for() { echo "$1/.forge/ledger.tsv"; }
+
+# Normalized dedup key: lowercase, every run of non-alphanumerics collapsed to a
+# single space. Exact match after that — genuinely different phrasings will NOT
+# merge. That is mitigated by a feedback loop rather than by clever matching:
+# memory is in the prompt, so a reviewer that has seen "2x: route added without
+# updating openapi.yaml" tends to re-emit that phrasing instead of inventing one.
+norm_key() {
+  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' \
+    | sed 's/[^a-z0-9]\{1,\}/ /g; s/^ //; s/ $//'
+}
+
+# A trailing [path] is what makes an entry's staleness detectable later.
+anchor_of() {
+  printf '%s' "$1" | sed -n 's/.*\[\([^][]\{1,\}\)\][[:space:]]*$/\1/p'
+}
+strip_anchor() {
+  printf '%s' "$1" | sed 's/[[:space:]]*\[[^][]\{1,\}\][[:space:]]*$//'
+}
+
+# Tabs are the ledger's field separator and newlines are its record separator, so
+# neither may survive into a field.
+sanitize() { printf '%s' "$1" | tr '\t\n' '  ' | sed 's/  \{1,\}/ /g; s/^ //; s/ $//'; }
+
+# One discursive model should not be able to spend the whole byte budget on a
+# single entry. Truncate the prose but keep the [anchor], since that is what lets
+# the entry be recognised as stale later.
+MAX_FACT_CHARS="${FORGE_MEMORY_MAX_FACT_CHARS:-180}"
+clamp_fact() {
+  local text="$1" anchor body
+  [ "${#text}" -le "$MAX_FACT_CHARS" ] && { printf '%s' "$text"; return; }
+  anchor="$(anchor_of "$text")"
+  body="$(strip_anchor "$text")"
+  local room="$MAX_FACT_CHARS"
+  [ -n "$anchor" ] && room=$((MAX_FACT_CHARS - ${#anchor} - 3))
+  [ "$room" -lt 40 ] && room=40
+  body="$(printf '%s' "$body" | cut -c1-"$room" | sed 's/[^ ]*$//; s/ $//')"
+  if [ -n "$anchor" ]; then printf '%s… [%s]' "$body" "$anchor"; else printf '%s…' "$body"; fi
+}
+
+section_title() {
+  case "$1" in
+    verify)  echo "## Verify" ;;
+    trap)    echo "## Known traps" ;;
+    finding) echo "## Recurring QA findings" ;;
+  esac
+}
+
+# --- rebuild ------------------------------------------------------------------
+# memory.md is regenerated from the whole ledger rather than mutated in place.
+# Rebuilding is idempotent and order-independent, so a crashed or concurrent run
+# cannot leave memory half-updated — it can only leave the ledger short a row.
+rebuild() { # rebuild <repo> -> prints "kept<TAB>pruned_stale<TAB>pruned_cap"
+  local repo="$1" led mem tmp cand jev_loaded=0
+  if [ "${FORGE_MEMORY_DEEP_PRUNE:-0}" = 1 ] && [ -f "$SKILL_DIR/scripts/forge-jev-options.sh" ]; then
+    source "$SKILL_DIR/scripts/forge-jev-options.sh" 2>/dev/null && jev_loaded=1
+  fi
+  led="$(ledger_for "$repo")"; mem="$(memory_for "$repo")"
+  [ -f "$led" ] || return 0
+  tmp="$mem.tmp.$$"; cand="$mem.cand.$$"
+
+  # Group by (category, key). count = number of DISTINCT runs the key appeared in,
+  # which is what makes a recurrence threshold meaningful: one run emitting the
+  # same learning twice is still one occurrence.
+  awk -F'\t' '
+    /^#/ || NF < 9 { next }
+    # Column 11 is the injectable flag. Rows written before it existed have NF == 10
+    # and are treated as injectable, so an existing ledger keeps behaving as it did.
+    NF >= 11 && $11 == "0" { next }
+    {
+      ts=$1; run=$2; cat=$7; key=$8; txt=$9
+      k = cat "\034" key
+      if (!((k "\034" run) in seen_run)) { seen_run[k "\034" run]=1; cnt[k]++ }
+      if (ts >= lastts[k]) { lastts[k]=ts; last[k]=txt }
+      catof[k]=cat
+    }
+    END { for (k in cnt) printf "%s\t%d\t%s\t%s\n", catof[k], cnt[k], lastts[k], last[k] }
+  ' "$led" > "$cand" 2>/dev/null
+
+  local kept=0 stale=0 capped=0
+  : > "$tmp"
+  local sec cat count ts text anchor line
+  for sec in verify trap finding; do
+    local body="$mem.sec.$$"; : > "$body"
+    # Highest count first, then most recent — the ordering a human scans for a
+    # systemic problem, and deterministic so tests can assert on it.
+    while IFS=$'\t' read -r cat count ts text; do
+      [ "$cat" = "$sec" ] || continue
+      # A finding seen once is an incident, not a pattern. Promoting it would fill
+      # memory with one-offs, which is exactly how this becomes a junk drawer.
+      if [ "$sec" = finding ] && [ "$count" -lt 2 ]; then continue; fi
+      anchor="$(anchor_of "$text")"
+      # An entry anchored to a path that no longer exists is stale by construction:
+      # the code it describes is gone, so the fact is at best useless and at worst
+      # actively misleading. Drop it rather than wait for the cap to evict it.
+      if [ -n "$anchor" ] && [ ! -e "$repo/$anchor" ]; then
+        [ -z "$MEMORY_DROPS" ] || printf 'anchor_missing\t%s\t%s\n' "$cat" "$text" >> "$MEMORY_DROPS"
+        stale=$((stale+1)); continue
+      fi
+      # The anchor still exists, but the fact about it may have quietly stopped being
+      # true. Only on an explicit `prune`: rebuild runs after EVERY dispatch, and a
+      # request per entry per dispatch would be the most expensive thing in a run.
+      # An unreachable or undecided answer keeps the entry -- dropping a fact on a
+      # failed request would erode memory over time with nothing recording why.
+      if [ "${FORGE_MEMORY_DEEP_PRUNE:-0}" = 1 ] && [ -n "$anchor" ] \
+         && [ "$jev_loaded" = 1 ] && forge_jev_active memory; then
+        if python3 "$SKILL_DIR/scripts/forge-jev.py" memory-stale \
+             --text "$text" --anchor "$repo/$anchor" \
+             ${JEV_RUN_DIR:+--run-dir "$JEV_RUN_DIR"} >/dev/null 2>&1; then
+          [ -z "$MEMORY_DROPS" ] || printf 'jev_stale\t%s\t%s\n' "$cat" "$text" >> "$MEMORY_DROPS"
+          stale=$((stale+1)); continue
+        fi
+      fi
+      if [ "$sec" = finding ]; then
+        printf '%s\t- %sx: %s\n' "$count" "$count" "$text" >> "$body"
+      else
+        printf '%s\t- %s\n' "$count" "$text" >> "$body"
+      fi
+    done < <(sort -t"$TAB" -k2,2nr -k3,3r "$cand")
+
+    if [ -s "$body" ]; then
+      { section_title "$sec"; cut -f2- "$body"; echo; } >> "$tmp"
+      kept=$((kept + $(wc -l < "$body" | tr -d ' ')))
+    fi
+    rm -f "$body"
+  done
+  rm -f "$cand"
+
+  if [ ! -s "$tmp" ]; then rm -f "$tmp" "$mem"; printf '0\t%s\t0\n' "$stale"; return 0; fi
+
+  local header="$mem.hdr.$$"
+  {
+    echo "# forge project memory"
+    echo "<!-- Maintained by forge from what its own runs observed. Do not edit this file"
+    echo "     inside a dwarf run: it is excluded from every diff and your edit would be"
+    echo "     overwritten. Facts only, one per line. -->"
+    echo
+    cat "$tmp"
+  } > "$header"
+
+  # Cap enforcement. Everything above already dropped stale entries and unpromoted
+  # findings, so what is left is real; trimming happens from the bottom, which the
+  # sort above has arranged to be the lowest-count, least-recent facts.
+  while [ "$(wc -l < "$header" | tr -d ' ')" -gt "$MAX_LINES" ] || \
+        [ "$(wc -c < "$header" | tr -d ' ')" -gt "$MAX_BYTES" ]; do
+    local last_fact
+    last_fact="$(grep -n '^- ' "$header" | tail -1 | cut -d: -f1)"
+    [ -n "$last_fact" ] || break
+    [ -z "$MEMORY_DROPS" ] || printf 'cap\t-\t%s\n' "$(sed -n "${last_fact}p" "$header")" >> "$MEMORY_DROPS"
+    sed "${last_fact}d" "$header" > "$header.x" && mv "$header.x" "$header"
+    capped=$((capped+1)); kept=$((kept-1))
+  done
+  # The cap can eat a section's last fact, leaving a heading over nothing.
+  drop_empty_sections "$header"
+
+  mkdir -p "$(dir_for "$repo")"
+  mv "$header" "$mem"
+  rm -f "$tmp"
+  printf '%s\t%s\t%s\n' "$kept" "$stale" "$capped"
+}
+
+# Remove a "## Section" line that has no "- " fact under it, which the cap can
+# produce by trimming a section's last entry.
+drop_empty_sections() {
+  local f="$1" out="$1.de.$$"
+  awk '
+    { l[NR] = $0 }
+    END {
+      for (i = 1; i <= NR; i++) {
+        if (l[i] ~ /^## /) {
+          keep = 0
+          for (j = i + 1; j <= NR && l[j] !~ /^## /; j++)
+            if (l[j] ~ /^- /) { keep = 1; break }
+          if (!keep) continue
+        }
+        print l[i]
+      }
+    }
+  ' "$f" > "$out"
+  # Collapse any run of blank lines to a single one.
+  awk '{ if ($0 == "") blank++; else blank = 0; if (blank < 2) print }' "$out" > "$f"
+  rm -f "$out"
+}
+
+# --- inject -------------------------------------------------------------------
+# Slices differ by role because every injected line is paid for on every dispatch:
+# QA is not building anything, so the build command is dead weight in its prompt.
+do_inject() {
+  local repo="${1:?inject needs a repo}" role="${2:?inject needs a role}"
+  shift 2 2>/dev/null || true
+  local TASKFILE=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --task) TASKFILE="${2:-}"; shift 2 ;;
+      --run-dir) JEV_RUN_DIR="${2:-}"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  memory_off && return 0
+  local mem; mem="$(memory_for "$repo")"
+  [ -s "$mem" ] || return 0
+
+  local want
+  case "$role" in
+    planner|dwarf) want="Verify|Known traps|Recurring QA findings" ;;
+    qa)            want="Known traps|Recurring QA findings" ;;
+    *) die "inject: unknown role '$role' (planner|dwarf|qa)" ;;
+  esac
+
+  local body; body="$(awk -v want="$want" '
+    /^## / { keep = 0; t=$0; sub(/^## /,"",t)
+             n=split(want,w,"|"); for (i=1;i<=n;i++) if (w[i]==t) keep=1
+             if (keep) { print ""; print $0 } ; next }
+    /^# |^<!--|^     / { next }
+    keep && NF { print }
+  ' "$mem")"
+  [ -n "$(printf '%s' "$body" | tr -d '[:space:]')" ] || return 0
+
+  # Narrow to the facts that bear on THIS task. The role slice and the 40-line/4KB cap
+  # above remain the outer bound; this only removes lines, never adds or reorders them,
+  # and any failure leaves `body` exactly as it was. Every line here is paid for on
+  # every dispatch of every run, which is what makes narrowing worth a request -- and
+  # also why the fallback has to be the full slice rather than an empty one.
+  if [ -n "$TASKFILE" ] && [ -r "$TASKFILE" ]; then
+    local jev_loaded=0
+    if [ -f "$SKILL_DIR/scripts/forge-jev-options.sh" ]; then
+      source "$SKILL_DIR/scripts/forge-jev-options.sh" 2>/dev/null && jev_loaded=1
+    fi
+    if [ "$jev_loaded" = 1 ] && forge_jev_active memory; then
+      local facts sliced
+      facts="$(printf '%s\n' "$body" | grep '^- ' || true)"
+      if [ -n "$facts" ]; then
+        local ftmp="${TMPDIR:-/tmp}/forge-mem-$$.txt"
+        printf '%s\n' "$facts" > "$ftmp"
+        local ktmp="${TMPDIR:-/tmp}/forge-mem-keep-$$.txt"
+        if python3 "$SKILL_DIR/scripts/forge-jev.py" memory-slice \
+             --task "$TASKFILE" --lines "$ftmp" \
+             ${JEV_RUN_DIR:+--run-dir "$JEV_RUN_DIR"} > "$ktmp" 2>/dev/null && [ -s "$ktmp" ]; then
+          # Two files, not -v: awk's -v processes escapes and cannot carry a literal
+          # newline, so passing the kept lines that way silently truncated the set at the
+          # first one. Read them as a first file instead.
+          sliced="$(printf '%s\n' "$body" | awk '
+            NR == FNR { want[$0] = 1; next }
+            /^## / { header = $0; printed = 0; next }
+            /^- / { if ($0 in want) { if (!printed) { print ""; print header; printed = 1 } print $0 } next }
+            { print }
+          ' "$ktmp" -)"
+          # Only adopt a narrowed body that actually kept something. An awk that fails,
+          # or a slice that matched nothing, must leave the full slice in place -- an
+          # empty memory section is a worse outcome than an unnarrowed one.
+          if [ -n "$(printf '%s' "$sliced" | grep -c '^- ' | tr -d ' ')" ] \
+             && printf '%s' "$sliced" | grep -q '^- '; then
+            body="$sliced"
+          fi
+        fi
+        rm -f "$ftmp" "$ktmp" 2>/dev/null || true
+      fi
+    fi
+  fi
+
+  echo "## What forge learned in this repo before"
+  if [ "$role" = qa ]; then
+    echo "From earlier forge runs on this project. Use it to notice a repeat bug and to"
+    echo "avoid reporting a known-generated file as a defect — it is context, not a checklist."
+  else
+    echo "From earlier forge runs on this project. Treat it as known-good context so you do"
+    echo "not rediscover it; if something here is now wrong, say so in your final message."
+  fi
+  printf '%s\n' "$body"
+}
+
+# --- note ---------------------------------------------------------------------
+# The instruction that makes automatic memory possible at all. It asks for the
+# learning in the same breath as the work, from the model that just did it — so
+# extraction costs no extra dispatch and no separate model has to guess what
+# mattered. Deliberately asks for nothing when nothing generalizes: a role that
+# invents a learning to be helpful is precisely how this fills up with noise.
+do_note() {
+  local role="${1:?note needs a role}"
+  memory_off && return 0
+  echo "## Before you finish"
+  echo "If — and only if — you learned something about THIS repository that would still be"
+  if [ "$role" = qa ]; then
+    # The reviewer's verdict line must stay the very last line of the reply, so a learning
+    # goes just above it; asking for "the very end" produced replies the parser rejected.
+    echo "true and useful on an unrelated task next month, add a line for it just above your"
+    echo "final FORGE_VERDICT line (the verdict stays the last line of your reply):"
+  else
+    echo "true and useful on an unrelated task next month, add a line for it at the very end:"
+  fi
+  echo
+  echo "  FORGE_LEARNING: verify | <the command that actually builds or tests this project>"
+  echo "  FORGE_LEARNING: trap | <a landmine: a flaky test, a generated file, a sharp edge>"
+  if [ "$role" = qa ]; then
+    echo "  FORGE_LEARNING: finding | <a mistake pattern likely to recur, not this one bug>"
+  fi
+  echo
+  echo "End the text with [path/that/anchors/it] where a path makes sense; forge drops an"
+  echo "entry whose path stops existing, which is how this file stays true as code moves."
+  echo "One short line each, phrased as a fact. Reuse the exact wording of anything already"
+  echo "listed above rather than rephrasing it, so repeats are recognised as repeats."
+  echo "Most runs teach nothing durable. Emitting no line is the normal, correct outcome."
+}
+
+# --- record -------------------------------------------------------------------
+do_record() {
+  local repo="${1:?record needs a repo}"; shift
+  local LAST="" ROLE="" RUN_ID="-" TASK="-" MODEL="-" VERDICT="-" DURATION="-"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --last)    LAST="${2:?--last needs a value}"; shift 2 ;;
+      --role)    ROLE="${2:?--role needs a value}"; shift 2 ;;
+      --run-id)  RUN_ID="${2:?--run-id needs a value}"; shift 2 ;;
+      --task)    TASK="${2:?--task needs a value}"; shift 2 ;;
+      --run-dir) JEV_RUN_DIR="${2:?--run-dir needs a value}"; shift 2 ;;
+      --model)   MODEL="${2:?--model needs a value}"; shift 2 ;;
+      --verdict) VERDICT="${2:?--verdict needs a value}"; shift 2 ;;
+      --duration) DURATION="${2:?--duration needs a value}"; shift 2 ;;
+      *) die "record: unknown option '$1'" ;;
+    esac
+  done
+  memory_off && return 0
+  [ -n "$ROLE" ] || die "record needs --role"
+  [ -d "$repo" ] || die "record: '$repo' is not a directory"
+
+  local led ts n=0
+  led="$(ledger_for "$repo")"
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  mkdir -p "$(dir_for "$repo")"
+  if [ ! -f "$led" ]; then
+    printf '# ts\trun_id\ttask\trole\tmodel\tverdict\tcategory\tkey\ttext\tduration_s\tinjectable\n' > "$led"
+  fi
+
+  local jev_loaded=0 cur=""
+  if [ -f "$SKILL_DIR/scripts/forge-jev-options.sh" ]; then
+    source "$SKILL_DIR/scripts/forge-jev-options.sh" 2>/dev/null && jev_loaded=1
+  fi
+  # Scratch files for the dataset event, outside the repo: .forge/ is the user's tree.
+  if memory_dataset_on; then
+    cur="$(mktemp "${TMPDIR:-/tmp}/forge-memory-cur.XXXXXX" 2>/dev/null)" || cur=""
+    MEMORY_DROPS="$(mktemp "${TMPDIR:-/tmp}/forge-memory-drops.XXXXXX" 2>/dev/null)" || MEMORY_DROPS=""
+  fi
+  if [ -n "$LAST" ] && [ -r "$LAST" ]; then
+    local line cat text key inject curated curated_rc jcat jinject jmatch jkey ecat
+    while IFS= read -r line; do
+      cat="$(printf '%s' "$line" | sed -n 's/^[[:space:]]*FORGE_LEARNING:[[:space:]]*\([a-zA-Z]\{1,\}\)[[:space:]]*|.*/\1/p' | tr '[:upper:]' '[:lower:]')"
+      text="$(printf '%s' "$line" | sed -n 's/^[[:space:]]*FORGE_LEARNING:[[:space:]]*[a-zA-Z]\{1,\}[[:space:]]*|[[:space:]]*\(.*\)/\1/p')"
+      case "$cat" in verify|trap|finding) ;; *) continue ;; esac
+      text="$(clamp_fact "$(sanitize "$text")")"
+      [ -n "$text" ] || continue
+      key="$(norm_key "$(strip_anchor "$text")")"
+      [ -n "$key" ] || continue
+      # Jev may refile the category, merge a paraphrase onto an existing key, and mark
+      # a one-off as not worth injecting. Every one of those is a suggestion: any
+      # failure, any missing key, any disabled capability leaves the three values below
+      # exactly as the model emitted them. The row is written either way -- the ledger
+      # is append-only and never injected, so this gates injection, never recording.
+      inject=1; ecat="$cat"; jcat=""; jinject=""; jmatch=""
+      if [ "$jev_loaded" = 1 ] && forge_jev_active memory; then
+        curated="$(python3 "$SKILL_DIR/scripts/forge-jev.py" memory-curate \
+            --repo "$repo" --category "$cat" --text "$text" \
+            ${JEV_RUN_DIR:+--run-dir "$JEV_RUN_DIR"} 2>/dev/null)"
+        curated_rc=$?
+        if [ "$curated_rc" -eq 0 ] && [ -n "$curated" ]; then
+          jcat="$(printf '%s' "$curated" | cut -f1)"
+          jinject="$(printf '%s' "$curated" | cut -f2)"
+          jmatch="$(printf '%s' "$curated" | cut -f3)"
+          case "$jcat" in verify|trap|finding) cat="$jcat" ;; esac
+          [ "$jinject" = 0 ] && inject=0
+          if [ -n "$jmatch" ]; then
+            # Re-derive the key with THIS file's norm_key rather than having Python
+            # return one: two implementations of the same normalisation would drift,
+            # and a key that disagrees by one character silently stops deduplicating.
+            # The leading "Nx: " is rebuild's recurrence marker, not part of the fact.
+            jmatch="$(printf '%s' "$jmatch" | sed 's/^[0-9]\{1,\}x: //')"
+            jkey="$(norm_key "$(strip_anchor "$jmatch")")"
+            [ -n "$jkey" ] && key="$jkey"
+          fi
+        fi
+      fi
+      printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+        "$ts" "$(sanitize "$RUN_ID")" "$(sanitize "$TASK")" "$(sanitize "$ROLE")" \
+        "$(sanitize "$MODEL")" "$(sanitize "$VERDICT")" "$cat" "$key" "$text" \
+        "$(sanitize "$DURATION")" "$inject" >> "$led"
+      [ -z "$cur" ] || printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$ecat" "$cat" "$key" "$inject" \
+        "$jcat" "$jinject" "$jmatch" "$text" >> "$cur"
+      n=$((n+1))
+    done < <(grep -o 'FORGE_LEARNING:.*' "$LAST" 2>/dev/null)
+  fi
+
+  # A dispatch that emitted no learning is still worth a ledger row: it is how the
+  # ledger can later answer "which model has worked on this repo, and how did it do".
+  if [ "$n" -eq 0 ]; then
+    printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+      "$ts" "$(sanitize "$RUN_ID")" "$(sanitize "$TASK")" "$(sanitize "$ROLE")" \
+      "$(sanitize "$MODEL")" "$(sanitize "$VERDICT")" "-" "-" "-" \
+      "$(sanitize "$DURATION")" >> "$led"
+  fi
+
+  local out kept stale capped
+  out="$(rebuild "$repo")"
+  kept="$(printf '%s' "$out" | cut -f1)"; stale="$(printf '%s' "$out" | cut -f2)"
+  capped="$(printf '%s' "$out" | cut -f3)"
+  memory_dataset_event memory_record "$repo" "$JEV_RUN_DIR" --set role="$ROLE" --set run_id="$RUN_ID" \
+    --set task="$TASK" --set model="$MODEL" --set verdict="$VERDICT" --set recorded="$n" \
+    --set kept="${kept:-0}" --set stale="${stale:-0}" --set capped="${capped:-0}" \
+    --set max_lines="$MAX_LINES" --set max_bytes="$MAX_BYTES" \
+    ${cur:+--file curation="$cur"} ${MEMORY_DROPS:+--file drops="$MEMORY_DROPS"} --file memory="$(memory_for "$repo")"
+  rm -f ${cur:+"$cur"} ${MEMORY_DROPS:+"$MEMORY_DROPS"}
+  printf 'memory: %s learning(s) recorded, %s fact(s) live' "$n" "${kept:-0}"
+  [ "${stale:-0}" -gt 0 ] 2>/dev/null && printf ', %s stale dropped' "$stale"
+  [ "${capped:-0}" -gt 0 ] 2>/dev/null && printf ', %s trimmed at cap' "$capped"
+  printf '\n'
+}
+
+# --- prune --------------------------------------------------------------------
+do_prune() { # do_prune <repo>
+  local repo="$1" out
+  if memory_dataset_on; then
+    MEMORY_DROPS="$(mktemp "${TMPDIR:-/tmp}/forge-memory-drops.XXXXXX" 2>/dev/null)" || MEMORY_DROPS=""
+  fi
+  out="$(FORGE_MEMORY_DEEP_PRUNE=1 rebuild "$repo")"
+  memory_dataset_event memory_prune "$repo" "" --set kept="$(printf '%s' "$out" | cut -f1)" \
+    --set stale="$(printf '%s' "$out" | cut -f2)" --set capped="$(printf '%s' "$out" | cut -f3)" \
+    ${MEMORY_DROPS:+--file drops="$MEMORY_DROPS"} --file memory="$(memory_for "$repo")"
+  rm -f ${MEMORY_DROPS:+"$MEMORY_DROPS"}
+}
+
+# --- spend --------------------------------------------------------------------
+# The ledger already carries one row per dispatch, and it is never injected into a
+# prompt, so accounting from it costs nothing at all. Time and dispatch counts
+# only: token accounting is exposed differently (or not at all) by the five CLIs,
+# and a number forge cannot actually measure would be worse than no number.
+do_spend() {
+  local repo="${1:?spend needs a repo}"; shift
+  local ONLY_RUN=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --run) ONLY_RUN="${2:?--run needs a value}"; shift 2 ;;
+      *) die "spend: unknown option '$1'" ;;
+    esac
+  done
+  local led; led="$(ledger_for "$repo")"
+  [ -s "$led" ] || { echo "no ledger in $repo/.forge — nothing dispatched here yet"; return 0; }
+
+  awk -F'\t' -v only="$ONLY_RUN" '
+    function hms(x,   h,m,s) {
+      if (x == "") return "     -"
+      h=int(x/3600); m=int((x%3600)/60); s=x%60
+      if (h>0) return sprintf("%dh%02dm", h, m)
+      if (m>0) return sprintf("%dm%02ds", m, s)
+      return sprintf("%ds", s)
+    }
+    /^#/ || NF < 9 { next }
+    {
+      ts=$1; run=$2; task=$3; role=$4; model=$5
+      dur = (NF >= 10 ? $10 : "-")
+      if (only != "" && run != only) next
+      # One dispatch emitting two learnings writes two rows. Every row from one
+      # dispatch shares its timestamp, so this counts dispatches, not lines.
+      k = ts "\034" run "\034" task "\034" role
+      if (!(k in seen)) {
+        seen[k] = 1; n[model]++; rn[role]++; total++; runs[run] = 1
+      }
+      # Count the dispatch once, but take its duration from whichever of its rows
+      # carries one — a dispatch that straddles the schema change has both kinds.
+      if (dur ~ /^[0-9]+$/ && !(k in durof)) {
+        durof[k] = dur
+        t[model] += dur; timed[model]++
+        rt[role] += dur
+        tt += dur; ttn++
+      }
+    }
+    END {
+      if (total == 0) { print "no dispatches recorded" ; exit }
+      nruns = 0; for (r in runs) nruns++
+      printf "%d dispatch(es) across %d run(s), %s of model time\n", total, nruns, hms(tt)
+      if (ttn < total)
+        printf "(%d dispatch(es) predate duration recording and are counted but not timed)\n", total - ttn
+      print "Durations sum concurrent work, so they exceed the wall-clock of a parallel run."
+      print ""
+      printf "  %-26s %6s %9s %9s\n", "by model", "disp", "total", "mean"
+      for (m in n)
+        printf "  %-26s %6d %9s %9s\n", m, n[m], hms(t[m]), \
+               (timed[m] > 0 ? hms(int(t[m]/timed[m])) : "     -")
+      print ""
+      printf "  %-26s %6s %9s\n", "by role", "disp", "total"
+      for (r in rn)
+        printf "  %-26s %6d %9s\n", r, rn[r], hms(rt[r])
+    }
+  ' "$led"
+}
+
+# --- main ---------------------------------------------------------------------
+[ $# -ge 1 ] || die "usage: forge-memory.sh <inject|note|record|show|prune|spend> [repo] [...]"
+CMD="$1"; shift
+case "$CMD" in
+  inject) do_inject "$@" ;;
+  note)   do_note "$@" ;;
+  record) do_record "$@" ;;
+  show)   mem="$(memory_for "${1:?show needs a repo}")"; [ -s "$mem" ] && cat "$mem" ;;
+  spend)  do_spend "$@" ;;
+  prune)  do_prune "${1:?prune needs a repo}" >/dev/null
+          do_inject "${1}" dwarf ;;
+  *) die "unknown subcommand '$CMD'" ;;
+esac

package/scripts/forge-metrics.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Each runner owns its metric state in a process/subshell, including failure exits.
+forge_metric_begin() {
+  FORGE_METRIC_ROOT="$1"; FORGE_METRIC_ROLE="$2"
+  FORGE_METRIC="$(python3 "$SKILL_DIR/scripts/forge-runtime.py" begin "$1" "$2")" || return 3
+  # Dispatches started from here name this execution as their parent in the run dataset.
+  export FORGE_DATASET_PARENT="${FORGE_METRIC##*/}"
+  # The hook, when the caller defines it, records status before finish and Fractal's _outcome.
+  trap 'metric_rc=$?; ! declare -F forge_metric_on_exit >/dev/null || forge_metric_on_exit "$metric_rc"; python3 "$SKILL_DIR/scripts/forge-runtime.py" finish "$FORGE_METRIC" "$FORGE_METRIC_ROOT" "$FORGE_METRIC_ROLE" pipeline "$metric_rc"; if [ -n "${FORGE_FRACTAL_RUN:-}" ]; then python3 "$SKILL_DIR/scripts/forge-fractal.py" _outcome "$FORGE_METRIC_ROOT" "$metric_rc"; fi; exit "$metric_rc"' EXIT
+}
+forge_metric_phase() {
+  python3 "$SKILL_DIR/scripts/forge-runtime.py" phase "$FORGE_METRIC" "$1"
+}
+
+# --- run dataset (scripts/forge_dataset) --------------------------------------------
+# Facts that are gone before any EXIT trap could read them: an aborted merge, a combine
+# that rolled back, a branch that moved. Fail-open and silent, like every capture.
+forge_dataset_off() {
+  case "${FORGE_DATASET:-on}" in off|OFF|Off|0|no|false) return 0 ;; esac
+  return 1
+}
+forge_dataset_event() { # forge_dataset_event <name> --dir <dir> [--task id] [--set k=v]... [--file label=path]...
+  forge_dataset_off && return 0
+  python3 "$SKILL_DIR/scripts/forge-dataset.py" event "$@" >/dev/null 2>&1 || true
+}
+forge_dataset_invocation() { # forge_dataset_invocation <command> <rc> <started> [argv...]
+  forge_dataset_off && return 0
+  local command="$1" rc="$2" started="$3"; shift 3
+  # Options before the command name: everything after it is the subcommand's own argv.
+  python3 "$SKILL_DIR/scripts/forge-dataset.py" invocation --dir "${1:-}" --rc "$rc" \
+    --started "$started" --pid "$$" "$command" -- "$@" >/dev/null 2>&1 || true
+}
+
+# --- update notice (scripts/forge-version.py) ----------------------------------------
+# One line on stderr when a newer forge release exists, checked at most once a day. Silent
+# offline, in CI and with FORGE_UPDATE_CHECK=off; it never changes a run's exit code.
+forge_update_notice() {
+  python3 "$SKILL_DIR/scripts/forge-version.py" notice --source "$SKILL_DIR" </dev/null >&2 2>/dev/null || true
+}