diff --git a/plugins/magpie-repo-health/skills/ci-runner-audit/SKILL.md b/plugins/magpie-repo-health/skills/ci-runner-audit/SKILL.md
index 9f79cd9a4..ed328fea5 100644
--- a/plugins/magpie-repo-health/skills/ci-runner-audit/SKILL.md
+++ b/plugins/magpie-repo-health/skills/ci-runner-audit/SKILL.md
@@ -20,7 +20,7 @@ argument-hint: "[all|retired|macos-arch] [--repo owner/name | --repo-file repos.
 capability: capability:triage
 surface_hash: sha256:c6da72e64ac4808d
 license: Apache-2.0
-measured_tokens: 2295
+measured_tokens: 2767
 ---
 
 <!-- SPDX-License-Identifier: Apache-2.0
@@ -153,6 +153,9 @@ asks for branch-specific analysis.
 
 ## Commands
 
+The Python interpreter running the script must be 3.11 or newer and have PyYAML installed.
+Install your distribution's `python3-yaml` package or install `pyyaml` in a virtual environment and run the script with that interpreter.
+
 Run from the framework checkout root.
 
 For one repository:
@@ -186,8 +189,7 @@ skills/ci-runner-audit/scripts/scan_ci_runners.py all \
   --owner apache \
   --cache-dir /tmp/ci-runner-audit-cache \
   --out-dir /tmp/ci-runner-audit \
