@frankzhang2026/opencode-android-orchestrator 0.1.0 → 0.3.0

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

@@ -0,0 +1,120 @@
+#!/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")"
+evidence_dir="$(automation_evidence_path "$task_id")"
+state_file="$(automation_state_path "$task_id")"
+ready_file="$evidence_dir/ready.json"
+transitions_file="$evidence_dir/transitions.jsonl"
+resumptions_file="$evidence_dir/review-resumptions.jsonl"
+
+[[ -f "$workspace_file" ]] || automation_die "workspace metadata is missing for $task_id"
+[[ -f "$state_file" ]] || automation_die "state is missing for $task_id"
+[[ -f "$evidence_dir/baseline.json" ]] || automation_die "baseline evidence is missing"
+[[ -f "$evidence_dir/red.json" ]] || automation_die "RED evidence is missing"
+[[ -f "$ready_file" ]] || automation_die "ready evidence is missing"
+[[ -f "$transitions_file" ]] || automation_die "transition evidence is missing"
+
+automation_acquire_run_lock "$task_id"
+trap 'automation_release_run_lock' EXIT
+
+[[ "$(automation_read_state "$task_id")" == "BLOCKED" ]] || automation_die "$task_id is not BLOCKED"
+
+task_root="$(automation_workspace_task_root "$workspace_file")"
+workspace_strategy="$(automation_workspace_strategy "$workspace_file")"
+source_root="$(jq -er '.sourceRoot' "$workspace_file")"
+source_root="$(jq -er '.sourceRoot' "$workspace_file")"
+task_branch="$(jq -er '.taskBranch' "$workspace_file")"
+baseline_head="$(jq -er '.baselineHead' "$workspace_file")"
+coding_cycle="$(jq -er '.codingCycle // 0' "$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
+task_root="$(cd "$task_root" && pwd -P)"
+source_root="$(cd "$source_root" && pwd -P)"
+[[ "$source_root" == "$AUTOMATION_ROOT" ]] || automation_die "workspace sourceRoot does not match this repository"
+[[ "$(automation_current_branch "$task_root")" == "$task_branch" ]] || automation_die "task branch changed"
+[[ "$(git -C "$task_root" rev-parse HEAD)" == "$baseline_head" ]] || automation_die "task HEAD changed after sealing"
+[[ "$(jq -er '.head' "$evidence_dir/baseline.json")" == "$baseline_head" ]] || automation_die "baseline evidence does not match workspace metadata"
+[[ "$(jq -er '.head' "$ready_file")" == "$baseline_head" ]] || automation_die "ready evidence does not match the baseline"
+[[ "$(jq -er '.codingCycle // 0' "$ready_file")" == "$coding_cycle" ]] || automation_die "ready evidence belongs to a different coding cycle"
+
+if ! jq -es -e '
+    ([to_entries[] |
+      select(.value.from == "REVIEWING" and
+             .value.to == "BLOCKED" and
+             .value.actor == "orchestrator" and
+             (.value.note | startswith("reviewer exited without submitting a decision")))] | last) as $failure
+    | ($failure != null) and
+      all(.[$failure.key + 1:][];
+          (.from == "BLOCKED" and .to == "PENDING" and .actor == "human") or
+          (.from == "PENDING" and .to == "BLOCKED" and
+           (.actor == "coder" or .actor == "preflight" or .actor == "orchestrator")))
+' "$transitions_file" >/dev/null; then
+    automation_die "BLOCKED state is not a recoverable reviewer interruption"
+fi
+
+ready_diff_sha="$(jq -er '.diffSha256' "$ready_file")"
+current_diff_sha="$(automation_worktree_diff_sha "$task_root")"
+[[ "$current_diff_sha" == "$ready_diff_sha" ]] || automation_die "sealed diff changed; reviewer-only recovery is forbidden"
+
+if [[ -f "$evidence_dir/reviews.jsonl" ]] &&
+   jq -es -e --arg sha "$ready_diff_sha" 'any(.[]; .diffSha256 == $sha)' "$evidence_dir/reviews.jsonl" >/dev/null; then
+    automation_die "a reviewer decision already exists for the sealed diff"
+fi
+if [[ -f "$evidence_dir/review.json" ]] &&
+   jq -e --arg sha "$ready_diff_sha" '.diffSha256 == $sha' "$evidence_dir/review.json" >/dev/null; then
+    automation_die "a reviewer decision already exists for the sealed diff"
+fi
+
+restart_count=0
+if [[ -f "$resumptions_file" ]]; then
+    restart_count="$(jq -s --arg sha "$ready_diff_sha" '[.[] | select(.diffSha256 == $sha)] | length' "$resumptions_file")"
+fi
+max_restarts="$(automation_config_value '.maxReviewerRestarts')"
+[[ "$restart_count" -lt "$max_restarts" ]] || automation_die "reviewer restart limit exhausted for the sealed diff"
+next_restart=$((restart_count + 1))
+
+(
+    cd "$task_root"
+    ./scripts/automation/scope-gate.sh "$task_id" >/dev/null
+)
+
+blocked_revision="$(jq -er '.revision' "$state_file")"
+automation_transition_state \
+    "$task_id" \
+    "BLOCKED" \
+    "REVIEWING" \
+    "human" \
+    "reviewer-only recovery $next_restart/$max_restarts; sealed diff preserved and coder bypassed"
+
+jq -nc \
+    --arg taskId "$task_id" \
+    --arg at "$(automation_now)" \
+    --arg diffSha256 "$ready_diff_sha" \
+    --argjson blockedRevision "$blocked_revision" \
+    --argjson restart "$next_restart" \
+    --argjson maxRestarts "$max_restarts" \
+    --argjson codingCycle "$coding_cycle" \
+    '{taskId: $taskId, at: $at, diffSha256: $diffSha256,
+      blockedRevision: $blockedRevision, restart: $restart,
+      maxRestarts: $maxRestarts, codingCycle: $codingCycle,
+      route: "BLOCKED->REVIEWING", coderRerun: false}' \
+    | automation_append_json "$resumptions_file"
+
+automation_info "$task_id reviewer-only recovery accepted; sealed diff $ready_diff_sha"
+automation_release_run_lock
+trap - EXIT
+
+"$SCRIPT_DIR/orchestrate-task.sh" "$task_id"

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

