continuous-intelligence/acdl
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases 128 Wiki Activity

docs(P21): rewrite README + normalize modules terminology (REQ-52,55,56,57,58,59,60)

Browse Source 
---ci---
project: acdl
phase: 21
milestone: v1.6
status: execute
---/ci---

README.md rewrite:
- Remove all .ciagent/ references (links + repository-layout row).
- Remove .gitea/workflows/ row from repository layout.
- Restate repository roles: consumer repo = app code + 1+ contracts +
  CI definitions (thin .github/workflows/*.yml uses:-ing the central
  workflow); platform repo owns modules/adapters/core/schemas/pipelines/
  scripts/workflows.
- Replace Status section with Features list (consumer + platform-engineer
  referenceable) + Roadmap (planned only, no version changelog, no
  internal CIAgent status). Includes the composition-redesign roadmap
  entry (dynamic module creation from a contract).
- Fix the mermaid flowchart: all node text visible (short multi-line
  labels via <br/>), add a security-checks stage before policy checks,
  do not name specific tools (security checks/policy checks/infrastructure
  plan via adapter), add infrastructure-apply stage (dev only, after
  evidence event).
- Remove the environments table (dev/qa/prod/dr) completely; point to
  docs/environments/ for platform-managed environments.
- Credentials section: remove go-gitea/gitea#36988 blocked mention +
  waivers D-039/D-047 language. State OIDC+ABAC default; alternative is a
  static AWS key (GitHub Secrets for platform-runner runs, .env.secrets
  locally) with daily rotation (platform-managed) or out-of-band rotation
  (consumer-managed for local .env.secrets).
- forge -> platform runners / platform-managed throughout.
- Links point to docs/ Pages paths, not .ciagent/.

modules/ terminology:
- modules/README.md: L1 primitives -> primitives, L2 compositions ->
  modules, composition -> pattern (prose); add roadmap note for the
  composition redesign.
- README-TEMPLATE.md: L1 primitive -> primitive.
- All 7 L1 READMEs: L1 primitive -> primitive.
- L2 static-asset + microservice READMEs: L2 composition -> module
  pattern, composition -> pattern, L1 -> primitive; bump stale @v1 ->
  @v1.4 in usage examples; fix CONSUMER_GUIDE.md -> consumer-guide.md
  link.

Verification: grep sweeps for .ciagent/.gitea/forge/go-gitea/waiver/
D-039/D-047/acdl_platform in docs/ README.md modules/ contracts/ all
return 0 hits. Tests: 166 pass. run_ci.sh green.
This commit is contained in:
Jon Chery
2026-07-22 18:26:00 +00:00
parent 4e495e5648
commit 553caf8f1d
12 changed files with 191 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files
modules/README-TEMPLATE.md
+1 -1
View File
@@ -1,6 +1,6 @@
# &lt;module-name&gt; — &lt;plain-language description&gt;
> **Module kind:** L1 primitive | **Version:** 1.0.0
> **Module kind:** primitive | **Version:** 1.0.0
## Overview
modules/README.md
+23 -16
View File
@@ -8,19 +8,19 @@ self-documented with a `README.md` following the
There are two kinds of module:
- **L1 primitives** — a single cloud resource or a small group of
related resources (e.g. a VPC with subnets and routing). Each L1 has
an `interface.json` declaring its inputs and outputs, and a `README.md`
in plain language.
- **L2 compositions** — a composition that references multiple L1s to
deploy a complete stack (e.g. an ECS Fargate microservice). Each L2
- **Primitives** — a single cloud resource or a small group of
related resources (e.g. a VPC with subnets and routing). Each primitive
has an `interface.json` declaring its inputs and outputs, and a
`README.md` in plain language.
- **Modules** — a pattern that references multiple primitives to
deploy a complete stack (e.g. an ECS Fargate microservice). Each module
has a `composition.json` declaring its children and wires.
The Terraform adapter (`adapters/terraform/adapter.py`) compiles a
module instance to Terraform. Each module's README documents which
Terraform resources it creates.
The substrate adapter (`adapters/terraform/adapter.py`) compiles a
module instance to infrastructure. Each module's README documents which
resources it creates.
## L1 primitives
## Primitives
| Module | What it creates | README |
|--------|----------------|--------|
@@ -32,19 +32,26 @@ Terraform resources it creates.
| `alb` | `aws_lb` + `aws_lb_target_group` + `aws_lb_listener` — Application Load Balancer | [README](l1/alb/README.md) |
| `ecr` | `aws_ecr_repository` — ECR container image repository | [README](l1/ecr/README.md) |
## L2 compositions
## Modules
| Module | What it references | README |
|--------|--------------------|--------|
| `microservice` | 6 L1s (vpc, cluster, ecr, iam-role, alb, ecs-service) | [README](l2/microservice/README.md) |
| `static-asset` | 1 L1 (s3) | [README](l2/static-asset/README.md) |
| `microservice` | 6 primitives (vpc, cluster, ecr, iam-role, alb, ecs-service) | [README](l2/microservice/README.md) |
| `static-asset` | 1 primitive (s3) | [README](l2/static-asset/README.md) |
## Registry
Module versions are tracked in `registry.json`. Both L1 and L2 entries
are registered.
Module versions are tracked in `registry.json`. Both primitives and
modules are registered.
## Template
New modules should use [README-TEMPLATE.md](README-TEMPLATE.md) as
their starting point.
their starting point.
## Module patterns (roadmap)
The current `composition.json` mechanism is a thin pattern layer. A future
redesign will let a consumer dynamically create a module directly from the
contract file (an agentic "composition" flow). That is on the roadmap, not
implemented today.
modules/l1/alb/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# alb — Application Load Balancer (load balancer + target group + listener)
> **Module kind:** L1 primitive | **Version:** 1.0.0
> **Module kind:** 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
modules/l1/ecr/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# ecr — ECR repository
> **Module kind:** L1 primitive | **Version:** 1.0.0
> **Module kind:** primitive | **Version:** 1.0.0
A single ECR repository that hosts the container image for the ECS
task. The simplest container-registry module — one resource, two
modules/l1/ecs-cluster/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# ecs-cluster — ECS Fargate cluster
> **Module kind:** L1 primitive | **Version:** 1.0.0
> **Module kind:** 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
modules/l1/ecs-service/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# ecs-service — ECS Fargate service (task definition + service)
> **Module kind:** L1 primitive | **Version:** 1.0.0
> **Module kind:** primitive | **Version:** 1.0.0
An ECS Fargate service with its task definition. Runs a container image
on Fargate, optionally behind an ALB target group. This is a
modules/l1/iam-role/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# iam-role — IAM role
> **Module kind:** L1 primitive | **Version:** 1.0.0
> **Module kind:** primitive | **Version:** 1.0.0
A single IAM role with an assume-role policy and optional managed
policy attachments. Used as the ECS task execution role.
modules/l1/s3/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# s3 — S3 bucket
> **Module kind:** L1 primitive | **Version:** 1.0.0
> **Module kind:** primitive | **Version:** 1.0.0
A single S3 bucket for object storage. The simplest module — one
resource, two inputs, two outputs. Versioning is enabled by default.
modules/l1/vpc/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# vpc — VPC with subnets and routing
> **Module kind:** L1 primitive | **Version:** 1.0.0
> **Module kind:** primitive | **Version:** 1.0.0
A VPC with one subnet per availability zone and a route table with a
default route through an internet gateway. The networking foundation
modules/l2/microservice/README.md
+8 -8
View File
@@ -1,16 +1,16 @@
# microservice — ECS Fargate microservice
> **Module kind:** L2 composition | **Version:** 1.0.0
> **Module kind:** module pattern | **Version:** 1.0.0
A composition that references multiple L1 primitives to deploy an ECS
A pattern that references multiple primitives to deploy an ECS
Fargate microservice end-to-end (VPC, cluster, ECR, IAM role, ALB,
ECS service).
## Resources
The composition references these L1 primitives:
The pattern references these primitives:
| L1 module | Purpose | README |
| Primitive | Purpose | README |
|-----------|---------|--------|
| `vpc` | VPC, subnets, routing | [README](../l1/vpc/README.md) |
| `ecs-cluster` | ECS Fargate cluster | [README](../l1/ecs-cluster/README.md) |
@@ -38,10 +38,10 @@ The composition references these L1 primitives:
## Usage
Define a contract referencing this composition:
Define a contract referencing this module:
```yaml
uses: acdl/pipelines/deploy.yaml@v1
uses: acdl/pipelines/deploy.yaml@v1.4
module: microservice
environment: dev
inputs:
@@ -52,7 +52,7 @@ inputs:
## Compliance extension points
The composition can wire compliance resources across L1s when the
The pattern can wire compliance resources across primitives when the
compliance milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
- **KMS key** — shared encryption key referenced by S3, ECR, CloudWatch Logs, and Secrets Manager.
@@ -61,7 +61,7 @@ compliance milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
- **Security groups** — proper network segmentation between ALB, service, and data tiers.
- **Private subnets** — ECS tasks in private subnets with NAT egress.
See each L1 module's README for per-module compliance extension points.
See each primitive's README for per-module compliance extension points.
## Versioning
modules/l2/static-asset/README.md
+9 -9
View File
@@ -1,15 +1,15 @@
# static-asset — S3 static asset
> **Module kind:** L2 composition | **Version:** 1.0.0
> **Module kind:** module pattern | **Version:** 1.0.0
A composition that references the `s3` L1 primitive to deploy a single
A pattern that references the `s3` primitive to deploy a single
S3 bucket for static asset hosting.
## Resources
The composition references this L1 primitive:
The pattern references this primitive:
| L1 module | Purpose | README |
| Primitive | Purpose | README |
|-----------|---------|--------|
| `s3` | S3 bucket | [README](../l1/s3/README.md) |
@@ -29,10 +29,10 @@ The composition references this L1 primitive:
## Usage
Define a contract referencing this composition:
Define a contract referencing this module:
```yaml
uses: acdl/pipelines/deploy.yaml@v1
uses: acdl/pipelines/deploy.yaml@v1.4
module: static-asset
environment: dev
inputs:
@@ -40,13 +40,13 @@ inputs:
region: us-east-1
```
See the [consumer guide](../../docs/CONSUMER_GUIDE.md) for a
See the [consumer guide](../../docs/consumer-guide.md) for a
step-by-step walkthrough, and the [s3 README](../l1/s3/README.md) for the
underlying L1 primitive.
underlying primitive.
## Compliance extension points
The composition can wire compliance resources when the compliance
The pattern can wire compliance resources when the compliance
milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
- **KMS key** — shared encryption key for S3 SSE.