@oneie/claude 0.8.0 → 0.10.0

package/scripts/do-world-check.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# do-world-check.sh — assert every CODE surface a promise's `world.code:` block
+# declares actually EXISTS on disk. Zero LLM; the path's presence is the verdict.
+#
+# WHY: a tag is an address, and the family named after it is what `world:`
+# manifests. `/do` already presence-checks the block's agents, skills, workflow
+# steps and views — but nothing checked for a `.ts`, `.astro` or `.tql` at the
+# tag's name, so a promise could name a code surface it never built and settle
+# green. `world.code:` declares those paths; this gate answers missing/present
+# with the same rule already applied to agents: missing → a cycle · present → skip.
+#
+# SCOPE — `world.code.*` ONLY, and the line is deliberate. The other four kinds
+# (agents · skills · workflow/lifecycle · views) stay the PROSE walk an agent runs
+# at DESIGN/PLAN (.claude/commands/do.md § world, .claude/agents/w1-recon.md);
+# they are named entities, not one deterministic path each. Every key under
+# `code:` is a repo-root-relative path, so every key under `code:` is checkable.
+# Not wired into do-w4-gates.sh or do-promise-settle.sh yet — that is the follow-on.
+#
+# The --self-test fixtures name paths under fixtures/ rather than schema/ only
+# because factory-repo.sh:44 (MONOREPO_PATH_RE) refuses a `portable` script that
+# names a monorepo path. The RED shape is identical either way; the demo C6 asks
+# for — `code.tql` naming an absent schema/<tag>.tql — is recorded verbatim in
+# text/deploy-todo.md § C6.
+#
+# Usage:
+#   do-world-check.sh <slug>          # text/<slug>.md, or $PROMISE_FILE
+#   do-world-check.sh --self-test     # temp fixtures, zero network
+#   exit: 0 all present (or no code: block) · 1 a surface missing · 2 no promise file · 4 bad usage
+set -u
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+
+# print "<key>\t<path>" for every path declared under world: → code:.
+# Two levels of nesting, so the col-0 terminator alone is not enough: the walk
+# tracks indentation. Both YAML list forms are read — flow (`tql: [a, b]`) and
+# block (`tql:` then `- a`) — and a trailing ` # comment` is stripped.
+code_entries() { # $1 = promise file
+  awk '
+    function indent(s,   n) { n = match(s, /[^ ]/); return n ? n - 1 : -1 }
+    function clean(v) {
+      sub(/[ \t]+#.*$/, "", v)                 # trailing comment
+      gsub(/^[ \t]+|[ \t]+$/, "", v)
+      gsub(/^["'"'"']|["'"'"']$/, "", v)       # one layer of quoting
+      return v
+    }
+    function emit(k, v) { v = clean(v); if (v != "") printf "%s\t%s\n", k, v }
+    function emit_flow(k, v,   n, i, parts) {
+      sub(/^\[/, "", v); sub(/\].*$/, "", v)
+      n = split(v, parts, ",")
+      for (i = 1; i <= n; i++) emit(k, parts[i])
+    }
+    /^---[ \t]*$/ { fm++; if (fm >= 2) exit; next }
+    fm != 1 { next }
+    /^world:[ \t]*$/ { inw = 1; next }
+    inw && /^[^ \t#]/ { inw = 0; inc = 0; key = "" }     # a col-0 key ends world:
+    !inw { next }
+    /^[ \t]*$/ { next }
+    /^[ \t]*#/ { next }
+    {
+      i = indent($0)
+      if (inc && i <= 2) { inc = 0; key = "" }            # a sibling of code: ends it
+      if (!inc) { if ($0 ~ /^[ \t]*code:[ \t]*(#.*)?$/ && i == 2) { inc = 1; key = "" } ; next }
+      if (i < 4) next
+      if ($0 ~ /^[ \t]*-[ \t]/) {                         # block list item
+        if (key == "") next
+        line = $0; sub(/^[ \t]*-[ \t]*/, "", line); emit(key, line); next
+      }
+      if (match($0, /^[ \t]*[A-Za-z][A-Za-z0-9_-]*:/)) {  # a code: sub-key
+        key = $0; sub(/^[ \t]*/, "", key); sub(/:.*$/, "", key)
+        rest = $0; sub(/^[ \t]*[A-Za-z][A-Za-z0-9_-]*:[ \t]*/, "", rest)
+        if (rest ~ /^\[/) { emit_flow(key, rest); key = "" }
+        else emit(key, rest)
+      }
+    }
+  ' "$1"
+}
+
+check() { # $1 = slug
+  local slug="$1"
+  local file="${PROMISE_FILE:-$ROOT/text/$slug.md}" missing=0 checked=0 line key path
+  if [ ! -f "$file" ]; then
+    echo "[world-check] $slug — no promise file at text/$slug.md"; return 2
+  fi
+  while IFS="$(printf '\t')" read -r key path; do
+    [ -z "${path:-}" ] && continue
+    checked=$((checked+1))
+    if [ -e "$ROOT/$path" ]; then
+      echo "[world-check] ok: world.code.$key → $path"
+    else
+      echo "[world-check] MISSING: world.code.$key declares $path — no such path"
+      missing=$((missing+1))
+    fi
+  done <<EOF
+$(code_entries "$file")
+EOF
+  if [ "$checked" -eq 0 ]; then
+    echo "[world-check] $slug — no world.code: surfaces declared (nothing to check)"; return 0
+  fi
+  if [ "$missing" -gt 0 ]; then
+    echo "[world-check] $slug — $missing/$checked declared code surface(s) missing"; return 1
+  fi
+  echo "[world-check] $slug — ok ($checked declared code surface(s) present)"; return 0
+}
+
+if [ "${1:-}" = "--self-test" ]; then
+  dir="$(mktemp -d)"; trap 'rm -rf "$dir"' EXIT
+  mkdir -p "$dir/text" "$dir/fixtures"
+  fails=0
+  : >"$dir/fixtures/green.tql"; : >"$dir/fixtures/green.astro"
+  # green: flow list + block list, every declared path on disk
+  cat >"$dir/text/green.md" <<'YAML'
+---
+slug: green
+world:
+  agents:
+    - { name: doctor, subscribes: [health] }
+  code:                    # a trailing comment on the key must not hide the block
+    tql: [fixtures/green.tql]
+    astro:
+      - fixtures/green.astro   # a trailing comment must not break the path
+  tracking:
+    marks: ["a nested sibling at indent 4 must not read as a code surface"]
+  views: []
+---
+YAML
+  # red: a declared .tql that was never written
+  cat >"$dir/text/red.md" <<'YAML'
+---
+slug: red
+world:
+  code:
+    tql: [fixtures/nonexistent-zzz.tql]
+---
+YAML
+  # bare: a world: block with no code: — passes, checks nothing
+  printf -- '---\nslug: bare\nworld:\n  agents: []\n---\n' >"$dir/text/bare.md"
+  out="$(ROOT="$dir" PROMISE_FILE= check green 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || { echo "FAIL green should pass: $out"; fails=$((fails+1)); }
+  case "$out" in *"ok (2 declared"*) ;; *) echo "FAIL green must count 2 surfaces: $out"; fails=$((fails+1)) ;; esac
+  out="$(ROOT="$dir" PROMISE_FILE= check red 2>&1)"; rc=$?
+  [ "$rc" -eq 1 ] || { echo "FAIL red should fail: $out"; fails=$((fails+1)); }
+  case "$out" in *"MISSING: world.code.tql"*) ;; *) echo "FAIL red must name the path: $out"; fails=$((fails+1)) ;; esac
+  out="$(ROOT="$dir" PROMISE_FILE= check bare 2>&1)"; rc=$?
+  [ "$rc" -eq 0 ] || { echo "FAIL bare should pass: $out"; fails=$((fails+1)); }
+  case "$out" in *"nothing to check"*) ;; *) echo "FAIL bare must say nothing to check: $out"; fails=$((fails+1)) ;; esac
+  echo "[world-check] self-test: 3 fixtures, $fails failed"
+  exit "$fails"
+fi
+
+SLUG="${1:-}"
+[ -z "$SLUG" ] && { echo "usage: do-world-check.sh <slug> | --self-test" >&2; exit 4; }
+PROMISE_FILE="${PROMISE_FILE:-}"
+check "$SLUG"

