@@ -29,40 +29,40 @@ description = "Static checks: ruff, shellcheck, and actionlint via pre-commit"
 run = "uv run pre-commit run --all-files"
 
 [tasks."test:tools"]
-description = "L1: test the shared shell scripts offline (bats)"
+description = "Test shell scripts offline with bats"
 run = "bats generator/scripts/tests"
 
 [tasks."test:preprocess"]
-description = "L2: test spec patching and the endpoint checker"
+description = "Test spec patching and endpoint coverage"
 run = "uv run python -m unittest generator.tests.test_strip_schema_titles generator.tests.test_openapi_overlay generator.tests.test_endpoint_coverage"
 
 [tasks."test:unit"]
-description = "L4: test the generated SDK and contract-case derivation offline"
+description = "Run unit tests offline"
 run = "uv run python -m unittest tests.test_sdk_smoke tests.test_wiretap_cases"
 
 [tasks."check:generated"]
-description = "L3: fail if regeneration changes upcloud_api/ or the patched spec"
+description = "Fail if regeneration changes upcloud_api/ or the patched spec"
 run = "bash generator/scripts/check_generated.sh upcloud_api generator/openapi/spec.patched.json -- mise run generate --force"
 
 [tasks."check:endpoints"]
-description = "L3: check that every spec operation has generated code"
+description = "Check that every spec operation has generated code"
 run = "uv run python generator/scripts/check_endpoint_coverage.py generator/openapi/spec.json generator/openapi/spec.patched.json upcloud_api/api"
 
 [tasks."test:contract"]
-description = "L5: run SDK calls against a local Wiretap mock; writes validation-artifacts/"
+description = "Run SDK calls against a local Wiretap mock (writes validation-artifacts/)"
 run = 'VALIDATION_ARTIFACTS="${VALIDATION_ARTIFACTS:-validation-artifacts}" bash generator/scripts/wiretap.sh generator/openapi/spec.patched.json uv run python -m unittest tests.test_wiretap'
 
 [tasks.check]
 alias = "test"
-description = "Integrity gate (must be green): lint, test:tools, test:preprocess, test:unit, check:generated"
+description = "Run required checks: lint, test:tools, test:preprocess, test:unit, check:generated"
 run = "mise run --jobs 1 lint ::: test:tools ::: test:preprocess ::: test:unit ::: check:generated"
 
 [tasks.findings]
-description = "Findings gate (red on known spec/generator defects): check:endpoints, test:contract"
+description = "Run check:endpoints and test:contract (fails on known spec/generator issues)"
 run = "mise run --continue-on-error --jobs 1 check:endpoints ::: test:contract"
 
 [tasks.validate]
-description = "Run check and findings, even if check fails (kept for one release)"
+description = "Run check and findings, even if check fails"
 run = "mise run --continue-on-error --jobs 1 check ::: findings"
 
 [tasks.build]
@@ -95,10 +95,10 @@ flag "--spec-file <file>" default="upcloud-public-openapi.json" help="Spec membe
 run = 'bash generator/scripts/download_spec.sh --version "$usage_version" --asset-url "$usage_asset_url" --spec-file "$usage_spec_file"'
 
 [tasks.regenerate]
-description = "Generate, then run the check gate; stops at the first failure"
+description = "Generate the SDK and run checks"
 run = ["mise run generate", "mise run check"]
 
 [tasks.examples]
-description = "L6: run live mdtest examples, all by default (creates real UpCloud resources; requires UPCLOUD_TOKEN)"
+description = "Run live mdtest examples (creates real UpCloud resources, requires UPCLOUD_TOKEN)"
 usage = 'arg "[name]..." var=#true help="Directory under examples/ (default: all)"'
 run = 'bash generator/scripts/run_examples.sh ${usage_name:-file-storage object-storage tag kubernetes}'
@@ -26,7 +26,7 @@ jobs:
         uses: jdx/mise-action@dad1bfd3df957f44999b559dd69dc1671cb4e9ea # v4.2.1
         with:
           version: 2026.10.3
-      - name: Integrity gate (must be green)
+      - name: Run checks
         run: mise run check
   unit:
     runs-on: ubuntu-latest
@@ -59,9 +59,9 @@ jobs:
         uses: jdx/mise-action@dad1bfd3df957f44999b559dd69dc1671cb4e9ea # v4.2.1
         with:
           version: 2026.10.3
-      - name: Findings gate (red on known spec or generator defects; does not block release)
+      - name: Run endpoint and contract checks
         run: mise run findings
-      - name: Upload contract diagnostics
+      - name: Upload Wiretap artifacts
         if: always()
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
 
