docs(adr): record IaC typed force-cutover decisions (0024 + 0025 + 0026) — Task 14#604
Merged
Conversation
Task 14 of the strict-contracts force-cutover plan (docs/plans/2026-05-10-strict-contracts-force-cutover.md, rev5). Adds three ADRs to decisions/ documenting the architectural trade-offs the cutover commits to: - 0024-iac-typed-force-cutover.md Hard cutover for IaC-flavored interfaces (IaCProvider, ResourceDriver) supersedes the additive 2026-04-26 design for those interfaces only. Module/Step/Trigger work remains live. Rationale: bug-cycle data (T3.9 structpb drop, v0.27.1 EnumeratorAll bridge gap, InvokeService case-string class) and user mandate feedback_force_strict_contracts_no_compat. Records the alternatives rejected: continue additive, compat shim / build-tag dual-path, deferral until Module/Step/Trigger lands. - 0025-iac-optional-method-typed-services-not-bool.md Cycle 3 I-1 split: REQUIRED service (11 RPCs) + 6 OPTIONAL typed services, auto-registered by SDK type-assertion. Absence of the service registration IS the negative signal — no NotSupported flag in any response, no codes.Unimplemented as a "supported by intent" signal. Records the alternatives rejected: Candidate A (NotSupported bool, cycle 1 I-1), Candidate B (codes.Unimplemented, same bug-class shape as v0.27.1 isPluginMethodUnimplemented boundary translator), single service with method-level type-assert. - 0026-iac-direct-grpc-client-no-wrapper.md wfctl uses pb.IaCProviderRequiredClient directly. No hand- written iacProviderClient wrapper layer (cycle 1 Alternative C: removes one of the four bug-class surfaces by removing the layer entirely, not by typing it). Records the narrow engine- side adapter (Task 30) as the bounded exception for platform.ComputePlan / wfctlhelpers.ApplyPlan consumers. No production code changes; documentation only. No rollback required. Verification: spell-checked manually; rendered locally via markdown preview. Each ADR follows the existing decisions/ format (Date, Status, Context, Decision, Consequences, Alternatives Rejected) modeled on decisions/0015–0023.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds three Architecture Decision Records (ADRs) under decisions/ documenting the chosen approach for the IaC typed force-cutover (required/optional typed services split, and wfctl using typed gRPC clients directly).
Changes:
- Add ADR 0024 documenting the hard cutover decision for IaC interfaces (superseding the earlier additive design for IaC only).
- Add ADR 0025 documenting the “required + optional typed services” approach (no
NotSupportedflags / nocodes.Unimplementedsignaling). - Add ADR 0026 documenting wfctl consuming typed
pb.*ClientAPIs directly (no handwritten wrapper layer), with a narrow engine-side adapter exception.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| decisions/0024-iac-typed-force-cutover.md | Records the rationale and scope of the IaC typed hard cutover. |
| decisions/0025-iac-optional-method-typed-services-not-bool.md | Documents optional-capability signaling via service registration rather than flags/status codes. |
| decisions/0026-iac-direct-grpc-client-no-wrapper.md | Documents wfctl’s direct use of typed gRPC clients and why wrapper layers are rejected. |
Comment on lines
+47
to
+48
| plan (`docs/plans/2026-05-10-strict-contracts-force-cutover.md`) | ||
| implements that mandate. |
⏱ Benchmark Results✅ No significant performance regressions detected. benchstat comparison (baseline → PR)
|
- ADR-0025: ResourceDriver "10 RPCs" → "9 RPCs" (count drift; iac.proto ships 9: Create, Read, Update, Delete, Diff, Scale, HealthCheck, SensitiveKeys, Troubleshoot). - ADR-0024: "PR-A" → "PR 2" (manifest naming consistency with the 2026-05-10-strict-contracts-force-cutover.md PR Grouping table).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Task 14 of the strict-contracts force-cutover plan (docs/plans/2026-05-10-strict-contracts-force-cutover.md, rev5).
Adds three ADRs to
decisions/documenting the architectural trade-offs the cutover commits to. Documentation only — no production code changes; no rollback required.ADRs
decisions/0024-iac-typed-force-cutover.md— Hard cutover for IaC-flavored interfaces (IaCProvider, ResourceDriver) supersedes the additive 2026-04-26 design for those interfaces only. Module/Step/Trigger work remains live. Records bug-cycle data (T3.9 structpb drop, v0.27.1 EnumeratorAll bridge gap, InvokeService case-string class) and the alternatives rejected: continue additive, compat shim / build-tag dual-path, deferral.decisions/0025-iac-optional-method-typed-services-not-bool.md— Cycle 3 I-1 split: REQUIRED service (11 RPCs) + 6 OPTIONAL typed services, auto-registered by SDK type-assertion. Absence of registration IS the negative signal — no NotSupported flag, nocodes.Unimplementedas "supported by intent." Records alternatives rejected: NotSupported bool (cycle 1 I-1), codes.Unimplemented (cycle 1 I-1 + v0.27.1 boundary-translator evidence), single service with method-level type-assert.decisions/0026-iac-direct-grpc-client-no-wrapper.md— wfctl usespb.IaCProviderRequiredClientdirectly. No hand-writteniacProviderClientwrapper layer (cycle 1 Alternative C: removes one of the four bug-class surfaces by removing the layer entirely, not by typing it). Records the narrow engine-side adapter (Task 30) as the bounded exception forplatform.ComputePlan/wfctlhelpers.ApplyPlan.Format
Each ADR follows the existing
decisions/format (Date, Status, Context, Decision, Consequences, Alternatives Rejected) modeled ondecisions/0015–0023.Verification
Test plan
🤖 Generated with Claude Code