@oneie/claude 0.7.0 → 0.8.0

package/scripts/do-prove.sh

@@ -19,9 +19,32 @@
 #   PROVE_PROD_URL   prod fallback base       (default https://one.ie)
 #   PROVE_CHECK_CMD  optional check command for non-frontend surfaces; if set and
 #                    it fails, do-prove.sh exits nonzero.
+#   PROVE_SESSION_COOKIE
+#                    `name=value` session cookie, sent on BOTH legs — chrome.mjs
+#                    already reads this env var itself; the curl leg now sends it
+#                    as a Cookie header. Needed to prove any authed route
+#                    (anything under /u/<slug>/…). Against a LOCAL dev base it is
+#                    acquired automatically via one.ie/web/scripts/dev-sign-in.ts
+#                    so a promise's proof: still runs in a bare shell; set it by
+#                    hand for a remote base. Sent to a localhost base only — the
+#                    prod fallback leg never carries it.
+#   PROVE_NO_SESSION=1
+#                    skip session acquisition — the documented way to drive the
+#                    landing rule red on demand (`--route /u/one/tasks` then fails
+#                    with "landed on /signin"). Without it the red state is only
+#                    reachable when sign-in itself fails.
+#
+# LANDING RULE (2026-08-04): a route is proven only if the browser/curl ENDED UP
+# on the path that was asked for. Measured: `--route /u/one/tasks` signed-out
+# 302s to /signin, which renders 200 with zero console errors — so do-prove
+# reported "ok" and a promise's proof clause went green on the sign-in page. The
+# tasks page was never loaded. Every authed `/u/one/*` clause in the corpus had
+# the same hole. Path is compared without query or trailing slash, so
+# `/u/one/in?dest=tasks` still proves itself.
 #
 # Exit codes: 0 = pass or skipped (no reachable environment) · 1 = a reachable
-# page failed (HTTP >= 500 / status 0 / console+JS errors) or declared check failed.
+# page failed (HTTP >= 500 / 404 / status 0 / console+JS errors / landed on a
+# different path than requested) or declared check failed.
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
@@ -130,8 +153,116 @@ routes=("${deduped[@]}")
 dev_up=0
 if curl -sf -o /dev/null --max-time 4 "$BASE_URL/" 2>/dev/null; then dev_up=1; fi
 
