fix: verwerk review-opmerkingen op de diagnose-laag

- README: json-diagnose gaat naar stdout, dus > out.json i.p.v. 2>err.json
- UNKNOWN krijgt eigen exit code 3 (niet 1 'jouw fout', niet 2 'veilig retryen')
  zodat de exit code de honesty-lijn volgt; README- en CLAUDE-tabel bijgewerkt
- spec-conformance: ontbrekend specbestand faalt hard i.p.v. stil te skippen
- verwijder em-dashes uit gebruikersgerichte foutmeldingen en docstrings

Author: anneschuth

CLAUDE.md

@@ -164,7 +164,7 @@ where to look, and suggest the fix. The machinery lives in `api/errors.py`:
 - **`Fault`** (StrEnum): `USER_INPUT`, `USER_APP`, `USER_CONFIG`, `AUTH`, `PLATFORM`,
   `NETWORK`, `UNKNOWN`. Drives a neutral source label (`FAULT_SOURCE`), color
   (`FAULT_COLOR`), and CI/CD exit code (`FAULT_EXIT_CODE`: 1 = your fault, 2 =
-  platform/transient).
+  platform/transient, 3 = unknown/unattributable).
 - **`Diagnosis`** (dataclass): `fault`, `headline`, `summary`, `details`, `next_steps`,
   `status_code`. `to_dict()` is the json contract (CI branches on `fault`).
 - **`diagnose_http_error`** parses status codes and FastAPI `422` validation arrays;
@@ -181,12 +181,12 @@ Rules for new code:
 - After any mutating op, call `surface_warnings(ctx, formatter, result)` so warnings /
   unhealthy components are surfaced (and `--strict` can fail CI).
 - **Honesty:** when the API gives no category, the fault is `UNKNOWN` and we point at
-  the logs — don't guess whose fault it is.
+  the logs (exit code 3); don't guess whose fault it is.
 
 **Spec coupling:** `CATEGORY_FAULT` / `CATEGORY_HINT` are keyed by `ErrorCategory`, and
 `tests/test_spec_conformance.py` asserts the enum matches `api/upstream-openapi.json` and
 that every category is mapped. When the api-sync workflow surfaces a new `ErrorCategory`,
-add it to `models.ErrorCategory` **and** both maps — the conformance test tells you.
+add it to `models.ErrorCategory` **and** both maps; the conformance test tells you.
 
 ### Client method conventions
 

README.md

@@ -75,15 +75,15 @@ zad metrics overview --output json | jq '.cpu_usage'
 ## Errors & exit codes
 
 Errors tell you **what's wrong and what to do next**, with a neutral label for where
-to look — your request, your application, your configuration, your credentials, or the
-ZAD platform — instead of a bare HTTP code. A failed image pull points you straight at
+to look (your request, your application, your configuration, your credentials, or the
+ZAD platform) instead of a bare HTTP code. A failed image pull points you straight at
 the image and registry (`Source: your application (cluster runtime)`) with the fix.
 
 Each error carries a structured diagnosis. In `--output json` it's a single object
 on stdout you can branch on in CI/CD:
 
 ```bash
-zad deployment create app -c web=img:tag -o json 2>err.json || jq -r .fault err.json
+zad deployment create app -c web=img:tag -o json > out.json || jq -r .fault out.json
 # UserInput | UserApp | UserConfig | Auth | Platform | Network | Unknown
 ```
 
@@ -92,8 +92,9 @@ Exit codes:
 | Code | Meaning |
 |------|---------|
 | `0` | success |
-| `1` | your fault — fix it (bad input, app/config failure, auth) |
-| `2` | platform/network — transient, safe to retry |
+| `1` | your fault, fix it (bad input, app/config failure, auth) |
+| `2` | platform/network, transient and safe to retry |
+| `3` | unknown, the API gave no signal to attribute the failure (check the logs) |
 
 `--strict` makes a command that *succeeds but reports warnings* (e.g. the deploy
 applied but a component is crash-looping) exit non-zero, so a pipeline fails the

