nightralph 0.0.0

package/eslint.config.js

@@ -0,0 +1,142 @@
+import neostandard from 'newneostandard'
+import tseslint from 'typescript-eslint'
+
+// Local rule: forbid spaces around `|` and `&` in TypeScript union and
+// intersection types, so `A|B` is required over `A | B`. Only flags
+// operators whose operands share a line, leaving multiline unions (one
+// member per line) untouched.
+const localPlugin = {
+    rules: {
+        'union-spacing': {
+            meta: {
+                type: 'layout',
+                fixable: 'whitespace',
+                schema: [],
+                messages: {
+                    before: "Unexpected space before '{{op}}' in type.",
+                    after: "Unexpected space after '{{op}}' in type."
+                }
+            },
+            create (context) {
+                const sc = context.sourceCode
+                const check = (node) => {
+                    for (const member of node.types) {
+                        const op = sc.getTokenBefore(member)
+                        if (!op) continue
+                        if (op.value !== '|' && op.value !== '&') continue
+                        const prev = sc.getTokenBefore(op)
+                        const next = sc.getTokenAfter(op)
+                        // Only enforce when the operator sits inline
+                        // between two members on a single line; leave
+                        // multiline unions (leading/trailing pipe) be.
+                        const inline = prev && next &&
+                            prev.loc.end.line === op.loc.start.line &&
+                            op.loc.end.line === next.loc.start.line
+                        if (!inline) continue
+                        if (prev.range[1] !== op.range[0]) {
+                            context.report({
+                                node: op,
+                                messageId: 'before',
+                                data: { op: op.value },
+                                fix: (fixer) => fixer.removeRange(
+                                    [prev.range[1], op.range[0]]
+                                )
+                            })
+                        }
+                        if (op.range[1] !== next.range[0]) {
+                            context.report({
+                                node: op,
+                                messageId: 'after',
+                                data: { op: op.value },
+                                fix: (fixer) => fixer.removeRange(
+                                    [op.range[1], next.range[0]]
+                                )
+                            })
+                        }
+                    }
+                }
+                return {
+                    TSUnionType: check,
+                    TSIntersectionType: check
+                }
+            }
+        }
+    }
+}
+
+export default tseslint.config(
+    {
+        ignores: [
+            'lib.es5.d.ts',
+            'dist/**',
+            'public/**',
+            'test/*.js'
+        ]
+    },
+
+    // JavaScript Standard Style, TypeScript-aware (flat-config successor
+    // to `eslint-config-standard`). Stylistic rules live under the
+    // `@stylistic/` namespace.
+    ...neostandard({ ts: true }),
+
+    // Standard Style overrides, applied to every file.
+    {
+        rules: {
+            '@stylistic/operator-linebreak': 'off',
+            '@stylistic/multiline-ternary': 'off',
+            '@stylistic/no-multiple-empty-lines': ['error', {
+                max: 1,
+                maxEOF: 1
+            }],
+            '@stylistic/indent': ['error', 4, {
+                SwitchCase: 1,
+                ignoredNodes: ['TemplateLiteral *']
+            }],
+            '@stylistic/comma-dangle': 'off',
+            '@stylistic/no-multi-spaces': ['error', {
+                ignoreEOLComments: true
+            }]
+        }
+    },
+
+    // `@typescript-eslint/recommended` plus our TypeScript overrides,
+    // scoped to TypeScript files where the parser and plugin are active.
+    {
+        files: ['**/*.ts', '**/*.tsx'],
+        extends: [tseslint.configs.recommended],
+        plugins: { local: localPlugin },
+        rules: {
+            '@typescript-eslint/no-explicit-any': 'off',
+            '@typescript-eslint/no-unused-vars': ['error', {
+                argsIgnorePattern: '^_',
+                varsIgnorePattern: '^_',
+                caughtErrorsIgnorePattern: '^_'
+            }],
+            '@typescript-eslint/consistent-type-imports': ['error', {
+                prefer: 'type-imports'
+            }],
+            // No space around the colon in type annotations
+            // (`const x:T`, params, returns). Keep `=>` in function
+            // types spaced via the arrow override.
+            '@stylistic/type-annotation-spacing': ['error', {
+                before: false,
+                after: false,
+                overrides: { arrow: 'ignore' }
+            }],
+            '@stylistic/arrow-spacing': ['error', {
+                before: true,
+                after: true
+            }],
+            // No space around the colon in object and type-literal
+            // members (`{ a:1 }`, `classes?:string[]`).
+            '@stylistic/key-spacing': ['error', {
+                beforeColon: false,
+                afterColon: false,
+                mode: 'strict'
+            }],
+            // Let `local/union-spacing` own union/intersection spacing.
+            '@stylistic/space-infix-ops': ['error', { ignoreTypes: true }],
+            'local/union-spacing': 'error'
+        }
+    }
+)