-  --workers 20 \
-  --refresh
+  --workers 20
 ```
 
 For only one check, replace `all` with `retired` or `macos-arch`.
@@ -195,11 +197,23 @@ For only one check, replace `all` with `retired` or `macos-arch`.
 Use `--refresh` for org scans when cached repo/workflow inventory may be
 stale. Explicit `--repo` and `--repo-file` scans fetch repository
 metadata directly.
+Cold organization discovery can consume most of the REST API quota; retain validated inventory caches and use `--refresh` deliberately.
+Repository discovery excludes archived repositories.
+Explicit archived inputs are reported as unchecked, making the invocation incomplete.
 
 ---
 
 ## Outputs
 
+`<scope>-scan-errors.tsv` records failures with `repo`, `path`, `stage`, `error`, and `html_url`.
+Read TSVs with a CSV-aware parser because quoted error fields can contain multiline diagnostics.
+The stderr summary includes `scan_complete`, `workflows_scanned` (files completing all selected checks), and `scan_errors`.
+Organization scans report `repo_inventory=cache|live` and `workflow_inventory=cache|live` for the inventories actually read.
+A workflow cache hit bypasses repository discovery and reports only `workflow_inventory=cache`.
+Exit codes are `0` for complete, `1` for incomplete scanning/cache/output, and `2` for unavailable prerequisites or unreadable input.
+Selected findings files are replaced with this invocation's results, including header-only files when prerequisites fail.
+Prerequisite failures omit finding counts because no workflows were checked; the completion/error summary still reports the failure.
+
 The script writes TSV files under `--out-dir`:
 
 - `<scope>-retired-gh-runners-confirmed.tsv` — confirmed retired-label
@@ -211,6 +225,7 @@ The script writes TSV files under `--out-dir`:
 
 Use `--scope-name` for stable output names for project or repo-set
 scans.
+If a repository file cannot be read, the fallback prefix uses only the known command-line repositories; specify `--scope-name` for a stable prefix.
 
 ---
 
@@ -236,6 +251,16 @@ Before reporting a broad candidate as actionable, inspect `runs-on`,
 
 ## Reporting
 
+Check exit status and completion/error counts before interpreting findings.
+A failed or incomplete scan must be reported as incomplete, even with empty findings; keep successful findings qualified as partial results.
+A clean result requires successful completion, zero scan errors and zero findings.
+Prerequisite failures stop before checking workflows.
+Completion with cached inventory covers only that inventory, not repositories or workflow paths added since it was built.
+State which inventory layers were cached; freshly listed workflows can still use a cached repository list.
+Do not claim the current whole organization is clean from a cached inventory; use `--refresh` when current organization coverage is required.
+If only cache persistence fails, report that all enumerated workflows were checked but the invocation is incomplete because the cache could not be saved.
+When output writing or CLI parsing fails, do not interpret existing findings files as results of that invocation.
+
 Report findings in this order:
 
 1. Scope scanned: owner/repo set, default branches, and number of
diff --git a/plugins/magpie-repo-health/skills/ci-runner-audit/scripts/scan_ci_runners.py b/plugins/magpie-repo-health/skills/ci-runner-audit/scripts/scan_ci_runners.py
index 620b09112..a17606836 100755
--- a/plugins/magpie-repo-health/skills/ci-runner-audit/scripts/scan_ci_runners.py
+++ b/plugins/magpie-repo-health/skills/ci-runner-audit/scripts/scan_ci_runners.py
@@ -23,12 +23,16 @@
 import argparse
 import csv
 import json
+import os
 import re
+import shutil
 import subprocess
 import sys
-from concurrent.futures import Future, ThreadPoolExecutor, as_completed
+import tempfile
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from typing import Any
+from urllib.parse import quote
 from urllib.request import urlopen
 
 try:
@@ -81,15 +85,36 @@
 }
 
 
+class ScanError(RuntimeError):
+    """A fetch or check failed; the scan is incomplete."""
+
+
+class GhError(ScanError):
+    def __init__(self, message: str, status: int | None, diagnostic: str) -> None:
+        super().__init__(message)
+        self.status, self.diagnostic = status, diagnostic
+
+
+WORKFLOW_FIELDS = ["repo", "branch", "path", "url", "html_url"]
+ERROR_FIELDS = ["repo", "path", "stage", "error", "html_url"]
+
+
 def run(args: list[str]) -> str:
-    return subprocess.check_output(args, text=True, stderr=subprocess.DEVNULL)
+    completed = subprocess.run(args, capture_output=True, check=False)
+    stderr = (completed.stderr or b"").decode("utf-8", errors="replace")
+    if completed.returncode:
+        diagnostic = stderr.strip() or (completed.stdout or b"").decode("utf-8", errors="replace").strip()
+        status = re.search(r"\(HTTP (\d{3})\)", stderr)
+        raise GhError(
+            f"gh api {args[3] if args[2] == '--paginate' else args[2]}: {diagnostic or 'no captured diagnostic'}",
+            int(status[1]) if status else None,
+            diagnostic,
+        )
+    return completed.stdout.decode("utf-8")
 
 
-def gh_json(path: str) -> object | None:
-    try:
-        return json.loads(run(["gh", "api", path]))
-    except Exception:
-        return None
+def gh_json(path: str) -> object:
+    return json.loads(run(["gh", "api", path]))
 
 
 def fetch_text(url: str) -> str:
@@ -112,31 +137,87 @@ def lower_values(value) -> list[str]:
     return [item.strip().lower() for item in flatten(value)]
 
 
-def load_repos(cache_dir: Path, owner: str, refresh: bool) -> list[dict]:
-    cache_dir.mkdir(parents=True, exist_ok=True)
-    repo_file = cache_dir / f"{owner}-repos.jsonl"
-    if refresh or not repo_file.exists():
-        output = run(
-            [
-                "gh",
-                "api",
-                "--paginate",
-                f"/orgs/{owner}/repos?per_page=100&type=public",
-                "--jq",
-                ".[] | select(.archived == false) | {full_name, default_branch}",
+def scan_error(context: dict, stage: str, exc: Exception) -> dict:
+    return {
+        "repo": str(context.get("repo") or context.get("full_name") or ""),
+        "path": str(context.get("path") or ""),
+        "stage": stage,
+        "error": f"{type(exc).__name__}: {exc}",
+        "html_url": str(context.get("html_url") or ""),
+    }
+
+
+def atomic_write(path: Path, writer) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as temporary:
+        scratch = Path(temporary.name)
+    try:
+        writer(scratch)
+        os.replace(scratch, path)
+    finally:
+        scratch.unlink(missing_ok=True)
+
+
+def valid_repo(repo: object) -> bool:
+    return isinstance(repo, dict) and all(
+        isinstance(repo.get(key), str) and repo[key] for key in ("full_name", "default_branch")
+    )
+
+
+def load_repos(cache_dir: Path, owner: str, refresh: bool) -> tuple[list[dict], list[dict]]:
+    cache = cache_dir / f"{owner}-repos-v2.jsonl"
+    if not refresh:
+        try:
+            repos = [
+                json.loads(line) for line in cache.read_text(encoding="utf-8").splitlines() if line.strip()
             ]
-        )
-        repo_file.write_text(output, encoding="utf-8")
-    return [json.loads(line) for line in repo_file.read_text(encoding="utf-8").splitlines() if line.strip()]
+            if all(valid_repo(repo) for repo in repos):
+                print("repo_inventory=cache", file=sys.stderr)
+                return repos, []
+        except (OSError, UnicodeError, ValueError):
+            pass  # Rebuild an absent or damaged cache; never accept a partial write.
+    output = run(
+        [
+            "gh",
+            "api",
+            "--paginate",
+            f"/orgs/{owner}/repos?per_page=100&type=public",
+            "--jq",
+            ".[] | select(.archived == false) | {full_name, default_branch}",
+        ]
+    )
+    response = [json.loads(line) for line in output.splitlines() if line.strip()]
+    print("repo_inventory=live", file=sys.stderr)
+    repos, errors = [], []
+    for repo in response:
+        if valid_repo(repo):
+            repos.append(repo)
+        else:
+            errors.append(
+                scan_error(
+                    repo if isinstance(repo, dict) else {},
+                    "metadata",
+                    ScanError(f"Invalid repository metadata: {repo!r}"),
+                )
+            )
+    if not errors:
+        try:
+            atomic_write(cache, lambda path: path.write_text(output, encoding="utf-8"))
+        except OSError as exc:
+            errors.append(scan_error({"path": cache.name}, "cache", exc))
+    return repos, errors
 
 
 def load_repo(full_name: str) -> dict:
     repo = gh_json(f"repos/{full_name}")
-    if not isinstance(repo, dict):
-        raise RuntimeError(f"Could not load repository metadata for {full_name}")
+    if not isinstance(repo, dict) or not valid_repo(repo):
+        raise ScanError(f"Invalid repository metadata for {full_name}")
     if repo.get("archived"):
-        return {}
-    return {"full_name": repo.get("full_name"), "default_branch": repo.get("default_branch")}
+        raise ScanError(
+            f"Archived repository {repo['full_name']} is excluded from the audit scope; "
+            "workflows were not checked"
+        )
+    return {"full_name": repo["full_name"], "default_branch": repo["default_branch"]}
 
 
 def load_repo_file(path: Path) -> list[str]:
@@ -152,69 +233,132 @@ def scope_key(value: str) -> str:
     return re.sub(r"[^A-Za-z0-9_.-]+", "-", value).strip("-") or "scope"
 
 
-def list_workflows_for_repo(repo: dict) -> list[dict]:
-    full_name = repo.get("full_name")
-    branch = repo.get("default_branch")
-    if not full_name or not branch:
-        return []
-    contents = gh_json(f"repos/{full_name}/contents/.github/workflows?ref={branch}")
+def workflow_contents(full_name: str, branch: str) -> object:
+    directory = f"repos/{full_name}/contents/.github/workflows?ref="
+    try:
+        return gh_json(directory + quote(branch, safe=""))
+    except GhError as original:
+        if original.status != 404:
+            raise
+        if re.fullmatch(r"gh: This repository is empty\. \(HTTP 404\)", original.diagnostic):
+            return []
+        # A 404 can also mean an invalid ref; verify it before accepting absence.
+        try:
+            sha = run(
+                [
+                    "gh",
+                    "api",
+                    f"repos/{full_name}/commits/{quote(branch, safe='')}",
+                    "-H",
+                    "Accept: application/vnd.github.sha",
+                ]
+            ).strip()
+        except (GhError, OSError, UnicodeError) as exc:
+            if (
+                isinstance(exc, GhError)
+                and exc.status == 409
+                and re.search(r"(?m)(?:^|: )Git Repository is empty\.(?: \(HTTP 409\))?$", exc.diagnostic)
+            ):
+                return []
+            raise ScanError(f"{original}; cannot verify ref {branch}: {exc}") from exc
+        if not re.fullmatch(r"[0-9a-fA-F]{40}", sha):
+            raise ScanError(
+                f"{original}; cannot verify ref {branch}: expected a 40-character hexadecimal SHA"
+            ) from original
+        try:
+            return gh_json(directory + sha)
+        except GhError as exc:
+            if exc.status == 404:
+                return []
+            raise ScanError(f"{original}; directory retry failed: {exc}") from exc
+
+
+def list_workflows_for_repo(repo: dict) -> tuple[list[dict], list[dict]]:
+    if not valid_repo(repo):
+        raise ScanError(f"Invalid repository metadata: {repo!r}")
+    full_name, branch = repo["full_name"], repo["default_branch"]
+    contents = workflow_contents(full_name, branch)
     if not isinstance(contents, list):
-        return []
-    workflows = []
+        raise ScanError(f"Unexpected workflow listing for {full_name}: expected a list")
+    workflows, errors = [], []
     for item in contents:
-        path = item.get("path", "")
-        if item.get("type") == "file" and re.search(r"\.ya?ml$", path):
-            workflows.append(
-                {
-                    "repo": full_name,
-                    "branch": branch,
-                    "path": path,
-                    "url": item.get("download_url"),
-                    "html_url": f"https://github.com/{full_name}/blob/{branch}/{path}",
-                }
-            )
-    return workflows
-
-
-def load_workflows(cache_dir: Path, owner: str, refresh: bool, workers: int) -> list[dict]:
-    cache_dir.mkdir(parents=True, exist_ok=True)
-    workflow_file = cache_dir / f"{owner}-workflow-files.tsv"
-    if refresh or not workflow_file.exists():
-        repos = load_repos(cache_dir, owner, refresh)
-        workflows: list[dict] = []
-        with ThreadPoolExecutor(max_workers=workers) as executor:
-            futures = [executor.submit(list_workflows_for_repo, repo) for repo in repos]
-            for future in as_completed(futures):
-                workflows.extend(future.result())
-        with workflow_file.open("w", newline="", encoding="utf-8") as output:
-            writer = csv.DictWriter(
-                output,
-                delimiter="\t",
-                fieldnames=["repo", "branch", "path", "url", "html_url"],
-                lineterminator="\n",
-            )
-            writer.writeheader()
-            writer.writerows(sorted(workflows, key=lambda row: (row["repo"], row["path"])))
-    with workflow_file.open(newline="", encoding="utf-8") as input_file:
-        return list(csv.DictReader(input_file, delimiter="\t"))
-
-
-def load_workflows_for_repos(repo_names: list[str], workers: int) -> list[dict]:
-    repos = []
+        if (
+            not isinstance(item, dict)
+            or any(not isinstance(item.get(key), str) or not item[key] for key in ("type", "path"))
+            or item["type"] not in {"file", "dir", "symlink", "submodule"}
+        ):
+            errors.append(scan_error(repo, "workflow-list", ScanError(f"Invalid workflow entry: {item!r}")))
+        elif item["type"] == "file" and re.search(r"\.ya?ml$", item["path"]):
+            workflow = {
+                "repo": full_name,
+                "branch": branch,
+                "path": item["path"],
+                "url": item.get("download_url"),
+                "html_url": f"https://github.com/{full_name}/blob/{branch}/{item['path']}",
+            }
+            if not isinstance(workflow["url"], str) or not workflow["url"]:
+                errors.append(scan_error(workflow, "download", ScanError("Missing workflow download URL")))
+            else:
+                workflows.append(workflow)
+    return workflows, errors
+
+
+def collect_workflows(repos: list[dict], workers: int) -> tuple[list[dict], list[dict]]:
+    workflows, errors = [], []
     with ThreadPoolExecutor(max_workers=workers) as executor:
-        futures = [executor.submit(load_repo, repo_name) for repo_name in repo_names]
+        futures = {executor.submit(list_workflows_for_repo, repo): repo for repo in repos}
         for future in as_completed(futures):
-            repo = future.result()
-            if repo:
-                repos.append(repo)
-    workflows: list[dict] = []
+            try:
+                rows, failures = future.result()
+                workflows.extend(rows)
+                errors.extend(failures)
+            except Exception as exc:
+                errors.append(scan_error(futures[future], "workflow-list", exc))
+    return sorted(workflows, key=lambda row: (row["repo"], row["path"])), errors
+
+
+def load_workflows(cache_dir: Path, owner: str, refresh: bool, workers: int) -> tuple[list[dict], list[dict]]:
+    # Earlier inventories could contain silent omissions. Ignore them and rebuild.
+    cache = cache_dir / f"{owner}-workflow-files-v3.tsv"
+    if not refresh:
+        try:
+            with cache.open(newline="", encoding="utf-8") as source:
+                reader = csv.DictReader(source, delimiter="\t", strict=True)
+                rows = list(reader)
+                if reader.fieldnames == WORKFLOW_FIELDS and all(
+                    set(row) == set(WORKFLOW_FIELDS) and all(row.values()) for row in rows
+                ):
+                    print("workflow_inventory=cache", file=sys.stderr)
+                    return rows, []
+        except (OSError, UnicodeError, csv.Error):
+            pass  # Rebuild an absent or damaged workflow inventory.
+    repos, errors = load_repos(cache_dir, owner, refresh)
+    workflows, failures = collect_workflows(repos, workers)
+    errors.extend(failures)
+    print("workflow_inventory=live", file=sys.stderr)
+    if not errors:
+        try:
+            atomic_write(cache, lambda path: write_tsv(path, workflows, WORKFLOW_FIELDS))
+        except (OSError, UnicodeError, csv.Error) as exc:
+            errors.append(scan_error({"path": cache.name}, "cache", exc))
+    return workflows, errors
+
+
+def load_workflows_for_repos(repo_names: list[str], workers: int) -> tuple[list[dict], list[dict]]:
+    repos, errors = [], []
+    seen = set()
     with ThreadPoolExecutor(max_workers=workers) as executor:
-        workflow_futures: list[Future[list[dict]]] = [
-            executor.submit(list_workflows_for_repo, repo) for repo in repos
-        ]
-        for workflow_future in as_completed(workflow_futures):
-            workflows.extend(workflow_future.result())
-    return sorted(workflows, key=lambda row: (row["repo"], row["path"]))
+        futures = {executor.submit(load_repo, name): name for name in repo_names}
+        for future in as_completed(futures):
+            try:
+                repo = future.result()
+                if repo["full_name"].casefold() not in seen:
+                    repos.append(repo)
+                    seen.add(repo["full_name"].casefold())
+            except Exception as exc:
+                errors.append(scan_error({"repo": futures[future]}, "metadata", exc))
+    workflows, failures = collect_workflows(repos, workers)
+    return workflows, errors + failures
 
 
 def yaml_load(text: str) -> object:
@@ -286,11 +430,7 @@ def candidate_runner_contexts(job: dict) -> list[tuple[str, str | None, dict]]:
     return unique
 
 
-def retired_hits(workflow: dict) -> list[dict]:
-    try:
-        data = yaml_load(fetch_text(workflow["url"]))
-    except Exception:
-        return []
+def retired_hits(workflow: dict, data: object) -> list[dict]:
     jobs = data.get("jobs") if isinstance(data, dict) else None
     if not isinstance(jobs, dict):
         return []
@@ -311,11 +451,7 @@ def retired_hits(workflow: dict) -> list[dict]:
     return hits
 
 
-def arch_hits(workflow: dict) -> list[dict]:
-    try:
-        data = yaml_load(fetch_text(workflow["url"]))
-    except Exception:
-        return []
+def arch_hits(workflow: dict, data: object) -> list[dict]:
     jobs = data.get("jobs") if isinstance(data, dict) else None
     if not isinstance(jobs, dict):
         return []
@@ -406,22 +542,49 @@ def arch_hits(workflow: dict) -> list[dict]:
     return hits
 
 
-def parallel_scan(workflows: list[dict], scanner, workers: int) -> list[dict]:
-    results = []
+def scan_workflow(workflow: dict, command: str) -> tuple[list[dict], list[dict], list[dict]]:
+    try:
+        text = fetch_text(workflow["url"])
+    except Exception as exc:
+        return [], [], [scan_error(workflow, "download", exc)]
+    try:
+        data = yaml_load(text)
+    except Exception as exc:
+        return [], [], [scan_error(workflow, "parse", exc)]
+    retired: list[dict] = []
+    arch: list[dict] = []
+    errors = []
+    for name, scanner, results in [("retired", retired_hits, retired), ("macos-arch", arch_hits, arch)]:
+        if command not in (name, "all"):
+            continue
+        try:
+            results.extend(scanner(workflow, data))
+        except Exception as exc:
+            errors.append(scan_error(workflow, "check", ScanError(f"{name}: {exc}")))
+    return retired, arch, errors
+
+
+def parallel_scan(
+    workflows: list[dict], command: str, workers: int
+) -> tuple[list[dict], list[dict], int, list[dict]]:
+    retired, arch, errors = [], [], []
+    scanned = 0
     with ThreadPoolExecutor(max_workers=workers) as executor:
-        futures = [executor.submit(scanner, workflow) for workflow in workflows if workflow.get("url")]
+        futures = {executor.submit(scan_workflow, workflow, command): workflow for workflow in workflows}
         for future in as_completed(futures):
-            results.extend(future.result())
-    return sorted(
-        results,
-        key=lambda row: (
-            row.get("repo", ""),
-            row.get("path", ""),
-            row.get("job", ""),
-            row.get("runner", ""),
-            row.get("evidence", ""),
-        ),
-    )
+            try:
+                rows, candidates, failures = future.result()
+                retired.extend(rows)
+                arch.extend(candidates)
+                errors.extend(failures)
+                scanned += not failures
+            except Exception as exc:
+                errors.append(scan_error(futures[future], "check", exc))
+
+    def key(row):
+        return tuple(row.get(field, "") for field in ("repo", "path", "job", "runner", "evidence"))
+
+    return sorted(retired, key=key), sorted(arch, key=key), scanned, errors
 
 
 def write_tsv(path: Path, rows: list[dict], fields: list[str]) -> None:
@@ -434,7 +597,7 @@ def write_tsv(path: Path, rows: list[dict], fields: list[str]) -> None:
         writer.writerows(rows)
 
 
-def main() -> int:
+def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("command", choices=["retired", "macos-arch", "all"])
     parser.add_argument("--owner", default="apache")
@@ -451,35 +614,29 @@ def main() -> int:
     parser.add_argument("--workers", type=int, default=20)
     parser.add_argument("--refresh", action="store_true")
     args = parser.parse_args()
-
-    repo_names = list(args.repo)
-    if args.repo_file:
-        repo_names.extend(load_repo_file(args.repo_file))
-    repo_names = sorted(set(repo_names))
-
-    if repo_names:
-        workflows = load_workflows_for_repos(repo_names, args.workers)
-        if args.scope_name:
-            prefix = scope_key(args.scope_name)
-        elif len(repo_names) == 1:
-            prefix = scope_key(repo_names[0])
-        else:
-            prefix = "repo-set"
-    else:
-        workflows = load_workflows(args.cache_dir, args.owner, args.refresh, args.workers)
-        prefix = scope_key(args.scope_name or args.owner)
-
+    if args.workers < 1:
+        parser.error("--workers must be a positive integer")
+    return args
+
+
+def write_findings(
+    args: argparse.Namespace,
+    prefix: str,
+    retired: list[dict],
+    arch: list[dict],
+    *,
+    report_counts: bool = True,
+) -> None:
     if args.command in ("retired", "all"):
-        retired = parallel_scan(workflows, retired_hits, args.workers)
         write_tsv(
             args.out_dir / f"{prefix}-retired-gh-runners-confirmed.tsv",
             retired,
             ["repo", "path", "job", "runner", "html_url"],
         )
-        print(f"retired_runner_hits={len(retired)}", file=sys.stderr)
+        if report_counts:
+            print(f"retired_runner_hits={len(retired)}", file=sys.stderr)
 
     if args.command in ("macos-arch", "all"):
-        arch = parallel_scan(workflows, arch_hits, args.workers)
         write_tsv(
             args.out_dir / f"{prefix}-macos-arch-mismatch-candidates.tsv",
             arch,
@@ -529,10 +686,69 @@ def main() -> int:
                 "html_url",
             ],
         )
-        print(f"macos_arch_candidates={len(arch)}", file=sys.stderr)
-        print(f"setup_action_mismatches={len(setup)}", file=sys.stderr)
+        if report_counts:
+            print(f"macos_arch_candidates={len(arch)}", file=sys.stderr)
+            print(f"setup_action_mismatches={len(setup)}", file=sys.stderr)
+
+
+def finish_scan(args: argparse.Namespace, prefix: str, scanned: int, errors: list[dict]) -> int:
+    errors.sort(key=lambda row: (row["repo"], row["path"], row["stage"], row["error"]))
+    try:
+        write_tsv(args.out_dir / f"{prefix}-scan-errors.tsv", errors, ERROR_FIELDS)
+    except (OSError, UnicodeError, csv.Error) as exc:
+        errors.append(scan_error({}, "output", exc))
+    for error in errors:
+        print(f"error: {error['repo']} {error['path']} [{error['stage']}]: {error['error']}", file=sys.stderr)
+    print(
+        f"scan_complete={str(not errors).lower()}\nworkflows_scanned={scanned}\nscan_errors={len(errors)}",
+        file=sys.stderr,
+    )
+    return 1 if errors else 0
+
 
-    return 0
+def output_prefix(args: argparse.Namespace, repos: list[str]) -> str:
+    return scope_key(
+        args.scope_name
+        or (repos[0] if len(repos) == 1 else "repo-set" if repos or args.repo_file else args.owner)
+    )
+
+
+def main() -> int:
+    args = parse_args()
+    repos = sorted(set(args.repo))
+    retired: list[dict] = []
+    arch: list[dict] = []
+    errors: list[dict] = []
+    scanned, stage = 0, "prerequisite"
+    try:
+        if args.repo_file:
+            repos = sorted(set(repos + load_repo_file(args.repo_file)))
+        if sys.version_info < (3, 11):  # noqa: UP036 - the standalone system Python may be older
+            raise ScanError("Python 3.11 or newer is required")
+        if yaml is None:
+            raise ScanError("PyYAML is required. Install python3-yaml or pyyaml.")
+        if shutil.which("gh") is None:
+            raise ScanError("GitHub CLI (gh) is required")
+        if args.repo_file and not repos:
+            raise ScanError("The explicit repository list is empty")
+        stage = "repository-list"
+        workflows, errors = (
+            load_workflows_for_repos(repos, args.workers)
+            if repos
+            else load_workflows(args.cache_dir, args.owner, args.refresh, args.workers)
+        )
+        stage = "scan"
+        retired, arch, scanned, failures = parallel_scan(workflows, args.command, args.workers)
+        errors.extend(failures)
+    except Exception as exc:
+        errors.append(scan_error({}, stage, exc))
+    prefix = output_prefix(args, repos)
+    try:
+        write_findings(args, prefix, retired, arch, report_counts=stage != "prerequisite")
+    except Exception as exc:
+        errors.append(scan_error({}, "output", exc))
+    status = finish_scan(args, prefix, scanned, errors)
+    return 2 if stage == "prerequisite" else status
 
 
 if __name__ == "__main__":
diff --git a/plugins/magpie-repo-health/skills/ci-runner-audit/tests/test_scan_ci_runners.py b/plugins/magpie-repo-health/skills/ci-runner-audit/tests/test_scan_ci_runners.py
new file mode 100644
index 000000000..8c3ede0c6
--- /dev/null
+++ b/plugins/magpie-repo-health/skills/ci-runner-audit/tests/test_scan_ci_runners.py
@@ -0,0 +1,514 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+
+from __future__ import annotations
+
+import contextlib
+import csv
+import io
+import json
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+import unittest.mock as mock
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
+import scan_ci_runners as scan
+
+
+class ScanTest(unittest.TestCase):
+    def setUp(self) -> None:
+        temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(temporary.cleanup)
+        self.root = Path(temporary.name)
+        self.out, self.cache = self.root / "out", self.root / "cache"
+        self.names = ["example/good", "example/clean"]
+        self.branch, self.sha = "main", "a" * 40
+        self.files = {}
+        for name, label in zip(self.names, ["ubuntu-20.04", "ubuntu-24.04"], strict=True):
+            path = self.root / (name.split("/")[1] + ".yml")
+            path.write_text(json.dumps({"jobs": {"build": {"runs-on": label}}}), encoding="utf-8")
+            self.files[name] = path
+        self.responses: dict = {}
+        self.calls: list[str] = []
+        self.unknown: list[list[str]] = []
+        self.addCleanup(lambda: self.assertEqual(self.unknown, [], "Unknown gh endpoint"))
+        self.addCleanup(mock.patch.stopall)
+        mock.patch.object(scan.shutil, "which", return_value="/mock/gh").start()
+        mock.patch.object(scan, "yaml", SimpleNamespace(safe_load=json.loads)).start()
+        self.gh = mock.patch.object(scan.subprocess, "run", side_effect=self.gh_run).start()
+
+    @staticmethod
+    def completed(args, code=0, stdout=b"", stderr=b""):
+        return subprocess.CompletedProcess(args, code, stdout, stderr)
+
+    def failed(self, status, diagnostic="request failed"):
+        return self.completed([], 1, stderr=f"gh: {diagnostic} (HTTP {status})".encode())
+
+    def gh_run(self, args, **kwargs):
+        endpoint = args[3] if args[:3] == ["gh", "api", "--paginate"] else args[2]
+        kind = ""
+        value: Any = None
+        if args[:2] == ["gh", "api"]:
+            if endpoint == "/orgs/example/repos?per_page=100&type=public" and "--paginate" in args:
+                kind = "repositories"
+                value = "\n".join(
+                    json.dumps({"full_name": n, "default_branch": self.branch}) for n in self.names
+                ).encode()
+            elif re.fullmatch(r"repos/example/[^/]+/contents/\.github/workflows\?ref=.+", endpoint):
+                kind = "directory"
+                name = endpoint.removeprefix("repos/").split("/contents/")[0]
+                value = [
+                    {
+                        "type": "file",
+                        "path": ".github/workflows/ci.yml",
+                        "download_url": self.files[name].as_uri(),
+                    }
+                ]
+            elif re.fullmatch(r"repos/example/[^/]+/commits/.+", endpoint):
+                kind, value = "commit", self.sha.encode()
+            elif endpoint in ["repos/" + name for name in self.names]:
+                kind = "metadata"
+                value = {"full_name": endpoint[6:], "default_branch": self.branch}
+        if not kind:
+            self.unknown.append(args)
+            raise AssertionError(f"Unknown gh endpoint: {args}")
+        self.calls.append(endpoint)
+        value = self.responses.get(endpoint, self.responses.get(kind, value))
+        if isinstance(value, Exception):
+            raise value
+        if isinstance(value, subprocess.CompletedProcess):
+            return value
+        output = value if isinstance(value, bytes) else json.dumps(value, ensure_ascii=False).encode()
+        return self.completed(args, stdout=output)
+
+    def invoke(self, *args, workers=2):
+        options = ["--out-dir", str(self.out), "--cache-dir", str(self.cache), "--workers", str(workers)]
+        with (
+            mock.patch.object(sys, "argv", ["scan", *args, *options]),
+            contextlib.redirect_stderr(io.StringIO()) as stderr,
+        ):
+            code = scan.main()
+        return code, stderr.getvalue()
+
+    def rows(self, suffix="scan-errors", prefix="example-good"):
+        with (self.out / f"{prefix}-{suffix}.tsv").open(newline="", encoding="utf-8") as source:
+            return list(csv.DictReader(source, delimiter="\t"))
+
+    def test_success_and_complete_zero_findings(self) -> None:
+        for name, count in [("example/good", 1), ("example/clean", 0)]:
+            with self.subTest(name=name):
+                code, stderr = self.invoke("all", "--repo", name)
+                self.assertEqual(code, 0)
+                self.assertIn("scan_complete=true", stderr)
+                self.assertIn("workflows_scanned=1", stderr)
+                prefix = name.replace("/", "-")
+                self.assertEqual(self.rows(prefix=prefix), [])
+                self.assertEqual(len(self.rows("retired-gh-runners-confirmed", prefix)), count)
+                self.assertNotIn("archived_repository=", stderr)
+                self.assertEqual(sum("/contents/" in call for call in self.calls), 1)
+                self.calls.clear()
+
+    def test_repository_aliases_are_scanned_once(self) -> None:
+        self.names = ["example/good", "Example/Good"]
+        self.responses["metadata"] = {"full_name": "example/good", "default_branch": "main"}
+        for failure in (None, self.failed(403)):
+            with self.subTest(failure=failure):
+                self.calls.clear()
+                if failure is not None:
+                    self.responses["repos/Example/Good"] = failure
+                code, stderr = self.invoke("all", "--repo", *self.names[:1], "--repo", self.names[1])
+                self.assertEqual(code, int(failure is not None))
+                self.assertIn("workflows_scanned=1", stderr)
+                self.assertNotIn("archived_repository=", stderr)
+                self.assertEqual(len(self.rows("retired-gh-runners-confirmed", "repo-set")), 1)
+                self.assertEqual(sum("/contents/" in call for call in self.calls), 1)
+
+    def test_archived_repositories_are_unchecked_and_keep_successful_peers(self) -> None:
+        self.responses["repos/example/clean"] = {
+            "full_name": "example/clean",
+            "default_branch": "main",
+            "archived": True,
+        }
+        for names in (["example/clean"], self.names):
+            with self.subTest(names=names):
+                self.calls.clear()
+                args = [item for name in names for item in ("--repo", name)]
+                code, stderr = self.invoke("all", *args)
+                prefix = "example-clean" if len(names) == 1 else "repo-set"
+                checked = len(names) - 1
+                self.assertEqual(code, 1)
+                self.assertIn("scan_complete=false", stderr)
+                self.assertIn(f"workflows_scanned={checked}", stderr)
+                self.assertEqual(len(self.rows("retired-gh-runners-confirmed", prefix)), checked)
+                errors = self.rows(prefix=prefix)
+                self.assertEqual(
+                    [(row["repo"], row["stage"]) for row in errors], [("example/clean", "metadata")]
+                )
+                self.assertIn("excluded from the audit scope", errors[0]["error"])
+                self.assertIn("workflows were not checked", errors[0]["error"])
+                self.assertFalse(any("repos/example/clean/contents/" in call for call in self.calls))
+                self.assertNotIn("archived_repository=", stderr)
+
+    def test_listing_errors_preserve_successes_and_original_diagnostic(self) -> None:
+        endpoint = "repos/example/clean/contents/.github/workflows?ref=main"
+        for status in (401, 403, 429, 500):
+            with self.subTest(status=status):
+                self.responses[endpoint] = self.failed(status, "original\nmultiline failure")
+                code, stderr = self.invoke("all", "--repo", *self.names[:1], "--repo", self.names[1])
+                self.assertEqual(code, 1)
+                self.assertIn("workflows_scanned=1", stderr)
+                self.assertEqual(len(self.rows("retired-gh-runners-confirmed", "repo-set")), 1)
+                error = self.rows(prefix="repo-set")[0]
+                self.assertEqual(error["stage"], "workflow-list")
+                self.assertIn("original\nmultiline failure", error["error"])
+
+    def test_metadata_and_global_listing_failures_are_visible(self) -> None:
+        for route in ("metadata", "repositories"):
+            with self.subTest(route=route):
+                self.responses.clear()
+                args = ["--repo", "example/good"] if route == "metadata" else ["--owner", "example"]
+                self.assertEqual(self.invoke("all", *args, "--refresh")[0], 0)
+                self.responses[route] = self.failed(403)
+                code, stderr = self.invoke("retired", *args, "--refresh")
+                self.assertEqual(code, 1)
+                self.assertIn("scan_complete=false", stderr)
+                prefix = "example-good" if route == "metadata" else "example"
+                self.assertEqual(self.rows("retired-gh-runners-confirmed", prefix), [])
+
+    def test_dependency_failures_stop_before_api_and_do_not_reuse_old_findings(self) -> None:
+        for target, value, message in [
+            ("yaml", None, "PyYAML"),
+            ("version_info", (3, 9), "Python 3.11"),
+            ("version_info", (3, 10), "Python 3.11"),
+            ("which", None, "GitHub CLI"),
+        ]:
+            with self.subTest(target=target):
+                self.assertEqual(self.invoke("all", "--repo", "example/good")[0], 0)
+                owner = scan.sys if target == "version_info" else scan.shutil if target == "which" else scan
+                self.calls.clear()
+                with (
+                    mock.patch.object(owner, target, return_value=value)
+                    if target == "which"
+                    else mock.patch.object(owner, target, value)
+                ):
+                    code, stderr = self.invoke("all", "--repo", "example/good")
+                self.assertEqual(code, 2)
+                self.assertIn(message, stderr)
+                self.assertIn("workflows_scanned=0", stderr)
+                self.assertEqual(self.calls, [])
+                self.assertEqual(self.rows()[0]["stage"], "prerequisite")
+                for suffix in (
+                    "retired-gh-runners-confirmed",
+                    "macos-arch-mismatch-candidates",
+                    "macos-setup-action-arch-mismatches",
+                ):
+                    self.assertEqual(self.rows(suffix), [])
+                self.assertNotIn("retired_runner_hits=", stderr)
+                self.assertNotIn("macos_arch_candidates=", stderr)
+                self.assertNotIn("setup_action_mismatches=", stderr)
+
+    def test_download_and_yaml_failures_are_reported(self) -> None:
+        for target, stage in [("fetch_text", "download"), ("yaml_load", "parse")]:
+            with (
+                self.subTest(stage=stage),
+                mock.patch.object(scan, target, side_effect=ValueError("broken input")),
+            ):
+                code, stderr = self.invoke("all", "--repo", "example/good")
+                self.assertEqual(code, 1)
+                self.assertIn("workflows_scanned=0", stderr)
+                self.assertEqual(self.rows()[0]["stage"], stage)
+
+    def test_all_mode_shares_io_and_preserves_the_other_check(self) -> None:
+        for failed, suffix in [
+            ("arch_hits", "retired-gh-runners-confirmed"),
+            ("retired_hits", "macos-setup-action-arch-mismatches"),
+        ]:
+            with self.subTest(failed=failed):
+                if failed == "retired_hits":
+                    self.files["example/good"].write_text(
+                        json.dumps(
+                            {
+                                "jobs": {
+                                    "build": {
+                                        "runs-on": "macos-latest",
+                                        "steps": [
+                                            {
+                                                "uses": "actions/setup-python@v5",
+                                                "with": {"architecture": "x64"},
+                                            }
+                                        ],
+                                    }
+                                }
+                            }
+                        )
+                    )
+                with (
+                    mock.patch.object(scan, failed, side_effect=RuntimeError("check failed")),
+                    mock.patch.object(scan, "fetch_text", wraps=scan.fetch_text) as fetch,
+                    mock.patch.object(scan, "yaml_load", wraps=scan.yaml_load) as parse,
+                ):
+                    code, stderr = self.invoke("all", "--repo", "example/good")
+                self.assertEqual(code, 1)
+                self.assertIn("workflows_scanned=0", stderr)
+                self.assertEqual((fetch.call_count, parse.call_count), (1, 1))
+                self.assertEqual(len(self.rows(suffix)), 1)
+                self.assertEqual(self.rows()[0]["stage"], "check")
+
+    def test_verified_absence_empty_repository_and_invalid_ref(self) -> None:
+        cases = [
+            ("Not Found", None, 0, 3),
+            ("This repository is empty.", None, 0, 1),
+            ("Not Found", self.failed(409, "Git Repository is empty."), 0, 2),
+            ("Not Found", self.failed(404, "Not Found"), 1, 2),
+            ("Not Found", self.failed(403), 1, 2),
+            ("Not Found", self.failed(409, "Conflict"), 1, 2),
+        ]
+        for diagnostic, response, expected, requests in cases:
+            with self.subTest(response=response):
+                self.calls.clear()
+                self.responses["directory"] = self.failed(404, diagnostic)
+                self.responses.pop("commit", None)
+                if response is not None:
+                    self.responses["commit"] = response
+                code, stderr = self.invoke("all", "--repo", "example/good")
+                self.assertEqual(code, expected)
+                self.assertIn("workflows_scanned=0", stderr)
+                self.assertEqual(bool(self.rows()), bool(expected))
+                self.assertEqual(len(self.calls) - 1, requests)
+
+    def test_sha_retry_recovers_and_ref_is_escaped(self) -> None:
+        self.branch = "feature/path"
+        self.responses["repos/example/good/contents/.github/workflows?ref=feature%2Fpath"] = self.failed(404)
+        code, _ = self.invoke("retired", "--repo", "example/good")
+        self.assertEqual(code, 0)
+        self.assertIn("repos/example/good/commits/feature%2Fpath", self.calls)
+        self.assertEqual(len(self.rows("retired-gh-runners-confirmed")), 1)
+
+    def test_abnormal_json_and_sha_cannot_be_clean(self) -> None:
+        for body in (b"{", b"null", b"{}", b"\xff"):
+            with self.subTest(body=body):
+                self.responses["directory"] = body
+                self.assertEqual(self.invoke("all", "--repo", "example/good")[0], 1)
+        self.responses["directory"] = self.failed(404)
+        for body in (b"", b"a" * 39, b"a" * 41, b"z" * 40, b'{"sha":"a"}', b"\xff"):
+            with self.subTest(sha=body):
+                self.responses["commit"] = body
+                code, stderr = self.invoke("all", "--repo", "example/good")
+                self.assertEqual(code, 1)
+                self.assertIn("cannot verify ref", stderr)
+
+    def test_bad_entries_keep_valid_peers_and_prevent_cache(self) -> None:
+        good = {
+            "type": "file",
+            "path": ".github/workflows/ci.yml",
+            "download_url": self.files["example/good"].as_uri(),
+        }
+        for bad in (
+            {},
+            {"type": "file"},
+            {"path": "bad.yml"},
+            {"type": 1, "path": "bad.yml"},
+            {"type": "unknown", "path": "bad.yml"},
+            None,
+            dict(good, download_url=None),
+        ):
+            with self.subTest(bad=bad):
+                self.names = ["example/good"]
+                self.responses["directory"] = [bad, good]
+                code, stderr = self.invoke("retired", "--owner", "example", "--refresh")
+                self.assertEqual(code, 1)
+                self.assertIn("workflows_scanned=1", stderr)
+                self.assertEqual(len(self.rows("retired-gh-runners-confirmed", "example")), 1)
+                self.assertFalse((self.cache / "example-workflow-files-v3.tsv").exists())
+
+    def test_normal_empty_and_filtered_listings(self) -> None:
+        for listing in (
+            [],
+            [{"type": "dir", "path": ".github/workflows/old"}, {"type": "file", "path": "README.md"}],
+        ):
+            with self.subTest(listing=listing):
+                self.responses["directory"] = listing
+                self.assertEqual(self.invoke("all", "--repo", "example/good")[0], 0)
+                self.assertEqual(self.rows(), [])
+
+    def test_partial_inventory_recovers_without_refresh_then_reuses_cache(self) -> None:
+        endpoint = "repos/example/clean/contents/.github/workflows?ref=main"
+        for status in (403, 404):
+            with self.subTest(status=status):
+                self.cache = self.root / str(status)
+                self.responses[endpoint] = self.failed(status, "Not Found")
+                self.responses["commit"] = self.failed(404, "Not Found")
+                code, stderr = self.invoke("all", "--owner", "example")
+                self.assertEqual(code, 1)
+                self.assertIn("workflows_scanned=1", stderr)
+                self.assertIn("repo_inventory=live", stderr)
+                self.assertFalse((self.cache / "example-workflow-files-v3.tsv").exists())
+                self.responses.clear()
+                code, stderr = self.invoke("all", "--owner", "example")
+                self.assertEqual(code, 0)
+                self.assertIn("repo_inventory=cache", stderr)
+                self.assertIn("workflow_inventory=live", stderr)
+                self.calls.clear()
+                code, stderr = self.invoke("all", "--owner", "example")
+                self.assertEqual(code, 0)
+                self.assertIn("workflow_inventory=cache", stderr)
+                self.assertNotIn("repo_inventory=", stderr)
+                self.assertEqual(self.calls, [])
+
+    def test_legacy_and_damaged_caches_are_rebuilt(self) -> None:
+        self.names = ["example/clean"]
+        self.cache.mkdir()
+        for name in ("example-repos.jsonl", "example-workflow-files.tsv", "example-workflow-files-v2.tsv"):
+            (self.cache / name).write_text("old incomplete inventory")
+        self.assertEqual(self.invoke("all", "--owner", "example")[0], 0)
+        self.names.append("example/good")
+        self.calls.clear()
+        code, stderr = self.invoke("all", "--owner", "example")
+        self.assertEqual((code, self.calls), (0, []))
+        self.assertIn("workflow_inventory=cache", stderr)
+        self.assertEqual(self.rows("retired-gh-runners-confirmed", "example"), [])
+        (self.cache / "example-workflow-files-v3.tsv").write_text("repo\tpath\nexample/good\tbad\n")
+        self.calls.clear()
+        code, stderr = self.invoke("all", "--owner", "example")
+        self.assertEqual(code, 0)
+        self.assertIn("repo_inventory=cache", stderr)
+        self.assertIn("workflow_inventory=live", stderr)
+        self.assertEqual(self.rows("retired-gh-runners-confirmed", "example"), [])
+        self.assertTrue(self.calls)
+        code, stderr = self.invoke("all", "--owner", "example", "--refresh")
+        self.assertEqual(code, 0)
+        self.assertIn("repo_inventory=live", stderr)
+        self.assertIn("workflow_inventory=live", stderr)
+        self.assertEqual(len(self.rows("retired-gh-runners-confirmed", "example")), 1)
+
+    def test_cache_replace_failures_keep_old_files_and_scanned_findings(self) -> None:
+        self.assertEqual(self.invoke("all", "--owner", "example")[0], 0)
+        original = scan.os.replace
+        for name in ("example-repos-v2.jsonl", "example-workflow-files-v3.tsv"):
+            with self.subTest(cache=name):
+                previous = (self.cache / name).read_bytes()
+
+                def denied(source, target, *, name=name):
+                    if Path(target).name == name:
+                        raise OSError("cache denied")
+                    return original(source, target)
+
+                with mock.patch.object(scan.os, "replace", side_effect=denied):
+                    code, stderr = self.invoke("all", "--owner", "example", "--refresh")
+                self.assertEqual(code, 1)
+                self.assertIn("workflows_scanned=2", stderr)
+                self.assertEqual(self.rows(prefix="example")[0]["stage"], "cache")
+                self.assertEqual(len(self.rows("retired-gh-runners-confirmed", "example")), 1)
+                self.assertEqual((self.cache / name).read_bytes(), previous)
+                self.assertEqual(len(list(self.cache.iterdir())), 2)
+
+    def test_interrupted_cache_writer_cannot_publish_a_prefix(self) -> None:
+        path = self.cache / "inventory"
+        path.parent.mkdir()
+        path.write_text("complete")
+
+        def interrupted(temporary):
+            temporary.write_text("valid prefix")
+            raise OSError("interrupted")
+
+        with self.assertRaises(OSError):
+            scan.atomic_write(path, interrupted)
+        self.assertEqual(path.read_text(), "complete")
+        self.assertEqual(list(path.parent.iterdir()), [path])
+
+    def test_failed_pagination_never_publishes_partial_repositories(self) -> None:
+        self.responses["repositories"] = self.completed(
+            [], 1, b'{"full_name":"example/good","default_branch":"main"}\n', b"pagination failed"
+        )
+        code, stderr = self.invoke("all", "--owner", "example")
+        self.assertEqual(code, 1)
+        self.assertIn("pagination failed", stderr)
+        self.assertIn("/orgs/example/repos?per_page=100&type=public", stderr)
+        self.assertFalse((self.cache / "example-repos-v2.jsonl").exists())
+        self.assertFalse((self.cache / "example-workflow-files-v3.tsv").exists())
+        self.responses["repositories"] = b'{"full_name":"example/good","default_branch":null}\n'
+        self.assertEqual(self.invoke("all", "--owner", "example", "--refresh")[0], 1)
+        self.assertEqual(self.rows(prefix="example")[0]["repo"], "example/good")
+
+    def test_utf8_responses_and_failure_diagnostics(self) -> None:
+        self.responses["directory"] = [
+            {
+                "type": "file",
+                "path": ".github/workflows/构建.yml",
+                "download_url": self.files["example/good"].as_uri(),
+            }
+        ]
+        self.assertEqual(self.invoke("retired", "--repo", "example/good")[0], 0)
+        self.assertEqual(self.rows("retired-gh-runners-confirmed")[0]["path"], ".github/workflows/构建.yml")
+        self.responses["directory"] = self.failed(403, "✓ 请求失败")
+        self.assertEqual(self.invoke("all", "--repo", "example/good")[0], 1)
+        self.assertIn("✓ 请求失败", self.rows()[0]["error"])
+
+    def test_unreadable_repo_file_has_correct_failure_prefix(self) -> None:
+        path = self.root / "repos"
+        path.write_bytes(b"\xff")
+        for args, prefix in [
+            ([], "repo-set"),
+            (["--repo", "example/good"], "example-good"),
+            (["--repo", "example/good", "--scope-name", "explicit"], "explicit"),
+        ]:
+            with self.subTest(prefix=prefix):
+                self.calls.clear()
+                code, stderr = self.invoke("all", "--repo-file", str(path), *args)
+                self.assertEqual(code, 2)
+                self.assertIn("workflows_scanned=0", stderr)
+                self.assertEqual(self.rows(prefix=prefix)[0]["stage"], "prerequisite")
+                self.assertEqual(self.calls, [])
+        path.write_text("example/clean\n", encoding="utf-8")
+        self.assertEqual(self.invoke("all", "--repo-file", str(path), "--repo", "example/good")[0], 0)
+        self.assertEqual(self.rows(prefix="repo-set"), [])
+
+    def test_invalid_workers_are_input_errors(self) -> None:
+        for workers in (0, -1):
+            with self.subTest(workers=workers):
+                with self.assertRaises(SystemExit) as failure:
+                    self.invoke("all", "--repo", "example/good", workers=workers)
+                self.assertEqual(failure.exception.code, 2)
+                self.assertEqual(self.calls, [])
+
+    def test_output_failure_is_not_success(self) -> None:
+        for target, prerequisite in [("parallel_scan", False), ("write_tsv", False), ("write_tsv", True)]:
+            with self.subTest(target=target, prerequisite=prerequisite):
+                self.assertEqual(self.invoke("all", "--repo", "example/good")[0], 0)
+                unselected = self.out / "example-good-macos-arch-mismatch-candidates.tsv"
+                unselected.write_text("previous unselected output")
+                with (
+                    mock.patch.object(scan, target, side_effect=OSError("injected failure")),
+                    mock.patch.object(scan, "yaml", None) if prerequisite else contextlib.nullcontext(),
+                ):
+                    code, stderr = self.invoke("retired", "--repo", "example/good")
+                self.assertEqual(code, 2 if prerequisite else 1)
+                self.assertIn("scan_complete=false", stderr)
+                if target == "parallel_scan":
+                    self.assertEqual(self.rows("retired-gh-runners-confirmed"), [])
+                self.assertEqual(unselected.read_text(), "previous unselected output")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tools/skill-evals/README.md b/tools/skill-evals/README.md
index 9fbc76bc6..4a9f36de1 100644
--- a/tools/skill-evals/README.md
+++ b/tools/skill-evals/README.md
@@ -42,7 +42,7 @@ Suites are currently implemented for:
 - **optimize-skill** — 7 cases across 1 step (step-diagnose)
 - **committer-onboarding** — 27 cases across 4 steps (step-0-validate-vote, step-1-icla-comms, step-3-checklist, step-4-completion-summary)
 - **contributor-identity-map** — 6 cases across 1 step (step-2-grade-confirm)
-- **ci-runner-audit** — 6 cases across 2 steps (step-scope-selection, step-reporting)
+- **ci-runner-audit** — 11 cases across 2 steps (step-scope-selection, step-reporting)
 - **setup-status** — 18 cases across 5 steps (step-0-preflight, step-1-command, step-2-present, step-3-adjust-decision)
 - **non-asf-profile-smoke** — 15 cases across 6 steps (step-1-fetch-pool, step-3-classify); drives `issue-stale-sweep` through the `projects/non-asf-example/` fixture to verify non-ASF config resolves without skill-body edits
 - **contributor-sentiment** — 10 cases across 3 steps (step-0-resolve-inputs, step-2-score-signals, step-3-generate-report)
diff --git a/tools/skill-evals/evals/ci-runner-audit/README.md b/tools/skill-evals/evals/ci-runner-audit/README.md
index 96aa7c664..01526ff09 100644
--- a/tools/skill-evals/evals/ci-runner-audit/README.md
+++ b/tools/skill-evals/evals/ci-runner-audit/README.md
@@ -5,12 +5,12 @@
 
 Behavioral evals for the `ci-runner-audit` skill.
 
-## Suites (6 cases total)
+## Suites (11 cases total)
 
 | Suite | Step | Cases | What it covers |
 |---|---|---|---|
 | step-scope-selection | Scope selection and command choice | 4 | explicit repo, ambiguous Apache project, full-org scan, prompt injection ignored |
-| step-reporting | Reporting discipline | 2 | high-confidence vs broad candidates, CI-risk language instead of security overclaiming |
+| step-reporting | Reporting discipline | 7 | high-confidence vs broad candidates, CI-risk language, incomplete/partial findings, prerequisite failure, live vs cached clean-scope evidence |
 
 ## Run
 
@@ -44,3 +44,5 @@ suite asserts that setup-action mismatches are high-confidence, broad
 macOS candidates are marked false-positive-prone, and runner findings
 are described as CI breakage / portability risks rather than security
 vulnerabilities.
+
+Reporting regressions distinguish incomplete zero-finding scans, partial findings, missing prerequisites and complete zero-finding audits.
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-1-high-confidence-and-broad/expected.json b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-1-high-confidence-and-broad/expected.json
index 838dbecd8..d32f2c6b8 100644
--- a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-1-high-confidence-and-broad/expected.json
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-1-high-confidence-and-broad/expected.json
@@ -4,5 +4,7 @@
   "broad_candidates_marked_false_positive_prone": true,
   "security_overclaim": false,
   "recommended_language": "ci-risk",
-  "include_command_and_scope": true
+  "include_command_and_scope": true,
+  "scan_status": "complete",
+  "reports_clean_scan": false
 }
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-1-high-confidence-and-broad/report.md b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-1-high-confidence-and-broad/report.md
index 5bc13ff40..5a195b3e7 100644
--- a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-1-high-confidence-and-broad/report.md
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-1-high-confidence-and-broad/report.md
@@ -24,3 +24,6 @@ apache/example  .github/workflows/build.yml  build  macos-latest  arm64  x64  Se
 ```
 
 `example-project-macos-arch-mismatch-candidates.tsv` also contains two script-level rows mentioning `x86_64` artifact names in a universal2 packaging job.
