Phase 7: add semantic run quality checks and reports

Author: evilrobotxoxo

CONTRIBUTING.md

@@ -46,4 +46,5 @@ python -m unittest discover -s tests -p 'test_*.py'
 ```bash
 python tools/verify_run_artifacts.py .task_runs/<run_id>
 ```
-6. Update docs/runbook when workflow or guardrails change.
+6. Confirm `quality_report.json` is present and status is not `FAIL`.
+7. Update docs/runbook when workflow or guardrails change.

MIGRATION_PLAN.md

@@ -11,6 +11,7 @@ This plan migrates behavioral task code out of the original monorepo into `RPi4_
 5. Phase 4: completed (production guardrails, runbook, and contributor boundaries).
 6. Phase 5: completed (optional tag-strict production lock and CI automation).
 7. Phase 6: completed (artifact integrity validation and verifier CLI).
+8. Phase 7: completed (semantic run-quality checks and quality reports).
 
 Inputs agreed during planning:
 - Priority: architectural cleanup over direct code copy.
@@ -191,6 +192,11 @@ Validation:
 2. Add a CLI verification tool for existing run directories.
 3. Add tests covering valid and invalid artifact structures.
 
+### Phase 7: Semantic Run Quality Gates
+1. Add protocol-aware semantic quality checks across events and results.
+2. Write a `quality_report.json` artifact per run.
+3. Enforce quality failures as run failures unless explicitly disabled in debug mode.
+
 ## Parity and Test Strategy
 ### Deterministic parity
 Use fixed seeds and fixed presets to compare:

README.md

@@ -4,7 +4,7 @@ Behavioral task protocols for RPi4 behavior boxes, separated from hardware suppo
 
 ## Current status
 Phase 0 scaffolding plus Phase 1/2 baselines are in place, and Phase 3
-experimental staging is now wired. Phase 4/5/6 release controls are now available:
+experimental staging is now wired. Phase 4/5/6/7 release controls are now available:
 - Shared protocol contract and runtime modules.
 - Preflight branch/commit checks.
 - User/project namespace under `users/`.
@@ -21,7 +21,10 @@ experimental staging is now wired. Phase 4/5/6 release controls are now availabl
 - Shared-checkout operator runbook and contributor ownership guidance.
 - CI workflow runs smoke/parity tests on push and pull requests.
 - Automatic run-artifact structural validation after each task run.
-  - Debug-only escape hatch: `--no-validate-artifacts`
+- Automatic semantic run-quality checks after each task run.
+- Debug-only escape hatches:
+  - `--no-validate-artifacts`
+  - `--no-validate-quality`
 
 ## Layout
 - `protocols/`: maintained shared protocol implementations.

RUNBOOK_SHARED_CHECKOUT.md

@@ -59,6 +59,7 @@ Runs are validated automatically after completion. To re-check an existing run:
 python tools/verify_run_artifacts.py .task_runs/<run_id>
 ```
 Note: production mode does not allow disabling artifact validation.
+Note: production mode does not allow disabling semantic run-quality validation.
 
 ## Release cadence recommendation
 1. Validate on a staging Pi in debug mode.

run_task.py

@@ -11,10 +11,12 @@
     RunMetadata,
     append_event,
     create_run_paths,
+    write_quality_report,
     write_result,
     write_run_metadata,
 )
 from runtime.preflight import run_preflight
+from runtime.quality_checks import evaluate_run_quality
 from runtime.release_policy import DEFAULT_RELEASE_POLICY, ReleasePolicy
 from runtime.runner import EXPERIMENTAL_PROTOCOLS, SUPPORTED_PROTOCOLS, run_protocol
 from runtime.session_config import build_session_config, load_mouse_info, load_session_template
@@ -88,6 +90,11 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Skip run artifact validation (debug-only escape hatch).",
     )
+    parser.add_argument(
+        "--no-validate-quality",
+        action="store_true",
+        help="Skip semantic run quality checks (debug-only escape hatch).",
+    )
     return parser.parse_args()
 
 
@@ -120,9 +127,15 @@ def resolve_release_policy(require_release_tag: bool) -> ReleasePolicy:
     return replace(DEFAULT_RELEASE_POLICY, require_release_tag_in_production=True)
 
 
-def validate_runtime_options(run_mode: str, no_validate_artifacts: bool) -> None:
+def validate_runtime_options(
+    run_mode: str,
+    no_validate_artifacts: bool,
+    no_validate_quality: bool,
+) -> None:
     if run_mode == "production" and no_validate_artifacts:
         raise ValueError("Artifact validation cannot be disabled in production mode.")
+    if run_mode == "production" and no_validate_quality:
+        raise ValueError("Run quality validation cannot be disabled in production mode.")
 
 
 def main() -> int:
@@ -156,7 +169,11 @@ def main() -> int:
 
     require_confirmation = True if args.run_mode == "production" else (not args.yes)
     release_policy = resolve_release_policy(require_release_tag=args.require_release_tag)
-    validate_runtime_options(run_mode=args.run_mode, no_validate_artifacts=args.no_validate_artifacts)
+    validate_runtime_options(
+        run_mode=args.run_mode,
+        no_validate_artifacts=args.no_validate_artifacts,
+        no_validate_quality=args.no_validate_quality,
+    )
 
     git_state = run_preflight(
         repo_root=repo_root,
@@ -199,6 +216,17 @@ def emit_event(event_type: str, payload: dict[str, object]) -> None:
             joined = "\n".join(f"- {error}" for error in validation_errors)
             raise RuntimeError(f"Run artifact validation failed:\n{joined}")
 
+    quality_report = evaluate_run_quality(run_paths.run_dir)
+    write_quality_report(run_paths.quality_report_path, quality_report)
+    if not args.no_validate_quality and quality_report["status"] == "FAIL":
+        quality_errors = [
+            finding["message"]
+            for finding in quality_report.get("findings", [])
+            if finding.get("level") == "error"
+        ]
+        joined = "\n".join(f"- {error}" for error in quality_errors)
+        raise RuntimeError(f"Run quality validation failed:\n{joined}")
+
     print(f"Run complete: {session.run_id}")
     print(f"Protocol: {session.protocol}")
     print(f"Output directory: {run_paths.run_dir}")

runtime/logging_schema.py

@@ -31,6 +31,7 @@ class RunPaths:
     metadata_path: Path
     events_path: Path
     result_path: Path
+    quality_report_path: Path
 
 
 
@@ -43,6 +44,7 @@ def create_run_paths(output_root: Path, run_id: str) -> RunPaths:
         metadata_path=run_dir / "run_metadata.json",
         events_path=run_dir / "events.jsonl",
         result_path=run_dir / "result.json",
+        quality_report_path=run_dir / "quality_report.json",
     )
 
 
@@ -67,3 +69,9 @@ def append_event(path: Path, event_type: str, payload: dict[str, object], timest
 def write_result(path: Path, result: dict[str, Any]) -> None:
     with path.open("w", encoding="utf-8") as handle:
         json.dump(result, handle, indent=2, sort_keys=True)
+
+
+
+def write_quality_report(path: Path, report: dict[str, Any]) -> None:
+    with path.open("w", encoding="utf-8") as handle:
+        json.dump(report, handle, indent=2, sort_keys=True)