@frankzhang2026/opencode-android-orchestrator 1.0.4 → 1.0.5

package/docs/TROUBLESHOOTING.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 Use this guide for
-`@frankzhang2026/opencode-android-orchestrator@1.0.4`.
+`@frankzhang2026/opencode-android-orchestrator@1.0.5`.
 
 ## Start with read-only evidence
 
@@ -11,7 +11,7 @@ From the repository root, capture:
 git status --short --branch
 git rev-parse HEAD
 opencode --version
-npx @frankzhang2026/opencode-android-orchestrator@1.0.4 doctor . --json
+npx @frankzhang2026/opencode-android-orchestrator@1.0.5 doctor . --json
 ```
 
 If installation never completed, doctor will correctly report a missing or
@@ -39,9 +39,9 @@ command-scoped override:
 
 ```sh
 npm --registry=https://registry.npmjs.org/ view \
-  @frankzhang2026/opencode-android-orchestrator@1.0.4 version
+  @frankzhang2026/opencode-android-orchestrator@1.0.5 version
 npx --yes --registry=https://registry.npmjs.org/ \
-  @frankzhang2026/opencode-android-orchestrator@1.0.4 upgrade . --json
+  @frankzhang2026/opencode-android-orchestrator@1.0.5 upgrade . --json
 ```
 
 This leaves the company's saved npm configuration unchanged. Use the option
@@ -71,7 +71,7 @@ Git-backed Superpowers plugin at runtime.
 | Invalid `--long-command-timeout-ms` | The value is not an integer from `120000` through `7200000`. | Use the `1800000` ms default or pass an intentional bounded value to `init`/`upgrade`; do not edit the generated config directly. |
 | Android SDK failure | No valid explicit SDK, `ANDROID_HOME`, `ANDROID_SDK_ROOT`, or `local.properties` `sdk.dir` was found. | Configure one real SDK root containing `platforms/` and `build-tools/`. Do not publish `local.properties`. |
 | Missing `git`, `jq`, `rg`, `shasum`, or Java | Required deterministic command is unavailable on `PATH`. | Install or restore the missing command, record its version, and rerun the read-only checks. |
-| `Bundled Orchestrator skill is unavailable` | The installed `1.0.4` package is incomplete, damaged, or loaded from an unsupported partial copy. | Reinstall the exact package, inspect its `resources/third-party/superpowers-v6.2.0/skills/` entries, restart OpenCode, and rerun `opencode debug skill`. Do not add an external Superpowers plugin as a fallback. |
+| `Bundled Orchestrator skill is unavailable` | The installed `1.0.5` package is incomplete, damaged, or loaded from an unsupported partial copy. | Reinstall the exact package, inspect its `resources/third-party/superpowers-v6.2.0/skills/` entries, restart OpenCode, and rerun `opencode debug skill`. Do not add an external Superpowers plugin as a fallback. |
 | `current process does not own this task queue execution` immediately after Coder start on 1.0.1 | OpenCode created the tool shell in a separate process group, so 1.0.1 rejected a legitimate Worker descendant. | Upgrade to 1.0.2 or later, restart OpenCode, then use the approved resume or abort workflow for the retained task. Do not edit the queue or lease files. |
 | The exact Superpowers v6.2.0 plugin remains after upgrade | That entry existed in the verified pre-install OpenCode file and is therefore user-owned. | Leave it in place or remove it as a separate reviewed configuration change. Upgrade only removes the old Orchestrator-managed entry. |
 
@@ -88,7 +88,7 @@ silence of `./gradlew tasks --all --console=plain | rg ...` in a large build.
 For an existing installation, run:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@1.0.4 upgrade . \
+npx @frankzhang2026/opencode-android-orchestrator@1.0.5 upgrade . \
   --refresh-gradle-discovery
 ```
 
