test(contracts): establish C10 evidence foundation and C01 RED process tests

Add shared, hash-locked synthetic argv vectors and a Java 8-compatible child probe.
Add fail-closed layered Surefire reporting with 12 self-tests and pinned OpenSpec strict CI.
This is the intentional C01 RED checkpoint; no product Java sources changed.
Keep C10 integration and the remaining OpenSpec changes open.

Author: loong10k

.github/workflows/contracts.yml

@@ -0,0 +1,126 @@
+name: OpenCLI Contracts
+
+on:
+  push:
+    branches:
+      - 'feature/1.0.x'
+      - 'feature/2.0.x'
+      - 'feature/3.0.x'
+      - 'feature/*-contract-hardening'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  specification:
+    name: OpenSpec strict and evidence-runner tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      OPENSPEC_TELEMETRY: '0'
+      DO_NOT_TRACK: '1'
+      CI: 'true'
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Verify report runner and shared fixture hashes
+        run: |
+          python3 -m unittest discover -s scripts/tests -v
+          (cd src/test/resources/opencli-contracts/v1 && sha256sum -c SHA256SUMS)
+      - name: Install pinned official OpenSpec
+        run: npm install --prefix "$RUNNER_TEMP/opencli-openspec" --ignore-scripts --no-audit --no-fund @fission-ai/openspec@1.13.1
+      - name: Validate all proposals and each change with strict mode
+        shell: bash
+        run: |
+          export PATH="$RUNNER_TEMP/opencli-openspec/node_modules/.bin:$PATH"
+          mkdir -p .spec-evidence
+          openspec --version | tee .spec-evidence/version.txt
+          openspec list --json > .spec-evidence/list.json
+          failed=0
+          for path in openspec/changes/*; do
+            [[ -d "$path" && "$(basename "$path")" != archive ]] || continue
+            change="$(basename "$path")"
+            if openspec validate "$change" --strict --no-interactive > ".spec-evidence/$change.log" 2>&1; then
+              printf '%s\tPASS\n' "$change"
+            else
+              cat ".spec-evidence/$change.log"
+              failed=1
+            fi
+          done
+          if ! openspec validate --all --strict --no-interactive > .spec-evidence/all.log 2>&1; then
+            cat .spec-evidence/all.log
+            failed=1
+          fi
+          exit "$failed"
+      - name: Upload specification evidence
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: openspec-strict-${{ github.sha }}
+          path: .spec-evidence
+          if-no-files-found: error
+
+  jvm:
+    name: Branch-specific JVM contract verification
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - name: Select declared branch line
+        id: line
+        shell: bash
+        run: |
+          case "$GITHUB_REF_NAME" in
+            feature/1.0.x*) echo 'java=8' >> "$GITHUB_OUTPUT" ;;
+            feature/2.0.x*) echo 'java=17' >> "$GITHUB_OUTPUT" ;;
+            feature/3.0.x*) echo 'java=21' >> "$GITHUB_OUTPUT" ;;
+            *) echo 'Unsupported branch line' >&2; exit 1 ;;
+          esac
+      - uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: ${{ steps.line.outputs.java }}
+          cache: maven
+      - name: Record exact source and actual tools
+        run: |
+          mkdir -p .contract-evidence
+          git rev-parse HEAD > .contract-evidence/head.txt
+          java -version > .contract-evidence/java.txt 2>&1
+          bash ./mvnw -version > .contract-evidence/maven.txt 2>&1
+      - name: Full clean verify using this branch wrapper
+        id: verify
+        shell: bash
+        run: |
+          set +e
+          bash ./mvnw -B --no-transfer-progress clean verify > .contract-evidence/maven.log 2>&1
+          result=$?
+          printf '%s\n' "$result" > .contract-evidence/maven.exit
+          tail -100 .contract-evidence/maven.log
+          exit "$result"
+      - name: Require nonempty, non-skipped contract evidence
+        if: always()
+        shell: bash
+        run: |
+          test -f .contract-evidence/maven.exit
+          python3 scripts/contract_report.py \
+            --reports target/surefire-reports \
+            --head "$(cat .contract-evidence/head.txt)" \
+            --branch "$GITHUB_REF_NAME" \
+            --java-version-file .contract-evidence/java.txt \
+            --maven-version-file .contract-evidence/maven.txt \
+            --exit-code "$(cat .contract-evidence/maven.exit)" \
+            --suite argv=io.github.easy4j.opencli.contract.OpenCliArgvContractTest \
+            --output .contract-evidence/report.json
+      - name: Upload actual JVM evidence
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: contracts-jdk-${{ steps.line.outputs.java }}-${{ github.sha }}
+          path: |
+            .contract-evidence
+            target/surefire-reports
+            target/site/jacoco
+          if-no-files-found: error

docs/implementation/c10-c01-execution.md

@@ -0,0 +1,23 @@
+# C10 foundation and C01 implementation ledger
+
+## Approved ordering and scope
+
+The user approved C10 foundation, then C01/C02/C03/C04/C05/C09, then C06/C07/C08, and only then C10 integration closure. `feature/2.0.x` is the canonical implementation line. This file records execution, not completion of the ten changes.
+
+An isolated implementation branch starts at `d0c8056990f7a47fcc202acffa387ba066bcfc67`. The 1.x/3.x baseline refs and permitted JDK/Jackson/Maven differences are recorded in `src/test/resources/opencli-contracts/v1/sources.lock.json`. No changes to `main`, dependency versions or coverage thresholds are part of this increment.
+
+## C10 foundation
+
+Shared synthetic UTF-8/base64 argv vectors preserve empty and trailing empty fields. They have content hashes and a specification ref, not an invented upstream capture provenance. A Java 8-compatible child prints each actual argument. The regression suite uses the real SDK executor, adapter and Browser paths; a Recording executor is not used to prove process behavior.
+
+The report runner separates enumeration, argv, protocol, typed-result and real-execution evidence. Only explicitly selected suites contribute; the real-execution layer remains NOT_RUN because a Java argv probe is not a live OpenCLI website test. Missing reports, zero tests, skipped required tests, nonzero Maven exit, malformed XML and inconsistent testcase counts fail closed.
+
+Local runner TDD: 12 failures before the runner existed, then 12 passing tests. The probe compiled with `javac --release 8` on JDK 21 and emitted an empty token unchanged. This does not constitute an actual JDK 8 runtime test. Full JVM evidence is produced by the branch-specific GitHub Actions workflow using each line's checked-in Maven wrapper.
+
+## C01 RED checkpoint
+
+The initial Java contract suite deliberately demands lossless values before any product source is changed. The first CI run must be inspected for assertion failures at the real child boundary, not treated as a completed fix. Compilation errors or tool setup failures are not valid RED proof.
+
+## Still open
+
+C01 schema-aware repeated/false option handling, C02/C03/C04/C05/C09 production fixes, discovery, Browser result models, context/diagnostics and three-branch integration closure are not complete. Official OpenSpec strict is configured but must be observed at the exact workflow run before claiming it passed. No OpenSpec implementation tasks are pre-checked.

scripts/contract_report.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Build fail-closed, layer-specific evidence from real Surefire XML reports.
+
+This is not a code coverage percentage or a claim that OpenCLI websites work.
+Only explicitly selected suites contribute to a layer. No network is used.
+"""
+import argparse
+import json
+import pathlib
+import re
+import sys
+import xml.etree.ElementTree as ET
+
+LAYERS = ('enumeration', 'argv', 'protocol', 'typed-result', 'real-execution')
+
+
+def _suite_summary(suite):
+    declared = {key: int(suite.attrib.get(key, '0')) for key in ('tests', 'failures', 'errors', 'skipped')}
+    cases = suite.findall('testcase')
+    actual = {'tests': len(cases), 'failures': sum(c.find('failure') is not None for c in cases),
+              'errors': sum(c.find('error') is not None for c in cases),
+              'skipped': sum(c.find('skipped') is not None for c in cases)}
+    if declared != actual or any(v < 0 for v in declared.values()):
+        raise ValueError('declared testcase counts disagree with XML evidence')
+    actual['executed'] = actual['tests'] - actual['skipped']
+    return actual
+
+
+def build_report(reports_dir, *, head, branch, java_version, maven_version, exit_code, required_suites):
+    """Return a JSON-serializable report; malformed/missing evidence fails closed."""
+    problems = []
+    if not re.fullmatch(r'[0-9a-fA-F]{40}', head or ''):
+        problems.append('exact 40-character source HEAD is required')
+    if not branch or not java_version.strip() or not maven_version.strip():
+        problems.append('branch and actual tool versions are required')
+    if exit_code != 0:
+        problems.append('verification command exited nonzero')
+    if not required_suites or any(layer not in LAYERS or not names for layer, names in required_suites.items()):
+        problems.append('non-empty required suites must use recognized layers')
+    suites = {}
+    for path in sorted(pathlib.Path(reports_dir).glob('TEST-*.xml')):
+        try:
+            root = ET.parse(path).getroot()
+            nodes = [root] if root.tag == 'testsuite' else list(root.findall('testsuite'))
+            if not nodes:
+                raise ValueError('no testsuite')
+            for suite in nodes:
+                name = suite.attrib['name']
+                if name in suites:
+                    raise ValueError('duplicate testsuite')
+                suites[name] = _suite_summary(suite)
+        except (ET.ParseError, OSError, KeyError, ValueError):
+            # Do not copy testcase failure bodies or captured application output.
+            problems.append('invalid or duplicate Surefire report: ' + path.name)
+    layers = {}
+    for layer in LAYERS:
+        names = list(required_suites.get(layer, []))
+        counts = dict.fromkeys(('tests', 'executed', 'skipped', 'failures', 'errors'), 0)
+        missing = [name for name in names if name not in suites]
+        for name in names:
+            for key in counts:
+                counts[key] += suites.get(name, {}).get(key, 0)
+        state = 'NOT_RUN'
+        if names:
+            state = 'PASS' if (not missing and counts['executed'] > 0 and
+                               not any(counts[key] for key in ('skipped', 'failures', 'errors'))) else 'FAIL'
+        layers[layer] = dict(counts, status=state, requiredSuites=names, missingSuites=missing)
+        if state == 'FAIL':
+            problems.append('required layer lacks passing, non-skipped execution: ' + layer)
+    return {'schemaVersion': 1, 'status': 'FAIL' if problems else 'PASS',
+            'head': head, 'branch': branch, 'javaVersion': java_version,
+            'mavenVersion': maven_version, 'commandExitCode': exit_code,
+            'layers': layers, 'problems': problems,
+            'scope': 'Explicit Surefire suites only; synthetic argv probes are not live OpenCLI verification.'}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--reports', type=pathlib.Path, required=True)
+    parser.add_argument('--head', required=True)
+    parser.add_argument('--branch', required=True)
+    parser.add_argument('--java-version-file', type=pathlib.Path, required=True)
+    parser.add_argument('--maven-version-file', type=pathlib.Path, required=True)
+    parser.add_argument('--exit-code', type=int, required=True)
+    parser.add_argument('--suite', action='append', required=True, help='layer=fully.qualified.TestClass; repeatable')
+    parser.add_argument('--output', type=pathlib.Path, required=True)
+    args = parser.parse_args(argv)
+    required = {}
+    for item in args.suite:
+        layer, separator, name = item.partition('=')
+        if not separator or layer not in LAYERS or not name:
+            parser.error('--suite must be recognized-layer=fully.qualified.TestClass')
+        if name in required.setdefault(layer, []):
+            parser.error('duplicate --suite')
+        required[layer].append(name)
+    try:
+        report = build_report(args.reports, head=args.head, branch=args.branch,
+                              java_version=args.java_version_file.read_text(encoding='utf-8'),
+                              maven_version=args.maven_version_file.read_text(encoding='utf-8'),
+                              exit_code=args.exit_code, required_suites=required)
+    except OSError as exc:
+        print('Missing tool-version evidence: ' + exc.__class__.__name__, file=sys.stderr)
+        return 1
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(json.dumps(report, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
+    print(json.dumps({'status': report['status'], 'head': report['head'], 'layers': report['layers']}))
+    return 0 if report['status'] == 'PASS' else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

scripts/tests/test_contract_report.py

@@ -0,0 +1,96 @@
+import importlib.util
+import json
+import pathlib
+import tempfile
+import unittest
+
+SCRIPT = pathlib.Path(__file__).resolve().parents[1] / 'contract_report.py'
+HEAD = 'd0c8056990f7a47fcc202acffa387ba066bcfc67'
+SUITE = 'io.github.easy4j.opencli.contract.OpenCliArgvContractTest'
+
+
+class ContractReportTest(unittest.TestCase):
+    def setUp(self):
+        self.assertTrue(SCRIPT.is_file(), 'C10 contract report runner is not implemented')
+        spec = importlib.util.spec_from_file_location('contract_report', SCRIPT)
+        self.module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(self.module)
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = pathlib.Path(self.temp.name)
+
+    def xml(self, tests=2, skipped=0, failures=0, errors=0):
+        executed = tests - skipped
+        cases = []
+        for i in range(tests):
+            child = '<skipped/>' if i >= executed else ('<failure/>' if i < failures else ('<error/>' if i < failures + errors else ''))
+            cases.append('<testcase name="case' + str(i) + '">' + child + '</testcase>')
+        (self.root / ('TEST-' + SUITE + '.xml')).write_text(
+            '<testsuite name="' + SUITE + '" tests="' + str(tests) + '" skipped="' + str(skipped)
+            + '" failures="' + str(failures) + '" errors="' + str(errors) + '">' + ''.join(cases) + '</testsuite>', encoding='utf-8')
+
+    def report(self, **kwargs):
+        return self.module.build_report(self.root, head=kwargs.get('head', HEAD),
+            branch='feature/2.0.x', java_version='openjdk 17 (test fixture)',
+            maven_version='Apache Maven (test fixture)', exit_code=kwargs.get('exit_code', 0),
+            required_suites={'argv': [SUITE]})
+
+    def test_complete_argv_evidence_passes_but_live_is_not_run(self):
+        self.xml()
+        report = self.report()
+        self.assertEqual('PASS', report['status'])
+        self.assertEqual(2, report['layers']['argv']['executed'])
+        self.assertEqual('NOT_RUN', report['layers']['real-execution']['status'])
+        self.assertEqual(HEAD, report['head'])
+        json.dumps(report)
+
+    def test_missing_report_fails(self):
+        self.assertEqual('FAIL', self.report()['status'])
+
+    def test_zero_tests_fails(self):
+        self.xml(tests=0)
+        self.assertEqual('FAIL', self.report()['status'])
+
+    def test_all_skipped_fails(self):
+        self.xml(tests=2, skipped=2)
+        self.assertEqual('FAIL', self.report()['status'])
+
+    def test_partly_skipped_fails(self):
+        self.xml(tests=2, skipped=1)
+        self.assertEqual('FAIL', self.report()['status'])
+
+    def test_failure_fails(self):
+        self.xml(failures=1)
+        self.assertEqual('FAIL', self.report()['status'])
+
+    def test_error_fails(self):
+        self.xml(errors=1)
+        self.assertEqual('FAIL', self.report()['status'])
+
+    def test_nonzero_command_exit_fails_despite_green_xml(self):
+        self.xml()
+        self.assertEqual('FAIL', self.report(exit_code=1)['status'])
+
+    def test_malformed_xml_fails_closed(self):
+        (self.root / 'TEST-broken.xml').write_text('<broken', encoding='utf-8')
+        self.assertEqual('FAIL', self.report()['status'])
+
+    def test_partial_sha_is_not_accepted(self):
+        self.xml()
+        self.assertEqual('FAIL', self.report(head='d0c8056')['status'])
+
+    def test_declared_counts_cannot_hide_missing_testcases(self):
+        self.xml()
+        path = self.root / ('TEST-' + SUITE + '.xml')
+        path.write_text(path.read_text().replace('tests="2"', 'tests="100"'), encoding='utf-8')
+        self.assertEqual('FAIL', self.report()['status'])
+
+    def test_undeclared_failure_fails(self):
+        self.xml()
+        path = self.root / ('TEST-' + SUITE + '.xml')
+        path.write_text(path.read_text().replace('</testcase>', '<failure/></testcase>', 1), encoding='utf-8')
+        self.assertEqual('FAIL', self.report()['status'])
+
+
+if __name__ == '__main__':
+    unittest.main()

src/test/java/io/github/easy4j/opencli/contract/ContractProbe.java

@@ -0,0 +1,16 @@
+package io.github.easy4j.opencli.contract;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+/** Offline child process: emits every actual JVM argument, including empty values. */
+public final class ContractProbe {
+    private ContractProbe() { }
+
+    public static void main(String[] args) {
+        System.out.println("argc:" + args.length);
+        for (String arg : args) {
+            System.out.println("arg:" + Base64.getEncoder().encodeToString(arg.getBytes(StandardCharsets.UTF_8)));
+        }
+    }
+}