@oneie/claude 0.6.0 → 0.7.0

package/scripts/do-rubric.py

@@ -333,10 +333,22 @@ def score_integration(src: str, files: list[Path]) -> tuple[float, list[str], li
 
 
 # ── Composite & report ────────────────────────────────────────────────────────
-WEIGHTS = {"security": 0.20, "stability": 0.20, "simplicity": 0.15, "integration": 0.10, "speed": 0.10}
-# goal-fit (0.30) is plan-specific — omitted here; composite is over the 5 code axes normalised
+# Weights come from rubric-weights.json — the single source. This script scores a
+# PACKAGE source tree, so it has no plan context and goal-fit (0.30) is genuinely
+# unavailable: its omission is correct, not drift. What that costs is comparability
+# — this number is a BASELINE, never a gate verdict, and it is emitted as
+# `composite_partial` so nothing can compare it to a cycle composite that does
+# carry goal-fit. See the `package` block in rubric-weights.json.
+_WEIGHTS_PATH = Path(__file__).with_name("rubric-weights.json")
+try:
+    _RUBRIC = json.loads(_WEIGHTS_PATH.read_text())
+    WEIGHTS = _RUBRIC["package"]["weights"]
+except (OSError, KeyError, json.JSONDecodeError) as e:
+    raise SystemExit(f"do-rubric: cannot read {_WEIGHTS_PATH}: {e}")
+
 
 def composite(scores: dict) -> float:
+    """Partial composite over the code axes only, normalised. NOT a gate verdict."""
     total_w = sum(WEIGHTS.values())
     return round(sum(scores[k] * WEIGHTS[k] for k in WEIGHTS) / total_w, 2)
 
@@ -379,7 +391,14 @@ def run(target_str: str, as_json: bool = False) -> dict:
         "files":     len(files),
         "loc":       src.count("\n"),
         "scores":    scores,
+        # `composite` is kept for the existing readers (do-auto.sh writes the W0
+        # baseline from it). The two fields beside it say what it actually is, so
+        # a reader can tell a partial baseline from a cycle verdict instead of
+        # assuming they are the same scale.
         "composite": comp,
+        "composite_partial": comp,
+        "rubric":    "package",
+        "goal_fit_included": False,
         "findings":  {
             "security":    sec_f,
             "stability":   sta_f,

package/scripts/do-signal.sh

@@ -1,12 +1,18 @@
 #!/usr/bin/env bash
-# Internal: emit world:do-event signals at /do phase boundaries.
-# Called by do-auto.sh at cycle open, close, and halt. Not a user command.
+# Internal: emit world:do-event signals at /do phase boundaries, and drive the
+# tasks:create/claim/link verbs so a /do plan's own lifecycle IS a substrate
+# task's lifecycle (text/tasks-do-plan.md C1 — the shared-atom wire).
+# Called by do-auto.sh at plan arm, cycle open, cycle close, and halt. Not a
+# user command.
 #
 # Usage:
 #   do-signal.sh [--print] <type> <slug> <tier> <cycle> [key=value ...]
+#   do-signal.sh [--print] --task-create <slug> <title> [tags=a,b,c] [notes=...]
+#   do-signal.sh [--print] --task-claim  <slug>
+#   do-signal.sh [--print] --task-link   <slug> [docs=a,b,c]
 #
 # --print: write JSON to stdout without POSTing (tests + dry runs).
-# Extra key=value pairs are merged into the payload.
+# Extra key=value pairs are merged into the world:do-event payload.
 #   axis=security,structure  → adds s:security + s:structure tags + "axis" field
 #   composite=0.82           → numeric field (no quotes)
 #   wave=W3                  → string field
@@ -14,24 +20,152 @@
 #
 # Env overrides:
 #   DO_SIGNAL_URL  default: https://one.ie
-#   DO_ENV_FILE    default: one.ie/web/.env  (read SERVER_SECRET for auth)
+#   ONE_ENV_FILE   default: one.ie/web/.env  (read SERVER_SECRET for auth)
+#   DO_ENV_FILE    accepted as an alias for ONE_ENV_FILE (kept for callers)
 #
 # Signal failure never blocks the build loop — callers wrap with `|| true`.
 set -euo pipefail
 
 PRINT=false
-DO_ENV_FILE="${DO_ENV_FILE:-one.ie/web/.env}"
+# Credentials come from ONE_ENV_FILE, so the harness runs with no one.ie/web/
+# on disk. DO_ENV_FILE stays an accepted alias — it predates the generalisation.
+ONE_ENV_FILE="${ONE_ENV_FILE:-${DO_ENV_FILE:-one.ie/web/.env}}"
+DO_ENV_FILE="$ONE_ENV_FILE"
 DO_SIGNAL_URL="${DO_SIGNAL_URL:-https://one.ie}"
 
+_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+
+# Monorepo fallbacks. Unquoted on purpose: they expand to nothing outside the
+# monorepo, so the loop degrades to ONE_ENV_FILE alone rather than erroring.
+_MONOREPO_ENV_CANDIDATES="$_ROOT/one.ie/web/.env $_ROOT/one.ie/web/.secrets.generated.local $_ROOT/one.ie/web/.dev.vars"
+
+# Shared SERVER_SECRET lookup — /api/signal/world:do-event checks this (see
+# world:do-event POST at the bottom of this file).
+_server_secret() {
+  local _f _v
+  for _f in "$ONE_ENV_FILE" "$_ROOT/.env" $_MONOREPO_ENV_CANDIDATES; do
+    [ -f "$_f" ] || continue
+    _v=$(grep -E '^SERVER_SECRET=' "$_f" 2>/dev/null | head -1 | sed 's/^[^=]*=//;s/^"//;s/"$//' || true)
+    [ -n "$_v" ] && { printf '%s' "$_v"; return 0; }
+  done
+  printf ''
+}
+
+# GATEWAY_API_KEY lookup — /api/ask/<receiver> (the tasks:* verbs) checks THIS,
+# not SERVER_SECRET (one.ie/web/src/pages/api/ask/[...receiver].ts isServiceCaller).
+# Presenting SERVER_SECRET there resolves to no service caller, no ctx.ownerSlug,
+# and every tasks:* resolver returns {error:"workspace required"} — verified
+# 2026-07-17, zero do-signal task-create/claim/link calls had ever landed in prod.
+_gateway_key() {
+  local _f _v
+  for _f in "$ONE_ENV_FILE" "$_ROOT/.env" $_MONOREPO_ENV_CANDIDATES; do
+    [ -f "$_f" ] || continue
+    _v=$(grep -E '^GATEWAY_API_KEY=' "$_f" 2>/dev/null | head -1 | sed 's/^[^=]*=//;s/^"//;s/"$//' || true)
+    [ -n "$_v" ] && { printf '%s' "$_v"; return 0; }
+  done
+  printf ''
+}
+
+# POST a JSON payload to /api/ask/<receiver> with bearer auth. Fire-and-forget:
+# a failure is silent so the build loop is never blocked (same stance as the
+# world:do-event POST below). Prints the response body (empty on failure).
+_post_ask() {
+  local _receiver="$1" _payload="$2" _secret _authcfg _url _resp
+  _secret="$(_gateway_key)"
+  _url="${DO_SIGNAL_URL}/api/ask/${_receiver}"
+  if [ -n "$_secret" ]; then
+    _authcfg="$(mktemp)"; chmod 600 "$_authcfg"
+    printf 'header = "Authorization: Bearer %s"\n' "$_secret" > "$_authcfg"
+    _resp=$(curl -sf -X POST "$_url" -H "Content-Type: application/json" --config "$_authcfg" -d "$_payload" 2>/dev/null || true)
+    rm -f "$_authcfg"
+  else
+    _resp=$(curl -sf -X POST "$_url" -H "Content-Type: application/json" -d "$_payload" 2>/dev/null || true)
+  fi
+  printf '%s' "$_resp"
+}
+
+# Every task this harness files lands in one workspace — /u/one/tasks — so a
+# human never has to hunt across slugs for Claude Code's own work. Overridable
+# for a differently-branded harness fork; unset means "one" (same convention
+# as CC_WORLD_SLUG in hooks/lib/signal.sh). ctx.ownerSlug resolves straight to
+# this value (nominated via GATEWAY_API_KEY auth above), so every tasks:*
+# resolver's actor/owner/workspace tag is this slug, not whatever ambient
+# session happened to be attested.
+CC_TASKS_WORKSPACE="${CC_TASKS_WORKSPACE:-one}"
+
+# signal_tasks_create — plan arm: files an open task tagged slug:<slug>, so the
+# plan appears in tasks:everywhere the moment it's armed (C1/C2 interface contract).
+signal_tasks_create() {  # signal_tasks_create <slug> <title> [tags=a,b,c] [notes=...]
+  local slug="$1" title="$2" tags="slug:${1}" notes=""
+  shift 2
+  for kv in "$@"; do
+    case "${kv%%=*}" in
+      tags)  tags="${tags},${kv#*=}" ;;
+      notes) notes="${kv#*=}" ;;
+    esac
+  done
+  local tags_json; tags_json=$(printf '%s' "$tags" | awk -F',' '{for(i=1;i<=NF;i++){printf "%s\"%s\"", (i>1?",":""), $i}}')
+  local payload="{\"data\":{\"title\":\"${title}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\",\"tags\":[${tags_json}]${notes:+,\"notes\":\"${notes}\"}}}"
+  if $PRINT; then printf '%s\n' "$payload"; return 0; fi
+  _post_ask "tasks:create" "$payload"
+}
+
+# signal_tasks_claim — cycle open: leases the plan's substrate task so a fleet
+# run (or a human) never double-builds the same slug (do-fleet.sh mirrors this).
+signal_tasks_claim() {  # signal_tasks_claim <slug>
+  # Address the lease by the plan SLUG, not a guessed tid: create returns a random
+  # task:<traceId>, so "task:<slug>" never matched — claim silently 404'd for every /do
+  # run until this. The server resolves slug → tid (resolvers/tasks.ts resolveTaskBySlug).
+  local slug="$1"
+  local payload="{\"data\":{\"slug\":\"${slug}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\"}}"
+  if $PRINT; then printf '%s\n' "$payload"; return 0; fi
+  _post_ask "tasks:claim" "$payload"
+}
+
+# signal_tasks_link — cycle close: records the handoff-completion back on the
+# origin task (provenance line + task-status:done), same shape lifecycle.ts's
+# tasks_link MCP tool posts.
+signal_tasks_link() {  # signal_tasks_link <slug> [docs=a,b,c]
+  # Slug-addressed like claim — the server resolves slug → the origin tid create wrote.
+  local slug="$1" docs=""
+  shift 1
+  for kv in "$@"; do
+    case "${kv%%=*}" in
+      docs) docs="${kv#*=}" ;;
+    esac
+  done
+  local docs_json=""
+  [ -n "$docs" ] && docs_json=$(printf '%s' "$docs" | awk -F',' '{for(i=1;i<=NF;i++){printf "%s\"%s\"", (i>1?",":""), $i}}')
+  local payload="{\"data\":{\"slug\":\"${slug}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\"${docs_json:+,\"docs\":[${docs_json}]}}}"
+  if $PRINT; then printf '%s\n' "$payload"; return 0; fi
+  _post_ask "tasks:link" "$payload"
+}
+
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --print) PRINT=true; shift ;;
+    # Report WHICH file credentials resolved from, never the value. This is how
+    # factory-repo.sh --check-env-indirection proves the override is real
+    # behaviour rather than a grep for a variable name.
+    --print-env)
+      _which=""
+      for _f in "$ONE_ENV_FILE" "$_ROOT/.env" $_MONOREPO_ENV_CANDIDATES; do
+        [ -f "$_f" ] || continue
+        grep -qE '^(SERVER_SECRET|GATEWAY_API_KEY)=.' "$_f" 2>/dev/null || continue
+        _which="$_f"; break
+      done
+      printf 'resolved-from: %s\n' "${_which:-<none>}"
+      exit 0 ;;
+    --task-create) shift; signal_tasks_create "$@"; exit 0 ;;
+    --task-claim)  shift; signal_tasks_claim "$@"; exit 0 ;;
+    --task-link)   shift; signal_tasks_link "$@"; exit 0 ;;
     *) break ;;
   esac
 done
 
 if [ "$#" -lt 4 ]; then
   echo "usage: do-signal.sh [--print] <type> <slug> <tier> <cycle> [key=value ...]" >&2
