@frankzhang2026/opencode-android-orchestrator 1.0.3 → 1.0.5

package/docs/MIGRATION.md

@@ -1,7 +1,7 @@
 # Migration guide
 
 This guide covers migration to
-`@frankzhang2026/opencode-android-orchestrator@1.0.3`. Pin the exact version and
+`@frankzhang2026/opencode-android-orchestrator@1.0.5`. Pin the exact version and
 prove the migration in a disposable clone before changing a long-lived
 repository.
 
@@ -9,10 +9,10 @@ repository.
 
 | Current state | Correct command after release | Important distinction |
 | --- | --- | --- |
-| No orchestrator files or manifest | `npx @frankzhang2026/opencode-android-orchestrator@1.0.3 init .` | Normal new installation; all runtime-detected Android modules and registered debug verification tasks are discovered automatically. |
+| No orchestrator files or manifest | `npx @frankzhang2026/opencode-android-orchestrator@1.0.5 init .` | Normal new installation; all runtime-detected Android modules and registered debug verification tasks are discovered automatically. |
 | Published `0.1.0` scaffold only | Remove any project-local `@0.1.0` plugin reference after review, then run `init`. | `0.1.0` did not create a usable managed installation and cannot be upgraded. |
-| `0.2.0` through `0.10.0` manifest-managed installation with intact managed/backup content | Run the `1.0.0` `upgrade`; add `--refresh-gradle-discovery` when generated module/task lists are incomplete. | Refresh replaces all derived module metadata, source paths, protected build files, and task allowlists from one Gradle runtime snapshot. Module scope, operator policies, user-owned AGENTS content, and an existing commit-prefix sidecar remain preserved. |
-| Healthy `1.0.0` through `1.0.2` installation | Stop the queue service, finish or abort retained workspaces, then run the fixed `1.0.3` `upgrade`. | Pending inbox contracts remain durable. Version 1.0.3 makes omitted task commit policies inherit the repository configuration while preserving the legacy human-approval fallback when the field is absent. |
+| `0.2.0` through `0.10.0` manifest-managed installation with intact managed/backup content | Run the `1.0.5` `upgrade`; add `--refresh-gradle-discovery` when generated module/task lists are incomplete. | Refresh replaces all derived module metadata, source paths, protected build files, and task allowlists from one Gradle runtime snapshot. Module scope, operator policies, user-owned AGENTS content, and an existing commit-prefix sidecar remain preserved. |
+| Healthy `1.0.0` through `1.0.4` installation | Stop the queue service, finish or abort retained workspaces, then run the fixed `1.0.5` `upgrade`. | Pending inbox contracts remain durable. Version 1.0.5 adds schema V3 contracts and rejects RED evidence containing preserved-behavior or undeclared failures; older approved contracts retain their legacy flow. |
 | Manually copied V3 files, no `.automation-plugin/manifest.json` | Finish active tasks, preserve historical evidence separately, then run `init`. | Exact files can be reused; differing managed files fail as conflicts. |
 | Healthy older manifest-managed installation | Run `doctor`, then the fixed target version's `upgrade`. | `upgrade` requires a valid installed manifest and intact original backups. |
 | Healthy current-version manifest | Run `doctor`; repeated `init` or same-version `upgrade` is verification-only and byte-idempotent. | Do not reinstall or delete the manifest. |
@@ -58,7 +58,7 @@ installation of `0.1.0` alone does not require project-file cleanup.
 After release, initialize with the fixed version:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@1.0.3 init .
+npx @frankzhang2026/opencode-android-orchestrator@1.0.5 init .
 ```
 
 New installations default to all-module scope, so multiple application modules
@@ -106,7 +106,7 @@ Use the lifecycle command selected by the active manifest:
 
 ```sh
 npx --yes --registry=https://registry.npmjs.org/ \