@@ -52,23 +52,22 @@ jobs:
           SPECS_ACCESS_PAT: ${{ secrets.SPECS_ACCESS_PAT }}
         run: mise run spec:download "$SPEC_VERSION" "$ASSET_URL" --spec-file "$SPEC_FILE"
 
-      # Integrity gate: if generation or `check` fails, no PR is opened.
-      - name: Generate, then run the check gate
+      - name: Generate and run checks
         id: regenerate
         run: mise run regenerate
 
-      - name: Run the findings gate (reported in the PR; does not block it)
+      - name: Run endpoint and contract checks
         id: findings
         if: ${{ !cancelled() && (steps.regenerate.outcome == 'success' || steps.regenerate.outcome == 'failure') }}
         continue-on-error: true
         run: mise run findings
 
-      - name: Save the generated changes as a patch
+      - name: Save generated changes as a patch
         run: |
           git add -A -- generator/openapi upcloud_api
           git diff --cached --binary > regenerate.patch
 
-      - name: Upload generated changes and contract diagnostics
+      - name: Upload generated changes and Wiretap artifacts
         if: always()
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
@@ -124,8 +123,8 @@ jobs:
           body: |
             Automated regeneration for spec version `${{ env.SPEC_VERSION }}`.
 
-            The integrity gate (`mise run check`) passed.
-            Findings gate (`mise run findings`): **${{ needs.generate.outputs.findings }}**.
-            The PR is a draft while findings fail; see the `regenerated-sdk` artifact
+            `mise run check` passed.
+            `mise run findings`: **${{ needs.generate.outputs.findings }}**.
+            The PR is opened as a draft when `findings` fails. See the `regenerated-sdk` artifact
             of ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
             for the Wiretap and endpoint reports.
