@oneie/claude 0.6.0 → 0.7.0

package/scripts/do-derives-check.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# do-derives-check.sh — assert every artifact a promise's derives: block declares
+# `true` actually EXISTS on disk. Zero LLM; the file's presence is the verdict.
+#
+# WHY: text/security-gates.md declared `docs: true` but text/security-gates-docs.md
+# was never written — the promise settled green on a lie. This gate closes that
+# class: a declared derives: artifact that is missing fails the check, so /close
+# (via do-promise-settle.sh) cannot mark the promise KEPT until the file exists.
+#
+# Usage:
+#   do-derives-check.sh <slug>        # exit 0 if every true file-key exists, else 1
+#   do-derives-check.sh --self-test   # temp fixtures, zero network
+#   exit: 0 all present · 1 an artifact missing · 2 no promise file · 4 bad usage
+#
+# SCOPE — file-shaped keys ONLY. The derives: block mixes two kinds of key:
+#   (a) 1:1 DOC keys → a single deterministic text/<slug>-<key>.md path:
+#       plan · todo · docs · tutorial · how-to · reference · features · ui — CHECKED.
+#   (b) named-entity / multi-file keys with NO single deterministic path — SKIPPED:
+#       tests    (per-surface files, not one text/<slug>.test.ts),
+#       agents   (a named actor at one.ie/ai/agents/*, or the -agents-docs.md
+#                 briefing — ambiguous; security-gates' agents:true is a compliance
+#                 actor, NOT text/security-gates-agents.md — checking it false-fails),
+#       skills · tasks · tracking · routing · views (world: entries — presence-checked
+#                 by the world: traversal + the proof's own test run, not a filename).
+# v1: simple + deterministic, matched to the concrete bug (a missing DOC).
+set -u
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+
+# derives keys that map 1:1 to text/<slug>-<key>.md (padded for whole-word match)
+FILE_KEYS=" plan todo docs tutorial how-to reference features ui "
+
+# print each derives sub-key whose value is exactly `true` (first frontmatter block).
+# Ends the block on the first column-0 non-space, non-comment line (e.g. `rubric:` /
+# `world:`); blank + col-0 comment lines inside the block are tolerated. world.agents
+# is never counted — only `^derives:` opens the block.
+true_derives_keys() { # $1 = promise file
+  awk '
+    /^---[[:space:]]*$/ { fm++; if (fm>=2) exit; next }
+    fm!=1 { next }
+    /^derives:[[:space:]]*$/ { ind=1; next }
+    ind==1 && /^[^[:space:]#]/ { ind=0 }
+    ind==1 && /^[[:space:]]+[A-Za-z][A-Za-z-]*:[[:space:]]+true([[:space:]]|#|$)/ {
+      k=$0; sub(/^[[:space:]]+/,"",k); sub(/:.*/,"",k); print k
+    }
+  ' "$1"
+}
+
+check() { # $1 = slug
+  local slug="$1"
+  local file="$ROOT/text/$slug.md" missing=0 checked=0 key
+  if [ ! -f "$file" ]; then
+    echo "[derives-check] $slug — no promise file at text/$slug.md"; return 2
+  fi
+  while IFS= read -r key; do
+    [ -z "$key" ] && continue
+    case "$FILE_KEYS" in *" $key "*) ;; *) continue ;; esac   # skip named-entity keys
+    checked=$((checked+1))
+    if [ ! -f "$ROOT/text/$slug-$key.md" ]; then
+      echo "[derives-check] MISSING: derives.$key=true but text/$slug-$key.md does not exist"
+      missing=$((missing+1))
+    fi
+  done < <(true_derives_keys "$file")
+  if [ "$missing" -gt 0 ]; then
+    echo "[derives-check] $slug — $missing/$checked declared artifact(s) missing"; return 1
+  fi
+  echo "[derives-check] $slug — ok ($checked file-shaped derives artifact(s) present)"; return 0
+}
+
+if [ "${1:-}" = "--self-test" ]; then
+  dir="$(mktemp -d)"; trap 'rm -rf "$dir"' EXIT
+  mkdir -p "$dir/text"
+  fails=0
+  # green: docs:true + doc present; agents:true present but MUST be skipped (no -agents.md)
+  printf -- '---\nslug: green\nderives:\n  plan: true\n  docs: true\n  agents: true\n---\n' >"$dir/text/green.md"
+  : >"$dir/text/green-plan.md"; : >"$dir/text/green-docs.md"
+  # red: docs:true but the doc is missing
+  printf -- '---\nslug: red\nderives:\n  plan: true\n  docs: true\n---\n' >"$dir/text/red.md"
+  : >"$dir/text/red-plan.md"
+  ROOT="$dir" check green >/dev/null 2>&1 || { echo "FAIL green should pass (agents skipped)"; fails=$((fails+1)); }
+  ROOT="$dir" check red  >/dev/null 2>&1 && { echo "FAIL red should fail (missing docs)"; fails=$((fails+1)); }
+  echo "[derives-check] self-test: 2 fixtures, $fails failed"
+  exit "$fails"
+fi
+
+SLUG="${1:-}"
+[ -z "$SLUG" ] && { echo "usage: do-derives-check.sh <slug> | --self-test" >&2; exit 4; }
+check "$SLUG"

