acdl/docs/NOVA_MIGRATION.md

Nova Migration Guide — What Consumers Must Know

Nova is the new product brand for the platform formerly known as ACDL (Agentic Cloud Delivery Platform). This guide announces the scheduled breaking changes coming in the rebrand rollout (Phases P2–P4) and tells you exactly what to do, when, and how long you have.

The product is being rebranded A C D L → Nova. The rebrand is staged across phases so that no consumer deployment breaks during the transition. Phases P2–P4 ship the breaking changes behind a dual-read / parallel-write grace period; Phase P5 removes the fallback and the old names stop working. This document is the consumer-facing contract for that rollout.

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.