@@ -97,7 +97,7 @@ least `1800000` milliseconds. A higher timeout already supplied by the caller
 is preserved; unrelated Bash commands are unchanged. To configure one hour,
 run `upgrade . --long-command-timeout-ms 3600000` on a healthy installation.
 If a command still reports `120000 ms`, confirm that the project manifest and
-OpenCode plugin reference are both `1.0.4`, restart the OpenCode session so the
+OpenCode plugin reference are both `1.0.5`, restart the OpenCode session so the
 plugin reloads, and rerun doctor before attempting recovery.
 
 After installation, inspect OpenCode discovery separately:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frankzhang2026/opencode-android-orchestrator",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Reusable OpenCode orchestration for Android projects",
   "license": "MIT",
   "author": "frankzhang2026",

package/templates/.opencode/agents/scheduled-coder.md

@@ -109,6 +109,15 @@ literally. Do not infer missing requirements and do not ask questions during a
 non-interactive run. If anything is ambiguous or blocked, stop and report the exact
 reason; the deterministic scripts own state transitions.
 
+For schema V3 tasks, keep production code unchanged while adding the approved
+tests, then call `./scripts/automation/record-red.sh <TASK-ID>` with no model-
+chosen failure text. The script checks every declared case. A familiar exception
+name in a log is not sufficient RED. Fix a test-only preparation error only when
+the contract remains unchanged and its preparation budget allows it; rerun the
+preflight afterwards. Contract contradictions must be blocked with the reported
+case IDs and measured results. Never delete evidence or weaken, skip or reclassify
+a test to pass the preflight.
+
 You may edit only paths allowed both by this agent and by the task contract.
 Treat `.automation-worktree-allowlist` and the status JSON's
 `runtime.effectiveWorktreeAllowlist` paths as human-owned local state: never

package/templates/.opencode/agents/scheduled-planner.md

@@ -62,6 +62,16 @@ approval. After approval, assemble a complete plan and contract in memory and
 call `android_orchestrator_intake` with action `draft`; do not create files in the
 product checkout. Preserve the snapshot's target branch and planningHead.
 
+Use schema V3 structured verification. Give every verification case a stable ID,
+its one-based acceptance-criterion reference, its source, and its exact test
+identity. Classify preserved behavior as `before: pass`, changed behavior as
+`before: fail`, and an uncertain old boundary as `before: observe`. Do not infer
+exact serializer, parser, locale, date or framework output from declarations or
+memory. For preserved behavior, use an existing trusted test or explicitly mark
+the value for baseline capture. Plan examples are implementation guidance and
+must not add requirements beyond the contract. Check acceptance criteria,
+non-goals and verification expectations for contradictions before drafting.
+
 When the draft does not specify a workspace or commit policy, use the values in
 `automation/config.json`; new installations configure `inPlaceExclusive` and
 `humanApproval`. A user may explicitly override the commit policy to

package/templates/.opencode/skills/scheduled-quality-coder/SKILL.md

@@ -52,7 +52,13 @@ it with `./scripts/automation/block-task.sh <TASK-ID> <reason>` before stopping.
 
 4. On the initial coding cycle, add or change the smallest behavior test
    permitted by `allowedPaths`.
-5. If RED evidence does not already exist, capture a genuine RED result with:
+5. If RED evidence does not already exist, capture a genuine RED result. For a
+   schema V3 contract use:
+
+   `./scripts/automation/record-red.sh <TASK-ID>`
+
+   It checks every declared preserved, changed and observed case against fresh
+   structured output. For a legacy schema V1/V2 contract use:
 
    `./scripts/automation/record-red.sh <TASK-ID> <expected-failure-text> -- <test-filter>`
 

package/templates/.opencode/skills/scheduled-quality-reviewer/SKILL.md

@@ -38,6 +38,10 @@ you review.
 5. Check each acceptance criterion against observable behavior. Inspect for
    regression risk, missing edge cases, out-of-scope changes, test deletion,
    ignored tests, relaxed assertions, and implementation-shaped tests.