src/zad_cli/api/client.py

@@ -61,11 +61,11 @@ def _parse_v2_response(model_cls: type, payload: Any) -> dict:
             f"Unexpected API response shape for {model_cls.__name__}: {e}",
             diagnosis=Diagnosis(
                 fault=Fault.PLATFORM,
-                headline="ZAD returned a response this CLI couldn't read — likely a CLI/API version mismatch.",
+                headline="ZAD returned a response this CLI couldn't read; likely a CLI/API version mismatch.",
                 summary=f"Schema {model_cls.__name__} failed to validate.",
                 next_steps=[
                     "Retry shortly (exit code 2 = transient).",
-                    "If it persists, the CLI may be out of date — update it or report the mismatch.",
+                    "If it persists, the CLI may be out of date; update it or report the mismatch.",
                 ],
                 status_code=502,
             ),
@@ -248,7 +248,7 @@ def _poll_task(self, poll_url: str) -> dict:
             task_id=task_id,
             diagnosis=Diagnosis(
                 fault=Fault.UNKNOWN,
-                headline=f"Timed out after {self.task_timeout}s waiting for the task — it may still be running.",
+                headline=f"Timed out after {self.task_timeout}s waiting for the task; it may still be running.",
                 next_steps=["This is a wait limit, not a failure. Check `zad task status <id>`."],
             ),
         )

src/zad_cli/api/errors.py