@@ -0,0 +1,110 @@
+#!/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"
+"$SCRIPT_DIR/validate-contract.sh" "$task_id" >/dev/null
+
+contract="$(automation_contract_path "$task_id")"
+evidence_dir="$(automation_evidence_path "$task_id")"
+baseline_meta="$evidence_dir/baseline.json"
+[[ -f "$baseline_meta" ]] || { automation_die "baseline evidence is missing"; exit 40; }
+
+baseline_head="$(jq -er '.head' "$baseline_meta")"
+current_head="$(git -C "$AUTOMATION_ROOT" rev-parse HEAD)"
+[[ "$baseline_head" == "$current_head" ]] || { automation_die "HEAD changed after baseline"; exit 40; }
+
+workspace_file="$(automation_workspace_path "$task_id")"
+planning_commit_policy="$(jq -r '.planningArtifactsCommitPolicy // "legacyCommittedSeparately"' "$workspace_file")"
+if [[ "$planning_commit_policy" == "withProductChanges" ]]; then
+    automation_assert_planning_artifacts_sealed "$task_id" "$AUTOMATION_ROOT" || exit 40
+    changed_file_list="$(automation_product_changed_paths_at "$task_id" "$AUTOMATION_ROOT")"
+    [[ -n "$changed_file_list" ]] || { automation_die "task has no product changes beyond its sealed planning artifacts"; exit 40; }
+else
+    changed_file_list="$(automation_changed_paths)"
+    [[ -n "$changed_file_list" ]] || { automation_die "task has no changed files"; exit 40; }
+fi
+
+max_changed="$(jq -r '.maxChangedFiles' "$contract")"
+changed_count="$(printf '%s\n' "$changed_file_list" | awk 'NF { count++ } END { print count + 0 }')"
+[[ "$changed_count" -le "$max_changed" ]] || { automation_die "changed file count $changed_count exceeds limit $max_changed"; exit 40; }
+
+production_changed=0
+test_changed=0
+while IFS= read -r path; do
+    [[ -n "$path" ]] || continue
+
+    while IFS= read -r protected; do
+        if automation_path_matches "$path" "$protected"; then
+            automation_die "protected path changed: $path"
+            exit 40
+        fi
+    done < <(jq -r '.protectedPaths[]' "$AUTOMATION_CONFIG")
+
+    if automation_array_matches_path "$contract" '.forbiddenPaths' "$path"; then
+        automation_die "forbidden path changed: $path"
+        exit 40
+    fi
+    if ! automation_array_matches_path "$contract" '.allowedPaths' "$path"; then
+        automation_die "path is outside allowedPaths: $path"
+        exit 40
+    fi
+
+    if automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.productionPaths' "$path"; then
+        production_changed=1
+    fi
+    if automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$path"; then
+        test_changed=1
+    fi
+done <<< "$changed_file_list"
+
+deleted_tests="$(
+    git -C "$AUTOMATION_ROOT" diff --name-only --diff-filter=D HEAD -- \
+        | while IFS= read -r path; do
+            if automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$path"; then
+                printf '%s\n' "$path"
+            fi
+        done
+)"
+[[ -z "$deleted_tests" ]] || { automation_die "test deletion is forbidden: $deleted_tests"; exit 40; }
+
+test_policy="$(jq -r '.testPolicy' "$contract")"
+if [[ "$production_changed" == "1" && "$test_policy" == "required" && "$test_changed" != "1" ]]; then
+    automation_die "production code changed without a test change"
+    exit 40
+fi
+
+added_test_lines="$(
+    while IFS= read -r path; do
+        [[ -n "$path" ]] || continue
+        if automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$path"; then
+            git -C "$AUTOMATION_ROOT" diff --unified=0 HEAD -- "$path"
+        fi
+    done <<< "$changed_file_list" \
+        | awk '/^\+\+\+/ { next } /^\+/ { sub(/^\+/, ""); print }'
+)"
+weakening_pattern='@Ignore|@Disabled|assumeTrue\(false\)|assertTrue\(true\)|assertFalse\(false\)'
+if printf '%s\n' "$added_test_lines" | rg -n "$weakening_pattern" >/dev/null; then
+    automation_die "potential test weakening detected in added lines"
+    exit 40
+fi
+
+while IFS= read -r untracked_test; do
+    if automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$untracked_test" && \
+        rg -n "$weakening_pattern" "$AUTOMATION_ROOT/$untracked_test" >/dev/null; then
+        automation_die "potential test weakening detected in new test: $untracked_test"
+        exit 40
+    fi
+done < <(git -C "$AUTOMATION_ROOT" ls-files --others --exclude-standard)
+
+if [[ "$planning_commit_policy" == "withProductChanges" ]]; then
+    automation_info "scope gate passed ($changed_count product files; sealed planning artifacts excluded from the contract limit)"
+else
+    automation_info "scope gate passed ($changed_count changed files)"
+fi
+printf '%s\n' "$changed_file_list"

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

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib.sh
+source "$SCRIPT_DIR/lib.sh"
+
+wanted="${1:-}"
+case "$wanted" in
+    PENDING|READY_FOR_REVIEW|REVIEWING) ;;
+    *) printf 'Usage: %s PENDING|READY_FOR_REVIEW|REVIEWING\n' "$0" >&2; exit 2 ;;
+esac
+
+matches=()
+while IFS= read -r state_file; do
+    [[ -f "$state_file" ]] || continue
+    state="$(jq -er '.state' "$state_file" 2>/dev/null || true)"
+    task_id="$(jq -er '.taskId' "$state_file" 2>/dev/null || true)"
+    if [[ "$state" == "$wanted" && "$task_id" =~ ^TASK-[A-Z0-9-]+$ ]]; then
+        matches+=("$task_id")
+    fi
+done < <(find "$AUTOMATION_STATE_DIR" -maxdepth 1 -type f -name 'TASK-*.json' | LC_ALL=C sort)
+
+if [[ "${#matches[@]}" -eq 0 ]]; then
+    automation_info "no task is in state $wanted"
+    exit 3
+fi
+if [[ "${#matches[@]}" -ne 1 ]]; then
+    automation_die "expected one $wanted task, found ${#matches[@]}: ${matches[*]}"
+    exit 4
+fi
+
+"$SCRIPT_DIR/validate-contract.sh" "${matches[0]}" >/dev/null
+printf '%s\n' "${matches[0]}"

