@frankzhang2026/opencode-android-orchestrator 1.1.0 → 1.2.1

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

@@ -32,8 +32,43 @@
           "minLength": 3
         },
         "origin": {
-          "type": "string",
-          "minLength": 12
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 12
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "className",
+                "methodName"
+              ],
+              "properties": {
+                "className": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z_$][A-Za-z0-9_.$]*$"
+                },
+                "methodName": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "fileName": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "lineNumber": {
+                  "type": "integer",
+                  "minimum": 1
+                }
+              },
+              "dependentRequired": {
+                "lineNumber": [
+                  "fileName"
+                ]
+              }
+            }
+          ]
         }
       }
     },
@@ -363,6 +398,57 @@
               ]
             }
           }
+        },
+        "criteriaEvidence": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "criterion",
+              "kind",
+              "references"
+            ],
+            "properties": {
+              "criterion": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "kind": {
+                "enum": [
+                  "behavior",
+                  "build",
+                  "lint",
+                  "device"
+                ]
+              },
+              "references": {
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          }
+        },
+        "supplementalTests": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "mode",
+            "maxRevisions"
+          ],
+          "properties": {
+            "mode": {
+              "const": "baselinePassingNewFiles"
+            },
+            "maxRevisions": {
+              "const": 1
+            }
+          }
         }
       }
     },

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

@@ -37,9 +37,7 @@
     "android-orchestrator-verification-before-completion"
   ],
   "acceptanceCriteria": [
-    "Replace with an observable input/output or UI behavior",
-    "A focused test demonstrates the behavior and is captured RED before implementation",
-    "Debug build passes; unit tests and Android lint also pass when their configuration flags are enabled"
+    "Replace with an observable input/output or UI behavior"
   ],
   "nonGoals": [
     "Do not refactor unrelated screens",
@@ -72,7 +70,10 @@
         },
         "expectedFailure": {
           "type": "java.lang.AssertionError",
-          "origin": "The assertion at the approved behavior call"
+          "origin": {
+            "className": "ReplaceWithFocusedTest",
+            "methodName": "replace with observable behavior"
+          }
         }
       }
     ],

package/templates/automation/verification/collect.init.gradle

@@ -6,7 +6,17 @@ import org.gradle.api.tasks.testing.TestListener
 import org.gradle.api.tasks.testing.TestResult
 
 // All three phases use this collector. Never infer execution from existing XML.
