feat: aggregate per-platform acceptance reports into a verification matrix

AGENTS.md

@@ -75,6 +75,15 @@ development substitute, or refresh expected evidence merely to make a change
 green. A skipped, unrun, timed-out, or wrong-platform required suite means the
 work is not complete.
 
+A change touching a guaranteed desktop capability is incomplete until the
+required acceptance suites pass on Windows, macOS, and Linux. The local
+operating system determines only which checks can run locally; it does not
+reduce the required verification scope. Archive every platform leg's
+`acceptance --json` report and prove the union with
+`raco rivet matrix <reports...> --json` (issue #287). Classify desktop
+capabilities as guaranteed, conditional, or platform-specific as documented
+in `docs/product-acceptance.md`.
+
 For this repository, inspect the nearest implementation and its tests before
 editing. The shared wire contract is documented in `docs/protocol.md` and
 exercised by `rivet/tests/protocol-golden.txt` across Racket, C++, Swift, and Kotlin.

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+- Make cross-platform verification first-class. `raco rivet matrix
+  <report.json>... [--json]` folds the per-platform `acceptance --json`
+  reports for one commit into a single machine-readable verdict: a required
+  kind/platform cell is proven only by a passing suite on that platform,
+  missing platforms are never silently green, and the exit code is green only
+  when every required cell is proven — so an agent editing on one OS can
+  still be judged by the other platforms' evidence. `docs/product-acceptance.md`
+  now defines the guaranteed / conditional / platform-specific capability
+  classification, and the maintainer contract states that the local
+  operating system does not reduce the required verification scope.
+
 - Ship the Windows runtime source list as a machine-consumable property
   sheet. `platform/windows/rivet-runtime-sources.props` is now the single
   author of the host library's `<ClCompile>` set — `rivet-host.vcxproj`

docs/agent-native.md

@@ -210,6 +210,14 @@ output bounds, checks exit status and declared artifacts, and returns a
 machine-readable report suitable for a required CI check. See
 [product acceptance evidence](product-acceptance.md).
 
+The local operating system bounds only which suites can run locally, not the
+required verification scope. Archive every platform leg's
+`acceptance --json` report as a CI artifact and judge the union with
+`raco rivet matrix <reports...> --json`: a change touching a guaranteed
+desktop capability is incomplete until the required suites are proven on
+every declared platform. Fix, then re-run only the affected platform's leg
+and re-aggregate.
+
 `build` validates the Racket schema and regenerates typed native clients.
 `package` creates and immediately verifies a development distributable.
 `verify` can audit the artifact again without rebuilding it. Production mode

docs/product-acceptance.md

@@ -89,6 +89,65 @@ commit with the acceptance report. A dirty, diverged, or unreachable checkout
 is a reason to stop and report the state, not a reason to stash, reset, or
 claim evidence against an unknown base.
 
+## Classify desktop capabilities
+
+Not every desktop capability carries the same parity obligation. Declare each
+one as one of three categories and let the category drive the requirements
+list:
+
+- **Guaranteed** — the same semantics are required on every declared desktop
+  platform; a missing platform is a release failure. These become
+  `requirements` entries with all desktop platforms and suites of the matching
+  kinds.
+- **Conditional capability** — the same API and semantics everywhere, but
+  runtime availability may differ: tray, global shortcuts, secure storage,
+  notifications. The adapter must report supported/unavailable/permission
+  state explicitly instead of failing silently, and suites assert the
+  reported state, not unconditional success.
+- **Platform-specific** — intentionally native-only behavior with no forced
+  cross-platform abstraction. It is excluded from the requirements list;
+  platform-specific does not mean unverified, it means verified by that
+  platform's own suites.
+
+The goal is semantic parity, not identical visual behavior. Native SwiftUI,
+WinUI, and GTK presentations are expected to differ; the acceptance evidence
+(accessibility state, RPC effects, declared artifacts) must not.
+
+A Guaranteed feature is not complete until every declared platform has run
+its suites — which is what the matrix below proves.
+
+## Aggregate the cross-platform matrix
+
+The local operating system is an editing environment, not the boundary of
+verification. Each platform leg archives its acceptance report as a CI
+artifact; the matrix folds the reports for one commit into a single verdict:
+
+```bash
+raco rivet matrix windows-report.json macos-report.json linux-report.json
+raco rivet matrix windows-report.json --json
+```
+
+```text
+Rivet verification matrix: Taskly - 3 reports
+
+  requirement    windows     macos     linux
+  contract          PASS      PASS      PASS
+  native-ui         PASS      PASS      FAIL
+
+Cross-platform status: FAIL
+```
+
+The rules are deterministic: a cell is proven only by a passing suite of that
+kind in a report from that platform; ran-but-failed evidence fails the cell;
+no evidence for a platform means missing, never silently green. All reports
+must describe the same project, so one product's green leg cannot vouch for
+another. A diagnostic `--suite` run is accepted and flagged as partial in the
+matrix, but merge gates should feed complete reports. The exit code is green
+only when every required kind/platform cell is proven.
+
+Feed the reports for the commit under verification; the matrix aggregates
+what it is given and does not heuristically prefer fresher runs.
+
 ## What counts as complete
 
 RackUnit is the normal owner of shared Racket behavior. A product that claims

rivet-cli/acceptance.rkt

@@ -17,6 +17,7 @@
 
 (provide default-acceptance-manifest-name
          acceptance-kinds
+         supported-platforms
          (struct-out acceptance-suite)
          load-acceptance-manifest
          acceptance-report

rivet-cli/main.rkt

@@ -40,6 +40,9 @@
     "  raco rivet inspect --json          emit the agent-readable project contract\n"
     "  raco rivet acceptance              run the current platform's declared acceptance suites\n"
     "  raco rivet acceptance --json       emit bounded machine-readable acceptance evidence\n"
+    "  raco rivet matrix <report.json>... aggregate per-platform acceptance reports into the\n"
+    "                                     cross-platform verification matrix\n"
+    "  raco rivet matrix <report.json>... --json  emit the machine-readable matrix\n"
     "  raco rivet schema --json           emit the current versioned API schema\n"
     "  raco rivet schema --output <file>  write a schema compatibility baseline\n"
     "  raco rivet schema check <file>     reject breaking changes from a baseline\n"
@@ -111,6 +114,12 @@
      (define run-acceptance-command
        (command "acceptance" 'run-acceptance-command))
      (exit (run-acceptance-command (current-project!) acceptance-args))]
+    [(cons "matrix" matrix-args)
+     ;; Matrix aggregation consumes report artifacts, not a project checkout,
+     ;; so it runs anywhere: on an editing host far from the platform legs it
+     ;; is judging (issue #287).
+     (define run-matrix-command (command "matrix" 'run-matrix-command))
+     (exit (run-matrix-command matrix-args))]
     [(list "schema" "--json")
      (define schema-snapshot (command "codegen" 'schema-snapshot))
      (write-json (schema-snapshot (current-project!)))