package/scripts/do-fleet.sh

@@ -31,6 +31,11 @@ RANK="$ROOT/.claude/scripts/do-rank.py"
 AUTO="$ROOT/.claude/scripts/do-auto.sh"
 WT_BASE="$ROOT/.do-worktrees"
 
+# Worktree branches cut from trunk, never HEAD — a shared tree parked on a
+# feature branch must not seed fleet plans with its commits. DO_BASE_REF overrides.
+BASE_REF="${DO_BASE_REF:-main}"
+git -C "$ROOT" show-ref --verify --quiet "refs/heads/$BASE_REF" || BASE_REF=HEAD
+
 GO=false
 SLOTS=3
 TOP=40
@@ -131,11 +136,50 @@ has_conflict() { # has_conflict <slug> → exit 0 if conflict
   return 1
 }
 
+# claim_task — fires tasks:claim before a worktree is cut (claim = lease, tasks-do C5).
+# Best-effort like do-signal.sh's world:do-event stance: no configured secret or an
+# unparseable response degrades to "ok to launch" rather than blocking the fleet. An
+# explicit already-claimed/blocked response returns 1 so fill_slots skips this slug —
+# two fleet runs (or a fleet run racing a human claim) never double-build the same task.
+claim_task() {  # claim_task <slug> → 0 ok to launch, 1 already claimed elsewhere
+  # GATEWAY_API_KEY, not SERVER_SECRET — /api/ask/<receiver>'s isServiceCaller checks
+  # env.GATEWAY_API_KEY (one.ie/web/src/pages/api/ask/[...receiver].ts). SERVER_SECRET
+  # is what /api/signal/ checks; the two routes don't share a secret. Also pin
+  # workspace so the claim's ctx.ownerSlug lands in /u/one/tasks like every other
+  # Claude Code task (do-signal.sh's CC_TASKS_WORKSPACE convention).
+  # Address the lease by the plan SLUG, never a guessed tid: real tids are minted
+  # task:<traceId> (resolvers/tasks.ts insertTaskRow), so "task:<slug>" resolved
+  # not_found for every plan and the lease could never gate. tasks:claim resolves
+  # data.slug via resolveTaskBySlug when present (resolvers/tasks.ts claim).
+  local slug="$1" secret="" f resp
+  # ONE_ENV_FILE first: the loop must be able to read credentials with no
+  # one.ie/web/ on disk. The monorepo paths stay as fallbacks and expand to
+  # nothing outside it.
+  for f in "${ONE_ENV_FILE:-${DO_ENV_FILE:-}}" "$ROOT/.env" "$ROOT/one.ie/web/.env" "$ROOT/one.ie/web/.secrets.generated.local"; do
+    [ -n "$f" ] || continue
+    [ -f "$f" ] || continue
+    secret=$(grep -E '^GATEWAY_API_KEY=' "$f" 2>/dev/null | head -1 | sed 's/^[^=]*=//;s/^"//;s/"$//' || true)
+    [ -n "$secret" ] && break
+  done
+  [ -z "$secret" ] && return 0
+  resp=$(curl -sf -X POST "${DO_SIGNAL_URL:-https://one.ie}/api/ask/tasks:claim" \
+    -H "Content-Type: application/json" -H "Authorization: Bearer $secret" \
+    -d "{\"data\":{\"slug\":\"$slug\",\"workspace\":\"${CC_TASKS_WORKSPACE:-one}\"}}" 2>/dev/null || true)
+  case "$resp" in
+    *'"ok":true'*)                 return 0 ;;   # lease held by us — launch
+    *'"error":"already-claimed"'*) echo "  ~ $slug — claimed by another actor, skipping" >&2; return 1 ;;
+    *'"error":"blocked"'*)         echo "  ~ $slug — blocked by an unresolved dependency, skipping" >&2; return 1 ;;
+    *'"error":"not_found"'*)       return 0 ;;   # no substrate task yet (claim-before-create) — launch
+    *'"error"'*)                   echo "  ! $slug — claim degraded: $resp" >&2; return 0 ;;
+    *)                             return 0 ;;   # unparseable/empty — best-effort, launch
+  esac
+}
+
 launch_plan() {  # launch_plan <slug> → echoes PID
   local slug="$1"
   local wt="$WT_BASE/$slug"
   if [ ! -d "$wt" ]; then
-    git -C "$ROOT" worktree add -b "do/$slug" "$wt" HEAD >/dev/null 2>&1 \
+    git -C "$ROOT" worktree add -b "do/$slug" "$wt" "$BASE_REF" >/dev/null 2>&1 \
       || git -C "$ROOT" worktree add "$wt" "do/$slug" >/dev/null 2>&1 || true
   fi
   link_deps "$wt"
@@ -260,6 +304,11 @@ fill_slots() {
   while [ "${#SLOT_PIDS[@]}" -lt "$SLOTS" ]; do
     pop_next
     [ -z "$NEXT_SLUG" ] && break
+    if ! claim_task "$NEXT_SLUG"; then
+      echo "  ~ $NEXT_SLUG — already claimed elsewhere, skipping"
+      DONE_SLUGS+=("$NEXT_SLUG")
+      continue
+    fi
     local pid; pid=$(launch_plan "$NEXT_SLUG")
     SLOT_PIDS+=("$pid")
     SLOT_SLUGS+=("$NEXT_SLUG")

package/scripts/do-killswitch-audit.py

@@ -54,27 +54,46 @@ def parse_outcome(text):
         lines = [re.sub(r"\\$", "", l.strip()) for l in bm.group(1).splitlines() if l.strip()]
         return " ".join(lines).strip()
     # inline form: outcome: "..."  or  outcome: ...
-    im = re.search(r'^outcome:\s*"?(.+?)"?\s*$', body, re.MULTILINE)
+    # A double-quoted YAML scalar must be unescaped (\" → ", \\ → \) and may
+    # carry a trailing comment after the closing quote — match the quoted
+    # string properly first, else the escapes leak into the shell verbatim
+    # and grep hunts for quote characters that were never in the file.
+    qm = re.search(r'^outcome:\s*"((?:[^"\\]|\\.)*)"', body, re.MULTILINE)
+    if qm:
+        return re.sub(r'\\(.)', r'\1', qm.group(1)).strip()
+    # single-quoted YAML scalar: '' is the only escape (a literal ')
+    sm = re.search(r"^outcome:\s*'((?:[^']|'')*)'", body, re.MULTILINE)
+    if sm:
+        return sm.group(1).replace("''", "'").strip()
+    im = re.search(r'^outcome:\s*(.+?)\s*$', body, re.MULTILINE)
     return im.group(1).strip() if im else ""
 
 
 def stale_cd(cmd):
     """Walk the &&/; chain tracking cwd — `cd a && cd ../b` makes ../b relative
-    to a, not to root. Return the first cd target that doesn't exist, else None."""
+    to a, not to root. A `(cd x && …)` subshell inherits the outer cwd but its
+    cd does NOT leak past the closing paren (outcomes are commonly chains of
+    subshells: `(cd web && test) && (cd channels && test)`). Parens inside
+    quotes (grep patterns) can unbalance the stack; that degrades to the outer
+    cwd, never a crash. Return the first cd target that doesn't exist, else None."""
     cwd = ROOT
+    stack = []
     for seg in re.split(r"&&|;|\|", cmd):
-        m = re.search(r"\bcd\s+([^\s&|;]+)", seg)
-        if not m:
-            continue
-        t = m.group(1)
-        nxt = Path(t) if t.startswith("/") else (cwd / t)
-        try:
-            nxt = nxt.resolve()
-        except Exception:
-            return t
-        if not nxt.exists():
-            return t
-        cwd = nxt
+        for _ in range(seg.count("(")):
+            stack.append(cwd)
+        m = re.search(r"\bcd\s+([^\s&|;)]+)", seg)
+        if m:
+            t = m.group(1)
+            nxt = Path(t) if t.startswith("/") else (cwd / t)
+            try:
+                nxt = nxt.resolve()
+            except Exception:
+                return t
+            if not nxt.exists():
+                return t
+            cwd = nxt
+        for _ in range(seg.count(")")):
+            cwd = stack.pop() if stack else ROOT
     return None
 
 

package/scripts/do-promise-lint.sh

@@ -57,6 +57,31 @@ assumes_entries() { # $1 = file
     | while IFS= read -r l; do unquote "$l"; echo; done
 }
 
+# exec_dry — IC6: catch a path-shape-fragile proof at PROMISE, before it dies
+# at settle. Runs proof: for real (env -i, from $base) and inspects stderr for
+# the classic bug: two deliverables' accept: joined by `&&`, each independently
+# written assuming CWD=repo-root, e.g. "cd A && test 1 && cd A && test 2" — the
+# second bare `cd A` runs from inside A (after the first leg), tries A/A, dies.
+# Subshell-wrapped legs ("(cd A && test 1) && (cd A && test 2)") reset CWD
+# between legs and never hit this. A non-zero exit alone is NOT a failure here —
+# red-before-green proofs are legitimately red; only the path-shape death is.
+exec_dry() { # $1 = file, $2 = base dir (default $ROOT)
+  local file="$1" base="${2:-$ROOT}" proof err
+  proof="$(extract_proof "$file")"
+  if [ -z "$proof" ]; then
+    echo "[promise-lint:exec-dry] FAIL — no proof: to test"
+    return 1
+  fi
+  err="$(cd "$base" && env -i HOME="$HOME" PATH="$PATH" bash -c "$proof" 2>&1 1>/dev/null)"
+  if printf '%s' "$err" | grep -qE 'cd: .*No such file or directory'; then
+    echo "[promise-lint:exec-dry] FAIL — path-shape death (a repeated bare 'cd X &&' leg dies once a prior leg already moved CWD into X):"
+    printf '%s\n' "$err" | grep -E 'cd: .*No such file or directory' | sed 's/^/  /'
+    return 1
+  fi
+  echo "[promise-lint:exec-dry] OK — proof is path-shape safe (a non-zero exit here is fine; red-before-green is legitimate)"
+  return 0
+}
+
 lint() { # $1 = slug, $2 = file, $3 = no_run (true/false), $4 = red (true/false)
   local slug="$1" file="$2" no_run="$3" red="$4" fails=0
   echo "[promise-lint] slug=$slug file=${file#"$ROOT"/}"
@@ -106,6 +131,28 @@ lint() { # $1 = slug, $2 = file, $3 = no_run (true/false), $4 = red (true/false)
 $(printf '%s\n' "$block" | grep '^[[:space:]]*accept:')
 EOF
 
+  # user-visible ⇒ page: a deliverable that explicitly names a page/route/view
+  # (kind prefix `route:`/`page:`/`view:`/`component:`, an .astro / src/pages/
+  # path, or the phrase "a page") must be proven by at least one accept: that
+  # actually checks the page — curl / browser-check / do-prove / an http(s) URL /
+  # a `--route /x` flag / a src/pages/ or .astro file check.
+  # Heuristic is deliberately conservative (deliverables text only, NOT the
+  # world: block) so settled promises whose UI is proven via vitest/grep
+  # (brain, chat) don't retro-fail; it catches new promises that schedule a
+  # page but never load it.
+  local vis_re='(route|page|view|component):|src/pages/|\.astro| a page '
+  local page_proof_re='curl|browser-check|do-prove|https?://|--route[[:space:]]+/|src/pages/|\.astro'
+  local vis_item
+  vis_item="$(printf '%s\n' "$block" | grep -E '^[[:space:]]*-[[:space:]]*item:' | grep -iE "$vis_re" | head -1)"
+  if [ -n "$vis_item" ]; then
+    if ! printf '%s\n' "$block" | grep '^[[:space:]]*accept:' | grep -qiE "$page_proof_re"; then
+      echo "[promise-lint] FAIL — user-visible deliverable but no page-load proof:"
+      echo "[promise-lint]   $(printf '%s' "$vis_item" | sed -E 's/^[[:space:]]*//')"
+      echo "[promise-lint]   add a route/component deliverable whose accept: loads the page (curl / browser-check / do-prove.sh --route /x / src/pages file check)"
+      fails=$((fails+1))
+    fi
+  fi
+
   # assumes: — client-side dependencies must be green at the making
   if [ "$no_run" != true ]; then
     local a_n=0
@@ -139,6 +186,60 @@ EOF
   return 1
 }
 
+# check_ui_coupling — IC9 lint coupling: when a promise's derives: block has
+# `ui: true`, its proof: must invoke `do-ui-gate.sh <slug>` (that promise's own
+# filename stem) — a UI-bearing promise can't settle without its screens
+# actually being gate-checked.
+check_ui_coupling() { # $1 = file
+  local file="$1" slug ui_val proof
+  slug="$(basename "$file" .md)"
+  ui_val="$(fm "$file" | awk '/^derives:/{on=1;next} on && /^[a-zA-Z_-]+:/{exit} on && /^[[:space:]]*ui:/{sub(/^[[:space:]]*ui:[[:space:]]*/,"");print;exit}')"
+  ui_val="$(unquote "$ui_val" | sed -E 's/^[[:space:]]+|[[:space:]]+$//g')"
+  if [ "$ui_val" != "true" ]; then
+    echo "[promise-lint:ui-coupling] skip — derives.ui != true (slug=$slug)"
+    return 0
+  fi
+  proof="$(extract_proof "$file")"
+  if printf '%s' "$proof" | grep -qF "do-ui-gate.sh $slug"; then
+    echo "[promise-lint:ui-coupling] OK — proof invokes do-ui-gate.sh $slug"
+    return 0
+  fi
+  echo "[promise-lint:ui-coupling] FAIL — derives.ui: true but proof: does not invoke 'do-ui-gate.sh $slug'"
+  return 1
+}
+
+# ── self-test: ui-coupling fixtures, zero network ────────────────────────────
+if [ "${1:-}" = "--self-test-ui-coupling" ]; then
+  dir="$(mktemp -d)"; trap 'rm -rf "$dir"' EXIT
+  cat >"$dir/uinocheck.md" <<'F'
+---
+derives:
+  ui:        true
+proof: "true"
+---
+F
+  cat >"$dir/uigood.md" <<'F'
+---
+derives:
+  ui:        true
+proof: "bash .claude/scripts/do-ui-gate.sh uigood"
+---
+F
+  cat >"$dir/nouify.md" <<'F'
+---
+derives:
+  ui:        false
+proof: "true"
+---
+F
+  fails=0
+  check_ui_coupling "$dir/uinocheck.md" >/dev/null && { echo "FAIL: expected ui-coupling FAIL when ui:true but proof lacks do-ui-gate.sh"; fails=$((fails+1)); }
+  check_ui_coupling "$dir/uigood.md" >/dev/null || { echo "FAIL: expected ui-coupling PASS when proof invokes do-ui-gate.sh <slug>"; fails=$((fails+1)); }
+  check_ui_coupling "$dir/nouify.md" >/dev/null || { echo "FAIL: expected ui-coupling PASS (skip) when ui:false"; fails=$((fails+1)); }
+  echo "[promise-lint] self-test-ui-coupling: 3 fixtures, $fails failed"
+  exit "$fails"
+fi
+
 # ── self-test: fixtures, zero network ────────────────────────────────────────
 if [ "${1:-}" = "--self-test" ]; then
   dir="$(mktemp -d)"; trap 'rm -rf "$dir"' EXIT
@@ -194,6 +295,22 @@ assumes:
   - "false"
 proof: "test -f a"
 ---
+F
+  cat >"$dir/pagegap.md" <<'F'
+---
+deliverables:
+  - item: "route: /foo — user sees the page"
+    accept: "grep -q foo a.ts"
+proof: "grep -q foo a.ts"
+---
+F
+  cat >"$dir/pagegood.md" <<'F'
+---
+deliverables:
+  - item: "route: /foo — user sees the page"
+    accept: "curl -sf https://one.ie/foo"
+proof: "curl -sf https://one.ie/foo"
+---
 F
   fails=0
   lint good "$dir/good.md" true false >/dev/null        || { echo "FAIL good → 0"; fails=$((fails+1)); }
@@ -203,19 +320,48 @@ F
   lint emptyproof "$dir/emptyproof.md" true false >/dev/null && { echo "FAIL emptyproof → 1"; fails=$((fails+1)); }
   lint badassume "$dir/badassume.md" false false >/dev/null && { echo "FAIL badassume → 1"; fails=$((fails+1)); }
   lint redcheck "$dir/gap.md" true true >/dev/null      && { echo "FAIL red-on-gap → 1"; fails=$((fails+1)); }
-  echo "[promise-lint] self-test: 7 fixtures, $fails failed"
+  lint pagegap "$dir/pagegap.md" true false >/dev/null  && { echo "FAIL pagegap → 1 (user-visible, no page proof)"; fails=$((fails+1)); }
+  lint pagegood "$dir/pagegood.md" true false >/dev/null || { echo "FAIL pagegood → 0"; fails=$((fails+1)); }
+  echo "[promise-lint] self-test: 9 fixtures, $fails failed"
+  exit "$fails"
+fi
+
+# ── self-test: exec-dry fixtures, zero network ───────────────────────────────
+if [ "${1:-}" = "--self-test-exec-dry" ]; then
+  dir="$(mktemp -d)"; trap 'rm -rf "$dir"' EXIT
+  mkdir -p "$dir/leg"
+  touch "$dir/leg/marker"
+  cat >"$dir/failcase.md" <<'F'
+---
+proof: "cd leg && test -f marker && cd leg && test -f marker"
+---
+F
+  cat >"$dir/passcase.md" <<'F'
+---
+proof: "(cd leg && test -f marker) && (cd leg && test -f marker)"
+---
+F
+  fails=0
+  exec_dry "$dir/failcase.md" "$dir" >/dev/null && { echo "FAIL: expected exec-dry FAIL on repeated bare 'cd leg &&' legs"; fails=$((fails+1)); }
+  exec_dry "$dir/passcase.md" "$dir" >/dev/null || { echo "FAIL: expected exec-dry PASS on subshell-wrapped legs"; fails=$((fails+1)); }
+  echo "[promise-lint] self-test-exec-dry: 2 fixtures, $fails failed"
   exit "$fails"
 fi
 
 # ── main ─────────────────────────────────────────────────────────────────────
 SLUG="${1:-}"; [ -z "$SLUG" ] && { grep '^# ' "$0" | sed 's/^# //' | sed -n '3,24p'; exit 4; }
 shift
-NO_RUN=false; RED=false
+NO_RUN=false; RED=false; EXEC_DRY=false
 while [ $# -gt 0 ]; do
   case "$1" in
-    --no-run) NO_RUN=true; shift ;;
-    --red)    RED=true; shift ;;
+    --no-run)   NO_RUN=true; shift ;;
+    --red)      RED=true; shift ;;
+    --exec-dry) EXEC_DRY=true; shift ;;
     *) echo "unknown flag $1"; exit 4 ;;
   esac
 done