-def request = new JsonSlurper().parse(new File(System.getProperty('orchestrator.inventoryRequest')))
+// Gradle 6.7.1 does not expose command-line -D properties through System yet
+// while evaluating init scripts in a (including single-use) daemon.
+def requestPath = gradle.startParameter.systemPropertiesArgs['orchestrator.inventoryRequest'] ?: System.getProperty('orchestrator.inventoryRequest')
+if (!(requestPath instanceof String) || requestPath.trim().isEmpty()) {
+    throw new GradleException('Missing orchestrator.inventoryRequest: pass an absolute request JSON path with -D')
+}
+def requestFile = new File(requestPath)
+if (!requestFile.isAbsolute() || !requestFile.isFile() || !requestFile.canRead()) {
+    throw new GradleException('Invalid orchestrator.inventoryRequest: an existing readable absolute file is required')
+}
+def request = new JsonSlurper().parse(requestFile)
 def outputFile = new File(request.output as String)
 def append = { Map value ->
     synchronized (outputFile) {
@@ -17,46 +27,56 @@ append([kind: 'start', phase: request.phase, gradleVersion: gradle.gradleVersion
 def filtersByTask = request.targets.groupBy { it.gradleTask }.collectEntries { path, targets ->
     [(path): targets.collect { it.filter }.unique().sort()]
 }
-gradle.taskGraph.whenReady { graph ->
-    filtersByTask.each { path, filters ->
-        def task = graph.allTasks.find { it.path == path }
-        if (!(task instanceof Test)) throw new GradleException("Inventory target must resolve to an exact Test task: ${path}")
-        def roots = [] as Set
-        def classes = task.testClassesDirs.files.collect { it.canonicalFile } as Set
-        def sourceSets = task.project.extensions.findByName('sourceSets')
-        sourceSets?.each { sourceSet ->
-            if (sourceSet.output.classesDirs.files.any { classes.contains(it.canonicalFile) }) {
-                roots.addAll(sourceSet.allSource.srcDirs)
-                roots.addAll(sourceSet.resources.srcDirs)
-            }
+// Keep dry-run source discovery independent of Android output providers.
+// Real output metadata is collected after producer tasks have executed.
+def recordTask = { task, boolean discovery ->
+    def path = task.path
+    def filters = filtersByTask[path]
+    def roots = [] as Set
+    def android = task.project.extensions.findByName('android')
+    // Dry-run discovery cannot execute producer tasks. Android source roots
+    // come from its DSL; class-output paths are recorded on the real run.
+    def classes = discovery && android != null ? ([] as Set) :
+        (task.testClassesDirs.files.collect { it.canonicalFile } as Set)
+    def sourceSets = android == null ? task.project.extensions.findByName('sourceSets') : null
+    sourceSets?.each { sourceSet ->
+        if (sourceSet.output.classesDirs.files.any { classes.contains(it.canonicalFile) }) {
+            roots.addAll(sourceSet.allSource.srcDirs)
+            roots.addAll(sourceSet.resources.srcDirs)
         }
-        // AGP variants expose the source providers actually used by each unit test.
-        def android = task.project.extensions.findByName('android')
-        if (android != null && android.hasProperty('unitTestVariants')) {
-            android.unitTestVariants.each { variant ->
-                if (task.name == "test${variant.name.capitalize()}") {
-                    variant.sourceSets.each { provider ->
-                        roots.addAll(provider.javaDirectories)
-                        roots.addAll(provider.resourcesDirectories)
-                        if (provider.hasProperty('kotlinDirectories')) roots.addAll(provider.kotlinDirectories)
-                    }
+    }
+    // AGP variants expose the source providers actually used by each unit test.
+    if (android != null && android.hasProperty('unitTestVariants')) {
+        android.unitTestVariants.each { variant ->
+            if (task.name == "test${variant.name.capitalize()}") {
+                variant.sourceSets.each { provider ->
+                    roots.addAll(provider.javaDirectories)
+                    roots.addAll(provider.resourcesDirectories)
+                    if (provider.hasProperty('kotlinDirectories')) roots.addAll(provider.kotlinDirectories)
                 }
             }
         }
-        // Modern AGP also exposes variant-specific test source sets through its DSL.
-        // Only unit-test providers are classified here, never production providers.
-        if (android != null && android.hasProperty('sourceSets')) {
-            android.sourceSets.findAll { it.name == 'test' || it.name.startsWith('test') && it.name.length() > 4 && Character.isUpperCase(it.name.charAt(4)) }.each { sourceSet ->
-                roots.addAll(sourceSet.java.srcDirs)
-                roots.addAll(sourceSet.resources.srcDirs)
-                if (sourceSet.hasProperty('kotlin')) roots.addAll(sourceSet.kotlin.srcDirs)
-                roots.addAll(sourceSet.assets.srcDirs)
-                roots.addAll(sourceSet.res.srcDirs)
-            }
+    }
+    // Modern AGP also exposes variant-specific test source sets through its DSL.
+    // Only unit-test providers are classified here, never production providers.
+    if (android != null && android.hasProperty('sourceSets')) {
+        android.sourceSets.findAll { it.name == 'test' || it.name.startsWith('test') && it.name.length() > 4 && Character.isUpperCase(it.name.charAt(4)) }.each { sourceSet ->
+            roots.addAll(sourceSet.java.srcDirs)
+            roots.addAll(sourceSet.resources.srcDirs)
+            if (sourceSet.hasProperty('kotlin')) roots.addAll(sourceSet.kotlin.srcDirs)
+            roots.addAll(sourceSet.assets.srcDirs)
+            roots.addAll(sourceSet.res.srcDirs)
         }
-        append([kind: 'task', taskPath: path, filters: filters,
-            sourceRoots: roots.collect { it.absoluteFile.toPath().normalize().toString() }.sort(),
-            testClassesDirs: classes.collect { it.toString() }.sort()])
+    }
+    append([kind: 'task', taskPath: path, filters: filters,
+        sourceRoots: roots.collect { it.absoluteFile.toPath().normalize().toString() }.sort(),
+        testClassesDirs: classes.collect { it.toString() }.sort()])
+}
+gradle.taskGraph.whenReady { graph ->
+    filtersByTask.each { path, filters ->
+        def task = graph.allTasks.find { it.path == path }
+        if (!(task instanceof Test)) throw new GradleException("Inventory target must resolve to an exact Test task: ${path}")
+        if (gradle.startParameter.dryRun) recordTask(task, true)
         task.outputs.upToDateWhen { false }
         task.outputs.doNotCacheIf('Orchestrator inventory requires actual test execution') { true }
         task.ignoreFailures = true
@@ -87,6 +107,10 @@ gradle.taskGraph.whenReady { graph ->
         })
     }
 }
+// beforeTask also records skipped/NO-SOURCE tasks for inventory validation.
+gradle.taskGraph.beforeTask { task ->
+    if (filtersByTask.containsKey(task.path)) recordTask(task, false)
+}
 gradle.taskGraph.afterTask { task, state ->
     if (filtersByTask.containsKey(task.path)) append([kind: 'taskEnd', taskPath: task.path,
         executed: state.executed, skipped: state.skipped, noSource: state.noSource,

package/templates/automation/verification/contract.cjs

@@ -59,7 +59,10 @@ function validateContract(contract, config) {
     assert(!targets.has(key), "Focused test targets must be unique"); targets.add(key);
   }
   const verification = contract.verification;
-  assert(fields(verification, ["version", "maxPreparationFixes", "cases", "inventory"]) && verification.version === 2, "Inventory verification requires verification version 2 with explicit inventory policy");
+  assert(fields(verification, ["version", "maxPreparationFixes", "cases", "inventory"], ["criteriaEvidence", "supplementalTests"]) && verification.version === 2, "Inventory verification requires verification version 2 with explicit inventory policy");
+  if (Object.hasOwn(verification, "supplementalTests")) assert(fields(verification.supplementalTests, ["mode", "maxRevisions"]) &&
+    verification.supplementalTests.mode === "baselinePassingNewFiles" && verification.supplementalTests.maxRevisions === 1,
+    "Supplemental tests require explicit baselinePassingNewFiles authorization and one revision");
   assert(Number.isInteger(verification.maxPreparationFixes) && verification.maxPreparationFixes >= 0 && verification.maxPreparationFixes <= 1, "Invalid preparation retry budget");
   const policy = verification.inventory;
   assert(fields(policy, ["mode", "existingSkips", "emptyBaseline"]) && policy.mode === "focusedBaseline" &&
@@ -79,11 +82,34 @@ function validateContract(contract, config) {
     else assert(item.intent === "observe" && item.before === "observe" && ["userRequirement", "existingTest", "baselineCapture", "measuredFact"].includes(item.source), "Invalid observed behavior");
     if (Object.hasOwn(item, "expectedFailure")) {
       const failure = item.expectedFailure;
-      assert(fields(failure, ["type", "origin"], ["messageIncludes"]) && text(failure.type) && text(failure.origin) && failure.origin.length >= 12 &&
+      const origin = failure.origin;
+      const structuredOrigin = fields(origin, ["className", "methodName"], ["fileName", "lineNumber"]) &&
+        text(origin.className) && /^[A-Za-z_$][A-Za-z0-9_.$]*$/.test(origin.className) && text(origin.methodName) &&
+        !/[().]/.test(origin.methodName) && (!Object.hasOwn(origin, "fileName") || text(origin.fileName) && !/[\\/]/.test(origin.fileName)) &&
+        (!Object.hasOwn(origin, "lineNumber") || Object.hasOwn(origin, "fileName") && Number.isSafeInteger(origin.lineNumber) && origin.lineNumber > 0);
+      assert(fields(failure, ["type", "origin"], ["messageIncludes"]) && text(failure.type) &&
+        (structuredOrigin || text(origin) && origin.length >= 12) &&
         (!Object.hasOwn(failure, "messageIncludes") || (text(failure.messageIncludes) && failure.messageIncludes.length >= 3)), "Invalid expected failure");
     }
   }
   assert(verification.cases.some(item => item.intent === "change"), "At least one changed behavior must provide genuine RED");
+  const covered = new Set(verification.cases.map(item => item.criterion));
+  if (Object.hasOwn(verification, "criteriaEvidence")) {
+    assert(Array.isArray(verification.criteriaEvidence), "Invalid criterion evidence mapping");
+    const explicit = new Set();
+    for (const evidence of verification.criteriaEvidence) {
+      assert(fields(evidence, ["criterion", "kind", "references"]) && Number.isInteger(evidence.criterion) &&
+        evidence.criterion >= 1 && evidence.criterion <= contract.acceptanceCriteria.length && !explicit.has(evidence.criterion), "Invalid or duplicate criterion evidence");
+      explicit.add(evidence.criterion);
+      assert(Array.isArray(evidence.references) && evidence.references.length > 0 && new Set(evidence.references).size === evidence.references.length, "Criterion evidence requires unique references");
+      const available = evidence.kind === "behavior" ? [...ids] : evidence.kind === "build" ? config.gradleVerification.assembleTasks :
+        evidence.kind === "lint" && config.lintEnabled === true ? config.gradleVerification.lintTasks :
+        evidence.kind === "device" && contract.deviceTestsRequired ? config.gradleVerification.deviceTestTasks : undefined;
+      assert(Array.isArray(available) && evidence.references.every(ref => available.includes(ref)), "Criterion evidence must reference approved behavior cases or mandatory enabled verification tasks");
+      covered.add(evidence.criterion);
+    }
+  }
+  assert(contract.acceptanceCriteria.every((_, index) => covered.has(index + 1)), "Every acceptance criterion requires an explicit behavior or verification evidence mapping");
   assert(!/replace with|TASK-EXAMPLE|\btodo\b|\btbd\b|placeholder/i.test(JSON.stringify(contract)), "Contract contains placeholders");
 }
 module.exports = { validateContract, identity, matchesPath, assert };

package/templates/automation/verification/inventory.cjs

@@ -104,6 +104,20 @@ function evaluateBaseline(contract, collection) {
   requireThat(policy.emptyBaseline === "allow" || empty.length === 0, "EMPTY_BASELINE", "One or more focused tasks have an empty baseline", empty);
   return { cases, summary: { existing: cases.length, passed: cases.length - skipped.length, skipped: skipped.length, emptyTasks: empty.length } };
 }
+function matchesFailureOrigin(expected, actual, test) {
+  if (!Array.isArray(actual.stack) || !actual.stack.length) return false;
+  const frames = actual.stack.map(frame => typeof frame === "string" &&
+    /^(?:[^/]+\/)?(.+)\.([^.(]+)\(([^():]+)(?::([0-9]+))?\)$/.exec(frame));
+  if (frames.some(frame => !frame)) return false;
+  const methodName = test.name.replace(/\[[^\]]*\]$/, "").replace(/\([^)]*\)$/, "");
+  // Before/after hooks, rules and initialization failures do not include the
+  // test body's invocation. Merely sharing an exception/message is not RED.
+  if (!frames.some(frame => frame[1] === test.className && frame[2] === methodName)) return false;
+  const origin = typeof expected.origin === "object" ? expected.origin : { className: test.className, methodName };
+  const first = frames.find(frame => !/^(?:org\.junit\.(?:Assert|ComparisonFailure)$|org\.junit\.jupiter\.api\.(?:Assertions|AssertionUtils|Assert\w+)$|org\.opentest4j\.|kotlin\.test\.|org\.hamcrest\.MatcherAssert$|org\.assertj\.core\.)/.test(frame[1]));
+  return Boolean(first && first[1] === origin.className && first[2] === origin.methodName &&
+    (!origin.fileName || first[3] === origin.fileName) && (!origin.lineNumber || Number(first[4]) === origin.lineNumber));
+}
 function evaluateCoverage(contract, baseline, collection, phase, manifest) {
   const actual = new Map(collection.cases.map(item => [identity(item), item]));
   const expected = new Map(baseline.cases.map(item => [identity(item), { ...item, classification: "regression", id: identity(item) }]));
@@ -127,7 +141,8 @@ function evaluateCoverage(contract, baseline, collection, phase, manifest) {
     } else {
       const failure = item.expectedFailure;
       const matched = result.result === "FAILURE" && failure && result.failures.length === 1 &&
-        result.failures[0].type === failure.type && (!failure.messageIncludes || result.failures[0].message.includes(failure.messageIncludes));
+        result.failures[0].type === failure.type && (!failure.messageIncludes || result.failures[0].message.includes(failure.messageIncludes)) &&
+        matchesFailureOrigin(failure, result.failures[0], item);
       valid = item.before === "pass" ? result.result === "SUCCESS" : item.before === "fail" ? matched : result.result === "SUCCESS" || matched;
     }
     const entry = { id: item.id, taskPath: item.taskPath, className: item.className, name: item.name,
@@ -213,7 +228,7 @@ function unchangedProduction(root, contract, config, patterns, phase, evidence)
   const invalid = changed.filter(file => !ignored.has(file) && (phase === "baseline" || !isTest(config, patterns, file)));
   requireThat(invalid.length === 0, "EVIDENCE_CHANGED", "Baseline/RED requires unchanged production and configuration", invalid.map(file => ({ path: file })));
 }
-function collectorHash() { return digest(["contract.cjs", "inventory.cjs", "collect.init.gradle"].map(file => [file, fileHash(path.join(__dirname, file))])); }
+function collectorHash() { return digest(["contract.cjs", "inventory.cjs", "project.cjs", "collect.init.gradle", "runtime.init.gradle"].map(file => [file, fileHash(path.join(__dirname, file))])); }
 function evidenceFiles(evidence, directory) {
   const result = [];
   function visit(folder) { for (const name of fs.readdirSync(folder).sort()) { const file = path.join(folder, name); const stat = fs.lstatSync(file);
@@ -234,7 +249,7 @@ function checkEvaluation(evidence, value, phase) {
   requireThat(value.phase === phase && typeof value.attemptPath === "string" &&
     new RegExp(`^inventory-attempts/${phase}-[0-9]+-[a-f0-9-]+$`).test(value.attemptPath),
   "EVIDENCE_CHANGED", "Invalid sealed attempt reference");
-  const { files, baselineInventorySha256, redSha256, manifestSha256, ...report } = value;
+  const { files, baselineInventorySha256, redSha256, manifestSha256, supplementSha256, ...report } = value;
   requireThat(same(report, read(path.join(evidence, value.attemptPath, "evaluation.json"))),
     "EVIDENCE_CHANGED", "Inventory report differs from its completed evaluation");
   if (files) requireThat(same(files, evidenceFiles(evidence, path.join(evidence, value.attemptPath))),
@@ -247,7 +262,7 @@ function runGradle(root, config, contract, phase, directory, discovery) {
   const requestFile = path.join(directory, "request.json"); atomic(requestFile, request, true);
   fs.writeFileSync(request.output, "", { flag: "wx" });
   const args = [...groupedTargets(contract).map(item => item.taskPath), "--no-configuration-cache", "--console=plain", "--no-build-cache",
-    "--init-script", path.join(__dirname, "collect.init.gradle"), `-Dorchestrator.inventoryRequest=${requestFile}`, ...(discovery ? ["--dry-run"] : [])];
+    "--init-script", path.join(__dirname, "runtime.init.gradle"), "--init-script", path.join(__dirname, "collect.init.gradle"), `-Dorchestrator.inventoryRequest=${requestFile}`, ...(discovery ? ["--dry-run"] : [])];
   const fd = fs.openSync(path.join(directory, "gradle.log"), "wx");
   let result;
   if (process.env.AUTOMATION_WORKER_TOKEN) args.push("--no-daemon");
@@ -264,7 +279,11 @@ function runGradle(root, config, contract, phase, directory, discovery) {
   let events;
   try { events = fs.readFileSync(request.output, "utf8").split("\n").filter(Boolean).map(line => JSON.parse(line)); }
   catch { throw new InventoryError("INCOMPLETE_COLLECTION", "Invalid or truncated collector output"); }
-  return { ...validateCollection(events, request, result.status, discovery), processExitCode: result.status };
+  const collection = validateCollection(events, request, result.status, discovery);
+  let runtime;
+  try { runtime = require("./project.cjs").parseBuildRuntime(fs.readFileSync(path.join(directory, "gradle.log"), "utf8")); }
+  catch (error) { throw new InventoryError("INCOMPLETE_COLLECTION", error.message); }
+  return { ...collection, runtime, processExitCode: result.status };
 }
 
 // Invalidate previous GREEN before even validating inputs. A crash, early
@@ -299,13 +318,15 @@ function runPhaseInternal(phase, contractFile, configFile, root, evidence, verif
   const checkBinding = value => requireThat(same(value.binding, binding), "EVIDENCE_CHANGED", "Contract, baseline, configuration or collector binding changed");
   const inputEvidence = [];
   const bindInput = file => { inputEvidence.push({ file, sha256: fileHash(file) }); };
-  let baseline, manifest, red, patterns;
+  let baseline, manifest, red, patterns, supplement;
   if (phase !== "baseline") {
     baseline = read(baselineFile); checkBinding(baseline); checkFiles(evidence, baseline.files);
     checkEvaluation(evidence, baseline, "baseline");
     requireThat(baseline.valid === true && baseline.phase === "baseline", "EVIDENCE_CHANGED", "A valid baseline inventory is required");
     bindInput(baselineFile);
     patterns = baseline.testPatterns;
+    requireThat(baseline.environmentSha256 === require("./project.cjs").buildEnvironmentBinding(require("./project.cjs").gradleBuildRoot(config, root), baseline.runtime),
+      "EVIDENCE_CHANGED", "Build environment or Gradle user/JVM configuration changed after baseline");
     if (phase === "green" || phase === "check") {
       red = read(redFile); manifest = read(manifestFile); checkBinding(red); checkBinding(manifest);
       requireThat(red.manifestSha256 === fileHash(manifestFile) && red.baselineInventorySha256 === fileHash(baselineFile) &&
@@ -314,7 +335,14 @@ function runPhaseInternal(phase, contractFile, configFile, root, evidence, verif
       checkEvaluation(evidence, manifest, "red");
       requireThat(red.structuredCasesVerified === true && manifest.valid === true && manifest.phase === "red", "EVIDENCE_CHANGED", "Valid sealed RED evidence is required");
       for (const file of [redFile, manifestFile, path.join(evidence, "test-preflight.json")]) bindInput(file);
-      requireThat(same(snapshot(root, config, patterns, excluded), manifest.testSnapshot), "EVIDENCE_CHANGED", "Test sources or resources changed after RED");
+      supplement = supplementalEvidence(phase, root, config, contract, evidence, binding, baseline, manifest, patterns, excluded);
+      if (supplement) {
+        bindInput(path.join(evidence, "test-supplement.json"));
+        baseline = { ...baseline, cases: [...baseline.cases, ...supplement.cases] };
+        manifest = { ...manifest, cases: [...manifest.cases, ...supplement.cases.map(item => ({ ...item, classification: "regression", id: identity(item), allowSkip: false }))],
+          testSnapshot: [...manifest.testSnapshot, ...supplement.addedFiles].sort((a, b) => a.path.localeCompare(b.path)) };
+      }
+      requireThat(same(snapshot(root, config, patterns, excluded), [...manifest.testSnapshot].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)), "EVIDENCE_CHANGED", "Test sources or resources changed after sealed test evidence");
     }
   }
   if (phase === "baseline" || phase === "red") requireThat(head === binding.baselineHead, "EVIDENCE_CHANGED", "Execution HEAD changed before RED");
@@ -326,6 +354,7 @@ function runPhaseInternal(phase, contractFile, configFile, root, evidence, verif
       "EVIDENCE_CHANGED", "Latest GREEN failed, was interrupted or is not the sealed successful run; rerun GREEN");
     checkEvaluation(evidence, green, "green");
     requireThat(green.valid && green.redSha256 === fileHash(redFile) && green.manifestSha256 === fileHash(manifestFile), "EVIDENCE_CHANGED", "GREEN is not bound to the sealed RED and manifest");
+    requireThat((green.supplementSha256 ?? null) === (supplement ? fileHash(path.join(evidence, "test-supplement.json")) : null), "EVIDENCE_CHANGED", "GREEN is not bound to the supplemental test evidence");
     requireThat(green.verifiedHead === head && green.worktreeSha256 === worktree(root, excluded), "EVIDENCE_CHANGED", "Repository inputs changed after GREEN; rerun verification");
     return green;
   }
@@ -364,7 +393,11 @@ function runPhaseInternal(phase, contractFile, configFile, root, evidence, verif
     }
     if (phase !== "green") unchangedProduction(root, contract, config, patterns, phase, evidence);
     const before = snapshot(root, config, patterns, excluded), repositoryBefore = worktree(root, excluded);
+    const environmentBefore = require("./project.cjs").buildEnvironmentBinding(require("./project.cjs").gradleBuildRoot(config, root), baseline?.runtime);
     const collection = runGradle(root, config, contract, phase, path.join(attempt, "collection"), false);
+    requireThat(environmentBefore === require("./project.cjs").buildEnvironmentBinding(require("./project.cjs").gradleBuildRoot(config, root), baseline?.runtime),
+      "EVIDENCE_CHANGED", "Build environment changed during collection");
+    if (baseline) requireThat(same(collection.runtime, baseline.runtime), "EVIDENCE_CHANGED", "Actual Gradle, build JVM, plugins or test JVMs differ from baseline");
     requireThat(same(patterns, testPatterns(root, config, collection.tasks)), "EVIDENCE_CHANGED", "Test source/resource discovery changed after baseline");
     const after = snapshot(root, config, patterns, excluded);
     requireThat(same(before, after) && repositoryBefore === worktree(root, excluded) && head === git(root, ["rev-parse", "HEAD"]).trim(),
@@ -378,7 +411,9 @@ function runPhaseInternal(phase, contractFile, configFile, root, evidence, verif
     const evaluation = phase === "baseline" ? evaluateBaseline(contract, collection) : evaluateCoverage(contract, baseline, collection, phase, manifest);
     const report = { schemaVersion: 1, taskId: contract.id, phase, attempt: number, attemptPath, startedAt, finishedAt: new Date().toISOString(),
       valid: true, reasonCode: phase === "red" ? "VALID_RED" : "VALID_INVENTORY", binding, ...evaluation, testPatterns: patterns, testSnapshot: after,
-      processExitCode: collection.processExitCode, verifiedHead: head, worktreeSha256: repositoryBefore,
+      processExitCode: collection.processExitCode, runtime: collection.runtime,
+      environmentSha256: require("./project.cjs").buildEnvironmentBinding(require("./project.cjs").gradleBuildRoot(config, root), collection.runtime),
+      verifiedHead: head, worktreeSha256: repositoryBefore,
       queueRunId: process.env.AUTOMATION_QUEUE_RUN_ID ?? null, ...(verificationRunId ? { verificationRunId } : {}) };
     atomic(path.join(attempt, "evaluation.json"), report, true);
     const files = evidenceFiles(evidence, attempt);
@@ -391,7 +426,8 @@ function runPhaseInternal(phase, contractFile, configFile, root, evidence, verif
         preflightSha256: fileHash(path.join(evidence, "test-preflight.json")), processExitCode: collection.processExitCode,
         expectedFailureCount: evaluation.summary.expectedRed, exitCode: 1, exitCodeMeaning: "approved-case-failure" }, true);
     }
-    if (phase === "green") atomic(path.join(evidence, "green-inventory.json"), { ...report, files, redSha256: fileHash(redFile), manifestSha256: fileHash(manifestFile) });
+    if (phase === "green") atomic(path.join(evidence, "green-inventory.json"), { ...report, files, redSha256: fileHash(redFile), manifestSha256: fileHash(manifestFile),
+      supplementSha256: supplement ? fileHash(path.join(evidence, "test-supplement.json")) : null });
     atomic(path.join(evidence, "inventory-status.json"), { ...report, nextAction: null });
     return report;
   } catch (error) {
@@ -406,7 +442,74 @@ function runPhaseInternal(phase, contractFile, configFile, root, evidence, verif
     throw error;
   }
 }
-module.exports = { identity, validateCollection, evaluateBaseline, evaluateCoverage, snapshot, testPatterns, isTest, runPhase };
+function supplementalEvidence(phase, root, config, contract, evidence, binding, baseline, manifest, patterns, excluded) {
+  const file = path.join(evidence, "test-supplement.json");
+  const original = manifest.testSnapshot, current = snapshot(root, config, patterns, excluded);
+  requireThat(original.every(item => current.some(candidate => same(item, candidate))), "EVIDENCE_CHANGED", "Original RED tests cannot be changed or deleted; approve a revised task for changed assertions");
+  const addedFiles = current.filter(item => !original.some(previous => previous.path === item.path));
+  const authorized = contract.verification.supplementalTests?.mode === "baselinePassingNewFiles";
+  const bound = { binding, redSha256: fileHash(path.join(evidence, "red.json")), manifestSha256: fileHash(path.join(evidence, "test-manifest.json")) };
+  if (fs.existsSync(file)) {
+    requireThat(authorized, "EVIDENCE_CHANGED", "Supplemental test permission was not approved");
+    const saved = read(file);
+    requireThat(saved.version === 1 && same(saved.bound, bound) && same(saved.addedFiles, addedFiles), "EVIDENCE_CHANGED", "Supplemental tests or their original RED binding changed");
+    checkFiles(evidence, saved.files);
+    requireThat(same(saved, read(path.join(evidence, saved.attemptPath, "supplement.json"))), "EVIDENCE_CHANGED", "Supplemental test report differs from its sealed attempt");
+    return saved;
+  }
+  if (!addedFiles.length) return null;
+  requireThat(phase === "green" && authorized, "EVIDENCE_CHANGED", "New test files require approved supplementalTests policy and a fresh GREEN; original RED remains frozen");
+  requireThat(addedFiles.length <= contract.maxChangedFiles && addedFiles.every(item =>
+    /\.(?:java|kt|groovy)$/.test(item.path) && contract.allowedPaths.some(pattern => matchesPath(pattern, item.path)) &&
+    !contract.forbiddenPaths.some(pattern => matchesPath(pattern, item.path))), "EVIDENCE_CHANGED", "Supplemental files must be new allowed test sources; resources and original assertions remain frozen");
+  const parent = path.join(evidence, "supplement-attempts"); fs.mkdirSync(parent, { recursive: true });
+  requireThat(fs.readdirSync(parent).length < contract.verification.supplementalTests.maxRevisions, "PREPARATION_BUDGET", "Supplemental revision budget exhausted; inspect retained evidence and approve a revised task");
+  const attemptPath = `supplement-attempts/${randomUUID()}`, attempt = path.join(evidence, attemptPath);
+  fs.mkdirSync(attempt);
+  const probe = path.join(attempt, "baseline-worktree"), sourceBefore = worktree(root, excluded);
+  let created = false;
+  try {
+    git(root, ["worktree", "add", "--detach", probe, binding.baselineHead]); created = true;
+    for (const item of addedFiles) {
+      const target = path.join(probe, localPath(probe, item.path));
+      requireThat(!fs.existsSync(target), "EVIDENCE_CHANGED", "Supplemental test overwrites a baseline file");
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, fs.readFileSync(path.join(root, item.path)), { flag: "wx", mode: item.mode });
+    }
+    // Only the SDK path may be passed to this diagnostic worktree. No ignored
+    // properties, credentials or arbitrary files are copied into model inputs.
+    const sourceBuild = require("./project.cjs").gradleBuildRoot(config, root);
+    const probeBuild = require("./project.cjs").gradleBuildRoot(config, probe);
+    const local = path.join(sourceBuild, "local.properties");
+    if (fs.existsSync(local)) {
+      const lines = fs.readFileSync(local, "utf8").split(/\r?\n/).filter(line => line.trim() && !/^\s*[#!]/.test(line));
+      requireThat(lines.every(line => /^\s*sdk\.dir\s*[=:]/.test(line) && !/\\$/.test(line)), "EVIDENCE_CHANGED", "Supplemental baseline requires explicit isolation setup for non-SDK local.properties entries");
+      fs.writeFileSync(path.join(probeBuild, "local.properties"), lines.join("\n") + "\n", { flag: "wx", mode: 0o600 });
+    }
+    const before = worktree(probe, excluded);
+    const collection = runGradle(probe, config, contract, "baseline", path.join(attempt, "collection"), false);
+    requireThat(before === worktree(probe, excluded) && sourceBefore === worktree(root, excluded) && same(current, snapshot(root, config, patterns, excluded)),
+      "INPUT_CHANGED_DURING_RUN", "Inputs changed while validating supplemental tests on the original baseline");
+    requireThat(same(collection.runtime, baseline.runtime), "EVIDENCE_CHANGED", "Supplemental baseline runtime differs from original baseline");
+    const expected = new Map(baseline.cases.map(item => [identity(item), item]));
+    requireThat(baseline.cases.every(item => collection.cases.some(result => identity(result) === identity(item) && result.result === item.result)),
+      "COVERAGE_MISMATCH", "Supplemental baseline changed existing regression outcomes");
+    const cases = collection.cases.filter(item => !expected.has(identity(item)));
+    requireThat(cases.length > 0 && cases.every(item => item.result === "SUCCESS" && !manifest.cases.some(original => identity(original) === identity(item))),
+      "CASE_EXPECTATION_MISMATCH", "Every new supplemental case must pass on the original baseline without replacing approved behavior identities");
+    git(root, ["worktree", "remove", "--force", probe]); created = false;
+    const saved = { version: 1, bound, addedFiles, cases, attemptPath, files: evidenceFiles(evidence, path.join(attempt, "collection")) };
+    atomic(path.join(attempt, "supplement.json"), saved, true);
+    atomic(file, saved, true);
+    return saved;
+  } catch (error) {
+    atomic(path.join(attempt, "failure.json"), { code: error.code ?? "SUPPLEMENT_FAILED", message: error.message });
+    throw error;
+  } finally {
+    if (created) git(root, ["worktree", "remove", "--force", probe]);
+  }
+}
+module.exports = { identity, validateCollection, evaluateBaseline, evaluateCoverage, matchesFailureOrigin, snapshot, testPatterns, isTest, runPhase };
 if (require.main === module) {
   const [phase, contractFile, configFile, root, evidence] = process.argv.slice(2);
   try {

package/templates/automation/verification/project.cjs

@@ -162,6 +162,64 @@ function validateConfigurationModel(config, root) {
     if (sources.some(p => config.protectedPaths.some(f => overlap(p, f.endsWith("/") ? f + "**" : f)))) fail("source paths overlap protected configuration");
 }
 exports.validateConfigurationModel = validateConfigurationModel;
+
+// Shared actual-runtime diagnostics. PATH java is only a launcher candidate;
+// it is never substituted for the wrapper's build JVM attestation.
+function parseBuildRuntime(output) {
+    const lines = output.split(/\r?\n/).filter(line => line.startsWith("ORCHESTRATOR_BUILD_RUNTIME="));
+    if (lines.length !== 1) throw new Error("Gradle did not produce exactly one actual build JVM record");
+    const value = JSON.parse(lines[0].slice("ORCHESTRATOR_BUILD_RUNTIME=".length));
+    if (value.version !== 1 || typeof value.gradleVersion !== "string" || !/^\d+\.\d+/.test(value.gradleVersion) ||
+        typeof value.javaVersion !== "string" || !/^(?:1\.)?\d+/.test(value.javaVersion) ||
+        typeof value.javaHome !== "string" || !isAbsolute(value.javaHome) || typeof value.javaVendor !== "string" ||
+        !Array.isArray(value.plugins) || !Array.isArray(value.tests)) throw new Error("Invalid actual Gradle/JVM record");
+    const java = Number(value.javaVersion.replace(/^1\./, "").match(/^\d+/)[0]);
+    if (/^6\.7(?:\.|$)/.test(value.gradleVersion) && (java < 8 || java > 15))
+        throw new Error("Gradle 6.7 requires an actual build JVM from Java 8 through 15");
+    for (const item of value.tests) if (!modulePath(item.task) || typeof item.executable !== "string" || !isAbsolute(item.executable))
+        throw new Error("Invalid test JVM record");
+    return value;
+}
+function inspectBuildRuntime(root, runner) {
+    const fs = require("node:fs"), path = require("node:path");
+    const executable = path.join(root, "gradlew");
+    const args = ["help", "--no-configuration-cache", "--console=plain", "--quiet", "--project-dir", root,
+        "--init-script", path.join(__dirname, "runtime.init.gradle")];
+    if (process.env.AUTOMATION_WORKER_TOKEN) args.push("--no-daemon");
+    const result = runner ? runner(executable, args) : require("node:child_process").spawnSync(executable, args,
+        { cwd: root, encoding: "utf8", timeout: 180000, maxBuffer: 8 * 1024 * 1024 });
+    if (result.status !== 0 || result.error) throw new Error(`Cannot verify the wrapper's actual Gradle/JVM: ${String(result.error ?? result.stderr ?? '').slice(-2000)}`);
+    return parseBuildRuntime(result.stdout);
+}
+function buildEnvironmentBinding(root, runtime) {
+    const fs = require("node:fs"), path = require("node:path"), crypto = require("node:crypto");
+    const hash = value => crypto.createHash("sha256").update(value).digest("hex");
+    const env = Object.fromEntries(["PATH", "JAVA_HOME", "JAVA_TOOL_OPTIONS", "JDK_JAVA_OPTIONS", "GRADLE_OPTS", "GRADLE_USER_HOME", "ANDROID_HOME", "ANDROID_SDK_ROOT"]
+        .map(key => [key, process.env[key] ?? null]));
+    const home = process.env.GRADLE_USER_HOME ?? path.join(require("node:os").homedir(), ".gradle");
+    const files = [path.join(home, "gradle.properties"), path.join(home, "init.gradle"), path.join(home, "init.gradle.kts"),
+        path.join(root, "gradle.properties"), path.join(root, "local.properties"), path.join(root, "gradle/gradle-daemon-jvm.properties")];
+    const init = path.join(home, "init.d");
+    if (fs.existsSync(init)) files.push(...fs.readdirSync(init).sort().filter(name => /\.gradle(?:\.kts)?$/.test(name)).map(name => path.join(init, name)));
+    const homes = [process.env.JAVA_HOME, runtime?.javaHome].filter(Boolean);
+    for (const javaHome of homes) files.push(path.join(javaHome, "bin/java"), path.join(javaHome, "release"));
+    if (runtime) files.push(...runtime.tests.map(test => test.executable));
+    const inputs = [...new Set(files)].sort().map(file => [file, fs.existsSync(file) ? hash(fs.readFileSync(file)) : null]);
+    return hash(JSON.stringify({ env, inputs }));
+}
+exports.parseBuildRuntime = parseBuildRuntime;
+exports.inspectBuildRuntime = inspectBuildRuntime;
+exports.buildEnvironmentBinding = buildEnvironmentBinding;
+function assertIsolatedBuildEnvironment(root) {
+    const fs = require("node:fs"), path = require("node:path");
+    const local = path.join(root, "local.properties");
+    if (!fs.existsSync(local)) return;
+    if (fs.lstatSync(local).isSymbolicLink()) throw new Error("Isolated builds require a regular local.properties file");
+    const lines = fs.readFileSync(local, "utf8").split(/\r?\n/).filter(line => line.trim() && !/^\s*[#!]/.test(line));
+    if (!lines.every(line => /^\s*sdk\.dir\s*[=:]/.test(line) && !/\\$/.test(line)))
+        throw new Error("ISOLATED_ENVIRONMENT_UNDECLARED: local.properties contains non-SDK inputs. Configure them through reviewed tracked build configuration or use an explicitly approved fixed-branch task; ignored files are not copied to worktrees.");
+}
+exports.assertIsolatedBuildEnvironment = assertIsolatedBuildEnvironment;
 if (require.main === module) {
     try {
         const config = JSON.parse(require("node:fs").readFileSync(process.argv[2], "utf8"));

package/templates/automation/verification/recovery.cjs

@@ -133,12 +133,11 @@ function inputBinding(root, contractFile, configFile, contract, allowProduct = f
     }
     return [file, stat.mode & 0o777, hash(stat.isSymbolicLink() ? fs.readlinkSync(absolute) : fs.readFileSync(absolute))];
   });
-  const java = cp.spawnSync("java", ["-version"], { encoding: "utf8", timeout: 10000 });
-  assert(java.status === 0, "Cannot identify the Java toolchain for baseline recovery");
   const environment = Object.fromEntries(["JAVA_HOME", "JAVA_TOOL_OPTIONS", "JDK_JAVA_OPTIONS", "GRADLE_OPTS", "GRADLE_USER_HOME", "ANDROID_HOME", "ANDROID_SDK_ROOT"].map(key => [key, process.env[key] ?? null]));
   const localProperties = path.join(require("./project.cjs").gradleBuildRoot(read(configFile), root), "local.properties");
   return { contractSha256: fileHash(contractFile), configSha256: fileHash(configFile), head: git(root, ["rev-parse", "HEAD"]).trim(),
-    inputsSha256: digest(inputs), excludedPathsSha256: digest(excluded), environmentSha256: digest(environment), javaSha256: hash(java.stdout + java.stderr), node: process.version,
+    inputsSha256: digest(inputs), excludedPathsSha256: digest(excluded), environmentSha256: digest(environment),
+    buildEnvironmentSha256: require("./project.cjs").buildEnvironmentBinding(require("./project.cjs").gradleBuildRoot(read(configFile), root)), node: process.version,
     localPropertiesSha256: fs.existsSync(localProperties) ? fileHash(localProperties) : null };
 }
 function artifactHashes(evidence, directory) {