v0.5.0 release scope and acceptance checklist

## Release objective

Ship chctl 0.5.0 with the Cloud CLI coverage planned in #699, plus the remaining correctness, local-development, output-contract, and CLI consistency work below.

This is the overall release scope tracker. #699 remains the detailed Cloud coverage plan and issue-to-PR matrix; individual issues remain the implementation owners. A submitted PR is not completed release work: track completion when the change is merged and validated.

Scope agreed on 2026-09-06: include all items from the remaining-issue review except #129 (locally built binaries) and #206 (live Pub/Sub E2E). The previously optional and deferred items listed below are now included in 0.5.0.

## Existing Cloud scope

- [ ] Complete and merge #699's 37 implementation issues and API baseline #522, including the separate library prerequisites and follow-up fixes. The recorded 53-layer stack runs from #700 through #754; use #699's issue-to-PR matrix rather than duplicating it here.
- [ ] Land the live CDC fixture repair #747 / #750 as part of that stack.
- [ ] Land README branding and product overview #755 / #756.

## Remaining implementation scope: 16 issues

### Correctness and release reliability

- [ ] #677 — Prevent closed-stderr credential/debug notices from panicking before Cloud command dispatch; add subprocess coverage proving the command still runs.
- [ ] #679 — Reject private-endpoint removal inputs missing provider or region instead of substituting defaults; fail before sending a request.
- [ ] #253 — Make the native-argument boundary explicit for both local clients. Require `--` for passthrough so unknown options cannot swallow later wrapper flags or change connection selection. Document compatibility changes and test both clients.
- [ ] #684 — Move closed-set flag validation to clap so invalid values produce usage exit 2 and discoverable possible values before networking.
- [ ] #685 — Reject MySQL ClickPipe port zero and audit other source-port parsers for the same omission.
- [ ] #673 — Classify service-delete failures structurally and preserve failure metadata when rewriting their messages.
- [ ] #676 — Bound generated integration resource names while preserving uniqueness; make manual Cloud integration dispatch reliable. Record the CLI name-length validation decision separately from any broader library constraint work.
- [ ] #687 — Isolate local test ports and project state and remove fragile wall-clock assumptions so the release test suite is reliable under load.
- [ ] #680 — Return the correct running-Postgres removal error with an actionable stop command. Track the issue's additional resume-JSON suggestion separately rather than letting it obscure the removal fix.

### Output contracts and CLI consistency

- [ ] #468 — Define and test the local-client JSON contract, carrying this unresolved issue forward from 0.4.2. Retain native output; explicitly document that `--json` and coding-agent detection do not select a SQL output format. Cover interactive, query, query-file, and explicit native-format cases.
- [ ] #683 — Render Postgres config through `print_human` in human mode and preserve JSON in explicit/agent JSON mode.
- [ ] #686 — Support consistent `--org-id` selection and auto-detection on org get/update while retaining positional compatibility; define and test conflicts and precedence.
- [ ] #689 — Add whole-tree clap validation and structural help checks for descriptions, context limits, and shared flags. Validate README command examples where useful. Follow current AGENTS.md: no whole-screen equality snapshots or wording pins, and no requirement to duplicate every command in README.

### Local-development behavior and exit-code policy

- [ ] #250 — Implement opt-in global data directories. Define selection, discovery, isolation, and migration behavior while preserving project-local behavior for existing users.
- [ ] #254 — Implement automatic loading of the special default server config. Coordinate with #250 and define explicit-config precedence and behavior when no default exists.
- [ ] #234 — Complete the exit-code taxonomy review and implement/document the agreed mapping with coverage. Start from the current codes (0 success, 1 error, 2 usage, 3 cancelled, 4 auth required, child exits passed through); the original issue's cancellation mapping is stale. Decide permission failures and transient/rate-limit signaling explicitly and document any compatibility changes.

## Ordering and design decisions

Resolve #250/#254 together before implementing their shared scope and precedence behavior. Resolve #234's policy alongside #684 so parsing and runtime errors remain coherent. #253's native-argument boundary and #468's output contract should be reviewed together. Keep API-library changes separate from CLI exposure and use linked, reviewable PRs for each owning issue.

## Bookkeeping and exclusions