-check_route_curl() { # $1 = base, $2 = route → echoes http code
-  curl -s -o /dev/null --max-time 20 -w '%{http_code}' "$1$2" 2>/dev/null || echo "000"
+# A session turns "the sign-in page rendered" into "the page under test rendered".
+# chrome.mjs reads PROVE_SESSION_COOKIE from the environment on its own (it is
+# inherited by the `node` call below); the curl leg needs it passed explicitly.
+#
+# Auto-acquire against a LOCAL dev server only. A promise's proof: has to run in
+# a bare shell — that is the whole point of the kill-switch — so requiring a
+# human to export a cookie first would just move the fail-open one level up.
+# Strictly gated: localhost/127.0.0.1 base, dev-sign-in.ts present, no cookie
+# already set. Never against a remote host, and the value is never echoed.
+_prove_local_base() {
+  case "$BASE_URL" in
+    http://localhost:*|http://localhost|http://127.0.0.1:*|http://127.0.0.1) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+# LAZY, and only on a /signin bounce. Signing in up front changes the answer for
+# routes that were already fine: locally, DEV_SLUG lets a signed-out request
+# render /u/one/* as workspace `one`, while a real session is tony@one.ie — so
+# an eager session turned `--route /u/one/workflows` from a genuine pass into
+# "landed on /u/tony/workflows". Measured 2026-08-04. Try signed-out first; only
+# a bounce to the login wall is worth a second attempt.
+#
+# PROVE_NO_SESSION=1 disables the retry entirely. Without it the landing rule's
+# red half is only reachable when sign-in itself fails, i.e. by accident — and a
+# gate nobody can drive red on demand is what this whole change exists to
+# prevent. The documented two-line matrix:
+#   PROVE_NO_SESSION=1 do-prove.sh --route /u/one/tasks   → FAIL, landed on /signin
+#                      do-prove.sh --route /u/one/tasks   → ok (retried with a session)
+_session_tried=0
+prove_acquire_session() { # → 0 if a cookie is now available, 1 otherwise
+  [ -n "${PROVE_SESSION_COOKIE:-}" ] && return 0
+  [ -n "${PROVE_NO_SESSION:-}" ] && return 1
+  [ "$_session_tried" -eq 1 ] && return 1
+  _session_tried=1
+  _prove_local_base || return 1
+  local c=""
+  # Preferred: the repo's own script. It seeds the credential in local D1 first,
+  # so it only works from a tree that has .wrangler/state — i.e. the main tree,
+  # which is where promise proofs actually run.
+  if [ -f "$ROOT/one.ie/web/scripts/dev-sign-in.ts" ] && command -v bun >/dev/null 2>&1; then
+    c="$( (cd "$ROOT/one.ie/web" && bun scripts/dev-sign-in.ts 2>/dev/null) \
+          | sed -n 's/^Set-Cookie: //p' | head -1 || true)"
+  fi
+  # Fallback for a worktree (no local D1 state): plain HTTP sign-in, but only
+  # with credentials the caller supplied. No password is hardcoded here —
+  # one.ie/web/scripts/dev-sign-in.ts stays the single source of the dev creds.
+  if [ -z "$c" ] && [ -n "${OWNER_EMAIL:-}" ] && [ -n "${DEV_PASSWORD:-}" ]; then
+    c="$(curl -s -D - -o /dev/null --max-time 20 -X POST \
+           -H 'Content-Type: application/json' -H "Origin: $BASE_URL" \
+           --data "{\"email\":\"${OWNER_EMAIL}\",\"password\":\"${DEV_PASSWORD}\"}" \
+           "$BASE_URL/api/auth/sign-in/email" 2>/dev/null \
+         | sed -n 's/^[Ss]et-[Cc]ookie: \(better-auth\.session_token=[^;]*\).*/\1/p' | head -1 || true)"
+  fi
+  [ -z "$c" ] && return 1
+  export PROVE_SESSION_COOKIE="$c"
+  curl_auth=(-H "Cookie: $c")
+  echo "PROVE: signed-out run hit the login wall — retrying with a dev session"
+  return 0
+}
+
+# A login wall is the one landing worth a retry; anything else is a real answer.
+is_signin_path() {
+  case "$1" in /signin|/login|/sign-in) return 0 ;; *) return 1 ;; esac
+}
+
+curl_auth=()
+[ -n "${PROVE_SESSION_COOKIE:-}" ] && curl_auth=(-H "Cookie: ${PROVE_SESSION_COOKIE}")
+
+check_route_curl() { # $1 = base, $2 = route → echoes "<http_code> <final_url>"
+  # -L on purpose: a redirect is followed so the LANDING RULE can see where it
+  # ended up. Without it every 302 read as a bare 3xx and the old code scored
+  # that as "ok — not >=500, not 404", which is how a signed-out authed route
+  # proved itself green.
+  # The session cookie goes to a LOCAL base only. Auto-acquire is already
+  # localhost-gated, but a hand-exported PROVE_SESSION_COOKIE is not — and this
+  # same function serves the prod fallback below, so without this check a dev
+  # server being down would send a live session cookie to $PROD_URL.
+  local auth=()
+  case "$1" in
+    http://localhost|http://localhost:*|http://127.0.0.1|http://127.0.0.1:*)
+      auth=("${curl_auth[@]+"${curl_auth[@]}"}") ;;
+  esac
+  curl -sL -o /dev/null --max-time 20 "${auth[@]+"${auth[@]}"}" \
+    -w '%{http_code} %{url_effective}' "$1$2" 2>/dev/null || echo "000 "
+}
+
+# Pathname only — no scheme/host, no query, no fragment, no trailing slash.
+# The landing rule compares these, so `/u/one/in?dest=tasks` matches its own
+# redirect-free landing and a bounce to /signin does not.
+path_of() {
+  local u="$1" rest
+  case "$u" in
+    *://*) rest="${u#*://}"
+           case "$rest" in
+             */*) u="/${rest#*/}" ;;
+             *)   u="/" ;;
+           esac ;;
+  esac
+  u="${u%%\?*}"; u="${u%%#*}"
+  case "$u" in ""|"/") printf '/' ;; *) printf '%s' "${u%/}" ;; esac
+}
+
+# One place decides what a wrong landing means, so both legs say the same thing.
+report_redirect() { # $1 = route, $2 = landed path, $3 = leg label
+  echo "PROVE: FAIL $1 — landed on $2, not $(path_of "$1") ($3) — the page under test never rendered"
+  case "$2" in
+    /signin|/login|/sign-in)
+      echo "PROVE:   hint: authed route — export PROVE_SESSION_COOKIE='better-auth.session_token=…'"
+      echo "PROVE:         (cd one.ie/web && bun scripts/dev-sign-in.ts prints one)" ;;
+  esac
 }
 
 fail=0