package/lib.es5.d.ts

@@ -0,0 +1,19 @@
+/** See https://stackoverflow.com/a/51390763/1470607  */
+type Falsy = false | 0 | '' | null | undefined;
+
+/**
+ * see https://www.karltarvas.com/typescript-array-filter-boolean.html
+ */
+interface Array<T> {
+  /**
+   * Returns the elements of an array that meet the condition specified in a
+   * callback function.
+   * @param predicate A function that accepts up to three arguments. The filter
+   * method calls the predicate function one time for each element in the array.
+   * @param thisArg An object to which the this keyword can refer in the
+   * predicate function. If thisArg is omitted, undefined is used as the
+   * this value.
+   */
+  filter<S extends T>(predicate: BooleanConstructor, thisArg?: any)
+    : Exclude<S, Falsy>[];
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "nightralph",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Small orchestrator that runs a single-agent session per issue.",
+  "bin": {
+    "nightralph": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "lint": "eslint \"./**/*.{ts,js}\"",
+    "start": "npm run build && node dist/index.js",
+    "build": "mkdir -p ./dist && rm -rf ./dist/* && npm run build-esm && npm run copy",
+    "build-esm": "esbuild src/index.ts src/orchestrator.ts src/setup.ts src/resolve.ts --format=esm --metafile=dist/meta.json --keep-names --tsconfig=tsconfig.build.json --outdir=./dist --sourcemap && tsc --emitDeclarationOnly --project tsconfig.build.json",
+    "copy": "mkdir -p ./dist/skills ./dist/docs-templates && cp -r ./src/skills/* ./dist/skills && cp -r ./src/docs-templates/* ./dist/docs-templates",
+    "clone-skills": "bash scripts/clone-skills.sh",
+    "toc": "markdown-toc --maxdepth 3 -i README.md",
+    "test": "esbuild test/setup.test.ts test/orchestrator.test.ts test/integration.test.ts --format=esm --bundle --packages=external --outdir=dist/test --sourcemap && node dist/test/setup.test.js && node dist/test/orchestrator.test.js && node dist/test/integration.test.js"
+  },
+  "devDependencies": {
+    "@substrate-system/tapzero": "^0.10.16",
+    "@types/node": "^26.3.0",
+    "esbuild": "^0.28.2",
+    "eslint": "^10.9.1",
+    "markdown-toc": "^1.2.0",
+    "newneostandard": "^0.14.3",
+    "typescript-eslint": "^8.68.0"
+  },
+  "author": "nichoth",
+  "dependencies": {
+    "@inquirer/prompts": "^8.7.0",
+    "yargs": "^18.1.0"
+  }
+}

package/progress.log

