GoCodeAlone
diff --git a/‎.github/workflows/cross-plugin-build-test.yml‎
Lines changed: 63 additions & 0 deletions b/‎.github/workflows/cross-plugin-build-test.yml‎
Lines changed: 63 additions & 0 deletions
diff --git a/‎DOCUMENTATION.md‎
Lines changed: 16 additions & 0 deletions b/‎DOCUMENTATION.md‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎docs/adr/009-providerplanner-included-per-user-override.md‎
Lines changed: 24 additions & 0 deletions b/‎docs/adr/009-providerplanner-included-per-user-override.md‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎docs/iac/providerplanner.md‎
Lines changed: 54 additions & 0 deletions b/‎docs/iac/providerplanner.md‎
Lines changed: 54 additions & 0 deletions
diff --git a/‎interfaces/iac_provider.go‎
Lines changed: 14 additions & 0 deletions b/‎interfaces/iac_provider.go‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎interfaces/iac_provider_planner_test.go‎
Lines changed: 35 additions & 0 deletions b/‎interfaces/iac_provider_planner_test.go‎
Lines changed: 35 additions & 0 deletions
@@ -0,0 +1,63 @@
+name: cross-plugin-build-test
+on:
+  pull_request:
+    paths:
+      # rev4 — cycle-3 minor: only run on IaC-touching PRs to save ~5min/docs-PR.
+      # T9.2 quality-review fix: include go.mod/go.sum so transitive dep bumps
+      # (a frequent source of downstream-plugin compile breakage) trigger the gate
+      # even when interfaces/iac/platform/plugin code is untouched.
+      - 'interfaces/**'
+      - 'iac/**'
+      - 'platform/**'
+      - 'plugin/sdk/**'
+      - 'go.mod'
+      - 'go.sum'
+      - '.github/workflows/cross-plugin-build-test.yml'
+
+# T9.2 quality-review fix: cancel older in-flight runs when a PR is updated.
+# Standard CI hygiene; saves CI minutes on rapid push cycles.
+concurrency:
+  group: cross-plugin-build-${{ github.ref }}
+  cancel-in-progress: true
+
+# R2 review: explicit minimal token permissions per CodeQL workflow-permissions
+# scan; this gate only needs to read the workflow + plugin checkouts.
+permissions:
+  contents: read
+
+# R2 review: match the repo-standard Go module env used by ci.yml + codeql.yml so
+# downstream plugin builds resolve github.com/GoCodeAlone/* deps consistently.
+env:
+  GOPRIVATE: github.com/GoCodeAlone/*
+  GONOSUMCHECK: github.com/GoCodeAlone/*
+
+jobs:
+  cross-plugin-build:
+    runs-on: ubuntu-latest
+    strategy:
+      # T9.2 quality-review fix: matches codeql.yml + release.yml precedent.
+      # The whole point of a cross-plugin gate is to surface ALL three plugins'
+      # breakage in a single CI run; default fail-fast: true would cancel the
+      # other two on first failure and force iterative re-runs to debug.
+      fail-fast: false
+      matrix:
+        plugin: [workflow-plugin-aws, workflow-plugin-gcp, workflow-plugin-azure]
+    steps:
+      - uses: actions/checkout@v4
+        with: { path: workflow }
+      - uses: actions/checkout@v4
+        with:
+          repository: GoCodeAlone/${{ matrix.plugin }}
+          path: ${{ matrix.plugin }}
+      - uses: actions/setup-go@v5
+        with: { go-version-file: workflow/go.mod }
+      # The replace directive points the plugin's go.mod at THIS PR's checkout
+      # of workflow (../workflow), NOT at workflow main. The gate exercises
+      # whether the PR's interface changes break AWS/GCP/Azure compilation —
+      # which is precisely the per-PR signal we want.
+      - run: |
+          cd ${{ matrix.plugin }}
+          go mod edit -replace github.com/GoCodeAlone/workflow=../workflow
+          go mod tidy
+          go build ./...
+          # NOTE: not `go test` — those plugins have their own CI; we just verify compile-compat
@@ -1113,6 +1113,22 @@ modules:
 
 ---
 
+### `ProviderPlanner` (IaC plugin interface)
+
+Optional interface in `interfaces/iac_provider.go` for v2 IaC plugins that need custom plan logic instead of core wfctl's default `platform.ComputePlan` + `driver.Diff` dispatch. Reserved as an extension hook for Tofu/Pulumi-style adapter plugins.
+
+```go
+type ProviderPlanner interface {
+    PlanV2(ctx context.Context, desired []ResourceSpec, current []ResourceState) (IaCPlan, error)
+}
+```
+
+Purely additive — plugins that do not implement `ProviderPlanner` remain valid `IaCProvider` implementations. Core wfctl does NOT type-assert against this interface in v0.21.0; future adapter PRs add the type-assertion at the dispatch site alongside their concrete consumer.
+
+See [docs/iac/providerplanner.md](docs/iac/providerplanner.md) for the adapter author guide and [ADR 009](docs/adr/009-providerplanner-included-per-user-override.md) for the ratification provenance.
+
+---
+
 ### `observability.otel`
 
 Initializes an OpenTelemetry distributed tracing provider that exports spans via OTLP/HTTP to a collector. Sets the global OTel tracer provider so all instrumented code in the process is covered.
 
@@ -0,0 +1,24 @@
+# ADR 009: ProviderPlanner Interface Included Per User Override
+
+## Status
+Accepted
+
+## Context
+
+Cycle-3 → cycle-7 adversarial reviews of the implementation plan oscillated between "drop entirely" (YAGNI) and "ship as definition-only" (preserve extension hook); rev6 surfaced the ratification ask to the user via plan § Open Questions.
+
+The user explicitly ratified Option C ("Override — W-9 expands to include the `ProviderPlanner` interface definition") on 2026-05-03 (the workspace owner, direct chat reply). User reasoning paraphrased: the design pass mandate "don't defer any fixes" + "build these fixes the right way" applies to the extension hook as well; the workspace roadmap includes future Tofu/Pulumi adapter work and the cost of shipping the interface now is bounded (~30 min plan revision + ~1 hour implementation).
+
+**Provenance:** Decided by the workspace owner 2026-05-03 via direct chat reply ("option C"). Recorded in plan § Open Questions § "ProviderPlanner deferral".
+
+## Decision
+
+The optional `ProviderPlanner` interface ships as part of W-9's T9.1 task (`interfaces/iac_provider.go`). The interface is purely additive (plugins that don't implement it remain valid `IaCProvider` implementations). Core wfctl's `platform.ComputePlan` + `wfctlhelpers.ApplyPlan` do NOT type-assert against `ProviderPlanner` in v0.21.0 — the type-assertion at the dispatch site is reserved for future adapter PRs (Tofu/Pulumi-style) which will add it alongside their concrete consumer + design discussion.
+
+## Consequences
+
+**Positive:** Extension hook is in the public API surface from v0.21.0; future adapter PRs do not need to make the interface change a separate prerequisite PR. Type-assertion pattern is documented in the interface comment for adapter authors. Cross-plugin-build CI gate (T9.2 here) verifies the interface addition does not break AWS/GCP/Azure compile compatibility.
+
+**Negative:** A speculative interface ships without a concrete in-tree consumer. If the future Tofu/Pulumi adapter design surfaces a different shape (different signature, different doc semantics), this interface will need a backwards-incompatible revision (or a sibling interface like `ProviderPlannerV2`). The user accepted this risk via the ratification.
+
+**Operational notes:** the interface's `PlanV2` signature mirrors `platform.ComputePlan` (ctx + desired + current → IaCPlan, error) so the future adapter can type-assert and call cleanly. No tests beyond T9.1's compile-time type-assertion test ship in this plan series; the first concrete consumer ships its own integration tests.
@@ -0,0 +1,54 @@
+# ProviderPlanner adapter author guide
+
+`ProviderPlanner` is an optional v2 interface declared in [`interfaces/iac_provider.go`](../../interfaces/iac_provider.go). It lets a plugin replace core wfctl's default plan logic (`platform.ComputePlan` + `driver.Diff` dispatch) with its own plan computation — typically because the plugin wraps a foreign engine (Terraform/OpenTofu, Pulumi) that already produces a plan from external state and needs to surface that plan back to wfctl rather than rebuilding it from scratch.
+
+This guide explains what the interface is, when to implement it, how core wfctl handles plugins that do not implement it, and the type-assertion pattern reserved for future adapter PRs at the dispatch site.
+
+## What `ProviderPlanner` is
+
+```go
+type ProviderPlanner interface {
+    PlanV2(ctx context.Context, desired []ResourceSpec, current []ResourceState) (IaCPlan, error)
+}
+```
+
+`PlanV2` mirrors the signature of `platform.ComputePlan` so that an adapter implementation can be invoked at the dispatch site as a drop-in replacement. The signature returns an `IaCPlan` value (not a pointer) — distinct from the existing `IaCProvider.Plan` method which returns `*IaCPlan`. The value-return is intentional: it underlines that `PlanV2` is a pure computation, not a method that retains plan state on the provider.
+
+The interface is **purely additive**. A plugin that does not implement `ProviderPlanner` is still a valid `IaCProvider` and continues to work without changes.
+
+## When to implement
+
+Implement `ProviderPlanner` when your plugin needs custom plan logic that core wfctl's default Diff dispatch cannot express. Typical cases:
+
+- **Tofu/Terraform-style adapters** that derive desired-vs-current state from a `.tfstate` file the plugin manages itself, rather than from wfctl's `[]ResourceState` snapshot.
+- **Pulumi-style adapters** that delegate plan computation to the Pulumi engine and need to translate its preview output into an `IaCPlan` directly.
+- **Composite providers** where a single resource type fans out to multiple sub-resources whose plan ordering must be coordinated across drivers.
+
+If your plugin's resources can be planned independently per driver and the per-driver Diff output is sufficient, do **not** implement `ProviderPlanner` — the default dispatch already does the right thing.
+
+## How core wfctl handles plugins that do not implement it
+
+In v0.21.0, core wfctl's `platform.ComputePlan` (in [`platform/differ.go`](../../platform/differ.go)) dispatches `driver.Diff` directly per resource — it resolves a `ResourceDriver` for each spec via `p.ResourceDriver(spec.Type)`, calls `driver.Diff(ctx, spec, currentOut)` for every modification candidate, and assembles the per-driver output into an `IaCPlan`. (Note: `IaCProvider.Plan`, when implemented, typically delegates back to `platform.ComputePlan` — but `ComputePlan` itself does not call `provider.Plan`.) There is no type-assertion against `ProviderPlanner` at the dispatch site — meaning even a plugin that does implement `ProviderPlanner` will not have its `PlanV2` method invoked by core code in v0.21.0.
+
+The `ProviderPlanner` interface is reserved as a forward-compatible extension hook. Adapter PRs that wish to use it will add the type-assertion at the dispatch site as part of their own design discussion.
+
+## Type-assertion pattern at the dispatch site
+
+The future adapter PR is expected to wire `ProviderPlanner` into `platform.ComputePlan` with a pattern of the following shape:
+
+```go
+// Illustrative pattern for the dispatch site in platform/differ.go's
+// ComputePlan (not yet wired in v0.21.0).
+if planner, ok := provider.(interfaces.ProviderPlanner); ok {
+    return planner.PlanV2(ctx, desired, current)
+}
+// Fall through to the existing per-driver Diff dispatch in ComputePlan.
+```
+
+The pattern is the standard Go optional-interface idiom: type-assert against the optional interface, fall through to the default if the provider does not implement it. The same optional-interface pattern is already used by `ProviderIDValidator` in [`interfaces/iac_resource_driver.go`](../../interfaces/iac_resource_driver.go) — type-assert against the optional interface, fall through to a default if the implementer does not satisfy it.
+
+Adapter authors wiring `PlanV2` into the dispatch site should also note the pointer/value asymmetry: `IaCProvider.Plan` returns `*IaCPlan` while `PlanV2` returns `IaCPlan` by value, so the wrapper at the dispatch site converts as needed (e.g. `p := planner.PlanV2(...); return &p, nil`).
+
+## Provenance
+
+This interface ships per [ADR 009](../adr/009-providerplanner-included-per-user-override.md), which records the user's Option-C ratification on 2026-05-03 of the decision to ship the extension hook in W-9 alongside the cross-plugin build CI gate, rather than deferring it to the first concrete adapter PR.
@@ -49,6 +49,20 @@ type IaCProvider interface {
 	Close() error
 }
 
+// ProviderPlanner is an optional interface for v2 plugins that need custom
+// plan logic (replacing platform.ComputePlan's default driver.Diff dispatch).
+//
+// Reserved as an extension hook for Tofu/Pulumi-style adapter plugins. Core
+// wfctl's platform.ComputePlan + wfctlhelpers.ApplyPlan do NOT type-assert
+// against this interface in v0.21.0 — adapter PRs that wish to use it will
+// add the type-assertion at the dispatch site in their own design discussion.
+//
+// Plugins implementing this interface are accepted by the loader; the
+// implementation is not yet exercised by core code.
+type ProviderPlanner interface {
+	PlanV2(ctx context.Context, desired []ResourceSpec, current []ResourceState) (IaCPlan, error)
+}
+
 // BootstrapResult contains metadata returned by a successful BootstrapStateBackend call.
 type BootstrapResult struct {
 	// Bucket is the name of the created or confirmed state bucket/container.
 
@@ -0,0 +1,35 @@
+package interfaces_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/GoCodeAlone/workflow/interfaces"
+)
+
+// TestProviderPlanner_TypeAssertionCompiles verifies the optional-interface
+// pattern: (1) a type CAN implement ProviderPlanner, and (2) a type that
+// implements IaCProvider is NOT required to implement ProviderPlanner —
+// the additivity claim ADR 009 makes about the v0.21.0 ship is enforced
+// here at the type system level. The negative case reuses the package's
+// existing mockProvider fixture (defined in iac_test.go), which intentionally
+// does not implement PlanV2.
+func TestProviderPlanner_TypeAssertionCompiles(t *testing.T) {
+	// (1) plannerStub implements ProviderPlanner.
+	var _ interfaces.ProviderPlanner = (*plannerStub)(nil)
+
+	// (2) mockProvider implements IaCProvider but NOT ProviderPlanner.
+	// If a future change accidentally moved PlanV2 onto IaCProvider (or
+	// made ProviderPlanner a required embedded interface), this runtime
+	// assertion would fail.
+	var p interfaces.IaCProvider = (*mockProvider)(nil)
+	if _, ok := p.(interfaces.ProviderPlanner); ok {
+		t.Errorf("mockProvider should not satisfy ProviderPlanner; the optional-interface idiom requires the negative case to assert false")
+	}
+}
+
+type plannerStub struct{}
+
+func (p *plannerStub) PlanV2(ctx context.Context, desired []interfaces.ResourceSpec, current []interfaces.ResourceState) (interfaces.IaCPlan, error) {
+	return interfaces.IaCPlan{}, nil
+}