@@ -154,34 +285,95 @@ for route in "${routes[@]}"; do
     # "Failed to load resource: … 401", which curl had always passed. Everything
     # else still counts — uncaught JS, real console.error, and subresource
     # 404/5xx, which are genuine breakage.
-    counted='((.jsErrors // []) + ((.consoleErrors // []) | map(select(test("status of (401|403)") | not))))'
+    # 400 joins the same carve-out for the same reason: Layout.astro fires a
+    # fire-and-forget tracking beacon (/api/follow) on every page, and it
+    # answers 400 missing_slug on any page outside a tenant workspace — measured
+    # on /, /components and prod one.ie/components identically (2026-08-07,
+    # livekit C5). The beacon's failure has no bearing on the page; it is
+    # gated-by-context the same way 401/403 is gated-by-session.
+    counted='((.jsErrors // []) + ((.consoleErrors // []) | map(select(test("status of (400|401|403)") | not))))'
+    # Against a LOCAL base only, a subresource 503 joins that list. Plain
+    # `astro dev` binds no Durable Objects, so /api/analytics answers 503
+    # intermittently — measured 2026-08-04 at roughly 1 load in 4, which made the
+    # types-views proof flip GREEN/GREEN/RED across three identical sweeps. Same
+    # reasoning as the 401/403 policy above: the environment is limited, the page
+    # is not broken. Scoped to localhost so a 503 in prod still fails, and every
+    # ignored one is PRINTED below rather than silently dropped. `dev:wrangler`
+    # binds the DOs and makes this moot.
+    if _prove_local_base; then
+      counted='((.jsErrors // []) + ((.consoleErrors // []) | map(select(test("status of (400|401|403|503)") | not))))'
+      ignored='((.consoleErrors // []) | map(select(test("status of 503"))) | length)'
+    else
+      ignored='0'
+    fi
     errs="$(printf '%s' "$out" | jq -r "$counted | length" 2>/dev/null || echo "")"
+    final="$(printf '%s' "$out" | jq -r '.finalUrl // ""' 2>/dev/null || echo "")"
+    # Hit the login wall signed-out? That is the one case a session can change,
+    # so retry once. Any other landing is the real answer and is left alone.
+    if is_signin_path "$(path_of "${final:-$route}")" && prove_acquire_session; then
+      out="$(node "$BROWSER_CHECK" "$BASE_URL$route" 2>/dev/null || true)"
+      status="$(printf '%s' "$out" | jq -r '.httpStatus // 0' 2>/dev/null || echo 0)"
+      errs="$(printf '%s' "$out" | jq -r "$counted | length" 2>/dev/null || echo "")"
+      final="$(printf '%s' "$out" | jq -r '.finalUrl // ""' 2>/dev/null || echo "")"
+    fi
+    # One retry when the ONLY complaint is console errors on an otherwise correct
+    # landing. Vite's first load after it pulls a new dep throws `useState of
+    # null` / "more than one copy of React" and they vanish once the optimizer
+    # settles (learnings 2026-08-02). Measured 2026-08-04: the same /u/one/tasks
+    # proof came back exit=1 then exit=0 with no edit in between — a gate that
+    # flips on a re-run cannot settle a promise. Status and landing failures are
+    # NOT retried; a genuinely broken page fails both runs, so this kills the
+    # flake without buying a flaky pass.
+    landed="$(path_of "${final:-$route}")"
+    if [ -n "$status" ] && [ "$status" != "0" ] && [ -n "$errs" ] && [ "$errs" -gt 0 ] \
+       && [ "$status" -lt 500 ] && [ "$status" -ne 404 ] && [ "$landed" = "$(path_of "$route")" ]; then
+      out="$(node "$BROWSER_CHECK" "$BASE_URL$route" 2>/dev/null || true)"
+      status="$(printf '%s' "$out" | jq -r '.httpStatus // 0' 2>/dev/null || echo 0)"
+      errs="$(printf '%s' "$out" | jq -r "$counted | length" 2>/dev/null || echo "")"
+      final="$(printf '%s' "$out" | jq -r '.finalUrl // ""' 2>/dev/null || echo "")"
+    fi
     if [ -n "$status" ] && [ "$status" != "0" ] && [ -n "$errs" ]; then
       proved=1; checked=$((checked+1))