+   For schema V3, also verify every structured case source and identity, that
+   preserved cases passed before implementation, that changed cases failed only
+   for their declared reason, and that RED contains no undeclared failure. Treat
+   the Planner and Coder summaries as claims; use the bound preflight evidence.
 6. Decide independently:
 
    - approve only when the diff is correct and evidence is sufficient;

package/templates/automation/task-contract.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:frankzhang2026:opencode-android-orchestrator:task-contract:v2",
+  "$id": "urn:frankzhang2026:opencode-android-orchestrator:task-contract:v3",
   "title": "Scheduled coding task contract",
   "type": "object",
   "additionalProperties": false,
@@ -14,6 +14,63 @@
       "type": "string",
       "minLength": 1,
       "pattern": "^[A-Za-z0-9_.#$*-]+$"
+    },
+    "expectedFailure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "origin"],
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "messageIncludes": { "type": "string", "minLength": 3 },
+        "origin": { "type": "string", "minLength": 12 }
+      }
+    },
+    "verificationCase": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "criterion", "intent", "before", "after", "source", "test"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]{2,63}$" },
+        "criterion": { "type": "integer", "minimum": 1 },
+        "intent": { "enum": ["preserve", "change", "observe"] },
+        "before": { "enum": ["pass", "fail", "observe"] },
+        "after": { "const": "pass" },
+        "source": { "enum": ["userRequirement", "existingTest", "baselineCapture", "measuredFact"] },
+        "test": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["target", "className", "name"],
+          "properties": {
+            "target": { "type": "integer", "minimum": 0 },
+            "className": { "type": "string", "minLength": 1 },
+            "name": { "type": "string", "minLength": 1 }
+          }
+        },
+        "expectedFailure": { "$ref": "#/$defs/expectedFailure" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "intent": { "const": "preserve" } } },
+          "then": {
+            "properties": {
+              "before": { "const": "pass" },
+              "source": { "enum": ["existingTest", "baselineCapture", "measuredFact"] }
+            },
+            "not": { "required": ["expectedFailure"] }
+          }
+        },
+        {
+          "if": { "properties": { "intent": { "const": "change" } } },
+          "then": {
+            "properties": { "before": { "const": "fail" }, "source": { "const": "userRequirement" } },
+            "required": ["expectedFailure"]
+          }
+        },
+        {
+          "if": { "properties": { "intent": { "const": "observe" } } },
+          "then": { "properties": { "before": { "const": "observe" } } }
+        }
+      ]
     }
   },
   "required": [
@@ -32,10 +89,11 @@
     "nonGoals",
     "targetTests",
     "deviceTestsRequired",
-    "testPolicy"
+    "testPolicy",
+    "verification"
   ],
   "properties": {
-    "schemaVersion": { "const": 2 },
+    "schemaVersion": { "const": 3 },
     "id": { "type": "string", "pattern": "^TASK-[A-Z0-9-]+$" },
     "title": { "type": "string", "minLength": 1 },
     "designApproved": { "const": true },
@@ -87,6 +145,20 @@
     },
     "deviceTestsRequired": { "type": "boolean" },
     "testPolicy": { "enum": ["required", "not-required"] },
-    "testPolicyReason": { "type": "string" }
+    "testPolicyReason": { "type": "string" },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "maxPreparationFixes", "cases"],
+      "properties": {
+        "version": { "const": 1 },
+        "maxPreparationFixes": { "type": "integer", "minimum": 0, "maximum": 1 },
+        "cases": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/verificationCase" }
+        }
+      }
+    }
   }
 }

package/templates/automation/tasks/TASK-TEMPLATE.json.example

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "id": "TASK-EXAMPLE-001",
   "title": "Replace with one small, observable behavior change",
   "designApproved": true,
@@ -53,5 +53,28 @@
   ],
   "deviceTestsRequired": false,
   "testPolicy": "required",
