rename cli helper for convenience

Author: Protonk

CONTRIBUTING.md

@@ -18,7 +18,7 @@ If a change affects behavior, outputs, or safety boundaries, it needs matching w
 Preferred coverage options (in roughly increasing integration cost):
 
 - Rust unit tests for pure logic
-- Rust integration tests in `controller/tests/`
+- Rust integration tests in `controller/integration/`
 - Smoke scripts in `tests/suites/smoke/` against a built `PolicyWitness.app`
 
 ### Write Swift like you want it trivially reverse-engineered

controller/Cargo.toml

@@ -12,6 +12,10 @@ path = "src/main.rs"
 name = "sandbox-log-observer"
 path = "src/bin/sandbox-log-observer.rs"
 
+[[test]]
+name = "cli_contract"
+path = "integration/cli_contract.rs"
+
 [dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

controller/tests/cli_integration.rs controller/integration/cli_contract.rscontroller/tests/cli_integration.rs renamed to controller/integration/cli_contract.rs

@@ -1,3 +1,9 @@
+//! CLI contract integration tests for the controller binary.
+//!
+//! These tests run the built PolicyWitness.app to validate the end-to-end
+//! envelope shape and instrumentation injection behavior. They are gated behind
+//! PW_INTEGRATION=1 so `cargo test --tests` can run without a built app.
+
 use std::env;
 use std::path::{Path, PathBuf};
 use std::process::{Command, Output};
@@ -15,6 +21,7 @@ fn repo_root() -> PathBuf {
 
 fn pw_bin_path() -> PathBuf {
     if let Ok(val) = env::var("PW_BIN_PATH") {
+        // Allow CI or local runs to point at a non-standard build location.
         return PathBuf::from(val);
     }
     repo_root()
@@ -27,6 +34,7 @@ fn pw_bin_path() -> PathBuf {
 fn require_pw_bin() -> PathBuf {
     let path = pw_bin_path();
     if !path.exists() {
+        // The integration suite assumes a built app bundle is available.
         panic!(
             "PolicyWitness.app not found at {} (build the app or set PW_BIN_PATH)",
             path.display()
@@ -49,8 +57,8 @@ fn specimen_smoke_file_read_deny() {
     }
     let bin = require_pw_bin();
 
-    // Note: sandboxed automation harnesses can block XPC lookup or unified log access.
-    // If this test fails with those symptoms, rerun from a normal Terminal to confirm.
+    // Sandboxed harnesses can block XPC lookup or unified log access; rerun from
+    // a normal Terminal if failures look environment-related.
 
     let specimen = repo_root()
         .join("tests")

tests/README.md

@@ -70,7 +70,7 @@ see `tests/suites/<suite>/README.md`.
 
 - `preflight`: codesign/entitlements inspection only (no execution)
 - `unit`: Rust unit tests (`cargo test --bins`)
-- `integration`: Rust integration tests (`cargo test --tests`), primarily `controller/tests/cli_integration.rs`
+- `integration`: Rust integration tests (`cargo test --tests`), primarily `controller/integration/cli_contract.rs`
 - `runner_debuggable`: smoke + blackbox coverage via the built-in debuggable runner
 - `runner_byoxpc`: smoke + blackbox coverage via a BYOXPC runner (opt-in)
 - `runner_machme`: smoke + blackbox coverage via a MachMe runner (opt-in)

tests/suites/integration/README.md

@@ -7,6 +7,7 @@ Rust integration tests that exercise the CLI contract against a built app.
 - Uses `PolicyWitness.app/Contents/MacOS/policy-witness` to run specimens.
 - Validates the controller envelope and runner result shape.
 - Exercises instrumentation injection and duplicate protection.
+- Test source lives at `controller/integration/cli_contract.rs`.
 
 ## Success criteria