autonomous-coding-toolkit 1.0.0

package/scripts/lib/run-plan-parser.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# run-plan-parser.sh — Parse markdown plan files into batch/task structures
+#
+# Plan format:
+#   ## Batch N: Title          <- batch boundary
+#   ### Task M: Name           <- task within batch
+#   [full text...]             <- extracted verbatim
+#
+# Functions:
+#   count_batches <plan_file>                -> number of batches
+#   get_batch_title <plan_file> <batch_num>  -> batch title text
+#   get_batch_text <plan_file> <batch_num>   -> full batch content (tasks + text)
+#   get_batch_task_count <plan_file> <batch_num> -> number of tasks in batch
+#   is_critical_batch <plan_file> <batch_num>    -> exit 0 if tagged CRITICAL
+
+count_batches() {
+    local plan_file="$1"
+    local count
+    count=$(grep -cE '^## Batch [0-9]+' "$plan_file" 2>/dev/null || true)
+    echo "${count:-0}"
+}
+
+get_batch_title() {
+    local plan_file="$1" batch_num="$2"
+    local line
+    line=$(grep -E "^## Batch ${batch_num}:" "$plan_file" 2>/dev/null | head -1)
+    if [[ -z "$line" ]]; then
+        echo ""
+        return
+    fi
+    # Strip "## Batch N: " prefix using bash parameter expansion
+    echo "${line#\#\# Batch ${batch_num}: }"
+}
+
+get_batch_text() {
+    local plan_file="$1" batch_num="$2"
+    # Extract everything after "## Batch N" up to the next "## Batch" or EOF
+    # Uses POSIX-compatible awk: $3 + 0 extracts batch number
+    awk -v batch="$batch_num" '
+        /^## Batch [0-9]+/ {
+            n = $3 + 0
+            if (n == batch) { printing = 1; next }
+            else if (printing) { exit }
+        }
+        printing { print }
+    ' "$plan_file"
+}
+
+get_batch_task_count() {
+    local plan_file="$1" batch_num="$2"
+    local text count
+    text=$(get_batch_text "$plan_file" "$batch_num")
+    if [[ -z "$text" ]]; then
+        echo "0"
+        return
+    fi
+    count=$(echo "$text" | grep -cE '^### Task [0-9]+' 2>/dev/null || true)
+    echo "${count:-0}"
+}
+
+get_batch_context_refs() {
+    local plan_file="$1" batch_num="$2"
+    local batch_text
+    batch_text=$(get_batch_text "$plan_file" "$batch_num")
+    # Extract "context_refs: file1, file2, ..." line
+    local refs_line
+    refs_line=$(echo "$batch_text" | grep -E '^context_refs:' | head -1 || true)
+    if [[ -z "$refs_line" ]]; then
+        echo ""
+        return
+    fi
+    # Strip "context_refs: " prefix and split on comma
+    echo "${refs_line#context_refs: }" | tr ',' '\n' | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//'
+}
+
+is_critical_batch() {
+    local plan_file="$1" batch_num="$2"
+    local header
+    header=$(grep -E "^## Batch ${batch_num}:" "$plan_file" 2>/dev/null | head -1)
+    [[ "$header" == *"CRITICAL"* ]]
+}

