Cutover Graph

A deterministic cutover control room for dependencies, live readiness, timing, checkpoints, contingency, risk and verified evidence.

Cutover Graph models a cutover as versionable state rather than a status spreadsheet. It can answer both planning and live-execution questions, preserve trusted snapshots, reject illegal state transitions, and hold execution when required evidence cannot be verified.

The operating question

During a cutover, the useful question is not just “what is green?” It is:

What can run now, what is blocking go-live, which task caused the delay, what changed since the last trusted state, where is operational risk concentrated, and—if forward execution must stop—which contingency is actually justified?

The control-room layer consolidates those signals into JSON, Markdown or standalone HTML without hiding the deterministic evidence underneath.

Public reference

The project page explains the operating model. Its generated control-room case is built from the repository's synthetic before/after snapshots on every documentation deployment. The same report is available as JSON for machine consumers and Markdown for review.

The case is demonstration data, not evidence from a production cutover. The Pages workflow regenerates it through the same deterministic modules exercised by CI, so the public output cannot drift into a hand-maintained mock-up.

Try it

Requires Python 3.10+.

python -m pip install .

cutover-graph validate examples/customer-cutover.json
cutover-graph plan examples/customer-cutover.json

Render the control room:

cutover-graph control-room examples/timed-cutover-after.json \
  --observed-at 2026-08-30T22:30:00Z \
  --readiness-policy examples/readiness-policy.json \
  --json-output build/control-room.json \
  --markdown build/control-room.md \
  --html build/control-room.html

The installed command is a thin dispatcher over the same deterministic modules used by CI. Existing python control_room.py ... and other module-level workflows remain supported.

Trusted state transition

With a previous trusted snapshot, the same control room validates whether the observed state transition is legal:

cutover-graph control-room examples/timed-cutover-after.json \
  --previous-snapshot build/previous-snapshot.json \
  --transition-policy examples/transition-policy.json \
  --observed-at 2026-08-30T22:30:00Z \
  --html build/control-room.html

The report derives one explicit operational mode:

planned_execution
readiness_hold
contingency_active
complete
invalid_state

invalid_state is fail-loud: an invalid plan, illegal snapshot transition, invalid timing state, or invalid contingency state cannot be presented as a normal operating view.

Verified external evidence

A checkpoint may point to evidence owned by another product instead of copying that evidence into the cutover plan. The first implemented binding is Reconciliation as Code.

Build a local verification registry from retained reconciliation evidence, then render a verified control room:

cutover-graph evidence build build/evidence-registry.json \
  path/to/reconciliation-evidence.json

cutover-graph control-room-verified examples/checkpoint-cutover.json \
  --evidence-registry build/evidence-registry.json \
  --observed-at 2026-08-30T22:30:00Z \
  --html build/verified-control-room.html

External evidence is addressed through stable eac:// references. A task is not treated as verified-complete when its required external evidence is missing, conflicting, or has failed. The registry retains evidence-document SHA-256 fingerprints and does not silently copy another product's semantic ownership into Cutover Graph.

Current capabilities

Planning and execution

• validate tasks and dependencies;
• detect missing dependencies and cycles;
• calculate deterministic execution waves and duration-based critical path;
• identify tasks executable now from dependency and checkpoint state;
• detect active blockers and checkpoint-aware completion;
• model approvals and evidence as explicit checkpoints;
• enforce readiness/go-no-go policies and owner/evidence requirements.

Trusted live state

• create immutable execution snapshots with deterministic snapshot IDs and plan fingerprints;
• validate parentage, timestamps and legal task-state transitions;
• protect against checkpoint regression and illegal state rollback;
• compare trusted snapshots without relying on manually maintained status summaries.

Timing and risk

• calculate timezone-aware baseline and live forecast from ISO-8601 timestamps;
• propagate delay through dependencies and separate originating from inherited delay;
• forecast completion and schedule variance;
• score open task risk using explicit policy;
• expose owner/workstream risk concentration, critical-path exposure and missing-risk buckets.

Contingency

• model rollback/contingency as explicit alternative execution branches;
• activate a branch only from explicit task-state or signal conditions;
• validate contingency dependencies/cycles separately from the forward plan;
• calculate branch-specific blockers, waves and executable_now.

Evidence and control-room output

• produce consolidated JSON, Markdown and standalone HTML control-room reports;
• combine execution, transition validity, timing, readiness, contingency and risk in one read-only decision surface;
• preserve stable eac:// artifact references;
• bind Reconciliation-as-Code run evidence through a verified registry;
• retain source-document SHA-256 and external result status before accepting evidence;
• expose machine-readable output suitable for CI, dashboards and agents;
• install one cutover-graph command while retaining deterministic module boundaries.

Command surface

cutover-graph validate
cutover-graph plan
cutover-graph control-room
cutover-graph control-room-verified
cutover-graph gate
cutover-graph timing
cutover-graph diff
cutover-graph contingency
cutover-graph snapshot
cutover-graph risk
cutover-graph artifacts
cutover-graph evidence

