docs: add Rule 8 (CI Gate Completeness) + update binary exceptions (pv, ttop)

Rule 8 addresses the five-whys root cause of PR #726 breaking main:
the spec said "CI must pass" but ci/gate silently skipped security.
Now all 4 quality dimensions (test, lint, coverage, security) block merge.

Also: workspace-test added to branch protection required checks.

Binary audit: pv and ttop are permanent standalone tool exceptions,
not legacy-to-migrate.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: noahgift

.github/workflows/ci.yml

@@ -28,7 +28,7 @@ jobs:
       repo: ${{ github.event.repository.name }}
     secrets: inherit
 
-  # APR-MONO: Workspace-wide test (all 70 crates)
+  # APR-MONO: Workspace-wide test (all 75 crates)
   workspace-test:
     runs-on: self-hosted
     container:
@@ -48,6 +48,14 @@ jobs:
           cargo test -p aprender-core --test monorepo_invariants
           cargo test -p aprender-core --test readme_contract
           cargo test -p apr-cli --test cli_commands
+      - name: Fix file ownership (container runs as root, runner as noah:1000)
+        if: always()
+        run: |
+          # Five-whys: Docker container creates files as root on bind-mounted
+          # workspace. Runner (noah:1000) can't git-clean them on next run
+          # → checkout fails → CI breaks. This runs inside the container
+          # (as root) restoring host ownership for subsequent bare-metal jobs.
+          chown -R 1000:1000 "$GITHUB_WORKSPACE" || true
 
   mutants:
     runs-on: self-hosted

contracts/apr-mono-binary-rule-v1.yaml

@@ -17,37 +17,38 @@ equations:
       For all crates C in workspace:
         C.has_user_facing_binary => C == apr-cli
       "User-facing" = installed by `cargo install aprender`, has --help
-      "Build-tool" = standalone dev tooling (pv)
+      "Standalone" = independent tool with its own install/use case (pv, ttop)
       "Internal" = called by apr-cli as subprocess, or dev-only
       "Legacy" = pre-merge binary, functionality subsumed by `apr` subcommand
     domain: all workspace Cargo.toml files
     codomain: bool
     invariants:
-    - "apr (from apr-cli) is the ONLY user-facing binary"
-    - "pv (from aprender-contracts-cli) is the only build-tool exception"
+    - "apr (from apr-cli) is the ONLY user-facing ML binary"
+    - "pv (aprender-contracts-cli) is a standalone build tool — not an apr subcommand"
+    - "ttop (aprender-viz-ttop) is a standalone system monitor — not an apr subcommand"
     - "Internal binaries must document their justification"
     - "Legacy binaries must have a migration plan to apr subcommand"
 
   binary_audit_2026_04_10:
     formula: |
-      22 crates with [[bin]], 24 total binary targets.
+      20 crates with [[bin]], 21 total binary targets.
       Classification:
 
       USER-FACING (1 crate, 1 binary):
-        apr-cli                -> apr              # THE user-facing binary
+        apr-cli                -> apr              # THE user-facing ML binary
 
-      BUILD-TOOL (1 crate, 1 binary):
-        aprender-contracts-cli -> pv               # Contract validation (Rule 2 exception)
+      STANDALONE TOOLS (2 crates, 2 binaries — permanent exceptions):
+        aprender-contracts-cli -> pv               # Build tool: contract validation, pre-commit, CI
+        aprender-viz-ttop      -> aprender-viz-ttop    # System monitor: GPU/CPU, independent of ML workflow
 
-      INTERNAL-HELPER (8 crates, 9 binaries):
+      INTERNAL-HELPER (7 crates, 8 binaries):
         aprender-cbtop         -> aprender-cbtop   # GPU monitor, called by `apr monitor`
         aprender-present-cli   -> presentar        # TUI server, called by `apr present`
         aprender-present-terminal -> score, ptop   # TUI widgets, used by presentar
         aprender-ptx-debug     -> aprender-ptx-debug  # CUDA PTX debugger (dev-only)
         aprender-test-cli      -> aprender-test-cli    # WASM test runner (dev-only)
         aprender-train-bench   -> aprender-train-bench # Training benchmark harness
         aprender-train-shell   -> aprender-train-shell # Interactive training REPL
-        aprender-viz-ttop      -> aprender-viz-ttop    # Standalone ttop (excluded from workspace)
 
       QA-TOOL (2 crates, 2 binaries — from Phase 2g port):
         aprender-qa-cli        -> apr-qa           # QA playbook runner (to wire into `apr qa`)

docs/specifications/aprender-monorepo-consolidation.md

@@ -84,7 +84,7 @@
 | ~~`#[contract]` on CLI commands~~ | 172 annotations workspace-wide (70 in apr-cli). PMAT-543 closed. |
 | ~~Phase 2g: QA playbook~~ | 5 crates ported, 2,792 tests, 256 playbooks. PMAT-532 closed. |
 | ~~Model type taxonomy~~ | `is_llm()` + 3 new Architecture variants + import guards. PMAT-526 closed. |
-| ~~24 unauthorized binaries~~ | 20 crates, 21 binaries. 2 migrated to `[[example]]` (serve, train). 8 legacy remain. PMAT-545. |
+| ~~24 unauthorized binaries~~ | 20 crates, 21 binaries: 1 user-facing (`apr`), 2 standalone (`pv`, `ttop`), 8 legacy. PMAT-545. |
 | ~~ratatui migration~~ | 0 deps remain. PMAT-539 closed. |
 
 **Open gaps (2 of 9):**