package/scripts/download-stats.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# download-stats.sh — every lifetime reach number we can prove, in one table.
+#
+#   bash .claude/scripts/download-stats.sh              # print
+#   bash .claude/scripts/download-stats.sh --write      # + record to text/download-stats.md
+#   bash .claude/scripts/download-stats.sh --json
+#   bash .claude/scripts/download-stats.sh --self-test
+#
+# manifest: needs-env — (npm + gh + network; writes only text/download-stats.md)
+#
+# FOLDS IN npm-downloads.sh, which this replaces. Both of that script's traps
+# are live here and neither is obvious:
+#
+#   1. npm's downloads API REFUSES a range longer than 18 months — and answers
+#      that refusal with HTTP 200 and an `error` field. A naive all-time query
+#      therefore returns nothing useful without failing. All-time is a WALK: from
+#      each package's first publish (registry `time.created`), 17 months at a
+#      time, summed. Read `.error`, never the status code.
+#   2. A scoped name must be percent-encoded — `@oneie%2Fsdk`. Unencoded, the
+#      slash reads as a path separator and the API 404s, which deserialises to a
+#      zero indistinguishable from a real one. Encoded once, in enc().
+#
+# And one about WHICH packages: the list comes from the REGISTRY (search by
+# maintainer), not from manifests on disk and not from `npm access list
+# packages` — that returns EMPTY under a granular token (measured 2026-09-14:
+# "packages in scope: 0" while all 30 were readable). Reading manifests misses
+# every package not in this repo, which was 10 of 30 — including `oneie` at
+# 13,117 downloads, the single most-downloaded package we have.
+#
+# WHY A RECORDED .md: npm's per-day history is queryable back to a package's
+# first publish, so npm needs no ledger. GitHub traffic is different — it keeps
+# FOURTEEN DAYS and offers no backfill (see gh-traffic-capture.sh). The .md is
+# the durable, committed, human-readable record; the gitignored ledger is the
+# daily machine one. A snapshot appended here survives a dead laptop.
+#
+# HONESTY, because these numbers are for social proof and will be checked:
+# npm counts mirrors, CI and crawlers. "57,819 downloads" is defensible;
+# "57,819 developers" is a lie. The table separates the current @oneie scope
+# from retired lines so a headline can be sourced to the right subtotal.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+OUT="$ROOT/text/download-stats.md"
+MAINTAINER="${NPM_MAINTAINER:-oneie}"
+ORG="${GH_ORG:-one-ie}"
+MODE=print
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --write) MODE=write ;;
+    --json)  MODE=json ;;
+    --self-test) MODE=selftest ;;
+    -h|--help) sed -n '2,8p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) echo "download-stats.sh: unknown flag '$1'" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+command -v jq >/dev/null || { echo "download-stats.sh: needs jq" >&2; exit 2; }
+
+enc() { printf '%s' "${1/\//%2F}"; }                       # @oneie/sdk -> @oneie%2Fsdk
+today() { date -u '+%Y-%m-%d'; }
+add_months() { date -j -v+"$2"m -f '%Y-%m-%d' "$1" '+%Y-%m-%d' 2>/dev/null || date -d "$1 + $2 months" '+%Y-%m-%d' 2>/dev/null; }
+
+# all_time <pkg> — the 17-month walk described above.
+all_time() {
+  local p="$1" e c created start end total=0 body err n
+  e="$(enc "$p")"
+  created="$(npm view "$p" time.created 2>/dev/null | head -1 | cut -c1-10)"
+  [[ -n "$created" ]] || created="2024-01-01"
+  start="$created"; end="$(today)"; cursor="$start"
+  while [[ "$cursor" < "$end" ]]; do
+    stop="$(add_months "$cursor" 17)"
+    [[ -z "$stop" || "$stop" > "$end" ]] && stop="$end"
+    body="$(curl -sS --max-time 25 "https://api.npmjs.org/downloads/point/${cursor}:${stop}/${e}" 2>/dev/null)"
+    err="$(printf '%s' "$body" | jq -r '.error // empty' 2>/dev/null)"
+    if [[ -z "$err" ]]; then
+      n="$(printf '%s' "$body" | jq -r '.downloads // 0' 2>/dev/null)"
+      [[ "$n" =~ ^[0-9]+$ ]] && total=$(( total + n ))
+    fi
+    [[ "$stop" == "$end" ]] && break
+    cursor="$stop"
+  done
+  printf '%s|%s' "$total" "$created"
+}
+
+if [[ "$MODE" == selftest ]]; then
+  fails=0
+  [[ "$(enc '@oneie/sdk')" == '@oneie%2Fsdk' ]] || { echo "  FAIL: scoped name not encoded"; fails=1; }
+  [[ "$(enc 'oneie')" == 'oneie' ]] || { echo "  FAIL: unscoped name mangled"; fails=1; }
+  [[ -n "$(add_months 2026-01-01 17)" ]] || { echo "  FAIL: add_months returned nothing"; fails=1; }
+  # the 18-month refusal must be READ, not inferred from the status code
+  b="$(curl -sS --max-time 20 "https://api.npmjs.org/downloads/point/2000-01-01:$(today)/npm" 2>/dev/null)"
+  [[ -n "$(printf '%s' "$b" | jq -r '.error // empty')" ]] \
+    || { echo "  NOTE: the >18mo range did not error — the walk is still correct, the guard is just untested here"; }
+  (( fails )) && { echo "download-stats.sh: self-test FAILED"; exit 1; }
+  echo "download-stats.sh: self-test PASS"; exit 0
+fi
+
+# ── npm ──────────────────────────────────────────────────────────────────────
+pkgs="$(curl -sS --max-time 30 "https://registry.npmjs.org/-/v1/search?text=maintainer:${MAINTAINER}&size=250" 2>/dev/null | jq -r '.objects[].package.name' | sort)"
+[[ -n "$pkgs" ]] || { echo "download-stats.sh: registry search returned no packages for maintainer:${MAINTAINER}" >&2; exit 1; }
+
+rows="[]"
+while IFS= read -r p; do
+  [[ -n "$p" ]] || continue
+  at="$(all_time "$p")"
+  wk="$(curl -sS --max-time 15 "https://api.npmjs.org/downloads/point/last-week/$(enc "$p")" 2>/dev/null | jq -r '.downloads // 0')"
+  ver="$(npm view "$p" version 2>/dev/null | tail -1)"
+  rows="$(printf '%s' "$rows" | jq --arg p "$p" --arg v "$ver" --arg c "${at##*|}" \
+          --argjson t "${at%%|*}" --argjson w "${wk:-0}" \
+          '. + [{package:$p,version:$v,since:$c,all_time:$t,last_week:$w,scoped:($p|startswith("@"))}]')"
+done <<< "$pkgs"
+
+NPM_ALL="$(printf '%s' "$rows" | jq '[.[].all_time]|add // 0')"
+NPM_WK="$(printf '%s' "$rows" | jq '[.[].last_week]|add // 0')"
+NPM_SCOPED="$(printf '%s' "$rows" | jq '[.[]|select(.scoped)|.all_time]|add // 0')"
+NPM_COUNT="$(printf '%s' "$rows" | jq 'length')"
+
+# ── github ───────────────────────────────────────────────────────────────────
+repos="$(gh api "orgs/$ORG/repos?per_page=100&type=public" 2>/dev/null)"
+GH_STARS="$(printf '%s' "$repos" | jq '[.[].stargazers_count]|add // 0')"
+GH_FORKS="$(printf '%s' "$repos" | jq '[.[].forks_count]|add // 0')"
+GH_REPOS="$(printf '%s' "$repos" | jq 'length')"
+GH_CLONES=0; GH_UNIQ=0
+while IFS= read -r r; do
+  [[ -n "$r" ]] || continue
+  t="$(gh api "repos/$r/traffic/clones" --jq '"\(.count) \(.uniques)"' 2>/dev/null)" || continue
+  GH_CLONES=$(( GH_CLONES + ${t%% *} )); GH_UNIQ=$(( GH_UNIQ + ${t##* } ))
+done < <(printf '%s' "$repos" | jq -r '.[].full_name')
+
+if [[ "$MODE" == json ]]; then
+  jq -n --argjson pkgs "$rows" --arg d "$(today)" \
+    --argjson na "$NPM_ALL" --argjson nw "$NPM_WK" --argjson ns "$NPM_SCOPED" --argjson nc "$NPM_COUNT" \
+    --argjson gs "$GH_STARS" --argjson gf "$GH_FORKS" --argjson gr "$GH_REPOS" \
+    --argjson gc "$GH_CLONES" --argjson gu "$GH_UNIQ" \
+    '{date:$d, npm:{packages:$nc, all_time:$na, scope_all_time:$ns, last_week:$nw, rows:$pkgs},
+      github:{repos:$gr, stars:$gs, forks:$gf, clones_14d:$gc, unique_cloners_14d:$gu}}'
+  exit 0
+fi
+
+emit() {
+  printf '# Download stats\n\n'
+  printf '_Measured %s by `.claude/scripts/download-stats.sh`. Every figure is re-derivable — no number here was typed by hand._\n\n' "$(today)"
+  printf '## Headline\n\n| metric | value | source |\n|---|---:|---|\n'
+  printf '| npm downloads, all time | **%s** | downloads API, per package since first publish |\n' "$NPM_ALL"
+  printf '| npm downloads, `@%s` scope | **%s** | the current product line only |\n' "$MAINTAINER" "$NPM_SCOPED"
+  printf '| npm downloads, last week | %s | downloads API |\n' "$NPM_WK"
+  printf '| packages published | **%s** | registry, maintainer `%s` |\n' "$NPM_COUNT" "$MAINTAINER"
+  printf '| GitHub stars | **%s** | %s public repos, org-wide |\n' "$GH_STARS" "$GH_REPOS"
+  printf '| GitHub forks | %s | org-wide |\n' "$GH_FORKS"
+  printf '| unique cloners, 14d | **%s** | %s clones — GitHub keeps only 14 days |\n\n' "$GH_UNIQ" "$GH_CLONES"
+  printf '## Packages\n\n| package | version | all time | last week | since |\n|---|---|---:|---:|---|\n'
+  printf '%s' "$rows" | jq -r 'sort_by(-.all_time)[] | "| `\(.package)` | \(.version) | \(.all_time) | \(.last_week) | \(.since) |"'
+  printf '\n## Using these for social proof\n\n'
+  printf 'npm counts mirrors, CI and crawlers alongside people. **%s downloads** is defensible; ' "$NPM_ALL"
+  printf '"%s developers" is not — say downloads, or cite unique cloners (**%s in 14 days**), which are closer to humans.\n\n' "$NPM_ALL" "$GH_UNIQ"
+  printf 'The all-time total spans retired lines as well as the current one. For claims about the product as it stands today, '
+  printf 'the honest subtotal is the **`@%s` scope: %s**.\n\n' "$MAINTAINER" "$NPM_SCOPED"
+  printf '## What cannot be recovered\n\n'
+  printf 'GitHub keeps **14 days** of clone and view traffic and offers no backfill, so all-time clones do not exist for any repo. '
+  printf '`.claude/scripts/gh-traffic-capture.sh` runs daily to stop further days being lost; everything before its first run is gone.\n'
+}
+
+if [[ "$MODE" == write ]]; then
+  mkdir -p "$(dirname "$OUT")"
+  emit > "$OUT"
+  echo "  ✓ recorded → text/download-stats.md ($(wc -l < "$OUT" | tr -d ' ') lines)"
+  echo "    npm all-time=$NPM_ALL  scope=$NPM_SCOPED  packages=$NPM_COUNT  stars=$GH_STARS  uniq-cloners-14d=$GH_UNIQ"
+else
+  emit
+fi

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 "$@"