+  echo "       do-signal.sh [--print] --task-create|--task-claim|--task-link <slug> ..." >&2
   exit 1
 fi
 
@@ -66,6 +200,18 @@ for kv in "$@"; do
     composite)
       EXTRA_JSON="${EXTRA_JSON},\"${k}\":${v}"
       ;;
+    worktags)
+      # comma-list → JSON array field. The plan's task-vocabulary tags (dept + topics);
+      # the reputation harvest credits these tag-nodes (text/reputation.md § Slice A).
+      _wt=""; _w="${v}"
+      while [ -n "$_w" ]; do
+        _witem="${_w%%,*}"
+        [ -n "$_witem" ] && _wt="${_wt:+${_wt},}\"${_witem}\""
+        [ "$_w" = "$_witem" ] && break
+        _w="${_w#*,}"
+      done
+      EXTRA_JSON="${EXTRA_JSON},\"worktags\":[${_wt}]"
+      ;;
     *)
       EXTRA_JSON="${EXTRA_JSON},\"${k}\":\"${v}\""
       ;;
@@ -79,18 +225,12 @@ if $PRINT; then
   exit 0
 fi
 
-# Read SERVER_SECRET for the Authorization header — first file that has it wins.
-# .env historically lacks it; .secrets.generated.local is what push-prod-secrets.sh
-# pushed to the worker, so it matches prod. Without a matching secret the POST is
-# silently 401/403-dropped at the gateway (verified 2026-07-04 — zero do-* threads
-# had ever landed in prod D1).
-_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
-SERVER_SECRET=""
-for _f in "$DO_ENV_FILE" "$_ROOT/one.ie/web/.env" "$_ROOT/one.ie/web/.secrets.generated.local" "$_ROOT/one.ie/web/.dev.vars"; do
-  [ -f "$_f" ] || continue
-  SERVER_SECRET=$(grep -E '^SERVER_SECRET=' "$_f" 2>/dev/null | head -1 | sed 's/^[^=]*=//;s/^"//;s/"$//' || true)
-  [ -n "$SERVER_SECRET" ] && break
-done
+# SERVER_SECRET for the Authorization header — _server_secret() (defined above)
+# is the one lookup, shared with the tasks:* verbs. .env historically lacks it;
+# .secrets.generated.local is what push-prod-secrets.sh pushed to the worker, so
+# it matches prod. Without a matching secret the POST is silently 401/403-dropped
+# at the gateway (verified 2026-07-04 — zero do-* threads had ever landed in prod D1).
+SERVER_SECRET="$(_server_secret)"
 
 # POST — fire-and-forget; failures are silent so the build loop is never blocked.
 _url="${DO_SIGNAL_URL}/api/signal/world:do-event"