-  @frankzhang2026/opencode-android-orchestrator@1.0.3 upgrade . --json
+  @frankzhang2026/opencode-android-orchestrator@1.0.5 upgrade . --json
 ```
 
 The command-level Registry option is useful when a company-wide npm Registry
@@ -136,7 +136,7 @@ computed includes dynamically or a company convention plugin applied
 
 ```sh
 npx --yes --registry=https://registry.npmjs.org/ \
-  @frankzhang2026/opencode-android-orchestrator@1.0.3 upgrade . \
+  @frankzhang2026/opencode-android-orchestrator@1.0.5 upgrade . \
   --refresh-gradle-discovery --json
 ```
 
@@ -220,7 +220,7 @@ use the queue rather than the old direct Shell commands. See [Queue operation](Q
 Run all checks from the detected Git root:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@1.0.3 doctor .
+npx @frankzhang2026/opencode-android-orchestrator@1.0.5 doctor .
 opencode debug config
 opencode debug skill
 opencode debug agent scheduled-planner

package/docs/QUEUE.md

@@ -1,6 +1,6 @@
 # Queue and background execution
 
-Version `1.0.3` stores proposals and approved contracts under
+Version `1.0.5` stores proposals and approved contracts under
 `<git-common-dir>/automation-runtime/inbox/queue.json`. A contract is runnable
 only after its full plan, version, digest, target branch and commit policy are
 approved and durably recorded. Planning reads a fixed `planningHead`, so another
@@ -51,9 +51,14 @@ rejected even if it copies the visible run ID.
 
 ## Service and scheduling
 
-The first enqueue starts the package-owned detached service. Closing the
-Planner does not stop it. Enqueue notifications, deadlines, worker completion,
-startup recovery and periodic scans all use the same atomic reservation logic.
+Each newly approved contract atomically clears the queue's pause flag when it
+is enqueued, then starts or wakes the package-owned detached service. This
+resumes the entire queue; existing tasks keep their normal priority/FIFO order,
+deadlines and dependencies. Failed or duplicate enqueue requests do not clear
+the pause flag, and enqueue never clears a fault or replaces an active executor.
+Closing the Planner does not stop the service. Enqueue notifications, deadlines,
+worker completion, startup recovery and periodic scans all use the same atomic
+reservation logic.
 Idle scans do not call a model. No launchd or external Scheduler is registered.
 The machine must be awake; a restarted service scans overdue entries once
 through normal arbitration. Recurring task-template generation is not exposed
@@ -80,7 +85,8 @@ opencode-android-orchestrator queue start .
 An unsuccessful OpenCode agent process pauses consumption as a shared execution
 fault; inspect its log and fix provider/environment failures before clearing it.
 
-Pause stops new reservations. Stop terminates the scheduler while preserving
+Pause stops new reservations until explicit resume or a new contract is
+successfully enqueued. Stop terminates the scheduler while preserving
 its active detached worker. Resume does not clear a fault. Notifications are
 persisted until acknowledged, so the original Planner session need not remain
 open. `queue --help` lists direct local-operator commands; interactive agents
@@ -95,8 +101,10 @@ opencode-android-orchestrator queue pause .
 opencode-android-orchestrator queue policy . isolatedWorktree humanApproval
 ```
 
-Review and commit the changed `automation/config.json` before resuming. The
-queued task fixes its workspace strategy when claimed. Its commit authorization
+Avoid approving new contracts during this maintenance pause: a new enqueue
+resumes queue consumption. Review and commit the changed
+`automation/config.json` before resuming. The queued task fixes its workspace
+strategy when claimed. Its commit authorization
 remains exactly the approved choice: changing a default cannot grant autoCommit
 to an older task. Direct configuration drift while a workspace is retained
 blocks scheduling; restore the recorded strategy before recovery.
@@ -116,6 +124,26 @@ It does not run `clean` or rerun all dependency tasks. Coder, Reviewer and local
 integration perform the configured full suite and build gates. Evidence records
 fresh-test logs, configured tasks and elapsed seconds.
 