- [x] Reconcile #333 with merged #622: the shipped decision is to document single-statement Cloud Query API input and direct multi-statement scripts to the native client. Close the stale issue on that basis; client-side SQL splitting is not new release work.
- [x] Align included issues with the v0.5.0 milestone, including #468's carryover and the previously unmilestoned fixes.
- [ ] Reconcile #699's checklist with merged PRs and final validation before closing the Cloud tracker.

Excluded: #129 and #206. The missing live Pub/Sub test remains a known validation gap, not a completed test or a release requirement.

## Release acceptance

- [ ] All included implementation work is merged, with linked issues/PRs and README/help updates for user-visible behavior and compatibility changes.
- [ ] The final combined revision passes formatting, both CLI Clippy configurations, telemetry-compiled-out checks, tests for every touched crate, applicable API/analyzer/Python checks, and classifier checks required by AGENTS.md.
- [ ] Required live Cloud suites pass against the final release candidate, including manual dispatch; historical or intermediate results are not substituted for final validation.
- [ ] Release notes describe the Cloud expansion, local scope/config behavior, argument boundary, output contracts, and any exit-code changes.
- [ ] Bump release versions in lockstep per AGENTS.md and verify release readiness before tagging.

## Implementation progress — 2026-09-08

25 submitted, ready-for-review PRs in GitHub stack #769 cover 21 issues. These are implementation submissions, not merged release completion. The stack starts at #767 and ends at #793.

| Issue | Submitted PRs |
| --- | --- |
| #253 | #785 |
| #468 | #789 |
| #673 | #771 |
| #676 | #784 |
| #677 | #767 |
| #679 | #770 |
| #680 | #783 |
| #683 | #778 |
| #684 | #775 |
| #685 | #776 |
| #686 | #782 |
| #687 | #774 |
| #689 | #792 |
| #758 | #772, #773 |
| #759 | #780, #781 |
| #760 | #768 |
| #761 | #788 |
| #762 | #777 |
| #763 | #793 |
| #766 | #790, #791 |
| #779 | #786, #787 |

The later live-audit work is included: #758–#763, current OpenAPI drift #766 (Prometheus graduation plus Kinesis Protobuf fields/enums), and numeric setting readback #779 discovered while verifying #759. Their original scope is preserved in separate issue-owned PRs; API prerequisites and CLI changes remain separate.

Design decisions deferred to Al: #250/#254 need coordinated global data selection, discovery/migration, and config precedence; #234 needs permission/transient/rate-limit exit-code policy. The optional CLI name-length guard in #676 was not adopted; generated harness names are now bounded and fingerprinted, while the API remains the authority for user-supplied names.

Targeted live validation covered Docker Postgres SQL effects and child exits, real native ClickHouse output including interactive terminals, service-setting updates and typed readback, metrics timestamp normalization, and object-storage field-mapping updates. Agent-created fixtures were cleaned up.

Combined stack head `4c17bc55d89108a0a73579b0655baf8189d97207` passed formatting, default CLI Clippy, telemetry-disabled build and all-target Clippy, all CLI tests, API/analyzer all-target Clippy and tests, Python/classifier tests, the real Docker input regression, and diff checks. A fresh live OpenAPI check reports zero actionable drift (five explicitly acknowledged unsupported enum constraints remain).

The final manual all-suites Cloud run is in progress: https://github.com/ClickHouse/clickhousectl/actions/runs/34229729628. Additional required per-PR Cloud runs are queued by the shared integration concurrency gate. These pending checks have not been waived or represented as passing; release acceptance remains open.

## Current-PR finalization — 2026-09-11

The assigned QA follow-ups are implemented on their **13 existing owning PRs, covering 14 issues wholly or partially**. The 39-layer stack was propagated and published, ending at `82b374816a917cbac3a68194659beaaa5c7c9087`. The existing #822 native-settings CI fixture was also repaired to use the managed lifecycle service, without new secrets or workflow changes. No new PRs were opened, no PRs were merged, and all QA issues remain open pending their remaining scope and merge requirements.

Only the named sub-items belong in this pass. The other QA work stays open for later; deferral here does not change its severity or the release scope above.