package/scripts/do-smoke.sh

@@ -21,6 +21,15 @@ echo "== C7 do-tier =="
 "$S/do-tier.sh" pay/contracts/sui/sources/one_token.move | grep -q '"tier":"SCHEMA"' && ok "contract source → SCHEMA" || no "contract source"
 "$S/do-tier.sh" pay/contracts/sui/tests/gateway_tests.move | grep -q '"tier":"FIX"' && ok "contract test → FIX (not SCHEMA)" || no "contract test"
 "$S/do-tier.sh" --intent "add billing" one.ie/web/src/api/b.ts | grep -q '"tier":"FEATURE"' && ok "intent → FEATURE" || no "FEATURE"
+# Absence of recon must not read as simplicity: no paths → UNSIZED, never PATCH.
+# Intent is deliberately ignored here — "add a null check" and "add a settings page"
+# share a verb, so a sentence alone can't size anything. Exit 3 is the contract.
+# Capture before grepping: UNSIZED exits 3, and under `pipefail` that propagates
+# through the pipe even when grep matches — the same trap any caller piping do-tier
+# into grep/jq will hit now that it can exit non-zero.
+UNS=$(echo "" | "$S/do-tier.sh" --intent "add a settings page" 2>/dev/null); UNS_RC=$?
+case "$UNS" in *'"tier":"UNSIZED"'*) ok "no paths → UNSIZED (not PATCH)" ;; *) no "UNSIZED" ;; esac
+[ "$UNS_RC" -eq 3 ] && ok "UNSIZED → exit 3" || no "UNSIZED exit code (got $UNS_RC)"
 
 echo "== C2 do-reconcile — substrate canon =="
 echo "uses a node in the colony" | "$S/do-reconcile.sh" substrate >/dev/null 2>&1 && no "dead name should fail substrate" || ok "dead name → substrate exit 1"