package/templates/scripts/automation/shadow-run.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib.sh
+source "$SCRIPT_DIR/lib.sh"
+
+automation_info "starting read-only shadow preflight" >&2
+"$SCRIPT_DIR/preflight.sh" --shadow >&2
+
+task_count="$(find "$AUTOMATION_TASKS_DIR" -maxdepth 1 -type f -name 'TASK-*.json' | wc -l | tr -d ' ')"
+automation_ensure_runtime_layout
+state_count="$(find "$AUTOMATION_STATE_DIR" -maxdepth 1 -type f -name 'TASK-*.json' | wc -l | tr -d ' ')"
+
+jq -n \
+    --arg checkedAt "$(automation_now)" \
+    --arg root "$AUTOMATION_ROOT" \
+    --arg enabled "$(automation_config_value '.enabled')" \
+    --arg mode "$(automation_config_value '.mode')" \
+    --argjson taskCount "$task_count" \
+    --argjson stateCount "$state_count" \
+    '{checkedAt: $checkedAt, root: $root, enabled: ($enabled == "true"), mode: $mode, activeContracts: $taskCount, runtimeStates: $stateCount, mutationPerformed: false}'
+
+automation_info "shadow run complete; no repository mutation performed" >&2

package/templates/scripts/automation/show-acceptance-review.sh