-  "testPolicyReason": "Behavior changes require a focused regression test"
+  "testPolicyReason": "Behavior changes require a focused regression test",
+  "verification": {
+    "version": 1,
+    "maxPreparationFixes": 1,
+    "cases": [
+      {
+        "id": "FOCUSED-BEHAVIOR",
+        "criterion": 1,
+        "intent": "change",
+        "before": "fail",
+        "after": "pass",
+        "source": "userRequirement",
+        "test": {
+          "target": 0,
+          "className": "ReplaceWithFocusedTest",
+          "name": "replace with observable behavior"
+        },
+        "expectedFailure": {
+          "type": "java.lang.AssertionError",
+          "origin": "The assertion at the approved behavior call"
+        }
+      }
+    ]
+  }
 }

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

@@ -26,6 +26,16 @@ 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"
+structured_red=null
+if [[ "$(jq -er '.schemaVersion' "$contract")" == "3" ]]; then
+    preflight_file="$evidence_dir/test-preflight.json"
+    manifest_file="$evidence_dir/test-manifest.json"
+    [[ -f "$preflight_file" && -f "$manifest_file" ]] || automation_die "structured RED acceptance evidence is incomplete"
+    [[ "$(jq -er '.valid' "$preflight_file")" == "true" ]] || automation_die "structured RED preflight was not valid"
+    [[ "$(jq -er '.preflightSha256' "$red_file")" == "$(automation_file_sha256 "$preflight_file")" ]] || automation_die "structured RED preflight changed"
+    [[ "$(jq -er '.manifestSha256' "$red_file")" == "$(automation_file_sha256 "$manifest_file")" ]] || automation_die "structured RED manifest changed"
+    structured_red="$(jq -c '{valid, reasonCode, summary, cases: [.cases[] | {id, criterion, intent, expectedBefore, test, valid}]}' "$preflight_file")"
+fi
 
 recorded_task_root="$(automation_workspace_task_root "$workspace_file")"
 workspace_strategy="$(automation_workspace_strategy "$workspace_file")"
@@ -90,6 +100,7 @@ jq -n \
     --argjson acceptanceCriteria "$(jq -c '.acceptanceCriteria' "$contract")" \
     --argjson nonGoals "$(jq -c '.nonGoals' "$contract")" \
     --argjson targetTests "$(jq -c '.targetTests' "$contract")" \
+    --argjson structuredRed "$structured_red" \
     '{taskId: $taskId, title: $title, state: $state,
       generatedAt: $generatedAt, originalBranch: $originalBranch,
       originalHeadBeforeContract: $originalHeadBeforeContract,
@@ -110,6 +121,7 @@ jq -n \
         baselineRecorded: true,
         redRecorded: true,
         redExitCode: $redExitCode,
+        structuredRed: $structuredRed,
         qualityGate: "PASSED",
         gateAttempts: $gateAttempts,
         codingCycle: $codingCycle,

package/templates/scripts/automation/lib.sh

@@ -566,6 +566,114 @@ automation_run_focused_test() {
     )
 }
 