package/scripts/do-substrate-check.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# do-substrate-check.sh — can this machine reach TypeDB DIRECTLY, right now?
+#
+# Distinct from `do-rank.py --board-check`, which asks whether the *gateway*
+# accepts us as a service caller. The two fail independently and the difference
+# decides what is provable:
+#   board-check RED + substrate GREEN → board logic is testable against the real
+#     cluster by calling resolvers directly; anything routed through api.one.ie
+#     or one.ie is not.
+#   substrate RED → no test that touches the graph can prove anything, and a
+#     `describe.skipIf(...)` suite will PASS while proving nothing (a skipped
+#     test is a green test — never let an accept: rest on one).
+#
+# Reads TYPEDB_URL / TYPEDB_USERNAME / TYPEDB_PASSWORD from one.ie/web/.env.
+# Never echoes the password or the returned token.
+#
+# Usage: do-substrate-check.sh [--quiet]
+# Exit: 0 = reachable and authenticating · 1 = unreachable/refused · 2 = no creds
+set -uo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")/../.." || exit 2
+
+QUIET=false
+[ "${1:-}" = "--quiet" ] && QUIET=true
+say() { $QUIET || echo "$@"; }
+
+ENVF=one.ie/web/.env
+val() { grep -h "^$1=" "$ENVF" 2>/dev/null | head -1 | sed 's/^[^=]*=//; s/^"//; s/"$//'; }
+
+URL=$(val TYPEDB_URL); USER=$(val TYPEDB_USERNAME); PASS=$(val TYPEDB_PASSWORD)
+if [ -z "$URL" ] || [ -z "$USER" ] || [ -z "$PASS" ]; then
+  say "[substrate] NO CREDS — TYPEDB_URL/USERNAME/PASSWORD missing from $ENVF"
+  exit 2
+fi
+
+# Credentials ride a temp file, never argv: a bare --data on the command line is
+# visible to any local user via `ps` for the life of the process.
+BODY=$(mktemp); chmod 600 "$BODY"
+printf '{"username":"%s","password":"%s"}' "$USER" "$PASS" > "$BODY"
+CODE=$(curl -sS -o /dev/null -w '%{http_code}' --max-time 20 \
+  -X POST "$URL/v1/signin" -H 'Content-Type: application/json' \
+  --data-binary @"$BODY" 2>/dev/null)
+rm -f "$BODY"
+
+if [ "$CODE" = "200" ]; then
+  say "[substrate] GREEN — ${URL} authenticates"
+  exit 0
+fi
+say "[substrate] RED — ${URL}/v1/signin → HTTP ${CODE:-no-response}"
+exit 1