@@ -0,0 +1,111 @@
+#!/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")" == "AWAITING_HUMAN" ]] || automation_die "$task_id is not AWAITING_HUMAN"
+
+workspace_file="$(automation_workspace_path "$task_id")"
+evidence_dir="$(automation_evidence_path "$task_id")"
+ready_file="$evidence_dir/ready.json"
+review_file="$evidence_dir/review.json"
+report_file="$evidence_dir/acceptance-report.json"
+[[ -f "$workspace_file" && -f "$ready_file" && -f "$review_file" ]] || \
+    automation_die "acceptance evidence is incomplete"
+
+task_root="$(automation_workspace_task_root "$workspace_file")"
+[[ -d "$task_root" ]] || automation_die "recorded task root is missing: $task_root"
+source_root="$(jq -er '.sourceRoot' "$workspace_file")"
+original_branch="$(jq -er '.originalBranch' "$workspace_file")"
+live_original_head="$(git -C "$source_root" rev-parse "refs/heads/$original_branch")"
+
+if [[ ! -f "$report_file" ]] || \
+   [[ "$(jq -r '.originalHeadCurrent // ""' "$report_file" 2>/dev/null || true)" != "$live_original_head" ]]; then
+    (
+        cd "$task_root"
+        ./scripts/automation/acceptance-report.sh "$task_id" >/dev/null
+    )
+fi
+
+[[ "$(jq -er '.taskId' "$report_file")" == "$task_id" ]] || automation_die "acceptance report task ID does not match"
+[[ "$(jq -er '.state' "$report_file")" == "AWAITING_HUMAN" ]] || automation_die "acceptance report is not awaiting human review"
+[[ "$(jq -er '.decision' "$review_file")" == "APPROVED" ]] || automation_die "latest independent review is not approved"
+
+current_diff_sha="$(automation_worktree_diff_sha "$task_root")"
+report_diff_sha="$(jq -er '.sealedDiffSha256' "$report_file")"
+[[ "$current_diff_sha" == "$report_diff_sha" ]] || automation_die "sealed diff changed after the acceptance package was generated"
+[[ "$current_diff_sha" == "$(jq -er '.diffSha256' "$ready_file")" ]] || automation_die "sealed diff no longer matches the quality gate"
+[[ "$current_diff_sha" == "$(jq -er '.diffSha256' "$review_file")" ]] || automation_die "sealed diff no longer matches independent review"
+
+changed_count="$(jq -er '.changedPaths | length' "$report_file")"
+max_changed_files="$(jq -er '.maxChangedFiles' "$report_file")"
+device_tests_required="$(jq -r '.deviceTestsRequired' "$report_file")"
+
+printf '# 🔔 人工验收提醒\n\n'
+printf '自动执行已停在 `AWAITING_HUMAN`。下面内容已重新核对 sealed diff；此时代码、计划与任务合同均尚未提交或集成。\n\n'
+printf '| 绑定项 | 当前封存值 |\n'
+printf '| --- | --- |\n'
+printf '| 任务 | `%s` · %s |\n' "$task_id" "$(jq -r '.title' "$report_file")"
+printf '| 原分支 | `%s` |\n' "$(jq -r '.originalBranch' "$report_file")"
+printf '| 原分支当前 HEAD | `%s` |\n' "$(jq -r '.originalHeadCurrent' "$report_file")"
+printf '| 原分支漂移 | `%s` |\n' "$(jq -r 'if .originalBranchDrifted then "是（集成将阻断）" else "否" end' "$report_file")"
+printf '| 任务分支收尾 | 成功集成后自动删除；失败或阻塞时保留 |\n'
+printf '| sealed diff SHA | `%s` |\n' "$report_diff_sha"
+printf '| 变更范围 | 实际 %s 个 / 合同上限 %s 个 |\n' "$changed_count" "$max_changed_files"
+printf '| 提交策略 | 代码、测试、计划与任务合同合并为一个提交 |\n'
+printf '| 自动证据 | Baseline ✓ · RED ✓ · G1–G6 ✓ · Reviewer APPROVED ✓ |\n'
+printf '\n## 必须重点复核\n\n'
+printf '### P0 · 真实行为是否满足合同\n\n'
+printf '这是人工验收的核心；请按以下条件实际操作或检查结果，不要只看测试为绿：\n\n'
+jq -r '.acceptanceCriteria | to_entries[] | "\(.key + 1). \(.value)"' "$report_file"
+
+printf '\n### P0 · 旧行为与范围是否被误伤\n\n'
+printf '**实际变更文件：**\n\n'
+jq -r '.changedPaths[] | "- `\(.)`"' "$report_file"
+printf '\n**随产品变更一并提交的封存规划文件（不计入合同文件上限）：**\n\n'
+jq -r '.planningArtifacts[] | "- `\(.)`"' "$report_file"
+printf '\n**合同允许路径：**\n\n'
+jq -r '.allowedPaths[] | "- `\(.)`"' "$report_file"
+printf '\n**明确不应发生：**\n\n'
+jq -r '.nonGoals[] | "- \(.)"' "$report_file"
+
+printf '\n### P1 · 自动证据是否可信\n\n'
+printf -- '- RED 退出码：`%s`（应为非 0，证明测试先真实失败）\n' "$(jq -r '.evidence.redExitCode' "$report_file")"
+printf -- '- 质量门：`%s`，第 %s 个编码周期内共运行 %s 次\n' \
+    "$(jq -r '.evidence.qualityGate' "$report_file")" \
+    "$(jq -r '.evidence.codingCycle' "$report_file")" \
+    "$(jq -r '.evidence.gateAttempts' "$report_file")"
+printf -- '- Reviewer：`%s`，独立复验退出码 `%s`\n' \
+    "$(jq -r '.evidence.reviewerDecision' "$report_file")" \
+    "$(jq -r '.evidence.reviewerVerificationExitCode' "$report_file")"
+printf -- '- Reviewer 摘要：%s\n' "$(jq -r '.reviewSummary' "$report_file")"
+printf -- '- 聚焦测试：\n'
+jq -r '.targetTests[] | "  - `./gradlew \(.gradleTask) --tests \(.filter)`"' "$report_file"
+
+printf '\n### P1 · 绑定与剩余风险\n\n'
+printf -- '- 当前 diff 与质量门、独立 Review、验收包的 SHA 三方一致。\n'
+printf -- '- 目标接收分支是 `%s`；通过后只做本地集成，`pushed: false`。\n' "$(jq -r '.originalBranch' "$report_file")"
+printf -- '- 原分支安全到达已验证提交后，本地任务分支 `%s` 将被自动删除；集成失败时保留以便恢复。\n' \
+    "$(jq -r '.taskBranch' "$report_file")"
+if [[ "$(jq -r '.originalBranchDrifted' "$report_file")" == "true" ]]; then
+    printf -- '- **原分支已偏离批准基线；当前策略会进入 `INTEGRATION_BLOCKED`，不会自动 cherry-pick。**\n'
+fi
+if [[ "$device_tests_required" == "true" ]]; then
+    printf -- '- 合同要求设备测试，自动质量门已执行；仍应人工确认真机/模拟器上的可观察体验。\n'
+else
+    printf -- '- 合同未要求设备测试。如果变更涉及 UI、系统权限或真机差异，请在通过前补做人工体验。\n'
+fi
+printf -- '- 测试策略：`%s`。%s\n' \
+    "$(jq -r '.testPolicy' "$report_file")" \
+    "$(jq -r '.testPolicyReason' "$report_file")"
+
+printf '\n## 你的决定\n\n'
+printf -- '- 全部重点通过：选择 **验收通过，提交到原分支。**\n'
+printf -- '- 任一项不通过：选择 **验收不通过，需要说明失败项**，并指出失败的验收条件或观察结果。\n'
+printf -- '- 还未检查完：选择 **暂不决定，保持封存**；系统继续停在 `AWAITING_HUMAN`。\n'
+printf '\n> 不要修改已封存的任务目录后沿用本次验收；diff 一旦变化，脚本会拒绝旧验收。\n'

