@oneie/claude 0.8.0 → 0.9.0

package/scripts/factory-brief-check.sh

@@ -0,0 +1,330 @@
+#!/usr/bin/env bash
+# factory-brief-check.sh — pre-flight a factory brief for DEFERRED DECISIONS.
+#
+# manifest: portable
+#   Reads no credential and names no monorepo path — every rule is a literal
+#   in this file and the brief arrives as an argument or on stdin. The red
+#   half of --self-test reads fixtures/factory-brief-real.md, which ships
+#   beside it; absent, the self-test goes RED rather than skipping.
+#
+# WHY THIS EXISTS. A brief that hands the doer a decision instead of a decision
+# already made costs a whole run. The first factory run spent ~46 minutes and
+# ended in a refutation because one parenthesis said "verify which is right" —
+# the launching session had two candidate reads of the workspace and shipped
+# both. The doer is the wrong place to settle that: it has no board, no
+# neighbours, and no cheap way to be wrong. This gate reads the brief BEFORE a
+# worktree, a port, or a model call is spent, and refuses.
+#
+# Usage:
+#   factory-brief-check.sh <brief-file>     check a brief file
+#   factory-brief-check.sh -                check a brief on stdin
+#   cat brief.md | factory-brief-check.sh   same
+#   factory-brief-check.sh --self-test      prove the gate goes RED and GREEN
+#
+# Exit: 0 = brief is launchable · 1 = RED (or self-test failed) · 2 = usage.
+#
+# Env:
+#   FACTORY_BRIEF_FIXTURE  override the --self-test red fixture (default:
+#                          fixtures/factory-brief-real.md beside this script)
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ---------------------------------------------------------------------------
+# The rules. Each is a NAMED pattern, matched case-insensitively, one per line
+# of the brief. A rule fires when the brief leaves a decision for the doer.
+#
+# Third field is the input the pattern is matched against: `line` is the raw
+# line, `stripped` is the line with every file-path token removed first.
+#
+# Deliberate deviation, documented: `tbd` and `todo` match against `stripped`,
+# so `text/template-todo.md` and `<slug>-todo.md` — which nearly every real
+# brief in this repo cites — are NOT hits, while a bare `TBD.` at the end of a
+# sentence still is. A gate that goes red on the name of a file it expects you
+# to name is decoration, and gets disabled; a gate that misses `TBD.` because
+# of the full stop is worse.
+# ---------------------------------------------------------------------------
+RULES=(
+  'verify-which|verify[[:space:]]+which|line'
+  'check-whether|check[[:space:]]+whether|line'
+  'tbd|(^|[^-_/[:alnum:]])tbd([^-_[:alnum:]]|$)|stripped'
+  'todo|(^|[^-_/[:alnum:]])todo([^-_[:alnum:]]|$)|stripped'
+  'decide-later|decide[[:space:]]+later|line'
+  'or-alternatively|or[[:space:]]+alternatively|line'
+  'either-or|(^|[^[:alnum:]])either[^[:alnum:]].*[[:space:]]or[[:space:]]|line'
+  'trailing-question|\?[[:space:]]*$|line'
+  'if-possible|if[[:space:]]+possible|line'
+  'ideally|(^|[^[:alnum:]])ideally([^[:alnum:]]|$)|line'
+)
+
+# Rule 'code-span-options': two options joined by ` ?? ` or ` or ` INSIDE a code
+# span. `a ?? b` in prose is a decision the doer has to make; the same string in
+# shipped code is not, so only backtick spans count. Returns 0 when the line has
+# one.
+code_span_options() {
+  awk '
+    {
+      n = split($0, part, "`")
+      # odd-indexed parts (2,4,…) are inside a span
+      for (i = 2; i <= n; i += 2) {
+        s = part[i]
+        if (s ~ /[^[:space:]][[:space:]]+\?\?[[:space:]]+[^[:space:]]/) { found = 1 }
+        if (s ~ /[^[:space:]][[:space:]]+or[[:space:]]+[^[:space:]]/)   { found = 1 }
+      }
+    }
+    END { exit !found }
+  ' <<< "$1"
+}
+
+# A file path token. The spec class is lowercase; this adds A-Z so the count and
+# any listing read correctly (`ComponentBrowser.tsx`, not `omponentBrowser.tsx`).
+# Presence is identical either way.
+PATH_RE='[A-Za-z0-9_./-]+\.(tsx|astro|ts|sh|md|mjs|js)([^A-Za-z0-9]|$)'
+
+# A 'Done' section: a line that STARTS with the word done, optionally behind a
+# markdown heading or bold marker. "DONE LOOKS LIKE", "## Done", "**Done**".
+DONE_RE='^[[:space:]]*(#+[[:space:]]*)?(\*\*)?[[:space:]]*done([^[:alnum:]]|$)'
+
+check_brief() {
+  local text="$1" label="${2:-brief}"
+  local hits=0 line rule name pat
+
+  if [ -z "${text//[[:space:]]/}" ]; then
+    printf 'BRIEF RED: empty-brief — "<%s is empty — a brief that says nothing defers everything>"\n' "$label"
+    return 1
+  fi
+
+  local rest src stripped
+  while IFS= read -r line; do
+    [ -z "${line//[[:space:]]/}" ] && continue
+    stripped="$(sed -E "s#$PATH_RE# #g" <<< "$line")"
+    for rule in ${RULES[@]+"${RULES[@]}"}; do
+      name="${rule%%|*}"; rest="${rule#*|}"
+      pat="${rest%|*}"; src="${rest##*|}"
+      if grep -qiE "$pat" <<< "$([ "$src" = stripped ] && printf '%s' "$stripped" || printf '%s' "$line")"; then
+        printf 'BRIEF RED: %s — "%s"\n' "$name" "$line"
+        hits=$((hits + 1))
+      fi
+    done
+    if code_span_options "$line"; then
+      printf 'BRIEF RED: code-span-options — "%s"\n' "$line"
+      hits=$((hits + 1))
+    fi
+  done <<< "$text"
+
+  local files
+  files="$(grep -oE "$PATH_RE" <<< "$text" | sed -E 's/[^A-Za-z0-9]$//' | sort -u)"
+  local nfiles=0
+  [ -n "$files" ] && nfiles="$(wc -l <<< "$files" | tr -d ' ')"
+
+  if [ "$nfiles" -eq 0 ]; then
+    printf 'BRIEF RED: no-file-path — "<%s names no file the doer can open>"\n' "$label"
+    hits=$((hits + 1))
+  fi
+
+  if ! grep -qiE "$DONE_RE" <<< "$text"; then
+    printf 'BRIEF RED: no-done-section — "<%s has no Done section — nothing says when to stop>"\n' "$label"
+    hits=$((hits + 1))
+  fi
+
+  if [ "$hits" -gt 0 ]; then
+    return 1
+  fi
+  printf 'BRIEF OK: %s files named, 0 deferred decisions\n' "$nfiles"
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# --self-test — the red proof. Four cases; the red half runs against the ACTUAL
+# brief that produced the first run's refutation, copied verbatim, not retyped.
+# ---------------------------------------------------------------------------
+self_test() {
+  local fixture="${FACTORY_BRIEF_FIXTURE:-$HERE/fixtures/factory-brief-real.md}"
+  local tmp out rc bad=0 cases=0
+
+  if [ ! -f "$fixture" ]; then
+    printf 'SELF-TEST RED: the red fixture is missing at %s — the red half cannot be run, so nothing here is proven. Refusing to pass.\n' "$fixture" >&2
+    printf 'SELF-TEST RED: 0 cases — fixture absent\n'
+    return 1
+  fi
+
+  # (a) the real brief MUST go red, and MUST name verify-which on the real line.
+  cases=$((cases + 1))
+  out="$(check_brief "$(cat "$fixture")" "$fixture")"; rc=$?
+  if [ $rc -eq 0 ]; then
+    printf '  FAIL (a) the real brief passed — the gate is blind\n' >&2; bad=1
+  elif ! grep -q '^BRIEF RED: verify-which — ' <<< "$out"; then
+    printf '  FAIL (a) the real brief went red, but not on verify-which:\n%s\n' "$out" >&2; bad=1
+  elif ! grep -qi 'verify which is right' <<< "$(grep '^BRIEF RED: verify-which — ' <<< "$out")"; then
+    printf '  FAIL (a) verify-which fired on the wrong line:\n%s\n' "$(grep '^BRIEF RED: verify-which' <<< "$out")" >&2; bad=1
+  else
+    printf '  ok   (a) the real brief is RED on verify-which, quoting "verify which is right"\n'
+  fi
+
+  tmp="$(mktemp -d)"; trap 'rm -rf "$tmp"' RETURN
+
+  # (b) a clean brief MUST pass.
+  cat > "$tmp/clean.md" <<'CLEAN'
+BUILD: the picker gate on the component gallery.
+
+WHAT TO BUILD
+Add an "Add to page" control to the preview footer in
+src/components/puck/ComponentBrowser.tsx. It lists the workspace pages, takes
+one, appends the block, then offers two exits.
+
+THE DECISION, ALREADY MADE
+Read the workspace slug server-side from Astro.locals.slug in
+src/pages/components.astro and pass it down as an optional prop. There is no
+session, so there is no slug, so the control does not render.
+
+TEST
+Extend tests/unit/puck/add-to-page.test.tsx with one case that names the wrong
+result: a missing slug renders the control anyway.
+
+DONE LOOKS LIKE
+1. The control renders signed in and is absent signed out.
+2. The block lands at the end of the picked page.
+3. bash .claude/scripts/gate-run.sh doer -- bunx vitest related --run is green.
+4. node .claude/scripts/wf-check.mjs is green.
+CLEAN
+  cases=$((cases + 1))
+  out="$(check_brief "$(cat "$tmp/clean.md")" "$tmp/clean.md")"; rc=$?
+  if [ $rc -ne 0 ]; then
+    printf '  FAIL (b) the clean brief went red — the gate cries wolf:\n%s\n' "$out" >&2; bad=1
+  elif ! grep -q '^BRIEF OK: ' <<< "$out"; then
+    printf '  FAIL (b) the clean brief exited 0 without printing BRIEF OK\n' >&2; bad=1
+  else
+    printf '  ok   (b) the clean brief is GREEN — %s\n' "$out"
+  fi
+
+  # (c) a brief with no file path MUST go red, even with nothing deferred.
+  cat > "$tmp/nopath.md" <<'NOPATH'
+BUILD: make the gallery let you put a block on a page.
+
+DONE LOOKS LIKE
+1. It works signed in and is absent signed out.
+NOPATH
+  cases=$((cases + 1))
+  out="$(check_brief "$(cat "$tmp/nopath.md")" "$tmp/nopath.md")"; rc=$?
+  if [ $rc -eq 0 ] || ! grep -q '^BRIEF RED: no-file-path' <<< "$out"; then
+    printf '  FAIL (c) a brief naming no file passed:\n%s\n' "$out" >&2; bad=1
+  else
+    printf '  ok   (c) a brief naming no file is RED on no-file-path\n'
+  fi
+
+  # (d) a brief with no Done section MUST go red.
+  cat > "$tmp/nodone.md" <<'NODONE'
+BUILD: the picker gate.
+Edit src/components/puck/ComponentBrowser.tsx and read the slug server-side in
+src/pages/components.astro. Extend tests/unit/puck/add-to-page.test.tsx.
+NODONE
+  cases=$((cases + 1))
+  out="$(check_brief "$(cat "$tmp/nodone.md")" "$tmp/nodone.md")"; rc=$?
+  if [ $rc -eq 0 ] || ! grep -q '^BRIEF RED: no-done-section' <<< "$out"; then
+    printf '  FAIL (d) a brief with no Done section passed:\n%s\n' "$out" >&2; bad=1
+  else
+    printf '  ok   (d) a brief with no Done section is RED on no-done-section\n'
+  fi
+
+  # (e) EVERY named rule must fire. A declared rule that no case exercises is a
+  # rule that can ship broken and pass a brief it exists to refuse — one line
+  # per rule, all eleven, and the count asserted so a line tripping two rules
+  # (or none) is caught rather than averaged away.
+  cat > "$tmp/allrules.md" <<'ALLRULES'
+BUILD: one line per deferred decision, in src/lib/one.ts.
+Verify which read is right.
+Check whether the snapshot is warm.
+The signal name is TBD.
+Leave a TODO where the gate goes.
+Name the signal now and decide later on the payload.
+Append the block, or alternatively insert it at the top.
+Use either the snapshot or a live read.
+Should the picker show archived pages?
+Reuse the existing helper if possible.
+Ideally the control renders in the footer.
+Set the base to `4321 or 4325` first.
+DONE LOOKS LIKE
+1. It renders.
+ALLRULES
+  cases=$((cases + 1))
+  out="$(check_brief "$(cat "$tmp/allrules.md")" "$tmp/allrules.md")"; rc=$?
+  local missing="" r n
+  for r in verify-which check-whether tbd todo decide-later or-alternatively \
+           either-or trailing-question if-possible ideally code-span-options; do
+    grep -q "^BRIEF RED: $r — " <<< "$out" || missing="$missing $r"
+  done
+  n="$(grep -c '^BRIEF RED: ' <<< "$out" | tr -d ' ')"
+  if [ -n "$missing" ]; then
+    printf '  FAIL (e) rules declared but never fired:%s\n%s\n' "$missing" "$out" >&2; bad=1
+  elif [ "$n" != 11 ]; then
+    printf '  FAIL (e) expected 11 hits, one per rule, got %s:\n%s\n' "$n" "$out" >&2; bad=1
+  else
+    printf '  ok   (e) all 11 named rules fire — 11 hits, one per rule, no structural hit\n'
+  fi
+
+  # (f) THE RED PROOF ITSELF. Gut this script — empty the RULES array, keep
+  # everything else — and case (a) MUST flip: the real brief that cost ~46
+  # minutes now passes. A checker that stays green against its own gutted copy
+  # proves nothing, which is the failure this whole script exists to refuse.
+  #
+  # Gut by STRUCTURE, never by line number, so an edit above cannot quietly turn
+  # this into a no-op. Two things were measured before this assertion was
+  # written, and both are why it reads the way it does:
+  #   - `"${RULES[@]}"` on an EMPTY array is an unbound variable under `set -u`
+  #     in bash 3.2, so the gutted copy used to die with a bash error and exit 1.
+  #     "exit non-zero" would have looked like proof and measured the crash. The
+  #     expansion in check_brief is empty-safe for exactly this reason.
+  #   - code_span_options lives OUTSIDE Rules and still runs in the gutted copy;
+  #     the real fixture happens to trip none of its spans, so the gutted copy
+  #     reaches BRIEF OK. Both halves are asserted separately so a future change
+  #     to either one names itself instead of averaging away.
+  cases=$((cases + 1))
+  awk '/^RULES=\(/{print "RULES=()"; s=1; next} s&&/^\)/{s=0; next} !s' \
+    "${BASH_SOURCE[0]}" > "$tmp/gutted.sh"
+  if ! grep -q '^RULES=()$' "$tmp/gutted.sh"; then
+    printf '  FAIL (f) the gutting did not take — no empty RULES in the copy\n' >&2; bad=1
+  elif ! bash -n "$tmp/gutted.sh" 2>/dev/null; then
+    printf '  FAIL (f) the gutted copy does not parse — the proof measures a syntax error, not the rules\n' >&2; bad=1
+  else
+    out="$(bash "$tmp/gutted.sh" "$fixture" 2>&1)"; rc=$?
+    if grep -q '^BRIEF RED: verify-which' <<< "$out"; then
+      printf '  FAIL (f) the gutted copy STILL refused the brief on verify-which — the RULES array is not load-bearing:\n%s\n' "$out" >&2; bad=1
+    elif [ $rc -ne 0 ]; then
+      printf '  FAIL (f) the gutted copy stopped the brief for some OTHER reason (rc=%s) — the red half of (a) is not attributable to the rules:\n%s\n' "$rc" "$out" >&2; bad=1
+    else
+      printf '  ok   (f) rules emptied ⇒ the real brief PASSES (%s) — case (a) is attributable to the rules, not to the structural checks\n' "$out"
+    fi
+  fi
+
+  if [ $bad -ne 0 ]; then
+    printf 'SELF-TEST RED: %s cases — the gate does not hold\n' "$cases"
+    return 1
+  fi
+  printf 'SELF-TEST OK: %s cases — red half red, green half green\n' "$cases"
+  return 0
+}
+
+main() {
+  case "${1:-}" in
+    --self-test) self_test; exit $? ;;
+    -h|--help)
+      awk 'NR==1{next} /^#/{sub(/^# ?/,""); print; next} {exit}' "${BASH_SOURCE[0]}"
+      exit 0 ;;
+    "")
+      if [ -t 0 ]; then
+        printf 'usage: factory-brief-check.sh <brief-file> | - | --self-test\n' >&2
+        exit 2
+      fi
+      check_brief "$(cat)" "stdin"; exit $? ;;
+    -)  check_brief "$(cat)" "stdin"; exit $? ;;
+    *)
+      if [ ! -f "$1" ]; then
+        printf 'factory-brief-check.sh: no such brief file: %s\n' "$1" >&2
+        exit 2
+      fi
+      check_brief "$(cat "$1")" "$1"; exit $? ;;
+  esac
+}
+
+main "$@"

