@frankzhang2026/opencode-android-orchestrator 0.1.0 → 0.2.0

package/templates/scripts/automation/orchestrate-task.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib.sh
+source "$SCRIPT_DIR/lib.sh"
+
+task_id="${1:-}"
+[[ "$#" -eq 1 ]] || { printf 'Usage: %s TASK-ID\n' "$0" >&2; exit 2; }
+automation_validate_task_id "$task_id"
+automation_require_orchestrated
+
+workspace_file="$(automation_workspace_path "$task_id")"
+[[ -f "$workspace_file" ]] || automation_die "workspace metadata is missing for $task_id"
+task_root="$(automation_workspace_task_root "$workspace_file")"
+workspace_strategy="$(automation_workspace_strategy "$workspace_file")"
+source_root="$(jq -er '.sourceRoot' "$workspace_file")"
+[[ -d "$task_root" ]] || automation_die "task root is missing: $task_root"
+if [[ "$(jq -r '.repositoryLeaseRequired // false' "$workspace_file")" == "true" ]]; then
+    automation_require_repository_lease "$task_id" "$source_root" "$workspace_strategy"
+fi
+
+automation_acquire_run_lock "$task_id"
+trap 'automation_release_run_lock' EXIT
+
+if [[ "${AUTOMATION_SKIP_AGENT_RUN:-0}" == "1" ]]; then
+    [[ "${AUTOMATION_TEST_MODE:-0}" == "1" ]] || automation_die "AUTOMATION_SKIP_AGENT_RUN is reserved for tests"
+    automation_info "test mode: task is prepared; agent launch skipped"
+    exit 0
+fi
+automation_require_command opencode
+
+run_agent() {
+    local role="$1"
+    local prompt="$2"
+    local cycle="$3"
+    local attempt="${4:-0}"
+    local log_file exit_code
+    if [[ "$attempt" -eq 0 ]]; then
+        log_file="$(automation_evidence_path "$task_id")/${role}-cycle-${cycle}.log"
+    else
+        log_file="$(automation_evidence_path "$task_id")/${role}-cycle-${cycle}-attempt-${attempt}.log"
+    fi
+    automation_info "starting $role for $task_id in $task_root"
+    set +e
+    (
+        cd "$task_root"
+        opencode run --agent "$role" -- "$prompt"
+    ) 2>&1 | tee "$log_file"
+    exit_code=${PIPESTATUS[0]}
+    set -e
+    jq -nc \
+        --arg taskId "$task_id" \
+        --arg role "$role" \
+        --argjson cycle "$cycle" \
+        --argjson attempt "$attempt" \
+        --arg at "$(automation_now)" \
+        --argjson exitCode "$exit_code" \
+        '{taskId: $taskId, role: $role, cycle: $cycle, attempt: $attempt, at: $at, exitCode: $exitCode}' \
+        | automation_append_json "$(automation_evidence_path "$task_id")/agent-runs.jsonl"
+    return "$exit_code"
+}
+
+for _step in 1 2 3 4 5 6 7 8; do
+    state="$(automation_read_state "$task_id")"
+    case "$state" in
+        PENDING|CODING)
+            coding_cycle="$(jq -er '.codingCycle // 0' "$workspace_file")"
+            coder_prompt="Use \$scheduled-quality-coder with $task_id. This is an orchestrated non-interactive run. Follow the deterministic state and evidence scripts. Never commit, merge, create worktrees, or push."
+            run_agent scheduled-coder "$coder_prompt" "$coding_cycle" || true
+            next_state="$(automation_read_state "$task_id")"
+            if [[ "$next_state" == "PENDING" || "$next_state" == "CODING" ]]; then
+                automation_transition_state "$task_id" "$next_state" "BLOCKED" "orchestrator" "coder exited without reaching a terminal gate state"
+            fi
+            ;;
+        READY_FOR_REVIEW)
+            (
+                cd "$task_root"
+                ./scripts/automation/begin-review.sh "$task_id"
+            )
+            ;;
+        REVIEWING)
+            review_cycle="$(jq -er '.reviewCycles // 0' "$workspace_file")"
+            agent_runs="$(automation_evidence_path "$task_id")/agent-runs.jsonl"
+            review_attempt=0
+            if [[ -f "$agent_runs" ]]; then
+                review_attempt="$(jq -s --argjson cycle "$review_cycle" '[.[] | select(.role == "scheduled-reviewer" and .cycle == $cycle)] | length' "$agent_runs")"
+            fi
+            reviewer_prompt="Use \$scheduled-quality-reviewer with $task_id. This is fresh, non-interactive, read-only review attempt $review_attempt for sealed review cycle $review_cycle. Work within the step budget. Run exactly ./scripts/automation/status.sh $task_id once; its JSON already includes baseline, RED, ready, latest gate, current diff SHA, and the sealed-SHA comparison, so do not browse the external evidence directory. Then inspect the approved contract and run exactly git diff. Submit exactly one decision. Do not browse generated build reports, list the whole repository, retry denied command variants, or run Gradle commands separately before deciding: submit-review.sh performs and records the focused tests, full unit suite, assembleDebug, and lint for APPROVED. Reserve a tool call for submit-review.sh. Never edit, commit, merge, or push."
+            run_agent scheduled-reviewer "$reviewer_prompt" "$review_cycle" "$review_attempt" || true
+            if [[ "$(automation_read_state "$task_id")" == "REVIEWING" ]]; then
+                automation_transition_state "$task_id" "REVIEWING" "BLOCKED" "orchestrator" "reviewer exited without submitting a decision; sealed diff preserved for reviewer-only recovery"
+            fi
+            ;;
+        CHANGES_REQUESTED)
+            (
+                cd "$task_root"
+                ./scripts/automation/resume-review-fix.sh "$task_id"
+            ) || true
+            ;;
+        AWAITING_HUMAN)
+            automation_info "$task_id reached AWAITING_HUMAN"
+            (
+                cd "$task_root"
+                ./scripts/automation/acceptance-report.sh "$task_id" >/dev/null
+            )
+            "$SCRIPT_DIR/show-acceptance-review.sh" "$task_id"
+            exit 0
+            ;;
+        BLOCKED|TEST_FAILED|NEEDS_HUMAN|INTEGRATION_BLOCKED)
+            automation_die "$task_id stopped in $state; inspect $(automation_evidence_path "$task_id")"
+            ;;
+        *)
+            automation_die "cannot orchestrate $task_id from state $state"
+            ;;
+    esac
+done
+
+automation_die "$task_id exceeded the deterministic orchestration step bound"

