fix(generator): preserve nested gcloud synopsis branch requirements

[thomhurst]

Review of generated Google PR #5338 at 34bc46d found three defects reproduced by the captured Google Cloud SDK 585 help already in the generator tests.

Responsible source: tools/ModularPipelines.OptionsGenerator/src/ModularPipelines.OptionsGenerator/Scrapers/Cli/GcloudSynopsisGroupReconciler.cs and UsageSynopsisParser.cs.

• Storage batch-operation source selection: the synopsis pairs a bucket/bucket-list choice with a manifest/prefix choice as one source branch. Generated validation counts those halves as separate exclusive alternatives, rejecting documented bucket requests; nested filters also reject dry-run and Insights sources.
• Storage custom contexts: the synopsis allows clear-all alone, a clear/update pair, or an update file. Generated validation flattens these branches and rejects both clear-all and the documented clear/update pair.
• Agent Identity OAuth providers: the selected three-legged branch requires all six options; the two-legged branch requires all three. Generated validation only requires any member, allowing incomplete credentials.

Evidence: #5338 Codex review; captured fixtures Fixtures/Gcloud/585.0.0/gcloud-storage-batch-operations-jobs-create.txt (synopsis lines 6-24 and examples 38-76) and gcloud-agent-identity-auth-providers-create.txt (synopsis lines 5-8).

Expected: preserve nested alternatives and branch-local conjunctions through generic synopsis reconciliation, with captured-help and generated-validator regressions for valid and incomplete branches. Fix source separately, merge it, then regenerate from latest main and validate the Google integration. Do not patch generated files or preserve obsolete APIs. Related: #5180, #4799.

[thomhurst]

Source fix 81c30d0 is confirmed at the remote head of #5340. It preserves required option-group syntax before positional parsing defers it and rebuilds fully matched nested validation constraints. All three captured generated-validator regressions failed before the fix; 19 focused checks now pass, covering valid bucket/filter combinations, custom-context clear/update alternatives, every missing OAuth companion, and existing Google resource/provider contracts. Full CI and review are running. This closed generated snapshot remains superseded; the generated-output findings remain open until a fresh latest-main replacement is validated.

[thomhurst]

Source prerequisite #5340 now includes 6739a90, which also addresses the review finding that flattened synopsis alternatives rejected documented Cloud Build trigger updates. All 26 focused generator checks pass. Storage custom-context tests now follow the documented independent clear/update choices, and 42 integration cases are prepared for the fresh generated snapshot. Full source CI and reviews remain in progress; this issue stays open until latest-main generation and the actual Google integration suite pass.

[thomhurst]

Source prerequisite #5340 merged as 1be7211 after all 3,368 generator tests, CodeQL, and reviews passed. Fresh latest-main Google generation is running with auto-merge disabled: https://github.com/thomhurst/ModularPipelines/actions/runs/35676360503. The replacement snapshot and actual Google integration suite remain required before closing this issue.

[thomhurst]

Fresh replacement #5341 applies artifact 10673523529 unchanged from generation run 35676360503 on main 1be7211. Latest-main freshness, reverse-application, command coverage, and documentation checks pass; generated Google library builds. Seven handwritten test files include 42 new Storage/OAuth/Cloud Build runtime cases and the four required constructor adaptations. Actual integration execution is running in https://github.com/thomhurst/ModularPipelines/actions/runs/35678558349; acceptance remains pending.

[thomhurst]

Review of fresh #5341 found that the required-synopsis pass still invents mandatory branch members. In SDK 585, cluster-director clusters update supports individual granular changes, but the generated validator adds 32 companion requirements (for example, setting Description requires AddFilestoreInstances and every other update flag). The SDK source lib/surface/cluster_director/clusters/update.py constructs a required mutually exclusive choice between optional granular flags and a config/update-mask bundle; adjacency in the rendered synopsis does not make all granular flags required.

The same authoritative check corrects the earlier OAuth finding: lib/surface/agent_identity/auth_providers/_partials/_create_ga.yaml explicitly sets required: false on every two/three-legged OAuth member, including PKCE. The new generator tests that demanded every member were based on an incorrect interpretation of SYNOPSIS. The generator must preserve branch exclusivity and explicit conditional requirements without inventing per-member requirements from adjacency.

Responsible source: tools/ModularPipelines.OptionsGenerator/src/ModularPipelines.OptionsGenerator/Scrapers/Cli/GcloudCliScraper.cs, especially ConvertSynopsisConstraint and required-choice reconciliation. Add captured regressions for individual granular changes, explicit config/update-mask companions, and SDK-declared optional OAuth members. Inspect the other 74 changed generated files for the same inference. #5341 will be closed and its CI cancelled; fix source separately before another latest-main generation.