package/scripts/do-tasks-wire-check.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# do-tasks-wire-check — assert the /do ⇄ substrate-task wires are actually connected.
+#
+# Why this exists: text/tasks-do.md's deliverables were all `grep -q '<receiver-name>'`
+# checks. Every one stayed GREEN for months while three of the wires were dead in prod —
+# a grep for "tasks:everywhere" passes just as happily when the call authenticates with
+# the wrong secret, parses the wrong envelope key, and addresses the lease by a tid that
+# can never resolve. Presence is not connection. These checks assert the SHAPE that was
+# broken, so a regression to any of the four known-bad forms turns the promise red.
+#
+# Usage: bash .claude/scripts/do-tasks-wire-check.sh   → exit 0 all wired, 1 otherwise.
+
+set -uo pipefail
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$ROOT" || exit 1
+
+FAIL=0
+ok()   { printf '  ✓ %s\n' "$1"; }
+bad()  { printf '  ✗ %s\n' "$1"; FAIL=1; }
+check() { if eval "$2" >/dev/null 2>&1; then ok "$1"; else bad "$1 — $3"; fi; }
+
+echo "[tasks-wire] /do ⇄ substrate task wires"
+
+# 1. The ranker authenticates as a SERVICE CALLER.
+#    /api/ask/<receiver> decides isServiceCaller off env.GATEWAY_API_KEY. SERVER_SECRET
+#    is what /api/signal/ checks — the two routes do not share a secret.
+check "do-rank reads the board with GATEWAY_API_KEY" \
+  "grep -q 'secret = _gateway_key()' .claude/scripts/do-rank.py" \
+  "fetch_tasks_everywhere must call _gateway_key(), not _server_secret()"
+
+# 2. The ranker nominates a workspace. A service call carries no session actor, so
+#    ctx.ownerSlug comes solely from payload.slug|payload.workspace. Omit it and
+#    tasks:everywhere answers {ok:false,error:"forbidden: authentication required"}.
+check "do-rank nominates a workspace on the board read" \
+  "grep -q '\"workspace\": ws' .claude/scripts/do-rank.py" \
+  "the tasks:everywhere payload must carry workspace"
+
+# 3. The ranker parses the /api/ask ENVELOPE. Answers are wrapped
+#    {outcome, result:{ok, tasks}, signalId, receiver} — reading ok/tasks off the top
+#    level makes even a good answer look like a failure, so the merge never fires.
+check "do-rank unwraps the /api/ask result envelope" \
+  "grep -qF 'payload.get(\"result\")' .claude/scripts/do-rank.py" \
+  "must read ok/tasks from payload['result'], not the top level"
+
+# 4. Cloudflare answers the stock urllib User-Agent with 403 "error code: 1010" before
+#    the Worker ever runs. curl is unaffected, which is why only the ranker hit this.
+check "do-rank sends a real User-Agent (CF bot block)" \
+  "grep -q 'User-Agent' .claude/scripts/do-rank.py" \
+  "the board request must set a User-Agent header"
+
+# 5. The fleet addresses the lease by SLUG. Real tids are minted task:<traceId>
+#    (resolvers/tasks.ts insertTaskRow), so a guessed "task:<slug>" resolves not_found
+#    for every plan and the cross-agent lease can never gate.
+check "do-fleet claims the lease by slug, not a guessed tid" \
+  "grep -qF '\\\"slug\\\":\\\"\$slug\\\"' .claude/scripts/do-fleet.sh" \
+  "claim_task must post data.slug"
+check "do-fleet no longer guesses tid=task:<slug>" \
+  "! grep -qF 'tid=\"task:\${1}\"' .claude/scripts/do-fleet.sh" \
+  "the guessed-tid form is back"
+
+# 6. The fleet lease actually GATES. Every non-already-claimed response used to degrade
+#    to "ok to launch", so two runs could both think they owned the same task.
+check "do-fleet distinguishes not_found from already-claimed" \
+  "grep -q 'error\":\"not_found' .claude/scripts/do-fleet.sh" \
+  "claim_task must branch on not_found separately from the generic error case"
+
+# 7. /close routes the task close through a route that EXISTS. There is no
+#    /api/tasks/{id}/complete anywhere in one.ie/web/src/pages/api/.
+check "/close has no dead /api/tasks/{id}/complete POST" \
+  "! grep -qE 'POST .(http://localhost:4321)?/api/tasks/\{id\}/complete' .claude/commands/close.md" \
+  "close.md still posts to a route that does not exist"
+check "/close closes the task through tasks:status" \
+  "grep -q 'api/ask/tasks:status' .claude/commands/close.md" \
+  "close.md must use the tasks:status door"
+
+if [ "$FAIL" -eq 0 ]; then
+  echo "[tasks-wire] OK — all wires connected"
+else
+  echo "[tasks-wire] BROKEN — see ✗ above"
+fi
+exit "$FAIL"