@@ -1,9 +1,9 @@
 """Clear, actionable diagnosis of API and task failures.
 
 The goal is simple: tell the user *what went wrong and what to do next*. The
-upstream API already carries the signal for that — ``ErrorCategory`` on cluster
-errors, ``ComponentFailureInfo`` (with log tails) on failed deployment tasks,
-``HTTPValidationError`` on bad input, ``error_type`` on task results — but a bare
+upstream API already carries the signal for that (``ErrorCategory`` on cluster
+errors, ``ComponentFailureInfo`` with log tails on failed deployment tasks,
+``HTTPValidationError`` on bad input, ``error_type`` on task results), but a bare
 ``HTTP 500`` / ``Task failed`` string throws it away.
 
 This module turns those raw signals into a :class:`Diagnosis`: a plain-language
@@ -39,15 +39,15 @@ class Fault(StrEnum):
     UNKNOWN = "Unknown"  # not enough signal to attribute honestly
 
 
-# Neutral, source-labelled phrasing (no blame — just where the fault lives).
+# Neutral, source-labelled phrasing (no blame, just where the fault lives).
 FAULT_SOURCE: dict[Fault, str] = {
     Fault.USER_INPUT: "your request",
     Fault.USER_APP: "your application (cluster runtime)",
     Fault.USER_CONFIG: "your configuration / git",
     Fault.AUTH: "your credentials / permissions",
     Fault.PLATFORM: "ZAD platform",
     Fault.NETWORK: "network / connectivity",
-    Fault.UNKNOWN: "unknown — see logs",
+    Fault.UNKNOWN: "unknown (see logs)",
 }
 
 # Rich color: user-fixable = yellow, escalate/investigate = red, auth = magenta.
@@ -61,15 +61,17 @@ class Fault(StrEnum):
     Fault.UNKNOWN: "red",
 }
 
-# CI/CD exit codes: 1 = your fault (fix it), 2 = platform/transient (safe to retry).
+# CI/CD exit codes: 1 = your fault (fix it), 2 = platform/transient (safe to retry),
+# 3 = unattributable. UNKNOWN gets its own code rather than claiming "your fault"
+# (1) or "safe to retry" (2) when the API gave us no signal to attribute the failure.
 FAULT_EXIT_CODE: dict[Fault, int] = {
     Fault.USER_INPUT: 1,
     Fault.USER_APP: 1,
     Fault.USER_CONFIG: 1,
     Fault.AUTH: 1,
     Fault.PLATFORM: 2,
     Fault.NETWORK: 2,
-    Fault.UNKNOWN: 1,
+    Fault.UNKNOWN: 3,
 }
 
 # Which fault each cluster ErrorCategory implies. Keyed by ErrorCategory so the
@@ -272,22 +274,22 @@ def _http_headline(status_code: int, fault: Fault) -> tuple[str, list[str]]:
         )
     if status_code == 404:
         return (
-            "Not found (HTTP 404) — the resource you referenced doesn't exist.",
+            "Not found (HTTP 404): the resource you referenced doesn't exist.",
             ["Check the name/spelling and that it exists (e.g. `zad deployment list`)."],
         )
     if status_code == 409:
         return (
-            "Conflict (HTTP 409) — the resource is in a state that blocks this action.",
+            "Conflict (HTTP 409): the resource is in a state that blocks this action.",
             ["Check its current state, then retry once it settles."],
         )
     if status_code == 422:
         return (
-            "Invalid request (HTTP 422) — the values you sent didn't pass validation.",
+            "Invalid request (HTTP 422): the values you sent didn't pass validation.",
             ["Fix the field(s) listed above and retry."],
         )
     if fault is Fault.PLATFORM:
         return (
-            f"ZAD platform error (HTTP {status_code}) — usually transient.",
+            f"ZAD platform error (HTTP {status_code}), usually transient.",
             ["Retry shortly (exit code 2 = transient). If it persists, report it with the time of the call."],
         )
     return (f"Request rejected (HTTP {status_code}).", [])
@@ -370,7 +372,7 @@ def degraded_diagnoses(result: object) -> list[Diagnosis]:
                 fault=Fault.USER_CONFIG,
                 headline="The operation succeeded with warnings.",
                 details=[str(w) for w in warnings],
-                next_steps=["Review the warnings above — they usually point at your configuration."],
+                next_steps=["Review the warnings above; they usually point at your configuration."],
             )
         )
 

src/zad_cli/api/models.py

@@ -182,7 +182,7 @@ class ProcessingStatus(BaseModel):
     """Processing-step status inside a task result.
 
     Mirrors the upstream task-models ``ProcessingStatus`` schema (the richer of
-    the two same-named schemas — it carries ``component_failures``).
+    the two same-named schemas, the one that carries ``component_failures``).
     """
 
     status: str

tests/test_errors.py

@@ -79,7 +79,8 @@ def test_task_failure_syncfailed_text_is_user_config() -> None:
 def test_task_failure_unknown_stays_unknown() -> None:
     d = diagnose_task_failure("something odd happened", {})
     assert d.fault is Fault.UNKNOWN
-    assert d.exit_code == 1
+    # UNKNOWN gets its own exit code: not "your fault" (1), not "safe to retry" (2).
+    assert d.exit_code == 3
     assert "logs" in " ".join(d.next_steps).lower()
 
 

tests/test_spec_conformance.py

@@ -3,8 +3,12 @@
 These assert the CLI's hand-written enums/mappings match the vendored OpenAPI spec
 (api/upstream-openapi.json). When the daily api-sync workflow refreshes the spec and
 the upstream adds/changes an ErrorCategory, these tests fail loudly with a clear
-instruction — turning a silent drift into an actionable PR. This is the *strict* half
+instruction, turning a silent drift into an actionable PR. This is the *strict* half
 of the coupling; runtime parsing (category_of / _coerce_unknown_*) is the *loose* half.
+
+The vendored spec is part of the repo, so a missing file is a hard failure, not a
+skip: skipping would let the whole conformance check pass silently if the file is ever
+moved or renamed.
 """
 
 import json
@@ -20,7 +24,10 @@
 
 def _spec_schemas() -> dict:
     if not _SPEC_PATH.exists():
-        pytest.skip(f"vendored spec not found at {_SPEC_PATH}")
+        pytest.fail(
+            f"vendored spec not found at {_SPEC_PATH}. It is part of the repo and these "
+            "conformance tests depend on it; if it moved, update _SPEC_PATH instead of skipping."
+        )
     return json.loads(_SPEC_PATH.read_text())["components"]["schemas"]