@oneie/claude 0.7.0 → 0.9.0

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"

package/scripts/do-reconcile.sh

@@ -47,6 +47,36 @@ _sanitize() {
     | _strip_allow
 }
 
+# Read stdin with a wall clock. macOS ships no `timeout(1)` (the same absence the
+# gate governor had to work around), so the bound is built from `read -t`.
+#
+# NOT with a backgrounded `cat`: the first attempt did that and read NOTHING,
+# because a job backgrounded by a non-interactive shell gets /dev/null for stdin.
+# The checker then reported OK on input containing a dead name -- a green gate
+# over a red input, which is worse than the hang it was fixing. Caught by the red
+# proof (`echo 'colony trail' | do-reconcile.sh dictionary` must FAIL); the
+# original caught 'trail', the rewrite did not.
+#
+# `read -t` distinguishes the two endings that matter: exit >128 is the timeout,
+# exit 1 is a clean EOF. Real pipes hit EOF in milliseconds.
+_read_stdin_bounded() {
+  local secs="${RECONCILE_STDIN_TIMEOUT:-10}" line out="" st rc=0
+  while true; do
+    if IFS= read -r -t "$secs" line; then
+      out="$out$line
+"
+    else
+      st=$?
+      # a final unterminated line still carries content
+      [ -n "$line" ] && out="$out$line"
+      [ "$st" -gt 128 ] && rc=1
+      break
+    fi
+  done
+  printf '%s' "$out"
+  return "$rc"
+}
+
 _load_text() {
   local text=""
   if [ "$#" -gt 0 ]; then
@@ -56,7 +86,32 @@ _load_text() {
       if [ -f "$a" ]; then text="$text $(_sanitize < "$a")"; else text="$text $(printf '%s' "$a" | _sanitize)"; fi
     done
   else
-    text="$(_sanitize)"  # stdin fallback (matches original do-reconcile.sh behaviour)
+    # STDIN FALLBACK -- bounded, because an unbounded one hangs the loop.
+    #
+    # Measured 2026-09-01: `do-reconcile.sh dictionary` with no file argument and
+    # an inherited-but-idle stdin blocked for over NINE MINUTES before it was
+    # killed. It is not slow; it is waiting for an EOF that never comes. And
+    # do.md's own toolbox documents exactly that argument-less form
+    # ("do-reconcile.sh dictionary  # no dead name, no new synonym"), so an agent
+    # copying the documented invocation stalls its whole cycle until do-auto's
+    # hard cap reaps it -- which reads as a mysteriously slow wave, not as a hang.
+    #
+    # Two guards. A terminal stdin can never deliver piped input, so that is a
+    # usage error, immediately. Anything else is read under a wall clock: real
+    # pipes (`git diff --name-only | do-reconcile.sh types`) close in
+    # milliseconds, so the bound only ever fires on the pathological case.
+    if [ -t 0 ]; then
+      printf 'do-reconcile: %s needs a file argument, or input on stdin.\n' "$CANON" >&2
+      printf '  do-reconcile.sh %s <file>...\n  git diff --name-only | do-reconcile.sh %s\n' "$CANON" "$CANON" >&2
+      exit 2
+    fi
+    local _raw=""
+    if ! _raw="$(_read_stdin_bounded)"; then
+      printf 'do-reconcile: %s timed out waiting on stdin after %ss — no file argument was given.\n' \
+        "$CANON" "${RECONCILE_STDIN_TIMEOUT:-10}" >&2
+      exit 2
+    fi
+    text="$(printf '%s' "$_raw" | _sanitize)"
   fi
   printf '%s' "$text"
 }
@@ -247,9 +302,71 @@ case "$CANON" in
 
     current=0
     if [ -d "$folder" ] && [ -f "$folder/tsconfig.json" ]; then
-      _tsc_tmp=$(mktemp)
-      ( cd "$folder" && bunx tsc --noEmit 2>&1 | grep -c 'error TS' > "$_tsc_tmp" ) 2>/dev/null || true
-      current=$(cat "$_tsc_tmp" 2>/dev/null | tr -d '[:space:]'); rm -f "$_tsc_tmp"
+      # ── Governed tsc (2026-08-18) ──────────────────────────────────────
+      # Six concurrent Claude sessions ran this canon at once, each spawning
+      # its own `tsc --noEmit` over the SAME tree for the SAME answer: load 57
+      # on 10 cores, swap exhausted, ~26 MB/s swapins. Starved, each tsc took
+      # 18 min instead of 2, sessions timed out, and retries piled on more.
+      # Fix: one tsc per (folder, tree-fingerprint); everyone else reuses its
+      # result. Identical work collapses instead of multiplying.
+      . "$(dirname "${BASH_SOURCE[0]}")/lib/govern.sh"
+
+      # Fingerprint the tree: same fingerprint => same tsc answer.
+      #
+      # ONE derivation, shared with tsc-cached.sh: tsc_tree_fingerprint in
+      # lib/govern.sh hashes the CONTENT of everything tsc reads (the folder's
+      # .ts/.tsx/.json + lockfile, tracked or not, plus packages/sdk/src for the
+      # folders that resolve @oneie/sdk types). It used to be an mtime stat
+      # here AND a second copy in tsc-cached.sh — two derivations of one key is
+      # how the memo split, and mtime is why it never shared across worktrees.
+      _fp_extra=""
+      case "$folder" in one.ie/web|channels) _fp_extra="packages/sdk/src" ;; esac
+      _fp=$(tsc_tree_fingerprint "$folder" $_fp_extra)
+      _cache="$GOVERN_DIR/tsc-$(printf '%s' "$folder" | tr '/' '_').$_fp"
+
+      if [ -s "$_cache" ]; then
+        current=$(cat "$_cache" | tr -d '[:space:]')          # someone already computed it
+      elif gate_lock "tsc-$(printf '%s' "$folder" | tr '/' '_')" "${RECONCILE_TSC_WAIT:-900}"; then
+        trap 'gate_release_all' EXIT INT TERM
+        if [ -s "$_cache" ]; then
+          current=$(cat "$_cache" | tr -d '[:space:]')        # computed while we queued
+        else
+          _tsc_tmp=$(mktemp)
+          # THE SLOT, not just the lock — same defect as tsc-cached.sh, same fix.
+          # The gate_lock above dedupes this folder against other reconciles; it
+          # does nothing about N worktrees typechecking N different folders at
+          # once. See tsc-cached.sh for the 2026-09-07 measurement.
+          # Resolve gate-run from THIS script's own directory. An earlier
+          # version used "$ROOT/..." -- ROOT is never set in this file, and under
+          # `set -u` that is a hard "unbound variable" that killed the whole
+          # `types` canon. Caught by tests/integration/reconcile.test.ts, which is
+          # the reason that test exists.
+          _gr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/gate-run.sh"
+          GOVERN_GATE_TIMEOUT="${RECONCILE_TSC_TIMEOUT:-600}" \
+          bash "$_gr" "tsc-reconcile:$folder" -- \
+            bash -c "cd '$folder' && bunx tsc --noEmit 2>&1 | grep -c 'error TS' > '$_tsc_tmp'" \
+            || true
+          current=$(cat "$_tsc_tmp" 2>/dev/null | tr -d '[:space:]'); rm -f "$_tsc_tmp"
+          current=${current:-0}
+          printf '%s' "$current" > "$_cache"
+        fi
+        gate_release_all; trap - EXIT INT TERM
+      else
+        # Lock held for the full wait. Re-check the cache once — the holder may
+        # have finished and released between our last poll and now.
+        if [ -s "$_cache" ]; then
+          current=$(cat "$_cache" | tr -d '[:space:]')
+        else
+          # Never exit 0 without an answer: a gate that passes because it was
+          # busy is a fail-open, which is worse than the load it avoids.
+          echo "RECONCILE[types]: lock held ${RECONCILE_TSC_WAIT:-900}s — checking anyway" >&2
+          _tsc_tmp=$(mktemp)
+          run_bounded "${RECONCILE_TSC_TIMEOUT:-600}" \
+            bash -c "cd '$folder' && bunx tsc --noEmit 2>&1 | grep -c 'error TS' > '$_tsc_tmp'" \
+            2>/dev/null || true
+          current=$(cat "$_tsc_tmp" 2>/dev/null | tr -d '[:space:]'); rm -f "$_tsc_tmp"
+        fi
+      fi
       current=${current:-0}
     fi