@frankzhang2026/opencode-android-orchestrator 0.1.0 → 0.3.0

package/templates/scripts/automation/acceptance-report.sh

@@ -0,0 +1,132 @@
+#!/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"
+
+contract="$(automation_contract_path "$task_id")"
+workspace_file="$(automation_workspace_path "$task_id")"
+origin_file="$(automation_origin_path "$task_id")"
+evidence_dir="$(automation_evidence_path "$task_id")"
+baseline_file="$evidence_dir/baseline.json"
+red_file="$evidence_dir/red.json"
+ready_file="$evidence_dir/ready.json"
+review_file="$evidence_dir/review.json"
+[[ -f "$workspace_file" && -f "$origin_file" && -f "$baseline_file" && -f "$red_file" && -f "$ready_file" && -f "$review_file" ]] || \
+    automation_die "acceptance evidence is incomplete"
+[[ "$(jq -er '.decision' "$review_file")" == "APPROVED" ]] || automation_die "latest independent review is not approved"
+red_exit_code="$(jq -er '.exitCode' "$red_file")"
+review_verification_exit_code="$(jq -er '.verificationExitCode' "$review_file")"
+[[ "$red_exit_code" -ne 0 ]] || automation_die "RED evidence does not contain a failing test result"
+[[ "$review_verification_exit_code" -eq 0 ]] || automation_die "independent review verification did not pass"
+
+recorded_task_root="$(automation_workspace_task_root "$workspace_file")"
+workspace_strategy="$(automation_workspace_strategy "$workspace_file")"
+source_root="$(jq -er '.sourceRoot' "$workspace_file")"
+original_branch="$(jq -er '.originalBranch' "$origin_file")"
+baseline_head="$(jq -er '.baselineHead' "$workspace_file")"
+original_head_current="$(git -C "$source_root" rev-parse "refs/heads/$original_branch")"
+original_branch_drifted=false
+if [[ "$original_head_current" != "$baseline_head" ]]; then
+    original_branch_drifted=true
+fi
+[[ "$(cd "$recorded_task_root" && pwd)" == "$AUTOMATION_ROOT" ]] || automation_die "acceptance report must run in the recorded task root"
+if [[ "$(jq -r '.repositoryLeaseRequired // false' "$workspace_file")" == "true" ]]; then
+    automation_require_repository_lease "$task_id" "$source_root" "$workspace_strategy"
+fi
+current_diff_sha="$(automation_worktree_diff_sha)"
+[[ "$current_diff_sha" == "$(jq -er '.diffSha256' "$ready_file")" ]] || automation_die "sealed diff changed after the quality gate"
+[[ "$current_diff_sha" == "$(jq -er '.diffSha256' "$review_file")" ]] || automation_die "sealed diff changed after independent review"
+automation_assert_planning_artifacts_sealed "$task_id" "$AUTOMATION_ROOT"
+
+"$SCRIPT_DIR/scope-gate.sh" "$task_id" >/dev/null
+changed_paths=()
+while IFS= read -r path; do
+    [[ -n "$path" ]] && changed_paths+=("$path")
+done < <(automation_product_changed_paths_at "$task_id" "$AUTOMATION_ROOT")
+changed_paths_json="$(printf '%s\n' "${changed_paths[@]}" | jq -Rsc 'split("\n") | map(select(length > 0))')"
+planning_artifacts_json="$(jq -c '[.planPath, .contractPath]' "$origin_file")"
+diff_stat="$(git -C "$AUTOMATION_ROOT" diff --stat HEAD --)"
+untracked_paths="$(git -C "$AUTOMATION_ROOT" ls-files --others --exclude-standard | LC_ALL=C sort)"
+
+sealed_diff="$evidence_dir/sealed.diff"
+{
+    git -C "$AUTOMATION_ROOT" diff --binary HEAD --
+    while IFS= read -r path; do
+        [[ -n "$path" ]] || continue
+        git -C "$AUTOMATION_ROOT" diff --binary --no-index -- /dev/null "$AUTOMATION_ROOT/$path" || [[ "$?" -eq 1 ]]
+    done <<< "$untracked_paths"
+} > "$sealed_diff"
+
+report_file="$evidence_dir/acceptance-report.json"
+jq -n \
+    --arg taskId "$task_id" \
+    --arg title "$(jq -er '.title' "$contract")" \
+    --arg generatedAt "$(automation_now)" \
+    --arg originalBranch "$original_branch" \
+    --arg originalHeadBeforeContract "$(jq -er '.originalHeadBeforeContract' "$origin_file")" \
+    --arg baselineHead "$baseline_head" \
+    --arg originalHeadCurrent "$original_head_current" \
+    --arg taskBranch "$(jq -er '.taskBranch' "$workspace_file")" \
+    --arg workspaceStrategy "$workspace_strategy" \
+    --arg taskRoot "$AUTOMATION_ROOT" \
+    --arg sealedDiffSha256 "$current_diff_sha" \
+    --arg diffStat "$diff_stat" \
+    --arg sealedDiffPath "$sealed_diff" \
+    --arg reviewSummary "$(jq -er '.summary' "$review_file")" \
+    --arg testPolicy "$(jq -er '.testPolicy' "$contract")" \
+    --arg testPolicyReason "$(jq -r '.testPolicyReason // "Not specified"' "$contract")" \
+    --argjson maxChangedFiles "$(jq -er '.maxChangedFiles' "$contract")" \
+    --argjson deviceTestsRequired "$(jq -r '.deviceTestsRequired' "$contract")" \
+    --argjson redExitCode "$red_exit_code" \
+    --argjson gateAttempts "$(jq -er '.gateAttempts' "$ready_file")" \
+    --argjson codingCycle "$(jq -er '.codingCycle' "$ready_file")" \
+    --argjson reviewVerificationExitCode "$review_verification_exit_code" \
+    --argjson changedPaths "$changed_paths_json" \
+    --argjson planningArtifacts "$planning_artifacts_json" \
+    --argjson originalBranchDrifted "$original_branch_drifted" \
+    --argjson allowedPaths "$(jq -c '.allowedPaths' "$contract")" \
+    --argjson acceptanceCriteria "$(jq -c '.acceptanceCriteria' "$contract")" \
+    --argjson nonGoals "$(jq -c '.nonGoals' "$contract")" \
+    --argjson targetTests "$(jq -c '.targetTests' "$contract")" \
+    '{taskId: $taskId, title: $title, state: "AWAITING_HUMAN",
+      generatedAt: $generatedAt, originalBranch: $originalBranch,
+      originalHeadBeforeContract: $originalHeadBeforeContract,
+      baselineHead: $baselineHead, originalHeadCurrent: $originalHeadCurrent,
+      originalBranchDrifted: $originalBranchDrifted, taskBranch: $taskBranch,
+      taskBranchCleanupPolicy: "deleteAfterSuccessfulIntegration",
+      workspaceStrategy: $workspaceStrategy, taskRoot: $taskRoot,
+      sealedDiffSha256: $sealedDiffSha256,
+      changedPaths: $changedPaths, maxChangedFiles: $maxChangedFiles,
+      planningArtifacts: $planningArtifacts,
+      planningArtifactsCommitPolicy: "withProductChanges",
+      allowedPaths: $allowedPaths, diffStat: $diffStat,
+      sealedDiffPath: $sealedDiffPath, acceptanceCriteria: $acceptanceCriteria,
+      nonGoals: $nonGoals, targetTests: $targetTests,
+      testPolicy: $testPolicy, testPolicyReason: $testPolicyReason,
+      deviceTestsRequired: $deviceTestsRequired,
+      evidence: {
+        baselineRecorded: true,
+        redRecorded: true,
+        redExitCode: $redExitCode,
+        qualityGate: "PASSED",
+        gateAttempts: $gateAttempts,
+        codingCycle: $codingCycle,
+        reviewerDecision: "APPROVED",
+        reviewerVerificationExitCode: $reviewVerificationExitCode
+      },
+      bindingChecks: {
+        state: "VERIFIED",
+        sealedDiffMatchesReady: true,
+        sealedDiffMatchesReview: true
+      },
+      reviewSummary: $reviewSummary, pushed: false}' \
+    | automation_record_json "$report_file"
+
+jq . "$report_file"

