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

---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
+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
+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.