Operating Workflow Revisions: Verify, Promote, or Roll Back

Active is production; candidate is proposed

Every workflow has one immutable active revision. Production runs and unattended triggers execute that exact revision. Saving from the editor, importing an App, changing an acceptance spec, generating a workflow, restoring history, or accepting a structural repair creates a candidate revision. Those operations do not modify the active graph.

The workflow editor shows both revision identities and their trust state. If a candidate exists, editing continues from that candidate. A stale editor or stale promotion request is rejected instead of overwriting newer work.

The normal release procedure

1. Save the change. Confirm the editor reports a candidate while the previous active revision remains deployed.
2. Run Verify candidate. Verification records static/capability readiness, a dry run, the pinned regression suite, a clean debug execution, and an accomplished outcome against the exact candidate revision and acceptance spec.
3. Review failed or unavailable gates. Correct the candidate or its environment, then verify the resulting new candidate. Evidence from a different graph or spec does not carry forward.
4. When every required gate passes, choose Promote. Promotion uses compare-and-swap against the expected active revision; if production changed meanwhile, refresh and reconcile rather than forcing the write.
5. Confirm the candidate is now active before enabling or updating unattended triggers.

A debug run may execute a selected candidate revision. A production run cannot be pointed at an arbitrary historical or candidate revision; it always resolves the active revision.

Rollback and exceptional promotion

Rollback is also candidate-first: choose a historical revision and restore it, verify the newly-created candidate, then promote it. History is never rewritten and the rollback receives its own audit trail. To discard an experiment, abandon the candidate; the active revision continues unchanged.

An administrative break-glass promotion requires an explicit reason and is audited. It cannot bypass acceptance-spec drift: when the workflow's definition of done changes, a new candidate must capture that spec and be verified against it. Use break-glass only when the operational risk of waiting exceeds the risk documented in the override.

What the workspace learns from execution

Only an accomplished run creates known-good workflow experience. The record is tied to the exact semantic hash and includes execution evidence, so a merely completed, partial, hollow, or failed run cannot teach the workspace that a graph works. After three accomplished runs of the same revision, the proven pattern is promoted from workflow-local context into the owning App's experience. Agent-role patterns that prove themselves across at least two workflows can additionally enter that specialist role's durable mind.

Verified repairs retain their root cause, applicability conditions, proof run, and regression fixture. Rejected or regressed repairs are stored as anti-patterns so agents are warned not to repeat them. When an agent later creates or debugs a workflow, Agentis supplies the most specific applicable evidence first: this workflow, then agent or specialist role, then App and workspace context. Inspect the resulting dossier through the workflow's Experience panel or API.

Operational inspection

Existing workspaces migrate without replacing known-good behavior

On first reconciliation, Agentis uses the newest accomplished run snapshot as the active revision when one exists. If the workflow currently stored in the editor differs, those bytes are retained as a candidate rather than overwriting the accomplished graph. Workflows without accomplished history receive a baseline revision from their current stored graph. Operators should review and verify any migrated candidate before promotion.

Continue