For module-level development and debugging the original scripts remain available. CI exercises both the installed command and those backwards-compatible paths.

Checkpoint model

A checkpoint belongs to a task and can require approvals and evidence before the task is considered complete for dependency purposes.

{
  "id": "reconcile-customers",
  "status": "done",
  "depends_on": ["load-customers"],
  "checkpoint": {
    "required_approvals": ["business", "data"],
    "approvals": [
      {"role": "business", "by": "business-owner"},
      {"role": "data", "by": "data-lead"}
    ],
    "required_evidence": ["reconciliation"],
    "evidence": [
      {
        "type": "reconciliation",
        "ref": "eac://dkharlanau/reconciliation-as-code/reconciliation/customer-final/run/RUN-001"
      }
    ]
  }
}

A raw done status does not release downstream work when a required checkpoint is incomplete or its external evidence cannot be verified.

Handoff to project assurance

Cutover Graph exports the state it owns as a stable artifact index. Project Evidence Graph can import that index without parsing the cutover plan or copying its semantics:

cutover-graph evidence build build/evidence-registry.json \
  examples/external-evidence/passed-reconciliation.json

cutover-graph artifacts examples/checkpoint-cutover.json \
  --registry build/evidence-registry.json \
  --output build/cutover-artifacts.json

project-evidence-graph import-cutover build/cutover-artifacts.json \
  --output build/project-cutover-fragment.json

project-evidence-graph analyze build/project-cutover-fragment.json

The boundary is fail-closed. An external checkpoint becomes positive downstream evidence only when the supplied registry verifies the referenced producer result. The same checkpoint exported without a registry remains traceable, but Project Evidence Graph imports it as an assurance gap rather than proof. See the artifact-index handoff contract.

Contingency model

Rollback is an explicit alternative branch, not prose attached to a task:

{
  "signals": {"abort_go_live": false},
  "tasks": [
    {"id": "load-customers", "status": "failed"}
  ],
  "contingencies": [
    {
      "id": "rollback-customer-load",
      "mode": "any",
      "activate_when": [
        {"task": "load-customers", "status_in": ["failed"]},
        {"signal": "abort_go_live", "equals": true}
      ],
      "tasks": [
        {"id": "close-inbound", "status": "done", "depends_on": []},
        {"id": "restore-snapshot", "status": "pending", "depends_on": ["close-inbound"]},
        {"id": "reconcile-restored-state", "status": "pending", "depends_on": ["restore-snapshot"]}
      ]
    }
  ]
}

A contingency is inactive until its activation rule passes. When active, its branch is evaluated as a separate deterministic DAG with its own executable tasks and blockers.

Design boundaries

Cutover Graph owns cutover execution state: tasks, dependencies, timing, checkpoints, contingencies, trusted snapshots and readiness decisions.

It does not become the semantic owner of the evidence it consumes. Reconciliation controls stay in Reconciliation as Code; project-wide assurance relationships can be projected into Project Evidence Graph. Stable references are preferred to copying the same business fact into several repositories.

Next product steps

• provide one complete synthetic rehearsal pack from baseline snapshot through verified control-room decision;
• add a stable machine-readable consumer contract for current control-room state;
• add controlled command hooks only behind explicit approval envelopes;
• add ticketing/monitoring status adapters only when their authority and freshness are explicit;
• add signed/attested snapshot and evidence-pack manifests where audit requirements justify them.

Design principles

• deterministic planning before automation
• explicit policy rather than hidden go/no-go logic
• rollback as an explicit alternative branch
• checkpoint-aware completion
• timezone-aware schedule math
• trusted, versionable state
• evidence-backed completion
• portable machine-readable output
• vendor-neutral core
• synthetic examples safe to publish

Related projects

• Reconciliation as Code owns executable reconciliation checks and run evidence that can satisfy an external cutover checkpoint.
• Project Evidence Graph consumes the Cutover artifact index and preserves verified checkpoints or unresolved assurance gaps in project-wide traceability.
• Transformation Graph provides broader project traceability context; there is currently no direct Transformation Graph import in Cutover Graph.
• Enterprise Change Graph owns change-focused impact and regression analysis; Cutover Graph does not infer its propagation rules.
• Mapping as Code, Interface as Code, and Process as Code remain the authoring homes for their domain contracts rather than inputs copied into the cutover model.

Portfolio map: https://dkharlanau.github.io/products/

Status

Executable MVP / active development. The installed CLI, control room, checkpoint-aware execution, trusted snapshots and transition validation, live timing, risk concentration, readiness policies, explicit contingencies, verified Reconciliation-as-Code evidence bindings, fail-closed Project Evidence handoff, generated public reference case, examples, tests and CI are implemented. The main remaining gaps are a stable current-state consumer contract and a full end-to-end rehearsal pack, not distribution or the deterministic execution core.

About the author

Created and maintained by Dzmitryi Kharlanau, an SAP consultant and system analyst working across enterprise architecture, data, integration, operations, and practical AI.

• Website and knowledge base
• LinkedIn