acdl/.ciagent/PLAN.md

phase, name, milestone, requirements, wave, depends_on

phase	name	milestone	requirements	wave	depends_on
P58	single-platform-vpc-deterministic-state	v1.11	REQ-126	1	P57

P58 — Single Platform VPC + Deterministic State Keys

Phase: P58 Milestone: v1.11 (RESTART) Requirement: REQ-126 Wave: 1 (foundation — the 4-VPC bug fix) Branch: milestone/v1.11-restart → phase/p58-platform-vpc-state

Goal

1. Add a single shared VPC to terraform/platform/main.tf (VPC + 2 subnets + IGW + route table + ECS security group). Output vpc_id, subnet_ids, ecs_security_group_id.
2. Drop the vpc child from the microservice composition; reference the platform VPC via a data_sources block. The alb + service children wire to the platform VPC, not an inline VPC.
3. Fix the state key to be env-aware: spike/{stack_name}/{environment}/terraform.tfstate. Same contract+env always hits the same state key → terraform modifies, never duplicates.
4. The adapter emits data "terraform_remote_state" "platform" + data "aws_vpc" blocks when a stack references platform-owned resources.

Tasks (single wave)

Task 1 — Platform VPC in terraform/platform/main.tf (data-engineer)

Add to terraform/platform/main.tf:

• aws_vpc.acdl_shared (10.0.0.0/16)
• 2 aws_subnet across 2 AZs (10.0.1.0/24, 10.0.2.0/24)
• aws_internet_gateway + aws_route_table + associations
• aws_security_group.ecs (ingress on port 80, egress all)
• Outputs: vpc_id, subnet_ids (comma-separated), ecs_security_group_id

Task 2 — Microservice composition: drop vpc, add data_sources (backend-engineer)

Update modules/l2/microservice/composition.json:

• Remove {"id": "vpc", "module": "vpc@1.0.0"} from children.
• Add a data_sources block: {"name": "platform_vpc", "type": "terraform_remote_state", "source": "platform"}.
• Update wires: vpc.outputs.subnet_ids → platform_vpc.outputs.subnet_ids.
• Add a wire for platform_vpc.outputs.vpc_id → alb.inputs.vpc_id.
• Add a wire for platform_vpc.outputs.ecs_security_group_id → service.inputs.security_group.

Task 3 — Contract resolver: pass environment + handle data_sources (backend-engineer)

Update core/contract_resolver.py:

• Add "environment": env_name to the stack instance's stack block (line 568-572).
• Handle data_sources in the composition: resolve data source references to stack-level pseudo-resources that the adapter can emit as data blocks.

Task 4 — Adapter: env-aware state key + data block emission (backend-engineer)

Update adapters/terraform/adapter.py:

• State key: spike/{stack_name}/{environment}/terraform.tfstate (read environment from stack_instance["stack"]["environment"]).
• When a resource input references a platform data source (e.g. ref:platform_vpc.subnet_ids), emit a data "terraform_remote_state" "platform" block + pass the data source output as the module argument.

Task 5 — Tests + offline regression

• Update tests/test_adapter.py: assert the state key is env-aware.
• Update tests/test_pipeline.py: the microservice contract now resolves without a vpc resource.
• pytest tests/ -m "not slow" — all pass.
• run_platform.sh --check-only contracts/microservice.yml — exits 0.

Success Criteria (phase gate)

1. terraform/platform/main.tf has a VPC + subnets + IGW + route table + SG.
2. contracts/microservice.yml resolution produces NO aws:ec2:vpc resource.
3. Two contract applies (dev + prod) → ONE VPC, two state keys (spike/msvc/dev/, spike/msvc/prod/), two ECS services.
4. Same contract+env re-applied → same state key → terraform modifies, never duplicates.
5. pytest tests/ -m "not slow" — all pass.
6. run_platform.sh --check-only contracts/microservice.yml — exits 0.