package/scripts/lib/run-plan-prompt.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# run-plan-prompt.sh — Build prompts for headless claude -p batch execution
+#
+# Requires run-plan-parser.sh to be sourced first (provides get_batch_title, get_batch_text)
+#
+# Functions:
+#   build_stable_prefix <plan_file> <worktree> <python> <quality_gate_cmd>
+#     -> stable portion of the prompt (plan identity, worktree, python, branch, TDD rules)
+#     -> safe to cache across batches; does NOT include prev_test_count or other per-batch data
+#   build_variable_suffix <plan_file> <batch_num> <worktree> <prev_test_count>
+#     -> per-batch portion of the prompt (tasks, commits, progress, gate results, test count)
+#   build_batch_prompt <plan_file> <batch_num> <worktree> <python> <quality_gate_cmd> <prev_test_count>
+#     -> full self-contained prompt (stable prefix + variable suffix) for claude -p
+#   generate_agents_md <plan_file> <worktree> <mode>
+#     -> writes AGENTS.md to worktree for agent team awareness
+
+# build_stable_prefix — assemble the stable (batch-invariant) portion of a batch prompt.
+#
+# Stability contract: output depends only on plan_file path, worktree path, python path,
+# quality_gate_cmd, and the git branch name. None of these change between batches in a
+# normal run, so the result may be cached and reused across batches.
+#
+# NOTE: prev_test_count intentionally excluded — it changes each batch. It belongs in
+# build_variable_suffix (see issue #48).
+#
+# Args: <plan_file> <worktree> <python> <quality_gate_cmd>
+build_stable_prefix() {
+    local plan_file="$1"
+    local worktree="$2"
+    local python="$3"
+    local quality_gate_cmd="$4"
+
+    local branch
+
+    # #46: Check worktree exists before calling git. Log a warning if git fails so
+    # the caller knows the branch name is unreliable rather than silently caching "unknown".
+    if [[ ! -d "$worktree" ]]; then
+        echo "WARNING: worktree directory does not exist: $worktree" >&2
+        branch="unknown"
+    else
+        branch=$(git -C "$worktree" branch --show-current 2>/dev/null) || {
+            echo "WARNING: git branch failed for worktree: $worktree — using 'unknown'" >&2
+            branch="unknown"
+        }
+        # git can succeed but print nothing (detached HEAD)
+        [[ -z "$branch" ]] && branch="unknown"
+    fi
+
+    cat <<PREFIX
+Working directory: ${worktree}
+Python: ${python}
+Branch: ${branch}
+
+Requirements:
+- TDD: write test -> verify fail -> implement -> verify pass -> commit each task
+- After all tasks: run quality gate (${quality_gate_cmd})
+- Update progress.txt with batch summary and commit
+PREFIX
+}
+
+# build_variable_suffix — assemble the per-batch (variable) portion of a batch prompt.
+#
+# Contains everything that can differ between batches: batch number, title, task text,
+# recent commits, progress tail, previous quality gate result, context refs, and the
+# current prev_test_count (which increases after each batch).
+#
+# Args: <plan_file> <batch_num> <worktree> <prev_test_count>
+build_variable_suffix() {
+    local plan_file="$1"
+    local batch_num="$2"
+    local worktree="$3"
+    local prev_test_count="$4"
+
+    local title batch_text recent_commits progress_tail prev_gate
+
+    title=$(get_batch_title "$plan_file" "$batch_num")
+    batch_text=$(get_batch_text "$plan_file" "$batch_num")
+
+    # Cross-batch context: recent commits
+    recent_commits=$(git -C "$worktree" log --oneline -5 2>/dev/null || echo "(no commits)")
+
+    # Cross-batch context: progress.txt tail
+    # #50: File existence is already checked before calling tail.
+    # Remove 2>/dev/null || true — permission errors on a confirmed-existing file should
+    # propagate so the caller sees the real error rather than silently getting no progress.
+    progress_tail=""
+    if [[ -f "$worktree/progress.txt" ]]; then
+        progress_tail=$(tail -20 "$worktree/progress.txt")
+    fi
+
+    # Cross-batch context: previous quality gate result
+    # #47: Distinguish "no state file / no key" (expected) from "corrupted JSON" (error).
+    # jq returns exit 5 on parse failure. Check exit code and warn on corruption so the
+    # caller knows prev_gate is empty due to an error, not just an absent first batch.
+    prev_gate=""
+    if [[ -f "$worktree/.run-plan-state.json" ]]; then
+        local jq_exit=0
+        prev_gate=$(jq -r '.last_quality_gate // empty' "$worktree/.run-plan-state.json" 2>/dev/null) || jq_exit=$?
+        if [[ $jq_exit -ne 0 ]]; then
+            echo "WARNING: .run-plan-state.json is corrupted (jq exit $jq_exit) — proceeding without previous gate context" >&2
+            prev_gate=""
+        fi
+    fi
+
+    # Cross-batch context: referenced files from context_refs
+    local context_refs_content=""
+    local refs
+    refs=$(get_batch_context_refs "$plan_file" "$batch_num")
+    if [[ -n "$refs" ]]; then
+        while IFS= read -r ref; do
+            [[ -z "$ref" ]] && continue
+            if [[ -f "$worktree/$ref" ]]; then
+                context_refs_content+="
+--- $ref ---
+$(head -100 "$worktree/$ref")
+"
+            fi
+        done <<< "$refs"
+    fi
+
+    cat <<SUFFIX
+You are implementing Batch ${batch_num}: ${title} from ${plan_file}.
+
+Tasks in this batch:
+${batch_text}
+
+Recent commits:
+${recent_commits}
+$(if [[ -n "$progress_tail" ]]; then
+echo "
+Previous progress:
+${progress_tail}"
+fi)
+$(if [[ -n "$prev_gate" && "$prev_gate" != "null" ]]; then
+echo "
+Previous quality gate: ${prev_gate}"
+fi)
+$(if [[ -n "$context_refs_content" ]]; then
+echo "
+Referenced files from prior batches:
+${context_refs_content}"
+fi)
+- All ${prev_test_count}+ tests must pass
+SUFFIX
+}
+
+# build_batch_prompt — full prompt for a single batch (stable prefix + variable suffix).
+#
+# Callers that run multiple batches should prefer calling build_stable_prefix once and
+# caching the result, then calling build_variable_suffix per batch — see run-plan-headless.sh.
+# This function is a convenience wrapper for single-batch callers and tests.
+#
+# Args: <plan_file> <batch_num> <worktree> <python> <quality_gate_cmd> <prev_test_count>
+build_batch_prompt() {
+    local plan_file="$1"
+    local batch_num="$2"
+    local worktree="$3"
+    local python="$4"
+    local quality_gate_cmd="$5"
+    local prev_test_count="$6"
+
+    local stable_prefix variable_suffix
+    stable_prefix=$(build_stable_prefix "$plan_file" "$worktree" "$python" "$quality_gate_cmd")
+    variable_suffix=$(build_variable_suffix "$plan_file" "$batch_num" "$worktree" "$prev_test_count")
+
+    printf '%s\n\n%s\n' "$variable_suffix" "$stable_prefix"
+}
+
+# Generate AGENTS.md in the worktree for agent team awareness.
+# Args: <plan_file> <worktree> <mode>
+generate_agents_md() {
+    local plan_file="$1" worktree="$2" mode="${3:-headless}"
+
+    # Source parser if needed
+    type count_batches &>/dev/null || source "$(dirname "${BASH_SOURCE[0]}")/run-plan-parser.sh"
+
+    local total_batches
+    total_batches=$(count_batches "$plan_file")
+
+    local batch_info=""
+    for ((b = 1; b <= total_batches; b++)); do
+        local title
+        title=$(get_batch_title "$plan_file" "$b")
+        [[ -z "$title" ]] && continue
+        batch_info+="| $b | $title |"$'\n'
+    done
+
+    cat > "$worktree/AGENTS.md" << EOF
+# Agent Configuration
+
+**Plan:** $(basename "$plan_file")
+**Mode:** $mode
+**Total:** $total_batches batches
+
+## Tools Allowed
+
+Bash, Read, Write, Edit, Grep, Glob
+
+## Permission Mode
+
+bypassPermissions
+
+## Batches
+
+| # | Title |
+|---|-------|
+${batch_info}
+## Guidelines
+
+- Run quality gate after each batch
+- Commit after passing gate
+- Append discoveries to progress.txt
+- Do not modify files outside your batch scope
+EOF
+}

