# Convergence States

> For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt).

TraderX uses explicit convergence checkpoints to keep multi-track evolution understandable and maintainable.

## Why Convergence States Exist

*   They mark recommended jump-off points for new work.
*   They keep track progression explicit without forcing multi-parent branch ancestry.
*   They allow transition states to remain focused and incremental.

Publish lineage remains single-parent via `previous`.  
Convergence context is represented separately via `isConvergence`, `convergenceLevel`, and `dottedParents`.

## Current Convergence Levels

### C0

*   `004-containerized-compose-runtime`

### C1

*   `007-observability-lgtm-compose`

### C2

*   `009-order-management-matcher`

### C3

*   `012-platform-convergence-c3`

## Contribution Policy

*   Prefer starting new state design from the nearest suitable convergence state.
*   If you modify a convergence state, update that state’s `system/convergence-rationale.md`.
*   Do not use dotted-line parents for non-convergence states.
*   Keep `previous` single-parent for publish lineage.

## CI + Artifact Publishing Policy

Convergence states from `C0+` must include:

*   container build/publish workflow (`.github/workflows/build-and-publish.yml`)
*   generated run bundle artifacts for consuming GHCR images directly

GHCR image namespaces are convergence-level scoped:

*   `C0`: `ghcr.io/finos/traderx-c0/<component>`
*   `C1`: `ghcr.io/finos/traderx-c1/<component>`
*   `C2`: `ghcr.io/finos/traderx-c2/<component>`
*   `C3`: `ghcr.io/finos/traderx-c3/<component>`

Use immutable commit-SHA tags plus a moving `latest` tag per namespace/component.

Reference: `/docs/spec-kit/generated-state-ci`

Convergence level alone does not force a deployment profile. Deployment-bundle profile selection follows runtime substrate:

*   Compose runtime states -> `aws-ec2-compose`
*   Kubernetes runtime states -> `aws-ec2-k8s` (planned; enable only after generator support lands)

## Canonical Sources

*   State metadata: `catalog/state-catalog.json`
*   Convergence governance ADR: `/docs/adr/008-convergence-state-model`
*   Visual graph: `/docs/learning-paths`