| Existing PR | QA issue(s) | Implemented work (pending CI/merge) |
|---|---|---|
| #768 | #856 | Choose Docker input mode from terminal/input conditions; support plain piped SQL and native passthrough such as `-- -c`. Preserve stdin EOF, child exit codes and #812 SQL-input diagnostics. |
| #775 | #841 | Expose canonical possible values on the remaining ClickPipe `--auth` flags. Preserve current accepted modes and aliases; auth inference and new credential requirements are outside this change. |
| #777 | #846 | State the supported pipe-kind constraint on `scale --replicas`, consistent with the adjacent CPU/memory flags and verified API behavior. |
| #781 | #832, #849 | Prevent lossy numeric input in both `--setting` and settings-file/stdin maps; retain exact in-range signed/unsigned integers. Cover u64::MAX, overflow and exponent inputs at the wire boundary. Coordinate with #822 without making this earlier PR depend on a descendant.
Include the settings-file path in file-open/read diagnostics; cover missing input before organization lookup or HTTP. |
| #792 | #848 | Fix indentation of the settings-set and query-endpoint-create CONTEXT blocks; extend structural help coverage to catch the inconsistency. Do not add wording-pinning tests. |
| #793 | #845 | Bring the already-verified object-storage fieldMappings/destination.columns requirement into update input help. Keep it scoped to object-storage; do not introduce unverified universal PATCH validation. |
| #811 | #850, #844, #837, #849 | Render present empty arrays and empty strings explicitly in the shared human renderer; preserve absent-field handling and PEM summaries.
Resolve item 6 (hidden empty fields) through the shared renderer; no separate ClickPipe-specific rendering change.
Resolve the empty-array-only slow-query detail producing zero human-output bytes; preserve JSON omission of an absent aggregate.
Make an API-supplied empty setting string visible in human output. Preserve the JSON value; do not reinterpret it as unset/null. |
| #814 | #844 | Resolve item 1: remove serde Option/untagged traversal artifacts from generic unknown-field paths and identify stdin input clearly. Retain strict unknown-field rejection and the specific BigQuery diagnostic. |
| #816 | #855, #860 | Use shared idempotent runtime-ignore creation for init and startup, even if metadata locking created the directory first. Preserve custom ignore contents and propagate write failures; cover ClickHouse and Postgres bootstrap paths.
Correct init JSON paths on a no-op and on a gitignore-only repair; update the existing repeated-init test that currently expects the misleading path. |
| #818 | #860 | Add the ClickHouse-only scope of `server list --global` to the Postgres parent help. No new global Postgres discovery behavior. |
| #819 | #848 | Document entry `id` and `isActiveNow` as response-only alongside `baseConfig`, while keeping the agent context within its line budget. |
| #821 | #839 | Make negative --limit values reach the existing range validators on logs and slow-query list, as --offset already does; retain the distinct 1–2000 and 1–500 limits. |
| #823 | #864 | Replace the README example value 268435456 with an in-range value such as 536870912; validate the example against the new insert-size bounds. |

### Final-revision validation and CI

- Local gates passed on `82b374816a917cbac3a68194659beaaa5c7c9087`: formatting; default CLI Clippy/tests; telemetry-disabled check and all-target Clippy; API/analyzer all-target Clippy/tests; Python/classifier checks. Results: 1,822 CLI tests, 639 library/doc tests, and 91 Python tests passed. Live tests remain separate from the ignored-by-default tests.
- Strict real Postgres 18 Docker validation passed on the same head: startup-ignore creation and custom-file preservation, plain SQL pipe/EOF, native `-- -c`, child exit 3, #812 missing-input diagnostics, redirected terminal output, genuine PTY query and Ctrl-D/EOF exit 0. Disposable container, volume and project cleanup was verified.
- Independent range-diff review confirmed all 39 PR commit ranges and ancestry were preserved. #781's self-contained precision guard and tests survive through #822; no descendant dependency was introduced. Explicit original-SHA leases protected the atomic publication of 38 changed heads.
- Required final-head Cloud runs were requested for #768, #772, #780, #784, #786, #789, #790 and #822. A separate [combined all-suite run](https://github.com/ClickHouse/clickhousectl/actions/runs/34607296509) is running on the final top head. These serialized live runs remain pending; old runs are not substituted and no overrides were recorded. The remaining PRs use their automatic no-suite decisions where selected by the trusted planner.
- The 14 affected QA issues now have implemented sub-items checked, with remaining scope preserved. The 13 owning PR descriptions and #822's fixture description record final scope and validation. Final CI reconciliation and merge/release acceptance remain open.