+      landed="$(path_of "${final:-$route}")"
+      # LANDING RULE first — a bounce to /signin renders 200 with zero errors, so
+      # every check below it would pass on a page that is not the one requested.
       # 404 IS A FAIL here too. The curl leg below learned this on 2026-07-29;
       # the browser leg never did, so a nonexistent route proved itself green
       # whenever the page also logged no errors. 401/403 stay ok — gated, not gone.
-      if [ "$status" -ge 500 ] || [ "$status" -eq 404 ] || [ "$errs" -gt 0 ]; then
+      if [ -n "$final" ] && [ "$landed" != "$(path_of "$route")" ]; then
+        report_redirect "$route" "$landed" "dev $BASE_URL"
+        fail=1
+      elif [ "$status" -ge 500 ] || [ "$status" -eq 404 ] || [ "$errs" -gt 0 ]; then
         echo "PROVE: FAIL $route — http=$status console/js errors=$errs (dev $BASE_URL)"
         printf '%s' "$out" | jq -r "$counted[]" 2>/dev/null | head -5 | sed 's/^/PROVE:   error: /'
         fail=1
       else
         echo "PROVE: ok $route — http=$status, 0 console/js errors (dev $BASE_URL)"
       fi
+      # Never silent: an ignored error is still an error someone should see.
+      ign="$(printf '%s' "$out" | jq -r "$ignored" 2>/dev/null || echo 0)"
+      [ "${ign:-0}" -gt 0 ] 2>/dev/null && \
+        echo "PROVE:   note — $ign subresource 503(s) ignored (no DO bindings in vite dev; dev:wrangler for DO parity)"
     fi
     # status 0 / unparsable = environmental (browser-check couldn't run) → fall through
   fi
   if [ "$proved" -eq 0 ] && [ "$dev_up" -eq 1 ]; then
     # dev reachable but playwright unavailable → curl the dev route
-    code="$(check_route_curl "$BASE_URL" "$route")"
+    read -r code effective <<< "$(check_route_curl "$BASE_URL" "$route")"
+    if is_signin_path "$(path_of "${effective:-$route}")" && prove_acquire_session; then
+      read -r code effective <<< "$(check_route_curl "$BASE_URL" "$route")"
+    fi
     if [ "$code" != "000" ]; then
       proved=1; checked=$((checked+1))
-      # 404 IS A FAIL. It used to report `ok` — only >=500 failed — so a route
-      # that does not exist proved itself. Measured 2026-07-29: `--route /factory`
-      # returned "ok /factory — http=404" against a dev server running a tree
-      # without the page, and that line was the 17th leg of a promise's proof.
-      # 401/403 stay ok: the route exists and answered, it is merely gated.
-      if [ "$code" -ge 500 ] || [ "$code" -eq 404 ]; then
+      landed="$(path_of "${effective:-$route}")"
+      # LANDING RULE, then 404. 404 IS A FAIL: it used to report `ok` — only >=500
+      # failed — so a route that does not exist proved itself. Measured 2026-07-29:
+      # `--route /factory` returned "ok /factory — http=404" against a dev server
+      # running a tree without the page, and that line was the 17th leg of a
+      # promise's proof. 401/403 stay ok: the route answered, it is merely gated.
+      if [ -n "$effective" ] && [ "$landed" != "$(path_of "$route")" ]; then
+        report_redirect "$route" "$landed" "dev $BASE_URL, curl"; fail=1
+      elif [ "$code" -ge 500 ] || [ "$code" -eq 404 ]; then
         echo "PROVE: FAIL $route — http=$code (dev $BASE_URL, curl)"; fail=1
       else
         echo "PROVE: ok $route — http=$code (dev $BASE_URL, curl)"
@@ -189,12 +381,16 @@ for route in "${routes[@]}"; do
     fi
   fi
   if [ "$proved" -eq 0 ]; then
