@oneie/claude 0.7.0 → 0.8.0

package/scripts/do-next.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# do-next.sh <slug> [--claim] [--all] — stream the next READY cycle(s) of a plan.
+#
+# manifest: portable
+#
+# WHY. do-engine runs a plan as BATCHES: every cycle in a batch must finish before
+# any cycle of the next one starts, so the batch costs its SLOWEST member and a
+# cycle whose own dependencies closed an hour ago still waits at the barrier. The
+# batch is not a real constraint — the DAG is. This emits the cycles whose
+# dependencies are ACTUALLY closed, right now, so a worker can take one, do it,
+# verify it, close it, and immediately ask for the next.
+#
+# Readiness is DERIVED, never read. The todo's `state: ready` / `state: blocked-on-C1,C2`
+# words are written once when the plan is authored and nothing updates them as
+# cycles close — the same second-source-of-truth seam that let a verified cycle
+# stay `- [ ]` forever. The `blocked-on-` list is the edge set (authored, static,
+# correct); whether those edges are SATISFIED is computed from the checkboxes,
+# which are the live record do-tick.sh writes.
+#
+# --claim makes the emission ATOMIC across every session and worktree on this box:
+# claim_take is mkdir(2)-arbitrated, so N workers racing the same plan each get a
+# DIFFERENT cycle and never the same one. A claim evaporates when its owner dies
+# or its lease expires, so a killed worker's cycle returns to the stream by itself
+# — no coordinator, no queue, nothing to deadlock.
+set -euo pipefail
+
+SLUG=""; DO_CLAIM=0; ALL=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --claim) DO_CLAIM=1 ;;
+    --all) ALL=1 ;;
+    -*) echo "do-next: unknown flag $1" >&2; exit 2 ;;
+    *) [ -n "$SLUG" ] && { echo "do-next: one slug only" >&2; exit 2; }; SLUG="$1" ;;
+  esac
+  shift
+done
+[ -n "$SLUG" ] || { echo "usage: do-next.sh <slug> [--claim] [--all]" >&2; exit 2; }
+
+ROOT="${DO_NEXT_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+TODO="$ROOT/text/${SLUG}-todo.md"
+[ -f "$TODO" ] || { echo "do-next: no such plan: $TODO" >&2; exit 3; }
+
+# The cycle-line shape. Identical to do-tick.sh's reader and do-auto.sh's
+# _remaining(); parity across all four implementations is proven behaviourally by
+# do-cycle-shape-check.sh, which reads this file rather than a copy of it.
+OPEN_RE='^[[:space:]]*- \[[ ~]\] \*{0,2}C[0-9]+\*{0,2} —'
+CLOSED_RE='^[[:space:]]*- \[x\] \*{0,2}C[0-9]+\*{0,2} —'
+
+closed_raw=$(grep -oE "$CLOSED_RE" "$TODO" 2>/dev/null || true)
+closed=" $(printf '%s' "$closed_raw" | grep -oE 'C[0-9]+' 2>/dev/null | tr '\n' ' ' || true)"
+open_lines=$(grep -E "$OPEN_RE" "$TODO" 2>/dev/null || true)
+[ -n "$open_lines" ] || { echo "do-next: ${SLUG} — no open cycles; plan complete" >&2; exit 0; }
+
+ready=""
+while IFS= read -r line; do
+  [ -n "$line" ] || continue
+  cid=$(printf '%s' "$line" | grep -oE 'C[0-9]+' | head -1)
+  [ -n "$cid" ] || continue
+  # Edge set: `state: blocked-on-C1,C2`. No blocked-on clause ⇒ no edges ⇒ ready.
+  deps=$(printf '%s' "$line" | sed -nE 's/.*blocked-on-([C0-9,]+).*/\1/p' | tr ',' ' ')
+  blocked=0
+  for d in $deps; do
+    case "$closed" in *" $d "*) ;; *) blocked=1; break ;; esac
+  done
+  [ "$blocked" -eq 0 ] && ready="$ready $cid"
+done <<EOF
+$open_lines
+EOF
+
+ready=$(printf '%s' "$ready" | tr ' ' '\n' | grep -v '^$' || true)
+[ -n "$ready" ] || { echo "do-next: ${SLUG} — cycles remain OPEN but every one is blocked on an unclosed dependency. Nothing to stream." >&2; exit 1; }
+
+if [ "$DO_CLAIM" -eq 0 ]; then
+  [ "$ALL" -eq 1 ] && printf '%s\n' "$ready" || printf '%s\n' "$ready" | head -1
+  exit 0
+fi
+
+# shellcheck source=lib/govern.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib/govern.sh"
+# Claim on behalf of the WORKER, not of this script. do-next.sh exits in
+# milliseconds; if the claim tracked its lifetime it would evaporate immediately
+# and the next racer would be handed the very cycle we just emitted. Default to
+# the caller (PPID) — the shell, agent, or fleet loop that will actually do the
+# work and whose death SHOULD return the cycle to the stream.
+export GOVERN_CLAIM_PID="${DO_NEXT_OWNER_PID:-$PPID}"
+# PPID is only the real worker when do-next is called directly. Called the
+# natural way — `cid=$(do-next.sh <slug> --claim)` — the parent IS the command
+# substitution's subshell, which dies the instant the value is assigned, so the
+# claim would evaporate before the worker ever saw the cycle it was handed.
+# minhold keeps the ground held for a grace window regardless of owner liveness;
+# the worker adopts it by re-claiming under its own pid (claim_take is idempotent
+# for the same owner), and the lease TTL still bounds the whole thing.
+export GOVERN_CLAIM_MIN_HOLD_SECS="${DO_NEXT_MIN_HOLD_SECS:-300}"
+took=""
+for cid in $ready; do
+  if claim_take "do-${SLUG}-${cid}" "${SLUG}/${cid}" >/dev/null 2>&1; then
+    took="$took $cid"
+    [ "$ALL" -eq 1 ] || break
+  fi
+done
+took=$(printf '%s' "$took" | tr ' ' '\n' | grep -v '^$' || true)
+if [ -z "$took" ]; then
+  echo "do-next: ${SLUG} — every ready cycle is already claimed by a live worker. Nothing to take." >&2
+  exit 1
+fi
+printf '%s\n' "$took"

