audit(v1.8): ARCHITECTURE.md v1.8 addendum + stale branch cleanup

---ci---
project: acdl
phase: 0
milestone: v1.8
status: complete
---/ci---

Audit fixes:
- ARCHITECTURE.md: added v1.8 addendum covering new primitives (kms-key,
  uptime), encryption-by-default, deletion-protection-by-default,
  decommission alias, adapter expansion (19 TYPE_MAP entries), pipeline
  stages (9), forge-agnostic API URLs.
- Stale branches cleaned: phase/21-docs-restructure (v1.6) and
  milestone/v1.0-initial (v1.0) deleted. Pruned remote refs.
- Only main + origin/main remain.

Audit result: PASS
This commit is contained in:
Jon Chery
2026-07-22 22:42:46 +00:00
parent f9a93d56cc
commit 9409d089bd
+69 -1
View File
@@ -375,4 +375,72 @@ stream as a `terraform.apply` event.
4. Phase 14 — `l2-microservice` + contract schema extension.
5. Phase 15 — consumer repo + `terraform apply` (dev) → live ECS service.
6. Phase 16 — capstone e2e: consumer commit → live HTTP 200 → evidence → timeline.
7. COMPLETE gate — review → ship `v1.3.0` → audit.
7. COMPLETE gate — review → ship `v1.3.0` → audit.
## v1.8 Architecture Addendum
> Milestone v1.8 (complete, tag `v1.8.0`). Adds encryption-by-default,
> deletion-protection-by-default, uptime monitoring, decommission alias,
> engineering standards, and path documentation.
### New Primitives
- **`kms-key`** (`aws:kms:key`) — Per-stack customer-managed KMS key with
`enable_key_rotation = true`. One key per L2 deployment (no shared keys).
Wired into both L2 compositions as a child, with its `kms_key_arn` output
connected to all children's `kms_key_arn` input. Adapter emits
`aws_kms_key` + `enable_key_rotation`.
- **`uptime`** (`aws:ecs:uptime-service`) — Uptime-kuma on ECS Fargate with
a feature flag (`feature_flag_enabled`), monitored endpoints (HTTP/DNS/TCP),
alert channels (Teams/email/SMS/GitHub issues). Deployed by default after
any L2 module with a separate terraform state. When the feature flag is
false, the adapter emits no resources.
### Encryption by Default
All 12 L1 primitives have `encryption_enabled` NFR (default true). Primitives
with at-rest data (s3, rds, ecr, ecs-service, ecs-cluster) have an optional
`kms_key_arn` input. The adapter emits encryption blocks (SSE-KMS for S3,
storage_encrypted for RDS, encryption_configuration for ECR) referencing the
per-stack CMK when provided. Managed KMS fallback with stderr warning for
standalone L1 deployments.
### Deletion Protection by Default
All 12 L1 primitives have `deletion_protection` NFR (default true). The
adapter emits `lifecycle { prevent_destroy = true }` when true. L2 modules
expose a `features.deletion_protection` flag (default true) propagated to
all children via the resolver. Setting `inputs.deletion_protection: false`
in the contract disables it for the whole stack.
### Decommission Alias
A `mode: decommission` on the deploy pipeline implements a 2-step destroy:
1. Disable deletion protection (resolve with `deletion_protection: false`,
terraform plan/apply, HITL SRE gate via GitHub environment).
2. Zero counts + destroy (`decommission_transform` zeroes all scalable counts,
terraform plan/apply, second HITL SRE gate).
CMDB validation via DynamoDB `acdl-change-requests` table. The Lambda
`validate_change_request` action queries the table and asserts
`status == "approved"` + `consumerRepo` match.
### Adapter Expansion
TYPE_MAP grew from 16 to 19 entries (+ `aws:kms:key`, `aws:kms:alias`,
`aws:ecs:uptime-service`). Specialized emission branches added for KMS key
rotation, S3 SSE-KMS configuration, uptime ECS Fargate task, and
`prevent_destroy` lifecycle on all resources.
### Pipeline Stages
The deploy pipeline grew from 8 to 9 stages (+ `deploy-uptime` after
`publish-outputs`). The `deploy-uptime` stage constructs a synthetic uptime
contract from the L2 stack outputs, resolves + adapts it to a separate
terraform state directory, and publishes the uptime URL via PR comment.
### Forge-Agnostic API URLs
The platform Lambda (`contract_ingestor.py`) reads `GITHUB_API_BASE` env
for forge-agnostic API URLs. GitHub uses `/search/issues`; Gitea uses
`/repos/{owner}/{repo}/issues`. Detection via `/api/v1` in the base URL.