Add an Ops role for verified GitOps deployment handoff

coilyco-ops commented

2026-07-31 07:57:06 +00:00

Member

Goal

Extend the Ward delivery lifecycle through deployment without making the Director responsible for releases or teaching Ward anything about Kubernetes. Build the Ops workflow on the generic composed-agent dispatch and messaging delivered by #1626.

The desired lifecycle is:

repo ticket
  -> Engineer implements
  -> QA validates
  -> Director accepts / merges
  -> Ops deploys and verifies
  -> verified deploy-state commit

Program graph

#1626 provides generic composed-agent dispatch and messaging. It is a prerequisite, not an Ops implementation.
#1627 defines the Ops release-candidate and outcome contract. It is blocked by #1626.
#1628 enforces verified deploy-state transitions per environment. It is blocked by #1626 and #1627.
#1629 proves the complete path in a disposable end-to-end fixture. It is blocked by #1626, #1627, and #1628.

This parent remains open until the three Ops children land and their evidence is reconciled here.

Role boundaries

Director

Speaks in tickets within a single repository.
Coordinates multiple repo-scoped tickets.
Hands an accepted application revision to Ops.
Does not deploy.

Engineer and QA

Speak in one repository ticket at a time.
Produce and validate the application change.

Ops

Owns the release workflow, whose unit of work is not necessarily a ticket.
Accepts a release candidate consisting of an application revision, target environment, and provenance.
May encounter deployment problems unrelated to the originating code change.
Reports whether the release became live, was rejected by the change, or remains blocked externally.
Uses application-provided deployment and verification surfaces; Ward must not understand Kubernetes, Argo, Flux, or any other deployment implementation.

Deployment-state model

Use the deploy-repository commit as the entire durable deployment state.

Ward already provides the durable observable execution trace: commands, observations, retries, failures, and reasoning. The deploy commit records only the verified resulting environment state.

Ward execution -> what happened
Deploy commit  -> what successfully became true

The GitOps variant for this workflow is:

Change the deploy repository locally.
Apply the candidate deployment.
Verify the resulting environment.
Push the deploy-repository commit only after verification succeeds.

The resulting commit means:

This environment was verified running this immutable application revision.

Failed or externally blocked attempts produce no deploy-state commit; their durable history remains in the Ward execution trace.

Required invariant

The deploy-repository environment revision always describes the last known verified state, and Ops never finishes while the actual environment knowingly differs from it.

This requires the Ops workflow to handle:

Deploy succeeded, push failed: retry the push or restore and verify the previously committed state.
Concurrent deployments: serialize per environment or use compare-and-swap against the deploy-repository revision observed at the start.
Partial deployment failure: restore and verify the previous committed state before finishing.
Out-of-band drift: detect or prevent changes that would make the repository cease to be authoritative.
Artifact identity: record immutable deployable identity, such as an image digest, rather than only a mutable tag.

Rollback is another verified deploy-state commit.

Ward scope

Ward should provide only the orchestration needed to:

consume the generic composed-agent dispatch from #1626 for an ops role;
hand it an accepted release candidate;
preserve its observable execution trace;
allow it to return a classified outcome and the verified deploy commit;
make the end-to-end demo finish with the feature live.

Ward should not add:

Kubernetes-specific knowledge;
a deployment DSL;
environment-management abstractions;
rollout or rollback implementations;
a parallel deployment-state object that must be synchronized with Git.

Acceptance criteria

A Director can hand an accepted application revision to an Ops role without deploying it directly.
Ops can invoke repo/application-provided deploy and verification operations.
The full Ops attempt is visible in the normal Ward execution artifacts.
A successful run creates and pushes a verified deploy-repository commit.
A failed or externally blocked run leaves no new deploy-state commit.
Ops cannot finish with a known mismatch between the environment and the deploy repository.
Concurrent deployment behavior is deterministic and protected per environment.
Ward contains no Kubernetes-specific deployment logic.
The demo can proceed from issue through implementation, QA, merge, deployment, verification, and observable live feature without manual intervention.

Blocked by

#1626