-    code="$(check_route_curl "$PROD_URL" "$route")"
+    read -r code effective <<< "$(check_route_curl "$PROD_URL" "$route")"
     if [ "$code" != "000" ]; then
       checked=$((checked+1))
-      # Same rule as the dev branch above — a 404 in production is the clearest
-      # possible "not shipped", and it must not read as proven.
-      if [ "$code" -ge 500 ] || [ "$code" -eq 404 ]; then
+      # Same rules as the dev branch above — a redirect off the requested path
+      # proves the wrong page, and a 404 in production is the clearest possible
+      # "not shipped". Neither may read as proven.
+      landed="$(path_of "${effective:-$route}")"
+      if [ -n "$effective" ] && [ "$landed" != "$(path_of "$route")" ]; then
+        report_redirect "$route" "$landed" "prod $PROD_URL"; fail=1
+      elif [ "$code" -ge 500 ] || [ "$code" -eq 404 ]; then
         echo "PROVE: FAIL $route — http=$code (prod $PROD_URL)"; fail=1
       else
         echo "PROVE: ok $route — http=$code (prod $PROD_URL)"

package/scripts/do-rank.py

@@ -96,6 +96,19 @@ def deliverable_dirs(text):
     dirs = set()
     for tok in deliverable_paths(text):
         parts = tok.split("/")
+        # `text/` is the ONE family where the containing-dir rule is wrong. The
+        # coupling argument above holds for code (two plans in one component family
+        # clobber each other); it does not hold here, because text/ is one flat dir
+        # of per-slug documents — `text/<slug>-docs.md` is named after the plan that
+        # owns it, so two plans there edit two different files BY CONSTRUCTION and
+        # cannot collide. Keying them to the shared `text` dir made every plan with a
+        # `doc:` deliverable mutually exclusive with every other: measured 2026-08-31,
+        # it serialized all four lifecycle children (and voice-agents, identity,
+        # playbook-run, agent-wallet-guardian) behind one another for no real conflict.
+        # File granularity here, containing-dir everywhere else.
+        if parts[0] == "text" and len(parts) == 2 and "." in parts[-1]:
+            dirs.add(tok)
+            continue
         # Drop the leaf if it names a file (has an extension); else the path IS a dir.
         sub = "/".join(parts[:-1]) if "." in parts[-1] else tok
         if sub:
@@ -121,7 +134,12 @@ def deliverable_paths(text):
     """Every repo-root path token in the `deliverables:` block (full path, not the
     top/second dir). The granularity-independent source — deliverable_dirs() and the
     linter both derive from it. Path column only (before the em-dash), REPO_DIRS-rooted."""