package/templates/scripts/automation/preflight.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib.sh
+source "$SCRIPT_DIR/lib.sh"
+
+shadow=0
+source_mode=0
+task_id=""
+for arg in "$@"; do
+    case "$arg" in
+        --shadow) shadow=1 ;;
+        --source) source_mode=1 ;;
+        TASK-*) task_id="$arg" ;;
+        *) printf 'Usage: %s [--shadow|--source] [TASK-ID]\n' "$0" >&2; exit 2 ;;
+    esac
+done
+[[ "$shadow" != "1" || "$source_mode" != "1" ]] || automation_die "--shadow and --source are mutually exclusive"
+
+fail_or_warn() {
+    if [[ "$shadow" == "1" ]]; then
+        automation_warn "$1"
+        return 0
+    fi
+    automation_die "$1"
+}
+
+automation_require_layout
+automation_require_command git
+automation_require_command jq
+automation_require_command rg
+automation_require_command shasum
+if [[ "${AUTOMATION_TEST_MODE:-0}" != "1" ]]; then
+    automation_require_command opencode
+fi
+[[ -x "$AUTOMATION_ROOT/gradlew" ]] || automation_die "gradlew is missing or not executable"
+
+automation_validate_config
+workspace_strategy="$(automation_config_value '.workspaceStrategy')"
+if [[ "$workspace_strategy" == "isolatedWorktree" ]]; then
+    automation_worktree_base >/dev/null
+fi
+
+enabled="$(automation_config_value '.enabled')"
+mode="$(automation_config_value '.mode')"
+
+[[ "$enabled" == "true" ]] || fail_or_warn "automation is disabled"
+[[ "$mode" == "orchestrated" ]] || fail_or_warn "automation mode is $mode, not orchestrated"
+
+if [[ "${AUTOMATION_TEST_MODE:-0}" != "1" ]]; then
+    [[ -n "${ANDROID_HOME:-}" ]] || fail_or_warn "ANDROID_HOME is not set; configure the Android SDK environment before running OpenCode"
+    if [[ -n "${ANDROID_HOME:-}" ]]; then
+        [[ -d "$ANDROID_HOME" ]] || fail_or_warn "ANDROID_HOME does not exist: $ANDROID_HOME"
+    fi
+fi
+
+if [[ -z "$task_id" ]] && ! automation_worktree_is_clean; then
+    fail_or_warn "Git worktree is dirty"
+fi
+
+if [[ "$source_mode" == "1" ]]; then
+    repository_lease_file="$(automation_repository_lease_dir)/lease.json"
+    if [[ -f "$repository_lease_file" ]]; then
+        fail_or_warn "repository workspace is leased by $(jq -r '.taskId // "an unknown task"' "$repository_lease_file")"
+    elif [[ -d "$(automation_repository_lease_dir)" ]]; then
+        fail_or_warn "repository workspace lease is malformed"
+    fi
+    automation_current_branch >/dev/null
+    git -C "$AUTOMATION_ROOT" config user.name >/dev/null || automation_die "Git user.name is not configured"
+    git -C "$AUTOMATION_ROOT" config user.email >/dev/null || automation_die "Git user.email is not configured"
+fi
+
+if [[ -n "$task_id" ]]; then
+    automation_validate_task_id "$task_id"
+    "$SCRIPT_DIR/validate-contract.sh" "$task_id"
+    workspace_file="$(automation_workspace_path "$task_id")"
+    [[ -f "$workspace_file" ]] || fail_or_warn "workspace metadata is missing for $task_id"
+    if [[ -f "$workspace_file" ]]; then
+        task_root="$(automation_workspace_task_root "$workspace_file")"
+        task_strategy="$(automation_workspace_strategy "$workspace_file")"
+        source_root="$(jq -er '.sourceRoot' "$workspace_file")"
+        task_branch="$(jq -er '.taskBranch' "$workspace_file")"
+        baseline_head="$(jq -er '.baselineHead' "$workspace_file")"
+        resolved_task_root="$(cd "$task_root" 2>/dev/null && pwd || true)"
+        [[ "$resolved_task_root" == "$AUTOMATION_ROOT" ]] || fail_or_warn "run must occur in the recorded task root: $task_root"
+        [[ "$(automation_current_branch)" == "$task_branch" ]] || fail_or_warn "current branch does not match task branch: $task_branch"
+        [[ "$(git -C "$AUTOMATION_ROOT" rev-parse HEAD)" == "$baseline_head" ]] || fail_or_warn "task HEAD changed outside the deterministic integrator"
+        planning_commit_policy="$(jq -r '.planningArtifactsCommitPolicy // "legacyCommittedSeparately"' "$workspace_file")"
+        if [[ "$planning_commit_policy" == "withProductChanges" ]]; then
+            automation_assert_planning_artifacts_sealed "$task_id" "$AUTOMATION_ROOT" || \
+                fail_or_warn "approved planning artifact validation failed for $task_id"
+            pending_path_count=0
+            while IFS= read -r pending_path; do
+                [[ -n "$pending_path" ]] || continue
+                pending_path_count=$((pending_path_count + 1))
+                automation_is_planning_artifact "$task_id" "$pending_path" || \
+                    fail_or_warn "unexpected change exists before Coder starts: $pending_path"
+                if git -C "$AUTOMATION_ROOT" ls-files --error-unmatch -- "$pending_path" >/dev/null 2>&1; then
+                    fail_or_warn "planning artifact was committed before product changes: $pending_path"
+                fi
+            done < <(automation_changed_paths)
+            [[ "$pending_path_count" -eq 2 ]] || fail_or_warn "task must start with exactly two sealed, uncommitted planning artifacts"
+        elif ! automation_worktree_is_clean; then
+            fail_or_warn "Git worktree is dirty"
+        fi
+        if [[ "$task_strategy" == "inPlaceExclusive" ]]; then
+            [[ "$task_root" == "$source_root" ]] || fail_or_warn "in-place task root must equal the recorded source root"
+        elif [[ "$task_strategy" == "isolatedWorktree" ]]; then
+            [[ "$task_root" != "$source_root" ]] || fail_or_warn "isolated task root must differ from the source root"
+        else
+            fail_or_warn "unsupported workspace strategy: $task_strategy"
+        fi
+        if [[ "$(jq -r '.repositoryLeaseRequired // false' "$workspace_file")" == "true" ]]; then
+            automation_require_repository_lease "$task_id" "$source_root" "$task_strategy" || \
+                fail_or_warn "repository workspace lease validation failed for $task_id"
+        fi
+    fi
+fi
+
+if [[ "${AUTOMATION_TEST_MODE:-0}" == "1" ]]; then
+    automation_info "test mode: OpenCode discovery checks skipped"
+else
+    discovery_dir="$(mktemp -d "${TMPDIR:-/tmp}/opencode-android-orchestrator-preflight.XXXXXX")"
+    trap 'rm -rf "$discovery_dir"' EXIT
+
+    if ! opencode debug config > "$discovery_dir/config.json" 2> "$discovery_dir/config.err"; then
+        automation_die "OpenCode resolved config failed; see $discovery_dir/config.err"
+    fi
+    superpowers_pin="$(jq -r '.plugins.superpowers' "$AUTOMATION_CONFIG")"
+    rg -F "$superpowers_pin" "$discovery_dir/config.json" >/dev/null || automation_die "resolved OpenCode config is missing pinned Superpowers"
+
+    if ! opencode debug skill > "$discovery_dir/skills.txt" 2> "$discovery_dir/skills.err"; then
+        automation_die "OpenCode skill discovery failed; see $discovery_dir/skills.err"
+    fi
+    while IFS= read -r skill; do
+        rg -F "\"$skill\"" "$discovery_dir/skills.txt" >/dev/null || \
+            rg -F "$skill" "$discovery_dir/skills.txt" >/dev/null || \
+            automation_die "required skill is not discoverable: $skill"
+    done < <(jq -r '.requiredSkills[]' "$AUTOMATION_CONFIG")
+
+    opencode debug agent scheduled-coder > "$discovery_dir/coder-agent.json" 2> "$discovery_dir/coder-agent.err" || \
+        automation_die "scheduled-coder agent is not discoverable"
+    opencode debug agent scheduled-reviewer > "$discovery_dir/reviewer-agent.json" 2> "$discovery_dir/reviewer-agent.err" || \
+        automation_die "scheduled-reviewer agent is not discoverable"
+    opencode debug agent scheduled-planner > "$discovery_dir/planner-agent.json" 2> "$discovery_dir/planner-agent.err" || \
+        automation_die "scheduled-planner agent is not discoverable"
+
+    jq -e '
+        def last_rule($permission; $pattern):
+            [.permission[] | select(.permission == $permission and .pattern == $pattern) | .action][-1];
+        (last_rule("*"; "*") == "deny") and
+        (last_rule("edit"; "docs/plans/**") == "allow") and
+        (last_rule("edit"; "automation/tasks/**") == "allow") and
+        (last_rule("edit"; "**/src/**") == "deny") and
+        (last_rule("bash"; "./scripts/automation/prepare-contract-review.sh *") == "allow") and
+        (last_rule("bash"; "./scripts/automation/approve-and-run.sh *") == "allow") and
+        (last_rule("bash"; "./scripts/automation/resume-review.sh *") == "allow") and
+        (last_rule("bash"; "./scripts/automation/accept-and-integrate.sh *") == "allow") and
+        (last_rule("bash"; "./scripts/automation/abort-task.sh *") == "allow") and
+        (last_rule("android_orchestrator_status"; "*") == "allow") and
+        (last_rule("android_orchestrator_doctor"; "*") == "allow") and
+        (last_rule("schedule_job"; "*") == "deny") and
+        (last_rule("task"; "*") == "deny") and
+        (.tools.question == true) and
+        (.tools.android_orchestrator_status == true) and
+        (.tools.android_orchestrator_doctor == true) and
+        ((.tools.schedule_job // false) == false) and
+        ((.tools.task // false) == false)
+    ' "$discovery_dir/planner-agent.json" >/dev/null || automation_die "scheduled-planner resolved permissions are unsafe"
+
+    jq -e '
+        def last_rule($permission; $pattern):
+            [.permission[] | select(.permission == $permission and .pattern == $pattern) | .action][-1];
+        (last_rule("*"; "*") == "deny") and
+        (last_rule("edit"; "**/src/main/**") == "allow") and
+        (last_rule("edit"; ".opencode/skills/**") == "deny") and
+        (last_rule("android_orchestrator_status"; "*") == "allow") and
+        (last_rule("android_orchestrator_doctor"; "*") == "allow") and
+        (last_rule("schedule_job"; "*") == "deny") and
+        (last_rule("task"; "*") == "deny") and
+        (.tools.android_orchestrator_status == true) and
+        (.tools.android_orchestrator_doctor == true) and
+        ((.tools.schedule_job // false) == false) and
+        ((.tools.delete_job // false) == false) and
+        ((.tools.task // false) == false)
+    ' "$discovery_dir/coder-agent.json" >/dev/null || automation_die "scheduled-coder resolved permissions are unsafe"
+
+    jq -e '
+        def last_rule($permission; $pattern):
+            [.permission[] | select(.permission == $permission and .pattern == $pattern) | .action][-1];
+        (last_rule("*"; "*") == "deny") and
+        (last_rule("edit"; "*") == "deny") and
+        (last_rule("android_orchestrator_status"; "*") == "allow") and
+        (last_rule("android_orchestrator_doctor"; "*") == "allow") and
+        (last_rule("schedule_job"; "*") == "deny") and
+        (last_rule("task"; "*") == "deny") and
+        (.tools.android_orchestrator_status == true) and
+        (.tools.android_orchestrator_doctor == true) and
+        ((.tools.schedule_job // false) == false) and
+        ((.tools.delete_job // false) == false) and
+        ((.tools.task // false) == false)
+    ' "$discovery_dir/reviewer-agent.json" >/dev/null || automation_die "scheduled-reviewer resolved permissions are unsafe"
+fi
+
+automation_info "preflight completed (mode=$mode, shadow=$shadow, source=$source_mode${task_id:+, task=$task_id}, sdk=${ANDROID_HOME:-unset})"

package/templates/scripts/automation/prepare-contract-review.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib.sh
+source "$SCRIPT_DIR/lib.sh"
+
+task_id="${1:-}"
+approval="${2:-}"
+if [[ "$#" -ne 2 ]]; then
+    printf 'Usage: %s TASK-ID "PROPOSAL-APPROVAL"\n' "$0" >&2
+    exit 2
+fi
+
+automation_validate_task_id "$task_id"
+automation_require_orchestrated
+automation_require_approval proposal "$approval"
+automation_assert_repository_lease_available "$task_id"
+"$SCRIPT_DIR/validate-contract.sh" "$task_id" >/dev/null
+
+contract="$(automation_contract_path "$task_id")"
+contract_rel="automation/tasks/$task_id.json"
+plan_rel="$(jq -er '.planPath' "$contract")"
+plan="$AUTOMATION_ROOT/$plan_rel"
+state_file="$(automation_state_path "$task_id")"
+origin_file="$(automation_origin_path "$task_id")"
+
+changed_paths=()
+while IFS= read -r path; do
+    [[ -n "$path" ]] && changed_paths+=("$path")
+done < <(automation_changed_paths)
+if [[ "${#changed_paths[@]}" -ne 2 ]] || \
+   [[ " ${changed_paths[*]} " != *" $contract_rel "* ]] || \
+   [[ " ${changed_paths[*]} " != *" $plan_rel "* ]]; then
+    automation_die "before contract review, the only changed paths must be $plan_rel and $contract_rel"
+fi
+for planning_path in "$plan_rel" "$contract_rel"; do
+    if git -C "$AUTOMATION_ROOT" ls-files --error-unmatch -- "$planning_path" >/dev/null 2>&1; then
+        automation_die "planning artifact must be a new untracked file: $planning_path"
+    fi
+done
+
+original_branch="$(automation_current_branch)"
+original_head="$(git -C "$AUTOMATION_ROOT" rev-parse HEAD)"
+contract_sha="$(automation_file_sha256 "$contract")"
+plan_sha="$(automation_file_sha256 "$plan")"
+
+automation_acquire_run_lock "$task_id"
+trap 'automation_release_run_lock' EXIT
+
+if [[ -f "$state_file" ]]; then
+    [[ "$(automation_read_state "$task_id")" == "CONTRACT_REVIEW" ]] || \
+        automation_die "task already has runtime state: $(automation_read_state "$task_id")"
+    [[ -f "$origin_file" ]] || automation_die "existing contract review has no origin evidence"
+    jq -e \
+        --arg root "$AUTOMATION_ROOT" \
+        --arg branch "$original_branch" \
+        --arg head "$original_head" \
+        --arg contractSha "$contract_sha" \
+        --arg planSha "$plan_sha" \
+        '.sourceRoot == $root and .originalBranch == $branch and
+         .originalHeadBeforeContract == $head and
+         .contractSha256 == $contractSha and .planSha256 == $planSha' \
+        "$origin_file" >/dev/null || automation_die "contract review artifacts changed; create a new task ID"
+    automation_info "$task_id is already waiting for contract review"
+    "$SCRIPT_DIR/status.sh" "$task_id"
+    exit 0
+fi
+
+automation_ensure_runtime_layout
+mkdir -p "$(automation_evidence_path "$task_id")"
+jq -n \
+    --arg taskId "$task_id" \
+    --arg sourceRoot "$AUTOMATION_ROOT" \
+    --arg originalBranch "$original_branch" \
+    --arg originalHeadBeforeContract "$original_head" \
+    --arg contractPath "$contract_rel" \
+    --arg planPath "$plan_rel" \
+    --arg contractSha256 "$contract_sha" \
+    --arg planSha256 "$plan_sha" \
+    --arg preparedAt "$(automation_now)" \
+    '{taskId: $taskId, sourceRoot: $sourceRoot, originalBranch: $originalBranch,
+      originalHeadBeforeContract: $originalHeadBeforeContract,
+      contractPath: $contractPath, planPath: $planPath,
+      contractSha256: $contractSha256, planSha256: $planSha256,
+      preparedAt: $preparedAt}' \
+    | automation_record_json "$origin_file"
+
+jq -nc \
+    --arg taskId "$task_id" \
+    --arg kind "proposal" \
+    --arg at "$(automation_now)" \
+    --arg contractSha256 "$contract_sha" \
+    --arg planSha256 "$plan_sha" \
+    '{taskId: $taskId, kind: $kind, at: $at,
+      contractSha256: $contractSha256, planSha256: $planSha256}' \
+    | automation_append_json "$(automation_approvals_path "$task_id")"
+
+automation_initialize_state "$task_id" "CONTRACT_REVIEW" "planner" "proposal approved; generated artifacts await contract review"
+automation_info "$task_id is ready for human contract review on $original_branch at $original_head"
+"$SCRIPT_DIR/status.sh" "$task_id"

package/templates/scripts/automation/quality-gate.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib.sh
+source "$SCRIPT_DIR/lib.sh"
+
+task_id="${1:-}"
+[[ -n "$task_id" ]] || { printf 'Usage: %s TASK-ID\n' "$0" >&2; exit 2; }
+automation_validate_task_id "$task_id"
+[[ "$(automation_read_state "$task_id")" == "CODING" ]] || automation_die "$task_id is not CODING"
+"$SCRIPT_DIR/validate-contract.sh" "$task_id" >/dev/null
+
+contract="$(automation_contract_path "$task_id")"
+evidence_dir="$(automation_evidence_path "$task_id")"
+mkdir -p "$evidence_dir"
+workspace_file="$(automation_workspace_path "$task_id")"
+coding_cycle=0
+if [[ -f "$workspace_file" ]]; then
+    coding_cycle="$(jq -er '.codingCycle // 0' "$workspace_file")"
+fi
+attempt_file="$evidence_dir/gate-attempts-cycle-$coding_cycle.json"
+previous_attempts=0
+if [[ -f "$attempt_file" ]]; then
+    previous_attempts="$(jq -er '.attempts' "$attempt_file")"
+fi
+attempt=$((previous_attempts + 1))
+max_fix_loops="$(jq -r '.maxFixLoops' "$contract")"
+max_attempts=$((max_fix_loops + 1))
+[[ "$attempt" -le "$max_attempts" ]] || automation_die "quality gate attempt limit already exhausted"
+
+attempt_log="$evidence_dir/gate-cycle-$coding_cycle-attempt-$attempt.log"
+started_at="$(automation_now)"
+set +e
+"$SCRIPT_DIR/verify-task.sh" "$task_id" 2>&1 | tee "$attempt_log"
+gate_status=${PIPESTATUS[0]}
+set -e
+
+jq -n \
+    --arg taskId "$task_id" \
+    --argjson attempts "$attempt" \
+    --argjson codingCycle "$coding_cycle" \
+    --argjson maxAttempts "$max_attempts" \
+    --arg startedAt "$started_at" \
+    --arg finishedAt "$(automation_now)" \
+    --argjson exitCode "$gate_status" \
+    '{taskId: $taskId, codingCycle: $codingCycle, attempts: $attempts, maxAttempts: $maxAttempts, lastStartedAt: $startedAt, lastFinishedAt: $finishedAt, lastExitCode: $exitCode}' \
+    | automation_record_json "$attempt_file"
+
+if [[ "$gate_status" -ne 0 ]]; then
+    if [[ "$gate_status" -eq 40 || "$gate_status" -eq 41 ]]; then
+        automation_transition_state "$task_id" "CODING" "BLOCKED" "quality-gate" "scope, integrity, or evidence gate failed with exit $gate_status"
+    elif [[ "$attempt" -ge "$max_attempts" ]]; then
+        automation_transition_state "$task_id" "CODING" "TEST_FAILED" "quality-gate" "verification failed after $attempt attempts"
+    else
+        automation_warn "verification failed; one systematic fix loop remains"
+    fi
+    exit "$gate_status"
+fi
+
+diff_sha="$(automation_worktree_diff_sha)"
+jq -n \
+    --arg taskId "$task_id" \
+    --arg verifiedAt "$(automation_now)" \
+    --arg head "$(git -C "$AUTOMATION_ROOT" rev-parse HEAD)" \
+    --arg diffSha256 "$diff_sha" \
+    --argjson attempts "$attempt" \
+    --argjson codingCycle "$coding_cycle" \
+    '{taskId: $taskId, verifiedAt: $verifiedAt, head: $head, diffSha256: $diffSha256, gateAttempts: $attempts, codingCycle: $codingCycle}' \
+    | automation_record_json "$evidence_dir/ready.json"
+
+automation_transition_state "$task_id" "CODING" "READY_FOR_REVIEW" "quality-gate" "G1-G6 passed with fresh evidence"

package/templates/scripts/automation/queue-task.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib.sh
+source "$SCRIPT_DIR/lib.sh"
+
+task_id="${1:-}"
+[[ -n "$task_id" ]] || { printf 'Usage: AUTOMATION_HUMAN_APPROVED=1 %s TASK-ID\n' "$0" >&2; exit 2; }
+automation_validate_task_id "$task_id"
+automation_require_layout
+
+[[ "${AUTOMATION_HUMAN_APPROVED:-0}" == "1" ]] || automation_die "set AUTOMATION_HUMAN_APPROVED=1 after explicit human approval"
+[[ "$(automation_config_value '.enabled')" == "true" ]] || automation_die "automation is disabled"
+[[ "$(automation_config_value '.mode')" == "orchestrated" ]] || automation_die "automation mode is not orchestrated"
+
+"$SCRIPT_DIR/validate-contract.sh" "$task_id"
+state_file="$(automation_state_path "$task_id")"
+
+if [[ ! -f "$state_file" ]]; then
+    automation_initialize_state "$task_id" "APPROVED_CONTRACT" "human" "legacy manual queue initialized"
+fi
+
+current="$(automation_read_state "$task_id")"
+case "$current" in
+    APPROVED_CONTRACT|TEST_FAILED|BLOCKED|CHANGES_REQUESTED)
+        automation_transition_state "$task_id" "$current" "PENDING" "human" "explicit human queue approval"
+        ;;
+    PENDING)
+        automation_info "$task_id is already PENDING"
+        ;;
+    *)
+        automation_die "cannot queue $task_id from state $current"
+        ;;
+esac

package/templates/scripts/automation/record-red.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib.sh
+source "$SCRIPT_DIR/lib.sh"
+
+task_id="${1:-}"
+expected="${2:-}"
+separator="${3:-}"
+filter="${4:-}"
+
+if [[ -z "$task_id" || -z "$expected" || "$separator" != "--" || -z "$filter" || "$#" -ne 4 ]]; then
+    printf 'Usage: %s TASK-ID EXPECTED-FAILURE-TEXT -- TEST-FILTER\n' "$0" >&2
+    exit 2
+fi
+
+automation_validate_task_id "$task_id"
+safe_filter_pattern='^[A-Za-z0-9_.#$*-]+$'
+[[ "$filter" =~ $safe_filter_pattern ]] || automation_die "unsafe test filter: $filter"
+[[ ${#expected} -ge 3 ]] || automation_die "expected failure text is too short"
+[[ "$(automation_read_state "$task_id")" == "CODING" ]] || automation_die "$task_id is not CODING"
+"$SCRIPT_DIR/validate-contract.sh" "$task_id"
+
+contract="$(automation_contract_path "$task_id")"
+jq -e --arg filter "$filter" '.targetTests | index($filter) != null' "$contract" >/dev/null || \
+    automation_die "test filter is not declared in the contract: $filter"
+
+evidence_dir="$(automation_evidence_path "$task_id")"
+mkdir -p "$evidence_dir"
+red_log="$evidence_dir/red.log"
+red_meta="$evidence_dir/red.json"
+[[ ! -e "$red_meta" ]] || automation_die "RED evidence already exists for $task_id"
+started_at="$(automation_now)"
+
+set +e
+(
+    cd "$AUTOMATION_ROOT"
+    ./gradlew testDebugUnitTest --tests "$filter"
+) 2>&1 | tee "$red_log"
+red_status=${PIPESTATUS[0]}
+set -e
+
+[[ "$red_status" -ne 0 ]] || automation_die "RED capture failed: focused test passed before implementation"
+rg -F "$expected" "$red_log" >/dev/null || automation_die "RED output does not contain the expected failure text"
+
+jq -n \
+    --arg taskId "$task_id" \
+    --arg startedAt "$started_at" \
+    --arg finishedAt "$(automation_now)" \
+    --arg expectedFailure "$expected" \
+    --arg testFilter "$filter" \
+    --argjson exitCode "$red_status" \
+    '{taskId: $taskId, startedAt: $startedAt, finishedAt: $finishedAt, command: ["./gradlew", "testDebugUnitTest", "--tests", $testFilter], expectedFailure: $expectedFailure, exitCode: $exitCode}' \
+    | automation_record_json "$red_meta"
+
+automation_info "$task_id RED evidence recorded"

package/templates/scripts/automation/resume-review-fix.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib.sh
+source "$SCRIPT_DIR/lib.sh"
+
+task_id="${1:-}"
+[[ "$#" -eq 1 ]] || { printf 'Usage: %s TASK-ID\n' "$0" >&2; exit 2; }
+automation_validate_task_id "$task_id"
+[[ "$(automation_read_state "$task_id")" == "CHANGES_REQUESTED" ]] || automation_die "$task_id is not CHANGES_REQUESTED"
+
+workspace_file="$(automation_workspace_path "$task_id")"
+[[ -f "$workspace_file" ]] || automation_die "workspace metadata is missing"
+review_cycles="$(jq -er '.reviewCycles // 0' "$workspace_file")"
+max_review_cycles="$(automation_config_value '.maxReviewCycles')"
+if [[ "$review_cycles" -ge "$max_review_cycles" ]]; then
+    automation_transition_state "$task_id" "CHANGES_REQUESTED" "NEEDS_HUMAN" "orchestrator" "automatic review-fix cycle limit exhausted"
+    automation_die "review-fix cycle limit exhausted"
+fi
+
+next_review_cycle=$((review_cycles + 1))
+coding_cycle="$(jq -er '.codingCycle // 0' "$workspace_file")"
+next_coding_cycle=$((coding_cycle + 1))
+jq \
+    --argjson reviewCycles "$next_review_cycle" \
+    --argjson codingCycle "$next_coding_cycle" \
+    --arg updatedAt "$(automation_now)" \
+    '.reviewCycles = $reviewCycles | .codingCycle = $codingCycle | .updatedAt = $updatedAt' \
+    "$workspace_file" | automation_record_json "$workspace_file"
+
+automation_transition_state "$task_id" "CHANGES_REQUESTED" "CODING" "orchestrator" "bounded reviewer feedback cycle $next_review_cycle started"