+if $EXEC_DRY; then
+  exec_dry "${PROMISE_FILE:-$ROOT/text/$SLUG.md}"
+  exit $?
+fi
 lint "$SLUG" "${PROMISE_FILE:-$ROOT/text/$SLUG.md}" "$NO_RUN" "$RED"

package/scripts/do-promise-settle.sh

@@ -24,6 +24,35 @@ set -u
 ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
 BASE="${ONE_API_URL:-http://localhost:4321}"
 
+# Credentials come from ONE_ENV_FILE (DO_ENV_FILE is the accepted alias), the same
+# indirection do-signal.sh and do-fleet.sh honour and that factory-repo.sh's
+# --check-env-indirection enforces for every shipped credential-reading script.
+#
+# This script read $GATEWAY_API_KEY from the PROCESS environment only, and nothing
+# exports it — so it never sent an Authorization header and every mark/warn 401'd.
+# The failure was invisible because a 401 printed "wire unreachable, broadcast-only":
+# the settle blaming the network for its own missing credential. Measured 2026-08-02
+# settling pages-fill-pack and tauri — both proofs exit 0, both marks 401, against a
+# localhost:4321 answering 200. tauri had already settled KEPT this way once before.
+ONE_ENV_FILE="${ONE_ENV_FILE:-${DO_ENV_FILE:-one.ie/web/.env}}"
+DO_ENV_FILE="$ONE_ENV_FILE"
+
+# Unquoted on purpose: expands 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/.dev.vars"
+
+# Reads a key out of the first env file that carries it. Never echoes the value
+# anywhere but its own stdout, which the caller assigns straight to a local.
+_env_key() { # $1 = key name
+  local _f _v
+  for _f in "$ONE_ENV_FILE" "$ROOT/.env" $_MONOREPO_ENV_CANDIDATES; do
+    [ -f "$_f" ] || continue
+    _v=$(grep -E "^$1=" "$_f" 2>/dev/null | head -1 | sed 's/^[^=]*=//;s/^"//;s/"$//' || true)
+    [ -n "$_v" ] && { printf '%s' "$_v"; return 0; }
+  done
+  printf ''
+}
+
 usage() { grep '^# ' "$0" | sed 's/^# //' | sed -n '3,14p'; exit 4; }
 
 # ── frontmatter proof: extractor (first frontmatter block only) ──────────────
