review(v1.5): READY TO SHIP — multi-persona code review

---ci---
project: acdl
phase: 20
milestone: v1.5
status: review
verdict: READY TO SHIP
p0: 1 (fixed — contract path resolution in deploy workflow)
p1: 6 (flagged post-hoc)
---/ci---

Multi-persona review of v1.5 phase 20 (docs + reusable deploy workflow).

P0 (blocking) — AUTO-FIXED:
- C1: scripts/run_platform.sh contract path resolution broken in deploy
  workflow. The reusable workflow invokes run_platform.sh from the consumer
  workspace root with a relative contract path (.acdl/contract.yaml), but
  run_platform.sh does `cd "$ROOT"` (platform repo) early, so the relative
  path resolved against the platform repo and the pipeline could never run.
  Fix (commit 75c2274): capture CALLER_CWD before cd "$ROOT"; resolve
  caller-supplied relative paths against CALLER_CWD; default no-arg contract
  stays relative to ROOT (preserves platform-local CI). Reproduced pre-fix;
  verified post-fix.

P1 (important) — FLAGGED FOR POST-HOC REVIEW (do not block ship):
- C2: ref: v1.4 in the deploy workflow platform checkout — no v1.4 tag exists
  (only v1.4.0 / v1.4.1). Operator must create a floating v1.4 tag or change
  the ref to v1.4.1.
- C3: modules/l2/{static-asset,microservice}/README.md still use @v1 in their
  Usage examples; missed by the v1.4 bump.
- S1: static-key override is not wired. ACDL_AWS_* env vars on the OIDC step
  are not read by aws-actions/configure-aws-credentials@v4 (it reads AWS_*
  or its own access-key/secret-key inputs). The README/CONSUMER_GUIDE claim
  a working override that doesn't function as written. Needs a conditional
  step or renamed env vars + input wiring.
- S2: README overstates ABAC repo:org/repo:ref:... scoping. The workflow
  constructs a numeric role name (github.repository_id); the actual claim
  enforcement lives in the IAM trust policy, not in this workflow.