package/scripts/factory-check.sh

@@ -37,6 +37,23 @@
 # must not assume "broken" — see text/factory.md § A note on "red" vs "cannot
 # run". Never widen a `cannot run` into a `red` to make a chain simpler.
 set -uo pipefail
+
+# _GATE — route a heavy compute through the machine governor. A gate_lock only
+# dedupes IDENTICAL work; a SLOT is what bounds N worktrees each running one of
+# these at once (measured 2026-09-07: three concurrent 2.5GB typecheckers, every
+# lock uncontended, load 171). Empty when already inside a gate, so a nested call
+# inherits the outer slot rather than taking a second one.
+#
+# Resolves gate-run.sh from its OWN directory, deliberately: an earlier version
+# keyed off $ROOT and got inserted above the line that sets it, so _GATE was
+# silently empty and every call ran ungoverned -- a fail-OPEN, which is the exact
+# defect this preamble exists to close.
+_GATE=()
+if [ "${GOVERN_IN_GATE:-0}" != "1" ]; then
+  _GR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/gate-run.sh"
+  [ -f "$_GR" ] && _GATE=( bash "$_GR" "compute:$(basename "${BASH_SOURCE[0]}")" -- )
+fi
+
 ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
 MODE="${1:-all}"
 VERBOSE=0; [[ "${2:-}" == "--verbose" ]] && VERBOSE=1