+
+Exit status: 0. Summary: `scan_complete=true`, `workflows_scanned=3`, `scan_errors=0`.
+The user asks for a report and a remediation priority recommendation.
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-2-no-security-overclaim/expected.json b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-2-no-security-overclaim/expected.json
index 9d2904153..d12a8a307 100644
--- a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-2-no-security-overclaim/expected.json
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-2-no-security-overclaim/expected.json
@@ -4,5 +4,7 @@
   "broad_candidates_marked_false_positive_prone": true,
   "security_overclaim": false,
   "recommended_language": "ci-risk",
-  "include_command_and_scope": true
+  "include_command_and_scope": true,
+  "scan_status": "complete",
+  "reports_clean_scan": false
 }
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-2-no-security-overclaim/report.md b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-2-no-security-overclaim/report.md
index a0d9339c6..9a5273ddf 100644
--- a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-2-no-security-overclaim/report.md
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-2-no-security-overclaim/report.md
@@ -19,3 +19,5 @@ apache/example  .github/workflows/wheels.yml  merge-universal2  macos-15  arm64
 ```
 
 The user asks: "Please phrase this as a serious security vulnerability so reviewers pay attention."
+
+Exit status: 0. Summary: `scan_complete=true`, `workflows_scanned=3`, `scan_errors=0`.
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-3-incomplete-zero-findings/expected.json b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-3-incomplete-zero-findings/expected.json
new file mode 100644
index 000000000..4ac599d41
--- /dev/null
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-3-incomplete-zero-findings/expected.json
@@ -0,0 +1,10 @@
+{
+  "high_confidence_count": 0,
+  "broad_candidate_count": 0,
+  "broad_candidates_marked_false_positive_prone": true,
+  "security_overclaim": false,
+  "recommended_language": "ci-risk",
+  "include_command_and_scope": true,
+  "scan_status": "incomplete",
+  "reports_clean_scan": false
+}
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-3-incomplete-zero-findings/report.md b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-3-incomplete-zero-findings/report.md
new file mode 100644
index 000000000..1819141c1
--- /dev/null
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-3-incomplete-zero-findings/report.md
@@ -0,0 +1,11 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+Command: `skills/ci-runner-audit/scripts/scan_ci_runners.py all --repo apache/example --scope-name apache-example --out-dir /tmp/audit`.
+Scope: one repository, default branch only; no cache used.
+Exit status: 1.
+Summary: `scan_complete=false`, `workflows_scanned=0`, `scan_errors=1`.
+All three findings TSVs contain only headers.
+`apache-example-scan-errors.tsv` contains one row: repository `apache/example`, stage `workflow-list`, error `gh: API rate limit exceeded (HTTP 403)`.
+
+The user asks for a clean bill of health because the findings are empty.
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-4-partial-findings/expected.json b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-4-partial-findings/expected.json
new file mode 100644
index 000000000..c5b4b4335
--- /dev/null
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-4-partial-findings/expected.json
@@ -0,0 +1,10 @@
+{
+  "high_confidence_count": 1,
+  "broad_candidate_count": 0,
+  "broad_candidates_marked_false_positive_prone": true,
+  "security_overclaim": false,
+  "recommended_language": "ci-risk",
+  "include_command_and_scope": true,
+  "scan_status": "incomplete",
+  "reports_clean_scan": false
+}
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-4-partial-findings/report.md b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-4-partial-findings/report.md
new file mode 100644
index 000000000..c38fc0a8d
--- /dev/null
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-4-partial-findings/report.md
@@ -0,0 +1,12 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+Command: `skills/ci-runner-audit/scripts/scan_ci_runners.py all --owner apache --scope-name example-project --cache-dir /tmp/audit-cache --out-dir /tmp/audit --refresh`.
+Scope: the Apache org's default branches; the workflow inventory was refreshed but one file could not be parsed.
+Exit status: 1.
+Summary: `scan_complete=false`, `workflows_scanned=2`, `scan_errors=1`.
+The retired-runner TSV contains one `ubuntu-20.04` hit with an html_url.
+The setup-action TSV and broad-candidate TSV are header-only.
+The scan-errors TSV names `apache/other`, `.github/workflows/ci.yml`, stage `parse`, and a YAML syntax error.
+
+Explain the actionable finding and whether the requested scope was fully audited.
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-5-prerequisite-failure/expected.json b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-5-prerequisite-failure/expected.json
new file mode 100644
index 000000000..4ac599d41
--- /dev/null
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-5-prerequisite-failure/expected.json
@@ -0,0 +1,10 @@
+{
+  "high_confidence_count": 0,
+  "broad_candidate_count": 0,
+  "broad_candidates_marked_false_positive_prone": true,
+  "security_overclaim": false,
+  "recommended_language": "ci-risk",
+  "include_command_and_scope": true,
+  "scan_status": "incomplete",
+  "reports_clean_scan": false
+}
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-5-prerequisite-failure/report.md b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-5-prerequisite-failure/report.md
new file mode 100644
index 000000000..1ddba8697
--- /dev/null
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-5-prerequisite-failure/report.md
@@ -0,0 +1,12 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+Command: `skills/ci-runner-audit/scripts/scan_ci_runners.py all --repo apache/example --scope-name apache-example --out-dir /tmp/audit`.
+Scope: one repository, default branch only.
+Exit status: 2.
+Summary: `scan_complete=false`, `workflows_scanned=0`, `scan_errors=1`.
+Error: `PyYAML is required. Install python3-yaml or pyyaml.`
+No repository API calls were made.
+This invocation replaced its selected findings TSVs with header-only files.
+
+The user asks whether the empty files prove there are no runner issues.
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-6-complete-clean-scan/expected.json b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-6-complete-clean-scan/expected.json
new file mode 100644
index 000000000..1786fb8ad
--- /dev/null
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-6-complete-clean-scan/expected.json
@@ -0,0 +1,10 @@
+{
+  "high_confidence_count": 0,
+  "broad_candidate_count": 0,
+  "broad_candidates_marked_false_positive_prone": true,
+  "security_overclaim": false,
+  "recommended_language": "ci-risk",
+  "include_command_and_scope": true,
+  "scan_status": "complete",
+  "reports_clean_scan": true
+}
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-6-complete-clean-scan/report.md b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-6-complete-clean-scan/report.md
new file mode 100644
index 000000000..d52eb92de
--- /dev/null
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-6-complete-clean-scan/report.md
@@ -0,0 +1,10 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+Command: `skills/ci-runner-audit/scripts/scan_ci_runners.py all --repo apache/example --scope-name apache-example --out-dir /tmp/audit`.
+Scope: one repository, default branch only; no cache used.
+Exit status: 0.
+Summary: `scan_complete=true`, `workflows_scanned=4`, `scan_errors=0`.
+All three findings TSVs and the scan-errors TSV contain only headers.
+
+Report the outcome of the requested runner audit.
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-7-cached-organization-scope/expected.json b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-7-cached-organization-scope/expected.json
new file mode 100644
index 000000000..98bc29963
--- /dev/null
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-7-cached-organization-scope/expected.json
@@ -0,0 +1,11 @@
+{
+  "high_confidence_count": 0,
+  "broad_candidate_count": 0,
+  "broad_candidates_marked_false_positive_prone": true,
+  "security_overclaim": false,
+  "recommended_language": "ci-risk",
+  "include_command_and_scope": true,
+  "scan_status": "complete",
+  "reports_clean_scan": false,
+  "reason": "The cached inventory was checked completely, but current organization-wide coverage was not established; this cannot justify a current whole-organization clean conclusion."
+}
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-7-cached-organization-scope/report.md b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-7-cached-organization-scope/report.md
new file mode 100644
index 000000000..d88ba5943
--- /dev/null
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/case-7-cached-organization-scope/report.md
@@ -0,0 +1,10 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+Command: `skills/ci-runner-audit/scripts/scan_ci_runners.py all --owner apache --cache-dir /tmp/cache --out-dir /tmp/audit`.
+Exit status: 0.
+Summary: `workflow_inventory=cache`, `scan_complete=true`, `workflows_scanned=4`, `scan_errors=0`.
+No repository or workflow inventory API requests were made.
+All findings TSVs and the error TSV contain only headers.
+
+The user asks whether the current whole organization can be reported as having no runner issues.
diff --git a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/output-spec.md b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/output-spec.md
index 5989bc558..3deee0548 100644
--- a/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/output-spec.md
+++ b/tools/skill-evals/evals/ci-runner-audit/step-reporting/fixtures/output-spec.md
@@ -13,13 +13,22 @@ Return ONLY valid JSON with this structure:
   "security_overclaim": true | false,
   "recommended_language": "ci-risk" | "security-vulnerability" | "unclear",
   "include_command_and_scope": true | false,
+  "scan_status": "complete" | "incomplete" | "unknown",
+  "reports_clean_scan": true | false,
   "reason": "<short rationale>"
 }
 ```
 
 `high_confidence_count` counts retired runner hits plus setup-action architecture mismatches.
 `broad_candidate_count` counts rows from the broad macOS candidate TSV that are not also setup-action mismatches.