@@ -67,7 +67,7 @@ The [mise](https://mise.jdx.dev/) configuration pins `openapi-python-client`,
 The `generate` task runs `generator/scripts/generate.sh` on the checked-in
 `generator/openapi/spec.json` (no download). It refuses to overwrite uncommitted
 changes in `upcloud_api/` unless you pass `mise run generate --force`.
-`mise run regenerate` runs `generate`, then the `check` gate, and stops at the
+`mise run regenerate` runs `generate`, then `check`, and stops at the
 first failure with a non-zero exit. The generated changes stay in place for
 investigation. Neither task changes `pyproject.toml` or `uv.lock`. A stale lock
 fails the `uv` commands, and only `mise run lock` and `mise run version:set` update it.
@@ -111,66 +111,51 @@ UV_PYTHON=pypy3.11 mise run test:unit
 | --- | --- |
 | `setup` | Install locked development dependencies. |
 | `lint` | Run pre-commit: ruff, shellcheck, and actionlint. |
-| `test:tools` | L1: test the shared shell scripts offline with bats. |
-| `test:preprocess` | L2: test schema-title filtering (`test_strip_schema_titles.py`), overlay fixes, and the endpoint checker. |
-| `test:unit` | L4: test the generated SDK and the contract-case derivation offline. |
-| `check:generated` | L3: regenerate and fail if `upcloud_api/` or `spec.patched.json` changes. |
-| `check:endpoints` | L3: check that every spec operation has a generated method/path contract. |
-| `test:contract` | L5: run generated sync/async SDK calls against a local Wiretap mock. |
-| `check` | Integrity gate: `lint`, `test:tools`, `test:preprocess`, `test:unit`, `check:generated`. Must be green. Alias: `test`. |
-| `findings` | Findings gate: `check:endpoints` and `test:contract`, run even if one fails. Red on known defects. |
-| `validate` | Run `check` and `findings`, even if `check` fails. Kept for one release. |
+| `test:tools` | Test the shell scripts offline with bats. |
+| `test:preprocess` | Test schema-title filtering, overlay fixes, and the endpoint checker. |
+| `test:unit` | Run offline unit tests for the SDK and Wiretap test cases. |
+| `check:generated` | Regenerate and fail if `upcloud_api/` or `spec.patched.json` changes. |
+| `check:endpoints` | Check that every spec operation has generated code. |
+| `test:contract` | Run generated sync/async SDK calls against a local Wiretap mock. |
+| `check` | Run required checks: `lint`, `test:tools`, `test:preprocess`, `test:unit`, `check:generated`. Alias: `test`. |
+| `findings` | Run `check:endpoints` and `test:contract` (fails on known spec and generator issues). |
+| `validate` | Run `check` and `findings`, even if `check` fails. |
 | `build` | Build a wheel and source distribution into `dist/`, then run `twine check`. |
 | `generate [--force]` | Regenerate the SDK from the checked-in spec. |
 | `regenerate` | Run `generate`, then `check`, and stop at the first failure. |
 | `lock` | Update `uv.lock`. |
-| `version:set <version>` | Explicitly change `[project].version` in `pyproject.toml` and `uv.lock` with `uv version --no-sync`. |
+| `version:set <version>` | Set `[project].version` in `pyproject.toml` and `uv.lock` with `uv version --no-sync`. |
 | `spec:download <version> <asset_url>` | Download a released spec using `SPECS_ACCESS_PAT` (used by the regeneration workflow). |
-| `examples [name...]` | L6: run live mdtest documents, all four by default. |
+| `examples [name...]` | Run live mdtest examples, all four by default. |
 
-### Test layers and gates
+### Checks and contract tests
 
-Every check belongs to one layer, and every defect fails exactly one check.
+`check` runs the required static, unit, and generation checks. It blocks builds,
+releases, and regeneration PRs.
 
-| Layer | Guards | Members |
-| --- | --- | --- |
-| L1 tools | The shared shell scripts behave safely. | `generator/scripts/tests/*.bats` |
-| L2 preprocess | Overlay fixes and title filtering are correct and idempotent. | `generator/tests/test_strip_schema_titles.py`, `test_openapi_overlay.py`, `test_endpoint_coverage.py` |
-| L3 generation | Committed output equals generator output, and every spec operation is generated. | `check:generated`, `check:endpoints` |
-| L4 SDK unit | Generated imports, enums, `client.py.jinja` behavior, contract-case derivation. | `tests/test_sdk_smoke.py`, `tests/test_wiretap_cases.py` |
-| L5 contract | SDK calls match the spec on the wire. | `tests/test_wiretap.py` via `wiretap.sh` |
-| L6 live | Real API behavior. | `examples/**/*.md` via mdtest |
-
-There are two gates. `check` (integrity) must always be green: a red `check`
-means the pipeline itself is broken. It blocks builds, releases, and regeneration
-PRs. `findings` covers the known spec and generator defects: a red `findings`
-means the spec or generator still has a known defect. It always runs and uploads
-its diagnostics, but it does not block releases. Regeneration PRs are opened as
-drafts while it fails.
+`findings` runs `check:endpoints` and `test:contract` to report known spec and
+generator issues without blocking releases. Regeneration PRs are opened as
+drafts when `findings` fails.
 
 `mise install` installs every pinned tool, including `wiretap`, `bats`,
 `shellcheck`, `actionlint`, `twine`, and `mdtest` (built with the pinned Go).
 Wiretap runs as a local binary in mock mode and doesn't need Docker or Podman.
 No task except `examples` needs UpCloud credentials or makes real UpCloud requests,
 but the first run needs network access to install tools and dependencies.
 
-The existing endpoint and Wiretap findings remain strict failures, not exemptions.
-`generator/scripts/wiretap.sh` starts Wiretap, sends a deliberately invalid canary
-request, runs the Python tests, and then fails if the report is missing, lacks the
-canary, or contains any other violation. It writes `wiretap.log` and
-`wiretap-report.json`. The Python tests add the `coverage.json` case inventory,
-which lists operations without generated code under `missing` (`check:endpoints`
-reports them as failures). All three go to `validation-artifacts/` (override with
-`VALIDATION_ARTIFACTS`). CI uploads these diagnostics.
+`generator/scripts/wiretap.sh` starts Wiretap, sends an invalid probe request to
+verify validation is active, runs the Python tests, and fails if the report is
+missing or contains any other violation. It writes `wiretap.log`,
+`wiretap-report.json`, and `coverage.json` to `validation-artifacts/` (override
+with `VALIDATION_ARTIFACTS`).
 
-### Task names across SDK repositories
+### Shared scripts across SDK repositories
 
-The task names, their inputs, and their exit semantics are the portable interface:
+The task names are shared across the Python, Go, and PHP SDK repositories:
 `setup`, `lint`, `generate`, `test:tools`, `test:preprocess`, `test:unit`,
 `check:generated`, `check:endpoints`, `test:contract`, `check`, `findings`,
-`build`, `spec:download`, `regenerate`, `examples`, and `version:set`. Go and PHP
-SDK repositories can use the same names. Only the `run` bodies are
-language-specific.
+`build`, `spec:download`, `regenerate`, `examples`, and `version:set`. Only the
+`run` commands are language-specific.
 
 Scripts with the header line `Copied unchanged into each UpCloud SDK repository`
 don't depend on the SDK language. They need only `bash`, `git`, `curl`, `tar`, and
 
@@ -12,7 +12,7 @@
 from pathlib import Path
 
 HTTP_METHODS = {"get", "put", "post", "delete", "patch", "head", "options", "trace"}
-SURFACES = {"sync_detailed", "asyncio_detailed"}
+FUNCTIONS = {"sync_detailed", "asyncio_detailed"}
 
 
 def normalize_path(path: str) -> str:
@@ -46,13 +46,13 @@ def endpoint_contract(path: Path) -> tuple[str, str]:
         for node in tree.body
         if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
     }