| Required PR run | Final head | Live validation |
|---|---|---|
| #768 | `fc9db82757c1` | [Run 34607307595](https://github.com/ClickHouse/clickhousectl/actions/runs/34607307595) |
| #772 | `b83648ff5251` | [Run 34607313153](https://github.com/ClickHouse/clickhousectl/actions/runs/34607313153) |
| #780 | `38baf09fcfcb` | [Run 34607319944](https://github.com/ClickHouse/clickhousectl/actions/runs/34607319944) |
| #784 | `2cf72b48930f` | [Run 34607326476](https://github.com/ClickHouse/clickhousectl/actions/runs/34607326476) |
| #786 | `cdbd161db05e` | [Run 34607334032](https://github.com/ClickHouse/clickhousectl/actions/runs/34607334032) |
| #789 | `54f131205325` | [Run 34607342761](https://github.com/ClickHouse/clickhousectl/actions/runs/34607342761) |
| #790 | `e46a72aa6ac9` | [Run 34607349933](https://github.com/ClickHouse/clickhousectl/actions/runs/34607349933) |
| #822 | `4521e1062023` | [Run 34607357195](https://github.com/ClickHouse/clickhousectl/actions/runs/34607357195) |

All 31 expected no-suite Cloud decisions have reconciled to success. The eight runs above are authorized on their exact final heads and remain queued; their decisions will reconcile after live execution.

### Execution and merge checks

- [x] Apply the assigned changes on each existing owning PR branch, with focused regression coverage and README/help updates where applicable.

- [x] For #781, preserve stack direction: #822 is later in the stack. Do not import a later API type into #781 without restructuring the prerequisites; prefer a self-contained precision guard or align #822 after the earlier fix.

- [x] Propagate/rebase descendants in the stack order and resolve overlaps once, especially #768/#812, #781/#787/#822, and #811/#814. A later PR must not reintroduce behavior fixed earlier.

- [x] Run cargo fmt, both CLI Clippy configurations, telemetry-compiled-out checks, and tests for touched crates; run applicable API/analyzer/Python/classifier checks per AGENTS.md. Add classifier entries if source/test files are added or renamed.

- [ ] Validate Docker input/PTY/EOF behavior and runtime gitignore bootstrap with appropriate subprocess/live checks; run required affected Cloud integration checks on final PR heads and preserve the existing release acceptance requirements.

- [x] Update existing PR descriptions to name these sub-items and validation. Use whole-issue closing keywords only when all of an issue is resolved; do not close batch issues for partial fixes.

- [ ] Recheck all current required checks on the final propagated stack before merge. Unlisted PRs retain their original scope and existing review/CI obligations; this audit does not certify them merge-ready.

### Deferred from this pass

Whole QA issues deferred: #825, #826, #827, #828, #829, #830, #831, #833, #834, #835, #836, #838, #840, #842, #843, #847, #851, #852, #853, #854, #857, #858, #859, #861, #862, #863. Their reviewed scope and corrections are recorded on the issues. Partial issues retain explicit remaining-scope notes.

In particular, #853 is broader usage validation than #775, #851 is ClickPipe org-flag propagation rather than #782's org get/update selectors, and #852 beta casing is distinct from #791's Prometheus graduation. #845 universal mapping enforcement needs evidence beyond #793's object-storage verification. These are not forced into unrelated PRs merely to avoid opening a new one.

#847 is diagnostics discoverability, not a blanket API blocker. #832 separates confirmed overflow parsing from the unproven CLI attribution of live u64-max rounding. #852/#863 retain correct API units/wire shapes unless an explicit contract change is agreed.

Start with the individual implementation issues and the #699 issue-to-PR matrix rather than treating this tracker as a single code change. Read AGENTS.md and the release acceptance checklist, then inspect the final Cloud validation workflow and current stack status. Done means included work is merged and validated, required checks pass, release notes and versions are updated, and release readiness is confirmed.

Written by the indexing model from the issue text.