## Goal Extend the Ward delivery lifecycle through deployment without making the Director responsible for releases or teaching Ward anything about Kubernetes. Build the Ops workflow on the generic composed-agent dispatch and messaging delivered by #1626. The desired lifecycle is: ```text repo ticket -> Engineer implements -> QA validates -> Director accepts / merges -> Ops deploys and verifies -> verified deploy-state commit ``` ## Program graph * #1626 provides generic composed-agent dispatch and messaging. It is a prerequisite, not an Ops implementation. * #1627 defines the Ops release-candidate and outcome contract. It is blocked by #1626. * #1628 enforces verified deploy-state transitions per environment. It is blocked by #1626 and #1627. * #1629 proves the complete path in a disposable end-to-end fixture. It is blocked by #1626, #1627, and #1628. This parent remains open until the three Ops children land and their evidence is reconciled here. ## Role boundaries ### Director - Speaks in tickets within a single repository. - Coordinates multiple repo-scoped tickets. - Hands an accepted application revision to Ops. - Does **not** deploy. ### Engineer and QA - Speak in one repository ticket at a time. - Produce and validate the application change. ### Ops - Owns the release workflow, whose unit of work is not necessarily a ticket. - Accepts a release candidate consisting of an application revision, target environment, and provenance. - May encounter deployment problems unrelated to the originating code change. - Reports whether the release became live, was rejected by the change, or remains blocked externally. - Uses application-provided deployment and verification surfaces; Ward must not understand Kubernetes, Argo, Flux, or any other deployment implementation. ## Deployment-state model Use the deploy-repository commit as the entire durable deployment state. Ward already provides the durable observable execution trace: commands, observations, retries, failures, and reasoning. The deploy commit records only the verified resulting environment state. ```text Ward execution -> what happened Deploy commit -> what successfully became true ``` The GitOps variant for this workflow is: 1. Change the deploy repository locally. 2. Apply the candidate deployment. 3. Verify the resulting environment. 4. Push the deploy-repository commit only after verification succeeds. The resulting commit means: > This environment was verified running this immutable application revision. Failed or externally blocked attempts produce no deploy-state commit; their durable history remains in the Ward execution trace. ## Required invariant > The deploy-repository environment revision always describes the last known verified state, and Ops never finishes while the actual environment knowingly differs from it. This requires the Ops workflow to handle: - **Deploy succeeded, push failed:** retry the push or restore and verify the previously committed state. - **Concurrent deployments:** serialize per environment or use compare-and-swap against the deploy-repository revision observed at the start. - **Partial deployment failure:** restore and verify the previous committed state before finishing. - **Out-of-band drift:** detect or prevent changes that would make the repository cease to be authoritative. - **Artifact identity:** record immutable deployable identity, such as an image digest, rather than only a mutable tag. Rollback is another verified deploy-state commit. ## Suggested commit contents The deploy repository should identify enough state to recognize or reconstruct the deployment, for example: ```yaml application_revision: sha256:... environment: production ward_execution: ward-run-123 originating_ticket: eco-app#482 verified_at: 2026-07-31T07:00:00Z ``` The ticket and Ward execution are provenance. They are not Ops' unit of work or a second deployment-state database. ## Ward scope Ward should provide only the orchestration needed to: - consume the generic composed-agent dispatch from #1626 for an `ops` role; - hand it an accepted release candidate; - preserve its observable execution trace; - allow it to return a classified outcome and the verified deploy commit; - make the end-to-end demo finish with the feature live. Ward should **not** add: - Kubernetes-specific knowledge; - a deployment DSL; - environment-management abstractions; - rollout or rollback implementations; - a parallel deployment-state object that must be synchronized with Git. ## Acceptance criteria - [ ] A Director can hand an accepted application revision to an Ops role without deploying it directly. - [ ] Ops can invoke repo/application-provided deploy and verification operations. - [ ] The full Ops attempt is visible in the normal Ward execution artifacts. - [ ] A successful run creates and pushes a verified deploy-repository commit. - [ ] A failed or externally blocked run leaves no new deploy-state commit. - [ ] Ops cannot finish with a known mismatch between the environment and the deploy repository. - [ ] Concurrent deployment behavior is deterministic and protected per environment. - [ ] Ward contains no Kubernetes-specific deployment logic. - [ ] The demo can proceed from issue through implementation, QA, merge, deployment, verification, and observable live feature without manual intervention. ## Blocked by * #1626

coilyco-ops referenced this issue

2026-07-31 08:12:49 +00:00

Spec dynamic downstream roles from roles.kdl without hardcoding them into this release #1328

coilyco-ops referenced this issue

2026-07-31 08:14:25 +00:00

Add a warded ops role for bounded live operations #817

coilyco-ops referenced this issue

2026-07-31 08:20:38 +00:00

Define the Ops release-candidate and outcome contract #1627

coilyco-ops referenced this issue

2026-07-31 08:21:28 +00:00

Enforce verified deploy-state transitions per environment #1628

coilyco-ops referenced this issue

2026-07-31 08:21:36 +00:00

Prove issue-to-verified-deployment in a disposable fixture #1629

coilyco-ops referenced this issue

2026-07-31 08:21:55 +00:00

Generalize the dispatch broker for arbitrary composed agents #1626

coilyco-ops added the

labels

2026-07-31 08:25:51 +00:00

coilyco-ops commented

2026-07-31 08:29:07 +00:00

Author

Member

Closing the non-executable program umbrella. Its headless implementation path is now explicit: #1626 supplies generic dispatch, #1627 defines the Ops contract, #1628 implements verified state transitions, and #1629 proves the complete disposable workflow. Those children retain all acceptance owned here.

coilyco-ops commented

2026-07-31 08:35:24 +00:00

Author

Member

Correction: reopened and restored to its prior triage state. The earlier closure was premature because Kai asked to review consult and interactive issues together before changing their disposition.

coilyco-ops commented

2026-07-31 09:02:20 +00:00

Author

Member

Closing as decomposed during the Ward v1 seal. #1626 owns generic composed-agent dispatch, #1627 owns the Ops handoff contract, #1628 owns verified deploy-state transitions, and #1629 owns the disposable end-to-end proof. Those headless children retain the complete executable program.

coilyco-ops closed this issue

2026-07-31 09:02:27 +00:00

Rows
Columns

Add an Ops role for verified GitOps deployment handoff #1625

Goal

Program graph

Role boundaries

Director

Engineer and QA

Ops

Deployment-state model

Required invariant

Suggested commit contents

Ward scope

Acceptance criteria

Blocked by