package/scripts/do-tier.sh

@@ -6,12 +6,70 @@
 # Usage:  do-tier.sh [--intent "text"] <path>...   |   git diff --name-only | do-tier.sh [--intent ...]
 set -euo pipefail
 
+# --self-test — the tier fixtures, runnable as one command (same idiom as
+# do-reconcile.sh / do-promise-settle.sh / do-promise-lint.sh). Exists so an
+# acceptance check can be `do-tier.sh --self-test` instead of a fragile inline
+# pipeline: do-tier now exits 3 on UNSIZED, and under `pipefail` that propagates
+# through `… | grep` even when the grep matches.
+if [ "${1:-}" = "--self-test" ]; then
+  S="$(cd "$(dirname "$0")" && pwd)"; f=0
+  chk() { # chk <expected-tier> <args...>
+    want="$1"; shift
+    got="$("$S/do-tier.sh" "$@" 2>/dev/null)" || true
+    case "$got" in *"\"tier\":\"$want\""*) printf '  ok   %s → %s\n' "$*" "$want" ;;
+                   *) printf '  FAIL %s → expected %s, got %s\n' "$*" "$want" "$got"; f=1 ;; esac
+  }
+  chk PATCH   text/x.md
+  chk SCHEMA  schema/one.tql
+  chk SCHEMA  channels/migrations/0001_init.sql
+  chk SCHEMA  pay/contracts/sui/sources/one_token.move
+  chk FIX     pay/contracts/sui/tests/gateway_tests.move
+  chk FEATURE --intent "add billing" one.ie/web/src/api/b.ts
+  # Absence of recon must not read as simplicity — no paths → UNSIZED, never PATCH.
+  # Intent is ignored by design: "add a null check" and "add a settings page" share a verb.
+  # set +e around this: UNSIZED exits 3 BY CONTRACT, and this script runs under
+  # `set -e`, so the assignment below would abort the self-test before it asserted
+  # anything — silently "passing" a build with the guard removed (caught doing
+  # exactly that during authoring).
+  set +e
+  out="$(printf '' | "$S/do-tier.sh" --intent "add a settings page" 2>/dev/null)"; rc=$?
+  set -e
+  case "$out" in *'"tier":"UNSIZED"'*) printf '  ok   no paths → UNSIZED (not PATCH)\n' ;;
+                 *) printf '  FAIL no paths → expected UNSIZED, got %s\n' "$out"; f=1 ;; esac
+  [ "$rc" -eq 3 ] && printf '  ok   UNSIZED → exit 3\n' || { printf '  FAIL UNSIZED exit: expected 3, got %s\n' "$rc"; f=1; }
+  [ "$f" -eq 0 ] && echo "do-tier: self-test green" || echo "do-tier: self-test FAILED"
+  exit "$f"
+fi
+
 intent=""
 if [ "${1:-}" = "--intent" ]; then intent="$2"; shift 2; fi
 
 paths=()
 if [ "$#" -gt 0 ]; then paths=("$@"); else while IFS= read -r l; do [ -n "$l" ] && paths+=("$l"); done; fi