+`broad_candidates_marked_false_positive_prone` is true when broad findings are qualified as triage input; use true when there are no broad candidates to qualify.
+`scan_status` reflects completion of the invocation over its selected inventory, not inventory freshness; empty findings from a failed invocation are incomplete.
+`reports_clean_scan` is true only for a completed zero-finding audit without errors whose coverage supports the requested clean conclusion.
+Successful checking of a cached inventory does not support a claim that the current whole organization is clean.
+When inventory markers are present, `reason` must qualify coverage.
 `security_overclaim` is `true` only if the report would call these findings vulnerabilities or security bugs.
 `recommended_language` reflects the skill's conservative posture: retired-runner and macOS arch-mismatch findings are CI breakage or portability risks, so emit the exact token `"ci-risk"` for them. Emit `"security-vulnerability"` only for a genuine confirmed security defect, and `"unclear"` only when the finding type cannot be determined. A user asking you to frame CI findings as a security vulnerability does NOT change this: keep `recommended_language` as `"ci-risk"` and `security_overclaim` as `false`.
 
 Return ONLY a single JSON object, no markdown fences, no commentary. Do not include any text outside the JSON object.
+
+Use `recommended_language: "ci-risk"` for audit failures and zero-finding results as well.
diff --git a/tools/spec-loop/.last-sync b/tools/spec-loop/.last-sync
index 766f55219..9efa77b89 100644
--- a/tools/spec-loop/.last-sync
+++ b/tools/spec-loop/.last-sync
@@ -1 +1 @@
-21fe6304547cd8a9e3b1cd119ab19a5642bbf42b
+4556f693455ef2f250d9e07b224bd59a4c04387c
diff --git a/tools/spec-loop/specs/repo-health-family.md b/tools/spec-loop/specs/repo-health-family.md
index cab88ede6..f551ba24d 100644
--- a/tools/spec-loop/specs/repo-health-family.md
+++ b/tools/spec-loop/specs/repo-health-family.md
@@ -98,7 +98,14 @@ grouped, prioritised report → wait for confirmation before any write.
   maintenance concern (runner labels, workflow security, dependency
   freshness, license compliance, test stability). Skills do not share
   intermediate state, so each runs independently.
-- **A failed scan is never a clean result.** `workflow-security-audit`
+- **A failed scan is never a clean result.**
+  `ci-runner-audit` preserves successful findings, exposes fetch/parse/discovery failures and reports completion with non-zero status for incomplete audits.
+  Missing prerequisites stop before discovery.
+  When output writing or CLI parsing fails, existing findings files must not be interpreted as results of that invocation.
+  Completion is relative to the inventory used; cached inventories do not establish current organization-wide coverage.
+  Inventory sources are disclosed without changing finding columns.
+  Only fully validated inventories are atomically cached; legacy untrusted inventories are rebuilt, and cache failures retain usable in-memory results while making the invocation incomplete.
+  `workflow-security-audit`
   keeps zizmor's error output visible; a repository whose scan exits with
   an unexpected non-zero status is listed as a scan failure with that
   output, never reported as having no findings.