F1.5: live-contract test tier — verified beliefs about real tools (#36)

.github/workflows/live-contract.yml

@@ -0,0 +1,25 @@
+# HOOK PARITY note: this workflow is the OPT-IN tier-3 live-contract run
+# (#36) — deliberately host-dependent, never part of PR CI (ci.yml is the
+# host-independent gate mirrored by .githooks/pre-push). Scheduled so mock
+# fixture drift against real CLIs surfaces on a cadence, not at 7am.
+name: Live contract
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 9 * * 1" # weekly, Monday
+
+jobs:
+  live:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Live-contract tests (tools present on the runner run; absent skip)
+        env:
+          MODULEX_LIVE_TESTS: "1"
+          # gh is preinstalled on GitHub runners; authenticate it with the
+          # workflow token so the gh --json shape test runs.
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: cargo test -p modulex-core --test live_contract -- --nocapture

CLAUDE.md

@@ -45,7 +45,10 @@ Standing law from it:
    for engine faults (bad config, unknown routine, leash denial of the run).
 6. **Unit tests never spawn real processes.** Use
    `exec::test_support::MockSpawner`. Real-subprocess coverage lives in the
-   dedicated gated integration test only.
+   dedicated gated integration test plus the opt-in live-contract tier
+   (`just live-test`, `MODULEX_LIVE_TESTS=1`) which verifies mock fixtures
+   against real tools — mock fixtures mimicking a real CLI carry a
+   FIXTURE-SYNC comment citing their live test.
 
 ## Build & validate