package/templates/scripts/automation/status.sh

@@ -0,0 +1,125 @@
+#!/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_require_layout
+
+contract="$(automation_contract_path "$task_id")"
+state_file="$(automation_state_path "$task_id")"
+workspace_file="$(automation_workspace_path "$task_id")"
+origin_file="$(automation_origin_path "$task_id")"
+evidence_dir="$(automation_evidence_path "$task_id")"
+
+state_json="$(if [[ -f "$state_file" ]]; then jq -c . "$state_file"; else printf 'null'; fi)"
+workspace_json="$(if [[ -f "$workspace_file" ]]; then jq -c . "$workspace_file"; else printf 'null'; fi)"
+origin_json="$(if [[ -f "$origin_file" ]]; then jq -c . "$origin_file"; else printf 'null'; fi)"
+baseline_json="$(if [[ -f "$evidence_dir/baseline.json" ]]; then jq -c . "$evidence_dir/baseline.json"; else printf 'null'; fi)"
+red_json="$(if [[ -f "$evidence_dir/red.json" ]]; then jq -c . "$evidence_dir/red.json"; else printf 'null'; fi)"
+ready_json="$(if [[ -f "$evidence_dir/ready.json" ]]; then jq -c . "$evidence_dir/ready.json"; else printf 'null'; fi)"
+review_json="$(if [[ -f "$evidence_dir/review.json" ]]; then jq -c . "$evidence_dir/review.json"; else printf 'null'; fi)"
+gate_json=null
+if [[ "$ready_json" != "null" ]]; then
+    coding_cycle="$(jq -r '.codingCycle // 0' <<< "$ready_json")"
+    gate_file="$evidence_dir/gate-attempts-cycle-$coding_cycle.json"
+    if [[ -f "$gate_file" ]]; then
+        gate_json="$(jq -c . "$gate_file")"
+    fi
+fi
+
+current_diff_sha=""
+lease_json=null
+lease_matches=null
+original_head_current=""
+original_branch_drifted=null
+task_branch_exists=null
+if [[ "$workspace_json" != "null" ]]; then
+    task_root="$(jq -r '.taskRoot // .taskWorktree // empty' <<< "$workspace_json")"
+    if [[ -n "$task_root" && -d "$task_root" ]]; then
+        current_diff_sha="$(automation_worktree_diff_sha "$task_root")"
+    fi
+    source_root="$(jq -r '.sourceRoot // empty' <<< "$workspace_json")"
+    original_branch="$(jq -r '.originalBranch // empty' <<< "$workspace_json")"
+    task_branch="$(jq -r '.taskBranch // empty' <<< "$workspace_json")"
+    baseline_head="$(jq -r '.baselineHead // empty' <<< "$workspace_json")"
+    if [[ -n "$source_root" && -n "$task_branch" ]]; then
+        if git -C "$source_root" show-ref --verify --quiet "refs/heads/$task_branch"; then
+            task_branch_exists=true
+        else
+            task_branch_exists=false
+        fi
+    fi
+    if [[ -n "$source_root" && -n "$original_branch" ]] && \
+       git -C "$source_root" show-ref --verify --quiet "refs/heads/$original_branch"; then
+        original_head_current="$(git -C "$source_root" rev-parse "refs/heads/$original_branch")"
+        if [[ -n "$baseline_head" && "$original_head_current" != "$baseline_head" ]]; then
+            original_branch_drifted=true
+        else
+            original_branch_drifted=false
+        fi
+    fi
+    if [[ "$(jq -r '.repositoryLeaseRequired // false' <<< "$workspace_json")" == "true" ]]; then
+        lease_file="$(automation_repository_lease_dir)/lease.json"
+        if [[ -f "$lease_file" ]]; then
+            lease_json="$(jq -c . "$lease_file")"
+            if jq -e \
+                --arg taskId "$task_id" \
+                --arg sourceRoot "$source_root" \
+                --arg strategy "$(jq -r '.workspaceStrategy' <<< "$workspace_json")" \
+                '.taskId == $taskId and .sourceRoot == $sourceRoot and .workspaceStrategy == $strategy' \
+                "$lease_file" >/dev/null; then
+                lease_matches=true
+            else
+                lease_matches=false
+            fi
+        else
+            lease_matches=false
+        fi
+    fi
+fi
+
+[[ -f "$contract" ]] || automation_die "contract not found: $contract"
+jq -n \
+    --slurpfile contract "$contract" \
+    --argjson state "$state_json" \
+    --argjson workspace "$workspace_json" \
+    --argjson origin "$origin_json" \
+    --argjson baseline "$baseline_json" \
+    --argjson red "$red_json" \
+    --argjson ready "$ready_json" \
+    --argjson gate "$gate_json" \
+    --argjson review "$review_json" \
+    --argjson repositoryLease "$lease_json" \
+    --argjson repositoryLeaseMatches "$lease_matches" \
+    --argjson taskBranchExists "$task_branch_exists" \
+    --arg originalHeadCurrent "$original_head_current" \
+    --argjson originalBranchDrifted "$original_branch_drifted" \
+    --arg evidence "$evidence_dir" \
+    --arg currentDiffSha256 "$current_diff_sha" \
+    '{contract: $contract[0], state: $state, workspace: $workspace, origin: $origin,
+      runtime: {
+        repositoryLease: $repositoryLease,
+        repositoryLeaseMatches: $repositoryLeaseMatches,
+        taskBranchExists: $taskBranchExists,
+        originalHeadCurrent: ($originalHeadCurrent | if length == 0 then null else . end),
+        originalBranchDrifted: $originalBranchDrifted
+      },
+      evidenceDirectory: $evidence,
+      evidence: {
+        directory: $evidence,
+        baseline: $baseline,
+        red: $red,
+        ready: $ready,
+        latestGate: $gate,
+        review: $review,
+        currentDiffSha256: ($currentDiffSha256 | if length == 0 then null else . end),
+        sealedDiffMatches: (if ($ready == null or ($currentDiffSha256 | length) == 0)
+                            then null
+                            else $ready.diffSha256 == $currentDiffSha256
+                            end)
+      }}'