package/scripts/do-orchestrate.sh

@@ -278,11 +278,23 @@ while [ "$i" -lt "$ITERS" ]; do
   fi
 
   # LIVE: build the plan (do-auto worktrees + cycles + W4 + digest)
-  echo "  ▶ building (log: $WT_BASE/$pick/.orchestrate.log)" | tee -a "$RUNLOG"
-  mkdir -p "$WT_BASE/$pick"
-  _link_deps "$WT_BASE/$pick"   # worktree can verify before do-auto even runs
-  if "$AUTO" "$pick" >"$WT_BASE/$pick/.orchestrate.log" 2>&1; then
-    _link_deps "$WT_BASE/$pick"   # re-link in case do-auto recreated the worktree
+  #
+  # The log lives BESIDE the worktrees, never inside one. It used to be
+  # "$WT_BASE/$pick/.orchestrate.log", which forced a `mkdir -p` of the worktree
+  # path before do-auto ran — and that plain directory made do-auto's old
+  # `rev-parse --git-dir` probe report "resuming worktree". `git worktree add`
+  # then never ran, and every cycle commit targeted the MAIN tree's HEAD, where
+  # _safe_stage refuses to stage: orchestrated cycles committed NOTHING, with no
+  # error. do-auto now discriminates properly (see _is_worktree there); this side
+  # removes the trigger, so neither half depends on the other being correct.
+  #
+  # Keeping it outside also means the log survives `git worktree remove`, which
+  # is when you most want to read it.
+  log="$WT_BASE/.logs/$pick.log"   # not `local` — this loop is top-level, not a function
+  mkdir -p "$WT_BASE/.logs"
+  echo "  ▶ building (log: $log)" | tee -a "$RUNLOG"
+  if "$AUTO" "$pick" >"$log" 2>&1; then
+    _link_deps "$WT_BASE/$pick"   # do-auto cut the worktree; ensure deps are linked
     if _reflect "$pick" | tee -a "$RUNLOG"; then
       echo "  ✅ $pick — VERIFIED, merge-ready on branch do/$pick" | tee -a "$RUNLOG"
       BUILT+=("$pick")