-    missing = SURFACES - functions.keys()
+    missing = FUNCTIONS - functions.keys()
     if missing:
-        raise ValueError(f"{path}: missing call surfaces {sorted(missing)}")
+        raise ValueError(f"{path}: missing functions {sorted(missing)}")
     if not isinstance(functions["asyncio_detailed"], ast.AsyncFunctionDef):
         raise ValueError(f"{path}: asyncio_detailed is not async")
     if ("sync" in functions) != ("asyncio" in functions):
-        raise ValueError(f"{path}: inconsistent parsed sync/async surfaces")
+        raise ValueError(f"{path}: inconsistent sync/async functions")
     builder = functions.get("_get_kwargs")
     if builder is None:
         raise ValueError(f"{path}: missing _get_kwargs")
@@ -115,7 +115,7 @@ def check_coverage(spec: dict, directory: Path, patched: dict | None = None) ->
     ids = Counter(operation["operationId"] for operation in expected.values())
     errors.extend(f"Duplicate operationId: {name}" for name, count in ids.items() if count > 1)
     if patched is not None and expected.keys() != operations(patched).keys():
-        errors.append("Preprocessing changed the method/path inventory")
+        errors.append("Preprocessing changed the operations")
     return errors
 
 
 
@@ -1,5 +1,5 @@
 #!/usr/bin/env bats
-# wiretap.sh report gate, with fake wiretap and curl binaries; jq is real.
+# Test wiretap.sh with fake wiretap and curl binaries (jq is real).
 
 bats_require_minimum_version 1.5.0
 
 
@@ -38,7 +38,7 @@ def test_formatted_path_and_matching_contract(self):
             self.assertTrue(any("Missing" in error for error in errors))
             self.assertTrue(any("Unexpected" in error for error in errors))
 
-    def test_duplicates_and_missing_surfaces_fail(self):
+    def test_duplicates_and_missing_functions_fail(self):
         with tempfile.TemporaryDirectory() as directory:
             api = Path(directory)
             (api / "server").mkdir()
@@ -48,7 +48,7 @@ def test_duplicates_and_missing_surfaces_fail(self):
             second.write_text(SOURCE)
             self.assertTrue(any("Duplicate generated" in e for e in check_coverage(SPEC, api)))
             second.write_text(SOURCE.replace("async def asyncio_detailed(): pass", ""))
-            self.assertTrue(any("missing call surfaces" in e for e in check_coverage(SPEC, api)))
+            self.assertTrue(any("missing functions" in e for e in check_coverage(SPEC, api)))
 
     def test_unsupported_expressions_and_removed_operations_fail(self):
         with tempfile.TemporaryDirectory() as directory:
 
@@ -70,7 +70,7 @@ async def call_gateway_plan_async(client):
 
 
 class SDKSmokeTests(unittest.TestCase):
-    """Check generated surfaces without making any network requests."""
+    """Test generated client and models without network requests."""
 
     def test_every_generated_api_and_model_module_imports(self):
         """Generator output and spec patches: every `api/` and `models/` module imports."""
 
@@ -48,7 +48,7 @@ def recover_documented_parse_failure(case, mode, error, responses, requests):
 
 
 class WiretapTests(unittest.IsolatedAsyncioTestCase):
-    """Exercise the SDK; generator/scripts/wiretap.sh owns the server and the report check."""
+    """Run SDK calls against Wiretap (wiretap.sh starts the server and checks the report)."""
 
     @classmethod
     def setUpClass(cls):
 
@@ -115,8 +115,8 @@ def test_scalar_conversions(self):
         with self.assertRaises(ValueError):
             convert("invalid", Literal["yes", "no"])
 
-    def test_operation_without_generated_code_is_inventoried_as_missing(self):
-        """A later derivable operation must not erase the missing-operation inventory."""
+    def test_operation_without_generated_code_is_recorded_as_missing(self):
+        """A later derivable operation must not clear the missing operations list."""
         ok = {"responses": {"200": {"description": "ok"}}}
         spec = {
             "paths": {
@@ -318,7 +318,7 @@ def test_known_response_does_not_hide_other_failures(self):
         )
         changed_title = json.loads(documented_body())
         changed_title["title"] = "Other"
-        # Parse failures before classification surface as the genuine model KeyError, not as
+        # Parse failures before classification raise the model KeyError, not
         # an AssertionError, because only the exact documented response is adapted.
         scenarios = {
             "wrong status": (self.serve(status=500), label, KeyError),