package/templates/scripts/automation/submit-review.sh

@@ -0,0 +1,73 @@
+#!/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:-}"
+decision="${2:-}"
+shift $(( $# >= 2 ? 2 : $# ))
+summary="$*"
+
+if [[ -z "$task_id" || -z "$decision" || -z "$summary" ]]; then
+    printf 'Usage: %s TASK-ID APPROVED|CHANGES_REQUESTED SUMMARY\n' "$0" >&2
+    exit 2
+fi
+
+automation_validate_task_id "$task_id"
+[[ "$decision" == "APPROVED" || "$decision" == "CHANGES_REQUESTED" ]] || automation_die "invalid review decision: $decision"
+[[ ${#summary} -ge 20 ]] || automation_die "review summary must contain at least 20 characters"
+[[ "$(automation_read_state "$task_id")" == "REVIEWING" ]] || automation_die "$task_id is not REVIEWING"
+
+evidence_dir="$(automation_evidence_path "$task_id")"
+ready_meta="$evidence_dir/ready.json"
+[[ -f "$ready_meta" ]] || automation_die "ready evidence is missing"
+current_diff_sha="$(automation_worktree_diff_sha)"
+ready_diff_sha="$(jq -er '.diffSha256' "$ready_meta")"
+
+if [[ "$current_diff_sha" != "$ready_diff_sha" ]]; then
+    decision="CHANGES_REQUESTED"
+    summary="Diff changed after coder gate. $summary"
+fi
+
+review_log="$evidence_dir/review-verification.log"
+verification_status=0
+if [[ "$decision" == "APPROVED" ]]; then
+    set +e
+    "$SCRIPT_DIR/verify-task.sh" "$task_id" 2>&1 | tee "$review_log"
+    verification_status=${PIPESTATUS[0]}
+    set -e
+    if [[ "$verification_status" -ne 0 ]]; then
+        decision="CHANGES_REQUESTED"
+        summary="Independent verification failed with exit $verification_status. $summary"
+    fi
+fi
+
+jq -n \
+    --arg taskId "$task_id" \
+    --arg decision "$decision" \
+    --arg summary "$summary" \
+    --arg reviewedAt "$(automation_now)" \
+    --arg diffSha256 "$current_diff_sha" \
+    --argjson verificationExitCode "$verification_status" \
+    '{taskId: $taskId, decision: $decision, summary: $summary, reviewedAt: $reviewedAt, diffSha256: $diffSha256, verificationExitCode: $verificationExitCode}' \
+    | automation_record_json "$evidence_dir/review.json"
+jq -nc \
+    --arg taskId "$task_id" \
+    --arg decision "$decision" \
+    --arg summary "$summary" \
+    --arg reviewedAt "$(automation_now)" \
+    --arg diffSha256 "$current_diff_sha" \
+    --argjson verificationExitCode "$verification_status" \
+    '{taskId: $taskId, decision: $decision, summary: $summary, reviewedAt: $reviewedAt, diffSha256: $diffSha256, verificationExitCode: $verificationExitCode}' \
+    | automation_append_json "$evidence_dir/reviews.jsonl"
+
+if [[ "$decision" == "APPROVED" ]]; then
+    automation_transition_state "$task_id" "REVIEWING" "AWAITING_HUMAN" "reviewer" "independent review approved; human acceptance required"
+    automation_info "$task_id approved and awaiting human acceptance"
+else
+    automation_transition_state "$task_id" "REVIEWING" "CHANGES_REQUESTED" "reviewer" "$summary"
+    automation_warn "$task_id requires changes"
+    exit 1
+fi