+# Run one focused target with fresh Test execution and machine-readable case
+# results. Test assertion failures are collected instead of failing Gradle so
+# the caller can distinguish approved RED from build and fixture failures.
+automation_run_classified_focused_test() {
+    local task="$1"
+    local filter="$2"
+    local root="$3"
+    local result_file="$4"
+    local log_file="$5"
+    local init_file status
+
+    automation_validate_config || return 1
+    automation_validate_gradle_task "$task" || return 1
+    automation_validate_test_filter "$filter" || return 1
+    jq -e --arg task "$task" \
+        '.gradleVerification.focusedTestTasks | index($task) != null' \
+        "$AUTOMATION_CONFIG" >/dev/null || {
+        automation_die "focused Gradle task is not allowed by automation/config.json: $task"
+        return 1
+    }
+
+    mkdir -p "$AUTOMATION_RUNTIME_ROOT/gradle" "$(dirname "$result_file")" "$(dirname "$log_file")"
+    init_file="$(mktemp "$AUTOMATION_RUNTIME_ROOT/gradle/classified-tests.XXXXXX")"
+    : > "$result_file"
+    cat > "$init_file" <<'GRADLE'
+import groovy.json.JsonOutput
+import org.gradle.api.tasks.testing.Test
+import org.gradle.api.tasks.testing.TestDescriptor
+import org.gradle.api.tasks.testing.TestListener
+import org.gradle.api.tasks.testing.TestResult
+
+def outputPath = System.getProperty('orchestrator.caseResultFile')
+if (outputPath == null || outputPath.isEmpty()) {
+    throw new GradleException('orchestrator.caseResultFile is required')
+}
+def outputFile = new File(outputPath)
+def appendResult = { Map value ->
+    synchronized (gradle) {
+        outputFile << JsonOutput.toJson(value) << System.lineSeparator()
+    }
+}
+
+gradle.allprojects { project ->
+    project.tasks.withType(Test).configureEach { testTask ->
+        outputs.upToDateWhen { false }
+        outputs.doNotCacheIf('Orchestrator requires fresh classified test execution') { true }
+        ignoreFailures = true
+        failFast = false
+        if (testTask.hasProperty('dryRun')) testTask.dryRun = false
+        addTestListener(new TestListener() {
+            void beforeSuite(TestDescriptor descriptor) {}
+            void beforeTest(TestDescriptor descriptor) {}
+            void afterTest(TestDescriptor descriptor, TestResult result) {
+                def failure = result.exceptions == null || result.exceptions.isEmpty() ? null : result.exceptions[0]
+                appendResult([
+                    kind: 'case', taskPath: testTask.path,
+                    className: descriptor.className ?: '', name: descriptor.name ?: '',
+                    result: result.resultType.toString(),
+                    exceptionType: failure == null ? null : failure.class.name,
+                    exceptionMessage: failure == null ? null : (failure.message ?: '')
+                ])
+            }
+            void afterSuite(TestDescriptor descriptor, TestResult result) {
+                if (descriptor.parent == null) {
+                    appendResult([
+                        kind: 'suite', taskPath: testTask.path,
+                        tests: result.testCount, failures: result.failedTestCount,
+                        skipped: result.skippedTestCount,
+                        result: result.resultType.toString()
+                    ])
+                }
+            }
+        })
+    }
+}
+GRADLE
+
+    set +e
+    (cd "$root" && ./gradlew "$task" --tests "$filter" \
+        --no-configuration-cache --console=plain --init-script "$init_file" \
+        "-Dorchestrator.caseResultFile=$result_file") 2>&1 | tee "$log_file"
+    status=${PIPESTATUS[0]}
+    set -e
+    rm -f "$init_file"
+    return "$status"
+}
+
+automation_test_diff_sha() {
+    local task_id="$1"
+    local root="${2:-$AUTOMATION_ROOT}"
+    local path tracked=0
+    {
+        while IFS= read -r path; do
+            [[ -n "$path" ]] || continue
+            if automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$path"; then
+                tracked=1
+                if git -C "$root" ls-files --error-unmatch -- "$path" >/dev/null 2>&1; then
+                    git -C "$root" diff --binary --no-renames HEAD -- "$path"
+                else
+                    printf 'UNTRACKED %s\0' "$path"
+                    git -C "$root" hash-object -- "$path"
+                fi
+            fi
+        done < <(automation_product_changed_paths_at "$task_id" "$root")
+        [[ "$tracked" == "1" ]] || printf 'NO-TEST-CHANGES'
+    } | shasum -a 256 | awk '{print $1}'
+}
+
 automation_require_approval() {
     local kind="$1"
     local supplied="$2"

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

@@ -6,51 +6,189 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 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
-
+[[ -n "$task_id" ]] || { printf 'Usage: %s TASK-ID [LEGACY-EXPECTED -- LEGACY-FILTER]\n' "$0" >&2; exit 2; }
 automation_validate_task_id "$task_id"
 automation_require_queue_execution "$task_id"
-automation_validate_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")"
-target_count="$(jq -er --arg filter "$filter" '[.targetTests[] | select(.filter == $filter)] | length' "$contract")"
-[[ "$target_count" -eq 1 ]] || automation_die "test filter must identify exactly one declared contract target: $filter"
-gradle_task="$(jq -er --arg filter "$filter" '.targetTests[] | select(.filter == $filter) | .gradleTask' "$contract")"
-
+schema_version="$(jq -er '.schemaVersion' "$contract")"
 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
-automation_run_focused_test "$gradle_task" "$filter" "$AUTOMATION_ROOT" 2>&1 | tee "$red_log"
-red_status=${PIPESTATUS[0]}
-set -e
+# Preserve the exact V1/V2 behavior for already approved contracts.
+if [[ "$schema_version" != "3" ]]; then
+    expected="${2:-}"
+    separator="${3:-}"
+    filter="${4:-}"
+    if [[ -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_test_filter "$filter"
+    [[ ${#expected} -ge 3 ]] || automation_die "expected failure text is too short"
+    target_count="$(jq -er --arg filter "$filter" '[.targetTests[] | select(.filter == $filter)] | length' "$contract")"
+    [[ "$target_count" -eq 1 ]] || automation_die "test filter must identify exactly one declared contract target: $filter"
+    gradle_task="$(jq -er --arg filter "$filter" '.targetTests[] | select(.filter == $filter) | .gradleTask' "$contract")"
+    red_log="$evidence_dir/red.log"
+    started_at="$(automation_now)"
+    set +e
+    automation_run_focused_test "$gradle_task" "$filter" "$AUTOMATION_ROOT" 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 gradleTask "$gradle_task" --arg testFilter "$filter" \
+        --argjson exitCode "$red_status" \
+        '{taskId: $taskId, startedAt: $startedAt, finishedAt: $finishedAt,
+          command: ["./gradlew", $gradleTask, "--tests", $testFilter],
+          expectedFailure: $expectedFailure, exitCode: $exitCode}' | automation_record_json "$red_meta"
+    automation_info "$task_id legacy RED evidence recorded"
+    exit 0
+fi
+
+[[ "$#" -eq 1 ]] || { printf 'Schema V3 usage: %s TASK-ID\n' "$0" >&2; exit 2; }
+"$SCRIPT_DIR/scope-gate.sh" "$task_id" >/dev/null
 
-[[ "$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"
+# RED must be captured before any production change. Planning artifacts are
+# excluded; test sources and fixtures are the only permitted product changes.
+while IFS= read -r changed_path; do
+    [[ -n "$changed_path" ]] || continue
+    if ! automation_array_matches_path "$AUTOMATION_CONFIG" '.androidProject.testPaths' "$changed_path"; then
+        automation_die "RED preflight requires unchanged production code; non-test path changed: $changed_path"
+    fi
+done < <(automation_product_changed_paths_at "$task_id" "$AUTOMATION_ROOT")
+
+previous_attempt=0
+preflight_meta="$evidence_dir/test-preflight.json"
+if [[ -f "$preflight_meta" ]]; then
+    previous_attempt="$(jq -er '.attempt' "$preflight_meta")"
+fi
+attempt=$((previous_attempt + 1))
+max_fixes="$(jq -er '.verification.maxPreparationFixes' "$contract")"
+if [[ "$attempt" -gt $((max_fixes + 1)) ]]; then
+    automation_die "test preparation retry budget exhausted; revise the contract or abort the task"
+fi
+
+attempt_id="$(printf '%03d' "$attempt")"
+attempt_dir="$evidence_dir/attempts/red-preflight-$attempt_id"
+mkdir -p "$attempt_dir"
+observed_file="$attempt_dir/observed.jsonl"
+: > "$observed_file"
+execution_failures='[]'
+started_at="$(automation_now)"
+target_index=0
+while IFS=$'\t' read -r gradle_task filter; do
+    result_file="$attempt_dir/target-$target_index.jsonl"
+    log_file="$attempt_dir/target-$target_index.log"
+    set +e
+    automation_run_classified_focused_test "$gradle_task" "$filter" "$AUTOMATION_ROOT" "$result_file" "$log_file"
+    gradle_status=$?
+    set -e
+    if [[ "$gradle_status" -ne 0 ]]; then
+        execution_failures="$(jq -nc --argjson current "$execution_failures" --argjson target "$target_index" \
+            --arg task "$gradle_task" --arg filter "$filter" --argjson exitCode "$gradle_status" \
+            '$current + [{target: $target, gradleTask: $task, filter: $filter, exitCode: $exitCode}]')"
+    fi
+    if [[ -s "$result_file" ]]; then
+        while IFS= read -r result_line; do
+            if ! jq -e . >/dev/null 2>&1 <<< "$result_line"; then
+                execution_failures="$(jq -nc --argjson current "$execution_failures" --argjson target "$target_index" \
+                    '$current + [{target: $target, reason: "invalid structured test output"}]')"
+                continue
+            fi
+            jq -c --argjson target "$target_index" '. + {target: $target}' <<< "$result_line" >> "$observed_file"
+        done < "$result_file"
+    else
+        execution_failures="$(jq -nc --argjson current "$execution_failures" --argjson target "$target_index" \
+            '$current + [{target: $target, reason: "no structured test results"}]')"
+    fi
+    target_index=$((target_index + 1))
+done < <(jq -r '.targetTests[] | [.gradleTask, .filter] | @tsv' "$contract")
+
+contract_sha="$(automation_file_sha256 "$contract")"
+baseline_head="$(jq -er '.head' "$evidence_dir/baseline.json")"
+test_diff_sha="$(automation_test_diff_sha "$task_id" "$AUTOMATION_ROOT")"
+finished_at="$(automation_now)"
 
 jq -n \
+    --slurpfile contract "$contract" \
+    --slurpfile observed "$observed_file" \
     --arg taskId "$task_id" \
     --arg startedAt "$started_at" \
-    --arg finishedAt "$(automation_now)" \
-    --arg expectedFailure "$expected" \
-    --arg gradleTask "$gradle_task" \
-    --arg testFilter "$filter" \
-    --argjson exitCode "$red_status" \
-    '{taskId: $taskId, startedAt: $startedAt, finishedAt: $finishedAt, command: ["./gradlew", $gradleTask, "--tests", $testFilter], expectedFailure: $expectedFailure, exitCode: $exitCode}' \
-    | automation_record_json "$red_meta"
-
-automation_info "$task_id RED evidence recorded"
+    --arg finishedAt "$finished_at" \
+    --arg contractSha256 "$contract_sha" \
+    --arg baselineHead "$baseline_head" \
+    --arg testDiffSha256 "$test_diff_sha" \
+    --argjson attempt "$attempt" \
+    --argjson executionFailures "$execution_failures" '
+      def failure_matches($decl; $actual):
+        ($actual.result == "FAILURE") and
+        ($actual.exceptionType == $decl.expectedFailure.type) and
+        (($decl.expectedFailure.messageIncludes // "") as $fragment |
+          ($fragment == "" or (($actual.exceptionMessage // "") | contains($fragment))));
+      ($contract[0].verification.cases | map(
+        . as $decl |
+        [$observed[] | select(.kind == "case" and .target == $decl.test.target and
+          .className == $decl.test.className and .name == $decl.test.name)] as $matches |
+        (if ($matches | length) == 1 then $matches[0] else null end) as $actual |
+        (if ($matches | length) != 1 then false
+         elif $decl.before == "pass" then $actual.result == "SUCCESS"
+         elif $decl.before == "fail" then failure_matches($decl; $actual)
+         elif $actual.result == "SUCCESS" then true
+         elif ($decl | has("expectedFailure")) then failure_matches($decl; $actual)
+         else false end) as $valid |
+        {id: $decl.id, criterion: $decl.criterion, intent: $decl.intent,
+         expectedBefore: $decl.before, test: $decl.test, expectedFailure: ($decl.expectedFailure // null),
+         matches: ($matches | length), actual: $actual, valid: $valid}
+      )) as $cases |
+      [$observed[] | select(.kind == "case") as $actual |
+        select(any($contract[0].verification.cases[];
+          .test.target == $actual.target and .test.className == $actual.className and .test.name == $actual.name) | not)] as $undeclared |
+      [$observed[] | select(.kind == "suite")] as $suites |
+      ($executionFailures | length == 0 and
+       ($suites | length) >= ($contract[0].targetTests | length) and
+       ($cases | all(.valid)) and ($undeclared | length == 0) and
+       ($cases | any(.intent == "change" and .actual.result == "FAILURE"))) as $valid |
+      {taskId: $taskId, attempt: $attempt, startedAt: $startedAt, finishedAt: $finishedAt,
+       contractSha256: $contractSha256, baselineHead: $baselineHead,
+       testDiffSha256: $testDiffSha256, valid: $valid,
+       reasonCode: (if $valid then "VALID_RED"
+                    elif ($executionFailures | length) > 0 then "EXECUTION_FAILURE"
+                    elif ($undeclared | length) > 0 then "UNDECLARED_TEST_RESULT"
+                    else "CASE_EXPECTATION_MISMATCH" end),
+       summary: {declared: ($cases | length), valid: ([$cases[] | select(.valid)] | length),
+                 invalid: ([$cases[] | select(.valid | not)] | length),
+                 expectedRed: ([$cases[] | select(.intent == "change" and .actual.result == "FAILURE")] | length),
+                 undeclared: ($undeclared | length)},
+       cases: $cases, undeclaredCases: $undeclared, suites: $suites,
+       executionFailures: $executionFailures}' | automation_record_json "$preflight_meta"
+
+cp "$preflight_meta" "$attempt_dir/evaluation.json"
+if [[ "$(jq -r '.valid' "$preflight_meta")" != "true" ]]; then
+    reason="$(jq -r '.reasonCode' "$preflight_meta")"
+    invalid="$(jq -r '[.cases[] | select(.valid | not) | .id] | join(", ")' "$preflight_meta")"
+    automation_die "RED preflight rejected ($reason); invalid cases: ${invalid:-none}; evidence: $preflight_meta"
+fi
+
+jq '{taskId, contractSha256, baselineHead, testDiffSha256,
+     cases: [.cases[] | {id, criterion, intent, test, actual}]}' "$preflight_meta" \
+    | automation_record_json "$evidence_dir/test-manifest.json"
+preflight_sha="$(automation_file_sha256 "$preflight_meta")"
+manifest_sha="$(automation_file_sha256 "$evidence_dir/test-manifest.json")"
+jq -n --arg taskId "$task_id" --arg startedAt "$started_at" --arg finishedAt "$finished_at" \
+    --arg contractSha256 "$contract_sha" --arg baselineHead "$baseline_head" \
+    --arg testDiffSha256 "$test_diff_sha" --arg preflightSha256 "$preflight_sha" \
+    --arg manifestSha256 "$manifest_sha" --arg attemptPath "attempts/red-preflight-$attempt_id" \
+    --argjson attempt "$attempt" \
+    '{taskId: $taskId, schemaVersion: 3, startedAt: $startedAt, finishedAt: $finishedAt,
+      contractSha256: $contractSha256, baselineHead: $baselineHead,
+      testDiffSha256: $testDiffSha256, preflightSha256: $preflightSha256,
+      manifestSha256: $manifestSha256, attempt: $attempt, attemptPath: $attemptPath,
+      structuredCasesVerified: true, exitCode: 1}' | automation_record_json "$red_meta"
+
+automation_info "$task_id structured RED evidence recorded"