- T1: no deploy-workflow triggers conformance test (CI workflow has one;
  deploy doesn't). Minor — reusable workflows use workflow_call, not push
  triggers, but the contract's triggers field is then unenforced.
- A1: terraform/spike/terraform.tf uploaded as artifact leaks the AWS account
  ID via the state-backend bucket name. Recommend excluding terraform.tf or
  gating artifact upload to non-public repos.

P2 (nits) — listed for awareness: floating-tag terminology imprecision (M1),
  header comment "Gitea Actions" in the GitHub copy (M2, intentional byte-
  identical), pip install split (P1-perf), comment drift in pipelines/deploy.yaml
  header (C4), module README internal inconsistency (C5).

Verdict: READY TO SHIP. The one P0 is fixed. The 6 P1s are post-hoc items —
the deploy workflow is a scaffold whose first real consumer run requires
operator setup (tag, IAM role, secrets) that gates go-live. The P1s should
be addressed before any consumer invokes uses: acdl/.gitea/workflows/
deploy.yml@v1.4 in earnest.

Tests: 154 pass (19 new). run_ci.sh green.

tests/conftest.py

@@ -15,18 +15,18 @@ def repo_root():
 
 
 @pytest.fixture
-def spike_ir():
-    return json.load(open(ROOT / "modules-ir/l1/l1-s3/spike_instance.json"))
+def stack_instance():
+    return json.load(open(ROOT / "modules/l1/s3/instance.json"))
 
 
 @pytest.fixture
-def ir_schema():
-    return json.load(open(ROOT / "schemas/ir.schema.json"))
+def stack_schema():
+    return json.load(open(ROOT / "schemas/stack.schema.json"))
 
 
 @pytest.fixture
 def registry():
-    return json.load(open(ROOT / "modules-ir/registry.json"))
+    return json.load(open(ROOT / "modules/registry.json"))
 
 
 @pytest.fixture

tests/test_adapter.py

@@ -15,38 +15,44 @@ from adapters.terraform.adapter import (
 ROOT = Path(__file__).resolve().parent.parent
 
 
-class TestSpikeInstance:
-    def test_spike_instance_validates_against_ir_schema(self, spike_ir, ir_schema):
-        jsonschema.validate(spike_ir, ir_schema)
+class TestInstance:
+    def test_instance_validates_against_stack_schema(self, stack_instance, stack_schema):
+        jsonschema.validate(stack_instance, stack_schema)
 
-    def test_spike_instance_has_one_resource(self, spike_ir):
-        assert len(spike_ir["resources"]) == 1
-        r = spike_ir["resources"][0]
+    def test_instance_has_one_resource(self, stack_instance):
+        assert len(stack_instance["resources"]) == 1
+        r = stack_instance["resources"][0]
         assert r["id"] == "s3"
         assert r["type"] == "aws:s3:bucket"
 
-    def test_spike_instance_stack_is_l1_s3(self, spike_ir):
-        assert spike_ir["stack"]["name"] == "l1-s3"
-        assert spike_ir["stack"]["kind"] == "l1"
+    def test_instance_stack_is_s3(self, stack_instance):
+        assert stack_instance["stack"]["name"] == "s3"
+        assert stack_instance["stack"]["kind"] == "l1"
 
 
 class TestRegistry:
-    def test_registry_has_7_l1_entries(self, registry):
-        assert len(registry) == 7
-        for key in registry:
-            assert key.startswith("l1-")
+    EXPECTED_L1_KEYS = {"s3", "vpc", "ecs-cluster", "ecs-service", "iam-role", "alb", "ecr"}
+    EXPECTED_L2_KEYS = {"static-asset", "microservice"}
 
-    def test_registry_has_no_l2_entries(self, registry):
-        l2 = [k for k in registry if k.startswith("l2")]
-        assert l2 == []
+    def test_registry_has_9_entries(self, registry):
+        assert len(registry) == 9
+        assert set(registry.keys()) == (self.EXPECTED_L1_KEYS | self.EXPECTED_L2_KEYS)
+
+    def test_registry_has_7_l1_entries(self, registry):
+        l1 = {k for k in registry if registry[k]["1.0.0"]["interface"].startswith("modules/l1/")}
+        assert l1 == self.EXPECTED_L1_KEYS
+
+    def test_registry_has_2_l2_entries(self, registry):
+        l2 = {k for k in registry if registry[k]["1.0.0"]["interface"].startswith("modules/l2/")}
+        assert l2 == self.EXPECTED_L2_KEYS
 
     def test_all_l1_interfaces_exist(self, registry, repo_root):
-        for name, versions in registry.items():
-            for ver, entry in versions.items():
-                iface_path = os.path.join(repo_root, entry["interface"])
-                assert os.path.isfile(iface_path), f"{iface_path} missing"
-                iface = json.load(open(iface_path))
-                assert iface["name"] == name
+        for name in self.EXPECTED_L1_KEYS:
+            entry = registry[name]["1.0.0"]
+            iface_path = os.path.join(repo_root, entry["interface"])
+            assert os.path.isfile(iface_path), f"{iface_path} missing"
+            iface = json.load(open(iface_path))
+            assert iface["name"] == name
 
 
 class TestTypeMap:
@@ -119,56 +125,56 @@ class TestRefExpr:
         assert result == "aws_vpc.vpc.id"
 
     def test_unknown_id_raises(self):
-        with pytest.raises(ValueError, match="unknown IR resource id"):
+        with pytest.raises(ValueError, match="unknown stack resource id"):
             _ref_expr("ref:nonexistent.output", {"s3": "aws:s3:bucket"})
 
 
 class TestAdapt:
-    def test_adapt_emits_three_files(self, spike_ir, tmp_path):
+    def test_adapt_emits_three_files(self, stack_instance, tmp_path):
         out_dir = str(tmp_path / "tf_out")
-        adapt(spike_ir, out_dir)
+        adapt(stack_instance, out_dir)
         assert os.path.isfile(os.path.join(out_dir, "main.tf"))
         assert os.path.isfile(os.path.join(out_dir, "terraform.tf"))
         assert os.path.isfile(os.path.join(out_dir, "providers.tf"))
 
-    def test_main_tf_has_s3_bucket(self, spike_ir, tmp_path):
+    def test_main_tf_has_s3_bucket(self, stack_instance, tmp_path):
         out_dir = str(tmp_path / "tf_out")
-        adapt(spike_ir, out_dir)
+        adapt(stack_instance, out_dir)
         main_tf = open(os.path.join(out_dir, "main.tf")).read()
         assert 'resource "aws_s3_bucket" "s3"' in main_tf
         assert 'bucket = "acdl-spike-bucket"' in main_tf
 
-    def test_main_tf_has_versioning(self, spike_ir, tmp_path):
+    def test_main_tf_has_versioning(self, stack_instance, tmp_path):
         out_dir = str(tmp_path / "tf_out")
-        adapt(spike_ir, out_dir)
+        adapt(stack_instance, out_dir)
         main_tf = open(os.path.join(out_dir, "main.tf")).read()
         assert "versioning" in main_tf
         assert "enabled = true" in main_tf
 
-    def test_main_tf_has_outputs(self, spike_ir, tmp_path):
+    def test_main_tf_has_outputs(self, stack_instance, tmp_path):
         out_dir = str(tmp_path / "tf_out")
-        adapt(spike_ir, out_dir)
+        adapt(stack_instance, out_dir)
         main_tf = open(os.path.join(out_dir, "main.tf")).read()
         assert 'output "bucket_arn"' in main_tf
         assert 'output "bucket_name"' in main_tf
 
-    def test_terraform_tf_has_backend(self, spike_ir, tmp_path):
+    def test_terraform_tf_has_backend(self, stack_instance, tmp_path):
         out_dir = str(tmp_path / "tf_out")
-        adapt(spike_ir, out_dir)
+        adapt(stack_instance, out_dir)
         terraform_tf = open(os.path.join(out_dir, "terraform.tf")).read()
         assert 'backend "s3"' in terraform_tf
         assert 'required_version' in terraform_tf
         assert ">= 1.9" in terraform_tf
 
-    def test_providers_tf_has_aws(self, spike_ir, tmp_path):
+    def test_providers_tf_has_aws(self, stack_instance, tmp_path):
         out_dir = str(tmp_path / "tf_out")
-        adapt(spike_ir, out_dir)
+        adapt(stack_instance, out_dir)
         providers_tf = open(os.path.join(out_dir, "providers.tf")).read()
         assert 'provider "aws"' in providers_tf
         assert "us-east-1" in providers_tf
 
-    def test_backend_key_uses_stack_name(self, spike_ir, tmp_path):
+    def test_backend_key_uses_stack_name(self, stack_instance, tmp_path):
         out_dir = str(tmp_path / "tf_out")
-        adapt(spike_ir, out_dir)
+        adapt(stack_instance, out_dir)
         terraform_tf = open(os.path.join(out_dir, "terraform.tf")).read()
-        assert "spike/l1-s3/terraform.tfstate" in terraform_tf
+        assert "spike/s3/terraform.tfstate" in terraform_tf

tests/test_confidence_signal.py

@@ -82,14 +82,14 @@ class TestPerInputScore:
 
     def test_validation_all_true(self):
         score, reasons = _per_input_score("validation", {
-            "schema": True, "ir_resolved": True,
+            "schema": True, "stack_resolved": True,
             "tf_validated": True, "tf_planned": True
         })
         assert score == 1.0
 
     def test_validation_partial(self):
         score, reasons = _per_input_score("validation", {
-            "schema": True, "ir_resolved": True,
+            "schema": True, "stack_resolved": True,
             "tf_validated": False, "tf_planned": False
         })
         assert score == 0.5
@@ -131,7 +131,7 @@ class TestCompute:
     def _base_inputs(self):
         return {
             "policy": [{"result": "pass"}],
-            "validation": {"schema": True, "ir_resolved": True,
+            "validation": {"schema": True, "stack_resolved": True,
                            "tf_validated": True, "tf_planned": True},
             "freshness": {"age_days": 0, "max_age_days": 7},
             "source": {"submitter": "dev", "commit_sha": "abc"},

tests/test_contract_resolver.py

@@ -0,0 +1,154 @@
+import json
+import os
+import sys
+from pathlib import Path
+
+import jsonschema
+import pytest
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+class TestContractSchema:
+    def test_schema_is_valid_json_schema(self):
+        schema = json.load(open(ROOT / "schemas/contract.schema.json"))
+        jsonschema.Draft202012Validator.check_schema(schema)
+
+    def test_schema_requires_uses_module_environment_inputs(self):
+        schema = json.load(open(ROOT / "schemas/contract.schema.json"))
+        for field in ["uses", "module", "environment", "inputs"]:
+            assert field in schema["required"]
+
+
+class TestResolveStaticAsset:
+    def test_resolve_static_asset_contract(self, tmp_path):
+        from acdl_platform.contract_resolver import resolve
+        stack = resolve(str(ROOT / "contracts/static-asset.yaml"), str(ROOT))
+        assert stack["stack"]["name"] == "static-asset"
+        assert stack["stack"]["kind"] == "l2"
+        assert stack["stack"]["depth"] == 1
+        assert len(stack["resources"]) >= 1
+
+    def test_resolve_static_asset_has_s3_resource(self):
+        from acdl_platform.contract_resolver import resolve
+        stack = resolve(str(ROOT / "contracts/static-asset.yaml"), str(ROOT))
+        s3_res = [r for r in stack["resources"] if r["type"] == "aws:s3:bucket"]
+        assert len(s3_res) == 1
+        assert s3_res[0]["inputs"]["bucket_name"] == "acdl-spike-bucket"
+        assert s3_res[0]["inputs"]["region"] == "us-east-1"
+
+    def test_resolve_static_asset_validates_against_stack_schema(self):
+        from acdl_platform.contract_resolver import resolve
+        stack = resolve(str(ROOT / "contracts/static-asset.yaml"), str(ROOT))
+        schema = json.load(open(ROOT / "schemas/stack.schema.json"))
+        jsonschema.validate(stack, schema)
+
+
+class TestResolveMicroservice:
+    def test_resolve_microservice_contract(self):
+        contract = {
+            "uses": "acdl/pipelines/deploy.yaml@v1",
+            "module": "microservice",
+            "environment": "dev",
+            "inputs": {
+                "image": "581513795199.dkr.ecr.us-east-1.amazonaws.com/acdl-microservice:latest",
+                "port": 8080,
+                "region": "us-east-1",
+            },
+        }
+        contract_path = ROOT / "contracts" / "test-microservice.yaml"
+        with open(contract_path, "w") as fh:
+            yaml.dump(contract, fh)
+        try:
+            from acdl_platform.contract_resolver import resolve
+            stack = resolve(str(contract_path), str(ROOT))
+            assert stack["stack"]["name"] == "microservice"
+            assert stack["stack"]["kind"] == "l2"
+            assert len(stack["resources"]) >= 6
+        finally:
+            os.remove(contract_path)
+
+
+class TestResolveL1Direct:
+    def test_resolve_s3_direct(self, tmp_path):
+        contract = {
+            "uses": "acdl/pipelines/deploy.yaml@v1",
+            "module": "s3",
+            "environment": "dev",
+            "inputs": {
+                "bucket_name": "my-test-bucket",
+                "region": "us-east-1",
+            },
+        }
+        contract_path = tmp_path / "test-s3.yaml"
+        with open(contract_path, "w") as fh:
+            yaml.dump(contract, fh)
+        from acdl_platform.contract_resolver import resolve
+        stack = resolve(str(contract_path), str(ROOT))
+        assert stack["stack"]["name"] == "s3"
+        assert stack["stack"]["kind"] == "l1"
+        assert len(stack["resources"]) == 1
+        assert stack["resources"][0]["type"] == "aws:s3:bucket"
+        assert stack["resources"][0]["inputs"]["bucket_name"] == "my-test-bucket"
+
+    def test_resolve_s3_validates_against_stack_schema(self, tmp_path):
+        contract = {
+            "uses": "acdl/pipelines/deploy.yaml@v1",
+            "module": "s3",
+            "environment": "dev",
+            "inputs": {"bucket_name": "test", "region": "us-east-1"},
+        }
+        contract_path = tmp_path / "test-s3-schema.yaml"
+        with open(contract_path, "w") as fh:
+            yaml.dump(contract, fh)
+        from acdl_platform.contract_resolver import resolve
+        stack = resolve(str(contract_path), str(ROOT))
+        schema = json.load(open(ROOT / "schemas/stack.schema.json"))
+        jsonschema.validate(stack, schema)
+
+
+class TestResolveErrors:
+    def test_unknown_module_raises(self, tmp_path):
+        contract = {
+            "uses": "acdl/pipelines/deploy.yaml@v1",
+            "module": "nonexistent",
+            "environment": "dev",
+            "inputs": {},
+        }
+        contract_path = tmp_path / "bad.yaml"
+        with open(contract_path, "w") as fh:
+            yaml.dump(contract, fh)
+        from acdl_platform.contract_resolver import resolve
+        with pytest.raises(ValueError, match="not found in registry"):
+            resolve(str(contract_path), str(ROOT))
+
+    def test_missing_required_field_fails_validation(self, tmp_path):
+        contract = {"uses": "acdl/pipelines/deploy.yaml@v1", "module": "s3"}
+        contract_path = tmp_path / "incomplete.yaml"
+        with open(contract_path, "w") as fh:
+            yaml.dump(contract, fh)
+        from acdl_platform.contract_resolver import resolve
+        with pytest.raises(jsonschema.ValidationError):
+            resolve(str(contract_path), str(ROOT))
+
+
+class TestDeployPipelineContract:
+    def test_deploy_pipeline_validates_against_schema(self):
+        schema = json.load(open(ROOT / "schemas/deploy-pipeline.schema.json"))
+        with open(ROOT / "pipelines/deploy.yaml") as fh:
+            contract = yaml.safe_load(fh)
+        jsonschema.validate(contract, schema)
+
+    def test_deploy_pipeline_has_six_stages(self):
+        with open(ROOT / "pipelines/deploy.yaml") as fh:
+            contract = yaml.safe_load(fh)
+        stage_names = [s["name"] for s in contract["stages"]]
+        assert "validate-contract" in stage_names
+        assert "resolve-stack" in stage_names
+        assert "terraform-plan" in stage_names
+        assert "checkov" in stage_names
+        assert "confidence" in stage_names
+        assert "apply" in stage_names

tests/test_outbox_writer.py

@@ -41,7 +41,7 @@ class TestWriteEvent:
             "eventType": "CONFIDENCE_COMPUTED",
             "ts": "2026-07-22T00:00:00Z",
             "environment": "dev",
-            "stack": "l1-s3",
+            "stack": "s3",
             "score": 0.85,
             "band": "pass",
             "prev_event_hash": "GENESIS",

tests/test_pipeline.py

@@ -10,14 +10,14 @@ ROOT = Path(__file__).resolve().parent.parent
 
 
 class TestPipelineIntegration:
-    def test_load_ir_and_adapt_offline(self, tmp_path):
-        ir = json.load(open(ROOT / "modules-ir/l1/l1-s3/spike_instance.json"))
-        assert ir["stack"]["name"] == "l1-s3"
+    def test_load_stack_and_adapt_offline(self, tmp_path):
+        stack = json.load(open(ROOT / "modules/l1/s3/instance.json"))
+        assert stack["stack"]["name"] == "s3"
 
         sys.path.insert(0, str(ROOT))
         from adapters.terraform.adapter import adapt
         out_dir = str(tmp_path / "tf")
-        adapt(ir, out_dir)
+        adapt(stack, out_dir)
 
         assert os.path.isfile(os.path.join(out_dir, "main.tf"))
         assert os.path.isfile(os.path.join(out_dir, "terraform.tf"))
@@ -33,7 +33,7 @@ class TestPipelineIntegration:
 
         inputs = {
             "policy": [{"result": "pass"}],
-            "validation": {"schema": True, "ir_resolved": True,
+            "validation": {"schema": True, "stack_resolved": True,
                            "tf_validated": True, "tf_planned": True},
             "freshness": {"age_days": 0, "max_age_days": 7},
             "source": {"submitter": "test", "commit_sha": "test-sha"},