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.

adapters/terraform/adapter.py

@@ -1,19 +1,19 @@
-"""ACDL Terraform adapter — compile a Target Stack IR instance to Terraform.
+"""ACDL Terraform adapter — compile a Target Stack instance to Terraform.
 
-ARCHITECTURE.md §12.2: the adapter translates the IR-typed L1 interface
-to a Terraform variable/output block, the L2 thin-composition tree to a
-root module that calls the L1 modules, the IR-typed relationships to
-Terraform module references, and emits a Terraform plan from the IR.
+ARCHITECTURE.md §12.2: the adapter translates the stack-typed L1 interface
+to a Terraform variable/output block, the L2 composition tree to a
+root module that calls the L1 modules, the stack-typed relationships to
+Terraform module references, and emits a Terraform plan from the stack.
 
 The adapter is a THIN LAYER; it does not own L1/L2 content — it only
 translates. Substrate-agnostic in, Terraform out.
 
-Phase 09 spike: handled one L1 (l1-s3, IR type aws:s3:bucket).
+Phase 09 spike: handled one L1 (s3, stack type aws:s3:bucket).
 Phase 13: generalized the resource/output emission via TYPE_MAP +
-INPUT_MAP + OUTPUT_MAP tables; added ECS Fargate IR types. S3 behavior
-is preserved (regression baseline: modules-ir/l1/l1-s3/spike_instance.json).
+INPUT_MAP + OUTPUT_MAP tables; added ECS Fargate stack types. S3 behavior
+is preserved (regression baseline: modules/l1/s3/instance.json).
 
-CLI: adapter.py <ir_instance.json> <out_dir>
+CLI: adapter.py <instance.json> <out_dir>
 """
 
 import json
@@ -21,8 +21,8 @@ import os
 import sys
 
 
-# IR type -> Terraform resource type. The only substrate-specific table.
-# As more L1s land, this grows; the L1 content + IR do not change.
+# Stack type -> Terraform resource type. The only substrate-specific table.
+# As more L1s land, this grows; the L1 content + stack do not change.
 TYPE_MAP = {
     "aws:s3:bucket": "aws_s3_bucket",
     "aws:ec2:vpc": "aws_vpc",
@@ -38,8 +38,8 @@ TYPE_MAP = {
     "aws:ecr:repository": "aws_ecr_repository",
 }
 
-# IR input name -> Terraform arg name, per IR type. Only non-identity
-# mappings are listed; any input not present here uses the IR name as
+# Stack input name -> Terraform arg name, per stack type. Only non-identity
+# mappings are listed; any input not present here uses the stack name as
 # the Terraform arg name (identity).
 INPUT_MAP = {
     "aws:s3:bucket": {"bucket_name": "bucket"},
@@ -56,9 +56,9 @@ INPUT_MAP = {
     "aws:ecr:repository": {},
 }
 
-# IR output name -> Terraform attribute name, per IR type. Only
+# Stack output name -> Terraform attribute name, per stack type. Only
 # non-identity mappings are listed; any output not present here uses the
-# IR name as the Terraform attribute name (identity).
+# stack name as the Terraform attribute name (identity).
 OUTPUT_MAP = {
     "aws:s3:bucket": {"bucket_arn": "arn", "bucket_name": "id"},
     "aws:ec2:vpc": {"vpc_id": "id"},
@@ -101,24 +101,24 @@ def _tf_value(value):
 
 
 def _ref_expr(ref_value, type_by_id):
-    """Translate a "ref:<ir_resource_id>.<output>" string to a Terraform
+    """Translate a "ref:<stack_resource_id>.<output>" string to a Terraform
     interpolation "${<tf_type>.<id>.<attr>}".
 
-    <ir_resource_id> is the IR resource id of the producing resource;
+    <stack_resource_id> is the stack resource id of the producing resource;
     <output> is the per-resource output name (e.g. `subnet_id`,
     `cluster_arn`); the attribute is mapped through OUTPUT_MAP for the
-    referenced resource's IR type. The resolver emits the ref using the
-    IR resource id directly (not the child id), so no child->resource
+    referenced resource's stack type. The resolver emits the ref using the
+    stack resource id directly (not the child id), so no child->resource
     lookup table is needed here.
     """
     body = ref_value[len("ref:"):]
     rid, out_name = body.split(".", 1)
     rtype = type_by_id.get(rid)
     if not rtype:
-        raise ValueError(f"ref to unknown IR resource id {rid!r}")
+        raise ValueError(f"ref to unknown stack resource id {rid!r}")
     tf_type = TYPE_MAP.get(rtype)
     if not tf_type:
-        raise ValueError(f"ref target {rid!r} has unknown IR type {rtype!r}")
+        raise ValueError(f"ref target {rid!r} has unknown stack type {rtype!r}")
     out_map = OUTPUT_MAP.get(rtype, {})
     tf_attr = out_map.get(out_name, out_name)
     return f"{tf_type}.{rid}.{tf_attr}"
@@ -139,7 +139,7 @@ def _emit_resource(resource, type_by_id=None):
     rid = resource["id"]
     tf_type = TYPE_MAP.get(rtype)
     if not tf_type:
-        raise ValueError(f"unknown IR type {rtype!r} (adapter TYPE_MAP has no entry)")
+        raise ValueError(f"unknown stack type {rtype!r} (adapter TYPE_MAP has no entry)")
     in_map = INPUT_MAP.get(rtype, {})
     body = []
     inputs = resource.get("inputs", {})
@@ -306,11 +306,11 @@ def _emit_output(output_name, value_expr):
     return f'output "{output_name}" {{\n  value = {value_expr}\n}}\n'
 
 
-def adapt(ir_instance, out_dir):
-    """Emit main.tf + terraform.tf + providers.tf to out_dir for the IR instance."""
+def adapt(stack_instance, out_dir):
+    """Emit main.tf + terraform.tf + providers.tf to out_dir for the stack instance."""
     os.makedirs(out_dir, exist_ok=True)
-    stack = ir_instance["stack"]
-    resources = ir_instance["resources"]
+    stack = stack_instance["stack"]
+    resources = stack_instance["resources"]
 
     # --- providers.tf: aws provider, region from the first resource's inputs.region ---
     region = "us-east-1"
@@ -345,9 +345,9 @@ def adapt(ir_instance, out_dir):
     )
 
     # --- main.tf: resources + outputs ---
-    # Build an IR-resource-id -> IR-type table so `ref:` input values can
+    # Build a stack-resource-id -> stack-type table so `ref:` input values can
     # be resolved to Terraform interpolations without a child->resource
-    # lookup (the resolver emits refs with the IR resource id directly).
+    # lookup (the resolver emits refs with the stack resource id directly).
     type_by_id = {r["id"]: r["type"] for r in resources}
     main_tf_parts = []
     has_vpc = any(r["type"] == "aws:ec2:vpc" for r in resources)
@@ -376,9 +376,9 @@ def adapt(ir_instance, out_dir):
 
 if __name__ == "__main__":
     if len(sys.argv) != 3:
-        print("usage: adapter.py <ir_instance.json> <out_dir>", file=sys.stderr)
+        print("usage: adapter.py <instance.json> <out_dir>", file=sys.stderr)
         sys.exit(2)
     with open(sys.argv[1], "r") as fh:
-        ir = json.load(fh)
-    adapt(ir, sys.argv[2])
+        stack = json.load(fh)
+    adapt(stack, sys.argv[2])
     print(f"adapter: emitted terraform to {sys.argv[2]}", file=sys.stderr)