-    m = re.search(r"^deliverables:\s*$(.*?)(?=^[a-z_]+:|^---\s*$|\Z)",
+    # The key line may carry a trailing YAML comment — `deliverables:   # note`.
+    # It legally does in 12 tracked plans INCLUDING text/template-todo.md, the
+    # file every new plan is copied from, so a `\s*$` anchor here made plans
+    # born unscoped: the block never matched, zero paths came back, and the
+    # fleet read that as "declares no dirs" and refused to pack them.
+    m = re.search(r"^deliverables:[ \t]*(?:#[^\n]*)?$(.*?)(?=^[a-z_]+:|^---\s*$|\Z)",
                   text, re.MULTILINE | re.DOTALL)
     if not m:
         return []
@@ -1122,6 +1140,18 @@ def selftest():
     check("dirs: filename dropped",
           "one.ie/web/src/lib/billing/expiry.ts" not in deliverable_dirs(fm_sub))
     check("dirs: bare dir kept", "channels/src" in deliverable_dirs(fm_sub))
+    # text/ file granularity — two plans' docs must NOT collapse to one `text` lock.
+    fm_t1 = "deliverables:\n  - doc: text/alpha-docs.md — x\n"
+    fm_t2 = "deliverables:\n  - doc: text/beta-docs.md — x\n"
+    check("dirs: text/ keeps the filename",
+          "text/alpha-docs.md" in deliverable_dirs(fm_t1))
+    check("dirs: text/ does not collapse to the bare dir",
+          "text" not in deliverable_dirs(fm_t1))
+    check("dirs: two text/ docs are disjoint",
+          not (deliverable_dirs(fm_t1) & deliverable_dirs(fm_t2)))
+    # RED half — the old behaviour must be genuinely gone, not merely untested.
+    check("dirs: text/ nested path still uses its containing dir",
+          "text/world" in deliverable_dirs("deliverables:\n  - doc: text/world/homepage-text.md — x\n"))
 
     # 6. transitive leverage: a→b→c chain ⇒ a has 2 dependents (b and c), not 1.
     direct = {"a": {"b"}, "b": {"c"}, "c": set()}

package/scripts/do-recon-cache.sh

@@ -11,7 +11,13 @@
 # prune              → delete entries older than MAX_AGE_DAYS
 set -euo pipefail
 
-CACHE_DIR="${CACHE_DIR:-.w1-cache}"
+# CACHE_DIR must NOT be CWD-relative. Every /do cycle runs in a fresh
+# .do-worktrees/<slug> checkout, so a relative `.w1-cache` was born empty on every
+# single cycle -- the "0 tokens on hit, ~12k saved/recon" lever this script exists
+# to provide had never once fired in a worktree run (measured 2026-09-01: no
+# .w1-cache directory existed anywhere in the tree). Key it to the MACHINE, the
+# same way the gate governor keys its locks, so worktrees share one warm store.
+CACHE_DIR="${CACHE_DIR:-${TMPDIR:-/tmp}/one-w1-cache}"
 MAX_AGE_DAYS=14
 BASE_URL="${ONEIE_BASE_URL:-${ONE_BASE_URL:-}}"
 API_KEY="${WAVE_CACHE_SECRET:-${ONEIE_API_KEY:-${ONE_API_KEY:-}}}"

package/scripts/do-recon-pack.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+# do-recon-pack.sh <slug> [--files <path>...] — the DETERMINISTIC W1.
+#
+# manifest: needs-env
+#
+# needs-env, not portable: it JOINs do-brief.sh (needs-env) and do-recon-cache.sh,
+# so it can be no cleaner than its inputs.
+#
+# WHY. `.claude/commands/do.md` Step 0.5 already states the contract: "with the
+# brief compiled, a cycle needs at most TWO model calls — W2 (decide) and W3
+# (make it). W1 collapses into the brief plus do-recon-cache.sh check." Step 3
+# still spawned a `w1-recon` agent every cycle anyway. Measured 2026-09-01, that
+# spawn re-loads 6.4KB of agent prose to narrate, in <400 words, facts that are
+# on disk: which files exist, how big they are, what they export, who imports
+# them, which docs carry the slug, and what the previous cycle left in
+# `.w4-improvements.json` / `.claude/improvements.queue.md`. None of that is
+# judgment. All of it is grep.
+#
+# This is a JOIN plus a symbol inventory, not new logic:
+#   do-brief.sh        -> slug, plan, ready, files, folders, tier, spine, ceiling
+#   do-recon-cache.sh  -> a warm prior recon for the same file shas (0 tokens)
+#   git grep / wc      -> exports, imports, consumers, doc family
+#
+# It does NOT replace the `w1-recon` AGENT for SURVEY or INVESTIGATE (the spine
+# stops in do.md Step 2). Those are once-per-PLAN judgment calls — reuse verdicts
+# and root-cause forensics — and are not the per-cycle bill. This replaces the
+# per-cycle RECON spawn only.
+#
+# Output: ONE json object on stdout. Non-zero exit + EMPTY stdout when the brief
+# cannot be compiled — a half-pack is worse than no pack, because the caller
+# cannot tell which half is missing (same law as do-brief.sh).
+#
+# --self-test  runs the fixtures INCLUDING a red proof; exits non-zero on failure.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+S="$ROOT/.claude/scripts"
+MAX_FILES="${RECON_PACK_MAX_FILES:-40}"
+
+_exports() {   # exported symbol names, capped
+  grep -hoE '^[[:space:]]*export[[:space:]]+(default[[:space:]]+)?(async[[:space:]]+)?(function|const|let|class|type|interface|enum)[[:space:]]+[A-Za-z_$][A-Za-z0-9_$]*' "$1" 2>/dev/null \
+    | awk '{print $NF}' | sort -u | head -30
+}
+_imports() {   # module specifiers this file pulls in, capped
+  [ "$WIDE" = true ] || return 0
+  grep -hoE "from[[:space:]]+['\"][^'\"]+['\"]" "$1" 2>/dev/null \
+    | sed -E "s/.*['\"]([^'\"]+)['\"].*/\1/" | sort -u | head -30
+}
+_consumers() { # files that import this one, by basename stem, capped
+  local stem; stem="$(basename "$1")"; stem="${stem%.*}"
+  [ -n "$stem" ] || return 0
+  git -C "$ROOT" grep -l -F -- "/$stem'" -- '*.ts' '*.tsx' '*.astro' 2>/dev/null \
+    | grep -vxF "$1" | head -"$CO_CAP" || true
+}
+
+# WIDTH CAP. This pack replaces a receipt do.md caps at 400 words (~2.5KB), and
+# a recon input bigger than the agent prompt it removed is not a saving.
+# Measured 2026-09-01: 5 files -> 6.4KB, 15 files -> 12.1KB uncapped. Past 10
+# files the per-file detail narrows — `imports` goes first, because W2 needs the
+# exported surface and who depends on it, almost never the module specifiers.
+CO_CAP=12
+WIDE=true
+_set_caps() { # <file-count>
+  if [ "$1" -gt "${RECON_PACK_WIDE_MAX:-10}" ]; then CO_CAP=5; WIDE=false
+  else CO_CAP=12; WIDE=true; fi
+}
+
+_json_arr() { # stdin lines -> json array (empty stdin -> [])
+  jq -R -s 'split("\n") | map(select(length > 0))'
+}
+
+_pack() {
+  local brief slug files_json
+  # The brief is the floor. If it refuses, we refuse — identically.
+  brief="$(bash "$S/do-brief.sh" "$@" 2>/dev/null)" || return 1
+  [ -n "$brief" ] || return 1
+  printf '%s' "$brief" | jq -e . >/dev/null 2>&1 || return 1
+
+  slug="$(printf '%s' "$brief" | jq -r '.slug // ""')"
+  files_json="$(printf '%s' "$brief" | jq -r '.files[]?' | head -"$MAX_FILES" | _json_arr)"
+  _set_caps "$(printf '%s' "$files_json" | jq 'length')"
+
+  # ---- per-file inventory (the part W1 used to narrate) ----
+  local inv='[]' f entry
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    if [ -f "$ROOT/$f" ]; then
+      entry="$(jq -n \
+        --arg path "$f" \
+        --argjson loc "$(wc -l < "$ROOT/$f" | tr -d ' ')" \
+        --arg sha "$(git -C "$ROOT" hash-object "$f" 2>/dev/null || echo '')" \
+        --argjson exports "$(_exports "$ROOT/$f" | _json_arr)" \
+        --argjson imports "$(_imports "$ROOT/$f" | _json_arr)" \
+        --argjson consumers "$(_consumers "$f" | _json_arr)" \
+        '{path:$path, exists:true, loc:$loc, sha:$sha, exports:$exports, imports:$imports, consumers:$consumers}')"
+    else
+      entry="$(jq -n --arg path "$f" '{path:$path, exists:false, loc:0, sha:"", exports:[], imports:[], consumers:[]}')"
+    fi
+    inv="$(printf '%s' "$inv" | jq --argjson e "$entry" '. + [$e]')"
+  done < <(printf '%s' "$files_json" | jq -r '.[]?')
+
+  # ---- prior-cycle carry-over (W1's non-recon side effects — must not be lost) ----
+  local improvements='[]' queue='[]' docs='[]'
+  if [ -f "$ROOT/.w4-improvements.json" ]; then
+    improvements="$(jq -c '[.. | objects | select(has("item") or has("improve"))] | .[0:10]' \
+      "$ROOT/.w4-improvements.json" 2>/dev/null || echo '[]')"
+  fi
+  if [ -n "$slug" ] && [ -f "$ROOT/.claude/improvements.queue.md" ]; then
+    queue="$(grep -i -- "$slug" "$ROOT/.claude/improvements.queue.md" 2>/dev/null | head -5 | _json_arr)"
+  fi
+  if [ -n "$slug" ]; then
+    docs="$(cd "$ROOT" && ls "text/$slug.md" "text/$slug-plan.md" "text/$slug-features.md" \
+             "text/$slug-ui.md" "text/$slug-todo.md" "text/$slug-docs.md" 2>/dev/null | _json_arr)"
+  fi
+
+  # ---- warm recon cache (0-token prior findings for the same shas) ----
+  local cache_hit=false cache_findings="" flist
+  flist="$(printf '%s' "$files_json" | jq -r '.[]?')"
+  if [ -n "$flist" ]; then
+    if cache_findings="$(cd "$ROOT" && bash "$S/do-recon-cache.sh" check $flist 2>/dev/null)"; then
+      cache_hit=true
+    else
+      cache_findings=""
+    fi
+  fi
+
+  jq -n \
+    --argjson brief "$brief" \
+    --argjson inventory "$inv" \
+    --argjson improvements "$improvements" \
+    --argjson queue "$queue" \
+    --argjson docs "$docs" \
+    --argjson cache_hit "$cache_hit" \
+    --arg cache_findings "$cache_findings" \
+    '{brief:$brief, inventory:$inventory, doc_family:$docs,
+      improvements_open:$improvements, improvements_queue:$queue,
+      recon_cache:{hit:$cache_hit, findings:$cache_findings}}'
+}
+
+_self_test() {
+  local fails=0 out
+
+  # 1. refusal parity with do-brief: a missing plan must refuse with EMPTY stdout.
+  if out=$(bash "$S/do-recon-pack.sh" __nosuchplan__ 2>/dev/null); then
+    echo "FAIL: missing plan produced a pack"; fails=$((fails+1))
+  else
+    [ -z "${out:-}" ] || { echo "FAIL: missing plan wrote to stdout"; fails=$((fails+1)); }
+    echo "ok: missing plan refuses (exit non-zero, empty stdout)"
+  fi
+
+  # 2. the pack is valid JSON and carries the brief + a real symbol inventory.
+  if out=$(bash "$S/do-recon-pack.sh" --files one.ie/web/src/lib/authority.ts 2>/dev/null); then
+    if printf '%s' "$out" | jq -e '.brief.tier and (.inventory | length > 0)' >/dev/null 2>&1; then
+      echo "ok: pack is valid JSON with brief + inventory"
+    else
+      echo "FAIL: pack missing brief/inventory"; fails=$((fails+1))
+    fi
+    if printf '%s' "$out" | jq -e '.inventory[0].exports | length > 0' >/dev/null 2>&1; then
+      echo "ok: exports extracted from a real source file"
+    else
+      echo "FAIL: no exports extracted from authority.ts"; fails=$((fails+1))
+    fi
+  else
+    echo "FAIL: --files pack did not run"; fails=$((fails+1))
+  fi
+
+  # 3. RED PROOF — a checker that cannot go red proves nothing.
+  #    Feed a file that does NOT exist. The pack must report exists:false and
+  #    exports:[] rather than fabricate an inventory — AND the exact assertion
+  #    that passed in (2) must now FAIL, proving it bites.
+  if out=$(bash "$S/do-recon-pack.sh" --files no/such/file.ts 2>/dev/null); then
+    if printf '%s' "$out" | jq -e '.inventory[0].exists == false and (.inventory[0].exports | length == 0)' >/dev/null 2>&1; then
+      echo "ok: RED PROOF — a missing target is reported exists:false, not fabricated"
+    else
+      echo "FAIL: RED PROOF — missing target was not marked absent"; fails=$((fails+1))
+    fi
+    if printf '%s' "$out" | jq -e '.inventory[0].exports | length > 0' >/dev/null 2>&1; then
+      echo "FAIL: RED PROOF — the exports assertion passed on a file with no exports"; fails=$((fails+1))
+    else
+      echo "ok: RED PROOF — the exports assertion goes RED on a file with none"
+    fi
+  else
+    echo "FAIL: RED PROOF — pack refused a syntactically fine --files target"; fails=$((fails+1))
+  fi
+
+  if [ "$fails" -eq 0 ]; then echo "do-recon-pack: self-test PASS"; return 0; fi
+  echo "do-recon-pack: self-test FAIL ($fails)"; return 1
+}
+
+case "${1:-}" in
+  --self-test) _self_test; exit $? ;;
+  ""|-h|--help) echo "usage: do-recon-pack.sh <slug> | --files <path>... | --self-test" >&2; exit 2 ;;
+esac
+
+out="$(_pack "$@")" || exit 1
+printf '%s\n' "$out"