docs(plans): supersede 2026-04-26 strict-contracts design for IaC scope#596
Merged
Conversation
…ider+ResourceDriver scope
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates strict-contracts documentation plans to record a partial supersession for the IaC-related migration items, while keeping the Module/Step/Trigger tracker entries active.
Changes:
- Add a standalone supersession notice document for the 2026-04-26 strict-contracts plan (IaC scope).
- Update the 2026-04-26 strict-contracts design frontmatter to indicate partial supersession and point at the newer force-cutover design.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/plans/2026-04-26-strict-grpc-plugin-contracts.SUPERSEDED-NOTICE.md | Adds a separate supersession notice pointing readers to the force-cutover plan/design. |
| docs/plans/2026-04-26-strict-grpc-plugin-contracts-design.md | Updates plan metadata to mark IaC scope as superseded (partial). |
Comment on lines
+2
to
+5
| status: in_progress | ||
| superseded_by: docs/plans/2026-05-10-strict-contracts-force-cutover-design.md | ||
| supersession_scope: IaCProvider, ResourceDriver (Module/Step/Trigger work remains live) | ||
| status: superseded_partial |
Comment on lines
+6
to
+9
| The IaCProvider + ResourceDriver migration tracker entries in `2026-04-26-strict-grpc-plugin-contracts.md` are SUPERSEDED by the 2026-05-10 force-cutover plan: | ||
| - Design: `docs/plans/2026-05-10-strict-contracts-force-cutover-design.md` | ||
| - Plan: `docs/plans/2026-05-10-strict-contracts-force-cutover.md` | ||
|
|
⏱ Benchmark Results✅ No significant performance regressions detected. benchstat comparison (baseline → PR)
|
…facts - Replace duplicate-key supersession on 2026-04-26 design+plan: status superseded_partial -> superseded (valid in audit), populate superseded_by list (no longer empty array, cite cutover design+plan), drop top-level duplicates. - Apply same supersession-status pattern to docs/plans/2026-04-26-strict-grpc-plugin-contracts.md (per team-lead authorization for the lead-owned plan file). - SUPERSEDED-NOTICE.md frontmatter: switch to audit-valid values (status: superseded, area: plugins, owner: jon). - Import canonical 2026-05-10 cutover design + plan + scope-lock + 8 adversarial-review files from design/strict-contracts-force-cutover @ e82b7e0c so SUPERSEDED-NOTICE cross-refs resolve. - Imported design.md frontmatter normalized: status draft -> approved, area plugins/iac -> plugins, supersedes string -> []string list, supersession_scope split out. - 8 adversarial-review files: status: complete -> status: approved (audit-valid). Local audit: zero ERROR. Three WARN remain (missing_frontmatter): two pre-existing on main (2026-05-09 sensitive-output-routing pair) + one on the scope-locked 2026-05-10 cutover plan file (cannot edit per scope-lock invariant).
Bonus normalization beyond Task 1's literal Files section, per team-lead's follow-up rulings on PR 596: - Add YAML frontmatter (status: approved / area: ecosystem / owner: jon / supersedes: [2026-04-26 plan]) to docs/plans/2026-05-10-strict-contracts-force-cutover.md. Per team-lead ruling #1: scope-lock hash covers ONLY the ## Scope Manifest section; prepending frontmatter above the H1 is safe + clears the audit missing_frontmatter WARN. - Extend ADR 0027 with a "Scope: bonus normalizations" section documenting the adversarial-review status complete→approved + cutover-design status draft→approved + 2026-04-26 files using supersession_scope custom field. Treated as fix-forward; manifest unchanged. Local audit (wfctl audit plans): 0 ERROR, 0 WARN on changed files. Two WARN remain on 2026-05-09-engine-sensitive-output-routing*.md files — pre-existing on main, out of scope for PR 596.
Comment on lines
+11
to
+13
|
|
||
| **Goal:** Replace string-method dispatch (`InvokeService("IaCProvider.X", map[string]any)`) with typed proto-generated gRPC services for the **external-plugin gRPC bridge** (workflow ↔ DO plugin), eliminating two specific bug classes (missing client bridge, missing server dispatcher) by making them compile-time errors. | ||
|
|
Comment on lines
+83
to
+88
| **Change class:** Documentation. Verification: spell-check + render preview; no runtime impact, no rollback note required. | ||
|
|
||
| **Step 1: Update design frontmatter** | ||
|
|
||
| Edit the YAML frontmatter at top of `docs/plans/2026-04-26-strict-grpc-plugin-contracts-design.md`: | ||
|
|
Comment on lines
+75
to
+81
| ### Task 1: Add supersession-notice doc + update design frontmatter | ||
|
|
||
| **Per plan-phase cycle 1 I-3:** the 2026-04-26 implementation PLAN is scope-lock-protected (per memory `feedback_plan_files_lead_owned`); editing its frontmatter mid-flight may be blocked. Compromise: edit only the DESIGN doc's frontmatter (designs are not scope-locked the same way; status is informational); for the implementation PLAN, add a NEW supersession-notice file in the same dir. | ||
|
|
||
| **Files:** | ||
| - Modify: `docs/plans/2026-04-26-strict-grpc-plugin-contracts-design.md` (frontmatter only — design docs are not scope-lock-protected) | ||
| - Create: `docs/plans/2026-04-26-strict-grpc-plugin-contracts.SUPERSEDED-NOTICE.md` (NEW supersession pointer; doesn't modify the locked plan file) |
| @@ -1,5 +1,6 @@ | |||
| --- | |||
| status: in_progress | |||
| status: superseded | |||
| @@ -1,5 +1,6 @@ | |||
| --- | |||
| status: in_progress | |||
| status: superseded | |||
|
|
||
| The Module/Step/Trigger migration tracker entries (workflow-plugin-{audit, sso, ws-auth, authz, security, etc.}) in the 2026-04-26 plan REMAIN LIVE — they're not superseded. | ||
|
|
||
| This notice exists as a separate file because the 2026-04-26 plan itself is scope-lock-protected per `feedback_plan_files_lead_owned` and cannot be edited in-place. |
Comment on lines
+7
to
+12
| ## Context | ||
|
|
||
| Plan §Task 1 step 1 instructed prepending `status: superseded_partial` and `superseded_by: [...]` to two existing plan-doc frontmatter blocks (`2026-04-26-strict-grpc-plugin-contracts-design.md` and `…contracts.md`). The instruction did not account for these files already containing `status:` and `superseded_by:` keys at other lines (line 1 + line 57 respectively). | ||
|
|
||
| Faithful execution of the plan introduced YAML duplicate keys, which `wfctl audit plans` (gopkg.in/yaml.v3 in `cmd/wfctl/plan_audit.go`) rejects with `mapping key already defined at line N` errors. Code-reviewer + Copilot independently flagged this on PR #596. | ||
|
|
Comment on lines
+1
to
+6
| --- | ||
| status: approved | ||
| area: ecosystem | ||
| owner: jon | ||
| supersedes: [docs/plans/2026-04-26-strict-grpc-plugin-contracts.md] | ||
| --- |
Comment on lines
60
to
+65
| - GOWORK=off go run ./cmd/wfctl audit plans --dir docs/plans --fix-index | ||
| result: partial | ||
| supersedes: [] | ||
| superseded_by: [] | ||
| superseded_by: | ||
| - docs/plans/2026-05-10-strict-contracts-force-cutover-design.md | ||
| - docs/plans/2026-05-10-strict-contracts-force-cutover.md |
- ADR 0027 (MINOR-E): drop literal `superseded_partial` from the technical Context paragraph; it now only appears in the alternatives-rejected / bonus-normalizations sections. - SUPERSEDED-NOTICE.md (MINOR-F): rephrase the closing paragraph to distinguish scope-locked plan BODY (immutable) vs frontmatter (lead-gated, may be edited for status/supersession bookkeeping). Avoids the prior "cannot be edited in-place" claim that this PR's frontmatter edits contradicted.
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
PR 1 / Task 1: doc housekeeping for the strict-contracts force-cutover. Marks the prior 2026-04-26 strict-grpc-plugin-contracts design+plan as superseded for the IaC scope, lands the new 2026-05-10-strict-contracts-force-cutover design+plan + 8 adversarial review files + scope-lock sidecar, adds SUPERSEDED-NOTICE pointer, files ADR-0027 documenting frontmatter-replace technique + scope expansion.
Changes (15 files)
Verification
wfctl audit plansreturns 0 ERROR + 2 WARN (both pre-existing, not touched by this PR)Plan-correction notes
See ADR-0027 for the replace-vs-append technique deviation from §Task 1 step 1's literal "add" instruction (which would create yaml.v3 duplicate-key errors). Manifest-section SHA unchanged; no scope-lock unlock required.
🤖 Generated with Claude Code