@@ -82,6 +111,55 @@ settle() { # $1 = slug, $2 = promise file, $3 = composite ("" = none), $4 = dry-
   local rc=0
   ( cd "$ROOT" && bash -c "$proof" ) >/dev/null 2>&1 || rc=$?
 
+  # EXIT 3 IS "COULD NOT RUN", NOT "BROKEN". A proof: is an `&&`-join, so a leg
+  # that cannot reach its substrate stops the chain and the join returns 3 — and
+  # this script used to fold that into `else → warn`. A TypeDB blip would then
+  # deposit resistance on a proven path, permanently, for infrastructure noise:
+  # the settle would record a promise as BROKEN for a reason the maker cannot
+  # fix and did not cause. text/factory.md § "A note on red vs cannot run" states
+  # the rule — "exit 3 anywhere in the chain means re-run later, never warn" —
+  # and until now the tool that enforces promises did not implement the sharpest
+  # idea in them.
+  #
+  # An unverifiable promise closes NOTHING: no mark, no warn, no on-chain settle,
+  # and the loop stays open by design. It is not `dissolved` either — dissolved
+  # means there is no observable to run (rule 1's third exit); here the observable
+  # exists and was simply unreachable. The caller re-runs later. /close must treat
+  # exit 3 as "not settled yet", never as a close.
+  if [ "$rc" -eq 3 ]; then
+    echo "[promise-settle] proof exit=3 → UNVERIFIABLE (substrate unreachable) — no mark, no warn, promise stays open"
+    echo "[promise-settle] re-run when the substrate answers: $0 $slug"
+    if [ "$dry" = true ]; then
+      echo "[promise-settle] DRY would write no path and broadcast unverifiable"
+      return 3
+    fi
+    # Announce it anyway: an unverifiable settle is news the world can act on
+    # (someone can fix the cluster), and the broadcast writes no path.
+    # shellcheck source=/dev/null
+    source "$ROOT/.claude/hooks/lib/signal.sh" 2>/dev/null && \
+      emit_world "promise" "fyi" "promise,do,unverifiable,$slug" \
+        "promise $slug UNVERIFIABLE — proof could not run; no path written" "proof_exit=3"
+    echo "[promise-settle] broadcast world:announce queued (fire-and-forget, unconfirmed) tags=[promise,do,unverifiable,$slug]"
+    return 3
+  fi
+
+  # derives gate — a promise cannot settle KEPT while an artifact its derives: block
+  # declares true is missing on disk (the class that let security-gates ship a missing
+  # -docs.md). Zero LLM; folds into the verdict so the close still ends in mark/warn.
+  # Only exit 1 ("artifact missing") overrides kept→broken — exit 2 ("no promise file
+  # at the conventional text/<slug>.md path") is a different failure class (e.g. a
+  # settle() call against a custom PROMISE_FILE, or a self-test fixture slug with no
+  # real promise on disk) and must not be conflated with a genuinely broken promise.
+  if [ "$rc" -eq 0 ]; then
+    local derives_out derives_rc=0
+    derives_out="$(bash "$ROOT/.claude/scripts/do-derives-check.sh" "$slug" 2>&1)" || derives_rc=$?
+    if [ "$derives_rc" -eq 1 ]; then
+      echo "[promise-settle] derives-check FAILED — declared artifact missing; overriding kept→broken:"
+      echo "$derives_out" | sed 's/^/[promise-settle]   /'
+      rc=1
+    fi
+  fi
+
   local verb strength verdict
   if [ "$rc" -eq 0 ]; then
     verdict=kept; verb=mark
@@ -94,7 +172,7 @@ settle() { # $1 = slug, $2 = promise file, $3 = composite ("" = none), $4 = dry-
   local edge="promise:${slug}→proof"
   if [ "$dry" = true ]; then
     echo "[promise-settle] DRY $verb $edge strength=$strength"
-    echo "[promise-settle] DRY broadcast world:announce tags=[promise,do,$verdict,$slug]"
+    echo "[promise-settle] DRY broadcast world:announce queued (fire-and-forget, unconfirmed) tags=[promise,do,$verdict,$slug]"
     if [ -n "${SUI_PRIVATE_KEY:-}" ]; then
       echo "[promise-settle] DRY on-chain settle_promise kept=$([ "$verdict" = kept ] && echo true || echo false) signer=env-override"
     else
@@ -112,20 +190,46 @@ settle() { # $1 = slug, $2 = promise file, $3 = composite ("" = none), $4 = dry-
   local -a hdr=(-H 'Content-Type: application/json')
   # Secrets off argv (ps aux would leak a bare -H value) — fold both into a
   # private 0600 curl --config file instead.
+  # Environment wins over the env file, so an explicit export still overrides.
+  local gsecret gkey
+  gsecret="${GATEWAY_SERVICE_SECRET:-$(_env_key GATEWAY_SERVICE_SECRET)}"
+  gkey="${GATEWAY_API_KEY:-$(_env_key GATEWAY_API_KEY)}"
   local authcfg=""
-  if [ -n "${GATEWAY_SERVICE_SECRET:-}" ] || [ -n "${GATEWAY_API_KEY:-}" ]; then
+  if [ -n "$gsecret" ] || [ -n "$gkey" ]; then
     authcfg="$(mktemp)"; chmod 600 "$authcfg"
-    [ -n "${GATEWAY_SERVICE_SECRET:-}" ] && printf 'header = "X-Gateway-Key: %s"\n' "$GATEWAY_SERVICE_SECRET" >>"$authcfg"
-    [ -n "${GATEWAY_API_KEY:-}" ] && printf 'header = "Authorization: Bearer %s"\n' "$GATEWAY_API_KEY" >>"$authcfg"
+    [ -n "$gsecret" ] && printf 'header = "X-Gateway-Key: %s"\n' "$gsecret" >>"$authcfg"
+    [ -n "$gkey" ] && printf 'header = "Authorization: Bearer %s"\n' "$gkey" >>"$authcfg"
     hdr+=(--config "$authcfg")
   fi
-  http="$(curl -sS -o /dev/null -w '%{http_code}' --max-time 5 -X POST "$BASE/api/$verb/$enc" \
-    "${hdr[@]}" -d "{\"strength\":$strength,\"tags\":[\"promise\",\"do\",\"$slug\"]}" 2>/dev/null || echo 000)"
+  # --max-time 20, not 5. This POST is a SUBSTRATE WRITE: the route authenticates,
+  # then opens a TypeDB transaction against the cloud cluster, where a cold sign-in
+  # alone measured 4.1s (factory-check.sh header, 2026-07-29). A 5s ceiling made a
+  # healthy system report "wire unreachable" — the settle blaming the network for
+  # its own stopwatch, which is exactly what /factory's gaps board did before it
+  # was fixed. Measured after the change: the same call answers well inside 20s.
+  #
+  # curl's own failure is captured separately. `|| echo 000` appended a second
+  # "000" to the -w output, printing http=000000 — a status code that does not
+  # exist, in the line an operator reads to decide whether the path moved.
+  local curl_rc=0
+  http="$(curl -sS -o /dev/null -w '%{http_code}' --max-time 20 -X POST "$BASE/api/$verb/$enc" \
+    "${hdr[@]}" -d "{\"strength\":$strength,\"tags\":[\"promise\",\"do\",\"$slug\"]}" 2>/dev/null)" || curl_rc=$?
+  [ "$curl_rc" -ne 0 ] && http="000 (curl rc=$curl_rc)"
   [ -n "$authcfg" ] && rm -f "$authcfg"
+  # Name the failure accurately. Calling a 401 "wire unreachable" is what hid the
+  # missing-credential bug above: an operator reading that line goes looking at the
+  # network for a fault that is entirely local.
   if [ "$http" = 200 ]; then
     echo "[promise-settle] $verb $edge strength=$strength http=$http"
   else
-    echo "[promise-settle] $verb $edge strength=$strength http=$http — wire unreachable, broadcast-only"
+    local why
+    case "$http" in
+      401|403) why="AUTH REJECTED — no/!bad GATEWAY_API_KEY; checked ONE_ENV_FILE=$ONE_ENV_FILE. Substrate NOT written" ;;
+      000*)    why="wire unreachable ($BASE)" ;;
+      404)     why="no such route at $BASE/api/$verb — substrate NOT written" ;;
+      *)       why="substrate NOT written" ;;
+    esac
+    echo "[promise-settle] $verb $edge strength=$strength http=$http — $why, broadcast-only"
   fi
 
   # public broadcast — the world hears the settlement regardless of the substrate wire