@@ -0,0 +1,190 @@
+## 2026-08-27 - US-001: Unit tests for findFeatureDirs
+
+Completed. Created test/integration.test.ts with 4 test cases (8 assertions):
+- Returns empty array when .scratch/ does not exist
+- Returns empty array when dirs lack issues/ subdirs
+- Returns correct name, dir, spec for valid feature dirs
+- Ignores non-directory entries in .scratch/
+
+Refactoring note: extracted findFeatureDirs and resolveIssuesDir from
+src/index.ts into src/resolve.ts. The top-level yargs(...).parse() call in
+index.ts runs on import, which crashes test processes. Moving the pure
+functions to resolve.ts lets tests import them without triggering CLI
+parsing. index.ts re-exports both functions so the public API is unchanged.
+
+Updated package.json:
+- build-esm: added src/resolve.ts to esbuild entry points
+- test: added integration.test.ts to build and run steps
+
+All 128 tests pass (setup: 66, orchestrator: 54, integration: 8).
+Lint clean.
+
+## 2026-08-27 - US-002: Unit tests for resolveIssuesDir with explicit flags
+
+Completed. Added 2 test cases (4 assertions) to test/integration.test.ts:
+- Returns { dir, spec } exactly as given when both flags are provided
+- No filesystem scanning occurs (temp dir has no .scratch/)
+
+Both tests confirm that resolveIssuesDir short-circuits when both --dir
+and --spec are supplied, returning them directly without touching the
+filesystem. The temp directory intentionally has no .scratch/ to prove
+no scanning happens.
+
+All 132 tests pass (setup: 66, orchestrator: 54, integration: 12).
+Lint clean.
+
+## 2026-08-28 - US-003: Subprocess CLI smoke test for execute
+
+Completed. Added 1 subprocess test (5 assertions) to
+test/integration.test.ts:
+- Spawns `node dist/index.js` with mock-agent-pass.js as provider
+- Creates temp dir with 2 ticket files (second blocked by first)
+  and a spec.md
+- Passes --dir, --spec, --timeout-secs 10 to the built CLI
+- Asserts exit code 0
+- Asserts both ticket files updated to **Status:** done on disk
+- Asserts log files created for both tickets
+
+Added helper functions: spawnCli (wraps execFile in a promise),
+makeTicketBody (generates ticket markdown with status and blockers).
+Also added readFileSync, existsSync, execFile imports to the test file.
+
+All 137 tests pass (setup: 66, orchestrator: 54, integration: 17).
+Lint clean.
+
+## 2026-08-28 - US-004: Create mock-agent-echo-args and test --model flag
+
+Completed. Created test/mock-agent-echo-args.js and added 1 test case
+(4 assertions) to test/integration.test.ts:
+- mock-agent-echo-args.js writes JSON.stringify(process.argv) to stdout,
+  then reads stdin to completion and exits 0
+- Test spawns CLI with -m test-model using the echo mock agent
+- Asserts exit code 0
+- Asserts log file created
+- Asserts log contains --model flag and test-model value
+
+Gotcha: new mock agent files need chmod +x to be spawnable by the
+orchestrator (spawn uses the shebang, not node directly).
+
+All 141 tests pass (setup: 66, orchestrator: 54, integration: 21).
+Lint clean.
+
+## 2026-08-28 - US-005: Subprocess CLI test for --dry-run
+
+Completed. Added 1 subprocess test (6 assertions) to
+test/integration.test.ts:
+- Spawns `node dist/index.js` with --dry-run, --dir, --spec flags
+- Creates temp dir with 2 ticket files (second blocked by first)
+  and a spec.md
+- Asserts exit code 0
+- Asserts stdout contains Wave 1 with 01-alpha.md
+- Asserts stdout contains Wave 2 with 02-beta.md
+- Asserts stdout contains AGENT INSTRUCTIONS (prompt preview)
+- Asserts both ticket files are NOT modified (still ready-for-agent)
+
+All 147 tests pass (setup: 66, orchestrator: 54, integration: 27).
+Lint clean.
+
+## 2026-08-28 - US-006: CLI exits gracefully when no tickets found
+
+Completed. Added 1 subprocess test (2 assertions) to
+test/integration.test.ts:
+- Spawns `node dist/index.js` with --dir pointing at an empty
+  issues directory and a valid --spec
+- Asserts exit code 0 (graceful, not a crash)
+- Asserts stdout contains "No ticket files found"
+
+The implementation already existed in src/index.ts (lines 148-150):
+scanTickets returns an empty array for an empty directory, and
+runExecute prints "No ticket files found. Exiting." then returns
+normally (exit code 0). This test validates that behavior end-to-end
+through the subprocess CLI.
+
+All 149 tests pass (setup: 66, orchestrator: 54, integration: 29).
+Lint clean.
+
+## 2026-08-28 - US-007: CLI exits with error for missing dir/spec
+
+Completed. Added 2 subprocess tests (4 assertions) to
+test/integration.test.ts:
+- Test 1: passes --dir /nonexistent/path with a valid --spec file,
+  asserts non-zero exit code and stderr contains "not found"
+- Test 2: passes valid --dir with --spec /nonexistent/spec.md,
+  asserts non-zero exit code and stderr contains "not found"
+
+The validation logic already existed in src/index.ts (lines 136-143):
+runExecute checks existsSync(dir) and existsSync(spec), prints
+"Directory not found: ..." or "Spec file not found: ..." to stderr,
+and calls process.exit(2). These tests validate that behavior
+end-to-end through the subprocess CLI.
+
+All 153 tests pass (setup: 66, orchestrator: 54, integration: 33).
+Lint clean.
+
+## 2026-08-28 - US-008: Unknown blocker warning and stripping
+
+Completed. Added 1 subprocess test (5 assertions) to
+test/integration.test.ts:
+- Creates a ticket with **Blocked by:** 99 where ticket 99 does not
+  exist in the issues directory
+- Spawns the CLI as a subprocess with mock-agent-pass.js
+- Asserts combined stdout+stderr contains "99" (the unknown blocker
+  number) and "not found" (the warning message)
+- Asserts exit code 0 (ticket completed despite invalid blocker)
+- Asserts ticket file updated to **Status:** done (blocker stripped)
+- Asserts log file created
+
+The warning and stripping logic already existed in src/index.ts
+(lines 155-170): runExecute builds a Set of known ticket numbers,
+iterates tickets to find blockers referencing unknown numbers,
+console.warn's the warning, then filters the blockers array to only
+known numbers. This test validates that behavior end-to-end through
+the subprocess CLI.
+
+All 158 tests pass (setup: 66, orchestrator: 54, integration: 38).
+Lint clean.
+
+## 2026-08-28 - US-009: Dry-run deadlock detection
+
+Completed. Added 1 subprocess test (4 assertions) to
+test/integration.test.ts:
+- Creates two tickets with circular dependencies (1 blocks 2,
+  2 blocks 1)
+- Spawns the CLI with --dry-run
+- Asserts exit code 0
+- Asserts stdout contains "Deadlocked tickets"
+- Asserts stdout lists both ticket filenames (01-alpha.md,
+  02-beta.md)
+
+The deadlock detection logic already existed in dryRun()
+(orchestrator.ts:222-231): after simulating waves, any tickets
+still in ready-for-agent state are reported as deadlocked. This
+test validates that behavior end-to-end through the subprocess
+CLI with a circular dependency scenario.
+
+All 162 tests pass (setup: 66, orchestrator: 54, integration: 42).
+Lint clean.
+
+## 2026-08-28 - US-010: Setup-then-execute composition test
+
+Completed. Added 1 composition test (12 assertions) to
+test/integration.test.ts:
+- Calls setup() with tracker:'local' in a temp project dir,
+  using dist/skills and dist/docs-templates as source dirs
+- Creates .scratch/my-feature/issues/ with 2 ticket files
+  (second blocked by first) and a spec.md
+- Spawns the CLI as a subprocess with mock-agent-pass.js,
+  passing --dir and --spec pointing at the .scratch layout
+- Asserts exit code 0
+- Asserts both tickets updated to **Status:** done
+- Asserts log files created in .scratch/my-feature/logs/
+- Asserts docs/agents/issue-tracker.md exists (from setup)
+- Asserts all 6 .agents/skills/ directories exist (from setup)
+
+Added import of setup and SKILL_DIRS from ../src/setup.js to
+the integration test file.
+
+All 174 tests pass (setup: 66, orchestrator: 54, integration: 54).
+Lint clean.
+
+All 10 user stories now have passes: true. PRD complete.

