added pause/wait functions for stream

tools/lint_gate.py

@@ -131,16 +131,24 @@ def run_doc_gate(force_all: bool) -> dict:
     """
     script = REPO.parent / "scripts" / "doc_lint.py"
     if not script.is_file():
-        return {"status": "unavailable", "findings": [], "baselined": []}
+        print(f"lint_gate: required documentation checker missing: {script}", file=sys.stderr)
+        return {"status": "error", "findings": [], "baselined": []}
     cmd = [sys.executable, str(script), "--json"]
     if force_all:
         cmd.append("--all")
     result = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", check=False)
+    if result.returncode not in (0, 1):
+        print(f"lint_gate: documentation checker failed ({result.returncode}): {result.stderr.strip()}", file=sys.stderr)
+        return {"status": "error", "findings": [], "baselined": []}
     if not result.stdout.strip():
         print(f"lint_gate: doc gate produced no output: {result.stderr.strip()[:200]}", file=sys.stderr)
         return {"status": "error", "findings": [], "baselined": []}
     try:
-        return json.loads(result.stdout)
+        payload = json.loads(result.stdout)
+        expected = "clean" if result.returncode == 0 else "findings"
+        if not isinstance(payload, dict) or payload.get("status") != expected:
+            return {"status": "error", "findings": [], "baselined": []}
+        return payload
     except json.JSONDecodeError:
         print("lint_gate: could not parse doc gate output", file=sys.stderr)
         return {"status": "error", "findings": [], "baselined": []}
@@ -161,6 +169,10 @@ def main(argv: list[str] | None = None) -> int:
     docs: dict = {"status": "skipped", "findings": [], "baselined": []}
     if not args.no_docs and args.files is None:
         docs = run_doc_gate(force_all=args.all)
+        if docs.get("status") not in ("clean", "findings"):
+            if args.json:
+                print(json.dumps({"status": "error", "docs": docs, "findings": []}))
+            return 2
 
     # Report the documentation verdict even when Ruff is unavailable: a missing linter must not
     # hide the docs result, and the exit code still signals the environment problem.