@oneie/claude 0.7.0 → 0.9.0

package/scripts/factory-walk.sh

@@ -0,0 +1,396 @@
+#!/usr/bin/env bash
+# factory-walk.sh — the factory's deterministic check of ONE piece of work.
+#
+# manifest: needs-env
+#   Names one.ie/web (the previewed app) and reads that app's gitignored .env
+#   through the scripts it composes. Every stage degrades to `unrun`, never to a
+#   pass, when the environment cannot answer.
+#
+# WHAT IT IS. One command whose exit code is the verdict on a task: it walks the
+# work across the lifecycle stages text/factory-do.md § THE WHOLE PATH names —
+# size · isolate · gate · prove · human · substrate — and writes one receipt. It
+# builds NO new gate. Every stage is an existing script, chosen by the tier and
+# the surface, run through the governor and the memo:
+#
+#   size       do-tier.sh            how big is the change; UNSIZED is a FAIL,
+#                                    because absence of recon must never read
+#                                    as simplicity
+#   isolate    worktree-preview.sh   a UI task's tree is a real worktree with
+#                                    local .vite/.astro caches (n/a on main)
+#   gate       verify-fast.sh        the tier's lane, per folder do-folder.sh
+#                                    maps — fast for PATCH/FIX/FEATURE, FULL
+#                                    for SCHEMA or schema/sdk/auth paths; via
+#                                    gate-run.sh (slot), tsc-cached.sh and
+#                                    test-cached.sh (memo). Exit 144 = UNRUN.
+#   prove      do-prove.sh           UI: every route, landing rule, against the
+#              do-walk.sh --agents   task's preview URL. Otherwise the slug's
+#                                    agents walk (text/<slug>-agents.md).
+#   human      the link block        UI only: the preview URL, one stop per
+#                                    route or per text/<slug>-humans.md stop,
+#                                    and the instruction that records the
+#                                    verdict. `--humans` on a tty asks y/n.
+#                                    Until a person answers, PENDING — which
+#                                    is unrun, which is not a pass.
+#   substrate  factory-check.sh      SCHEMA tier only: the ladder is live.
+#
+# THE HONESTY LAW, inherited from do-w4-gates.sh: every stage has FOUR states
+#     pass  : ran, green          fail  : ran, red
+#     unrun : could not run       n/a   : does not apply, by rule
+# and the verdict is `pass` only with ZERO fails AND ZERO unruns. A missing row
+# is treated as unrun and named — an absent row is the fail-open trap in data
+# form. Exit 0 = pass · 1 = a stage failed · 3 = nothing failed but something
+# was not proven (unrun / pending human).
+#
+# THE LANE IS PART OF THE RECEIPT. A fast pass is never reported as a full pass:
+# the receipt and the last line carry `lane:<fast|full|test|none>` beside
+# `verdict:<ok|red|unrun>`, which is exactly the pair the executor writes onto
+# the task with tasks:tag (§ Tests, T4).
+#
+# Usage:
+#   factory-walk.sh <slug> [--files <path>...] [--route </path>]...
+#                   [--preview <url>] [--no-gate] [--humans] [--json <file>]
+#   factory-walk.sh --self-test
+#
+#   <slug>      names text/<slug>-agents.md / -humans.md when they exist, and
+#               the receipt. Any word; a task id is fine.
+#   --files     the changed paths (default: git diff HEAD + untracked, from
+#               the repo this script lives in — a worktree checks itself)
+#   --route     a route to prove; repeatable. Derived from changed
+#               src/pages/**.astro when omitted (dynamic [param] routes are
+#               skipped and named — pass them explicitly)
+#   --preview   the task's private server, from worktree-preview.sh up
+#               (default http://localhost:4321 — the human's server)
+#   --no-gate   record the gate as UNRUN instead of running it (a read of the
+#               other stages; never a pass)
+#   --humans    on a tty, ask y/n per stop and record the human verdict
+#   --json      where the receipt goes (default $TMPDIR/one-factory-walk/<slug>.json)
+#
+# Env, self-test only (the TSC_CACHE_CMD idiom): FACTORY_WALK_TIER_CMD,
+# FACTORY_WALK_GATE_CMD, FACTORY_WALK_PROVE_CMD, FACTORY_WALK_SUBSTRATE_CMD
+# substitute the stage's command so every state can be driven deterministically,
+# and FACTORY_WALK_DROP_ROW=<stage> drops a row to prove the missing-row trap
+# bites. None of them is read outside --self-test.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+S="$ROOT/.claude/scripts"
+cd "$ROOT" || exit 2
+
+# ---------------------------------------------------------------------------
+# self-test — every state driven, and the two red proofs that matter
+# ---------------------------------------------------------------------------
+if [ "${1:-}" = "--self-test" ]; then
+  fails=0; T="$(mktemp -d)"
+  ok()  { printf '  ok   %s\n' "$*"; }
+  bad() { printf '  FAIL %s\n' "$*"; fails=$((fails+1)); }
+  # stubs: a tier, a gate, a prove, a substrate check — each a tiny script
+  printf '#!/bin/bash\necho "{\\"tier\\":\\"%s\\"}"; exit %s\n' FIX 0 > "$T/tier-fix"; chmod +x "$T/tier-fix"
+  printf '#!/bin/bash\necho "{\\"tier\\":\\"%s\\"}"; exit %s\n' SCHEMA 0 > "$T/tier-schema"; chmod +x "$T/tier-schema"
+  printf '#!/bin/bash\necho "{\\"tier\\":\\"%s\\"}"; exit %s\n' UNSIZED 3 > "$T/tier-unsized"; chmod +x "$T/tier-unsized"
+  for rc in 0 1 3 144; do printf '#!/bin/bash\nexit %s\n' "$rc" > "$T/rc$rc"; chmod +x "$T/rc$rc"; done
+  printf '#!/bin/bash\necho "PROVE: skipped (no reachable environment)"; exit 0\n' > "$T/prove-skipped"; chmod +x "$T/prove-skipped"
+  printf '#!/bin/bash\necho "PROVE: pass (1 route(s) proven)"; exit 0\n' > "$T/prove-pass"; chmod +x "$T/prove-pass"
+  run() { # run <expected-exit> <label> <env...> -- <args...>
+    local want="$1" label="$2"; shift 2
+    local envs=(); while [ "$1" != "--" ]; do envs+=("$1"); shift; done; shift
+    local out rc
+    out="$(env "${envs[@]+"${envs[@]}"}" FACTORY_WALK_SELFTEST=1 bash "$0" "$@" --json "$T/r.json" 2>&1)"; rc=$?
+    if [ "$rc" = "$want" ]; then ok "$label (exit $rc)"; else bad "$label — expected exit $want, got $rc"; printf '%s\n' "$out" | tail -8 | sed 's/^/       /'; fi
+    LAST_OUT="$out"
+  }
+  COMMON=(FACTORY_WALK_SUBSTRATE_CMD="$T/rc0" FACTORY_WALK_PROVE_CMD="$T/rc0")
+
+  echo "== green: a FIX with every stage answering"
+  run 0 "non-UI FIX, gate green, walk green" FACTORY_WALK_TIER_CMD="$T/tier-fix" FACTORY_WALK_GATE_CMD="$T/rc0" "${COMMON[@]}" -- selftest --files one.ie/web/src/lib/x.ts
+  jq -e '.verdict=="ok" and .lane=="fast" and .tier=="FIX"' "$T/r.json" >/dev/null && ok "receipt carries verdict:ok lane:fast tier:FIX" || bad "receipt wrong: $(cat "$T/r.json")"
+
+  echo "== RED PROOFS: the walk must be able to lose"
+  run 1 "gate exits 1 → verdict red, exit 1" FACTORY_WALK_TIER_CMD="$T/tier-fix" FACTORY_WALK_GATE_CMD="$T/rc1" "${COMMON[@]}" -- selftest --files one.ie/web/src/lib/x.ts
+  jq -e '.verdict=="red"' "$T/r.json" >/dev/null && ok "receipt says red" || bad "receipt did not say red"
+  run 3 "gate exits 144 (unrun) → NOT a pass, exit 3" FACTORY_WALK_TIER_CMD="$T/tier-fix" FACTORY_WALK_GATE_CMD="$T/rc144" "${COMMON[@]}" -- selftest --files one.ie/web/src/lib/x.ts
+  jq -e '.stages[]|select(.stage=="gate")|.status=="unrun"' "$T/r.json" >/dev/null && ok "144 is recorded as unrun" || bad "144 not recorded as unrun"
+  run 1 "no paths → UNSIZED → FAIL (absence of recon is not simplicity)" FACTORY_WALK_TIER_CMD="$T/tier-unsized" FACTORY_WALK_GATE_CMD="$T/rc0" "${COMMON[@]}" -- selftest --files one.ie/web/src/lib/x.ts
+  run 3 "--no-gate → gate unrun → exit 3, never 0" FACTORY_WALK_TIER_CMD="$T/tier-fix" FACTORY_WALK_GATE_CMD="$T/rc0" "${COMMON[@]}" -- selftest --files one.ie/web/src/lib/x.ts --no-gate
+  run 3 "a dropped stage row reads as unrun, never as pass" FACTORY_WALK_TIER_CMD="$T/tier-fix" FACTORY_WALK_GATE_CMD="$T/rc0" FACTORY_WALK_DROP_ROW=gate "${COMMON[@]}" -- selftest --files one.ie/web/src/lib/x.ts
+  case "$LAST_OUT" in *"no row for gate"*) ok "the missing row is NAMED" ;; *) bad "missing row not named" ;; esac
+
+  echo "== UI: the human gets a link and the walk is PENDING until they answer"
+  run 3 "UI change, prove skipped, no human yet → exit 3" FACTORY_WALK_TIER_CMD="$T/tier-fix" FACTORY_WALK_GATE_CMD="$T/rc0" FACTORY_WALK_PROVE_CMD="$T/prove-skipped" FACTORY_WALK_SUBSTRATE_CMD="$T/rc0" -- selftest --files one.ie/web/src/pages/factory.astro --preview http://localhost:4399
+  case "$LAST_OUT" in *"HUMAN WALK"*"http://localhost:4399/factory"*"factory-walk.sh selftest --humans"*) ok "link block: URL, route, and the record-the-verdict instruction" ;; *) bad "link block missing pieces"; printf '%s\n' "$LAST_OUT" | grep -n 'HUMAN\|http' | head -5 ;; esac
+  jq -e '.stages[]|select(.stage=="prove")|.status=="unrun"' "$T/r.json" >/dev/null && ok "a skipped prove is unrun (do-prove exits 0 on skip — the walk reads the line, not the code)" || bad "skipped prove misread"
+  run 3 "UI, prove PASS, human pending → still exit 3 (a person has not looked)" FACTORY_WALK_TIER_CMD="$T/tier-fix" FACTORY_WALK_GATE_CMD="$T/rc0" FACTORY_WALK_PROVE_CMD="$T/prove-pass" FACTORY_WALK_SUBSTRATE_CMD="$T/rc0" -- selftest --files one.ie/web/src/pages/factory.astro --preview http://localhost:4399
+  jq -e '.stages[]|select(.stage=="human")|.status=="unrun" and (.detail|test("PENDING"))' "$T/r.json" >/dev/null && ok "human stage is PENDING, counted as unrun" || bad "human stage not pending"
+  run 3 "a dynamic [param] page with no --route is unrun and named" FACTORY_WALK_TIER_CMD="$T/tier-fix" FACTORY_WALK_GATE_CMD="$T/rc0" FACTORY_WALK_PROVE_CMD="$T/prove-pass" FACTORY_WALK_SUBSTRATE_CMD="$T/rc0" -- selftest --files 'one.ie/web/src/pages/u/[slug]/tasks.astro'
+  case "$LAST_OUT" in *"pass --route"*) ok "the fix is named in the output" ;; *) bad "dynamic route not named" ;; esac
+
+  echo "== SCHEMA: the substrate check joins, and a 3 is cannot-run"
+  run 3 "schema tier, substrate exits 3 → unrun" FACTORY_WALK_TIER_CMD="$T/tier-schema" FACTORY_WALK_GATE_CMD="$T/rc0" FACTORY_WALK_PROVE_CMD="$T/rc0" FACTORY_WALK_SUBSTRATE_CMD="$T/rc3" -- selftest --files schema/one.tql
+  jq -e '.lane=="full"' "$T/r.json" >/dev/null && ok "SCHEMA takes the FULL lane" || bad "SCHEMA did not take the full lane: $(jq -r .lane "$T/r.json")"
+  run 1 "schema tier, substrate exits 1 → red" FACTORY_WALK_TIER_CMD="$T/tier-schema" FACTORY_WALK_GATE_CMD="$T/rc0" FACTORY_WALK_PROVE_CMD="$T/rc0" FACTORY_WALK_SUBSTRATE_CMD="$T/rc1" -- selftest --files schema/one.tql
+
+  echo "== doc-only: no gate by rule (n/a), and n/a is not unrun"
+  run 0 "a text/ change: gate n/a, prove via walk stub, pass" FACTORY_WALK_TIER_CMD="$T/tier-fix" FACTORY_WALK_GATE_CMD="$T/rc1" "${COMMON[@]}" -- selftest --files text/factory-do.md
+  jq -e '.stages[]|select(.stage=="gate")|.status=="n/a"' "$T/r.json" >/dev/null && ok "doc-only gate is n/a (the red stub was never run)" || bad "doc-only gate not n/a"
+
+  rm -rf "$T"
+  [ "$fails" -eq 0 ] && { echo "factory-walk: self-test PASS"; exit 0; }
+  echo "factory-walk: self-test FAILED ($fails)"; exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# args
+# ---------------------------------------------------------------------------
+slug=""; files=(); routes=(); preview="${FACTORY_WALK_PREVIEW:-http://localhost:4321}"
+no_gate=0; humans=0; json_out=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --files)   shift; while [ "$#" -gt 0 ] && [ "${1#--}" = "$1" ]; do files+=("$1"); shift; done ;;
+    --route)   routes+=("$2"); shift 2 ;;
+    --preview) preview="${2%/}"; shift 2 ;;
+    --no-gate) no_gate=1; shift ;;
+    --humans)  humans=1; shift ;;
+    --json)    json_out="$2"; shift 2 ;;
+    --*)       echo "factory-walk: unknown flag $1" >&2; exit 2 ;;
+    *)         [ -z "$slug" ] && slug="$1" || { echo "factory-walk: one slug only" >&2; exit 2; }; shift ;;
+  esac
+done
+[ -n "$slug" ] || { sed -n '2,3p;42,60p' "$0" >&2; exit 2; }
+[ -n "$json_out" ] || { mkdir -p "${TMPDIR:-/tmp}/one-factory-walk"; json_out="${TMPDIR:-/tmp}/one-factory-walk/$slug.json"; }
+selftest="${FACTORY_WALK_SELFTEST:-0}"
+
+if [ "${#files[@]}" -eq 0 ]; then
+  while IFS= read -r f; do [ -n "$f" ] && files+=("$f"); done < <(
+    { git diff --name-only HEAD 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null; } | sort -u)
+fi
+
+# ---------------------------------------------------------------------------
+# receipt rows — jq lines, exactly the do-w4-gates.sh shape
+# ---------------------------------------------------------------------------
+ROWS="$(mktemp)"; trap 'rm -f "$ROWS"' EXIT
+_add() { # stage status detail
+  [ "$selftest" = "1" ] && [ "${FACTORY_WALK_DROP_ROW:-}" = "$1" ] && return 0
+  jq -n --arg s "$1" --arg st "$2" --arg d "$3" '{stage:$s,status:$st,detail:$d}' >> "$ROWS"
+  printf '  %-9s %-6s %s\n' "$1" "$2" "$3"
+}
+_cmd() { # _cmd <ENV_NAME> <default...> — self-test substitution only
+  local v="$1"; shift
+  if [ "$selftest" = "1" ] && [ -n "${!v:-}" ]; then printf '%s' "${!v}"; else printf '%s' "$*"; fi
+}
+
+echo "FACTORY-WALK: $slug · ${#files[@]} file(s) · preview $preview"
+
+# ---------------------------------------------------------------------------
+# 1. size — the fork everything else hangs off
+# ---------------------------------------------------------------------------
+tier="UNKNOWN"
+_tier_cmd="$(_cmd FACTORY_WALK_TIER_CMD bash "$S/do-tier.sh")"
+_tier_out="$(printf '%s\n' "${files[@]}" | $_tier_cmd 2>/dev/null)"; _tier_rc=$?
+tier="$(printf '%s' "$_tier_out" | jq -r '.tier // "UNKNOWN"' 2>/dev/null || echo UNKNOWN)"
+if [ "$_tier_rc" -eq 3 ] || [ "$tier" = "UNSIZED" ]; then
+  _add size fail "UNSIZED — no paths to size; absence of recon must never read as simplicity (do-tier.sh exit 3)"
+elif [ "$_tier_rc" -ne 0 ] || [ "$tier" = "UNKNOWN" ]; then
+  _add size unrun "do-tier.sh could not answer (exit $_tier_rc)"
+else
+  _add size pass "tier=$tier"
+fi
+
+# surface — from the paths, by rule
+ui=0; substrate=0; full=0; doc_only=1; pages=()
+for f in "${files[@]}"; do
+  case "$f" in
+    one.ie/web/src/pages/*|one.ie/web/src/components/*|one.ie/web/src/layouts/*|*.astro) ui=1 ;;
+  esac
+  case "$f" in schema/*|*.tql) substrate=1 ;; esac
+  case "$f" in schema/*|packages/sdk/*|*auth*|*authority*|*roles*) full=1 ;; esac
+  case "$f" in *.md|.claude/*|text/*|docs/*) ;; *) doc_only=0 ;; esac
+  case "$f" in one.ie/web/src/pages/*.astro) pages+=("$f") ;; esac
+done
+[ "$tier" = "SCHEMA" ] && full=1
+# derive routes from the changed pages
+for pg in "${pages[@]+"${pages[@]}"}"; do
+  r="${pg#one.ie/web/src/pages}"; r="${r%.astro}"; r="${r%/index}"; [ -z "$r" ] && r="/"
+  case "$r" in *\[*) echo "  route     note   $pg is dynamic — pass --route <concrete path> to prove it"; dyn=1; continue ;; esac
+  routes+=("$r")
+done
+dyn="${dyn:-0}"
+
+# ---------------------------------------------------------------------------
+# 2. isolate — a UI task lives in a worktree with local caches
+# ---------------------------------------------------------------------------
+if [ "$ui" -eq 1 ] && [ "$selftest" != "1" ]; then
+  _common="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)"
+  if [ -n "$_common" ] && [ "$(dirname "$_common")" != "$ROOT" ]; then
+    if bash "$S/worktree-preview.sh" check --dir "$ROOT/one.ie/web" >/dev/null 2>&1; then
+      _add isolate pass "linked worktree, per-entry node_modules, local .vite/.astro"
+    else
+      _add isolate fail "worktree-preview.sh check RED — see \`worktree-preview.sh check --dir $ROOT/one.ie/web\`"
+    fi
+  else
+    _add isolate n/a "main checkout — the human's tree; a task's build goes in a worktree (§ Concurrency)"
+  fi
+elif [ "$ui" -eq 1 ]; then
+  _add isolate n/a "self-test"
+else
+  _add isolate n/a "not a UI change"
+fi
+
+# ---------------------------------------------------------------------------
+# 3. gate — the tier's lane, per folder, through the governor and the memo
+# ---------------------------------------------------------------------------
+lane="none"
+if [ "$doc_only" -eq 1 ]; then
+  _add gate n/a "doc-only change — no gate by rule (do-folder.sh)"
+elif [ "$no_gate" -eq 1 ]; then
+  _add gate unrun "--no-gate: the lane was not run (a read, never a pass)"
+  lane="$([ "$full" -eq 1 ] && echo full || echo fast)"
+else
+  lane="$([ "$full" -eq 1 ] && echo full || echo fast)"
+  _gate_cmd="$(_cmd FACTORY_WALK_GATE_CMD "")"
+  if [ -n "$_gate_cmd" ]; then
+    $_gate_cmd "$lane" >/dev/null 2>&1; _g=$?
+    case "$_g" in
+      0)   _add gate pass "lane=$lane (stub)" ;;
+      144) _add gate unrun "lane=$lane exit 144 — the gate could not run (queued out / killed); not red, not green" ;;
+      *)   _add gate fail "lane=$lane exit $_g" ;;
+    esac
+  else
+    _gfail=0; _gunrun=0; _gran=0
+    while IFS= read -r row; do
+      folder="$(printf '%s' "$row" | jq -r '.folder // empty')"; [ -n "$folder" ] || continue
+      [ -d "$ROOT/$folder" ] || { _add gate unrun "$folder: not on disk"; _gunrun=1; continue; }
+      _log="$(mktemp)"
+      if jq -e '.scripts["verify:fast"]' "$ROOT/$folder/package.json" >/dev/null 2>&1; then
+        ( cd "$ROOT/$folder" && FULL_VERIFY="$( [ "$lane" = full ] && echo 1 || echo 0 )" bun run verify:fast ) > "$_log" 2>&1; _g=$?
+        _lane_ran="$lane"
+      elif jq -e '.scripts.test' "$ROOT/$folder/package.json" >/dev/null 2>&1; then
+        ( cd "$ROOT/$folder" && bun run test ) > "$_log" 2>&1; _g=$?
+        _lane_ran="test"; lane="test"
+      else
+        _add gate unrun "$folder: no verify:fast or test script"; _gunrun=1; rm -f "$_log"; continue
+      fi
+      _gran=1
+      case "$_g" in
+        0)   _add gate pass "$folder lane=$_lane_ran — $(grep -o 'PASS ([^)]*)\|cache HIT[^—]*\|typecheck: 0 errors' "$_log" | tail -1)" ;;
+        144) _add gate unrun "$folder lane=$_lane_ran exit 144 — could not run (queued out or killed); log $_log"; _gunrun=1 ;;
+        *)   _add gate fail "$folder lane=$_lane_ran exit $_g — $(grep -m1 'FAILED\|FAIL\|error' "$_log" | cut -c1-120); log $_log" ; _gfail=1 ;;
+      esac
+      [ "$_g" -eq 0 ] && rm -f "$_log"
+    done < <(printf '%s\n' "${files[@]}" | bash "$S/do-folder.sh" 2>/dev/null | jq -c 'select(.folder != null)')
+    [ "$_gran" -eq 0 ] && [ "$_gfail" -eq 0 ] && [ "$_gunrun" -eq 0 ] && _add gate unrun "no folder mapped — do-folder.sh answered nothing for these paths"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# 4. prove — routes with the landing rule, or the slug's agents walk
+# ---------------------------------------------------------------------------
+if [ "$ui" -eq 1 ]; then
+  if [ "${#routes[@]}" -eq 0 ]; then
+    _add prove unrun "UI change with no provable route$([ "$dyn" = 1 ] && echo ' (dynamic page)') — pass --route </path>"
+  else
+    _prove_cmd="$(_cmd FACTORY_WALK_PROVE_CMD bash "$S/do-prove.sh")"
+    _rargs=(); for r in "${routes[@]}"; do _rargs+=(--route "$r"); done
+    _pout="$(PROVE_BASE_URL="$preview" $_prove_cmd "${_rargs[@]}" 2>&1)"; _p=$?
+    case "$_pout" in
+      *"PROVE: skipped"*|*"PROVE: no changes"*) _add prove unrun "do-prove.sh skipped — no reachable environment at $preview (exit 0 there is NOT a pass)" ;;
+      *) if [ "$_p" -eq 0 ]; then _add prove pass "${#routes[@]} route(s) at $preview, landing rule held"
+         else _add prove fail "$(printf '%s\n' "$_pout" | grep -m1 'PROVE: FAIL' | cut -c1-140)"; fi ;;
+    esac
+  fi
+else
+  _prove_cmd="$(_cmd FACTORY_WALK_PROVE_CMD "")"
+  if [ -n "$_prove_cmd" ]; then
+    $_prove_cmd >/dev/null 2>&1; _p=$?
+    case "$_p" in 0) _add prove pass "agents walk (stub)";; 3) _add prove unrun "walk could not run (stub 3)";; *) _add prove fail "walk failed (stub $_p)";; esac
+  elif [ -f "$ROOT/text/$slug-agents.md" ]; then
+    _wout="$(WALK_BASE_URL="$preview" bash "$S/do-walk.sh" "$slug" --agents --strict 2>&1)"; _p=$?
+    case "$_p" in
+      0) _add prove pass "$(printf '%s\n' "$_wout" | grep -m1 '^WALK: pass')" ;;
+      3) _add prove unrun "$(printf '%s\n' "$_wout" | grep -m1 'could not be run' | cut -c1-140)" ;;
+      *) _add prove fail "$(printf '%s\n' "$_wout" | grep -m1 '^WALK: FAIL' | cut -c1-140)" ;;
+    esac
+  else
+    _add prove unrun "no text/$slug-agents.md — write the walk (one stop per deliverable, expect_cmd = the accept:)"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# 5. human — UI only: the link, the stops, and how the verdict lands
+# ---------------------------------------------------------------------------
+if [ "$ui" -eq 1 ]; then
+  hdoc="$ROOT/text/$slug-humans.md"
+  echo
+  echo "── HUMAN WALK — $slug ──────────────────────────────────────────────"
+  echo "   open:  $preview${routes[0]:-/}"
+  if [ -f "$hdoc" ]; then
+    WALK_BASE_URL="$preview" bash "$S/do-walk.sh" "$slug" --humans --list 2>/dev/null | sed -n '2,$p' | sed 's/^/   /'
+  else
+    i=0
+    for r in "${routes[@]+"${routes[@]}"}"; do
+      i=$((i+1)); echo "   $i. $preview$r"
+      echo "      · the page you land on IS $r (a bounce to /signin proves nothing — sign in first)"
+      echo "      · the change this task describes is visible and behaves; no console errors (⌥⌘I)"
+    done
+    [ "$i" -eq 0 ] && echo "   (no route derived — open the preview and the page this task changed)"
+    echo "   No text/$slug-humans.md yet — one \`\`\`walk block per stop makes this list yours."
+  fi
+  echo "   record: bash .claude/scripts/factory-walk.sh $slug --humans        # asks y/n per stop on a tty"
+  echo "       or: signal(\"tasks:tag\", { tid, tags: [\"verdict:ok\"] })       # or verdict:red — lands on the task"
+  echo "────────────────────────────────────────────────────────────────────"
+  echo
+  if [ "$humans" -eq 1 ] && [ -t 0 ] && [ -f "$hdoc" ]; then
+    if WALK_BASE_URL="$preview" bash "$S/do-walk.sh" "$slug" --humans; then _add human pass "a person walked every stop and said ok"
+    else _add human fail "a person rejected a stop"; fi
+  elif [ "$humans" -eq 1 ] && [ -t 0 ]; then
+    printf '   verified in the browser? [y/n] '; read -r v || v=n
+    case "$v" in y|Y|yes) _add human pass "a person looked and said ok" ;; *) _add human fail "a person looked and said red" ;; esac
+  else
+    _add human unrun "PENDING — a person has not looked; the link block above is the instruction"
+  fi
+else
+  _add human n/a "not a UI change"
+fi
+
+# ---------------------------------------------------------------------------
+# 6. substrate — SCHEMA tier: the ladder is live, and a 3 is cannot-run
+# ---------------------------------------------------------------------------
+if [ "$substrate" -eq 1 ] || [ "$tier" = "SCHEMA" ]; then
+  _sub_cmd="$(_cmd FACTORY_WALK_SUBSTRATE_CMD bash "$S/factory-check.sh" schema-live)"
+  $_sub_cmd >/dev/null 2>&1; _s=$?
+  case "$_s" in
+    0) _add substrate pass "factory-check.sh schema-live" ;;
+    3) _add substrate unrun "factory-check.sh could not reach the substrate (3) — nothing proven either way" ;;
+    *) _add substrate fail "factory-check.sh schema-live RED (exit $_s)" ;;
+  esac
+else
+  _add substrate n/a "not a schema change"
+fi
+
+# ---------------------------------------------------------------------------
+# verdict — zero fails AND zero unruns, over exactly the six rows
+# ---------------------------------------------------------------------------
+fails=$(jq -s '[.[]|select(.status=="fail")]|length' "$ROWS")
+unruns=$(jq -s '[.[]|select(.status=="unrun")]|length' "$ROWS")
+missing=0
+for st in size isolate gate prove human substrate; do
+  if [ "$(jq -r --arg s "$st" 'select(.stage==$s)|.stage' "$ROWS" 2>/dev/null | head -1)" != "$st" ]; then
+    echo "  $st       unrun  no row for $st — an absent row is the fail-open trap in data form"
+    missing=$((missing+1))
+  fi
+done
+unruns=$((unruns + missing))
+if [ "$fails" -gt 0 ]; then verdict=red; rc=1
+elif [ "$unruns" -gt 0 ]; then verdict=unrun; rc=3
+else verdict=ok; rc=0; fi
+
+jq -n --arg slug "$slug" --arg tier "$tier" --arg lane "$lane" --arg verdict "$verdict" \
+      --arg preview "$preview" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      --argjson ui "$ui" --argjson fails "$fails" --argjson unruns "$unruns" \
+      --slurpfile rows "$ROWS" \
+      '{slug:$slug, ts:$ts, tier:$tier, lane:$lane, verdict:$verdict, ui:($ui==1), preview:$preview,
+        fails:$fails, unruns:$unruns, stages:$rows}' > "$json_out" 2>/dev/null \
+  || jq -n --arg slug "$slug" --arg verdict "$verdict" --arg lane "$lane" --arg tier "$tier" '{slug:$slug,verdict:$verdict,lane:$lane,tier:$tier,stages:[]}' > "$json_out"
+
+echo
+echo "FACTORY-WALK: $verdict — $fails failed · $unruns not proven · tier $tier · receipt $json_out"
+echo "tasks:tag  lane:$lane verdict:$verdict          # what the executor writes on the task (T4)"
+exit "$rc"

package/scripts/factory-width.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# factory-width.sh — how many factory tasks this box may build AT ONCE, measured.
+#
+# manifest: portable
+#
+# The Workflow runtime caps a script's concurrency at min(16, cpus-2) — CORES,
+# which were never the binding constraint here (10 cores authorised 8 worktrees
+# on a 24 GB box; 8 cycles is ~16 GB of gates). Two things bind first, and this
+# prints the smaller so the launcher passes it as args.width:
+#
+#   memory   gate_headroom — MB actually free (vm_stat: free + purgeable + cold
+#            cache, never memory_pressure's inflated figure) ÷ the measured price
+#            of one cycle. 99 means "the sensor is unreadable — do not constrain".
+#   ports    the preview range minus what a neighbour already holds. One
+#            server per UI task; 4321 is the human's and is never counted.
+#
+# Prints ONE JSON line: {"width":N,"memory":N,"ports":N,"price_mb":N}. Never 0 —
+# work slows, it never stops (the governor's own floor). Exit 0 always; a reader
+# that cannot get a number gets 1, printed, not a crash.
+#
+#   bash .claude/scripts/factory-width.sh            # {"width":1,...}
+#   bash .claude/scripts/factory-width.sh --explain  # the same, with the why
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+LIB="$ROOT/.claude/scripts/lib/govern.sh"
+PORT_MIN="${PREVIEW_PORT_MIN:-4322}"; PORT_MAX="${PREVIEW_PORT_MAX:-4329}"
+
+mem=99; price=0
+if [ -f "$LIB" ]; then
+  # shellcheck source=lib/govern.sh
+  . "$LIB"
+  mem="$(gate_headroom 2>/dev/null || echo 99)"
+  price="$(gate_price_mb 2>/dev/null || echo 0)"
+fi
+case "$mem" in ''|*[!0-9]*) mem=99 ;; esac
+
+ports=0
+if command -v lsof >/dev/null 2>&1; then
+  for ((p = PORT_MIN; p <= PORT_MAX; p++)); do
+    lsof -nP -iTCP:"$p" -sTCP:LISTEN >/dev/null 2>&1 || ports=$((ports + 1))
+  done
+else
+  ports=$((PORT_MAX - PORT_MIN + 1))   # no lsof: cannot see neighbours; the range is the cap
+fi
+[ "$ports" -lt 1 ] && ports=1
+
+width="$mem"; [ "$ports" -lt "$width" ] && width="$ports"
+[ "$width" -lt 1 ] && width=1
+# 99 is "unconstrained by memory"; the ports then bind, and they always exist.
+[ "$width" -gt 16 ] && width=16
+
+printf '{"width":%s,"memory":%s,"ports":%s,"price_mb":%s}\n' "$width" "$mem" "$ports" "$price"
+if [ "${1:-}" = "--explain" ]; then
+  echo "width $width = min(memory funds $mem cycle(s) at ${price} MB, $ports free preview port(s) in $PORT_MIN-$PORT_MAX)" >&2
+  [ "$mem" = 99 ] && echo "memory sensor unreadable (99) — not constraining; ports bind" >&2
+fi
+exit 0

package/scripts/fade-toxic.sh

@@ -4,7 +4,8 @@
 # Runs every hour via ie.one.fade-toxic.plist:
 #   1. --sync-closes   reconcile close-derived weight from learnings.md (idempotent)
 #   2. --fade --rate   decay LIVE weight (strength cools, resistance heals 2× faster)
-#   3. regenerate todo.md  (same shape as the sync-priority-todo hook — one source of truth)
+#   3. regenerate todo.md  (this loop is its ONLY writer since 2026-09-05 — the
+#      per-edit/Stop/SessionStart hook that also wrote it cost 5.7s a fire)
 #   4. append a one-line toxic report to the log
 #
 # NON-DESTRUCTIVE by contract: fades + reports only. It NEVER deletes a todo, edits a plan,
@@ -31,7 +32,7 @@ TS=$(date '+%Y-%m-%d %H:%M')
 python3 "$RANK" --sync-closes >/dev/null 2>&1 || true
 FADED_LINE=$(python3 "$RANK" --fade --rate "$FADE_RATE" 2>/dev/null | head -1 || true)
 
-# 3 — regenerate todo.md (identical wrapper to .claude/hooks/sync-priority-todo.sh).
+# 3 — regenerate todo.md. `do-rank.py` is live for anything that needs it fresher than hourly.
 QUEUE_OUT=$(python3 "$RANK" 2>/dev/null || true)
 if [ -n "$QUEUE_OUT" ]; then
   {
@@ -41,7 +42,7 @@ if [ -n "$QUEUE_OUT" ]; then
     echo "$QUEUE_OUT"
     echo '```'
     echo
-    echo "> Auto-generated by do-rank.py (hourly fade-toxic loop + session hooks)."
+    echo "> Auto-generated by do-rank.py (hourly fade-toxic loop). Fresher: python3 .claude/scripts/do-rank.py"
     echo "> Run \`do-rank.py --toxic\` for the demoted list, \`--frontier\` for what's next."
   } > "$ROOT/todo.md"
 fi

package/scripts/fixtures/factory-brief-real.md

@@ -0,0 +1,44 @@
+You are the hand. Build task task:01a07591e5c350a306c93933: "In pages/components add a button > add this component to a page — it shows a list of pages in the workspace, you select the page to add the component, then edit the page or continue adding components".
+Notes from the board:
+SPEC (the title is the whole spec; the row's notes were empty — this brief was assembled by the launching session from a real read of the tree on 2026-09-06, every file:line verified).
+
+WHAT TO BUILD
+On /components (the Component Library gallery, ComponentBrowser.tsx), give every block an 'Add to page' affordance. Clicking it opens a picker listing the workspace's pages; choosing one appends that block to that page; after the write, offer two exits — 'Edit page' (link to the page editor) and 'Continue adding components' (dismiss the picker, stay in the gallery).
+
+BOTH RECEIVERS ALREADY EXIST — DO NOT WRITE A NEW ONE, DO NOT ADD AN API ROUTE.
+- pages:list — one.ie/web/src/lib/resolvers/pages.ts:670. Request { slug }. Returns { pages: [{ slug, title, status, updated_at }] } ordered by updated_at DESC. This is the picker's list. Returns { pages: [] } on any auth denial.
+- pages:add-block — one.ie/web/src/lib/resolvers/pages.ts:630. Request { slug, page, section: { component, props }, atIndex? }. atIndex omitted = append to end, which is what this feature wants. It already runs normalizeBlockProps(BLOCK_SCHEMA, ...) server-side, so send the block's defaultProps verbatim — do NOT normalize on the client.
+
+EXACT CALL-SITE PRECEDENT — copy this shape:
+one.ie/web/src/components/chat/BlockFrame.tsx:112-125. It is the same feature one surface over ('Add to page' from chat). Note its gate: `const canAddToPage = addToPage && !!slug && !!page`, its pending/added state machine, and `emitClick('ui:chat:add-to-page', { component })` before the call. Use `ask` from '@/lib/in/ask'. Emit a sibling signal name, e.g. 'ui:component-browser:add-to-page'.
+
+THE ONE DESIGN DECISION, ALREADY SETTLED — DO NOT RE-OPEN IT.
+/components is a genuinely PUBLIC route. pages/components.astro mounts <ComponentBrowser client:only="react" /> with a plain Layout and passes NO props, and ComponentBrowser takes none. It is NOT one of the slugless console pages: those (see pages/tasks.astro) call resolveRoom() and rewrite to /u/[slug]/..., and components.astro does neither. There is also no workspace-scoped mount — ComponentBrowser appears only in pages/components.astro and is referenced by components/puck/BlockFinder.tsx.
+
+So: derive the workspace slug SERVER-SIDE in pages/components.astro (from Astro.locals.workspaceContext?.workspace ?? Astro.locals.slug — verify which is right against how another workspace-aware page reads it) and pass it down as an optional `slug` prop to ComponentBrowser. When there is no session there is no slug, and the 'Add to page' button MUST NOT RENDER — same gate shape as BlockFrame's canAddToPage. An anonymous visitor keeps exactly today's public gallery, unchanged. Do NOT invent a client-side workspace read, do NOT add a new route, do NOT make /components members-only.
+
+WHERE THE BUTTON GOES
+ComponentBrowser.tsx has two surfaces for a block: the grid card (article, ~line 250) and PreviewModal (~line 143). Put the affordance in the PreviewModal footer at minimum — the modal is the block's detail view and already has a footer row. A card-level quick-add is welcome but must not swallow the card's existing onClick (which opens the preview).
+
+DONE LOOKS LIKE
+1. Signed in, /components → open any block → 'Add to page' → picker lists this workspace's real pages → pick one → success state → 'Edit page' and 'Continue adding components' both present and both work.
+2. The block actually lands: re-open that page in the editor and the block is there, rendered, at the end.
+3. Signed out, /components renders exactly as before with no 'Add to page' button anywhere.
+4. `cd one.ie/web && bun run verify:fast` green. Add a unit test for the picker gate (no slug ⇒ no button).
+
+CONSTRAINTS
+- 6-token palette only (hook:design-check blocks otherwise) — follow the existing var(--color-border) / text-font / bg-foreground idiom in this very file.
+- Do not regress the IntersectionObserver lazy-mount or the PreviewErrorBoundary; the gallery renders ~376 blocks.
+- Edit in a worktree, never on shared main.
+
+RULES, each one a recorded outage (text/factory-do.md § Concurrency):
+1. Work in YOUR OWN worktree, never the shared main tree. Slug: task-task:01a07591e5c350a306c93933.
+   UI task — run:  bash .claude/scripts/worktree-preview.sh up task-task:01a07591e5c350a306c93933 --route /components
+   It cuts the worktree from main, links node_modules CONTENTS (never the dir), copies .env, allocates a port (never sweeps), and hands you a URL only after 3 consecutive 200s. Use the path and URL it prints.
+2. NEVER `bun install` inside the worktree. NEVER symlink node_modules itself.
+3. Make the change the task describes — minimal, in the worktree. Write or extend the test that names the concrete failure this change prevents (input → wrong result). No test that guards a shape.
+4. Run only YOUR test file(s) in the worktree:  cd <wt>/one.ie/web && bunx vitest related --run <files>  — through bash ../../.claude/scripts/gate-run.sh doer -- … . Do NOT run the suite; factory-walk.sh runs the tier's lane after you.
+5. Commit in the worktree by EXPLICIT PATH (git add <file>...), message: "task(task:01a07591e5c350a306c93933): <what was measured>". Never git add -A.
+6. Report files from `git status --porcelain` / `git show --stat` in the worktree, never from memory.
+7. THE BRAIN AND THE EDGE (root CLAUDE.md, LOCKED): if the change adds or touches a receiver, it reads KV / BrainDO JSON — never typedbQuery — and writes to the brain fire-and-forget or via sync/. resolvers/factory.ts is the one exception. Prove the door: bash .claude/scripts/signal-watch.sh --local (with your preview as SIGNAL_WATCH_LOCAL) — a door over budget or reaching for the brain is red, and red closes nothing.
+If the task cannot be done as written, do the part that can, say exactly what you left out and why, and return committed:false rather than inventing scope.

package/scripts/fixtures/triage-dupe.md

@@ -0,0 +1,5 @@
+---
+deliverables:
+  - item: "xyzzy-triage-dupe unique deliverable phrase"
+    accept: "true"
+---