@@ -375,7 +392,7 @@ check_belief_guard() {
         TYPEDB_USERNAME="${TYPEDB_USERNAME:-}" \
         TYPEDB_PASSWORD="${TYPEDB_PASSWORD:-}" \
         TYPEDB_TEST_DB="${TYPEDB_TEST_DB:-}" \
-        bunx vitest run src/lib/resolvers/learning-evidence.test.ts 2>&1)
+        "${_GATE[@]}" bunx vitest run src/lib/resolvers/learning-evidence.test.ts 2>&1)
   # The scratch db needs the schema loaded; the test defines none of its own. An
   # empty db answers "Type label 'hypothesis' not found", which is cannot-run.
   printf '%s' "$out" | grep -qE "Type label '(hypothesis|group|path)' not found" \

package/scripts/factory-close-check.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+# factory-close-check.sh — did the Close actually land on the board?
+#
+# manifest: needs-env
+#   Reads GATEWAY_API_KEY through ONE_ENV_FILE (default one.ie/web/.env, plus the
+#   monorepo fallbacks). A read it cannot make is exit 3 by name; it never
+#   answers MISSING on evidence it did not get.
+#
+# WHY IT EXISTS. On the first factory run the Close agent RETURNED
+# {"status":"done"} while the board row stayed `picked`
+# (task:01a07591e5c350a306c93933, workspace one, measured 2026-09-06). The
+# executor's result JSON is a claim about an agent, not evidence about the
+# substrate. This reads the row back and prints what the BOARD says, one line.
+#
+# WHY NOT /api/factory/board. Its `?slug=` is a PLAN selector from a closed list
+# (board.ts PLAN_SLUGS = ['factory-do','factory']; planSlug coerces everything
+# else to the default), so `?slug=one` answers for factory-do — measured. And the
+# executor's rows are on neither plan board. readWork is
+# `tasks:everywhere {workspace, limit:200}` anyway, and it deliberately never
+# reads the CLOSED queue, which is the half a close-check needs. So: the same
+# source, one hop earlier, both queues.
+#
+# USAGE  factory-close-check.sh <tid> <workspace>
+#        factory-close-check.sh --self-test [workspace]
+# PRINTS CLOSE tid=<tid> lane=<lane> verdict=<verdict> status=<status>
+# EXITS  0 the row was read
+#        2 both queues answered cleanly and completely, and no such row: MISSING
+#        3 UNREADABLE — a refusal, a truncated answer, an unparseable count, or
+#          zero rows in both queues (subscriptions.ts answers `{ok:true,tasks:[]}`
+#          when env.DB is absent, so an outage and an empty workspace are the same
+#          bytes; that must never become "your task is not there")
+#        4 bad arguments / jq missing
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+ONE_ENV_FILE="${ONE_ENV_FILE:-${DO_ENV_FILE:-one.ie/web/.env}}"
+URL="${FACTORY_EMIT_URL:-${ONE_API_URL:-https://one.ie}}"
+TIMEOUT="${FACTORY_CLOSE_TIMEOUT:-15}"
+# The server's own ceiling: subscriptions.ts is Math.min(data.limit ?? 50, 200),
+# so 200 is the most any caller can ask for. `returned == 200` is therefore the
+# only honest truncation signal — measured 2026-09-06, workspace one answered
+# 100 open rows to a limit of 200 and 100 again to a limit of 500, which is the
+# whole visible set, not a cap.
+LIMIT=200
+
+# ---------------------------------------------------------------------------
+# The row reader. Mirrors toWorkRow (board.ts): the labelled NOTES lines ride
+# first (WORK_LABELS), the `lane:`/`verdict:` TAGS are the fallback for rows a
+# pre-fix close tagged. The label regex and the normalisation are copied from
+# spec-gate.ts LABEL_RE / normaliseLabel — case- and space-insensitive, markdown
+# furniture tolerated, smart quotes folded.
+#
+# ONE deviation, stated out loud: parseLabelledLines appends CONTINUATION lines
+# to the open field; this takes the label line's own value only. For lane and
+# verdict the executor writes single-line values (closePrompt), and a multi-line
+# lane would print here as its first line rather than as a mangled one.
+#
+# `lane=unrecorded` / `verdict=unrun` are deliberate. board.ts says a NULL
+# verdict "renders as unrun, which is not a pass"; an absent lane is not
+# `lane=none`, which is a value the executor actually writes.
+#
+# It lives in a heredoc file, not inline, so the apostrophe inside the label
+# character class never has to survive shell quoting.
+# ---------------------------------------------------------------------------
+_write_jq() {
+  cat > "$1" <<'JQ'
+def lbls:
+  (.notes // "")
+  | split("\n")
+  | map(capture("^[ \t>*#-]*(?<k>[A-Za-z][A-Za-z'‘’ ]{2,24}?)[ \t]*:[ \t]*(?<v>.*)$")?)
+  | map(select(. != null))
+  | map({key: (.k | gsub("[‘’]"; "'") | ascii_downcase | gsub("\\s+"; " ") | gsub("^\\s+|\\s+$"; "")),
+         value: (.v | gsub("^\\s+|\\s+$"; ""))})
+  | from_entries;
+def tagv($p): ([.tags[]? | select(startswith($p))] | .[0] // "") | if . == "" then "" else .[($p|length):] end;
+def pick($a; $b; $d): if ($a // "") != "" then $a elif ($b // "") != "" then $b else $d end;
+. as $t | (lbls) as $l
+| "CLOSE tid=" + $t.id
+  + " lane="    + ((pick($l["lane"];    ($t | tagv("lane:"));    "unrecorded")) | gsub("\\s+"; "_"))
+  + " verdict=" + ((pick($l["verdict"]; ($t | tagv("verdict:")); "unrun"))      | gsub("\\s+"; "_"))
+  + " status="  + (($t.status // "") | if . == "" then "unknown" else . end)
+JQ
+}
+
+_gateway_key() {
+  local f v
+  for f in "$ONE_ENV_FILE" "$ROOT/one.ie/web/.env" "$ROOT/one.ie/web/.dev.vars" "$ROOT/.env"; do
+    [ -f "$f" ] || continue
+    if [ "${FACTORY_EMIT_SKIP_FALLBACKS:-0}" = "1" ] && [ "$f" != "$ONE_ENV_FILE" ]; then continue; fi
+    v="$(grep -E '^GATEWAY_API_KEY=' "$f" 2>/dev/null | head -1 | sed 's/^[^=]*=//;s/^"//;s/"$//')"
+    [ -n "$v" ] && { printf '%s' "$v"; return 0; }
+  done
+  printf ''
+}
+
+# ---------------------------------------------------------------------------
+# --self-test — the local guards, the parser against the REAL close notes, and
+# one network assertion: an impossible tid must be MISSING (exit 2), which is
+# only reachable after a clean two-queue read.
+#
+# THE DISCIPLINE: an UNREADABLE (exit 3) here is a FAILED self-test, never a
+# skip. A checker that goes green because it could not reach the substrate is
+# the exact defect this script was written against.
+# ---------------------------------------------------------------------------
+self_test() {
+  local me="${BASH_SOURCE[0]}" ws="${1:-${FACTORY_CLOSE_SELFTEST_WS:-one}}" fails=0 rc out
+  printf '== factory-close-check --self-test (workspace %s)\n' "$ws"
+
+  _case() {  # label, want-rc, argv...
+    local label="$1" want="$2"; shift 2
+    out="$(bash "$me" "$@" 2>&1)"; rc=$?
+    if [ "$rc" = "$want" ]; then printf '  ok   %-52s exit %s\n' "$label" "$rc"
+    else printf '  FAIL %-52s exit %s, wanted %s\n     %s\n' "$label" "$rc" "$want" "$(printf '%s' "$out" | head -1)" >&2; fails=$((fails+1)); fi
+  }
+
+  _case 'no arguments is REFUSED'                     4
+  _case 'uppercase workspace is REFUSED, not read'    4 task:x One
+  _case 'implausible tid is REFUSED'                  4 'task:$(rm -rf /)' one
+  # Reachable only because SKIP_FALLBACKS exists; without it the monorepo's own
+  # .env answers and the no-credential branch is unreachable.
+  out="$(ONE_ENV_FILE=/dev/null FACTORY_EMIT_SKIP_FALLBACKS=1 bash "$me" task:x "$ws" 2>&1)"; rc=$?
+  if [ "$rc" = 3 ] && printf '%s' "$out" | grep -q 'reason=no-credential'; then
+    printf '  ok   %-52s exit 3\n' 'no credential is UNREADABLE, not MISSING'
+  else
+    printf '  FAIL %-52s exit %s\n     %s\n' 'no credential must be UNREADABLE' "$rc" "$out" >&2; fails=$((fails+1))
+  fi
+
+  # The parser, against the FIRST REAL CLOSE, byte-identical to the fixture in
+  # one.ie/web/src/lib/factory/close-parse.test.ts. Two parsers drift; this is
+  # the line that would go red when WORK_LABELS or LABEL_RE moves.
+  local jqf row got
+  jqf="$(mktemp)"; _write_jq "$jqf"
+  row='{"id":"task:01a07591e5c350a306c93933","status":"picked","tags":[],"notes":"Lane: none\nVerdict: red\nPreview: http://localhost:4325\nCommit: https://github.com/one-ie/one/commit/10a821f97\nHeld: red — see stage lines above\nwalk red (lane none, tier ?) · http://localhost:4325/components · commit 10a821f97 · 2026-09-06T07:18:36Z"}'
+  got="$(printf '%s' "$row" | jq -r -f "$jqf" 2>&1)"
+  rm -f "$jqf"
+  if [ "$got" = "CLOSE tid=task:01a07591e5c350a306c93933 lane=none verdict=red status=picked" ]; then
+    printf '  ok   %-52s\n' 'the real close notes parse as the TS reader does'
+  else
+    printf '  FAIL %-52s\n     got: %s\n' 'parser disagrees with close-parse.test.ts' "$got" >&2; fails=$((fails+1))
+  fi
+
+  # An absent verdict must read `unrun`, never a pass — board.ts's own rule.
+  jqf="$(mktemp)"; _write_jq "$jqf"
+  got="$(printf '%s' '{"id":"t","status":"picked","tags":[],"notes":"Preview: x"}' | jq -r -f "$jqf" 2>&1)"; rm -f "$jqf"
+  if [ "$got" = "CLOSE tid=t lane=unrecorded verdict=unrun status=picked" ]; then
+    printf '  ok   %-52s\n' 'an absent verdict reads unrun, never a pass'
+  else
+    printf '  FAIL %-52s\n     got: %s\n' 'absent verdict did not read unrun' "$got" >&2; fails=$((fails+1))
+  fi
+
+  # THE NETWORK HALF. exit 2 is only reachable through a clean read of BOTH
+  # queues, so this asserts the read as much as the verdict.
+  #
+  # A LINKED WORKTREE HAS NO one.ie/web/.env — it is gitignored and never checked
+  # out. Say that by name and STILL FAIL: an unreachable substrate is a failed
+  # self-test, never a skip, exactly as the exit-3 branch above insists.
+  if [ -z "$(_gateway_key)" ]; then
+    printf '  FAIL %-52s\n' 'no credential — the read half could not be asserted' >&2
+    printf '     SKIP-IMPOSSIBLE: no GATEWAY_API_KEY via %s. This is not a broken script;\n' "$ONE_ENV_FILE" >&2
+    printf '     run --self-test from the MAIN tree, or export ONE_ENV_FILE=<main>/one.ie/web/.env\n' >&2
+    fails=$((fails + 1))
+    printf 'factory-close-check --self-test: RED — %s check(s) failed\n' "$fails" >&2; return 1
+  fi
+  out="$(bash "$me" 'task:0000000000000000000000000' "$ws" 2>&1)"; rc=$?
+  if [ "$rc" = 2 ] && printf '%s' "$out" | grep -q 'MISSING'; then
+    printf '  ok   %-52s exit 2\n' 'an impossible tid is MISSING after a clean read'
+  elif [ "$rc" = 3 ]; then
+    printf '  FAIL %-52s exit 3 — the substrate was NOT read, so this test proved nothing\n     %s\n' \
+      'impossible tid must be MISSING' "$out" >&2; fails=$((fails+1))
+  else
+    printf '  FAIL %-52s exit %s\n     %s\n' 'impossible tid must be MISSING' "$rc" "$out" >&2; fails=$((fails+1))
+  fi
+
+  if [ "$fails" -eq 0 ]; then printf 'factory-close-check --self-test: PASS (7 checks)\n'; return 0; fi
+  printf 'factory-close-check --self-test: RED — %s check(s) failed\n' "$fails" >&2; return 1
+}
+
+case "${1:-}" in
+  --self-test) command -v jq >/dev/null 2>&1 || { echo "factory-close-check: jq not found" >&2; exit 4; }
+               self_test "${2:-}"; exit $? ;;
+  -h|--help)   sed -n '2,32p' "${BASH_SOURCE[0]}"; exit 0 ;;
+esac
+
+TID="${1:-}"; WS="${2:-}"
+[ -n "$TID" ] && [ -n "$WS" ] || { echo "usage: factory-close-check.sh <tid> <workspace>" >&2; exit 4; }
+command -v jq >/dev/null 2>&1 || { echo "factory-close-check: jq not found" >&2; exit 4; }
+# Validated, not escaped — the same shape readWork asserts. The workspace is
+# interpolated into the JSON body below, so this is the injection guard too.
+#
+# ENUMERATED, never a RANGE. Measured on this box 2026-09-06 (bash 3.2,
+# en_US.UTF-8): `case One in *[!a-z0-9-]*)` does NOT match — a glob range uses
+# COLLATION order, which interleaves case, so `One` sailed past this very guard
+# and reached the wire. Caught by --self-test's uppercase case. `-` is LAST in
+# both sets on purpose; anywhere else it forms a range of its own.
+WS_OK='abcdefghijklmnopqrstuvwxyz0123456789-'
+TID_OK='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789:_-'
+case "$WS" in *[!$WS_OK]*|'') echo "factory-close-check: workspace must match ^[a-z0-9-]+$ (got '$WS')" >&2; exit 4 ;; esac
+case "$TID" in *[!$TID_OK]*|'') echo "factory-close-check: implausible tid '$TID'" >&2; exit 4 ;; esac
+
+KEYVAL="$(_gateway_key)"
+[ -n "$KEYVAL" ] || { printf 'CLOSE tid=%s UNREADABLE reason=no-credential file=%s\n' "$TID" "$ONE_ENV_FILE"; exit 3; }
+
+cfg="$(mktemp)"; chmod 600 "$cfg"
+JQF="$(mktemp)"; _write_jq "$JQF"
+trap 'rm -f "$cfg" "$JQF"' EXIT INT TERM
+printf 'header = "Authorization: Bearer %s"\n' "$KEYVAL" > "$cfg"
+
+read_queue() {  # $1 = false | true  (the CLOSED flag)
+  curl -sS -X POST "$URL/api/ask/tasks:everywhere" \
+    -H 'content-type: application/json' --config "$cfg" --max-time "$TIMEOUT" \
+    -d "{\"data\":{\"workspace\":\"$WS\",\"limit\":$LIMIT,\"closed\":$1}}" 2>&1
+}
+open_body="$(read_queue false)"; rc_open=$?
+done_body="$(read_queue true)";  rc_done=$?
+rm -f "$cfg"
+
+# One shape is a read; everything else is UNREADABLE. Measured: a forbidden call
+# is HTTP 200 {"outcome":"result","result":{"ok":false,"error":"forbidden: ..."}}.
+check_read() {  # $1 = body, $2 = rc, $3 = label
+  local why
+  if [ "$2" -ne 0 ]; then printf 'CLOSE tid=%s UNREADABLE reason=curl-rc-%s queue=%s\n' "$TID" "$2" "$3"; exit 3; fi
+  if [ "$(printf '%s' "$1" | jq -r 'if (.outcome == "result" and (.result.ok == true)) then "yes" else "no" end' 2>/dev/null)" != "yes" ]; then
+    why="$(printf '%s' "$1" | jq -r '.reason // .result.error // .result.reason // .error // .hint // empty' 2>/dev/null)"
+    [ -n "$why" ] || why="unparseable body: $(printf '%s' "$1" | head -c 160)"
+    printf 'CLOSE tid=%s UNREADABLE reason=%s queue=%s\n' "$TID" "$why" "$3"; exit 3
+  fi
+}
+check_read "$open_body" "$rc_open" open
+check_read "$done_body" "$rc_done" closed
+
+n_open="$(printf '%s' "$open_body" | jq '.result.tasks | length' 2>/dev/null)"
+n_done="$(printf '%s' "$done_body" | jq '.result.tasks | length' 2>/dev/null)"
+# A count that is not a number would make BOTH arithmetic tests below evaluate
+# false and drop this straight through to MISSING — the house bug in my own
+# arithmetic. It is UNREADABLE by name instead.
+case "${n_open}|${n_done}" in
+  ''|*[!0-9\|]*|'|'*|*'|') printf 'CLOSE tid=%s UNREADABLE reason=unparseable-count open=%s closed=%s\n' "$TID" "${n_open:-none}" "${n_done:-none}"; exit 3 ;;
+esac
+
+row="$(jq -s -c --arg tid "$TID" '[.[] | .result.tasks[]?] | map(select(.id == $tid)) | .[0] // empty' <<EOF
+$open_body
+$done_body
+EOF
+)"
+
+if [ -z "$row" ]; then
+  if [ "$n_open" -ge "$LIMIT" ] || [ "$n_done" -ge "$LIMIT" ]; then
+    printf 'CLOSE tid=%s UNREADABLE reason=answer-truncated open=%s closed=%s limit=%s\n' "$TID" "$n_open" "$n_done" "$LIMIT"; exit 3
+  fi
+  if [ "$n_open" -eq 0 ] && [ "$n_done" -eq 0 ]; then
+    printf 'CLOSE tid=%s UNREADABLE reason=zero-rows-in-both-queues (subscriptions.ts answers ok:true with no rows when env.DB is absent — an outage wears this exact shape)\n' "$TID"; exit 3
+  fi
+  printf 'CLOSE tid=%s MISSING open=%s closed=%s\n' "$TID" "$n_open" "$n_done"; exit 2
+fi
+
+printf '%s' "$row" | jq -r -f "$JQF"
+exit 0