@oneie/claude 0.6.0 → 0.7.0

package/scripts/do-ui-gate.sh

@@ -0,0 +1,332 @@
+#!/usr/bin/env bash
+# do-ui-gate.sh — IC9: executable proof rows for a promise's screens/states.
+#
+# Reads the ```ui fenced blocks out of text/<slug>-ui.md — same fenced-block
+# convention as do-walk.sh's ```walk blocks — and executes them:
+#
+#   ```ui
+#   row: 1
+#   component: LoginButton
+#   state: default
+#   route: /login
+#   expect_text: "Sign in"            # optional — substring in the served HTML
+#   expect_cmd: test -f x.tsx         # optional bash, exit 0 = pass
+#   check: renders a blue primary button
+#   ```
+#
+# Rows may be moved under a `## Deferred` heading, but that ONLY skips them
+# if the Deferred section's body contains a line `promise: <slug>` (ties the
+# deferral to a tracked promise — otherwise the gate FAILs; UI work can't be
+# silently waived).
+#
+# Usage:
+#   do-ui-gate.sh <slug> [--list]     # print parsed rows (active vs deferred), run nothing
+#   do-ui-gate.sh <slug>              # run active rows against a live/self-started dev server
+#   do-ui-gate.sh --self-test
+#
+# Env:
+#   UI_GATE_BASE_URL   force the base URL (skips sentinel detection + self-start)
+#
+# Base URL resolution (when UI_GATE_BASE_URL unset):
+#   1. derive port = 4400 + (cksum of slug) % 100 (same derivation as do-auto.sh's
+#      _sentinel_port, IC1) and check .do-worktrees/<slug>/.do-loop-running for a
+#      live pid on that port
+#   2. else self-start `astro dev --port <port>` from one.ie/web, poll for 200
+#      up to 60s, run rows, then kill the server it started
+#
+# Exit codes: 0 = every active row passed (or --list) · 1 = a row failed, or an
+# undeferred waive (rows after ## Deferred with no `promise: <slug>` line).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+# ---------- parse helpers (copied from do-walk.sh, fence tag `ui`) ----------
+
+# extract_stops <file> → lines "N<TAB>key: value" for every ```ui block
+extract_stops() {
+  awk '
+    /^```ui[[:space:]]*$/ { inb=1; n++; next }
+    /^```[[:space:]]*$/   { inb=0; next }
+    inb                   { print n "\t" $0 }
+  ' "$1"
+}
+
+# field <stops> <n> <key> → value, empty if absent (fence-agnostic)
+field() {
+  printf '%s\n' "$1" | awk -F'\t' -v n="$2" -v k="$3" '
+    $1 == n {
+      line = $2
+      prefix = k ": "
+      if (index(line, prefix) == 1) {
+        v = substr(line, length(prefix) + 1)
+        sub(/[ \t]+$/, "", v)
+        len = length(v)
+        if (len >= 2) {
+          first = substr(v, 1, 1); last = substr(v, len, 1)
+          if ((first == "\"" && last == "\"") || (first == "'"'"'" && last == "'"'"'")) {
+            v = substr(v, 2, len - 2)
+          }
+        }
+        print v
+        exit
+      }
+    }'
+}
+
+# _sentinel_port <slug> — must match do-auto.sh's derivation exactly
+_sentinel_port() {
+  echo $(( 4400 + $(cksum <<<"$1" | cut -d' ' -f1) % 100 ))
+}
+
+# split_rows <file> <stops> <ids> → prints two files: $1.active $1.deferred
+# (as global vars ACTIVE_IDS / DEFERRED_IDS, newline-separated row numbers)
+split_deferred() { # $1 = ui.md file, $2 = stops
+  local file="$1"
+  awk '/^##[[:space:]]*Deferred/{print NR; exit}' "$file"
+}
+
+deferred_section_names_promise() { # $1 = file, $2 = slug
+  local file="$1" slug="$2" ln
+  ln="$(awk '/^##[[:space:]]*Deferred/{print NR; exit}' "$file")"
+  [ -z "$ln" ] && return 1
+  tail -n "+$ln" "$file" | grep -qE "^promise:[[:space:]]*${slug}[[:space:]]*$"
+}
+
+row_line_number() { # $1 = file, $2 = row n → line number of the ```ui fence that starts row n
+  awk -v want="$2" '
+    /^```ui[[:space:]]*$/ { n++; if (n == want) { print NR; exit } }
+  ' "$1"
+}
+
+# ---------- self-test ----------
+
+if [ "${1:-}" = "--self-test" ]; then
+  tmpdir="$(mktemp -d)"; trap 'rm -rf "$tmpdir"' EXIT
+  fails=0
+
+  # fixture 1: one passing row, one failing row (both expect_cmd, no route) — expect exit 1
+  f1="$tmpdir/f1-ui.md"
+  cat > "$f1" <<'EOF'
+## Row 1
+```ui
+row: 1
+component: A
+state: default
+expect_cmd: true
+check: always passes
+```
+## Row 2
+```ui
+row: 2
+component: B
+state: default
+expect_cmd: false
+check: always fails
+```
+EOF
+  if UI_GATE_SELF_TEST=1 bash "${BASH_SOURCE[0]}" _fixture_f1 --file "$f1" >/dev/null 2>&1; then
+    echo "FAIL: fixture1 expected exit 1 (one failing row), got 0"; fails=$((fails+1))
+  fi
+
+  # fixture 2: failing row moved under ## Deferred, no `promise: <slug>` line — expect exit 1 (undeferred waive)
+  f2="$tmpdir/f2-ui.md"
+  cat > "$f2" <<'EOF'
+## Row 1
+```ui
+row: 1
+component: A
+state: default
+expect_cmd: true
+check: always passes
+```
+## Deferred
+Some other note, no promise line here.
+```ui
+row: 2
+component: B
+state: default
+expect_cmd: false
+check: always fails
+```
+EOF
+  if UI_GATE_SELF_TEST=1 bash "${BASH_SOURCE[0]}" _fixture_f2 --file "$f2" >/dev/null 2>&1; then
+    echo "FAIL: fixture2 expected exit 1 (undeferred waive), got 0"; fails=$((fails+1))
+  fi
+
+  # fixture 3: same deferred row, but section names `promise: <slug>` — expect exit 0
+  f3="$tmpdir/f3-ui.md"
+  cat > "$f3" <<'EOF'
+## Row 1
+```ui
+row: 1
+component: A
+state: default
+expect_cmd: true
+check: always passes
+```
+## Deferred
+promise: _fixture_f3
+```ui
+row: 2
+component: B
+state: default
+expect_cmd: false
+check: always fails
+```
+EOF
+  if ! UI_GATE_SELF_TEST=1 bash "${BASH_SOURCE[0]}" _fixture_f3 --file "$f3" >/dev/null 2>&1; then
+    echo "FAIL: fixture3 expected exit 0 (properly deferred), got nonzero"; fails=$((fails+1))
+  fi
+
+  echo "[ui-gate] self-test: 3 fixtures, $fails failed"
+  exit "$fails"
+fi
+
+# ---------- args ----------
+
+slug="" list=0 file_override=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --list) list=1; shift ;;
+    --file) [ "$#" -ge 2 ] || { echo "UI-GATE: --file requires a value"; exit 1; }
+            file_override="$2"; shift 2 ;;   # internal: used by --self-test fixtures
+    -*)     echo "UI-GATE: unknown flag $1"; exit 1 ;;
+    *)      slug="$1"; shift ;;
+  esac
+done
+[ -n "$slug" ] || { echo "UI-GATE: usage: do-ui-gate.sh <slug> [--list]"; exit 1; }
+
+file="${file_override:-$ROOT/text/${slug}-ui.md}"
+[ -f "$file" ] || { echo "UI-GATE: no ui doc at text/${slug}-ui.md"; exit 1; }
+
+stops="$(extract_stops "$file")"
+[ -n "$stops" ] || { echo "UI-GATE: text/${slug}-ui.md has no \`\`\`ui blocks"; exit 1; }
+ids="$(printf '%s\n' "$stops" | awk -F'\t' '{print $1}' | sort -un)"
+
+deferred_at_line="$(awk '/^##[[:space:]]*Deferred/{print NR; exit}' "$file")"
+
+active_ids=""; deferred_ids=""
+for n in $ids; do
+  rln="$(row_line_number "$file" "$n")"
+  if [ -n "$deferred_at_line" ] && [ "$rln" -gt "$deferred_at_line" ]; then
+    deferred_ids="$deferred_ids $n"
+  else
+    active_ids="$active_ids $n"
+  fi
+done
+
+if [ -n "$deferred_ids" ]; then
+  if ! deferred_section_names_promise "$file" "$slug"; then
+    echo "UI-GATE: FAIL — rows$deferred_ids are under ## Deferred but that section does not name \`promise: $slug\` — UI work cannot be silently waived"
+    exit 1
+  fi
+  echo "UI-GATE: rows$deferred_ids deferred to promise: $slug (skipped)"
+fi
+
+echo "UI-GATE: $slug · $(printf '%s\n' "$active_ids" | wc -w | tr -d ' ') active row(s)"
+
+# ---------- list mode ----------
+
+if [ "$list" -eq 1 ]; then
+  for n in $active_ids; do
+    c="$(field "$stops" "$n" component)"; s="$(field "$stops" "$n" state)"
+    r="$(field "$stops" "$n" route)"; ck="$(field "$stops" "$n" check)"
+    echo "  active $n. $c/$s${r:+ → $r}"
+    [ -n "$ck" ] && echo "     $ck"
+  done
+  for n in $deferred_ids; do
+    c="$(field "$stops" "$n" component)"; s="$(field "$stops" "$n" state)"
+    echo "  deferred $n. $c/$s"
+  done
+  exit 0
+fi
+
+# ---------- zero-network short-circuit (self-test fixtures) ----------
+# If no active row needs a route/expect_text (only expect_cmd rows), skip the
+# base-URL bootstrap entirely — keeps --self-test zero-network.
+needs_network=0
+for n in $active_ids; do
+  r="$(field "$stops" "$n" route)"
+  [ -n "$r" ] && needs_network=1
+done
+
+base=""
+started_server=0
+server_pid=""
+
+if [ "$needs_network" -eq 1 ]; then
+  base="${UI_GATE_BASE_URL:-}"
+  port="$(_sentinel_port "$slug")"
+
+  if [ -z "$base" ]; then
+    sentinel="$ROOT/.do-worktrees/$slug/.do-loop-running"
+    if [ -f "$sentinel" ]; then
+      spid="$(grep -o '"pid":[0-9]*' "$sentinel" | head -1 | cut -d: -f2 || true)"
+      sport="$(grep -o '"port":[0-9]*' "$sentinel" | head -1 | cut -d: -f2 || true)"
+      if [ -n "$spid" ] && kill -0 "$spid" 2>/dev/null && [ -n "$sport" ]; then
+        if curl -sf -o /dev/null --max-time 3 "http://localhost:$sport/" 2>/dev/null; then
+          base="http://localhost:$sport"
+        fi
+      fi
+    fi
+  fi
+
+  if [ -z "$base" ]; then
+    echo "UI-GATE: self-starting dev server on port $port"
+    ( cd "$ROOT/one.ie/web" && exec ./node_modules/.bin/astro dev --port "$port" ) >/tmp/ui-gate-$slug.log 2>&1 &
+    server_pid=$!
+    started_server=1
+    base="http://localhost:$port"
+    ok=0
+    for _ in $(seq 1 30); do
+      if curl -sf -o /dev/null --max-time 2 "$base/" 2>/dev/null; then ok=1; break; fi
+      sleep 2
+    done
+    if [ "$ok" -ne 1 ]; then
+      echo "UI-GATE: FAIL — dev server on $base did not come up within 60s"
+      kill "$server_pid" 2>/dev/null || true
+      exit 1
+    fi
+  fi
+  echo "UI-GATE: base=$base"
+fi
+
+cleanup() {
+  if [ "$started_server" -eq 1 ] && [ -n "$server_pid" ]; then
+    kill "$server_pid" 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
+
+# ---------- run ----------
+
+fail=0
+for n in $active_ids; do
+  c="$(field "$stops" "$n" component)"; s="$(field "$stops" "$n" state)"
+  r="$(field "$stops" "$n" route)"
+  et="$(field "$stops" "$n" expect_text)"
+  ec="$(field "$stops" "$n" expect_cmd)"
+
+  ok=1; why=""
+  if [ -n "$r" ] && [ -n "$base" ]; then
+    body="$(curl -s --max-time 20 "$base$r" 2>/dev/null || true)"
+    if [ -z "$body" ]; then ok=0; why="no response from $base$r"; fi
+    if [ "$ok" -eq 1 ] && [ -n "$et" ] && ! printf '%s' "$body" | grep -qiF "$et"; then
+      ok=0; why="text '$et' not in served HTML"
+    fi
+  fi
+  if [ "$ok" -eq 1 ] && [ -n "$ec" ]; then
+    if ! (cd "$ROOT" && bash -c "$ec" >/dev/null 2>&1); then ok=0; why="expect_cmd failed: $ec"; fi
+  fi
+
+  if [ "$ok" -eq 1 ]; then
+    echo "UI-GATE: ok row $n — $c/$s"
+  else
+    echo "UI-GATE: FAIL row $n — $c/$s — $why"
+    fail=1
+  fi
+done
+
+echo ""
+if [ "$fail" -eq 1 ]; then echo "UI-GATE: fail"; exit 1; fi
+echo "UI-GATE: pass"; exit 0

package/scripts/do-untracked-gate.sh

@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+# do-untracked-gate.sh — a deliverable that exists on disk but is NOT in git has
+# not shipped. This gate is the only check in the harness that can say so.
+#
+# WHY (the real failure, 2026-07-28, plan `factory`): two shipped deliverables —
+#   packages/sdk/src/fn-allowlist.ts            (C8's single source of truth)
+#   one.ie/web/tests/unit/fn-entity-args.test.ts (C7's proof)
+# sat UNTRACKED for hours while every acceptance check stayed GREEN, because
+# every check reads the WORKING TREE. Built, tested, passing, and on a path to
+# never reach main. A human running `git status` caught it; no gate did.
+#
+# That is the promise's own failure class — "built but not wired" — one level
+# lower than it was being looked for. factory-check.sh asks "is it live in the
+# substrate?"; this asks the question underneath it: "is it even in the repo?"
+#
+# Usage:
+#   do-untracked-gate.sh <slug> [--verbose]   # e.g. do-untracked-gate.sh factory
+#   do-untracked-gate.sh --self-test          # temp git fixtures, zero network
+#
+# Exit: 0 = green (every existing deliverable file is tracked)
+#       1 = red   (a deliverable exists on disk and is untracked or gitignored)
+#       3 = cannot run (not a git repo, or neither text/<slug>.md nor -todo.md)
+#       4 = bad usage
+#
+# 1 vs 3 is the same distinction factory-check.sh draws: red sends someone to
+# `git add`; cannot-run sends them to fix the environment, and proves nothing
+# either way. Never widen a cannot-run into a red to make a chain simpler.
+#
+# WHAT IT READS — the `deliverables:` frontmatter block of BOTH text/<slug>.md
+# (the promise: `- item:` / `accept:` prose) and text/<slug>-todo.md (the plan:
+# `- <kind>: "path — description"`). Paths live in prose, so every path-shaped
+# token in the block is a candidate. Comments inside the block are scanned too:
+# a path worth naming in the schedule is a path worth having in git.
+#
+# WHAT IT DOES NOT DO — it never reports a MISSING file. A deliverable path that
+# does not exist is simply not built yet; that is factory-check.sh's / the
+# promise proof's job. This gate has exactly one question: of the files that
+# DO exist, is any of them invisible to git?
+set -uo pipefail
+
+ROOT="${DO_UNTRACKED_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+VERBOSE=0
+say()    { [ "$VERBOSE" -eq 1 ] && echo "      $*" >&2; return 0; }
+red()    { echo "RED  $1" >&2; return 1; }
+cannot() { echo "CANNOT RUN: $1" >&2; return 3; }
+
+# Paths that are legitimately absent from git and are never a deliverable.
+# A `#` comment inside a deliverables block may name one (e.g. an assumes-style
+# credential file); reporting those as red would be noise, not a finding.
+# `.env` / `.dev.vars` are named inside real `accept:` command lines (sui-upgrade's
+# accept sources a key from pay/backend/.dev.vars) — a local secrets file is never
+# a deliverable, and flagging it as "can never ship" is noise that trains the
+# reader to ignore the gate.
+SKIP_RE='(^|/)(node_modules|dist|build|\.wrangler|\.astro)/|(^|/)\.env|(^|/)\.dev\.vars|\.local\.md$|\.keys\.local'
+
+# ── the deliverables: frontmatter block ──────────────────────────────────
+# First frontmatter block only. Opens on `^deliverables:` — WITH an optional
+# trailing comment: text/marketplace-deal.md and text/template-feature.md both
+# write `deliverables:              # THE SCHEDULE …`, and an anchored
+# `[[:space:]]*$` never opened the block for them. That produced the worst
+# possible verdict — `ok (0 files checked)`, a green earned by reading nothing.
+#
+# Closes on the first column-0 KEY (`assumes:`, `ux_before:`, `proof:`), not on
+# any column-0 non-space char: the equally-valid YAML style puts `- item:` at
+# column 0, and closing on `-` would end the block at its first entry — the same
+# read-nothing green by a different door. Blank lines and comments inside the
+# block are tolerated; the closing `---` ends it via the fm counter.
+deliverables_block() { # $1 = file
+  awk '
+    /^---[[:space:]]*$/ { fm++; if (fm>=2) exit; next }
+    fm!=1 { next }
+    /^deliverables:[[:space:]]*(#.*)?$/ { ind=1; next }
+    ind==1 && /^[A-Za-z_][A-Za-z0-9_.-]*:/ { ind=0 }
+    ind==1 { print }
+  ' "$1"
+}
+
+# ── candidate path extraction ────────────────────────────────────────────
+# A candidate is a repo-relative-looking token with a file extension. It must
+# contain a `/` — a bare `one.tql` or `do-walk.sh` names a file the writer did
+# not locate, and resolving it by basename alone across 7k files invites a
+# false positive worse than the miss.
+#
+# Globs (`text/template-*.md`), brace sets and URLs are dropped: a glob is not a
+# path, and a URL is not in the repo.
+candidates() { # stdin = block text
+  grep -oE '[A-Za-z0-9_@.][A-Za-z0-9_@./+-]*\.[A-Za-z0-9]{1,6}' \
+    | grep '/' \
+    | grep -vE '://' \
+    | grep -vE "$SKIP_RE" \
+    | sort -u
+}
+
+# ── resolution ───────────────────────────────────────────────────────────
+# Two shapes appear in real plans, and the gate is worthless unless it handles
+# both — the 2026-07-28 failure had one of each:
+#   (a) repo-relative   packages/sdk/src/fn-allowlist.ts        → direct hit
+#   (b) package-relative tests/unit/fn-entity-args.test.ts      → suffix match
+#                        (that file lives at one.ie/web/tests/unit/…)
+# (b) is resolved against the repo's file universe (tracked + untracked-not-
+# ignored, one `git ls-files` call). An AMBIGUOUS suffix — more than one hit —
+# is NOT skipped: every hit is checked. "Ambiguous → skip" is exactly how this
+# bug walks through the gate a second time.
+resolve() { # $1 = candidate; prints 0+ repo-relative paths
+  local cand="$1"
+  if [ -e "$ROOT/$cand" ]; then printf '%s\n' "$cand"; return 0; fi
+  printf '%s\n' "$INDEX" | awk -v c="$cand" '
+    BEGIN { n=length(c) }
+    $0==c { print; next }
+    length($0) > n && substr($0, length($0)-n) == "/" c { print }
+  '
+}
+
+check() { # $1 = slug
+  local slug="$1"
+  local promise="$ROOT/text/$slug.md" todo="$ROOT/text/$slug-todo.md"
+  local block="" found=0 bad=0 checked=0 unresolved=0 cand path
+
+  git -C "$ROOT" rev-parse --git-dir >/dev/null 2>&1 \
+    || { cannot "$ROOT is not a git repo — trackedness is unanswerable here"; return 3; }
+
+  if [ -f "$promise" ]; then block+=$(deliverables_block "$promise")$'\n'; found=1
+    else say "no promise at text/$slug.md"; fi
+  if [ -f "$todo" ];    then block+=$(deliverables_block "$todo")$'\n';    found=1
+    else say "no todo at text/$slug-todo.md"; fi
+  [ "$found" -eq 1 ] || { cannot "$slug — neither text/$slug.md nor text/$slug-todo.md exists"; return 3; }
+
+  INDEX="$(git -C "$ROOT" ls-files --cached --others --exclude-standard)"
+
+  while IFS= read -r cand; do
+    [ -z "$cand" ] && continue
+    local hits; hits="$(resolve "$cand")"
+    if [ -z "$hits" ]; then
+      unresolved=$((unresolved+1)); say "skip (not on disk): $cand"; continue
+    fi
+    while IFS= read -r path; do
+      [ -z "$path" ] && continue
+      [ -d "$ROOT/$path" ] && { say "skip (directory): $path"; continue; }
+      checked=$((checked+1))
+      if git -C "$ROOT" ls-files --error-unmatch -- "$path" >/dev/null 2>&1; then
+        say "tracked: $path"; continue
+      fi
+      # tracked-first is deliberate: a file that is both tracked and matched by
+      # .gitignore is tracked, and git ships it.
+      if git -C "$ROOT" check-ignore -q -- "$path" 2>/dev/null; then
+        red "GITIGNORED deliverable: $path — exists, matched by .gitignore, CAN NEVER SHIP (named by $slug)"
+      else
+        red "UNTRACKED deliverable: $path — exists on disk, absent from git; \`git add $path\` or it never reaches main"
+      fi
+      bad=$((bad+1))
+    done <<<"$hits"
+  done < <(printf '%s' "$block" | candidates)
+
+  if [ "$bad" -gt 0 ]; then
+    echo "[untracked-gate] $slug — $bad/$checked existing deliverable file(s) not in git" >&2
+    return 1
+  fi
+  echo "[untracked-gate] $slug — ok ($checked existing deliverable file(s) tracked, $unresolved path(s) not on disk / not resolvable)"
+  return 0
+}
+
+# ── self-test ────────────────────────────────────────────────────────────
+# Drives a GREEN fixture and a RED fixture through a real temp git repo. No
+# commit is needed: `git ls-files --error-unmatch` answers from the INDEX, so
+# `git add` alone makes a file tracked and the test needs no user.name/email.
+# The red fixture also exercises the package-relative suffix resolver — the
+# shape that carried half the real 2026-07-28 failure.
+self_test() {
+  local fails=0 rc out
+  dir="$(mktemp -d)"; trap 'rm -rf "$dir"' EXIT
+  git -C "$dir" init -q
+  mkdir -p "$dir/text" "$dir/packages/sdk/src" "$dir/web/tests/unit"
+
+  # A promise + todo naming two deliverables: one repo-relative, one package-relative.
+  printf -- '---\nslug: green\ndeliverables:\n  - item: "the allowlist"\n    accept: "test -f packages/sdk/src/fn-allowlist.ts"\n---\n' \
+    >"$dir/text/green.md"
+  printf -- '---\nslug: green\ndeliverables:\n  - test: "tests/unit/fn-entity-args.test.ts — entity-param binding proven (C7)"\n\nux_before: "x"\n---\n' \
+    >"$dir/text/green-todo.md"
+  sed 's/green/red/' "$dir/text/green.md"      >"$dir/text/red.md"
+  sed 's/green/red/' "$dir/text/green-todo.md" >"$dir/text/red-todo.md"
+
+  : >"$dir/packages/sdk/src/fn-allowlist.ts"
+  : >"$dir/web/tests/unit/fn-entity-args.test.ts"
+  git -C "$dir" add text packages/sdk/src/fn-allowlist.ts >/dev/null 2>&1
+
+  # RED: the package-relative test file exists but was never `git add`ed —
+  # the exact 2026-07-28 shape.
+  ROOT="$dir" VERBOSE=0 check red >/dev/null 2>&1; rc=$?
+  [ "$rc" -eq 1 ] || { echo "FAIL red fixture: expected exit 1, got $rc"; fails=$((fails+1)); }
+  # captured, never piped into `grep -q`: pipefail + grep's early exit SIGPIPEs
+  # the producer and reports 141 for a pipeline that actually matched.
+  out="$(ROOT="$dir" VERBOSE=0 check red 2>&1)"
+  case "$out" in *fn-entity-args.test.ts*) ;; *)
+    echo "FAIL red fixture: reason must name the untracked file"; fails=$((fails+1)) ;; esac
+
+  # GREEN: same fixture once the file is tracked.
+  git -C "$dir" add web/tests/unit/fn-entity-args.test.ts >/dev/null 2>&1
+  ROOT="$dir" VERBOSE=0 check green >/dev/null 2>&1; rc=$?
+  [ "$rc" -eq 0 ] || { echo "FAIL green fixture: expected exit 0, got $rc"; fails=$((fails+1)); }
+
+  # GITIGNORED: a deliverable git can never ship must be loud, not silent.
+  printf 'packages/sdk/src/fn-allowlist.ts\n' >"$dir/.gitignore"
+  git -C "$dir" rm --cached -q packages/sdk/src/fn-allowlist.ts >/dev/null 2>&1
+  out="$(ROOT="$dir" VERBOSE=0 check green 2>&1)"
+  case "$out" in *GITIGNORED*) ;; *)
+    echo "FAIL gitignored fixture: expected a GITIGNORED reason"; fails=$((fails+1)) ;; esac
+
+  # BLOCK BOUNDARY: a `deliverables:   # trailing comment` header with its entries
+  # at COLUMN 0. Both shapes exist in text/ and both used to yield an empty block
+  # — i.e. exit 0 having checked nothing. The fixture must go RED.
+  mkdir -p "$dir/text" "$dir/src"
+  : >"$dir/src/lonely.ts"
+  printf -- '---\nslug: shape\ndeliverables:   # THE SCHEDULE\n- item: "a thing"\n  accept: "test -f src/lonely.ts"\n\nproof: "x"\n---\n' \
+    >"$dir/text/shape.md"
+  ROOT="$dir" VERBOSE=0 check shape >/dev/null 2>&1; rc=$?
+  [ "$rc" -eq 1 ] || { echo "FAIL block-boundary: comment header + column-0 entries must still parse (got $rc)"; fails=$((fails+1)); }
+
+  # CANNOT RUN: no promise and no todo → 3, never 1.
+  ROOT="$dir" check nosuchslug >/dev/null 2>&1; rc=$?
+  [ "$rc" -eq 3 ] || { echo "FAIL missing-slug: expected exit 3, got $rc"; fails=$((fails+1)); }
+
+  echo "[untracked-gate] self-test: 6 assertions, $fails failed"
+  return "$fails"
+}
+
+case "${1:-}" in
+  --self-test) self_test; exit $? ;;
+  ""|-*)       echo "usage: do-untracked-gate.sh <slug> [--verbose] | --self-test" >&2; exit 4 ;;
+esac
+[ "${2:-}" = "--verbose" ] && VERBOSE=1
+check "$1"