package/templates/scripts/automation/approve-and-run.sh

@@ -0,0 +1,175 @@
+#!/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 "CONTRACT-APPROVAL"\n' "$0" >&2
+    exit 2
+fi
+
+automation_validate_task_id "$task_id"
+automation_require_orchestrated
+automation_require_approval contract "$approval"
+"$SCRIPT_DIR/validate-contract.sh" "$task_id" >/dev/null
+[[ "$(automation_read_state "$task_id")" == "CONTRACT_REVIEW" ]] || automation_die "$task_id is not awaiting contract review"
+
+origin_file="$(automation_origin_path "$task_id")"
+[[ -f "$origin_file" ]] || automation_die "origin evidence is missing"
+source_root="$(jq -er '.sourceRoot' "$origin_file")"
+original_branch="$(jq -er '.originalBranch' "$origin_file")"
+original_head="$(jq -er '.originalHeadBeforeContract' "$origin_file")"
+contract_rel="$(jq -er '.contractPath' "$origin_file")"
+plan_rel="$(jq -er '.planPath' "$origin_file")"
+contract="$source_root/$contract_rel"
+plan="$source_root/$plan_rel"
+
+[[ "$source_root" == "$AUTOMATION_ROOT" ]] || automation_die "approval must run from the recorded source worktree"
+[[ "$(automation_current_branch "$source_root")" == "$original_branch" ]] || automation_die "original branch changed after contract review began"
+[[ "$(git -C "$source_root" rev-parse HEAD)" == "$original_head" ]] || automation_die "original HEAD changed after contract review began"
+[[ "$(automation_file_sha256 "$contract")" == "$(jq -er '.contractSha256' "$origin_file")" ]] || automation_die "contract changed after proposal approval"
+[[ "$(automation_file_sha256 "$plan")" == "$(jq -er '.planSha256' "$origin_file")" ]] || automation_die "plan changed after proposal approval"
+
+changed_paths=()
+while IFS= read -r path; do
+    [[ -n "$path" ]] && changed_paths+=("$path")
+done < <(automation_changed_paths_at "$source_root")
+if [[ "${#changed_paths[@]}" -ne 2 ]] || \
+   [[ " ${changed_paths[*]} " != *" $contract_rel "* ]] || \
+   [[ " ${changed_paths[*]} " != *" $plan_rel "* ]]; then
+    automation_die "contract approval requires exactly the sealed plan and contract changes"
+fi
+for planning_path in "$plan_rel" "$contract_rel"; do
+    if git -C "$source_root" ls-files --error-unmatch -- "$planning_path" >/dev/null 2>&1; then
+        automation_die "planning artifact must remain a new untracked file until the combined task commit: $planning_path"
+    fi
+done
+
+automation_require_command git
+automation_require_command jq
+automation_require_command shasum
+if [[ "${AUTOMATION_TEST_MODE:-0}" != "1" ]]; then
+    automation_require_command opencode
+    [[ -n "${ANDROID_HOME:-}" ]] || automation_die "ANDROID_HOME is not set; export it before approving the contract"
+    [[ -d "$ANDROID_HOME" ]] || automation_die "ANDROID_HOME does not exist: $ANDROID_HOME"
+fi
+git -C "$source_root" config user.name >/dev/null || automation_die "Git user.name is not configured"
+git -C "$source_root" config user.email >/dev/null || automation_die "Git user.email is not configured"
+
+workspace_strategy="$(automation_config_value '.workspaceStrategy')"
+worktree_base=""
+task_slug="$(tr '[:upper:]' '[:lower:]' <<< "$task_id")"
+task_branch="$(automation_task_branch "$task_id")"
+task_root="$source_root"
+if [[ "$workspace_strategy" == "isolatedWorktree" ]]; then
+    worktree_base="$(automation_worktree_base)"
+    task_root="$worktree_base/$task_slug"
+    [[ ! -e "$task_root" ]] || automation_die "task worktree path already exists: $task_root"
+fi
+if git -C "$source_root" show-ref --verify --quiet "refs/heads/$task_branch"; then
+    automation_die "task branch already exists: $task_branch"
+fi
+
+automation_acquire_run_lock "$task_id"
+preparation_complete=0
+lease_acquired=0
+workspace_materialized=0
+approval_exit() {
+    local exit_code=$?
+    trap - EXIT
+    if [[ "$preparation_complete" != "1" ]] && [[ -f "$(automation_state_path "$task_id")" ]] && \
+       [[ "$(automation_read_state "$task_id" 2>/dev/null || true)" == "PREPARING" ]]; then
+        automation_transition_state "$task_id" "PREPARING" "BLOCKED" "orchestrator" "task workspace preparation failed" || true
+    fi
+    if [[ "$lease_acquired" == "1" && "$workspace_materialized" != "1" ]]; then
+        automation_release_repository_lease "$task_id" || true
+    fi
+    automation_release_run_lock
+    exit "$exit_code"
+}
+trap approval_exit EXIT
+
+automation_acquire_repository_lease "$task_id" "$source_root" "$workspace_strategy"
+lease_acquired=1
+
+jq -nc \
+    --arg taskId "$task_id" \
+    --arg kind "contract" \
+    --arg at "$(automation_now)" \
+    --arg originalBranch "$original_branch" \
+    --arg originalHead "$original_head" \
+    --arg contractSha256 "$(automation_file_sha256 "$contract")" \
+    '{taskId: $taskId, kind: $kind, at: $at, originalBranch: $originalBranch,
+      originalHead: $originalHead, contractSha256: $contractSha256,
+      planningArtifactsCommitPolicy: "withProductChanges"}' \
+    | automation_append_json "$(automation_approvals_path "$task_id")"
+
+baseline_head="$original_head"
+
+jq \
+    --arg approvedAt "$(automation_now)" \
+    --arg baselineHead "$baseline_head" \
+    '.approvedAt = $approvedAt |
+     .baselineHead = $baselineHead |
+     .planningArtifactsCommitPolicy = "withProductChanges" |
+     .contractCommit = null' \
+    "$origin_file" | automation_record_json "$origin_file"
+
+automation_transition_state "$task_id" "CONTRACT_REVIEW" "APPROVED_CONTRACT" "human" "sealed contract explicitly approved"
+automation_transition_state "$task_id" "APPROVED_CONTRACT" "PREPARING" "orchestrator" "preparing transactional task workspace"
+
+if [[ "$workspace_strategy" == "inPlaceExclusive" ]]; then
+    git -C "$source_root" switch -c "$task_branch" "$baseline_head"
+else
+    mkdir -p "$worktree_base"
+    git -C "$source_root" worktree add "$task_root" -b "$task_branch" "$baseline_head"
+    mkdir -p "$(dirname "$task_root/$plan_rel")" "$(dirname "$task_root/$contract_rel")"
+    cp "$plan" "$task_root/$plan_rel"
+    cp "$contract" "$task_root/$contract_rel"
+    [[ "$(automation_file_sha256 "$task_root/$plan_rel")" == "$(jq -er '.planSha256' "$origin_file")" ]] || \
+        automation_die "isolated task plan transfer changed its sealed content"
+    [[ "$(automation_file_sha256 "$task_root/$contract_rel")" == "$(jq -er '.contractSha256' "$origin_file")" ]] || \
+        automation_die "isolated task contract transfer changed its sealed content"
+    rm -f "$plan" "$contract"
+    automation_worktree_is_clean "$source_root" || automation_die "source worktree is not clean after moving planning artifacts to the isolated task root"
+fi
+workspace_materialized=1
+automation_assert_planning_artifacts_sealed "$task_id" "$task_root"
+materialized_paths=()
+while IFS= read -r path; do
+    [[ -n "$path" ]] && materialized_paths+=("$path")
+done < <(automation_changed_paths_at "$task_root")
+if [[ "${#materialized_paths[@]}" -ne 2 ]] || \
+   [[ " ${materialized_paths[*]} " != *" $contract_rel "* ]] || \
+   [[ " ${materialized_paths[*]} " != *" $plan_rel "* ]]; then
+    automation_die "prepared task root must contain only the sealed, uncommitted plan and contract"
+fi
+workspace_file="$(automation_workspace_path "$task_id")"
+jq -n \
+    --arg taskId "$task_id" \
+    --arg sourceRoot "$source_root" \
+    --arg originalBranch "$original_branch" \
+    --arg baselineHead "$baseline_head" \
+    --arg workspaceStrategy "$workspace_strategy" \
+    --arg taskRoot "$task_root" \
+    --arg taskBranch "$task_branch" \
+    --arg worktreeBase "$worktree_base" \
+    --arg createdAt "$(automation_now)" \
+    '{taskId: $taskId, sourceRoot: $sourceRoot, originalBranch: $originalBranch,
+      baselineHead: $baselineHead, workspaceStrategy: $workspaceStrategy,
+      taskRoot: $taskRoot, repositoryLeaseRequired: true,
+      planningArtifactsCommitPolicy: "withProductChanges",
+      taskBranch: $taskBranch, worktreeBase: $worktreeBase,
+      codingCycle: 0, reviewCycles: 0, createdAt: $createdAt}' \
+    | automation_record_json "$workspace_file"
+
+automation_transition_state "$task_id" "PREPARING" "PENDING" "orchestrator" "$workspace_strategy task workspace prepared and queued"
+preparation_complete=1
+automation_release_run_lock
+trap - EXIT
+
+"$SCRIPT_DIR/orchestrate-task.sh" "$task_id"

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