package/scripts/lib/run-plan-quality-gate.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# run-plan-quality-gate.sh — Quality gate runner for plan execution
+#
+# Wraps quality-gate.sh with test count regression detection + git status check.
+# Runs between every batch in all modes.
+#
+# Functions:
+#   extract_test_count <test_output>                          -> parse "N passed" from pytest output
+#   check_test_count_regression <new_count> <previous_count>  -> 0 if new >= previous, 1 otherwise
+#   check_git_clean <worktree>                                -> 0 if clean, 1 if dirty
+#   run_quality_gate <worktree> <quality_gate_cmd> <batch_num> [duration] -> full gate: cmd + regression + clean + state update
+#
+# Requires: run-plan-state.sh sourced for run_quality_gate (state functions)
+
+QUALITY_GATE_SCRIPT="${QUALITY_GATE_SCRIPT:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../quality-gate.sh}"
+
+# Extract passed test count from test output.
+# Supports pytest ("N passed"), jest ("Tests: N passed"), go test ("ok" lines).
+# Returns -1 if no recognized format found (signals "skip regression check").
+extract_test_count() {
+    local output="$1"
+    local count
+
+    # 1. pytest: "N passed" (e.g., "85 passed" in "3 failed, 85 passed, 2 skipped in 30.1s")
+    count=$(echo "$output" | grep -oE '[0-9]+ passed' | tail -1 | grep -oE '^[0-9]+' || true)
+    if [[ -n "$count" ]]; then
+        echo "$count"
+        return
+    fi
+
+    # 2. jest: "Tests: N passed" (e.g., "Tests:       45 passed, 48 total")
+    count=$(echo "$output" | grep -oE 'Tests:[[:space:]]+([0-9]+ failed, )?[0-9]+ passed' | grep -oE '[0-9]+ passed' | grep -oE '^[0-9]+' || true)
+    if [[ -n "$count" ]]; then
+        echo "$count"
+        return
+    fi
+
+    # 3. go test: count "ok" lines (each = one passing package)
+    count=$(echo "$output" | grep -c '^ok' || true)
+    if [[ "$count" -gt 0 ]]; then
+        echo "$count"
+        return
+    fi
+
+    # 4. No recognized format — return -1 to signal "skip regression check"
+    echo "-1"
+}
+
+# Check for test count regression.
+# Returns 0 if new_count >= previous_count, 1 otherwise.
+# -1 means unrecognized format — skip regression check.
+check_test_count_regression() {
+    local new_count="$1" previous_count="$2"
+    if [[ "$new_count" == "-1" || "$previous_count" == "-1" ]]; then
+        echo "INFO: Skipping test count regression check (unrecognized test format)" >&2
+        return 0
+    fi
+    if [[ "$new_count" -ge "$previous_count" ]]; then
+        return 0
+    else
+        echo "WARNING: Test count regression: $new_count < $previous_count (previous)" >&2
+        return 1
+    fi
+}
+
+# Check if worktree has uncommitted changes.
+# Returns 0 if clean, 1 if dirty.
+check_git_clean() {
+    local worktree="$1"
+    local status
+    status=$(git -C "$worktree" status --porcelain 2>/dev/null)
+    if [[ -z "$status" ]]; then
+        return 0
+    else
+        echo "WARNING: Worktree has uncommitted changes:" >&2
+        echo "$status" >&2
+        return 1
+    fi
+}
+
+# Run the full quality gate for a batch.
+# Executes quality_gate_cmd, checks test regression, checks git clean, updates state.
+# Returns 0 on pass, 1 on fail.
+#
+# Requires run-plan-state.sh functions: get_previous_test_count, complete_batch, set_quality_gate
+run_quality_gate() {
+    local worktree="$1" quality_gate_cmd="$2" batch_num="$3" duration="${4:-0}"
+    local gate_output gate_exit test_count previous_count
+
+    echo "=== Quality Gate: Batch $batch_num ==="
+
+    # 1. Execute quality gate command in worktree.
+    # Use 'bash -c' rather than 'eval' to avoid command injection from the
+    # user-supplied --quality-gate CLI flag (#3). The command may contain
+    # shell features (pipes, redirects) so a simple array exec isn't viable,
+    # but 'bash -c' still runs in a fresh subshell which limits injection scope.
+    gate_output=$(cd "$worktree" && bash -c "$quality_gate_cmd" 2>&1) && gate_exit=0 || gate_exit=$?
+    echo "$gate_output"
+
+    if [[ $gate_exit -ne 0 ]]; then
+        echo ""
+        echo "QUALITY GATE FAILED: command exited $gate_exit"
+        set_quality_gate "$worktree" "$batch_num" "false" 0
+        return 1
+    fi
+
+    # 2. Extract test count from output
+    test_count=$(extract_test_count "$gate_output")
+    echo "Test count: $test_count"
+
+    # 3. Compare against previous batch count
+    previous_count=$(get_previous_test_count "$worktree")
+    if ! check_test_count_regression "$test_count" "$previous_count"; then
+        echo "QUALITY GATE FAILED: test count regression ($test_count < $previous_count)"
+        set_quality_gate "$worktree" "$batch_num" "false" "$test_count"
+        return 1
+    fi
+
+    # 4. Check git clean
+    if ! check_git_clean "$worktree"; then
+        echo "QUALITY GATE FAILED: uncommitted changes in worktree"
+        set_quality_gate "$worktree" "$batch_num" "false" "$test_count"
+        return 1
+    fi
+
+    # 5. Update state — batch complete, gate passed
+    complete_batch "$worktree" "$batch_num" "$test_count" "$duration"
+    set_quality_gate "$worktree" "$batch_num" "true" "$test_count"
+
+    echo "QUALITY GATE PASSED (batch $batch_num, $test_count tests)"
+    return 0
+}