package/scripts/do-plan-json.mjs

@@ -0,0 +1,162 @@
+// do-plan-json.mjs — parse a /do plan into JSON, deterministically. No LLM.
+//
+// WHY (2026-08-31): do-engine.js runs with no filesystem access, so it asked an
+// LLM agent for "the raw, verbatim content of text/<slug>-todo.md". An LLM will
+// not return a 30KB file verbatim — it returned 6.8KB ending "(Full todo text
+// continues...)". The guard reading open cycles out of that text saw NONE, and
+// four launches burned ~3M subagent tokens building nothing.
+//
+// The plan is a deterministic fact on disk. Reading it through a probabilistic
+// channel is the defect. This is the deterministic channel; the agent's only job
+// becomes "run this, paste stdout". Same discipline as do-auto.sh's _remaining(),
+// which is grep and has never had this failure.
+//
+// Exits non-zero and emits NOTHING when the plan is unreadable — a partial plan
+// must never read as a runnable one.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+const slug = process.argv[2]
+if (!slug) { console.error('usage: do-plan-json.mjs <slug>'); process.exit(2) }
+
+const repo = path.resolve(new URL('../..', import.meta.url).pathname)
+
+// READ THE TODO THE ENGINE WRITES.
+//
+// do-tick.sh runs inside the plan WORKTREE, so a closed cycle is ticked in
+// .do-worktrees/<slug>/text/<slug>-todo.md. This parser read main's copy, where
+// those cycles are still `- [ ]` until the branch merges. So a relaunch computed
+// openCycles from main and rebuilt work the worktree had already proven --
+// measured 2026-09-01: a relaunch of `lifecycle` re-ran C0, C2 and C3 (all three
+// closed and committed on do/lifecycle) before it could reach the C1/C5 it was
+// launched for.
+//
+// Same read/write divergence that stalled the engine this morning, one level up:
+// the tick and the reader were looking at two different files. The worktree copy
+// is the live record while a plan is in flight; main's is the record after merge.
+// Prefer the worktree when it exists, and SAY which one was read so a surprising
+// openCycles is one line of output away from being explained.
+const wtTodo = path.join(repo, '.do-worktrees', slug, 'text', `${slug}-todo.md`)
+const mainTodo = path.join(repo, 'text', `${slug}-todo.md`)
+const todo = (process.env.DO_PLAN_TODO) || (fs.existsSync(wtTodo) ? wtTodo : mainTodo)
+if (!fs.existsSync(todo)) { console.error(`do-plan-json: no such plan: text/${slug}-todo.md`); process.exit(3) }
+
+const t = fs.readFileSync(todo, 'utf8')
+const fail = (m) => { console.error(`do-plan-json: ${m}`); process.exit(4) }
+
+const fm = t.match(/^---\n([\s\S]*?)\n---/)
+if (!fm) fail('no frontmatter')
+const F = fm[1]
+
+// batches: `- [C0, C2]` lines under `batches:`
+const bm = F.match(/^batches:\n((?:[ \t]+- \[.*\]\n?)+)/m)
+const batches = bm
+  ? bm[1].trim().split('\n').map((l) =>
+      l.replace(/^[\s-]*\[|\]\s*$/g, '').split(',').map((s) => s.trim()).filter(Boolean))
+  : []
+
+// outcome: the kill-switch. A YAML double-quoted scalar carries \" and \\ escapes;
+// stripping the outer quotes WITHOUT unescaping leaves a stray backslash that
+// JSON.stringify then doubles, emitting invalid JSON (measured: lifecycle-money,
+// lifecycle-human, both of whose outcomes contain a quoted grep pattern).
+function unquote(raw) {
+  if (raw.length > 1 && raw.startsWith('"') && raw.endsWith('"')) {
+    return raw.slice(1, -1).replace(/\\(["\\])/g, '$1')
+  }
+  if (raw.length > 1 && raw.startsWith("'") && raw.endsWith("'")) {
+    return raw.slice(1, -1).replace(/''/g, "'")
+  }
+  return raw
+}
+let outcome = ''
+const om = F.match(/^outcome:[ \t]*(?:\|[-+]?|>[-+]?)?[ \t]*(.*)$/m)
+if (om) {
+  if (om[1].trim()) outcome = unquote(om[1].trim())
+  else {
+    const rest = F.slice(F.indexOf(om[0]) + om[0].length)
+    const blk = rest.match(/^\n((?:[ \t]+.*\n?)+)/)
+    if (blk) outcome = blk[1].split('\n').map((l) => l.trim()).filter(Boolean).join(' ')
+  }
+}
+
+// The Status kanban — the same fact do-auto.sh's _remaining() greps.
+const openCycles = []
+for (const m of t.matchAll(/^[ \t]*- \[[ ~]\] \*{0,2}(C\d+)\*{0,2} —/gm)) {
+  if (!openCycles.includes(m[1])) openCycles.push(m[1])
+}
+
+// closed + deps — the REAL DAG, so a scheduler can stream instead of marching.
+// `batches:` is the author's flattening of this graph into rounds, and a round
+// costs its slowest member: a cycle whose own dependencies closed an hour ago
+// still waits at the barrier for an unrelated sibling. The edges themselves live
+// in the kanban's `state: blocked-on-C1,C2` clause. Emitting them lets the engine
+// start a cycle the moment ITS dependencies pass. Same source do-next.sh reads.
+const closedCycles = []
+for (const m of t.matchAll(/^[ \t]*- \[x\] \*{0,2}(C\d+)\*{0,2} —/gm)) {
+  if (!closedCycles.includes(m[1])) closedCycles.push(m[1])
+}
+const deps = {}
+for (const m of t.matchAll(/^[ \t]*- \[[x ~]\] \*{0,2}(C\d+)\*{0,2} —(.*)$/gm)) {
+  const d = m[2].match(/blocked-on-([C0-9,]+)/)
+  deps[m[1]] = d ? d[1].split(',').map((x) => x.trim()).filter(Boolean) : []
+}
+
+// Cycle headers: "## C3 — title  ⚡/★ marker"
+const cycles = {}
+const heads = [...t.matchAll(/^##[ \t]+(C\d+)[ \t]+—[ \t]+(.+)$/gm)]
+heads.forEach((m, i) => {
+  const body = t.slice(m.index, i + 1 < heads.length ? heads[i + 1].index : t.length)
+  // Repo-relative paths named anywhere in the cycle body — W1's recon list.
+  // ALWAYS repo-relative: an absolute path double-prefixes ${WT} downstream, and
+  // an LLM asked for "the file list" returns absolute paths about half the time.
+  const files = [...new Set(
+    [...body.matchAll(/(?<![\w/.-])((?:one\.ie|packages|channels|api|schema|pay|sync|backup|text|\.claude)\/[A-Za-z0-9._\/\[\]-]+\.[a-z]{2,5})/g)]
+      .map((f) => f[1].replace(/[.,)`]+$/, '')),
+  )]
+    // A path is only a recon hint if it EXISTS. Plan prose abbreviates
+    // ("api/events.ts" for one.ie/web/src/pages/api/events.ts), and a hint that
+    // resolves to nothing sends W1 hunting for a file that was never there.
+    // Existence-filtering makes the list self-validating instead of plausible.
+    .filter((f) => fs.existsSync(path.join(repo, f)))
+    .slice(0, 12)
+  cycles[m[1]] = {
+    title: m[2].replace(/\s*[⚡★].*$/, '').trim(),
+    // schema tier: touches persistent/irreversible shape (same patterns as do-tier.sh)
+    schema: /\.tql\b|migrations\/\d|\.sql\b|\.move\b|\.sol\b/.test(body),
+    fableMandatory: /\[Fable\s*—\s*mandatory\]/i.test(body),
+    files,
+  }
+})
+
+// Invariants — refuse to emit a plan that cannot be run.
+if (!batches.length) fail('frontmatter has no `batches:` — nothing to schedule')
+if (!openCycles.length) {
+  fail('no open cycles in the Status kanban. Lines must match /^[ \\t]*- \\[[ ~]\\] C<n> — /; ' +
+       'a "Batch N  - [ ] C0 — ..." prefix breaks the ^ anchor and hides the cycle')
+}
+const orphan = batches.flat().filter((c) => !cycles[c])
+if (orphan.length) fail(`batches name cycles with no "## Cn —" header: ${orphan.join(', ')}`)
+if (!outcome) fail('frontmatter has no `outcome:` kill-switch')
+
+// shared_recon: the author's own explicit file list, existence-checked the same way.
+const srm = F.match(/^shared_recon:\n((?:[ \t]+- .*\n?)+)/m)
+const sharedRecon = srm
+  ? srm[1].trim().split('\n').map((l) => l.replace(/^[\s-]+/, '').trim())
+      .filter((f) => f && fs.existsSync(path.join(repo, f)))
+  : []
+
+process.stdout.write(JSON.stringify({
+  slug,
+  sharedRecon,
+  todo: path.relative(repo, todo),
+  todoSource: todo === mainTodo ? 'main' : 'worktree',
+  worktree: path.join(repo, '.do-worktrees', slug),
+  outcome,
+  batches,
+  openCycles,
+  closedCycles,
+  deps,
+  cycles,
+  sha256: crypto.createHash('sha256').update(t).digest('hex').slice(0, 16),
+}, null, 2) + '\n')

package/scripts/do-plan-json.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# do-plan-json.sh <slug> — thin wrapper over do-plan-json.mjs (the parser).
+# manifest: portable
+# Kept as a .sh so callers match every other script in this dir; the parser is a
+# real .mjs file rather than a quoted heredoc, because embedding it inline is how
+# a stray backslash silently became invalid JSON.
+set -euo pipefail
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/do-plan-json.mjs" "$@"

package/scripts/do-preflight.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# do-preflight.sh <slug> [--fix] — refuse to launch a plan into a broken environment.
+#
+# manifest: needs-env
+#
+# WHY. Every expensive failure on 2026-08-31 was an ENVIRONMENT fault discovered
+# only AFTER the run had spent itself:
+#
+#   - an unreachable model made W2 return nothing; W3 edited nothing, W4 verified
+#     an empty diff, and the plan reported "batch total loss". 41 agents and 3.7M
+#     tokens to learn that a model name was wrong.
+#   - `.env` was not linked into the worktree, so real-TypeDB tests failed with
+#     no_gateway_key and two verifiers hand-classified 4-7 red files as
+#     "environmental" before they could score their gate.
+#   - four abandoned gates held the box at load 138 and one held a governor slot,
+#     so live cycles starved and verifiers began SKIPPING their gates and passing
+#     cycles anyway.
+#   - a cycle line the writers could tick was invisible to the engine's reader.
+#
+# Not one of those is a code defect, and every one is checkable in seconds. This
+# is the cheap deterministic gate that runs first, so a run is never spent
+# discovering something a grep could have said.
+#
+# Exit 0 = safe to launch. Exit 1 = a blocker (do not launch). Exit 2 = usage.
+set -uo pipefail
+
+SLUG="${1:-}"; shift 2>/dev/null || true
+FIX=0
+for f in "$@"; do case "$f" in --fix) FIX=1 ;; esac; done
+[ -n "$SLUG" ] || { echo "usage: do-preflight.sh <slug> [--fix]" >&2; exit 2; }
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+WT="$ROOT/.do-worktrees/$SLUG"
+bad=0; warn=0
+ok()   { printf '  ok    %s\n' "$1"; }
+fail() { printf '  FAIL  %s\n' "$1"; bad=$((bad+1)); }
+note() { printf '  warn  %s\n' "$1"; warn=$((warn+1)); }
+
+echo "do-preflight: $SLUG"
+
+# 1. The plan must PARSE. do-plan-json refuses (non-zero, no stdout) on a plan
+#    missing worktree/outcome/batches/cycles, which is the failure that used to
+#    surface as an LLM summarising a 30KB file down to 6.8KB.
+if plan=$(node "$ROOT/.claude/scripts/do-plan-json.mjs" "$SLUG" 2>&1); then
+  ok "plan parses ($(printf '%s' "$plan" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(len(d["cycles"]), "cycles,", len(d["batches"]), "batches")' 2>/dev/null || echo 'ok'))"
+else
+  fail "plan does not parse: $(printf '%s' "$plan" | head -1)"
+fi
+
+# 2. Worktree + the gitignored deps a worktree cannot inherit. A missing .env is
+#    not a slow test -- it makes a verifier argue with its own gate and teaches
+#    whoever reads the report that red is normal.
+if [ -d "$WT" ]; then
+  ok "worktree present"
+  for dep in .env node_modules; do
+    for where in "one.ie/web/$dep" "$dep"; do
+      [ -e "$ROOT/$where" ] || continue
+      if [ -e "$WT/$where" ]; then ok "linked: $where"; else
+        if [ "$FIX" = "1" ]; then
+          mkdir -p "$(dirname "$WT/$where")" && ln -s "$ROOT/$where" "$WT/$where" 2>/dev/null \
+            && ok "linked: $where (repaired)" || fail "could not link $where"
+        else
+          fail "MISSING in worktree: $where — real-infra tests will fail as 'environmental'. Re-run with --fix"
+        fi
+      fi
+      break
+    done
+  done
+else
+  note "no worktree yet at .do-worktrees/$SLUG (do-auto --setup-only will cut one)"
+fi
+
+# 3. The cycle-line shape must agree across its four implementations, or the
+#    engine reads a different set of open cycles than the writers can tick.
+if bash "$ROOT/.claude/scripts/do-cycle-shape-check.sh" >/dev/null 2>&1; then
+  ok "cycle-line shape parity (reader == writer)"
+else
+  fail "cycle-shape parity RED — run .claude/scripts/do-cycle-shape-check.sh"
+fi
+
+# 4. A workflow with a syntax error does not fail loudly; it never launches.
+if node "$ROOT/.claude/scripts/wf-check.mjs" >/dev/null 2>&1; then
+  ok "workflow scripts parse + seam checks"
+else
+  fail "wf-check RED — run node .claude/scripts/wf-check.mjs"
+fi
+
+# 5. The box. A saturated box is why verifiers started skipping gates and
+#    reporting passes anyway, so this is an ACCURACY check, not only a speed one.
+orph=$(bash "$ROOT/.claude/scripts/gate-reaper.sh" --once --dry-run 2>/dev/null | grep -c 'WOULD reap' || true)
+if [ "${orph:-0}" -gt 0 ]; then
+  if [ "$FIX" = "1" ]; then
+    bash "$ROOT/.claude/scripts/gate-reaper.sh" --once >/dev/null 2>&1
+    ok "reaped ${orph} abandoned gate(s)"
+  else
+    fail "${orph} abandoned gate(s) burning the box — re-run with --fix, or gate-reaper.sh --once"
+  fi
+else
+  ok "no abandoned gates"
+fi
+
+head=$(bash -c ". '$ROOT/.claude/scripts/lib/govern.sh'; gate_headroom" 2>/dev/null || echo 99)
+loadi=$(uptime | sed -E 's/.*load averages?: ([0-9.]+).*/\1/' | cut -d. -f1)
+cores=$(sysctl -n hw.ncpu 2>/dev/null || echo 8)
+if [ "${loadi:-0}" -gt $(( cores * 3 )) ]; then
+  note "load ${loadi} on ${cores} cores — gates will run slow; the governor will queue them"
+else
+  ok "load ${loadi} on ${cores} cores, memory funds ${head} concurrent cycle(s)"
+fi
+
+echo
+if [ "$bad" -gt 0 ]; then
+  echo "do-preflight: $bad blocker(s) — DO NOT LAUNCH. Every one of these is cheaper to fix now than to discover mid-run."
+  exit 1
+fi
+echo "do-preflight: clear${warn:+ ($warn warning(s))} — safe to launch $SLUG"
+exit 0

package/scripts/do-project.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# do-project.sh — project a promise's deliverables: into an idempotent subtask spec.
+# Parent = the promise (born with tags slug:<slug> — resolveTaskBySlug cannot retrofit).
+# One child per deliverable; notes first line is accept: <that accept:> verbatim.
+# Emits JSON. Does not POST. Re-projecting with --existing <prior.json> yields new_rows=0.
+# Usage:  do-project.sh <slug> [--existing prior.json]   |   do-project.sh --self-test
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+
+# Lifted from do-promise-lint.sh — do not fork a second YAML parser.
+unquote() {
+  local line="$1"
+  case "$line" in
+    \"*) printf '%s' "$line" | sed -E 's/^"(.*)"[[:space:]]*(#.*)?$/\1/' | sed 's/\\"/"/g' ;;
+    \'*) printf '%s' "$line" | sed -E "s/^'(.*)'[[:space:]]*(#.*)?\$/\1/" | sed "s/''/'/g" ;;
+    *)   printf '%s' "$line" | sed -E 's/[[:space:]]+#.*$//' ;;
+  esac
+}
+fm() { awk '/^---[[:space:]]*$/{c++;next} c==1{print} c>=2{exit}' "$1"; }
+extract_proof() {
+  local line
+  line="$(fm "$1" | awk '/^proof:/{print;exit}')"
+  [ -z "$line" ] && return 1
+  line="${line#proof:}"
+  unquote "$(printf '%s' "$line" | sed -E 's/^[[:space:]]+//')"
+}
+deliverables_block() {
+  fm "$1" | awk '/^deliverables:/{on=1;next} on && /^[a-zA-Z_-]+:/{exit} on{print}'
+}
+
+if [ "${1:-}" = "--self-test" ]; then
+  S="$(cd "$(dirname "$0")" && pwd)"; f=0
+  dir="$(mktemp -d)"; trap 'rm -rf "$dir"' EXIT
+  cat >"$dir/proj.md" <<'F'
+---
+title: Project fixture
+slug: proj
+deliverables:
+  - item: "alpha row"
+    accept: "test -f a"
+  - item: "beta row"
+    accept: "test -f b"
+proof: "test -f a && test -f b"
+---
+F
+  cat >"$dir/gap.md" <<'F'
+---
+title: Gap
+slug: gap
+deliverables:
+  - item: "alpha row"
+proof: "true"
+---
+F
+  out1="$(PROMISE_FILE="$dir/proj.md" "$S/do-project.sh" proj)" || { echo "  FAIL first project exited $?"; exit 1; }
+  echo "$out1" >"$dir/once.json"
+  case "$out1" in *"\"slug:proj\""*) printf '  ok   parent carries slug:proj\n' ;;
+                 *) printf '  FAIL parent missing slug:proj: %s\n' "$out1"; f=1 ;; esac
+  case "$out1" in *"accept: test -f a"*) printf '  ok   child carries accept: verbatim\n' ;;
+                 *) printf '  FAIL child missing accept: %s\n' "$out1"; f=1 ;; esac
+  case "$out1" in *"\"new_rows\":3"*) printf '  ok   first project inserts 3 rows\n' ;;
+                 *) printf '  FAIL first new_rows: %s\n' "$out1"; f=1 ;; esac
+  out2="$(PROMISE_FILE="$dir/proj.md" "$S/do-project.sh" proj --existing "$dir/once.json")" || { echo "  FAIL second project exited $?"; f=1; out2=""; }
+  case "$out2" in *"\"new_rows\":0"*) printf '  ok   second project new_rows=0\n' ;;
+                 *) printf '  FAIL second diff not empty: %s\n' "$out2"; f=1 ;; esac
+  set +e
+  PROMISE_FILE="$dir/gap.md" "$S/do-project.sh" gap >/dev/null 2>&1; rc=$?
+  set -e
+  [ "$rc" -ne 0 ] && printf '  ok   missing accept: refused (exit %s)\n' "$rc" \
+    || { printf '  FAIL missing accept: should refuse\n'; f=1; }
+  [ "$f" -eq 0 ] && echo "do-project: self-test green" || echo "do-project: self-test FAILED"
+  exit "$f"
+fi
+
+slug="${1:-}"
+[ -z "$slug" ] && { echo "usage: do-project.sh <slug> [--existing prior.json] | --self-test" >&2; exit 4; }
+shift
+existing=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --existing) existing="${2:-}"; shift 2 ;;
+    *) echo "unknown flag $1" >&2; exit 4 ;;
+  esac
+done
+
+file="${PROMISE_FILE:-$ROOT/text/$slug.md}"
+[ -f "$file" ] || { echo "do-project: no promise at ${file#"$ROOT"/}" >&2; exit 3; }
+
+block="$(deliverables_block "$file")"
+[ -z "$block" ] && { echo "do-project: no deliverables: in ${file#"$ROOT"/}" >&2; exit 1; }
+
+items=""; accepts=""
+while IFS= read -r raw; do
+  [ -z "$raw" ] && continue
+  val="$(unquote "$(printf '%s' "$raw" | sed -E 's/^[[:space:]]*-[[:space:]]*item:[[:space:]]*//')")"
+  items="${items}${val}
+"
+done <<EOF
+$(printf '%s\n' "$block" | grep '^[[:space:]]*-[[:space:]]*item:' || true)
+EOF
+while IFS= read -r raw; do
+  [ -z "$raw" ] && continue
+  val="$(unquote "$(printf '%s' "$raw" | sed -E 's/^[[:space:]]*accept:[[:space:]]*//')")"
+  accepts="${accepts}${val}
+"
+done <<EOF
+$(printf '%s\n' "$block" | grep '^[[:space:]]*accept:' || true)
+EOF
+
+n_items="$(printf '%s' "$items" | grep -c . || true)"
+n_acc="$(printf '%s' "$accepts" | grep -c . || true)"
+if [ "$n_items" -lt 1 ] || [ "$n_items" -ne "$n_acc" ]; then
+  echo "do-project: refuse — $n_items item(s) but $n_acc accept(s); every deliverable needs accept:" >&2
+  exit 1
+fi
+
+title="$(fm "$file" | awk '/^title:/{sub(/^title:[[:space:]]*/,"");print;exit}')"
+title="$(unquote "$title")"
+[ -z "$title" ] && title="$slug"
+proof="$(extract_proof "$file" || true)"
+
+pairf="$(mktemp)"
+paste -d $'\t' <(printf '%s' "$items" | grep -v '^$') <(printf '%s' "$accepts" | grep -v '^$') >"$pairf"
+python3 - "$slug" "$title" "$proof" "$existing" "$pairf" <<'PY'
+import json, sys
+slug, title, proof, existing_path, pairf = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4], sys.argv[5]
+pairs = [ln.rstrip("\n").split("\t", 1) for ln in open(pairf) if ln.strip()]
+if not proof:
+    proof = " && ".join(p[1] for p in pairs)
+prior = {"parent": None, "children": []}
+if existing_path:
+    prior = json.load(open(existing_path))
+prior_tags = (prior.get("parent") or {}).get("tags") or []
+parent_exists = ("slug:%s" % slug) in prior_tags
+prior_titles = {c.get("title") for c in (prior.get("children") or []) if c.get("title")}
+parent = {
+    "title": title,
+    "tags": ["slug:%s" % slug],
+    "notes": "accept: %s" % proof,
+    "insert": not parent_exists,
+    "create": "tasks:create",
+}
+children, new_rows = [], 1 if parent["insert"] else 0
+for item, accept in pairs:
+    ins = item not in prior_titles
+    children.append({
+        "title": item,
+        "notes": "accept: %s" % accept,
+        "insert": ins,
+        "steps": ["tasks:subtask", "tasks:notes"],
+    })
+    if ins:
+        new_rows += 1
+print(json.dumps({"parent": parent, "children": children, "new_rows": new_rows}, separators=(",", ":")))
+PY
+rm -f "$pairf"