@@ -0,0 +1,18 @@
+#!/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")" == "READY_FOR_REVIEW" ]] || automation_die "$task_id is not READY_FOR_REVIEW"
+
+ready_file="$(automation_evidence_path "$task_id")/ready.json"
+[[ -f "$ready_file" ]] || automation_die "ready evidence is missing"
+current_diff_sha="$(automation_worktree_diff_sha)"
+[[ "$current_diff_sha" == "$(jq -er '.diffSha256' "$ready_file")" ]] || automation_die "diff changed after quality gate"
+
+automation_transition_state "$task_id" "READY_FOR_REVIEW" "REVIEWING" "orchestrator" "sealed diff handed to a fresh read-only reviewer"

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

@@ -0,0 +1,26 @@
+#!/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:-}"
+shift $(( $# >= 1 ? 1 : $# ))
+reason="$*"
+
+if [[ -z "$task_id" || ${#reason} -lt 12 ]]; then
+    printf 'Usage: %s TASK-ID REASON-OF-AT-LEAST-12-CHARACTERS\n' "$0" >&2
+    exit 2
+fi
+
+automation_validate_task_id "$task_id"
+current="$(automation_read_state "$task_id")"
+case "$current" in
+    PENDING|CODING)
+        automation_transition_state "$task_id" "$current" "BLOCKED" "coder" "$reason"
+        ;;
+    *)
+        automation_die "cannot block $task_id from state $current"
+        ;;
+esac

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

@@ -0,0 +1,74 @@
+#!/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
+
+[[ "$(automation_read_state "$task_id")" == "PENDING" ]] || automation_die "$task_id is not PENDING"
+evidence_dir="$(automation_evidence_path "$task_id")"
+mkdir -p "$evidence_dir"
+preflight_log="$evidence_dir/preflight.log"
+set +e
+"$SCRIPT_DIR/preflight.sh" "$task_id" 2>&1 | tee "$preflight_log"
+preflight_status=${PIPESTATUS[0]}
+set -e
+if [[ "$preflight_status" -ne 0 ]]; then
+    automation_transition_state "$task_id" "PENDING" "BLOCKED" "preflight" "preflight failed with exit $preflight_status"
+    automation_die "preflight failed; task moved to BLOCKED"
+fi
+
+automation_transition_state "$task_id" "PENDING" "CODING" "coder-launcher" "preflight passed; capturing baseline"
+
+baseline_log="$evidence_dir/baseline.log"
+baseline_meta="$evidence_dir/baseline.json"
+protected_hashes="$evidence_dir/protected.sha256"
+started_at="$(automation_now)"
+head_commit="$(git -C "$AUTOMATION_ROOT" rev-parse HEAD)"
+baseline_command="$(automation_gradle_group_command_json "fullUnitTestTasks")"
+
+set +e
+automation_run_gradle_group "fullUnitTestTasks" "$AUTOMATION_ROOT" 2>&1 | tee "$baseline_log"
+baseline_status=${PIPESTATUS[0]}
+set -e
+
+if [[ "$baseline_status" -ne 0 ]]; then
+    jq -n \
+        --arg taskId "$task_id" \
+        --arg startedAt "$started_at" \
+        --arg finishedAt "$(automation_now)" \
+        --arg head "$head_commit" \
+        --argjson command "$baseline_command" \
+        --argjson exitCode "$baseline_status" \
+        '{taskId: $taskId, startedAt: $startedAt, finishedAt: $finishedAt, head: $head, command: $command, exitCode: $exitCode}' \
+        | automation_record_json "$baseline_meta"
+    automation_transition_state "$task_id" "CODING" "BLOCKED" "preflight" "baseline unit tests failed"
+    automation_die "baseline unit tests failed"
+fi
+
+: > "$protected_hashes"
+while IFS= read -r tracked; do
+    while IFS= read -r protected; do
+        if automation_path_matches "$tracked" "$protected"; then
+            shasum -a 256 "$AUTOMATION_ROOT/$tracked" >> "$protected_hashes"
+            break
+        fi
+    done < <(jq -r '.protectedPaths[]' "$AUTOMATION_CONFIG")
+done < <(git -C "$AUTOMATION_ROOT" ls-files)
+
+jq -n \
+    --arg taskId "$task_id" \
+    --arg startedAt "$started_at" \
+    --arg finishedAt "$(automation_now)" \
+    --arg head "$head_commit" \
+    --arg worktree "$AUTOMATION_ROOT" \
+    --argjson command "$baseline_command" \
+    '{taskId: $taskId, startedAt: $startedAt, finishedAt: $finishedAt, head: $head, worktree: $worktree, command: $command, exitCode: 0}' \
+    | automation_record_json "$baseline_meta"
+
+automation_info "$task_id claimed; baseline is green"

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

@@ -0,0 +1,103 @@
+#!/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:-}"
+base="${2:-}"
+head="${3:-}"
+if [[ "$#" -ne 3 ]]; then
+    printf 'Usage: %s TASK-ID BASE-COMMIT HEAD-COMMIT\n' "$0" >&2
+    exit 2
+fi
+automation_validate_task_id "$task_id"
+git -C "$AUTOMATION_ROOT" cat-file -e "$base^{commit}" 2>/dev/null || automation_die "invalid integration base: $base"
+git -C "$AUTOMATION_ROOT" cat-file -e "$head^{commit}" 2>/dev/null || automation_die "invalid integration head: $head"
+"$SCRIPT_DIR/validate-contract.sh" "$task_id" >/dev/null
+
+contract="$(automation_contract_path "$task_id")"
+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
+    all_changed_file_list="$(automation_changed_paths_between "$base" "$head")"
+    origin_file="$(automation_origin_path "$task_id")"
+    contract_rel="$(jq -er '.contractPath' "$origin_file")"
+    plan_rel="$(jq -er '.planPath' "$origin_file")"
+    for planning_path in "$plan_rel" "$contract_rel"; do
+        if ! printf '%s\n' "$all_changed_file_list" | awk -v expected="$planning_path" '$0 == expected { found = 1 } END { exit !found }'; then
+            automation_die "integration candidate omitted approved planning artifact: $planning_path"
+            exit 40
+        fi
+    done
+    changed_file_list="$(automation_product_changed_paths_between "$task_id" "$base" "$head" "$AUTOMATION_ROOT")"
+else
+    changed_file_list="$(automation_changed_paths_between "$base" "$head")"
+fi
+[[ -n "$changed_file_list" ]] || { automation_die "integration candidate has no product changes"; exit 40; }
+
+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 "integration 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
+    if automation_array_matches_path "$AUTOMATION_CONFIG" '.protectedPaths' "$path"; then
+        automation_die "protected path changed in integration candidate: $path"
+        exit 40
+    fi
+    if automation_array_matches_path "$contract" '.forbiddenPaths' "$path"; then
+        automation_die "forbidden path changed in integration candidate: $path"
+        exit 40
+    fi
+    if ! automation_array_matches_path "$contract" '.allowedPaths' "$path"; then
+        automation_die "integration 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 "$base" "$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; }
+if [[ "$production_changed" == "1" && "$(jq -r '.testPolicy' "$contract")" == "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 "$base" "$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 integration candidate"
+    exit 40
+fi
+
+if [[ "$planning_commit_policy" == "withProductChanges" ]]; then
+    automation_info "integration scope gate passed ($changed_count product files plus the two sealed planning artifacts)"
+else
+    automation_info "integration scope gate passed ($changed_count changed files)"
+fi
+printf '%s\n' "$changed_file_list"