fix(declarative): enforce saved plan execution modes

[floze-the-genius]

Summary

• enforce strict saved-plan ownership for declarative execution commands:
  • apply --plan accepts only apply-mode plans
  • sync --plan accepts only sync-mode plans
  • delete --plan accepts only delete-mode plans
• keep diff --plan mode-neutral
• identify the plan source, actual mode, required mode, regeneration command, and safe execution command in mismatch errors
• retain defensive action validation for editable plan artifacts:
  • apply accepts CREATE, UPDATE, and EXTERNAL_TOOL
  • sync accepts CREATE, UPDATE, DELETE, and EXTERNAL_TOOL
  • delete accepts only DELETE
• correct delete help that routed delete-mode plans through sync
• make saved-plan examples generate the mode required by their execution command
• add unit, integration, root-command, and E2E coverage for the mode and action invariants

Testing

• go fix ./...
• changed Go files formatted with gofumpt and golines -m 120
• make build
• make build-ci
• make lint
• make test
• make test-integration
• KONGCTL_E2E_SCENARIO=declarative/plan-mode-validation go test -tags=e2e ./test/e2e -run '^Test_Scenarios$' -count=1 -v

Closes #1653

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[github-actions]

Trusted E2E passed for reviewed fork SHA.

• PR: fix(declarative): enforce saved plan execution modes #1655
• Reviewed SHA: 2b4a97e6bfb9a370b346b8248822ef60083b3cb9
• Trusted run: https://github.com/Kong/kongctl/actions/runs/30009134373
• Status: success
• Description: Trusted E2E passed for reviewed fork SHA.

This trusted E2E result applies only to the exact reviewed SHA above. Re-run trusted E2E if the contributor pushes another commit.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6731cc4955

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: abf46a99eb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[rspurgeon]

@floze-the-genius please see #1655 (comment)

thank you for your contribution

[floze-the-genius]

Thanks for the reminder. I have now signed the CLA, and the license/cla status is passing on the current head SHA.

[rspurgeon]

Thank you @floze-the-genius . I wanted to point to some expanded information in the original issue on this
#1653 (comment)
I want to expand the behavior such that we are stricter on validating modes when apply|sync|delete commands are ran. My goal for this change is to ensure we cover all those cases as well as update documentation a bit to provide the necessary clarity (if needed).

Please let me know if you'd like to expand your PR to cover that additional requirement, otherwise I can take it from you and continue.

Thanks again

[floze-the-genius]

Thanks for the clarification. I expanded the PR to cover the full command/mode contract from #1653 and rebased it onto the latest main.

The updated implementation now:

• enforces apply/apply, sync/sync, and delete/delete saved-plan ownership;
• keeps diff --plan mode-neutral;
• preserves command-specific action invariants for editable plan artifacts;
• reports the plan source, actual mode, required mode, and the correct regeneration or safe execution workflow;
• fixes the obsolete delete-to-sync help path and aligns saved-plan examples;
• adds unit, integration, root-command, and E2E mismatch coverage.

The full race-enabled unit and integration suites, lint, CGO-disabled build, and the focused E2E scenario all pass on the rebased head.

[rspurgeon]

I pushed a small follow-up that only copy-edits the plan-mode validation errors. Suggested commands now appear on their own lines with a mock terminal prompt, and the guidance names the applicable command. There are no behavioral changes.

[floze-the-genius]

The trusted E2E payload itself passed: the build, harness, and all five acceptance shards completed successfully. The red E2E Required status comes from the final shard-verification job, where actions/download-artifact found all six artifacts but then failed while fetching a signed artifact URL with 404 Not Found: workflow run not found.

This appears to be a transient artifact-service/verifier failure rather than a test failure on 2b4a97e6. Could you rerun the trusted E2E workflow when convenient?