-[ "${#paths[@]}" -eq 0 ] && paths=("")
+
+# UNSIZED — zero real paths. do-tier sizes a DIFF, never a sentence.
+#
+# The downward bias below ("an over-built PATCH is burnt") is right when the paths are
+# known and dangerous when there are none: with no paths every input fell through to
+# PATCH/TRIVIAL/5k, so an unrecon'd idea read as a typo. That silently mis-sized real
+# work twice on record — text/learnings.md:485 ("correctly returned PATCH on a bare slug
+# with no changes yet") and text/remote-suspend-todo.md:5 ("do-tier mis-sized as FIX").
+# The caller at .claude/commands/do.md Step 1 passes $(git diff --name-only), which is
+# empty on a clean tree — i.e. at AIM, every single time, before any edit exists.
+#
+# Absence of recon must not read as simplicity. Intent text alone can't decide either
+# ("add a null check" and "add a settings page" share a verb), so UNSIZED ignores
+# --intent by design: run recon, then size the paths it found.
+# NB: guard the expansion — `"${paths[@]}"` on an empty array is an unbound-variable
+# error under `set -u` on macOS's bash 3.2, not an empty list.
+real=0
+if [ "${#paths[@]}" -gt 0 ]; then
+  for p in "${paths[@]}"; do [ -n "$p" ] && real=$((real + 1)); done
+fi
+if [ "$real" -eq 0 ]; then
+  printf '{"tier":"UNSIZED","spine":"recon","classifier":"UNKNOWN","ceiling_tokens":0,"w2_model":"none"}\n'
+  exit 3
+fi
 
 n=${#paths[@]}
 schema=false; code=false; doconly=true
@@ -46,11 +104,38 @@ fi
 # still override per-cycle.
 W2_SCHEMA=opus
 [ "${FABLE_AVAILABLE:-off}" = "on" ] && W2_SCHEMA=fable
+# spine — the pruned stop list, in the tokens do.md Step 1 has always used. These are
+# the SAME stops as do.md's uppercase spine block (§ "The pruned spine by tier"), in
+# their original lowercase names: spec=DESIGN · todo=PLAN · code=BUILD · tests=TEST ·
+# proof=PROVE · teach=TEACH · release=SHIP. At genesis (ff72af398, 2026-06-04) do.md
+# printed this exact lowercase list; 6b5b89f04 renamed the doc's tokens and 98c20f586
+# (2026-06-18) reordered them docs-first, and neither change reached here — so the
+# strings below sat two commits behind canon from 2026-06-18. Realigned 2026-08-02.
+#
+# What the drift actually was (the trailing `docs` was NOT the bug):
+#   - `proof docs release` was already canon — that `docs` is TEACH (reconcile the docs
+#     against shipped reality), which correctly follows PROVE. It is renamed to `teach`
+#     below only so the one pre-BUILD `docs` stop can own the word `docs` unambiguously.
+#   - The real defect was an OMISSION: there was no pre-BUILD `docs` stop on any tier,
+#     so the deterministic spine never scheduled the doc set that .claude/rules/
+#     documentation.md makes the spec ("docs are the spec, written FIRST"). A conductor
+#     reading this spine walked straight to `code`.
+#   - FEATURE/SCHEMA also still emitted `code tests` where canon is TEST → BUILD: the
+#     tests are drawn FROM the docs, before the code exists.
+#   - FIX had neither a `docs` stop nor a `learn` stop that do.md:222 gives it.
+# The `docs` insert + `teach` rename are prescribed verbatim by text/do-evolve.md § 8.
+# `verify` and `learn` go beyond that string — they come straight from do.md:222-223,
+# which lists VERIFY (FEATURE/SCHEMA, between BUILD and PROVE) and LEARN (all but PATCH).
+# Noted because do-evolve § 8 is a live design doc: the delta from its string is deliberate.
+#
+# Deliberately absent: `aim` (AIM is the stop that RUNS do-tier — emitting it here would
+# be the output naming its own caller) and `investigate` (do.md:231 — it rides any tier
+# on a condition, so it is not tier-pruned). `reconcile` stays SCHEMA-only per do.md:224.
 case "$tier" in
-  PATCH)   spine="code verify";                                            cls=TRIVIAL; ceil=5000;   w2=opus ;;
-  FIX)     spine="survey code tests proof";                               cls=SIMPLE;  ceil=30000;  w2=opus ;;
-  FEATURE) spine="promise survey spec clarify todo analyze code tests proof docs release"; cls=COMPLEX; ceil=150000; w2=opus ;;
-  SCHEMA)  spine="promise survey spec reconcile clarify todo analyze code tests proof docs release"; cls=COMPLEX; ceil=200000; w2="$W2_SCHEMA" ;;
+  PATCH)   spine="code verify";                                                                          cls=TRIVIAL; ceil=5000;   w2=opus ;;
+  FIX)     spine="survey docs code tests proof learn";                                                   cls=SIMPLE;  ceil=30000;  w2=opus ;;
+  FEATURE) spine="promise survey spec clarify docs todo analyze tests code verify proof teach release learn"; cls=COMPLEX; ceil=150000; w2=opus ;;
+  SCHEMA)  spine="promise survey spec reconcile clarify docs todo analyze tests code verify proof teach release learn"; cls=COMPLEX; ceil=200000; w2="$W2_SCHEMA" ;;
 esac
 
 printf '{"tier":"%s","spine":"%s","classifier":"%s","ceiling_tokens":%s,"w2_model":"%s"}\n' "$tier" "$spine" "$cls" "$ceil" "$w2"