@@ -262,12 +262,19 @@ Every `aprender-*` crate is a **library**. They expose `pub fn` APIs consumed
 by `apr-cli` or by external Rust code via `use aprender_compute::*;`.
 They do NOT produce binaries, CLIs, or executables.
 
-Exception: `aprender-contracts-cli` may produce a `pv` binary for standalone
-contract validation (build tooling, not user-facing ML tooling).
+**Exceptions** (2 standalone binaries that MUST remain separate):
 
-**Status (2026-04-10)**: AUDITED — 22 crates have `[[bin]]` targets (24 total).
+1. **`pv`** (`aprender-contracts-cli`) — standalone contract validation tool.
+   Used in build.rs, pre-commit hooks, and CI pipelines independently of `apr`.
+   Cannot be an `apr` subcommand because it's a build dependency, not a runtime tool.
+
+2. **`ttop`** (`aprender-viz-ttop`) — standalone terminal system monitor.
+   Used independently for GPU/CPU monitoring outside the ML workflow.
+   Separate binary provides zero-dep install for sysadmin use cases.
+
+**Status (2026-04-12)**: AUDITED — 20 crates have `[[bin]]` targets (21 total).
 Classified in `apr-mono-binary-rule-v1.yaml` v2.0: 1 user-facing (`apr`),
-1 build-tool (`pv`), 9 internal-helpers, 2 QA-tools, 11 legacy-to-migrate.
+2 standalone tools (`pv`, `ttop`), 9 internal-helpers, 2 QA-tools, 8 legacy-to-migrate.
 Legacy binaries have `apr` subcommand migration paths documented. PMAT-545 closed.
 
 ### Rule 3: CLI Contract Coverage
@@ -384,6 +391,69 @@ The CUDA executor tries to initialize; on failure, falls through to CPU.
 
 **Contract**: `contracts/apr-cli-command-safety-v1.yaml` — `long_running_graceful` equation.
 
+### Rule 8: CI Gate Completeness
+
+**The `ci / gate` check MUST verify ALL quality dimensions. No silent skips.**
+
+This rule was added after PR #726 exposed a spec-implementation gap: the spec
+said "CI must pass before merge" but `ci / gate` only checked 3 of 6 CI jobs,
+allowing security failures to merge silently.
+
+#### Five-Whys (2026-04-12)
+
+| # | Question | Answer |
+|---|----------|--------|
+| 1 | Why is main broken after PR merge? | `ci / security` fails on main |
+| 2 | Why did security-failing PR merge? | `ci / security` is not a required check |
+| 3 | Why isn't security required? | `ci / gate` doesn't check `needs.security.result` |
+| 4 | Why doesn't gate check security? | Security was `continue-on-error: true` ("informational") |
+| 5 | Why was this accepted? | Spec says "CI must pass" but doesn't define which checks |
+
+**Root cause**: Spec-implementation gap. The spec promises "CI must pass before
+merge" but doesn't enumerate which jobs constitute "CI". Branch protection
+enforces `ci / gate` only, and the gate silently skips security.
+
+#### Required CI jobs (MUST block merge)
+
+| Job | What it validates | Runner | Required? |
+|-----|-------------------|--------|-----------|
+| `ci / test` | `cargo test --workspace --lib` | `[self-hosted, clean-room]` | **YES** |
+| `ci / lint` | `cargo clippy` + `cargo fmt` | `[self-hosted, clean-room]` | **YES** |
+| `ci / coverage` | Coverage report generation | `[self-hosted, clean-room]` | **YES** |
+| `ci / security` | `cargo audit` (exemptions via `.cargo/audit.toml`) | `[self-hosted, clean-room]` | **YES** — was ubuntu-latest + informational, now self-hosted + mandatory |
+| `ci / gate` | Aggregates test + lint + coverage + security | `[self-hosted, clean-room]` | **YES** — branch protection required check |
+| `workspace-test` | Full workspace test + integration tests | `self-hosted` + container | **YES** — branch protection required check |
+| `ci / provenance` | SLSA attestation | `ubuntu-latest` | NO — informational (no code execution) |
+| `ci / bench` | Performance benchmarks | `[self-hosted, clean-room]` | NO — main-only |
+
+**Sovereign runner policy**: ALL jobs that execute repo code MUST run on
+`[self-hosted, clean-room]` or `self-hosted` with the sovereign container.
+Only metadata jobs (provenance attestation) may use `ubuntu-latest`.
+This ensures consistent hardware (Intel + GPU), local container registry
+(`localhost:5000/sovereign-ci:stable`), and NVMe RAID storage.
+
+#### Implementation
+
+The `ci / gate` job in `paiml/.github/sovereign-ci.yml` must check:
+
+```yaml
+# BEFORE (broken — silently skips security):
+if needs.test.result == "failure" → fail
+if needs.lint.result == "failure" → fail
+if needs.coverage.result == "failure" → fail
+
+# AFTER (complete — all quality dimensions):
+if needs.test.result == "failure" → fail
+if needs.lint.result == "failure" → fail
+if needs.coverage.result == "failure" → fail
+if needs.security.result == "failure" → fail   # ADDED
+```
+
+Branch protection must also add `workspace-test` as a required check
+(it's a local job in `ci.yml`, not part of the reusable workflow).
+
+**Contract**: `contracts/ci-security-audit-v1.yaml` (FALSIFY-AUDIT-001, FALSIFY-AUDIT-002).
+
 ---
 
 ### Citations