+Newly generated contracts use task-contract schema V3. Every verification case
+has a stable ID, a one-based acceptance-criterion reference, an evidence source,
+an exact test identity, and a pre-change classification:
+
+- `preserve` must pass before and after implementation;
+- `change` must fail before implementation with the approved exception type and
+  optional message fragment, then pass afterwards;
+- `observe` may record a previously uncertain boundary, but a failure is
+  accepted only when the contract declares its expected cause.
+
+Before product code changes, `record-red.sh TASK-ID` forces fresh focused Test
+execution and collects structured case results through a temporary Gradle init
+script. Missing, duplicate, skipped or undeclared cases, build failures, and any
+preserved behavior failure reject the preflight. Failed attempts remain under
+the task evidence directory; only a completely valid attempt creates immutable
+RED and test-manifest records. Those records bind the contract hash, execution
+baseline and test-only diff, so changing a RED test afterwards invalidates the
+quality gate. V1/V2 contracts already approved before upgrade retain the legacy
+explicit failure-text command.
+
 ## Baselines and recovery
 
 Before execution, changes to contract-relevant files or execution configuration

package/docs/SECURITY.md

@@ -1,7 +1,7 @@
 # Security model
 
 This document describes the security properties of
-`@frankzhang2026/opencode-android-orchestrator@1.0.3`. The lifecycle foundation
+`@frankzhang2026/opencode-android-orchestrator@1.0.5`. The lifecycle foundation
 completed the real OpenCode `1.14.22` and `1.15.13` release matrix in `0.2.0`;
 `1.0.0` retains that compatibility boundary.
 

package/docs/TROUBLESHOOTING.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 Use this guide for
-`@frankzhang2026/opencode-android-orchestrator@1.0.3`.
+`@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.3 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.3 version
+  @frankzhang2026/opencode-android-orchestrator@1.0.5 version
 npx --yes --registry=https://registry.npmjs.org/ \
-  @frankzhang2026/opencode-android-orchestrator@1.0.3 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.3` 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.3 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.3`, 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:
@@ -246,6 +246,7 @@ session or a missing notification is not evidence that a task never started.
 | Symptom | Recovery |
 | --- | --- |
 | Fresh matching question receipt required | Show a new queue review/draft question and select it in the same Planner session; do not paste its approval label into chat. |
+| Service is running but the queue is paused | Use `queue resume .` to run existing approvals. A newly approved contract also resumes the queue when enqueued; duplicate or rejected enqueue requests leave the pause unchanged. |
 | Waiting for human confirmation or fixed workspace | Accept the current candidate or use the approved abort workflow; further contracts may still be enqueued. |
 | Isolated capacity reached | Integrate or explicitly archive retained workspaces; do not delete failed work simply to advance the queue. |
 | Execution launch ownership unknown | Stop the recorded launcher, prove it exited, then use `queue recover-execution .`; preserve any partial workspace. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frankzhang2026/opencode-android-orchestrator",
-  "version": "1.0.3",
+  "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
@@ -77,7 +87,10 @@ fresh `合同确认` single-choice question using the exact returned `question`
 key and digest. Adjustments create a new draft version and require a new review.
 
 After enqueue succeeds, report its task ID, queue state and policies and return
-to the user. The detached repository service owns execution. Never hold this
+to the user. A newly enqueued contract automatically resumes the whole queue
+and starts or wakes its service; existing scheduling rules and faults still
+apply. Failed or duplicate enqueue requests do not clear a pause.
+The detached repository service owns execution. Never hold this
 conversation waiting for Coder/Reviewer or simulate model polling while idle.
 The user can immediately submit another request.
 

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-orchestrator/SKILL.md

@@ -39,6 +39,9 @@ description: Plan stable committed code, approve independent inbox contracts, an
    `{key, digest, approval}`. A new version requires a new approval.
 7. Report durable enqueue success and return. Execution is asynchronous, one
    repository slot; the foreground may plan/approve B and C while A runs.
+   A newly enqueued contract resumes the whole queue and starts or wakes its
+   service. Existing scheduling rules and faults still apply; failed or
+   duplicate enqueue requests do not clear a pause.
 
 # Acceptance and controls
 

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"