# Nova Migration Guide — What Consumers Must Know

> **STATUS: COMPLETE (milestone v1.15.4, 2026-07-30).** The Nova rebrand
> is fully rolled out. The dual-read / parallel-write grace period has
> ended (P5 cutoff passed). All `ACDL_*` env var fallbacks, `.acdl/`
> consumer-path fallbacks, `/acdl/` SSM-path fallbacks, `acdl:*` tag-key
> fallbacks, and `acdl-*` AWS resource names are removed. Consumers must
> use the `NOVA_*` / `.nova/` / `/nova/` / `nova:*` / `nova-*` names
> exclusively. If you have not yet migrated, follow the steps below.

> **Nova** is the new product brand for the platform formerly known as
> **ACDL** (Agentic Cloud Delivery Platform). This guide documents the
> breaking changes from the rebrand rollout (Phases P2–P4, cutoff P5)
> and tells you exactly what to do.

## What is NOT changing

- **The Gitea repository name** (`continuous-intelligence/acdl`) is **not**
  changing. Only the product brand is changing. The `uses:` reference
  (`acdl/.github/workflows/deploy.yml@vX.Y`) and the GitHub `acdl/acdl` repo
  path are unchanged for the duration of the rebrand; the workflow
  `uses:` reference will be migrated in a later, separately-announced step.
- **The platform behavior** is unchanged. Same pipeline stages, same
  contract schema, same confidence model, same evidence stream, same
  modules. Only the brand, the on-disk path, the env var names, the SSM
  path, the AWS tag keys, and the AWS resource names are changing.

## The 5 breaking changes

Five things that consumers may reference are being renamed. Each is
scheduled into a phase, ships with a grace period, and has a cutoff.

### 1. Consumer contract path — Phase P2

- **Old:** `.acdl/contract.yml`
- **New:** `.nova/contract.yml`
- **Phase:** P2 (env vars + consumer path)
- **Grace period:** during P2–P4 the deploy workflow reads **both** paths
  (`.nova/contract.yml` first, falling back to `.acdl/contract.yml` if the
  new path is absent). Your existing contracts keep working until P5.
- **Cutoff:** P5 removes the `.acdl/` fallback. Move your contract file
  before P5.
- **What you must do:** rename the directory in your consumer repo from
  `.acdl/` to `.nova/` and update any `contract:` workflow input that
  points at the old path. Nothing else changes in the contract content.

### 2. Environment variables — Phase P2

- **Old:** `ACDL_*` (e.g. `ACDL_LIFECYCLE_MODE`, `ACDL_AWS_ACCOUNT_ID`,
  `ACDL_BOOTSTRAP_AWS_ACCESS_KEY_ID`, …)
- **New:** `NOVA_*` (e.g. `NOVA_LIFECYCLE_MODE`, `NOVA_AWS_ACCOUNT_ID`,
  `NOVA_BOOTSTRAP_AWS_ACCESS_KEY_ID`, …)
- **Phase:** P2 (env vars + consumer path)
- **Grace period — dual-read fallback:** during P2–P4 the platform reads
  **`NOVA_*` first, then falls back to `ACDL_*`** if the Nova variable is
  unset. This means your CI secrets, workflow env blocks, and local
  `.env.secrets` keep working unchanged through P4. You do not need to
  rename everything in one shot — rename a variable and the dual-read picks
  it up; leave one old and it still resolves.
- **Cutoff:** P5 removes the `ACDL_*` fallback. After P5, only `NOVA_*`
  is read.
- **What you must do:** rename your `ACDL_*` CI secrets, workflow `env:`
  blocks, and any local `.env.secrets` entries to `NOVA_*`. Because of the
  dual-read, you can do this incrementally across P2–P4 — but it must be
  complete before P5.

### 3. SSM parameter path — Phase P3 (DONE)

- **Old:** `/acdl/{env}/{contractId}/{output}`
- **New:** `/nova/{env}/{contractId}/{output}`
- **Phase:** P3 (SSM paths + tag keys) — **shipped in P3**
- **Grace period — parallel-write:** during P3–P4 the platform **writes
  every output to both** the `/acdl/…` and `/nova/…` SSM paths, and reads
  from `/nova/…` first (falling back to `/acdl/…`). Any hardcoded SSM path
  reads in your application code keep resolving through P4. The P3
  migration script (`scripts/migrate_ssm_paths.py`) copies existing
  `/acdl/…` parameters to `/nova/…`, verifies the copy, and deletes the
  old ones.
- **Cutoff:** P5 stops writing to `/acdl/…` and removes the read fallback.
  After P5 only `/nova/…` exists.
- **What you must do:** if your application code or runbooks read deploy
  outputs from SSM by hardcoded path, update the path prefix from `/acdl/`
  to `/nova/`. If you consume outputs only via the PR-comment / GitHub
  issue surface, you do nothing — the platform republishes under the new
  path automatically.

### 4. AWS tag keys — Phase P3 (DONE)

- **Old:** `acdl:owner`, `acdl:environment`, `acdl:contract`,
  `acdl:cost-center`, `acdl:ref`
- **New:** `nova:owner`, `nova:environment`, `nova:contract`,
  `nova:cost-center`, `nova:ref`