[thomhurst]

Source fix #5342 is open at e8482e5. It preserves per-member and nested-choice requiredness from documented FLAGS instead of inferring mandatory companions from SYNOPSIS adjacency. All 30 focused checks pass, including captured Cluster Director, Composer, GKE, Storage, Cloud Build, and corrected optional OAuth cases. Full generator CI and reviews are running. Seven handwritten integration test files are prepared for the next fresh snapshot, with 61 cases in the nested-synopsis test class.

[thomhurst]

Source fix #5342 is merged as c2ccb29. All 3,379 generator tests pass, and CodeQL, CodeFactor, Claude, CodeRabbit, and Codex are clear. All review findings are addressed, and no pending CI remains on the merged source PR.

Fresh latest-main generation: https://github.com/thomhurst/ModularPipelines/actions/runs/35682446460. The replacement will retain SDK-documented branch optionality while enforcing explicit GKE autoprovisioning dependencies. Sixty-seven handwritten runtime cases are prepared for the Google integration. This issue remains open until the unchanged artifact and actual Google integration CI pass review and validation.

[thomhurst]

Independent review of SDK 585.0.0 help found another nested-choice defect in GcloudCliScraper.PreserveDocumentedChoices. gcloud managed-kafka clusters update documents an at least one group of independent settings, with a nested at most one choice between --clear-mtls-ca-pools and --mtls-ca-pools. Its flattened SYNOPSIS must not make the entire group exclusive.

A captured-help generated-validator regression fails on latest main c2ccb29: selecting Cpu,MtlsCaPools returns Exactly one of MtlsCaPools or (...) must be specified. Expected: CPU and CA pool updates can be combined; clearing and replacing CA pools cannot be combined; an empty update is invalid.

I am fixing the generic same-member nonexclusive-choice preservation separately and cancelling generation run 35682446460 before it can publish this known defective output. No replacement PR has been created. Fresh latest-main generation will follow the source fix and its checks/reviews.

[thomhurst]

Source fix: #5343. The SDK regression fails before the fix and all 19 focused generated-validator tests pass after it. The Google replacement now has 76 handwritten nested-choice runtime cases prepared. Generation 35682446460 is confirmed cancelled with no replacement PR published.

[thomhurst]

Source fix #5343 is merged as 6d6ca2e. All 3,380 generator tests, CodeQL, and reviews pass; no pending work remains on the source PR.

Fresh latest-main generation: https://github.com/thomhurst/ModularPipelines/actions/runs/35684123650. This includes #5342's documented optionality/conditional GKE requirements and #5343's nonexclusive update-group preservation. The Google replacement has 76 nested-choice runtime cases prepared. Acceptance remains pending unchanged-artifact review and actual Google integration CI.

[thomhurst]

Fresh latest-main replacement: #5344, generated by run 35684123650 after source fixes through #5343. Artifact 10676728248 is unchanged and passes provenance, coverage, and documentation checks. The replacement contains 76 nested-choice runtime cases plus the earlier regression suites. Actual Google integration CI and reviews are pending; acceptance issues remain open until those pass.

[thomhurst]

Fresh latest-main replacement: #5347, generated by run 35690354313 after source fixes through #5346. Artifact 10678711892 is unchanged and passes provenance, coverage, and documentation checks. Compared with rejected #5344, only eight embedded-credential SecretValue annotations and the fingerprint change; no masking annotation is removed.

The replacement retains 76 nested-choice cases and adds runtime attribute checks for all eight credential fields. Explicit integration CI: https://github.com/thomhurst/ModularPipelines/actions/runs/35692851347. Acceptance remains pending actual Google test execution and reviews.

[thomhurst]

Fresh replacement: #5349, generated by https://github.com/thomhurst/ModularPipelines/actions/runs/35696052122 from main a94af5a6379aa097b0828d9584323787c9fc6449 after source fix #5348.

The unchanged artifact preserves all 7,951 commands, including all 54 reported commands, with no removals or exclusions. Compared with #5347, exactly seven inline-secret annotations are added and eight OAuth/SCIM resource-ID annotations are removed. All 15 embedded credential fields are now marked as secrets. Documentation builds successfully (331 documents).

The generated library compiles. The replacement adapts the four existing handwritten test constructor calls and adds focused Google regressions. Actual Google integration validation is running in https://github.com/thomhurst/ModularPipelines/actions/runs/35698901283. Acceptance remains open until CI and review finish.