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.
2026-07-22 17:24:28 +00:00
parent 75c227429a
commit f68f85c9fd
44 changed files with 905 additions and 244 deletions
@@ -1,11 +1,11 @@
-# l1-alb — Application Load Balancer (load balancer + target group + listener)
+# alb — Application Load Balancer (load balancer + target group + listener)

 > **Module kind:** L1 primitive  |  **Version:** 1.0.0

 An Application Load Balancer with a target group and a listener. This is
 a multi-resource module: it creates a load balancer, a target group, and
 a listener that forwards traffic to the target group. The target group
-is what `l1-ecs-service` registers its tasks with.
+is what `ecs-service` registers its tasks with.

 ## Resources

@@ -20,7 +20,7 @@ is what `l1-ecs-service` registers its tasks with.
 | Name | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
 | `name` | string | yes | — | Name tag for the load balancer and child resources |
-| `subnets` | string | yes | — | Comma-separated subnet ids (from `l1-vpc`) |
+| `subnets` | string | yes | — | Comma-separated subnet ids (from `vpc`) |
 | `security_group` | string | yes | — | Security group id for the load balancer |
 | `port` | number | no | 80 | Listener port |
 | `protocol` | string | no | `HTTP` | Listener protocol |
@@ -40,7 +40,7 @@ is what `l1-ecs-service` registers its tasks with.
 {
  "id": "alb",
  "type": "aws:elbv2:loadbalancer",
-  "module": "l1-alb@1.0.0",
+  "module": "alb@1.0.0",
  "inputs": {
    "name": "acdl-microservice",
    "subnets": "ref:vpc.subnet_ids",
@@ -52,7 +52,7 @@ is what `l1-ecs-service` registers its tasks with.
 }
 ```

-The `target_group_arn` output is referenced by `l1-ecs-service` as its
+The `target_group_arn` output is referenced by `ecs-service` as its
 `lb_target_group_arn` input to wire the service to the ALB.

 ## Compliance extension points
@@ -1,9 +1,9 @@
 {
-  "name": "l1-alb",
+  "name": "alb",
  "version": "1.0.0",
  "kind": "l1",
  "type": "aws:elbv2:loadbalancer",
-  "description": "Application Load Balancer primitive (substrate-agnostic IR types aws:elbv2:loadbalancer + aws:elbv2:listener + aws:elbv2:targetgroup; the Terraform adapter translates to aws_lb/aws_lb_listener/aws_lb_target_group).",
+  "description": "Application Load Balancer primitive (substrate-agnostic stack types aws:elbv2:loadbalancer + aws:elbv2:listener + aws:elbv2:targetgroup; the Terraform adapter translates to aws_lb/aws_lb_listener/aws_lb_target_group).",
  "inputs": {
    "name": {
      "type": "string",
@@ -12,7 +12,7 @@
    },
    "subnets": {
      "type": "string",
-      "description": "Comma-separated subnet ids (ref to l1-vpc).",
+      "description": "Comma-separated subnet ids (ref to vpc).",
      "required": true
    },
    "security_group": {
@@ -1,4 +1,4 @@
-# l1-ecr — ECR repository
+# ecr — ECR repository

 > **Module kind:** L1 primitive  |  **Version:** 1.0.0

@@ -32,7 +32,7 @@ inputs, two outputs.
 {
  "id": "ecr",
  "type": "aws:ecr:repository",
-  "module": "l1-ecr@1.0.0",
+  "module": "ecr@1.0.0",
  "inputs": {
    "name": "acdl-microservice",
    "region": "us-east-1"
@@ -41,7 +41,7 @@ inputs, two outputs.
 ```

 The `repository_url` output is used to build the `image` input for
-`l1-ecs-service` (e.g. `<repository_url>:latest`).
+`ecs-service` (e.g. `<repository_url>:latest`).

 ## Compliance extension points

@@ -1,9 +1,9 @@
 {
-  "name": "l1-ecr",
+  "name": "ecr",
  "version": "1.0.0",
  "kind": "l1",
  "type": "aws:ecr:repository",
-  "description": "ECR repository primitive (substrate-agnostic IR type aws:ecr:repository; the Terraform adapter translates to aws_ecr_repository).",
+  "description": "ECR repository primitive (substrate-agnostic stack type aws:ecr:repository; the Terraform adapter translates to aws_ecr_repository).",
  "inputs": {
    "name": {
      "type": "string",
@@ -1,10 +1,10 @@
-# l1-ecs-cluster — ECS Fargate cluster
+# ecs-cluster — ECS Fargate cluster

 > **Module kind:** L1 primitive  |  **Version:** 1.0.0

 An ECS Fargate cluster. The simplest ECS module — one resource, two
 inputs, two outputs. The cluster is the container orchestration
-boundary that `l1-ecs-service` references for task placement.
+boundary that `ecs-service` references for task placement.

 ## Resources

@@ -32,7 +32,7 @@ boundary that `l1-ecs-service` references for task placement.
 {
  "id": "cluster",
  "type": "aws:ecs:cluster",
-  "module": "l1-ecs-cluster@1.0.0",
+  "module": "ecs-cluster@1.0.0",
  "inputs": {
    "name": "acdl-microservice",
    "region": "us-east-1"
@@ -40,7 +40,7 @@ boundary that `l1-ecs-service` references for task placement.
 }
 ```

-The `cluster_arn` output is referenced by `l1-ecs-service` as its
+The `cluster_arn` output is referenced by `ecs-service` as its
 `cluster_arn` input.

 ## Compliance extension points
@@ -1,9 +1,9 @@
 {
-  "name": "l1-ecs-cluster",
+  "name": "ecs-cluster",
  "version": "1.0.0",
  "kind": "l1",
  "type": "aws:ecs:cluster",
-  "description": "ECS Fargate cluster primitive (substrate-agnostic IR type aws:ecs:cluster; the Terraform adapter translates to aws_ecs_cluster).",
+  "description": "ECS Fargate cluster primitive (substrate-agnostic stack type aws:ecs:cluster; the Terraform adapter translates to aws_ecs_cluster).",
  "inputs": {
    "name": {
      "type": "string",
@@ -1,4 +1,4 @@
-# l1-ecs-service — ECS Fargate service (task definition + service)
+# ecs-service — ECS Fargate service (task definition + service)

 > **Module kind:** L1 primitive  |  **Version:** 1.0.0

@@ -23,10 +23,10 @@ runs it.
 | `cpu` | number | no | 256 | Task CPU units (Fargate) |
 | `memory` | number | no | 512 | Task memory in MiB (Fargate) |
 | `env` | string | no | — | Environment variables as a JSON map string |
-| `cluster_arn` | arn | yes | — | ECS cluster ARN (from `l1-ecs-cluster`) |
-| `subnets` | string | yes | — | Comma-separated subnet ids (from `l1-vpc`) |
+| `cluster_arn` | arn | yes | — | ECS cluster ARN (from `ecs-cluster`) |
+| `subnets` | string | yes | — | Comma-separated subnet ids (from `vpc`) |
 | `security_group` | string | yes | — | Security group id for the service ENIs |
-| `lb_target_group_arn` | arn | no | — | Optional ALB target group ARN (from `l1-alb`) |
+| `lb_target_group_arn` | arn | no | — | Optional ALB target group ARN (from `alb`) |
 | `region` | string | yes | — | AWS region the service is created in |

 ## Outputs
@@ -42,7 +42,7 @@ runs it.
 {
  "id": "service",
  "type": "aws:ecs:task_definition",
-  "module": "l1-ecs-service@1.0.0",
+  "module": "ecs-service@1.0.0",
  "inputs": {
    "image": "581513795199.dkr.ecr.us-east-1.amazonaws.com/acdl-microservice:latest",
    "port": 8080,
@@ -1,9 +1,9 @@
 {
-  "name": "l1-ecs-service",
+  "name": "ecs-service",
  "version": "1.0.0",
  "kind": "l1",
  "type": "aws:ecs:task_definition",
-  "description": "ECS Fargate service primitive (substrate-agnostic IR types aws:ecs:task_definition + aws:ecs:service; the Terraform adapter translates to aws_ecs_task_definition/aws_ecs_service).",
+  "description": "ECS Fargate service primitive (substrate-agnostic stack types aws:ecs:task_definition + aws:ecs:service; the Terraform adapter translates to aws_ecs_task_definition/aws_ecs_service).",
  "inputs": {
    "image": {
      "type": "string",
@@ -34,12 +34,12 @@
    },
    "cluster_arn": {
      "type": "arn",
-      "description": "ECS cluster ARN (ref to l1-ecs-cluster).",
+      "description": "ECS cluster ARN (ref to ecs-cluster).",
      "required": true
    },
    "subnets": {
      "type": "string",
-      "description": "Comma-separated subnet ids (ref to l1-vpc).",
+      "description": "Comma-separated subnet ids (ref to vpc).",
      "required": true
    },
    "security_group": {
@@ -49,7 +49,7 @@
    },
    "lb_target_group_arn": {
      "type": "arn",
-      "description": "Optional ALB target group ARN (ref to l1-alb).",
+      "description": "Optional ALB target group ARN (ref to alb).",
      "required": false
    },
    "region": {
@@ -1,4 +1,4 @@
-# l1-iam-role — IAM role
+# iam-role — IAM role

 > **Module kind:** L1 primitive  |  **Version:** 1.0.0

@@ -33,7 +33,7 @@ policy attachments. Used as the ECS task execution role.
 {
  "id": "roles",
  "type": "aws:iam:role",
-  "module": "l1-iam-role@1.0.0",
+  "module": "iam-role@1.0.0",
  "inputs": {
    "role_name": "acdl-microservice-exec",
    "assume_role_policy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"ecs-tasks.amazonaws.com\"},\"Action\":\"sts:AssumeRole\"}]}",
@@ -1,9 +1,9 @@
 {
-  "name": "l1-iam-role",
+  "name": "iam-role",
  "version": "1.0.0",
  "kind": "l1",
  "type": "aws:iam:role",
-  "description": "IAM role primitive (substrate-agnostic IR type aws:iam:role; the Terraform adapter translates to aws_iam_role).",
+  "description": "IAM role primitive (substrate-agnostic stack type aws:iam:role; the Terraform adapter translates to aws_iam_role).",
  "inputs": {
    "role_name": {
      "type": "string",
@@ -1,4 +1,4 @@
-# l1-s3 — S3 bucket
+# s3 — S3 bucket

 > **Module kind:** L1 primitive  |  **Version:** 1.0.0

@@ -37,7 +37,7 @@ resource, two inputs, two outputs. Versioning is enabled by default.
 {
  "id": "s3",
  "type": "aws:s3:bucket",
-  "module": "l1-s3@1.0.0",
+  "module": "s3@1.0.0",
  "inputs": {
    "bucket_name": "acdl-spike-bucket",
    "region": "us-east-1"
@@ -45,7 +45,7 @@ resource, two inputs, two outputs. Versioning is enabled by default.
 }
 ```

-A concrete instance is at `spike_instance.json` (used by the platform
+A concrete instance is at `instance.json` (used by the platform
 pipeline as the regression baseline).

 ## Compliance extension points
@@ -1,7 +1,7 @@
 {
  "version": "1.0.0",
  "stack": {
-    "name": "l1-s3",
+    "name": "s3",
    "kind": "l1",
    "depth": 1
  },
@@ -9,7 +9,7 @@
    {
      "id": "s3",
      "type": "aws:s3:bucket",
-      "module": "l1-s3@1.0.0",
+      "module": "s3@1.0.0",
      "inputs": {
        "bucket_name": "acdl-spike-bucket",
        "region": "us-east-1"
@@ -1,9 +1,9 @@
 {
-  "name": "l1-s3",
+  "name": "s3",
  "version": "1.0.0",
  "kind": "l1",
  "type": "aws:s3:bucket",
-  "description": "S3 bucket primitive (substrate-agnostic IR type aws:s3:bucket; the Terraform adapter translates to aws_s3_bucket).",
+  "description": "S3 bucket primitive (substrate-agnostic stack type aws:s3:bucket; the Terraform adapter translates to aws_s3_bucket).",
  "inputs": {
    "bucket_name": {
      "type": "string",
@@ -1,4 +1,4 @@
-# l1-vpc — VPC with subnets and routing
+# vpc — VPC with subnets and routing

 > **Module kind:** L1 primitive  |  **Version:** 1.0.0

@@ -38,7 +38,7 @@ that other modules (ALB, ECS service) reference for subnet ids.
 {
  "id": "vpc",
  "type": "aws:ec2:vpc",
-  "module": "l1-vpc@1.0.0",
+  "module": "vpc@1.0.0",
  "inputs": {
    "cidr": "10.0.0.0/16",
    "azs": "us-east-1a,us-east-1b",
@@ -1,9 +1,9 @@
 {
-  "name": "l1-vpc",
+  "name": "vpc",
  "version": "1.0.0",
  "kind": "l1",
  "type": "aws:ec2:vpc",
-  "description": "VPC primitive (substrate-agnostic IR types aws:ec2:vpc + aws:ec2:subnet + aws:ec2:routetable; the Terraform adapter translates to aws_vpc/aws_subnet/aws_route_table).",
+  "description": "VPC primitive (substrate-agnostic stack types aws:ec2:vpc + aws:ec2:subnet + aws:ec2:routetable; the Terraform adapter translates to aws_vpc/aws_subnet/aws_route_table).",
  "inputs": {
    "cidr": {
      "type": "string",