- **Phase:** P3 (SSM paths + tag keys) — **shipped in P3**
- **Grace period — parallel-tag period:** during P3–P4 the platform
  **tags every resource with both** the `acdl:*` and `nova:*` keys (same
  values). The ABAC session policy matches on **either** key set, so your
  existing scoped permissions keep working. The default cost-center value
  moves from `acdl-default` to `nova-default` (both written during the
  parallel-tag period). Terraform now emits `nova:*` keys; old `acdl:*`
  tags on pre-P3 live resources are removed by the P4 runbook's
  `scripts/untag_acdl_keys.py` step after the `nova:*` tags are applied
  live.
- **Cutoff:** P5 stops writing the `acdl:*` keys and the ABAC policy matches
  only on `nova:*`. After P5, resources created before P5 still carry the
  old `acdl:*` tags (tags are not retroactively rewritten) but **new**
  resources are tagged `nova:*` only, and the policy no longer grants
  access via `acdl:*`.
- **What you must do:** if you have IAM policies, Cost Explorer filters,
  or billing groupings that key off `acdl:*` tag keys, add a parallel
  `nova:*` condition (or migrate to `nova:*`) before P5. The platform
  handles the dual-tagging; you only need to update your own tag-key
  references.

### 5. AWS resource names — Phase P4

- **Old:** `acdl-*` (DynamoDB tables `acdl-contracts`,
  `acdl-change-requests`; Lambda `acdl-contract-ingestor`; SNS
  `acdl-sod-halt`; security group `acdl-ecs-sg`; KMS alias
  `alias/acdl-platform`; ECS services, ECR repos, IAM user
  `acdl-spike-runner`, state bucket `acdl-tfstate-*`, ALB `acdl-alb`,
  `acdl-deploy-*`)
- **New:** `nova-*` (the same resources, prefixed `nova-`)
- **Phase:** P4 (resource names) — **maintenance window**
- **Grace period:** P4 is a **planned maintenance window**. AWS resources
  cannot be renamed in place, so P4 provisions the `nova-*` resources,
  migrates data (DynamoDB tables, S3 state), repoints the platform, and
  tears down the `acdl-*` resources. The platform team schedules and
  announces the window; consumers do not provision or rename anything
  themselves.
- **Cutoff:** the `acdl-*` resources are decommissioned at the end of the
  P4 maintenance window. After P4, only `nova-*` resources exist.
- **What you must do:** nothing for the resource names themselves — the
  platform owns the rename. If your application code or runbooks reference
  a specific `acdl-*` resource by name (e.g. a hardcoded DynamoDB table
  name or ECR URI), update it to the `nova-*` name during P4. The platform
  publishes the exact old → new name mapping with the P4 announcement.

## Timeline at a glance

| Phase | What ships | Grace period | Cutoff |
|-------|------------|--------------|--------|
| **P1** (this phase) | Brand prose, docs, decks, schema `$id`, release titles | n/a (prose only) | n/a |
| **P2** | `.nova/` contract path + `NOVA_*` env vars | dual-read: `.nova/`→`.acdl/`, `NOVA_*`→`ACDL_*` | **P5** removes fallback |
| **P3** | `/nova/` SSM path + `nova:*` tag keys | parallel-write (SSM) + parallel-tag (ABAC matches either) | **P5** removes old path/tags |
| **P4** | `nova-*` AWS resource names | maintenance window (platform-owned migration) | end of P4 window |
| **P5** | Fallback removal | — | `ACDL_*` env vars, `.acdl/` path, `/acdl/` SSM, `acdl:*` tags stop working |

## What consumers must do (checklist)

1. **Before P5 — contract path:** move `.acdl/contract.yml` →
   `.nova/contract.yml` in your consumer repo; update the `contract:`
   workflow input. *(Can be done any time in P2–P4.)*
2. **Before P5 — env vars:** rename `ACDL_*` CI secrets / workflow `env:`
   blocks / local `.env.secrets` to `NOVA_*`. *(Incremental during P2–P4;
   dual-read keeps you green.)*
3. **Before P5 — SSM reads:** if you read deploy outputs from SSM by
   hardcoded `/acdl/…` path, update to `/nova/…`. *(Skip if you consume
   outputs via PR comments only.)*
4. **Before P5 — tag-key references:** if you have IAM policies, Cost
   Explorer filters, or billing groupings keyed off `acdl:*`, add or
   migrate to `nova:*`. *(Platform handles dual-tagging.)*
5. **During P4 — resource-name references:** if your code or runbooks
   reference a specific `acdl-*` AWS resource by name, update to the
   `nova-*` name per the P4 mapping announcement. *(Platform owns the
   rename itself.)*

## Questions

If anything in this guide is unclear, or you are unsure whether your
consumer repo references a renamed value, open an issue on the platform
repo. The platform team will confirm what you need to change and when.

> **Note:** the real Gitea repository name (`continuous-intelligence/acdl`)
> is **not** changing — only the product brand. The `uses:` workflow
> reference and repo path are migrated in a separately-announced later step;
> until then, keep your `uses: acdl/.github/workflows/deploy.yml@vX.Y`
> reference as-is.