@@ -133,7 +237,14 @@ settle() { # $1 = slug, $2 = promise file, $3 = composite ("" = none), $4 = dry-
   source "$ROOT/.claude/hooks/lib/signal.sh" 2>/dev/null && \
     emit_world "promise" "fyi" "promise,do,$verdict,$slug" \
       "promise $slug $verdict — $verb $edge strength=$strength" "proof_exit=$rc"
-  echo "[promise-settle] broadcast world:announce tags=[promise,do,$verdict,$slug]"
+  # NOT a confirmation. emit_world curls in a background subshell, discards the
+  # response and returns 0 unconditionally — by design, since it also runs from
+  # hooks that must never block. So this line reports what was QUEUED, not what
+  # the world heard. Printing it as a delivery would be a settle announcing its
+  # own success on no evidence, which is the failure class this whole promise
+  # family exists to name. Confirming it needs a synchronous emitter; until then
+  # the wording carries the uncertainty.
+  echo "[promise-settle] broadcast world:announce queued (fire-and-forget, unconfirmed) tags=[promise,do,$verdict,$slug]"
 
   # on-chain twin — settle_promise on the generated Move object (schema/sui.tql →
   # substrate.move). Fires only when armed (signer present + object minted); the
@@ -183,6 +294,10 @@ if [ "${1:-}" = "--self-test" ]; then
   printf -- '---\ntitle: no proof here\n---\n' >"$dir/noproof.md"
   printf -- '---\nproof: "[ \\"a\\" = \\"a\\" ]"\n---\n' >"$dir/escaped-quotes.md"
   printf -- '---\nproof: "true"\ncontract:\n  oracle: "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"\n---\n' >"$dir/unmatchable-oracle.md"
+  # cannot-run: the `&&`-join stops at a leg that exits 3, so the join returns 3.
+  # The second leg must NEVER run — if it did, this fixture would return 0 and the
+  # test would pass for the wrong reason.
+  printf -- '---\nproof: "exit 3 && true"\n---\n' >"$dir/cannotrun.md"
   fails=0
   out="$(settle kept-fixture "$dir/kept.md" 0.8 true)"
   echo "$out" | grep -q 'DRY mark .*strength=4' || { echo "FAIL kept → mark strength=4"; fails=$((fails+1)); }
@@ -195,7 +310,14 @@ if [ "${1:-}" = "--self-test" ]; then
   rc=$?
   echo "$out" | grep -q 'DRY on-chain: unmatchable oracle=0xffff.*would skip' || { echo "FAIL unmatchable-oracle → clean skip, no wrong-key attempt"; fails=$((fails+1)); }
   [ "$rc" -eq 0 ] || { echo "FAIL unmatchable-oracle → exit 0"; fails=$((fails+1)); }
-  echo "[promise-settle] self-test: 5 fixtures, $fails failed"
+  # cannot-run must be its OWN verdict: exit 3, and NEITHER verb written. The bug
+  # this fixture pins is a cluster blip settling a promise BROKEN and warning its
+  # path — so asserting "not mark" is not enough; assert "not warn" explicitly.
+  out="$(settle cannotrun-fixture "$dir/cannotrun.md" "" true)"; rc=$?
+  [ "$rc" -eq 3 ] || { echo "FAIL cannot-run → exit 3 (got $rc)"; fails=$((fails+1)); }
+  echo "$out" | grep -q 'UNVERIFIABLE' || { echo "FAIL cannot-run → says UNVERIFIABLE"; fails=$((fails+1)); }
+  echo "$out" | grep -qE 'DRY (warn|mark) ' && { echo "FAIL cannot-run → wrote a path verb (must write neither)"; fails=$((fails+1)); }
+  echo "[promise-settle] self-test: 6 fixtures, $fails failed"
   exit "$fails"
 fi