package/ralph_claude.sh

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+#
+# ralph_claude.sh -- one-task-per-session agentic loop for Claude Code.
+#
+# Each loop iteration = exactly ONE Claude session = ideally ONE task + commit.
+# The bash loop owns the cadence; Claude owns the work inside a single session.
+#
+# Usage:  ./ralph_claude.sh [MAX_ITERATIONS] [MAX_TURNS_PER_SESSION]
+#         ./ralph_claude.sh 200 80
+#
+set -uo pipefail   # NOT -e: we handle per-iteration failures ourselves.
+
+# --- Config -----------------------------------------------------------------
+PROMPT_FILE="PROMPT.md"
+PRD_FILE="specs/prd.json"
+LOG_FILE="progress.log"
+MODEL="claude-opus-4-6"
+MAX_ITERATIONS=${1:-10}
+MAX_TURNS_PER_SESSION=${2:-80}   # hard ceiling so a single session can't run away
+STALL_LIMIT=4                    # bail after this many no-progress iterations
+ITERATION=0
+STALLED_COUNT=0
+TMP_CONTEXT=""                   # globals so the EXIT trap can clean them up
+TMP_CAPTURE=""
+
+# Adaptive reasoning ladder, indexed by stall count (clamps at the last entry).
+# Valid levels: low | medium | high | xhigh | max -- AVAILABILITY DEPENDS ON THE
+# MODEL. If your $MODEL rejects a level (e.g. "max"), trim the high end here.
+# With STALL_LIMIT=4 the loop runs at stall 0,1,2,3 before bailing, so all four
+# tiers fire. Progress resets STALLED_COUNT=0, which drops effort back to the
+# baseline automatically -- no separate "reset to medium" logic needed.
+EFFORT_TIERS=("medium" "high" "max")
+
+# --- UI Colors --------------------------------------------------------------
+BLUE='\033[1;34m'; YELLOW='\033[1;33m'; GREEN='\033[1;32m'; MAGENTA='\033[1;35m'; RED='\033[1;31m'; NC='\033[0m'
+log_info()    { echo -e "${BLUE}ℹ️  $1${NC}"; }
+log_step()    { echo -e "${YELLOW}➔ $1${NC}"; }
+log_success() { echo -e "${GREEN}✅ $1${NC}"; }
+log_warn()    { echo -e "${MAGENTA}⚠️  $1${NC}"; }
+log_error()   { echo -e "${RED}✖ $1${NC}"; }
+
+cleanup() { rm -f "${TMP_CONTEXT:-}" "${TMP_CAPTURE:-}" 2>/dev/null || true; }
+trap cleanup EXIT
+trap 'echo; log_warn "Stopping Ralph Loop..."; exit 130' INT
+
+# --- Preflight --------------------------------------------------------------
+for bin in claude jq git; do
+    command -v "$bin" >/dev/null 2>&1 || { log_error "'$bin' not found in PATH."; exit 1; }
+done
+for f in "$PROMPT_FILE" "$PRD_FILE"; do
+    [ -f "$f" ] || { log_error "Missing required file: $f"; exit 1; }
+done
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { log_error "Not inside a git repo."; exit 1; }
+touch "$LOG_FILE"
+
+# --- Helpers ----------------------------------------------------------------
+# Is the PRD parseable and shaped as expected? Distinguishes a real "done"
+# state from a corrupted file (which must NOT look like success).
+prd_ok() {
+    jq -e 'has("userStories") and (.userStories | type == "array")' "$PRD_FILE" >/dev/null 2>&1
+}
+# Count tasks not yet passing, excluding manual:true (those require a
+# human-in-the-loop device session -- see ralph_device.sh -- and must never
+# be selected or counted by this autonomous loop). Returns -1 on parse failure.
+count_pending() {
+    jq -r '[.userStories[] | select((.passes == false or .passes == null) and (.manual != true))] | length' "$PRD_FILE" 2>/dev/null || echo "-1"
+}
+# Count manual:true stories still not passing, for the "only manual work
+# left" report. These are surfaced but never selected or touched here.
+count_pending_manual() {
+    jq -r '[.userStories[] | select((.passes == false or .passes == null) and (.manual == true))] | length' "$PRD_FILE" 2>/dev/null || echo "-1"
+}
+# Pretty list of pending tasks (for visibility / context). Manual stories are
+# still listed, tagged, so a session knows they exist and to leave them alone.
+pending_list() {
+    jq -r '.userStories[] | select(.passes == false or .passes == null) | "[\(.id)] \(.title)" + (if .manual == true then "  (manual -- excluded from this loop)" else "" end)' "$PRD_FILE" 2>/dev/null
+}
+# Pretty list of manual:true stories still not passing.
+pending_manual_list() {
+    jq -r '.userStories[] | select((.passes == false or .passes == null) and (.manual == true)) | "[\(.id)] \(.title)"' "$PRD_FILE" 2>/dev/null
+}
+# The single highest-priority pending, non-manual task. Empty string when the
+# PRD is valid and has no such task left (caller checks count_pending_manual()
+# to distinguish "fully done" from "only manual work remains").
+current_task() {
+    jq -r '
+        [.userStories[] | select((.passes == false or .passes == null) and (.manual != true))]
+        | sort_by(.priority // 9999)
+        | (.[0] // empty) | "[\(.id)] \(.title)"
+    ' "$PRD_FILE" 2>/dev/null
+}
+
+# Map the stall count onto a reasoning effort level from EFFORT_TIERS, clamping
+# at the last tier. This is the model-side half of escalation: it raises the
+# actual thinking budget via `claude --effort`. The prompt-side half lives in
+# reasoning_hint() below; both ramp on the same counter and stay in sync.
+effort_for_stall() {
+    local n="$1" last=$(( ${#EFFORT_TIERS[@]} - 1 ))
+    [ "$n" -gt "$last" ] && n="$last"
+    echo "${EFFORT_TIERS[$n]}"
+}
+
+# Reasoning hint injected into the prompt, escalating with the stall count.
+# With STALL_LIMIT=4 the hint is evaluated at stall 0,1,2,3 -> all tiers fire
+# before the loop bails. (Prompt-based escalation is version-proof; it doesn't
+# rely on any particular `claude` reasoning flag existing.) This reinforces the
+# `--effort` ladder driven by effort_for_stall().
+reasoning_hint() {
+    case "$1" in
+        0) echo "" ;;
+        1) echo "REASONING: Think step by step before acting." ;;
+        2) echo "REASONING: This task stalled once already. Re-read progress.log and the spec, question your earlier assumptions, and try a different approach." ;;
+        *) echo "REASONING: This task has stalled repeatedly. Think very hard. Re-read the Codebase Patterns and recent learnings in progress.log, abandon the approaches that have already failed, and attempt a genuinely different strategy." ;;
+    esac
+}
+
+# --- Main loop --------------------------------------------------------------
+while [ "$ITERATION" -lt "$MAX_ITERATIONS" ]; do
+    ITERATION=$((ITERATION + 1))
+
+    # 0. Never treat a broken PRD as completion.
+    if ! prd_ok; then
+        log_error "$PRD_FILE is missing/malformed or has no 'userStories' array. Stopping for human review."
+        exit 3
+    fi
+
+    # 1. Pick the one task for this session.
+    TASK="$(current_task)"
+    if [ -z "$TASK" ]; then
+        PENDING_MANUAL="$(count_pending_manual)"
+        if [ "$PENDING_MANUAL" -gt 0 ]; then
+            log_success "No headless work left — only manual:true stories remain:"
+            pending_manual_list
+            log_info "Run each via ./ralph_device.sh <story-id> in an attended session."
+            exit 0
+        fi
+        log_success "All tasks in $PRD_FILE pass. Nothing left to do."
+        exit 0
+    fi
+    PENDING_BEFORE="$(count_pending)"
+    HEAD_BEFORE="$(git rev-parse HEAD 2>/dev/null || echo none)"
+
+    # 1b. Pick this session's reasoning effort from the current stall count.
+    EFFORT="$(effort_for_stall "$STALLED_COUNT")"
+
+    # 2. Stall-driven friction relief: wipe stale local wrangler state.
+    if [ "$STALLED_COUNT" -eq 2 ] && [ -d ".wrangler/state/v3" ]; then
+        log_warn "Friction detected — clearing .wrangler/state/v3 ..."
+        rm -rf .wrangler/state/v3
+    fi
+
+    echo -e "${BLUE}------------------------------------------------------------${NC}"
+    log_info "ITERATION $ITERATION/$MAX_ITERATIONS  |  PENDING: $PENDING_BEFORE  |  STALL: $STALLED_COUNT/$STALL_LIMIT  |  EFFORT: $EFFORT"
+    log_step "TARGET: $TASK"
+    echo -e "${BLUE}------------------------------------------------------------${NC}"
+
+    # 3. Build the per-session context. Pin THIS task and forbid touching others.
+    TMP_CONTEXT="$(mktemp)"
+    {
+        cat "$PROMPT_FILE"
+        echo
+        echo "# THIS SESSION"
+        echo "Work on EXACTLY ONE task: $TASK"
+        echo "Complete it (write failing tests first, implement, lint, run only the"
+        echo "relevant tests, update progress.log, set passes:true for this story,"
+        echo "then commit). When that single task is done and committed, STOP. Do NOT"
+        echo "start any other task this session, and do NOT mark any other story passing."
+        echo
+        echo "Remaining tasks (context only — do not work on these now):"
+        pending_list
+        echo
+        echo "LAST_LOG_ENTRIES:"
+        tail -n 8 "$LOG_FILE" 2>/dev/null
+        HINT="$(reasoning_hint "$STALLED_COUNT")"
+        if [ -n "$HINT" ]; then echo; echo "$HINT"; fi
+    } > "$TMP_CONTEXT"
+
+    # 4. Execute one session. Stream events live for the human; tee the RAW jsonl
+    #    to a capture file. tee sits BETWEEN claude and jq, so the capture holds
+    #    claude's stdout regardless of any downstream jq hiccup.
+    #    --effort raises the model-side reasoning budget as stalls accumulate.
+    TMP_CAPTURE="$(mktemp)"
+    set +o pipefail
+    cat "$TMP_CONTEXT" | claude -p --verbose \
+          --output-format stream-json \
+          --model "$MODEL" \
+          --effort "$EFFORT" \
+          --max-turns "$MAX_TURNS_PER_SESSION" \
+          --dangerously-skip-permissions \
+      | tee "$TMP_CAPTURE" \
+      | jq --unbuffered -r '
+          if .type == "system" then
+            ( .subtype as $s
+              | if   $s == "init"             then "🟦 session start (" + (.model // "?") + ")"
+                elif $s == "api_retry"        then "⏳ retry " + ((.attempt // 0)|tostring) + "/" + ((.max_retries // 0)|tostring)
+                                                    + " — " + (.error // "?") + " " + ((.error_status // "")|tostring)
+                elif $s == "compact_boundary" then "🗜️  context compacted"
+                elif $s == "thinking_tokens"  then "🧠 thinking: " + ([to_entries[] | select(.value|type=="number") | "\(.key)=\(.value)"] | join(" "))
+                else "🟦 system: " + ($s // "?") end )
+          elif .type == "assistant" then
+            (.message.content[]? |
+              if .type == "text"     then "💬 " + .text
+              elif .type == "tool_use" then "🔧 " + .name + ": " + ((.input // {}) | tostring | .[0:140])
+              else empty end)
+          elif .type == "user" then
+            (.message.content[]? | if .type == "tool_result" then "↩️  tool result" else empty end)
+          elif .type == "result" then
+            "✅ " + (.subtype // "done") + "  ($" + ((.total_cost_usd // 0) | tostring) + ")"
+          else empty end
+        ' 2>/dev/null
+    # Capture pipe statuses IMMEDIATELY (before any other command clobbers them).
+    PSTATUS=("${PIPESTATUS[@]}")
+    set -o pipefail
+    CLAUDE_RC="${PSTATUS[1]:-0}"   # 0=cat 1=claude 2=tee 3=jq
+    if [ "$CLAUDE_RC" -ne 0 ]; then
+        log_warn "claude exited non-zero (rc=$CLAUDE_RC) — auth/rate-limit/crash/unsupported --effort? Treating as no progress."
+    fi
+
+    # 5. Detect completion — but ONLY trust it if the PRD agrees all tasks pass.
+    #    This kills false positives from claude merely *restating* the stop
+    #    string while planning, and from any stream that echoes the prompt.
+    PENDING_AFTER="$(count_pending)"
+    if grep -q '<promise>COMPLETE</promise>' "$TMP_CAPTURE"; then
+        if [ "$PENDING_AFTER" -eq 0 ]; then
+            log_success "MISSION ACCOMPLISHED — COMPLETE reported and 0 tasks pending."
+            exit 0
+        else
+            log_warn "Saw COMPLETE signal but $PENDING_AFTER task(s) still pending — ignoring (likely planning text)."
+        fi
+    fi
+
+    # 6. Progress = a NEW COMMIT or FEWER PENDING TASKS. A merely-dirty tree is
+    #    NOT progress: uncommitted flailing must not reset the stall counter,
+    #    otherwise reasoning never escalates.
+    HEAD_AFTER="$(git rev-parse HEAD 2>/dev/null || echo none)"
+    if [ -n "$(git status --porcelain)" ]; then
+        log_warn "Working tree left dirty (uncommitted changes). Not counted as progress — Claude should commit completed work."
+    fi
+
+    if [ "$HEAD_AFTER" != "$HEAD_BEFORE" ] || [ "$PENDING_AFTER" -lt "$PENDING_BEFORE" ]; then
+        DELTA=$((PENDING_BEFORE - PENDING_AFTER))
+        if [ "$DELTA" -gt 1 ]; then
+            log_warn "Pending dropped by $DELTA (>1) — session completed more than one task. Tighten the prompt if this recurs."
+        fi
+        log_success "Progress (commits: $HEAD_BEFORE → $HEAD_AFTER, pending: $PENDING_BEFORE → $PENDING_AFTER). Effort resets to ${EFFORT_TIERS[0]}."
+        STALLED_COUNT=0
+    else
+        STALLED_COUNT=$((STALLED_COUNT + 1))
+        log_warn "No progress this session (stall $STALLED_COUNT/$STALL_LIMIT). Next effort: $(effort_for_stall "$STALLED_COUNT")."
+    fi
+
+    # Clean this iteration's tempfiles now (the EXIT trap is the safety net).
+    rm -f "$TMP_CONTEXT" "$TMP_CAPTURE"; TMP_CONTEXT=""; TMP_CAPTURE=""
+
+    # 7. Bail if we're truly stuck — avoid burning all iterations on a no-op.
+    if [ "$STALLED_COUNT" -ge "$STALL_LIMIT" ]; then
+        log_error "Stalled $STALL_LIMIT sessions in a row with escalation exhausted. Stopping for human review."
+        exit 2
+    fi
+done
+
+log_warn "Reached MAX_ITERATIONS=$MAX_ITERATIONS with tasks still pending ($(count_pending) left)."
+exit 0